doc/develop/codingstyle.rst

   1 .. SPDX-License-Identifier: GPL-2.0+:
   2
   3 U-Boot Coding Style
   4 ===================
   5
   6 The following Coding Style requirements shall be mandatory for all code contributed to
   7 the U-Boot project.
   8
   9 Exceptions are only allowed if code from other projects is integrated with no
  10 or only minimal changes.
  11
  12 The 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
  62 Submissions of new code or patches that do not conform to these requirements
  63 shall be rejected with a request to reformat the changes.
  64
  65 U-Boot Code Documentation
  66 -------------------------
  67
  68 U-Boot adopted the kernel-doc annotation style, this is the only exception from
  69 multi-line comment rule of Coding Style. While not mandatory, adding
  70 documentation is strongly advised. The Linux kernel `kernel-doc
  71 <https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html>`_
  72 documentation applies with no changes.
  73
  74 Our Python code documentation follows `PEP257 (Docstring Conventions)
  75 <https://peps.python.org/pep-0257/>`_.
  76
  77 Use structures for I/O access
  78 -----------------------------
  79
  80 U-Boot typically uses a C structure to map out the registers in an I/O region,
  81 rather 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
  91 Some 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
 105 Please use the check_member() macro to verify that your structure is the
 106 expected size, or that particular members appear at the right offset.
 107
 108 Include files
 109 -------------
 110
 111 You should follow this ordering in U-Boot. In all cases, they should be listed
 112 in alphabetical order. First comes headers which are located directly in our
 113 top-level include diretory. Second are headers within subdirectories, Finally
 114 directory-local includes should be listed. See this example:
 115
 116 .. code-block:: C
 117
 118    #include <bootstage.h>
 119    #include <dm.h>
 120    #include <others.h>
 121    #include <asm/...>
 122    #include <asm/arch/...>
 123    #include <dm/device_compat.h>
 124    #include <linux/...>
 125    #include "local.h"
 126
 127 For files that need to be compiled for the host (e.g. tools), you need to use
 128 ``#ifndef USE_HOSTCC`` to avoid including U-Boot specific include files. See
 129 common/image.c for an example.
 130
 131 If your file uses driver model, include <dm.h> in the C file. Do not include
 132 dm.h in a header file. Try to use forward declarations (e.g. ``struct
 133 udevice``) instead.
 134
 135 Filenames
 136 ---------
 137
 138 For .c and .h files try to use underscore rather than hyphen unless you want
 139 the file to stand out (e.g. driver-model uclasses should be named xxx-uclass.h.
 140 Avoid upper case and keep the names fairly short.
 141
 142 Function and struct comments
 143 ----------------------------
 144
 145 Non-trivial functions should have a comment which describes what they do. If it
 146 is an exported function, put the comment in the header file so the API is in
 147 one place. If it is a static function, put it in the C file.
 148
 149 If the function returns errors, mention that and list the different errors that
 150 are returned. If it is merely passing errors back from a function it calls,
 151 then you can skip that.
 152
 153 See `here
 154 <https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation>`_
 155 for style.
 156
 157 Driver model
 158 ------------
 159
 160 When declaring a device, try to use ``struct udevice *dev``, i.e. ``dev`` as the name:
 161
 162 .. code-block:: C
 163
 164    struct udevice *dev;
 165
 166 Use ``ret`` as the return value:
 167
 168 .. code-block:: C
 169
 170    struct udevice *dev;
 171    int ret;
 172
 173    ret = uclass_first_device_err(UCLASS_ACPI_PMC, &dev);
 174    if (ret)
 175            return log_msg_ret("pmc", dev);
 176
 177 Consider using log_ret() or log_msg_ret() to return a value (see above).
 178
 179 Add a ``p`` suffix on return arguments:
 180
 181 .. code-block:: C
 182
 183    int dm_pci_find_class(uint find_class, int index, struct udevice **devp)
 184    {
 185    ...
 186            *devp = dev;
 187
 188            return 0;
 189    }
 190
 191 There are standard variable names that you should use in drivers:
 192
 193 * ``struct xxx_priv`` and ``priv`` for dev_get_priv()
 194
 195 * ``struct xxx_plat`` and ``plat`` for dev_get_platdata()
 196
 197 For example:
 198
 199 .. code-block:: C
 200
 201    struct simple_bus_plat {
 202       u32 base;
 203       u32 size;
 204       u32 target;
 205    };
 206
 207    /* Davinci MMC board definitions */
 208    struct davinci_mmc_priv {
 209       struct davinci_mmc_regs *reg_base;   /* Register base address */
 210       uint input_clk;      /* Input clock to MMC controller */
 211       struct gpio_desc cd_gpio;       /* Card Detect GPIO */
 212       struct gpio_desc wp_gpio;       /* Write Protect GPIO */
 213    };
 214
 215       struct rcar_gpio_priv *priv = dev_get_priv(dev);
 216
 217       struct pl01x_serial_platdata *plat = dev_get_platdata(dev);
 218
 219 Other
 220 -----
 221
 222 Some minor things:
 223
 224 * Put a blank line before the last ``return`` in a function unless it is the only line:
 225
 226 .. code-block:: C
 227
 228    struct udevice *pci_get_controller(struct udevice *dev)
 229    {
 230       while (device_is_on_pci_bus(dev))
 231          dev = dev->parent;
 232
 233       return dev;
 234    }
 235
 236 Tests
 237 -----
 238
 239 Please add tests when you add code. Please change or expand tests when you change code.
 240
 241 Run the tests with::
 242
 243    make check
 244    make qcheck   (skips some tests)
 245
 246 Python tests are in test/py/tests - see the docs in test/py for info.
 247
 248 Try to write your tests in C if you can. For example, tests to check a command
 249 will be much faster (10-100x or more) if they can directly call run_command()
 250 and ut_check_console_line() instead of using Python to send commands over a
 251 pipe to U-Boot.
 252
 253 Tests run all supported CI systems (GitLab, Azure) using scripts in the root of
 254 the U-Boot tree.