path: root/2009/linux-coding-style-iii-tw2009/linux-coding-style.mgp

%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