KernelPatches

Typical Patch Life Cycle

This outlines the typical steps a patch should go through before it's included into the Ubuntu kernel.

  1. Patch is created and thoroughly tested.

  2. File a bug in Launchpad documenting the issue and what the patch does to resolve that issue.

  3. Attach the patch to the Launchpad bug. Be sure to tick the "This attachment is a patch" checkbox when attaching.

  4. Once the patch is ready, submit it upstream. See the the Submitting a Patch Upstream section below.

    • The patch will typically undergo a review by the upstream kernel developers and may receive additional comments on how to improve the patch. Be sure to make the suggested improvements and resubmit until it's finally accepted.
    • At this point, it's also a good idea to add a reference in the Launchpad bug to the thread of the patch posted upstream.
  5. Patch accepted upstream.
  6. Once upstream, the patch will automatically land in the Ubuntu kernel.

If you need assistance with any of these steps, please refer to the help section below.

Submitting a Patch Upstream

If a patch will benefit the entire kernel community as a whole it should go upstream first. Once the patch is integrated upstream, the patch will automatically trickle down into the Ubuntu kernel. If a patch has not been submitted upstream it's less likely to be applied to the Ubuntu kernel. So how does one go about submitting a patch to the upstream kernel?

  1. First, read the upstream patch submission documentation. Do not just skim or browse this. It's rude to waste an upstream developers time by not knowing how to properly submit a patch, especially when the patch submission process has been fully documented. The upstream developers take patches and contributions seriously, so please return the favor by submitting a patch properly.

  2. Look at the https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/MAINTAINERS file to know where to send the patch. You can also use scripts/get_maintainer.pl in your kernel tree to get the same information.

  3. Be sure to create the patch against the upstream kernel source, not the Ubuntu kernel source.
  4. Make sure to maintain full provenance of the patch by signing off on it (i.e. add your Signed-off-by:)

  5. To have the patch automatically included in the stable tree, add the tag Cc: stable@vger.kernel.org in the sign-off area (not in the email's CC!). Once the patch is merged it will be applied to the stable tree, and will in turn trickle down to Ubuntu kernel. Read https://www.kernel.org/doc/html/latest/process/stable-kernel-rules.html for more details of this tag.

Example of Submitting a Patch Upstream

Bug 323592 - reboot freeze of Dell XPS 710

This particular bug was fixed by creating a patch to add a reboot quirk for this particular system. This patch would be beneficial not only for Ubuntu users but all users who had this hardware. As such, this patch was submitted upstream as follows:

  1. The patch was first thoroughly tested and confirmed to fix the issue.

  2. The submitter carefully read the upstream patch submission documentation and noted some key elements to keep in mind:

    • the patch needed to have a well written description
    • the patch followed the upstream kernel coding style
    • the patch would be submitted as inline text in an email (ie. no attachments, no links, etc.)
    • patch was generated against the latest kernel available
    • "[PATCH]" was included in the subject of the email
    • patch was signed off

  3. The submitter examined the https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/MAINTAINERS file to see who and where to submit the patch to: 

    • X86 ARCHITECTURE (32-BIT AND 64-BIT)
P:      Thomas Gleixner
M:      tglx@linutronix.de
P:      Ingo Molnar
M:      mingo@redhat.com
P:      H. Peter Anvin
M:      hpa@zytor.com
M:      x86@kernel.org
T:      git git://git.kernel.org/pub/scm/linux/kernel/git/x86/linux-2.6-x86.git
S:      Maintained
F:      Documentation/x86/
F:      arch/x86/

  4. After examining the https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/MAINTAINERS file it was noted that this particular subsystem had it's own git tree. The patch was quickly rebased against the linux-2.6-x86.git tree.

  5. The email was then crafted and was sent to the maintainers (Thomas Gleixner, Ingo Molnar, H. Peter Anvin), the x86 kernel mailing list, and LKML.
  6. The patch was accepted and merged upstream

Additional Examples

https://bugs.launchpad.net/ubuntu/+source/linux/+bug/371574

Submitting a Patch to the Ubuntu Kernel

The majority of patches should go upstream first before the Ubuntu kernel team will consider applying them to the Ubuntu kernel. Refer to the Submitting a Patch Upstream section above. Once a patch has been submitted and accepted upstream it will automatically find it's way into the Ubuntu kernel. If the upstream patch is something that should be cherry-picked/backported as soon as possible into the Ubuntu kernel tree, please do the following:

  1. File a bug in Launchpad and be sure to reference the upstream SHA1 git id that the Ubuntu kernel team should cherry-pick.

  2. Send the patch to the Kernel Team mailing list following these procedures.

There are exceptions that are sometimes made. If a patch is for example a Critical bug fix, the Ubuntu kernel team may opt to temporarily carry the patch while it's going through the upstream submission process. Patches must still adhere to the following:

  1. A bug should also be filed in Launchpad for tracking purposes.
  2. The patch should have full provenance (including your Signed-off-by:), i.e., who wrote the patch, where it came from, and a descriptive commit log message.

  3. These types of patches can be submitted to the Ubuntu kernel team mailing list also following the stable patch format

    • A pull request from a publicly available git repository, e.g., attach the output of 'git request-pull'. This is the preferred method for large or numerous patches.

    • From your local git repository run the command 'git format-patch -1 <SHA1>' and email the resulting file. Beware of tab mangling. Use an email attachment if necessary.

  4. The email to the Ubuntu kernel team mailing list should reference the upstream thread where discussion is taking place regarding the patch as well as the Launchpad bug #.

Finally, there do exist scenarios where a patch is Ubuntu specific. For example, Bug 393517. If this is the case, file a bug in Launchpad. Then send an email to the Ubuntu kernel team mailing list following the stable patch format.

Reasons Why the Ubuntu Kernel Team Won't Take a Patch

  • "If it ain't good enough for Linus it ain't good enough for us." That's not 100% true, but the basic idea is that if the patch is not in upstream, that generally means they aren't stable. Ubuntu's kernel is not a testing ground for developing features.
  • Just because the patch is tested by you and solved the problem on your one model of hardware, doesn't mean that it doesn't break the kernel for any of the many other models supported by the same driver. This is a particular concern for audio and video drivers. It is critical for patches to have upstream maintainer review and wider testing.
  • Maintaining a patch in our tree is not easy. Let's say we include v0.54 of some patch. Later, we want to sync up to the latest version of this patch. It's not easy to simply revert v0.54, because merges could have changed some of the code. Not to mention, there are very few patches like this that provide incremental changes between versions.
  • Patching stock code means we can't get upstream kernel maintainers to help us much anymore. If our users experience bugs, we'll have to get them to try a stock kernel before being able to push the bug to upstream.
  • Patching stock code means we have to worry about merges between the patch and code it touches. This can happen while we are following upstream development of the kernel, or when doing security patches for released kernels.
  • Patching stock code opens up to unforeseen security issues. The patch you are asking to include could contain potential security problems, which we would likely never hear about, since the code isn't part of the stock kernel.
  • Patching stock code could introduce bugs that even users who aren't getting the features of the patch would see (Xen is a good example of this). Adding bugs is bad.
  • The patch is not against a new enough kernel. For example, at the time of writing this, Xen was still only stable against 2.6.16, but the kernel we are working on is 2.6.20-pre. The 2.6.20 kernel line broke even our third-party drivers.
  • Confusion. This applies to patches that people want compiled as a separate kernel flavour. While we've done this for other features, it is not always good to have so many types of kernels available. Not to mention we'll also have people wanting flavour foo compiled with flavour bar, to provide a foo-bar kernel. We don't want to make a habit of this.
  • A very uncommon reason, but just as important, is that the patch is just crap or serves no real purpose. Don't be offended.
  • And the most important reason is, we just don't have time. Think if we included everyone's pet patch, and had to maintain them all. We'd be so swamped, we couldn't keep Ubuntu the great stable Linux OS it is now.

The Patch Wasn't Accepted, Now What?

There's usually a good reason why a patch wasn't accepted and it's usually explained in a reply. If there are suggestions for improvements that need to be done to the patch before it'll be accepted, make those improvements and re-submit. Most patches go through this type of review process and will need to be modified and re-submitted a few times before they are accepted. Don't give up.

There are some patches that don't make it upstream or into the Ubuntu kernel. Some people seem to be able, and God help them, willing to maintain a kernel package outside of Ubuntu's main repository. This is great if someone is willing to do this but it's not recommended. If someone opts for this route, things usually happen in stages. Most custom kernels never make it past the first stage.

  1. People create custom kernels built against the Ubuntu source and provide it publicly somewhere. They take on all the responsibility of keeping it current.
  2. If the package is used enough, sometimes it can make it into Universe, and made available to a wider audience. The patch would build depend on the Ubuntu kernel source, and easily stay in sync with updates to it. It would also be built on all available architectures. For this to happen, takes a greater degree of commitment from the person maintaining this package.
  3. Hopefully, some time after this stage the patch will be reconsidered for inclusion in upstream kernel. If not, then there's probably very little chance it would be included in the main Ubuntu kernel, but things can happen.

Colin: 1 & 2 would be much easier if building linux-restricted-modules against non-standard flavours were supported. I submitted some changes in a bug report but I don't think it has been looked at; wouldn't something similar go a long way towards facilitating kernel customization? --MattPrice

Getting Help

If you need assistance or have any questions regarding a patch, need a patch to be reviewed, or need help getting the patch submitted upstream, the Ubuntu kernel team would be happy to help. Please contact them either through the Ubuntu kernel team mailing list <kernel-team@lists.ubuntu.com> or join the #ubuntu-kernel channel on the Libera Chat (irc.libera.chat) server.

CategoryKernel

Kernel/Dev/KernelPatches (last edited 2024-01-26 14:18:34 by kleber-souza)