|| ||Ben Collins <email@example.com>|
|| ||Linux Kernel Development <firstname.lastname@example.org>,
Linus Torvalds <email@example.com>|
|| ||[Updated]: How to become a kernel driver maintainer|
|| ||Wed, 08 Mar 2006 13:03:33 -0500|
Only small changes, title and a little rewording regarding "local
development copy". I will submit a patch if there are no more changes to
How to become a kernel driver maintainer
This document explains what you must know before becoming the maintainer
of a portion of the Linux kernel. Please read SubmittingPatches,
SubmittingDrivers and CodingStyle, also in the Documentation/ directory.
With the large amount of hardware available for Linux, it's becoming
increasingly common for drivers for new or rare hardware to be
outside of the main kernel tree. Usually these drivers end up in the
kernel tree once they are stable, but many times users and distribution
maintainers are left with collecting these external drivers in order to
support the required hardware.
The purpose of this document is to provide information for the authors
these drivers to eventually have their code in the mainline kernel tree.
Why should I submit my driver?
This is often the question a driver maintainer is faced with. Most
authors really don't see the benefit of having their code in the main
kernel. Some even see it as giving up control of their code. This is
simply not the case, and then end result is always beneficial to users
The primary benefit is availability. When people want to compile a
they want to have everything there in the kernel tree. No one (not even
kernel developers) likes having to search for, download, and build
external drivers out-of-tree (outside the stock kernel source). It's
difficult to find the right driver (one known to work correctly), and is
even harder to find one that works on the kernel version they are
The benefit to users compiling their own kernel is immense. The benefit
distributions is even greater. Linux distributions already have a large
amount of work to provide a kernel that works for most users. If a
has to be provided for users that isn't in the primary kernel source, it
adds additional work to maintaining (tracking the external driver,
patching it into the build system, often times fixing build problems).
With a driver in the kernel source, it's as simple as tracking the main
This assumes that the distribution finds your driver worth the time of
doing all this. If they don't, then the few users needing your driver
probably never get it (since most users are not capable of compiling
Another benefit of having the driver in the kernel tree is to promote
hardware that it supports. Many companies who have written drivers for
their hardware to run under Linux have not yet taken the leap to placing
the driver in the main kernel. The "Old Way" of providing downloadable
drivers doesn't work as well for Linux, since it's almost impossible to
provide pre-compiled versions for any given system. Having the driver in
the kernel tree means it will always be available. It also means that
users wishing to purchase hardware that "Just Works" with Linux will
more options. A well written and stable driver is a good reason for a
to choose that particular type of hardware.
Having drivers in the main kernel tree benefits everyone.
What should I do to prepare for code submission?
First you need to inspect your code and make sure it meets criteria for
inclusion. Read Documentation/CodingStyle for help on proper coding
(indentation, comment style, etc). It is strongly suggested that your
driver builds cleanly when checked by the "sparse" tool. You will
need to annotate the driver so sparse can tell that it is following the
kernel's rules for address space accesses and endianness. Adding these
annotations is a simple, but time-consuming, operation that often
real portability problems in drivers.
Once you have properly formatted the code, you also need to check a few
other areas. Most drivers include backward compatibility for older
(usually ifdef's with LINUX_VERSION_CODE). This backward compatibility
needs to be removed. It's considered a waste of code for the driver to
backward compatible within the kernel source tree, since it is going to
compiled with a known version of the kernel.
Proper location in the kernel source needs to be determined. Find
similar to yours, and use the same location. For example, USB network
drivers go in drivers/usb/net/, and filesystems go in fs/.
The driver should then be prepared for building from the main source
in this location. A proper Makefile and Kconfig file in the Kbuild
should be provided. Most times it is enough to just add your entries to
existing files. Here are some good rules to follow:
- If your driver is a single source file (or single .c with a
then it's typical to place the driver in an existing directory. Also,
modify existing Makefile/Kconfig for that directory.
- If your driver is made up of several source files, then it is typical
to create a subdirectory for it under the existing directory where it
applies. Separate Makefile should be included, with a reference in
parent Makefile to make sure to descend into the one you created.
+ In this case, it is usually still correct to just add the Kconfig
entry to the existing one. Unless your driver has 2 or more config
options (debug options, extra features, etc), then creating a
standalone Kconfig may be best. Make sure to source this new
from the parent directory.
- When creating the Kconfig entries be sure to keep in mind the
for the driver to be build. For example, a wireless network driver
need to "depend on NET && IEEE80211". Also, if you driver is
to a certain architecture, be sure the Kconfig entry reflects this.
NOT force your driver to a specific architecture simply because the
driver is not written portably.
Lastly, you'll need to create an entry in the MAINTAINERS file. It
reference you or the team responsible for the code being submitted (this
should be the same person/team submitting the code).
Once your patches are ready, you can submit them to the linux-kernel
mailing list. However, since most drivers fall under some subsystem
usb, etc), then it is often required that you also Cc the mailing list
this subsystem (see MAINTAINERS file for help finding the correct
The code review process is there for two reasons. First, it ensures that
only good code, that follows current API's and coding practices, gets
the kernel. The kernel developers know you have good intentions of
maintaining your driver, but too often a driver is submitted to the
kernel, and some time later becomes unmaintained. Then developers who
not familiar with the code or it's purpose are left with keeping it
compiling and working. So the code needs to be readable, and easily
Secondly, the code review helps you to make your driver better. The
looking at your code have been doing Linux kernel work for years, and
intimately familiar with all the nuances of the code. They can help with
locking issues as well as big-endian/little-endian and 64-bit
Be prepared to take some heavy criticism. It's very rare that anyone
out of this process without a scratch. Usually code review takes several
tries. You'll need to follow the suggested changes, and make these to
code, or have clear, acceptable reasons for *not* following the
suggestions. Code reviewers are generally receptive to reasoned
If you do not follow a reviewer's initial suggestions, you should add
descriptive comments to the appropriate parts of the driver, so that
future contributors can understand why things are in a possibly
state. Once you've made the changes required, resubmit. Try not to take
personally. The suggestions are meant to help you, your code, and your
users (and is often times seen as a rite of passage).
What is expected of me after my driver is accepted?
The real work of maintainership begins after your code is in the tree.
This is where some maintainers fail, and is the reason the kernel
developers are so reluctant to allow new drivers into the main tree.
There are two aspects of maintaining your driver in the kernel tree. The
obvious first duty is to keep your code synced to the kernel source.
means submitting regular patch updates to the linux-kernel mailing list
and to the particular tree maintainer (e.g. Linus or Andrew). Now that
your code is included and properly styled and coded (with that shiny new
driver smell), it should be fairly easy to keep it that way.
The other side of the coin is keeping changes in the kernel synced to
code. Often times, it is necessary to change a kernel API (driver model,
USB stack changes, networking subsystem change, etc). These sorts of
changes usually affect a large number of drivers. It is not feasible for
these changes to be individually submitted to the driver maintainers. So
instead, the changes are made together in the kernel tree. If your
is affected, you are expected to pick up these changes and merge them
your temporary development copy. Usually this job is made easier if you
use the same source control system that the kernel maintainers use
(currently, git), but this is not required. Using git, however, allows
to merge more easily.
There are times where changes to your driver may happen that are not the
API type of changes described above. A user of your driver may submit a
patch directly to Linus to fix an obvious bug in the code. Sometimes
trivial and obvious patches will be accepted without feedback from the
driver maintainer. Don't take this personally. We're all in this
Just pick up the change and keep in sync with it. If you think the
was incorrect, try to find the mailing list thread or log comments
regarding the change to see what was going on. Then email the patch
about the change to start discussion.
How should I maintain my code after it's in the kernel tree?
The suggested, and certainly the easiest method, is to start a git tree
cloned from the primary kernel tree. In this way, you are able to
automatically track the kernel changes by pulling from Linus' tree. You
can read more about maintaining a kernel git tree at
Whatever you decide to use for keeping your kernel tree, just remember
that the kernel tree source is the primary code. Your repository should
mainly be used for queuing patches, and doing development. Users should
not have to regularly go to your source in order to get a stable and
Ubuntu - http://www.ubuntu.com/
Debian - http://www.debian.org/
Linux 1394 - http://www.linux1394.org/
SwissDisk - http://www.swissdisk.com/