U-Boot Coding Style

The following Coding Style requirements shall be mandatory for all code contributed to the U-Boot project.

Exceptions are only allowed if code from other projects is integrated with no or only minimal changes.

The following rules apply:

• All contributions to U-Boot should conform to the Linux kernel coding style; see the file "Documentation/CodingStyle" and the script "scripts/Lindent" in your Linux kernel source directory.
  • The exception for net files to the multi-line comment in "Documentation/CodingStyle : 556" applies only to Linux, not to U-Boot. Only large hunks which are copied unchanged from Linux may retain that comment format.
• Use patman to send your patches ('tools/patman/patman -H' for full instructions). With a few tags in your commits this will check your patches and take care of emailing them.
• If you don't use patman, make sure to run the checkpatch.pl script from the Linux source tree to check your patches. See also Patches for more comments on this tool. Note that this should be done before posting on the mailing list!
• Source files originating from different projects (for example the MTD subsystem or the hush shell code from the BusyBox project) may, after careful consideration, be exempted from these rules. For such files, the original coding style may be kept to ease subsequent migration to newer versions of those sources.
• Please note that U-Boot is implemented in C (and to some small parts in Assembler); no C++ is used, so please do not use C++ style comments (//) in your code.
  • The sole exception here is for SPDX tags in some files (checkpatch.pl will warn you).
• Please also stick to the following formatting rules:
  • Remove any trailing white space
  • Use TAB characters for indentation and vertical alignment, not spaces
  • Make sure NOT to use DOS '\r\n' line feeds
  • Do not add more than 2 consecutive empty lines to source files
  • Do not add trailing empty lines to source files
  • Using the option git config --global color.diff auto will help to visually see whitespace problems in diff output from git.
  • In Emacs one can use M-x whitespace-global-mode to get visual feedback on the nasty details. M-x whitespace-cleanup does The Right Thing (tm)

Submissions of new code or patches that do not conform to these requirements shall be rejected with a request to reformat the changes.

U-Boot Code Documentation

U-Boot adopted the kernel-doc annotation style, this is the only exception from multi-line comment rule of Coding Style. While not mandatory, adding documentation is strongly advised. The Linux kernel kernel-doc document applies with no changes.

Use structures for I/O access

U-Boot typically uses a C structure to map out the registers in an I/O region, rather than offsets. The reasons for this are:

• It dissociates the register location (offset) from the register type, which means the developer has to make sure the type is right for each access, whereas with the struct method, this is checked by the compiler;

• It avoids actually writing all offsets, which is (more) error- prone;

• It allows for better compile time sanity-checking of values we write to registers.

Some reasons why you might not use C structures:

• Where the registers appear at different offsets in different hardware revisions supported by the same driver
• Where the driver only uses a small subset of registers and it is not worth defining a struct to cover them all, with large empty regions
• Where the offset of a register might be hard to figure out when buried a long way down a structure, possibly with embedded sub-structures

Please use check_member() to verify that your structure is the expected size, or that particular members appear at the right offset.

Include files

You should follow this ordering in U-Boot:

   <common.h>
   <others.h>
   <asm/...>
   <arch/arm/...>
   <linux/...>
   "local.h"

Within that order, sort your includes.

It is important to include common.h first since it provides basic features used by most files, e.g. CONFIG options.

For files that need to be compiled for the host (e.g. tools), you need to use '#ifndef USE_HOSTCC' to avoid including common.h since it includes a lot of internal U-Boot things. See common/image.c for an example.

If your file uses driver model, include in the C file. Do not include dm.h in a header file. Try to use forward declarations (e.g. 'struct udevice') instead.

Filenames

For .c and .h files try to use underscore rather than hyphen unless you want the file to stand out (e.g. driver-model uclasses should be named xxx-uclass.h. Avoid upper case and keep the names fairly short.