Copyright © 2011 Armijn Hemel & Ralf Baechle .
This work is available under the Creative Commons Attribution 3.0 Unported license.

This document describes what steps chip vendors need to take to successfully upstream their code into the mainline Linux kernel.
Why upstreaming?

Upstreaming code has various advantages: the code will be seen by more people. A "code dump" on some FTP site will be less visible than code in the mainline kernel. If code is in the mainline kernel it will be more readily accessible and usable by more people, making your chip or board more attractive to use. It will be easier for others to improve the code and keep it up to date (code in the Linux kernel is frequently reworked). 

Upstreaming your code does not mean that people will write the code for you from day 1. The biggest investment in engineering will, at least initially, still come from you. While there might be some additional costs in the short term in the form of engineering resources, upstreaming will definitely pay off in the mid to long term.

Communicating with upstream

The Linux kernel community has its own set of rules regarding various things, such as coding style, communication, and so on. Many of the leading developers in the Linux kernel community have little time, so it is best to follow these rules to make the whole process as smooth as possible. 

Managing expectations

It is likely that the first submission to a Linux kernel developer of your code will not be accepted. This could be for various reasons: the code does not follow the coding style, code quality might not be as high as is expected, and so on. Do not see this as a rejection of your code, but as a first step for successful inclusion into the mainline kernel.

Sometimes developers might react very terse, or seemingly irritated. Once again, do not see this as a rejection, but as a sign that you need to put in a little bit more effort.

Preparing and submitting your code

The rules to follow have been documented in the Linux kernel source archive at the following locations:

* Documentation/CodingStyle
* Documentation/SubmitChecklist
* Documentation/SubmittingDrivers
* Documentation/SubmittingPatches

Typically the submission process starts with cleaning up your code and formatting it to comply with the rules as outlined in the document "CodingStyle". A list of items to check for in the code is in "SubmitChecklist"; the remaining two files document the actual submission process.

Once the code has been adapted according to the coding standard, the next step is to split up the code into patches for submission. Because very large patches are harder to review it is best to keep patches reasonably small. Another benefit is that this way the patches can be reviewed independently. Some examples of what are good things to keep in one separate patch:

- fixing a bug
- fixing a spelling mistake
- a bug fix for the same bug that appears in several places in the kernel sources
- a new driver
- support for a new SOC or evaluation board

Patches should be split in such a way that when they get applied to the kernel they do not break anything, not even temporarily. This is because it makes debugging a lot harder. Debugging the Linux kernel is done using "git-bisect".  If a version of the kernel is broken, even if it is temporarily, the use of git bisect is significantly harder or even impossible.

After you have cleaned up the code, adapted it according to the right coding style and split it up into proper patches it is time to send out the patches. Support for an entire new system or SOC will touch several areas of the kernel, but it is not necessary to send all the patches to everybody on the Linux kernel mailinglist. For example, the maintainers of ARM Linux will not be very interested in MIPS specific code. The MAINTAINERS file in the kernel source tree can help you with this.

As an example, for the squashfs code you would find:

SQUASHFS FILE SYSTEM
M:      Phillip Lougher
L:      This e-mail address is being protected from spambots. You need JavaScript enabled to view it (subscribers-only)
W:      https://squashfs.org.uk
S:      Maintained
F:      Documentation/filesystems/squashfs.txt
F:      fs/squashfs/

'L' points to the mailing list for the specific subsystem. 'M' indicates the direct contact address for the maintainer or maintainers. In some cases one of these might be missing. If both are missing you should use This e-mail address is being protected from spambots. You need JavaScript enabled to view it to send patches to. 
If you follow these simple rules upstreaming your code should not be much of a problem. One important piece of advice that we want to give you: if you have questions, simply ask them. The Linux kernel developers will be more than happy to answer your questions.