summaryrefslogtreecommitdiff
path: root/2009/linux-coding-style-kr2009/linux-coding-style.mgp
diff options
context:
space:
mode:
Diffstat (limited to '2009/linux-coding-style-kr2009/linux-coding-style.mgp')
-rw-r--r--2009/linux-coding-style-kr2009/linux-coding-style.mgp410
1 files changed, 410 insertions, 0 deletions
diff --git a/2009/linux-coding-style-kr2009/linux-coding-style.mgp b/2009/linux-coding-style-kr2009/linux-coding-style.mgp
new file mode 100644
index 0000000..96a1b8f
--- /dev/null
+++ b/2009/linux-coding-style-kr2009/linux-coding-style.mgp
@@ -0,0 +1,410 @@
+%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 Samsung understand Linux and Open Source!
+
+ hwelte@hmw-consulting.de
+
+%center
+Thanks for your Attention
personal git repositories of Harald Welte. Your mileage may vary