Skip to main content.

Patches and Feature Requests

Before you begin to implement any new ideas or concepts it is always a good idea to present your plans on the u-boot mailing list. U-Boot supports a huge amount of very different systems, and it is often impossible for the individual developer to oversee the consequences of a specific change to all architectures. Discussing concepts early can help you to avoid spending effort on code which, when submitted as a patch, might be rejected and/or will need lots of rework because it does not fit for some reason. Early peer review is an important resource - use it.

A good introduction how to prepare for submitting patches can be found in the LWN article How to Get Your Change Into the Linux Kernel - the same rules apply to U-Boot, too:

Patman

U-Boot has a useful tool called patman which can check and prepare patches directly from a git branch. You add a few tags into the commits to tell patman what to do. See the README or type ./tools/patman/patman -H for more information.

General Patch Submission Rules

Attributing Code, Copyrights, Signing

Commit message conventions

Please adhere to the following conventions when writing your commit log messages:

Sending updated patch versions

It is pretty normal that the first version of a patch you are submitting does not get accepted as is, and that you are asked to submit another, improved version.

When re-posting such a new version of your patch(es), please always make sure to observe the following rules: 

From: Joe Hacker 
Date: Thu, 1 Jan 2222 12:21:22 +0200
Subject: [PATCH 1/2 v3] FOO: add timewarp-support

This patch adds timewarp-support for the FOO family of processors.

adapted for the current kernel structures.

Signed-off-by: Joe Hacker <jh@hackers.paradise.com>
Cc: Tom Maintainer <tm@u-boot.custodians.org>
---
Changes for v2:
   - Coding Style cleanup
   - fixed miscalculation of time-space discontinuities
Changes for v3:
   - fixed compiler warnings observed with GCC-17.3.5
   - worked around integer overflow in warp driver

 arch/foo/cpu/spacetime.c                      |    8 +
 drivers/warp/Kconfig                          |    7 +
 drivers/warp/Makefile                         |   42 +++
 drivers/warp/warp-core.c                      |  255 +++++++++++++++++++++++++
...

Uncommented and un-threaded repostings are extremely annoying and time-consuming, as we have to try to remember if anything similar has been posted before, look up the old threads, and then manually compare if anything has been changed, or what.

If you have problems with your e-mail client, for example because it mangles white space or wraps long lines, then please read this article about Email Clients and Patches .

