U-Boot Coding Style

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 documentation applies with no changes.

Our Python code documentation follows PEP257 (Docstring Conventions).

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

• This may need to change to the kernel model if we allow for more run-time detection of what drivers are appropriate for what we’re running on.

Please use the check_member() macro 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. In all cases, they should be listed in alphabetical order. First comes headers which are located directly in our top-level include diretory. Second are headers within subdirectories, Finally directory-local includes should be listed. See this example:

#include<bootstage.h>
#include<dm.h>
#include<others.h>
#include<asm/...>
#include<asm/arch/...>
#include<dm/device_compat.h>
#include<linux/...>
#include"local.h"

For files that need to be compiled for the host (e.g. tools), you need to use #ifndef USE_HOSTCC to avoid including U-Boot specific include files. See common/image.c for an example.

If your file uses driver model, include <dm.h> 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.

Function and struct comments

Non-trivial functions should have a comment which describes what they do. If it is an exported function, put the comment in the header file so the API is in one place. If it is a static function, put it in the C file.

If the function returns errors, mention that and list the different errors that are returned. If it is merely passing errors back from a function it calls, then you can skip that.

See here for style.

Conditional Compilation

Wherever possible, don’t use preprocessor conditionals (#if, #ifdef) in .c files; doing so makes code harder to read and logic harder to follow. Instead, use such conditionals in a header file defining functions for use in those .c files, providing no-op stub versions in the #else case, and then call those functions unconditionally from .c files. The compiler will avoid generating any code for the stub calls, producing identical results, but the logic will remain easy to follow.

Prefer to compile out entire functions, rather than portions of functions or portions of expressions. Rather than putting an ifdef in an expression, factor out part or all of the expression into a separate helper function and apply the conditional to that function.

If you have a function or variable which may potentially go unused in a particular configuration, and the compiler would warn about its definition going unused, mark the definition as __maybe_unused rather than wrapping it in a preprocessor conditional. (However, if a function or variable always goes unused, delete it.)

Within code, where possible, use the IS_ENABLED macro to convert a Kconfig symbol into a C boolean expression, and use it in a normal C conditional:

if(IS_ENABLED(CONFIG_SOMETHING)){
...
}

The compiler will constant-fold the conditional away, and include or exclude the block of code just as with an #ifdef, so this will not add any runtime overhead. However, this approach still allows the C compiler to see the code inside the block, and check it for correctness (syntax, types, symbol references, etc). Thus, you still have to use an #ifdef if the code inside the block references symbols that will not exist if the condition is not met.

When working with xPL (see Generic xPL framework for more information) we need to take further care to use the right macro. In the case where a symbol may be referenced with an xPL-specific Kconfig symbol, use the CONFIG_IS_ENABLED macro instead, in a similar manner:

if(CONIG_IS_ENABLED(SOMETHING)){
...
}

When dealing with a Kconfig symbol that has both a normal name and one or more xPL-prefixed names, the Makefile needs special consideration as well. The PHASE_ macro helps us in this situation thusly:

obj-$(CONFIG_$(PHASE_)SOMETHING)+=something.o

At the end of any non-trivial #if or #ifdef block (more than a few lines), place a comment after the #endif on the same line, noting the conditional expression used. For instance:

#ifdef CONFIG_SOMETHING
...
#endif /* CONFIG_SOMETHING */

Driver model

When declaring a device, try to use struct udevice *dev, i.e. dev as the name:

structudevice*dev;

Use ret as the return value:

structudevice*dev;
intret;
ret=uclass_first_device_err(UCLASS_ACPI_PMC,&dev);
if(ret)
returnlog_msg_ret("pmc",dev);

Consider using log_ret() or log_msg_ret() to return a value (see above).

Add a p suffix on return arguments:

intdm_pci_find_class(uintfind_class,intindex,structudevice**devp)
{
...
*devp=dev;
return0;
}

There are standard variable names that you should use in drivers:

• struct xxx_priv and priv for dev_get_priv()

• struct xxx_plat and plat for dev_get_platdata()

For example:

structsimple_bus_plat{
u32base;
u32size;
u32target;
};
/* Davinci MMC board definitions */
structdavinci_mmc_priv{
structdavinci_mmc_regs*reg_base;/* Register base address */
uintinput_clk;/* Input clock to MMC controller */
structgpio_desccd_gpio;/* Card Detect GPIO */
structgpio_descwp_gpio;/* Write Protect GPIO */
};
structrcar_gpio_priv*priv=dev_get_priv(dev);
structpl01x_serial_platdata*plat=dev_get_platdata(dev);

Other

Some minor things:

• Put a blank line before the last return in a function unless it is the only line:

structudevice*pci_get_controller(structudevice*dev)
{
while(device_is_on_pci_bus(dev))
dev=dev->parent;
returndev;
}

Tests

Please add tests when you add code. Please change or expand tests when you change code.

Run the tests with:

make check
make qcheck (skips some tests)

Python tests are in test/py/tests - see the docs in test/py for info.

Try to write your tests in C if you can. For example, tests to check a command will be much faster (10-100x or more) if they can directly call run_command() and ut_check_console_line() instead of using Python to send commands over a pipe to U-Boot.

Tests run all supported CI systems (GitLab, Azure) using scripts in the root of the U-Boot tree.