Upstreaming your Code - A Primer

Written by Armijn Hemel & Ralf Baechle 林誠夏/翻譯

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 an 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 for others. It will also 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 seem irritated. Once again, do not view this as a rejection, but as a sign that you need to put in a bit more effort.


Preparing and submitting your code

The rules to follow have been documented in the Linux kernel source archive in 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 a 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 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 mailing list. 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:      squash fs-devel@lists.sourceforge.net
W:      http://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 linux-kernel@vger.kernel.org.

If you follow these simple rules, upstreaming your code should not be a problem. One important piece of advice that we want to give: if you have questions, ask them. The Linux kernel developers will answer your questions.

WorkingGroups/KernelArchived/UpstreamTips2 (last modified 2013-01-14 19:31:35)