411 lines
13 KiB
Plaintext
411 lines
13 KiB
Plaintext
%include "default.mgp"
|
|
%default 1 bgrad
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
%nodefault
|
|
%back "blue"
|
|
|
|
|
|
%center
|
|
%size 5
|
|
Introduction to the
|
|
Linux Coding Style
|
|
and
|
|
Submitting Patches Mainline
|
|
|
|
%center
|
|
%size 4
|
|
by
|
|
|
|
Harald Welte <hwelte@hmw-consulting.de>
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Introduction
|
|
|
|
Who is speaking to you?
|
|
an independent Free Software developer, consultant and trainer
|
|
14 years experience using/deploying and developing for Linux on server and workstation
|
|
10 years professional experience doing Linux system + kernel level development
|
|
strong focus on network security and embedded
|
|
expert in Free and Open Source Software (FOSS) copyright and licensing
|
|
digital board-level hardware design, esp. embedded systems
|
|
active developer and contributor to many FOSS projects
|
|
thus, a techie, who will therefore not have fancy animated slides ;)
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Code Architecture / Style
|
|
|
|
|
|
What is coding style ?
|
|
It is not just about cosmetics / code format and layout
|
|
It is a fundamental skill of sustainable software engineering
|
|
It is about writing readable, not just executable code
|
|
It is about clearly expressing your thoughts and ideas
|
|
It is about good software architecture
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Code Architecture
|
|
|
|
|
|
Why does good code architecture matter ?
|
|
Because Linux runs on 25 CPU architectures
|
|
Because Linux runs on systems with 1 or 512 CPU cores
|
|
Because Linux is a reliable operating system kernel
|
|
Because Linux will support your hardware even after the hardware vendor doesn't
|
|
becuase the company is gone
|
|
because the company has lost business interest
|
|
because the original developers are gone
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Code Architecture
|
|
|
|
|
|
Linux kernel API's change
|
|
the kernel constantly gets improved
|
|
the kernel constantly adapts to changes in e.g. hardware
|
|
|
|
Use latest kernel API's
|
|
very often there are old and new API's in parallel
|
|
old API's are only to be used by legacy drivrers until they have been converted to the new API's
|
|
new drivers using old API's will not get merged
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Code Architecture
|
|
|
|
|
|
Code reuse
|
|
makes software maintainable
|
|
makes software vendor-independent
|
|
increases performance (efficient memory+cache use)
|
|
so please, reuse existing code
|
|
decreases overall R&D effort
|
|
example
|
|
Linux provides one 802.11 stack for all wifi cards
|
|
Linux provides one Bluetooth stack for all bluetoth HCI
|
|
Vendor drivers only implement minimal hardware glue
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Code Architecture
|
|
|
|
|
|
Code Structure
|
|
helps code to be readable
|
|
helps code to be maintainable
|
|
means
|
|
functions of reasonable length
|
|
no spaghetti code
|
|
functions with clearly-defined purpose
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Code Architecture
|
|
|
|
|
|
Code Portability
|
|
Linux runs on 25 CPU architectures
|
|
some 32bit/64bit
|
|
some cache-coherent, some not
|
|
some with CPU == IO address space, some not
|
|
some little, some big endian
|
|
with different alignment requirements
|
|
with or without SMP
|
|
|
|
So please never, ever assume you only care about IA32.
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Coding Style
|
|
|
|
|
|
Coding style in a narrow sense
|
|
is how the code actually looks like
|
|
/usr/src/linux/Documentation/CodingStyle
|
|
|
|
|
|
Why do "cosmetics" matter
|
|
you write code to be read by other developers
|
|
anyone who reads one part of the kernel should be able to read all parts
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Coding Style
|
|
|
|
|
|
Indentation
|
|
No multiple statements on one line
|
|
Break long lines to fit 80character terminal width
|
|
Opening/closing braces on same line, except functions
|
|
No unneccessary braces
|
|
Space after keyword, but not after function
|
|
No space inside parenthesis
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Coding Style
|
|
|
|
|
|
Centralized exitting of functions
|
|
goto helps
|
|
C89 style comments
|
|
/* */ instead of //
|
|
careful with inlining
|
|
excessive inlining wastes cache
|
|
function return values
|
|
standard case: 0 in success, -ERRNO on error
|
|
volatile is almost always wrong
|
|
see Documentation/volatile-considered-harmful.txt
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Coding Style
|
|
|
|
|
|
Naming
|
|
DontUseSturdyCapsLikeInWindows
|
|
keep local variables short
|
|
global symbols with prefix and underscore
|
|
like s3cfb_do_something()
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
The Linux Coding Style
|
|
Coding Style
|
|
|
|
|
|
Now, let's look at some actual code!
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
Why does revision control matter
|
|
|
|
because revision control preserves development timeline
|
|
this timeline can be used to
|
|
discover which change caused a regression
|
|
understand why the code was changed when and where
|
|
understand who wrote which part of the code
|
|
keep a clear track of who has copyright on which part
|
|
It is important to keep revision control system clean
|
|
never commit two unrelated changes as one changeset
|
|
never commit without meaningful description/changelog
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
Classic Revision control systems
|
|
|
|
RCS (Revison Control System)
|
|
per-file revision control
|
|
used in the 'old days', no network support
|
|
sometimes still used by sysadmins for local config files
|
|
CVS (Concurrent Versioning System)
|
|
network-enabled version of RCS
|
|
supports checkin/commit of entire trees of files (not atomic)
|
|
revisions are kept per-file
|
|
SVN (Subversion)
|
|
revisions are for the entire tree!
|
|
much faster/better/modern, WebDAV based
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
Distributed Revision control systems
|
|
|
|
git
|
|
specifically developed by Linux kernel develoeprs for kernel development
|
|
quite new, but very popular in the Linux world
|
|
based very simple primitives with toolkit on top
|
|
suports local and remote branches
|
|
keeps track of author and committer name/email
|
|
mercurial/hg
|
|
bazaar/bzr
|
|
monotone/mtn
|
|
other systems, not discussed here
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
Working with diff
|
|
|
|
the 'diff' program describes changes between two text files
|
|
most commonly, the 'unified diff' (diff -u) is used
|
|
the output is human-readable, all developers can read it
|
|
recursive operation for entire trees (diff -r)
|
|
optionally ignore whitespace changes (diff -w)
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
Working with Changesets
|
|
|
|
What is a Changeset?
|
|
A changeset is a specific logical change to software source code
|
|
A changeset is usually a patch (unified diff) plus decscription
|
|
A chronologic timeline of changesets is what your revision control system keeps
|
|
Please always specify against which base version you made your changeset.
|
|
|
|
Most of the time patch == changeset == diff
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
Contributing to FOSS projecst
|
|
|
|
|
|
We never send entire versions of our program around
|
|
We always use changesets (unified diff plus description)
|
|
Distributed development works by sending around changesets by e-mail
|
|
Mailinglists play important role so everyone can keep up-to-date with other people's changest
|
|
The project/subsystem maintainer picks changesets from e-mail and applies them to his tree
|
|
Sometimes, maintainer can 'pull' changes from contributors' tree into hist tree
|
|
The project/subsystem maintainer sends 'pull request' to higher maintainer
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
Lifecycle of a patch
|
|
|
|
Lifecycle of a netfilter/iptables patch
|
|
Developer sends patch+description to netfilter-devel list
|
|
Other developers see it and may discuss it
|
|
After some review, a new version is sent to the list
|
|
The netfilter maintainer applies the patch to his tree (netfilter.git)
|
|
At some point, the maintainer sends pull-request to network maintainer
|
|
Network-maintainer pulls the changes into his tree (net-2.6.git)
|
|
At some point, the network maintainer sends pull-request to Linus
|
|
Linus pulls those changes during the next merge window into linux-2.6.git
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
General Rules
|
|
|
|
make sure your code is compliant with Documentation/CodingStyle
|
|
make sure your code is written against the lastest mainline git tree
|
|
sometimes, development against a specific subsystem git tree
|
|
make sure your code passes the 'checkpatch.pl' script without errors
|
|
sometimes, warnings are acceptable. errors are never acceptable
|
|
make sure you have read Documentation/SubmittingPatches
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
Don't do this
|
|
|
|
Don't do this
|
|
reimplement code that already exist in the kernel (e.g. crc32)
|
|
include a protocol stack in your driver
|
|
protocol stacks (SD/MMC, 802.11, bluetooth) are vendor/device independent shared code
|
|
submit an OS independent driver with glue layer for Linux API's
|
|
submit drivers with support for older kernel API's (LINUX_VERSION_CODE)
|
|
submit drivers that include firmware in some header file
|
|
rather, use request_firmware() API to load firmware from filesystem
|
|
submit one driver for two completely different chips
|
|
submit two drivers for two chips that are 90% identical
|
|
submit drivers that don't work with latest linux-2.6.git
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
What's Signed-off-by ?
|
|
|
|
The 'developer certificate of origin'
|
|
If you add that line, you certify that you have
|
|
written the code yourself
|
|
and/or have permission to release it under GPLv2
|
|
The idea is to keep track of who has written code
|
|
Maintainers usually add their signature, too
|
|
See Documentation/SubmittingPatches
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
To which list should I send
|
|
|
|
check the linux-2.6/MAINTAINERS file for 'L:' columns
|
|
or search on the project/subsytem homepagepage
|
|
if no specific list is found, use linux-kernel (lkml)
|
|
for 'merge request' patches, Cc the maintainer
|
|
search for 'M:
|
|
some list restrict posting to list subscribers, so you first need to subscribe
|
|
usually there is a web-based interface for subscription
|
|
sometimes you have to use e-mail based method
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
I sent the patch, what next?
|
|
|
|
in the worst case, you get no feedback
|
|
if there's no feedback for one week, re-post and/or
|
|
send private mail to maintainer pointing out no feedback
|
|
in the 'best' case your code gets merged immediately
|
|
you usually receive e-mail from the maintainer about it
|
|
in the regular case, you get some feedback / change requests
|
|
try to answer to all questions as fast as possible
|
|
try to accomodate change requests as fast as possible
|
|
re-submit after integrating all change requests
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
My patch got merged, what next?
|
|
|
|
if you wrote an entire driver and merged it
|
|
you 'own' the code, i.e. you should maintain it
|
|
you should send bug fixes and updates, one-by-one, as patches
|
|
don't wait for some "official release" !!!
|
|
it is your responsibility to make sure the code in mainline is synchronized
|
|
you will get Cc'ed by other people who want to change your driver
|
|
i.e. if some API change affects your driver
|
|
i.e. if somebody discovers a bug in your driver
|
|
you should verify the new code works and provide feedback
|
|
always keep the mailinglist in Cc
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
How to use git
|
|
|
|
please see the practical demonstration
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%page
|
|
Linux mainline contribution
|
|
Thanks
|
|
|
|
|
|
Please share your questions and doubts now!
|
|
|
|
Please contact me at any later point, if you have questions
|
|
|
|
I'm here to help understand Linux and Open Source!
|
|
|
|
hwelte@hmw-consulting.de
|
|
|
|
%center
|
|
Thanks for your Attention
|