1.. SPDX-License-Identifier: GPL-2.0+:
2
3U-Boot Coding Style
4===================
5
6The following Coding Style requirements shall be mandatory for all code contributed to
7the U-Boot project.
8
9Exceptions are only allowed if code from other projects is integrated with no
10or only minimal changes.
11
12The following rules apply:
13
14* All contributions to U-Boot should conform to the `Linux kernel
15  coding style <https://www.kernel.org/doc/html/latest/process/coding-style.html>`_
16  and the `Lindent script <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/Lindent>`_.
17  * The exception for net files to the `multi-line comment
18  <https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting>`_
19  applies only to Linux, not to U-Boot. Only large hunks which are copied
20  unchanged from Linux may retain that comment format.
21
22* Python code shall conform to `PEP8 (Style Guide for Python Code)
23  <https://peps.python.org/pep-0008/>`_. Use `pylint
24  <https://github.com/pylint-dev/pylint>`_ for checking the code.
25
26* Use patman to send your patches (``tools/patman/patman -H`` for full
27  instructions). With a few tags in your commits this will check your patches
28  and take care of emailing them.
29
30* If you don't use patman, make sure to run ``scripts/checkpatch.pl``. For
31  more information, read :doc:`checkpatch`. Note that this should be done
32  *before* posting on the mailing list!
33
34* Source files originating from different projects (for example the MTD
35  subsystem or the hush shell code from the BusyBox project) may, after
36  careful consideration, be exempted from these rules. For such files, the
37  original coding style may be kept to ease subsequent migration to newer
38  versions of those sources.
39
40* Please also stick to the following formatting rules:
41
42  * Remove any trailing white space
43
44  * Use TAB characters for indentation and vertical alignment, not spaces
45
46    * The exception here is Python which requires 4 spaces instead.
47
48  * All source files need to be in "Unix" and not "DOS" or "Windows" format,
49    with respect to line ends.
50
51  * Do not add more than 2 consecutive empty lines to source files
52
53  * Do not add trailing empty lines to source files
54
55  * Using the option ``git config --global color.diff auto`` will help to
56    visually see whitespace problems in ``diff`` output from ``git``.
57
58  * In Emacs one can use ``=M-x whitespace-global-mode=`` to get visual
59    feedback on the nasty details. ``=M-x whitespace-cleanup=`` does The Right
60    Thing (tm)
61
62Submissions of new code or patches that do not conform to these requirements
63shall be rejected with a request to reformat the changes.
64
65U-Boot Code Documentation
66-------------------------
67
68U-Boot adopted the kernel-doc annotation style, this is the only exception from
69multi-line comment rule of Coding Style. While not mandatory, adding
70documentation is strongly advised. The Linux kernel `kernel-doc
71<https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html>`_
72documentation applies with no changes.
73
74Our Python code documentation follows `PEP257 (Docstring Conventions)
75<https://peps.python.org/pep-0257/>`_.
76
77Use structures for I/O access
78-----------------------------
79
80U-Boot typically uses a C structure to map out the registers in an I/O region,
81rather than offsets. The reasons for this are:
82
83* It dissociates the register location (offset) from the register type, which
84  means the developer has to make sure the type is right for each access,
85  whereas with the struct method, this is checked by the compiler;
86
87* It avoids actually writing all offsets, which is (more) error-prone;
88
89* It allows for better compile time sanity-checking of values we write to registers.
90
91Some reasons why you might not use C structures:
92
93* Where the registers appear at different offsets in different hardware
94  revisions supported by the same driver
95
96* Where the driver only uses a small subset of registers and it is not worth
97  defining a struct to cover them all, with large empty regions
98
99* Where the offset of a register might be hard to figure out when buried a long
100  way down a structure, possibly with embedded sub-structures
101
102* This may need to change to the kernel model if we allow for more run-time
103  detection of what drivers are appropriate for what we're running on.
104
105Please use the check_member() macro to verify that your structure is the
106expected size, or that particular members appear at the right offset.
107
108Include files
109-------------
110
111You should follow this ordering in U-Boot. The common.h header (which is going
112away at some point) should always be first, followed by other headers in order,
113then headers with directories, then local files:
114
115.. code-block:: C
116
117   #include <common.h>
118   #include <bootstage.h>
119   #include <dm.h>
120   #include <others.h>
121   #include <asm/...>
122   #include <arm/arch/...>
123   #include <dm/device_compat/.h>
124   #include <linux/...>
125   #include "local.h"
126
127Within that order, sort your includes.
128
129It is important to include common.h first since it provides basic features used
130by most files, e.g. CONFIG options.
131
132For files that need to be compiled for the host (e.g. tools), you need to use
133``#ifndef USE_HOSTCC`` to avoid including common.h since it includes a lot of
134internal U-Boot things. See common/image.c for an example.
135
136If your file uses driver model, include <dm.h> in the C file. Do not include
137dm.h in a header file. Try to use forward declarations (e.g. ``struct
138udevice``) instead.
139
140Filenames
141---------
142
143For .c and .h files try to use underscore rather than hyphen unless you want
144the file to stand out (e.g. driver-model uclasses should be named xxx-uclass.h.
145Avoid upper case and keep the names fairly short.
146
147Function and struct comments
148----------------------------
149
150Non-trivial functions should have a comment which describes what they do. If it
151is an exported function, put the comment in the header file so the API is in
152one place. If it is a static function, put it in the C file.
153
154If the function returns errors, mention that and list the different errors that
155are returned. If it is merely passing errors back from a function it calls,
156then you can skip that.
157
158See `here
159<https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation>`_
160for style.
161
162Driver model
163------------
164
165When declaring a device, try to use ``struct udevice *dev``, i.e. ``dev`` as the name:
166
167.. code-block:: C
168
169   struct udevice *dev;
170
171Use ``ret`` as the return value:
172
173.. code-block:: C
174
175   struct udevice *dev;
176   int ret;
177
178   ret = uclass_first_device_err(UCLASS_ACPI_PMC, &dev);
179   if (ret)
180           return log_msg_ret("pmc", dev);
181
182Consider using log_ret() or log_msg_ret() to return a value (see above).
183
184Add a ``p`` suffix on return arguments:
185
186.. code-block:: C
187
188   int dm_pci_find_class(uint find_class, int index, struct udevice **devp)
189   {
190   ...
191           *devp = dev;
192
193           return 0;
194   }
195
196There are standard variable names that you should use in drivers:
197
198* ``struct xxx_priv`` and ``priv`` for dev_get_priv()
199
200* ``struct xxx_plat`` and ``plat`` for dev_get_platdata()
201
202For example:
203
204.. code-block:: C
205
206   struct simple_bus_plat {
207      u32 base;
208      u32 size;
209      u32 target;
210   };
211
212   /* Davinci MMC board definitions */
213   struct davinci_mmc_priv {
214      struct davinci_mmc_regs *reg_base;   /* Register base address */
215      uint input_clk;      /* Input clock to MMC controller */
216      struct gpio_desc cd_gpio;       /* Card Detect GPIO */
217      struct gpio_desc wp_gpio;       /* Write Protect GPIO */
218   };
219
220      struct rcar_gpio_priv *priv = dev_get_priv(dev);
221
222      struct pl01x_serial_platdata *plat = dev_get_platdata(dev);
223
224Other
225-----
226
227Some minor things:
228
229* Put a blank line before the last ``return`` in a function unless it is the only line:
230
231.. code-block:: C
232
233   struct udevice *pci_get_controller(struct udevice *dev)
234   {
235      while (device_is_on_pci_bus(dev))
236         dev = dev->parent;
237
238      return dev;
239   }
240
241Tests
242-----
243
244Please add tests when you add code. Please change or expand tests when you change code.
245
246Run the tests with::
247
248   make check
249   make qcheck   (skips some tests)
250
251Python tests are in test/py/tests - see the docs in test/py for info.
252
253Try to write your tests in C if you can. For example, tests to check a command
254will be much faster (10-100x or more) if they can directly call run_command()
255and ut_check_console_line() instead of using Python to send commands over a
256pipe to U-Boot.
257
258Tests run all supported CI systems (GitLab, Azure) using scripts in the root of
259the U-Boot tree.
260