Notes

  1. U-Boot is Free Software that can redistributed and/or modified under the terms of the GNU General Public License (GPL). Currently (July 2009) version 2 of the GPL applies. Please see Licensing for details.
    To allow that later versions of U-Boot may be released under a later version of the GPL, all new code that gets added to U-Boot shall use a "GPL-2.0+" SPDX-License-Identifier.
  2. All code must follow the U-Boot Coding Style requirements.
  3. Before sending the patch, you must run the MAKEALL script on your patched source tree and make sure that no errors or warnings are reported for any of the boards. Well, at least not any more warnings than without your patch.

    It is strongly recommended to verify that out-of-tree building (with "-O" make option resp. "BUILD_DIR" environment variable) is still working. For example, run: 
    $ BUILD_DIR=/tmp/u-boot-build ./MAKEALL


    Please also run MAKEALL for at least one other architecture than the one you made your modifications in.
  4. If you modify existing code, make sure that your new code does not add to the memory footprint of the code. Remember: Small is beautiful! When adding new features, these should compile conditionally only (using the configuration system resp. #ifdef), and the resulting code with the new feature disabled must not need more memory than the old code without your modification.

Patch Tracking

Like some other project U-Boot uses Patchwork to track the state of patches. This is one of the reasons why it is mandatory to submit all patches to the U-Boot mailing list - only then they will be picked up by patchwork.

At http://patchwork.ozlabs.org/project/uboot/list/ you can find the list of open U-Boot patches. By using the "Filters" link (Note: requires JavaScript) you can also select other views, for example, to include old patches that have, for example, already been applied or rejected.

As a Custodian you have additional privileges: you can

Patchwork work-flow

At the moment we are in the process of defining our work-flow with Patchwork, so I try to summarize what the states and state changes mean; most of this information is based on this mail thread.
New:
Patch has been submitted to the list, and none of the maintainers has changed it's state since. Under Review::
Accepted:
When a patch has been applied to a custodian repository that gets used for pulling from into upstream, they are put into "accepted" state.
Rejected:
Rejected means we just don't want to do what the patch does.
RFC:
The patch is not intended to be applied to any of the mainline repositories, but merely for discussing or testing some idea or new feature.
Not Applicable:
The patch does not apply cleanly against the current U-Boot repository, most probably because it was made against a much older version of U-Boot, or because the submitter's mailer mangled it (for example by converting TABs into SPACEs, or by breaking long lines).
Changes Requested:
The patch looks mostly OK, but requires some rework before it will be accepted for mainline. Awaiting Upstream::
Superseeded:
Patches are marked as 'superseeded' when the poster submits a new version of these patches.
Deferred:
Deferred usually means the patch depends on something else that isn't upstream, such as patches that only apply against some specific other repository.
Archived:
Archiving puts the patch away somewhere where it doesn't appear in the normal pages and needs extra effort to get to.

We also can put patches in a "bundle". I don't know yet if that has any deeper sense but to mark them to be handled together, like a patch series that logically belongs together.

Apply patches

To apply a patch from the patchwork queue using git, download the mbox file and apply it using 
$ git am <file
The openembedded wiki also provides a script pw-am.sh which can be used to fetch an 'mbox' patch from patchwork and git am it 
usage: pw-am.sh <number>
example: 'pw-am.sh 71002' will get and apply the patch from http://patchwork.ozlabs.org/patch/71002/

Update the state of patches

You have to register to be able to update the state of patches. You can use the Web interface, `pwclient`, or `pwparser`.

pwclient

The `pwclient` command line tool can be used for example to retrieve patches, search the queue or update the state.

All necessary information for `pwclient` is linked from the bottom of http://patchwork.ozlabs.org/project/uboot/

Use 

$ pwclient help
for an overview on how to use it.

pwparser

See http://www.mail-archive.com/patchwork@lists.ozlabs.org/msg00057.html

Review Process, Git Tags

There are a number of git tags that are used to document the origin and the processing of patches on their way into the mainline U-Boot code. The following is an attempt to document how these are usually handled in the U-Boot project. In general, we try to follow the established procedures from other projects, especially the Linux kernel, but there may be smaller differences. For reference, see the Linux kernel's SubmittingPatches document.

Signed-off-by:
the Signed-off-by: is a line at the end of the commit message by which the signer certifies that he was involved in the development of the patch and that he accepts the Developer's Certificate of Origin (see SubmittingPatches).

In U-Boot, we typically do not add a Signed-off-by: if we just pass on a patch without any changes.
Reviewed-by:
The patch has been reviewed and found acceptible according to the Reviewer's Statement ( as found in the SubmittingPatches file. A Reviewed-by: tag is a statement of opinion that the patch is an appropriate modification of the code without any remaining serious technical issues. Any interested reviewer (who has done the work) can offer a Reviewed-by: tag for a patch.
Acked-by:
If a person was not directly involved in the preparation or handling of a patch but wishes to signify and record their approval of it then they can arrange to have an Acked-by: line added to the patch's changelog.
Tested-by:
A Tested-by: tag indicates that the patch has been successfully tested (in some environment) by the person named. Andrew Morton: "I think it's very useful information to have. For a start, it tells you who has the hardware and knows how to build a kernel. So if you're making a change to a driver and want it tested, you can troll the file's changelog looking for people who might be able to help."
Reported-by:
If this patch fixes a problem reported by somebody else, consider adding a Reported-by: tag to credit the reporter for their contribution. Please note that this tag should not be added without the reporter's permission, especially if the problem was not reported in a public forum.
Cc:
If a person should have the opportunity to comment on a patch, you may optionally add a Cc: tag to the patch. Git tools (git send-email) will then automatically arrange that he receives a copy of the patch when you submit it to the mainling list. This is the only tag which might be added without an explicit action by the person it names. This tag documents that potentially interested parties have been included in the discussion.

For example, when your change affects a specific board or driver, then makes a lot of sense to put the respective maintainer of this code on Cc:

Note that Patchwork automatically tracks and collects such git tags from follow-up mails, so it is usually better to apply a patch through the Patchwork commandline interface than just manually applying it from a posting on the mailing list (in which case you have to do all the tracking and adding of git tags yourself).