[PATCH 1/7] doc: Migrate CodingStyle wiki page to Sphinx
Move the current CodingStyle wiki page to doc/develop/codingstyle.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com --- Changes in v2: - Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich --- doc/develop/codingstyle.rst | 255 ++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 8 ++ 2 files changed, 263 insertions(+) create mode 100644 doc/develop/codingstyle.rst
diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst new file mode 100644 index 000000000000..bbeca42e656b --- /dev/null +++ b/doc/develop/codingstyle.rst @@ -0,0 +1,255 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +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 https://www.kernel.org/doc/html/latest/process/coding-style.html`_ + and the `Lindent script https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/Lindent`_. + * The exception for net files to the `multi-line comment + https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting`_ + 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 ``scripts/checkpatch.pl``. For + more information, read :doc:`checkpatch`. 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 +https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html`_ +documentation 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 + +* 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 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. The common.h header (which is going +away at some point) should always be first, followed by other headers in order, +then headers with directories, then local files: + +.. code-block:: C + + #include <common.h> + #include <bootstage.h> + #include <dm.h> + #include <others.h> + #include <asm/...> + #include <arm/arch/...> + #include <dm/device_compat/.h> + #include <linux/...> + #include "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 <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 +https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation`_ +for style. + +Driver model +------------ + +When declaring a device, try to use ``struct udevice *dev``, i.e. ``dev`` as the name: + +.. code-block:: C + + struct udevice *dev; + +Use ``ret`` as the return value: + +.. code-block:: C + + struct udevice *dev; + int ret; + + ret = uclass_first_device_err(UCLASS_ACPI_PMC, &dev); + if (ret) + return log_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: + +.. code-block:: C + + int dm_pci_find_class(uint find_class, int index, struct udevice **devp) + { + ... + *devp = dev; + + return 0; + } + +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: + +.. code-block:: C + + struct simple_bus_plat { + u32 base; + u32 size; + u32 target; + }; + + /* Davinci MMC board definitions */ + struct davinci_mmc_priv { + struct davinci_mmc_regs *reg_base; /* Register base address */ + uint input_clk; /* Input clock to MMC controller */ + struct gpio_desc cd_gpio; /* Card Detect GPIO */ + struct gpio_desc wp_gpio; /* Write Protect GPIO */ + }; + + struct rcar_gpio_priv *priv = dev_get_priv(dev); + + struct pl01x_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: + +.. code-block:: C + + struct udevice *pci_get_controller(struct udevice *dev) + { + while (device_is_on_pci_bus(dev)) + dev = dev->parent; + + return dev; + } + +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, travis, azure) using scripts in the +root of the U-Boot tree. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index fe3564a9fbf4..dde47994c71a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -3,6 +3,14 @@ Develop U-Boot ==============
+General +------- + +.. toctree:: + :maxdepth: 1 + + codingstyle + Implementation --------------
Move the current DesignPrinciples wiki page to doc/develop/designprinciples.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com --- Changes in v2: - Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich --- doc/develop/designprinciples.rst | 205 +++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 206 insertions(+) create mode 100644 doc/develop/designprinciples.rst
diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst new file mode 100644 index 000000000000..43aeb5dacf5f --- /dev/null +++ b/doc/develop/designprinciples.rst @@ -0,0 +1,205 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +U-Boot Design Principles +======================== + +The 10 Golden Rules of U-Boot design +------------------------------------ + +Keep it Small +^^^^^^^^^^^^^ + +U-Boot is a Boot Loader, i.e. its primary purpose in the shipping +system is to load some operating system. +That means that U-Boot is +necessary to perform a certain task, but it's nothing you want to +throw any significant resources at. Typically U-Boot is stored in +relatively small NOR flash memory, which is expensive +compared to the much larger NAND devices often used to store the +operating system and the application. + +At the moment, U-Boot supports boards with just 128 KiB ROM or with +256 KiB NOR flash. We should not easily ignore such configurations - +they may be the exception in among all the other supported boards, +but if a design uses such a resource-constrained hardware setup it is +usually because costs are critical, i. e. because the number of +manufactured boards might be tens or hundreds of thousands or even +millions... + +A usable and useful configuration of U-Boot, including a basic +interactive command interpreter, support for download over Ethernet +and the capability to program the flash shall fit in no more than 128 !KiB. + +Keep it Fast +^^^^^^^^^^^^ + +The end user is not interested in running U-Boot. In most embedded +systems he is not even aware that U-Boot exists. The user wants to +run some application code, and that as soon as possible after switching +on his device. + +It is therefore essential that U-Boot is as fast as possible, +especially that it loads and boots the operating system as fast as possible. + +To achieve this, the following design principles shall be followed: + +* Enable caches as soon and whenever possible + +* Initialize devices only when they are needed within U-Boot, i.e. don't + initialize the Ethernet interface(s) unless U-Boot performs a download over + Ethernet; don't initialize any IDE or USB devices unless U-Boot actually + tries to load files from these, etc. (and don't forget to shut down these + devices after using them - otherwise nasty things may happen when you try to + boot your OS). + +Also, building of U-Boot shall be as fast as possible. +This makes it easier to run a build for all supported configurations +or at least for all configurations of a specific architecture, +which is essential for quality assurance. +If building is cumbersome and slow, most people will omit +this important step. + +Keep it Simple +^^^^^^^^^^^^^^ + +U-Boot is a boot loader, but it is also a tool used for board +bring-up, for production testing, and for other activities + +Keep it Portable +^^^^^^^^^^^^^^^^ + +U-Boot is a boot loader, but it is also a tool used for board +bring-up, for production testing, and for other activities that are +very closely related to hardware development. So far, it has been +ported to several hundreds of different boards on about 30 different +processor families - please make sure that any code you add can be +used on as many different platforms as possible. + +Avoid assembly language whenever possible - only the reset code with +basic CPU initialization, maybe a static DRAM initialization and the C +stack setup should be in assembly. +All further initializations should be done in C using assembly/C +subroutines or inline macros. These functions represent some +kind of HAL functionality and should be defined consistently on all +architectures. E.g. Basic MMU and cache control, stack pointer manipulation. +Non-existing functions should expand into empty macros or error codes. + +Don't make assumptions over the environment where U-Boot is running. +It may be communicating with a human operator on directly attached +serial console, but it may be through a GSM modem as well, or driven +by some automatic test or control system. So don't output any fancy +control character sequences or similar. + +Keep it Configurable +^^^^^^^^^^^^^^^^^^^^ + +Section "Keep it Small" already explains about the size restrictions +for U-Boot on one side. On the other side, U-Boot is a powerful tool +with many, many extremely useful features. The maintainer or user of +each board will have to decide which features are important to him and +what shall be included with his specific board configuration to meet +his current requirements and restrictions. + +Please make sure that it is easy to add or remove features from a +board configuration, so everybody can make the best use of U-Boot on +his system. + +If a feature is not included, it should not have any residual code +bloating the build. + +Keep it Debuggable +^^^^^^^^^^^^^^^^^^ + +Of course debuggable code is a big benefit for all of us contributing +in one way or another to the development of the U-Boot project. But +as already mentioned in section "Keep it Portable" above, U-Boot is +not only a tool in itself, it is often also used for hardware +bring-up, so debugging U-Boot often means that we don't know if we are +tracking down a problem in the U-Boot software or in the hardware we +are running on. Code that is clean and easy to understand and to +debug is all the more important to many of us. + +* One important feature of U-Boot is to enable output to the (usually serial) + console as soon as possible in the boot process, even if this causes + tradeoffs in other areas like memory footprint. + +* All initialization steps shall print some "begin doing this" message before + they actually start, and some "done" message when they complete. For example, + RAM initialization and size detection may print a "RAM: " before they start, + and "256 MB\n" when done. The purpose of this is that you can always see + which initialization step was running if there should be any problem. This + is important not only during software development, but also for the service + people dealing with broken hardware in the field. + +* U-Boot should be debuggable with simple JTAG or BDM equipment. It shall use + a simple, single-threaded execution model. Avoid any magic, which could + prevent easy debugging even when only 1 or 2 hardware breakpoints are + available. + +Keep it Usable +^^^^^^^^^^^^^^ + +Please always keep in mind that there are at least three different +groups of users for U-Boot, with completely different expectations +and requirements: + +* The end user of an embedded device just wants to run some application; he + does not even want to know that U-Boot exists and only rarely interacts with + it (for example to perform a reset to factory default settings etc.) + +* System designers and engineers working on the development of the application + and/or the operating system want a powerful tool that can boot from any boot + device they can imagine, they want it fast and scriptable and whatever - in + short, they want as many features supported as possible. And some more. + +* The engineer who ports U-Boot to a new board and the board maintainer want + U-Boot to be as simple as possible so porting it to and maintaining it on + their hardware is easy for them. + +* Make it easy to test. Add debug code (but don't re-invent the wheel - use + existing macros like debug() or debugX()). + +Please always keep in mind that U-Boot tries to meet all these +different requirements. + +Keep it Maintainable +^^^^^^^^^^^^^^^^^^^^ + +* Avoid ``#ifdefs`` where possible + +* Use "weak" functions + +* Always follow the :doc:`codingstyle` requirements. + +Keep it Beautiful +^^^^^^^^^^^^^^^^^ + +* Keep the source code clean: strictly follow the :doc:`codingstyle`, + keep lists (target names in the Makefiles, board names, etc.) + alphabetically sorted, etc. + +* Keep U-Boot console output clean: output only really necessary information, + be terse but precise, keep output vertically aligned, do not use control + character sequences (e.g. backspaces or \r to do "spinning wheel" activity + indicators), etc. + +Keep it Open +^^^^^^^^^^^^ + +Contribute your work back to the whole community. Submit your changes +and extensions as patches to the U-Boot mailing list. + +Lemmas from the golden rules +---------------------------- + +Generic Code is Good Code +^^^^^^^^^^^^^^^^^^^^^^^^^ + +New code shall be as generic as possible and added to the U-Boot +abstraction hierarchy as high as possible. As few code as possible shall be +added in board directories as people usually do not expect re-usable code +there. Thus peripheral drivers should be put below +"drivers" even if they start out supporting only one specific +configuration. Note that it is not a requirement for such a first +instance to be generic as genericity generally cannot be extrapolated +from a single data point. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index dde47994c71a..c0f4f0ba413a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -10,6 +10,7 @@ General :maxdepth: 1
codingstyle + designprinciples
Implementation --------------
On 7/11/22 19:14, Tom Rini wrote:
Move the current DesignPrinciples wiki page to doc/develop/designprinciples.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich
doc/develop/designprinciples.rst | 205 +++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 206 insertions(+) create mode 100644 doc/develop/designprinciples.rst
diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst new file mode 100644 index 000000000000..43aeb5dacf5f --- /dev/null +++ b/doc/develop/designprinciples.rst @@ -0,0 +1,205 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+U-Boot Design Principles +========================
+The 10 Golden Rules of U-Boot design +------------------------------------
+Keep it Small +^^^^^^^^^^^^^
+U-Boot is a Boot Loader, i.e. its primary purpose in the shipping +system is to load some operating system. +That means that U-Boot is +necessary to perform a certain task, but it's nothing you want to +throw any significant resources at. Typically U-Boot is stored in +relatively small NOR flash memory, which is expensive +compared to the much larger NAND devices often used to store the +operating system and the application.
+At the moment, U-Boot supports boards with just 128 KiB ROM or with +256 KiB NOR flash. We should not easily ignore such configurations - +they may be the exception in among all the other supported boards, +but if a design uses such a resource-constrained hardware setup it is +usually because costs are critical, i. e. because the number of +manufactured boards might be tens or hundreds of thousands or even +millions...
+A usable and useful configuration of U-Boot, including a basic +interactive command interpreter, support for download over Ethernet +and the capability to program the flash shall fit in no more than 128 !KiB.
+Keep it Fast +^^^^^^^^^^^^
+The end user is not interested in running U-Boot. In most embedded +systems he is not even aware that U-Boot exists. The user wants to +run some application code, and that as soon as possible after switching +on his device.
+It is therefore essential that U-Boot is as fast as possible, +especially that it loads and boots the operating system as fast as possible.
+To achieve this, the following design principles shall be followed:
+* Enable caches as soon and whenever possible
+* Initialize devices only when they are needed within U-Boot, i.e. don't
- initialize the Ethernet interface(s) unless U-Boot performs a download over
- Ethernet; don't initialize any IDE or USB devices unless U-Boot actually
- tries to load files from these, etc. (and don't forget to shut down these
- devices after using them - otherwise nasty things may happen when you try to
- boot your OS).
+Also, building of U-Boot shall be as fast as possible. +This makes it easier to run a build for all supported configurations +or at least for all configurations of a specific architecture, +which is essential for quality assurance. +If building is cumbersome and slow, most people will omit +this important step.
+Keep it Simple +^^^^^^^^^^^^^^
+U-Boot is a boot loader, but it is also a tool used for board +bring-up, for production testing, and for other activities
+Keep it Portable +^^^^^^^^^^^^^^^^
+U-Boot is a boot loader, but it is also a tool used for board +bring-up, for production testing, and for other activities that are +very closely related to hardware development. So far, it has been +ported to several hundreds of different boards on about 30 different +processor families - please make sure that any code you add can be +used on as many different platforms as possible.
+Avoid assembly language whenever possible - only the reset code with +basic CPU initialization, maybe a static DRAM initialization and the C +stack setup should be in assembly. +All further initializations should be done in C using assembly/C +subroutines or inline macros. These functions represent some +kind of HAL functionality and should be defined consistently on all +architectures. E.g. Basic MMU and cache control, stack pointer manipulation.
%s/. E.g./, e.g./
%s/Basic/basic/
+Non-existing functions should expand into empty macros or error codes.
+Don't make assumptions over the environment where U-Boot is running.
%s/over/about/
+It may be communicating with a human operator on directly attached +serial console, but it may be through a GSM modem as well, or driven +by some automatic test or control system. So don't output any fancy +control character sequences or similar.
+Keep it Configurable +^^^^^^^^^^^^^^^^^^^^
+Section "Keep it Small" already explains about the size restrictions +for U-Boot on one side. On the other side, U-Boot is a powerful tool +with many, many extremely useful features. The maintainer or user of +each board will have to decide which features are important to him and +what shall be included with his specific board configuration to meet +his current requirements and restrictions.
+Please make sure that it is easy to add or remove features from a +board configuration, so everybody can make the best use of U-Boot on +his system.
+If a feature is not included, it should not have any residual code +bloating the build.
+Keep it Debuggable +^^^^^^^^^^^^^^^^^^
+Of course debuggable code is a big benefit for all of us contributing +in one way or another to the development of the U-Boot project. But +as already mentioned in section "Keep it Portable" above, U-Boot is +not only a tool in itself, it is often also used for hardware +bring-up, so debugging U-Boot often means that we don't know if we are +tracking down a problem in the U-Boot software or in the hardware we +are running on. Code that is clean and easy to understand and to +debug is all the more important to many of us.
+* One important feature of U-Boot is to enable output to the (usually serial)
- console as soon as possible in the boot process, even if this causes
- tradeoffs in other areas like memory footprint.
+* All initialization steps shall print some "begin doing this" message before
Look at the number of initialization step in board_r and board_f. For sure the advice above is wrong.
Generally we want the system to be quiet and avoid superfluous messages.
If everything passes normally, there should be no message at all. If an error occurs write a message.
- they actually start, and some "done" message when they complete. For example,
- RAM initialization and size detection may print a "RAM: " before they start,
- and "256 MB\n" when done. The purpose of this is that you can always see
- which initialization step was running if there should be any problem. This
- is important not only during software development, but also for the service
- people dealing with broken hardware in the field.
+* U-Boot should be debuggable with simple JTAG or BDM equipment. It shall use
- a simple, single-threaded execution model. Avoid any magic, which could
- prevent easy debugging even when only 1 or 2 hardware breakpoints are
- available.
+Keep it Usable +^^^^^^^^^^^^^^
+Please always keep in mind that there are at least three different +groups of users for U-Boot, with completely different expectations +and requirements:
+* The end user of an embedded device just wants to run some application; he
- does not even want to know that U-Boot exists and only rarely interacts with
- it (for example to perform a reset to factory default settings etc.)
+* System designers and engineers working on the development of the application
- and/or the operating system want a powerful tool that can boot from any boot
- device they can imagine, they want it fast and scriptable and whatever - in
- short, they want as many features supported as possible. And some more.
+* The engineer who ports U-Boot to a new board and the board maintainer want
- U-Boot to be as simple as possible so porting it to and maintaining it on
- their hardware is easy for them.
+* Make it easy to test. Add debug code (but don't re-invent the wheel - use
- existing macros like debug() or debugX()).
Please, don't advise to use of debug(). Refer to log_debug() instead.
debugX() does not exist.
Best regards
Heinrich
+Please always keep in mind that U-Boot tries to meet all these +different requirements.
+Keep it Maintainable +^^^^^^^^^^^^^^^^^^^^
+* Avoid ``#ifdefs`` where possible
+* Use "weak" functions
+* Always follow the :doc:`codingstyle` requirements.
+Keep it Beautiful +^^^^^^^^^^^^^^^^^
+* Keep the source code clean: strictly follow the :doc:`codingstyle`,
- keep lists (target names in the Makefiles, board names, etc.)
- alphabetically sorted, etc.
+* Keep U-Boot console output clean: output only really necessary information,
- be terse but precise, keep output vertically aligned, do not use control
- character sequences (e.g. backspaces or \r to do "spinning wheel" activity
- indicators), etc.
+Keep it Open +^^^^^^^^^^^^
+Contribute your work back to the whole community. Submit your changes +and extensions as patches to the U-Boot mailing list.
+Lemmas from the golden rules +----------------------------
+Generic Code is Good Code +^^^^^^^^^^^^^^^^^^^^^^^^^
+New code shall be as generic as possible and added to the U-Boot +abstraction hierarchy as high as possible. As few code as possible shall be +added in board directories as people usually do not expect re-usable code +there. Thus peripheral drivers should be put below +"drivers" even if they start out supporting only one specific +configuration. Note that it is not a requirement for such a first +instance to be generic as genericity generally cannot be extrapolated +from a single data point. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index dde47994c71a..c0f4f0ba413a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -10,6 +10,7 @@ General :maxdepth: 1
codingstyle
designprinciples
Implementation
On Wed, Jul 13, 2022 at 07:22:33PM +0200, Heinrich Schuchardt wrote:
On 7/11/22 19:14, Tom Rini wrote:
Move the current DesignPrinciples wiki page to doc/develop/designprinciples.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich
doc/develop/designprinciples.rst | 205 +++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 206 insertions(+) create mode 100644 doc/develop/designprinciples.rst
diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst new file mode 100644 index 000000000000..43aeb5dacf5f --- /dev/null +++ b/doc/develop/designprinciples.rst @@ -0,0 +1,205 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+U-Boot Design Principles +========================
+The 10 Golden Rules of U-Boot design +------------------------------------
+Keep it Small +^^^^^^^^^^^^^
+U-Boot is a Boot Loader, i.e. its primary purpose in the shipping +system is to load some operating system. +That means that U-Boot is +necessary to perform a certain task, but it's nothing you want to +throw any significant resources at. Typically U-Boot is stored in +relatively small NOR flash memory, which is expensive +compared to the much larger NAND devices often used to store the +operating system and the application.
+At the moment, U-Boot supports boards with just 128 KiB ROM or with +256 KiB NOR flash. We should not easily ignore such configurations - +they may be the exception in among all the other supported boards, +but if a design uses such a resource-constrained hardware setup it is +usually because costs are critical, i. e. because the number of +manufactured boards might be tens or hundreds of thousands or even +millions...
+A usable and useful configuration of U-Boot, including a basic +interactive command interpreter, support for download over Ethernet +and the capability to program the flash shall fit in no more than 128 !KiB.
+Keep it Fast +^^^^^^^^^^^^
+The end user is not interested in running U-Boot. In most embedded +systems he is not even aware that U-Boot exists. The user wants to +run some application code, and that as soon as possible after switching +on his device.
+It is therefore essential that U-Boot is as fast as possible, +especially that it loads and boots the operating system as fast as possible.
+To achieve this, the following design principles shall be followed:
+* Enable caches as soon and whenever possible
+* Initialize devices only when they are needed within U-Boot, i.e. don't
- initialize the Ethernet interface(s) unless U-Boot performs a download over
- Ethernet; don't initialize any IDE or USB devices unless U-Boot actually
- tries to load files from these, etc. (and don't forget to shut down these
- devices after using them - otherwise nasty things may happen when you try to
- boot your OS).
+Also, building of U-Boot shall be as fast as possible. +This makes it easier to run a build for all supported configurations +or at least for all configurations of a specific architecture, +which is essential for quality assurance. +If building is cumbersome and slow, most people will omit +this important step.
+Keep it Simple +^^^^^^^^^^^^^^
+U-Boot is a boot loader, but it is also a tool used for board +bring-up, for production testing, and for other activities
+Keep it Portable +^^^^^^^^^^^^^^^^
+U-Boot is a boot loader, but it is also a tool used for board +bring-up, for production testing, and for other activities that are +very closely related to hardware development. So far, it has been +ported to several hundreds of different boards on about 30 different +processor families - please make sure that any code you add can be +used on as many different platforms as possible.
+Avoid assembly language whenever possible - only the reset code with +basic CPU initialization, maybe a static DRAM initialization and the C +stack setup should be in assembly. +All further initializations should be done in C using assembly/C +subroutines or inline macros. These functions represent some +kind of HAL functionality and should be defined consistently on all +architectures. E.g. Basic MMU and cache control, stack pointer manipulation.
%s/. E.g./, e.g./
%s/Basic/basic/
It should probably read "on all architectures, e.g. basic ...". I'll reword.
+Non-existing functions should expand into empty macros or error codes.
+Don't make assumptions over the environment where U-Boot is running.
%s/over/about/
Yes.
+It may be communicating with a human operator on directly attached +serial console, but it may be through a GSM modem as well, or driven +by some automatic test or control system. So don't output any fancy +control character sequences or similar.
+Keep it Configurable +^^^^^^^^^^^^^^^^^^^^
+Section "Keep it Small" already explains about the size restrictions +for U-Boot on one side. On the other side, U-Boot is a powerful tool +with many, many extremely useful features. The maintainer or user of +each board will have to decide which features are important to him and +what shall be included with his specific board configuration to meet +his current requirements and restrictions.
+Please make sure that it is easy to add or remove features from a +board configuration, so everybody can make the best use of U-Boot on +his system.
+If a feature is not included, it should not have any residual code +bloating the build.
+Keep it Debuggable +^^^^^^^^^^^^^^^^^^
+Of course debuggable code is a big benefit for all of us contributing +in one way or another to the development of the U-Boot project. But +as already mentioned in section "Keep it Portable" above, U-Boot is +not only a tool in itself, it is often also used for hardware +bring-up, so debugging U-Boot often means that we don't know if we are +tracking down a problem in the U-Boot software or in the hardware we +are running on. Code that is clean and easy to understand and to +debug is all the more important to many of us.
+* One important feature of U-Boot is to enable output to the (usually serial)
- console as soon as possible in the boot process, even if this causes
- tradeoffs in other areas like memory footprint.
+* All initialization steps shall print some "begin doing this" message before
Look at the number of initialization step in board_r and board_f. For sure the advice above is wrong.
Generally we want the system to be quiet and avoid superfluous messages.
If everything passes normally, there should be no message at all. If an error occurs write a message.
This is something to address in a follow-up patch.
- they actually start, and some "done" message when they complete. For example,
- RAM initialization and size detection may print a "RAM: " before they start,
- and "256 MB\n" when done. The purpose of this is that you can always see
- which initialization step was running if there should be any problem. This
- is important not only during software development, but also for the service
- people dealing with broken hardware in the field.
+* U-Boot should be debuggable with simple JTAG or BDM equipment. It shall use
- a simple, single-threaded execution model. Avoid any magic, which could
- prevent easy debugging even when only 1 or 2 hardware breakpoints are
- available.
+Keep it Usable +^^^^^^^^^^^^^^
+Please always keep in mind that there are at least three different +groups of users for U-Boot, with completely different expectations +and requirements:
+* The end user of an embedded device just wants to run some application; he
- does not even want to know that U-Boot exists and only rarely interacts with
- it (for example to perform a reset to factory default settings etc.)
+* System designers and engineers working on the development of the application
- and/or the operating system want a powerful tool that can boot from any boot
- device they can imagine, they want it fast and scriptable and whatever - in
- short, they want as many features supported as possible. And some more.
+* The engineer who ports U-Boot to a new board and the board maintainer want
- U-Boot to be as simple as possible so porting it to and maintaining it on
- their hardware is easy for them.
+* Make it easy to test. Add debug code (but don't re-invent the wheel - use
- existing macros like debug() or debugX()).
Please, don't advise to use of debug(). Refer to log_debug() instead.
debugX() does not exist.
Depends on the context I think, I'll update to "log_debug() or debug() depending on context".
For some time now we've allowed for '//' style comments, which mirrors the Linux kernel. So drop this point here.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com --- Changes in v2: - None --- doc/develop/codingstyle.rst | 6 ------ 1 file changed, 6 deletions(-)
diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst index bbeca42e656b..fdc1f594babc 100644 --- a/doc/develop/codingstyle.rst +++ b/doc/develop/codingstyle.rst @@ -33,12 +33,6 @@ The following rules apply: 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
Move the current Process wiki page to doc/develop/process.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com --- Changes in v2: - Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich --- doc/develop/index.rst | 1 + doc/develop/process.rst | 200 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 201 insertions(+) create mode 100644 doc/develop/process.rst
diff --git a/doc/develop/index.rst b/doc/develop/index.rst index c0f4f0ba413a..eab00a55382a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -11,6 +11,7 @@ General
codingstyle designprinciples + process
Implementation -------------- diff --git a/doc/develop/process.rst b/doc/develop/process.rst new file mode 100644 index 000000000000..534da4a2a704 --- /dev/null +++ b/doc/develop/process.rst @@ -0,0 +1,200 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +U-Boot Development Process +========================== + +Management Summary +------------------ + +* Development happens in Release Cycles of 3 months. + +* The first 2 weeks are called Merge Window, which is followed by a + Stabilization Period. + +* Patches with new code get only accepted while the Merge Window is open. + +* A patch that is generally in good shape and that was submitted while the + Merge Window was open is eligible to go into the upcoming release, even if + changes and resubmits are needed. + +* During the Stabilization Period, only patches that contain bug fixes get + applied. + +Phases of the Development Process +--------------------------------- + +U-Boot development takes place in `Release Cycles +https://www.denx.de/wiki/U-Boot/ReleaseCycle`_. A Release Cycle lasts +normally for three months. + +The first two weeks of each Release Cycle are called *Merge Window*. + +It is followed by a *Stabilization Period*. + +The end of a Release Cycle is marked by the release of a new U-Boot version. + +Merge Window +------------ + +The Merge Window is the period when new patches get submitted +(and hopefully accepted) for inclusion into U-Boot mainline. + +This is the only time when new code (like support for new processors or new +boards, or other new features or reorganization of code) is accepted. + +Twilight Time +------------- + +Usually patches do not get accepted as they are - the peer review that takes +place will usually require changes and resubmits of the patches before they +are considered to be ripe for inclusion into mainline. + +Also, the review often happens not immediately after a patch was submitted, +but only when somebody (usually the responsible custodian) finds time to do +this. + +In the result, the final version of such patches gets submitted after the +merge window has been closed. + +It is current practice in U-Boot that such patches are eligible to go into the +upcoming release. + +In the result, the release of the ``"-rc1"`` version does not immediately follow +the closing of the Merge Window. + +Stabilization Period +-------------------- + +During the Stabilization Period only patches containing bug fixes get +applied. + +Corner Cases +------------ + +Sometimes it is not clear if a patch contains a bug fix or not. +For example, changes that remove dead code, unused macros etc. or +that contain Coding Style fixes are not strict bug fixes. + +In such situations it is up to the responsible custodian to decide if he +applies such patches even when the Merge Window is closed. + +Exception: at the end of the Stabilization Period only strict bug +fixes my be applied. + +Sometimes patches miss the the Merge Window slightly - say by few +hours or even a day. Patch acceptance is not as critical as a +financial transaction, or such. So if there is such a slight delay, +the custodian is free to turn a blind eye and accept it anyway. The +idea of the development process is to make it foreseeable, +but not to slow down development. + +It makes more sense if an engineer spends another day on testing and +cleanup and submits the patch a couple of hours late, instead of +submitting a green patch which will waste efforts from several people +during several rounds of review and reposts. + +Differences to the Linux Development Process +-------------------------------------------- + +* In Linux, top-level maintainers will collect patches in their trees and send + pull requests to Linus as soon as the merge window opens. + So far, most U-Boot custodians do not work like that; they send pull requests + only at (or even after) the end of the merge window. + +* In Linux, the closing of the merge window is marked by the release of the + next ``"-rc1"`` + In U-Boot, ``"-rc1"`` will only be released after all (or at least most of + the) patches that were submitted during the merge window have been applied. + +Custodians +---------- + +The Custodians take responsibility for some area of the U-Boot code. The +in-tree ``MAINTAINERS`` files list who is reponsible for which areas. + +It is their responsibility to pick up patches from the mailing list +that fall into their responsibility, and to process these. + +A very important responsibility of each custodian is to provide +feedback to the submitter of a patch about what is going on: if the +patch was accepted, or if it was rejected (which exact list of +reasons), if it needs to be reworked (with respective review +comments). Even a "I have no time now, will look into it later" +message is better than nothing. Also, if there are remarks to a +patch, these should leave no doubt if they were just comments and the +patch will be accepted anyway, or if the patch should be +reworked/resubmitted, or if it was rejected. + +Work flow of a Custodian +------------------------ + +The normal flow of work in the U-Boot development process will look +like this: + +#. A developer submits a patch via e-mail to the u-boot-users mailing list. + U-Boot has adopted the `Linux kernel signoff policy https://groups.google.com/g/fa.linux.kernel/c/TLJIJVA-I6o?pli=1`_, so the submitter must + include a ``Signed-off-by:`` line. + +#. Everybody who can is invited to review and test the changes. Reviews should + reply on the mailing list with ``Acked-by`` lines. + +#. The responsible custodian + + #. inspects this patch, especially for: + + #. :doc:`codingstyle` + + #. Basic logic: + + * The patch fixes a real problem. + + * The patch does not introduce new problems, especially it does not break + other boards or architectures + + #. U-Boot Philosophy + + #. Applies cleanly to the source tree + + #. passes a ``MAKEALL`` compile test without creating new warnings + +#. Notes: + + #. In some cases more than one custodian may be affected or feel responsible. + To avoid duplicated efforts, the custodian who starts processing the + patch should send a short ACK to the mailing list. + + #. We should create some tool to automatically do this. + + #. This is well documented in :doc:`designprinciples`. + + #. The custodian decides himself how recent the code must be. It is + acceptable to request patches against the last officially released + version of U-Boot or newer. Of course a custodian can also accept + patches against older code. + + #. Commits should show original author in the ``author`` field and include all + sign off/ack lines. + +#. The custodian decides to accept or to reject the patch. + +#. If accepted, the custodian adds the patch to his public git repository and + notifies the mailing list. This note should include: + + * a short description of the changes + + * the list of the affected boards / architectures etc. + + * suggested tests + + Although the custodian is supposed to perform his own tests + it is a well-known and accepted fact that he needs help from + other developers who - for example - have access to the required + hardware or tool chains. + The custodian request help for tests and feedback from + specific maintainers and U-Boot users. + +#. Once tests are passed, some agreed time limit expires, the custodian + requests that the changes in his public git repository be merged into the + main tree. If necessary, the custodian may have to adapt his changes to + allow for a clean merge. + Todo: define a reasonable time limit. 3 weeks?
On 7/11/22 19:14, Tom Rini wrote:
Move the current Process wiki page to doc/develop/process.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich
doc/develop/index.rst | 1 + doc/develop/process.rst | 200 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 201 insertions(+) create mode 100644 doc/develop/process.rst
diff --git a/doc/develop/index.rst b/doc/develop/index.rst index c0f4f0ba413a..eab00a55382a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -11,6 +11,7 @@ General
codingstyle designprinciples
process
Implementation
diff --git a/doc/develop/process.rst b/doc/develop/process.rst new file mode 100644 index 000000000000..534da4a2a704 --- /dev/null +++ b/doc/develop/process.rst @@ -0,0 +1,200 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+U-Boot Development Process +==========================
+Management Summary +------------------
+* Development happens in Release Cycles of 3 months.
+* The first 2 weeks are called Merge Window, which is followed by a
- Stabilization Period.
+* Patches with new code get only accepted while the Merge Window is open.
+* A patch that is generally in good shape and that was submitted while the
- Merge Window was open is eligible to go into the upcoming release, even if
- changes and resubmits are needed.
+* During the Stabilization Period, only patches that contain bug fixes get
- applied.
+Phases of the Development Process +---------------------------------
+U-Boot development takes place in `Release Cycles +https://www.denx.de/wiki/U-Boot/ReleaseCycle`_. A Release Cycle lasts +normally for three months.
+The first two weeks of each Release Cycle are called *Merge Window*.
+It is followed by a *Stabilization Period*.
+The end of a Release Cycle is marked by the release of a new U-Boot version.
+Merge Window +------------
+The Merge Window is the period when new patches get submitted +(and hopefully accepted) for inclusion into U-Boot mainline.
+This is the only time when new code (like support for new processors or new +boards, or other new features or reorganization of code) is accepted.
+Twilight Time +-------------
+Usually patches do not get accepted as they are - the peer review that takes +place will usually require changes and resubmits of the patches before they +are considered to be ripe for inclusion into mainline.
+Also, the review often happens not immediately after a patch was submitted, +but only when somebody (usually the responsible custodian) finds time to do +this.
+In the result, the final version of such patches gets submitted after the +merge window has been closed.
+It is current practice in U-Boot that such patches are eligible to go into the +upcoming release.
+In the result, the release of the ``"-rc1"`` version does not immediately follow +the closing of the Merge Window.
+Stabilization Period +--------------------
+During the Stabilization Period only patches containing bug fixes get +applied.
+Corner Cases +------------
+Sometimes it is not clear if a patch contains a bug fix or not. +For example, changes that remove dead code, unused macros etc. or +that contain Coding Style fixes are not strict bug fixes.
+In such situations it is up to the responsible custodian to decide if he +applies such patches even when the Merge Window is closed.
+Exception: at the end of the Stabilization Period only strict bug +fixes my be applied.
+Sometimes patches miss the the Merge Window slightly - say by few +hours or even a day. Patch acceptance is not as critical as a +financial transaction, or such. So if there is such a slight delay, +the custodian is free to turn a blind eye and accept it anyway. The +idea of the development process is to make it foreseeable, +but not to slow down development.
+It makes more sense if an engineer spends another day on testing and +cleanup and submits the patch a couple of hours late, instead of +submitting a green patch which will waste efforts from several people +during several rounds of review and reposts.
+Differences to the Linux Development Process +--------------------------------------------
+* In Linux, top-level maintainers will collect patches in their trees and send
- pull requests to Linus as soon as the merge window opens.
- So far, most U-Boot custodians do not work like that; they send pull requests
- only at (or even after) the end of the merge window.
+* In Linux, the closing of the merge window is marked by the release of the
- next ``"-rc1"``
- In U-Boot, ``"-rc1"`` will only be released after all (or at least most of
- the) patches that were submitted during the merge window have been applied.
+Custodians +----------
+The Custodians take responsibility for some area of the U-Boot code. The +in-tree ``MAINTAINERS`` files list who is reponsible for which areas.
+It is their responsibility to pick up patches from the mailing list +that fall into their responsibility, and to process these.
+A very important responsibility of each custodian is to provide +feedback to the submitter of a patch about what is going on: if the +patch was accepted, or if it was rejected (which exact list of +reasons), if it needs to be reworked (with respective review +comments). Even a "I have no time now, will look into it later" +message is better than nothing. Also, if there are remarks to a +patch, these should leave no doubt if they were just comments and the +patch will be accepted anyway, or if the patch should be +reworked/resubmitted, or if it was rejected.
+Work flow of a Custodian +------------------------
+The normal flow of work in the U-Boot development process will look +like this:
+#. A developer submits a patch via e-mail to the u-boot-users mailing list.
- U-Boot has adopted the `Linux kernel signoff policy https://groups.google.com/g/fa.linux.kernel/c/TLJIJVA-I6o?pli=1`_, so the submitter must
- include a ``Signed-off-by:`` line.
+#. Everybody who can is invited to review and test the changes. Reviews should
- reply on the mailing list with ``Acked-by`` lines.
+#. The responsible custodian
- #. inspects this patch, especially for:
This should not be a bullet point.
- #. :doc:`codingstyle`
- #. Basic logic:
* The patch fixes a real problem.* The patch does not introduce new problems, especially it does not breakother boards or architectures- #. U-Boot Philosophy
- #. Applies cleanly to the source tree
- #. passes a ``MAKEALL`` compile test without creating new warnings
+#. Notes:
- #. In some cases more than one custodian may be affected or feel responsible.
To avoid duplicated efforts, the custodian who starts processing thepatch should send a short ACK to the mailing list.- #. We should create some tool to automatically do this.
- #. This is well documented in :doc:`designprinciples`.
- #. The custodian decides himself how recent the code must be. It is
acceptable to request patches against the last officially releasedversion of U-Boot or newer. Of course a custodian can also acceptpatches against older code.
This paragraph is unclear. How about:
Patches should be based on the git HEAD. If merge conflicts arise, the custodian decides to either rebase the patch himself or to request the submitter for a rebased patch.
- #. Commits should show original author in the ``author`` field and include all
sign off/ack lines.
Sign-off, Acked-by, Reviewed-by lines.
Best regards
Heinrich
+#. The custodian decides to accept or to reject the patch.
+#. If accepted, the custodian adds the patch to his public git repository and
- notifies the mailing list. This note should include:
- a short description of the changes
- the list of the affected boards / architectures etc.
- suggested tests
- Although the custodian is supposed to perform his own tests
- it is a well-known and accepted fact that he needs help from
- other developers who - for example - have access to the required
- hardware or tool chains.
- The custodian request help for tests and feedback from
- specific maintainers and U-Boot users.
+#. Once tests are passed, some agreed time limit expires, the custodian
- requests that the changes in his public git repository be merged into the
- main tree. If necessary, the custodian may have to adapt his changes to
- allow for a clean merge.
- Todo: define a reasonable time limit. 3 weeks?
On Wed, Jul 13, 2022 at 07:36:02PM +0200, Heinrich Schuchardt wrote:
On 7/11/22 19:14, Tom Rini wrote:
[snip]
+Work flow of a Custodian +------------------------
+The normal flow of work in the U-Boot development process will look +like this:
+#. A developer submits a patch via e-mail to the u-boot-users mailing list.
- U-Boot has adopted the `Linux kernel signoff policy https://groups.google.com/g/fa.linux.kernel/c/TLJIJVA-I6o?pli=1`_, so the submitter must
- include a ``Signed-off-by:`` line.
+#. Everybody who can is invited to review and test the changes. Reviews should
- reply on the mailing list with ``Acked-by`` lines.
+#. The responsible custodian
- #. inspects this patch, especially for:
This should not be a bullet point.
- #. :doc:`codingstyle`
- #. Basic logic:
* The patch fixes a real problem.* The patch does not introduce new problems, especially it does not breakother boards or architectures- #. U-Boot Philosophy
- #. Applies cleanly to the source tree
- #. passes a ``MAKEALL`` compile test without creating new warnings
+#. Notes:
- #. In some cases more than one custodian may be affected or feel responsible.
To avoid duplicated efforts, the custodian who starts processing thepatch should send a short ACK to the mailing list.- #. We should create some tool to automatically do this.
- #. This is well documented in :doc:`designprinciples`.
- #. The custodian decides himself how recent the code must be. It is
acceptable to request patches against the last officially releasedversion of U-Boot or newer. Of course a custodian can also acceptpatches against older code.This paragraph is unclear. How about:
Patches should be based on the git HEAD. If merge conflicts arise, the custodian decides to either rebase the patch himself or to request the submitter for a rebased patch.
- #. Commits should show original author in the ``author`` field and include all
sign off/ack lines.Sign-off, Acked-by, Reviewed-by lines.
Please comment on the later patch where I re-write this section a good deal. To repeat, I do not want to make significant changes to these documents in the same commit that imports them from the wiki.
- Remove some missed wiki markup, and escape a "\n" correctly. - Use gender-neutral language to refer to the user, consistently.
Cc: Claudius Heine ch@denx.de Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com --- Changes in v2: - None --- doc/develop/designprinciples.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst index 43aeb5dacf5f..e5e12dca79f5 100644 --- a/doc/develop/designprinciples.rst +++ b/doc/develop/designprinciples.rst @@ -28,15 +28,15 @@ millions...
A usable and useful configuration of U-Boot, including a basic interactive command interpreter, support for download over Ethernet -and the capability to program the flash shall fit in no more than 128 !KiB. +and the capability to program the flash shall fit in no more than 128 KiB.
Keep it Fast ^^^^^^^^^^^^
The end user is not interested in running U-Boot. In most embedded -systems he is not even aware that U-Boot exists. The user wants to +systems they are not even aware that U-Boot exists. The user wants to run some application code, and that as soon as possible after switching -on his device. +on their device.
It is therefore essential that U-Boot is as fast as possible, especially that it loads and boots the operating system as fast as possible. @@ -63,7 +63,7 @@ Keep it Simple ^^^^^^^^^^^^^^
U-Boot is a boot loader, but it is also a tool used for board -bring-up, for production testing, and for other activities +bring-up, for production testing, and for other activities.
Keep it Portable ^^^^^^^^^^^^^^^^ @@ -96,13 +96,13 @@ Keep it Configurable Section "Keep it Small" already explains about the size restrictions for U-Boot on one side. On the other side, U-Boot is a powerful tool with many, many extremely useful features. The maintainer or user of -each board will have to decide which features are important to him and -what shall be included with his specific board configuration to meet -his current requirements and restrictions. +each board will have to decide which features are important to them and +what shall be included with their specific board configuration to meet +their current requirements and restrictions.
Please make sure that it is easy to add or remove features from a board configuration, so everybody can make the best use of U-Boot on -his system. +their system.
If a feature is not included, it should not have any residual code bloating the build. @@ -126,7 +126,7 @@ debug is all the more important to many of us. * All initialization steps shall print some "begin doing this" message before they actually start, and some "done" message when they complete. For example, RAM initialization and size detection may print a "RAM: " before they start, - and "256 MB\n" when done. The purpose of this is that you can always see + and "256 MB\n" when done. The purpose of this is that you can always see which initialization step was running if there should be any problem. This is important not only during software development, but also for the service people dealing with broken hardware in the field. @@ -143,8 +143,8 @@ Please always keep in mind that there are at least three different groups of users for U-Boot, with completely different expectations and requirements:
-* The end user of an embedded device just wants to run some application; he - does not even want to know that U-Boot exists and only rarely interacts with +* The end user of an embedded device just wants to run some application; they + do not even want to know that U-Boot exists and only rarely interacts with it (for example to perform a reset to factory default settings etc.)
* System designers and engineers working on the development of the application @@ -157,7 +157,7 @@ and requirements: their hardware is easy for them.
* Make it easy to test. Add debug code (but don't re-invent the wheel - use - existing macros like debug() or debugX()). + existing macros like debug()).
Please always keep in mind that U-Boot tries to meet all these different requirements.
On 7/11/22 19:14, Tom Rini wrote:
- Remove some missed wiki markup, and escape a "\n" correctly.
- Use gender-neutral language to refer to the user, consistently.
Cc: Claudius Heine ch@denx.de Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- None
doc/develop/designprinciples.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst index 43aeb5dacf5f..e5e12dca79f5 100644 --- a/doc/develop/designprinciples.rst +++ b/doc/develop/designprinciples.rst @@ -28,15 +28,15 @@ millions...
A usable and useful configuration of U-Boot, including a basic interactive command interpreter, support for download over Ethernet -and the capability to program the flash shall fit in no more than 128 !KiB. +and the capability to program the flash shall fit in no more than 128 KiB.
Keep it Fast ^^^^^^^^^^^^
The end user is not interested in running U-Boot. In most embedded -systems he is not even aware that U-Boot exists. The user wants to +systems they are not even aware that U-Boot exists. The user wants to
"The end user" is singular.
run some application code, and that as soon as possible after switching -on his device. +on their device.
It is therefore essential that U-Boot is as fast as possible, especially that it loads and boots the operating system as fast as possible. @@ -63,7 +63,7 @@ Keep it Simple ^^^^^^^^^^^^^^
U-Boot is a boot loader, but it is also a tool used for board -bring-up, for production testing, and for other activities +bring-up, for production testing, and for other activities.
Keep it Portable ^^^^^^^^^^^^^^^^ @@ -96,13 +96,13 @@ Keep it Configurable Section "Keep it Small" already explains about the size restrictions for U-Boot on one side. On the other side, U-Boot is a powerful tool with many, many extremely useful features. The maintainer or user of -each board will have to decide which features are important to him and -what shall be included with his specific board configuration to meet -his current requirements and restrictions. +each board will have to decide which features are important to them and +what shall be included with their specific board configuration to meet +their current requirements and restrictions.
Please make sure that it is easy to add or remove features from a board configuration, so everybody can make the best use of U-Boot on -his system. +their system.
If a feature is not included, it should not have any residual code bloating the build. @@ -126,7 +126,7 @@ debug is all the more important to many of us.
- All initialization steps shall print some "begin doing this" message before they actually start, and some "done" message when they complete. For example, RAM initialization and size detection may print a "RAM: " before they start,
- and "256 MB\n" when done. The purpose of this is that you can always see
- and "256 MB\n" when done. The purpose of this is that you can always see
%s/MB/MiB/
which initialization step was running if there should be any problem. This is important not only during software development, but also for the service people dealing with broken hardware in the field.@@ -143,8 +143,8 @@ Please always keep in mind that there are at least three different groups of users for U-Boot, with completely different expectations and requirements:
-* The end user of an embedded device just wants to run some application; he
- does not even want to know that U-Boot exists and only rarely interacts with
+* The end user of an embedded device just wants to run some application; they
Please, don't mix singular and plural.
do not even want to know that U-Boot exists and only rarely interacts with it (for example to perform a reset to factory default settings etc.)
- System designers and engineers working on the development of the application
@@ -157,7 +157,7 @@ and requirements: their hardware is easy for them.
- Make it easy to test. Add debug code (but don't re-invent the wheel - use
- existing macros like debug() or debugX()).
- existing macros like debug()).
%s/debug()/log_debug()/
Best regards
Heinrich
Please always keep in mind that U-Boot tries to meet all these different requirements.
On Wed, Jul 13, 2022 at 07:40:03PM +0200, Heinrich Schuchardt wrote:
On 7/11/22 19:14, Tom Rini wrote:
- Remove some missed wiki markup, and escape a "\n" correctly.
- Use gender-neutral language to refer to the user, consistently.
Cc: Claudius Heine ch@denx.de Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- None
doc/develop/designprinciples.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst index 43aeb5dacf5f..e5e12dca79f5 100644 --- a/doc/develop/designprinciples.rst +++ b/doc/develop/designprinciples.rst @@ -28,15 +28,15 @@ millions...
A usable and useful configuration of U-Boot, including a basic interactive command interpreter, support for download over Ethernet -and the capability to program the flash shall fit in no more than 128 !KiB. +and the capability to program the flash shall fit in no more than 128 KiB.
Keep it Fast ^^^^^^^^^^^^
The end user is not interested in running U-Boot. In most embedded -systems he is not even aware that U-Boot exists. The user wants to +systems they are not even aware that U-Boot exists. The user wants to
"The end user" is singular.
First person singular they is normal usage. Talk to me on IRC if you want me to dig up one of the essays on the extensive history of first person singular they :)
run some application code, and that as soon as possible after switching -on his device. +on their device.
It is therefore essential that U-Boot is as fast as possible, especially that it loads and boots the operating system as fast as possible. @@ -63,7 +63,7 @@ Keep it Simple ^^^^^^^^^^^^^^
U-Boot is a boot loader, but it is also a tool used for board -bring-up, for production testing, and for other activities +bring-up, for production testing, and for other activities.
Keep it Portable ^^^^^^^^^^^^^^^^ @@ -96,13 +96,13 @@ Keep it Configurable Section "Keep it Small" already explains about the size restrictions for U-Boot on one side. On the other side, U-Boot is a powerful tool with many, many extremely useful features. The maintainer or user of -each board will have to decide which features are important to him and -what shall be included with his specific board configuration to meet -his current requirements and restrictions. +each board will have to decide which features are important to them and +what shall be included with their specific board configuration to meet +their current requirements and restrictions.
Please make sure that it is easy to add or remove features from a board configuration, so everybody can make the best use of U-Boot on -his system. +their system.
If a feature is not included, it should not have any residual code bloating the build. @@ -126,7 +126,7 @@ debug is all the more important to many of us.
- All initialization steps shall print some "begin doing this" message before they actually start, and some "done" message when they complete. For example, RAM initialization and size detection may print a "RAM: " before they start,
- and "256 MB\n" when done. The purpose of this is that you can always see
- and "256 MB\n" when done. The purpose of this is that you can always see
%s/MB/MiB/
Plenty of memory related notices, even in the docs, use "MB". Lets just put this on the pile to adjust later.
- Use gender-neutral language to refer to the user, consistently. - Reword a few places so that they read more naturally. - Make the long standing practice around "Twilight Time" more clear, hopefully. - Replace a reference to MAKEALL with a reference to CI testing as that's the current requirement.
Cc: Claudius Heine ch@denx.de Cc: Martin Bonner martingreybeard@gmail.com Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com --- Changes in v2: - Further tweak the wording, per Martin --- doc/develop/process.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-)
diff --git a/doc/develop/process.rst b/doc/develop/process.rst index 534da4a2a704..d0c46b58f3e9 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -46,21 +46,22 @@ Twilight Time -------------
Usually patches do not get accepted as they are - the peer review that takes -place will usually require changes and resubmits of the patches before they +place will usually require changes and resubmissions of the patches before they are considered to be ripe for inclusion into mainline.
-Also, the review often happens not immediately after a patch was submitted, +Also the review often happens not immediately after a patch was submitted, but only when somebody (usually the responsible custodian) finds time to do this.
-In the result, the final version of such patches gets submitted after the +The result is that the final version of such patches gets submitted after the merge window has been closed.
It is current practice in U-Boot that such patches are eligible to go into the upcoming release.
-In the result, the release of the ``"-rc1"`` version does not immediately follow -the closing of the Merge Window. +The result is that the release of the ``"-rc1"`` version and formal closing of +the Merge Window does not preclude patches that were already posted from being +merged for the upcoming release.
Stabilization Period -------------------- @@ -75,13 +76,13 @@ Sometimes it is not clear if a patch contains a bug fix or not. For example, changes that remove dead code, unused macros etc. or that contain Coding Style fixes are not strict bug fixes.
-In such situations it is up to the responsible custodian to decide if he -applies such patches even when the Merge Window is closed. +In such situations it is up to the responsible custodian to decide if they +apply such patches even when the Merge Window is closed.
Exception: at the end of the Stabilization Period only strict bug fixes my be applied.
-Sometimes patches miss the the Merge Window slightly - say by few +Sometimes patches miss the Merge Window slightly - say by a few hours or even a day. Patch acceptance is not as critical as a financial transaction, or such. So if there is such a slight delay, the custodian is free to turn a blind eye and accept it anyway. The @@ -110,7 +111,7 @@ Custodians ----------
The Custodians take responsibility for some area of the U-Boot code. The -in-tree ``MAINTAINERS`` files list who is reponsible for which areas. +in-tree ``MAINTAINERS`` files list who is responsible for which areas.
It is their responsibility to pick up patches from the mailing list that fall into their responsibility, and to process these. @@ -155,7 +156,7 @@ like this:
#. Applies cleanly to the source tree
- #. passes a ``MAKEALL`` compile test without creating new warnings + #. Passes :doc:`ci_testing` as this checks for new warnings and other issues.
#. Notes:
@@ -167,7 +168,7 @@ like this:
#. This is well documented in :doc:`designprinciples`.
- #. The custodian decides himself how recent the code must be. It is + #. The custodian decides themselves how recent the code must be. It is acceptable to request patches against the last officially released version of U-Boot or newer. Of course a custodian can also accept patches against older code. @@ -177,7 +178,7 @@ like this:
#. The custodian decides to accept or to reject the patch.
-#. If accepted, the custodian adds the patch to his public git repository and +#. If accepted, the custodian adds the patch to their public git repository and notifies the mailing list. This note should include:
* a short description of the changes @@ -186,15 +187,15 @@ like this:
* suggested tests
- Although the custodian is supposed to perform his own tests - it is a well-known and accepted fact that he needs help from + Although the custodian is supposed to perform their own tests + it is a well-known and accepted fact that they needs help from other developers who - for example - have access to the required hardware or tool chains. The custodian request help for tests and feedback from specific maintainers and U-Boot users.
#. Once tests are passed, some agreed time limit expires, the custodian - requests that the changes in his public git repository be merged into the - main tree. If necessary, the custodian may have to adapt his changes to + requests that the changes in their public git repository be merged into the + main tree. If necessary, the custodian may have to adapt their changes to allow for a clean merge. Todo: define a reasonable time limit. 3 weeks?
On 7/11/22 19:14, Tom Rini wrote:
- Use gender-neutral language to refer to the user, consistently.
- Reword a few places so that they read more naturally.
- Make the long standing practice around "Twilight Time" more clear, hopefully.
- Replace a reference to MAKEALL with a reference to CI testing as that's the current requirement.
Cc: Claudius Heine ch@denx.de Cc: Martin Bonner martingreybeard@gmail.com Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- Further tweak the wording, per Martin
doc/develop/process.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-)
diff --git a/doc/develop/process.rst b/doc/develop/process.rst index 534da4a2a704..d0c46b58f3e9 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -46,21 +46,22 @@ Twilight Time
Usually patches do not get accepted as they are - the peer review that takes -place will usually require changes and resubmits of the patches before they +place will usually require changes and resubmissions of the patches before they are considered to be ripe for inclusion into mainline.
-Also, the review often happens not immediately after a patch was submitted, +Also the review often happens not immediately after a patch was submitted, but only when somebody (usually the responsible custodian) finds time to do this.
-In the result, the final version of such patches gets submitted after the +The result is that the final version of such patches gets submitted after the merge window has been closed.
It is current practice in U-Boot that such patches are eligible to go into the upcoming release.
-In the result, the release of the ``"-rc1"`` version does not immediately follow -the closing of the Merge Window. +The result is that the release of the ``"-rc1"`` version and formal closing of +the Merge Window does not preclude patches that were already posted from being +merged for the upcoming release.
Stabilization Period
@@ -75,13 +76,13 @@ Sometimes it is not clear if a patch contains a bug fix or not. For example, changes that remove dead code, unused macros etc. or that contain Coding Style fixes are not strict bug fixes.
-In such situations it is up to the responsible custodian to decide if he -applies such patches even when the Merge Window is closed. +In such situations it is up to the responsible custodian to decide if they
The custodian is singular.
+apply such patches even when the Merge Window is closed.
Exception: at the end of the Stabilization Period only strict bug fixes my be applied.
-Sometimes patches miss the the Merge Window slightly - say by few +Sometimes patches miss the Merge Window slightly - say by a few hours or even a day. Patch acceptance is not as critical as a financial transaction, or such. So if there is such a slight delay, the custodian is free to turn a blind eye and accept it anyway. The @@ -110,7 +111,7 @@ Custodians
The Custodians take responsibility for some area of the U-Boot code. The -in-tree ``MAINTAINERS`` files list who is reponsible for which areas. +in-tree ``MAINTAINERS`` files list who is responsible for which areas.
It is their responsibility to pick up patches from the mailing list that fall into their responsibility, and to process these. @@ -155,7 +156,7 @@ like this:
#. Applies cleanly to the source tree
- #. passes a ``MAKEALL`` compile test without creating new warnings
- #. Passes :doc:`ci_testing` as this checks for new warnings and other issues.
%s/ci/CI/
#. Notes:
@@ -167,7 +168,7 @@ like this:
#. This is well documented in :doc:`designprinciples`.
- #. The custodian decides himself how recent the code must be. It is
- #. The custodian decides themselves how recent the code must be. It is
The custodian is singular.
acceptable to request patches against the last officially released version of U-Boot or newer. Of course a custodian can also accept patches against older code.@@ -177,7 +178,7 @@ like this:
#. The custodian decides to accept or to reject the patch.
-#. If accepted, the custodian adds the patch to his public git repository and +#. If accepted, the custodian adds the patch to their public git repository and notifies the mailing list. This note should include:
* a short description of the changes@@ -186,15 +187,15 @@ like this:
* suggested tests
- Although the custodian is supposed to perform his own tests
- it is a well-known and accepted fact that he needs help from
- Although the custodian is supposed to perform their own tests
ditto
it is a well-known and accepted fact that they needs help from other developers who - for example - have access to the required hardware or tool chains. The custodian request help for tests and feedback from specific maintainers and U-Boot users.
#. Once tests are passed, some agreed time limit expires, the custodian
- requests that the changes in his public git repository be merged into the
- main tree. If necessary, the custodian may have to adapt his changes to
- requests that the changes in their public git repository be merged into the
- main tree. If necessary, the custodian may have to adapt their changes to
ditto
Best regards
Heinrich
allow for a clean merge. Todo: define a reasonable time limit. 3 weeks?
On Wed, Jul 13, 2022 at 07:43:25PM +0200, Heinrich Schuchardt wrote:
On 7/11/22 19:14, Tom Rini wrote:
[snip]
@@ -155,7 +156,7 @@ like this:
#. Applies cleanly to the source tree
- #. passes a ``MAKEALL`` compile test without creating new warnings
- #. Passes :doc:`ci_testing` as this checks for new warnings and other issues.
%s/ci/CI/
No? This is a reference so it renders using the document title.
The "Workflow of a Custodian" section on the wiki had not been changed in quite some time to reflect how the process has been functioning for some time. First, update some links to point to modern and current sources of information.
Second, and more overarching, reword much of the section. This expands on the expectations of both custodians and developers when it comes to rebasing patches. Rework the final points to be clearer that Custodians are expected to do their best to test the changes and ask for help when needed, as well as that pull requests are expected in a timely manner.
Cc: Claudius Heine ch@denx.de Cc: Martin Bonner martingreybeard@gmail.com Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com --- Changes in v2: - New patch --- doc/develop/process.rst | 88 ++++++++++++++++++++--------------------- 1 file changed, 42 insertions(+), 46 deletions(-)
diff --git a/doc/develop/process.rst b/doc/develop/process.rst index d0c46b58f3e9..56c9d274be71 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -132,16 +132,20 @@ Work flow of a Custodian The normal flow of work in the U-Boot development process will look like this:
-#. A developer submits a patch via e-mail to the u-boot-users mailing list. - U-Boot has adopted the `Linux kernel signoff policy https://groups.google.com/g/fa.linux.kernel/c/TLJIJVA-I6o?pli=1`_, so the submitter must - include a ``Signed-off-by:`` line. +#. A developer submits a patch via e-mail to the u-boot mailing list. In + U-Boot, we make use of the `Developer Certificate of Origin + https://developercertificate.org/`_ that is common in other projects such + as the Linux kernel. Following this and adding a ``Signed-off-by:`` line + that contains the developer's name and email address is required.
-#. Everybody who can is invited to review and test the changes. Reviews should - reply on the mailing list with ``Acked-by`` lines. +#. Everybody who can is invited to review and test the changes. Typically, we + follow the same guidelines as the Linux kernel for `Acked-by + https://www.kernel.org/doc/html/latest/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by`_ + as well as `Reviewed-by + https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes`_ + and similar additional tags.
-#. The responsible custodian - - #. inspects this patch, especially for: +#. The responsible custodian inspects this patch, especially for:
#. :doc:`codingstyle`
@@ -152,50 +156,42 @@ like this: * The patch does not introduce new problems, especially it does not break other boards or architectures
- #. U-Boot Philosophy + #. U-Boot Philosophy, as documented in :doc:`designprinciples`.
- #. Applies cleanly to the source tree + #. Applies cleanly to the source tree. The custodian is expected to put in + a "best effort" if a patch does not apply cleanly, but can be made to apply + still. It is up to the custodian to decide how recent of a commit the + patch must be against. It is acceptable to request patches against the + last officially released version of U-Boot or newer. Of course a + custodian can also accept patches against older code. It can be + difficult to find the correct balance between putting too much work on + the custodian or too much work on an individual submitting a patch when + something does not apply cleanly.
#. Passes :doc:`ci_testing` as this checks for new warnings and other issues.
-#. Notes: - - #. In some cases more than one custodian may be affected or feel responsible. - To avoid duplicated efforts, the custodian who starts processing the - patch should send a short ACK to the mailing list. - - #. We should create some tool to automatically do this. - - #. This is well documented in :doc:`designprinciples`. - - #. The custodian decides themselves how recent the code must be. It is - acceptable to request patches against the last officially released - version of U-Boot or newer. Of course a custodian can also accept - patches against older code. - - #. Commits should show original author in the ``author`` field and include all - sign off/ack lines. - -#. The custodian decides to accept or to reject the patch. - -#. If accepted, the custodian adds the patch to their public git repository and - notifies the mailing list. This note should include: +#. Note that in some cases more than one custodian may feel responsible for a + particular change. To avoid duplicated efforts, the custodian who starts + processing the patch should follow up to the email saying they intend to + pick it up.
- * a short description of the changes +#. Commits must show original author in the ``author`` field and include all of + the ``Signed-off-by``, ``Reviewed-by``, etc, tags that have been submitted.
- * the list of the affected boards / architectures etc. +#. The final decision to accept or reject a patch comes down to the custodian + in question.
- * suggested tests +#. If accepted, the custodian adds the patch to their public git repository. + Ideally, they will also follow up on the mailing list with some notification + that it has been applied. This is not always easy given different custodian + workflows and environments however.
- Although the custodian is supposed to perform their own tests - it is a well-known and accepted fact that they needs help from - other developers who - for example - have access to the required - hardware or tool chains. - The custodian request help for tests and feedback from - specific maintainers and U-Boot users. +#. Although a custodian is supposed to perform their own tests it is a + well-known and accepted fact that they needs help from other developers who + - for example - have access to the required hardware or other relevant + environments. Custodians are expected to ask for assistance with testing + when required.
-#. Once tests are passed, some agreed time limit expires, the custodian - requests that the changes in their public git repository be merged into the - main tree. If necessary, the custodian may have to adapt their changes to - allow for a clean merge. - Todo: define a reasonable time limit. 3 weeks? +#. Custodians are expected to submit a timely pull request of their git + repository to the main repository. It is strongly encouraged that a CI run + have been complete prior to submission, but not required.
On 7/11/22 19:14, Tom Rini wrote:
The "Workflow of a Custodian" section on the wiki had not been changed in quite some time to reflect how the process has been functioning for some time. First, update some links to point to modern and current sources of information.
Second, and more overarching, reword much of the section. This expands on the expectations of both custodians and developers when it comes to rebasing patches. Rework the final points to be clearer that Custodians are expected to do their best to test the changes and ask for help when needed, as well as that pull requests are expected in a timely manner.
Cc: Claudius Heine ch@denx.de Cc: Martin Bonner martingreybeard@gmail.com Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- New patch
doc/develop/process.rst | 88 ++++++++++++++++++++--------------------- 1 file changed, 42 insertions(+), 46 deletions(-)
diff --git a/doc/develop/process.rst b/doc/develop/process.rst index d0c46b58f3e9..56c9d274be71 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -132,16 +132,20 @@ Work flow of a Custodian The normal flow of work in the U-Boot development process will look like this:
-#. A developer submits a patch via e-mail to the u-boot-users mailing list.
- U-Boot has adopted the `Linux kernel signoff policy https://groups.google.com/g/fa.linux.kernel/c/TLJIJVA-I6o?pli=1`_, so the submitter must
- include a ``Signed-off-by:`` line.
+#. A developer submits a patch via e-mail to the u-boot mailing list. In
- U-Boot, we make use of the `Developer Certificate of Origin
- https://developercertificate.org/`_ that is common in other projects such
- as the Linux kernel. Following this and adding a ``Signed-off-by:`` line
- that contains the developer's name and email address is required.
-#. Everybody who can is invited to review and test the changes. Reviews should
- reply on the mailing list with ``Acked-by`` lines.
+#. Everybody who can is invited to review and test the changes. Typically, we
- follow the same guidelines as the Linux kernel for `Acked-by
- https://www.kernel.org/doc/html/latest/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by`_
- as well as `Reviewed-by
- https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes`_
- and similar additional tags.
-#. The responsible custodian
- #. inspects this patch, especially for:
+#. The responsible custodian inspects this patch, especially for:
#. :doc:`codingstyle`@@ -152,50 +156,42 @@ like this: * The patch does not introduce new problems, especially it does not break other boards or architectures
- #. U-Boot Philosophy
- #. U-Boot Philosophy, as documented in :doc:`designprinciples`.
- #. Applies cleanly to the source tree
#. Applies cleanly to the source tree. The custodian is expected to put in
a "best effort" if a patch does not apply cleanly, but can be made to applystill. It is up to the custodian to decide how recent of a commit thepatch must be against. It is acceptable to request patches against thelast officially released version of U-Boot or newer. Of course acustodian can also accept patches against older code. It can bedifficult to find the correct balance between putting too much work onthe custodian or too much work on an individual submitting a patch whensomething does not apply cleanly.#. Passes :doc:`ci_testing` as this checks for new warnings and other issues.
-#. Notes:
- #. In some cases more than one custodian may be affected or feel responsible.
To avoid duplicated efforts, the custodian who starts processing thepatch should send a short ACK to the mailing list.- #. We should create some tool to automatically do this.
- #. This is well documented in :doc:`designprinciples`.
- #. The custodian decides themselves how recent the code must be. It is
acceptable to request patches against the last officially releasedversion of U-Boot or newer. Of course a custodian can also acceptpatches against older code.- #. Commits should show original author in the ``author`` field and include all
sign off/ack lines.-#. The custodian decides to accept or to reject the patch.
-#. If accepted, the custodian adds the patch to their public git repository and
- notifies the mailing list. This note should include:
+#. Note that in some cases more than one custodian may feel responsible for a
- particular change. To avoid duplicated efforts, the custodian who starts
- processing the patch should follow up to the email saying they intend to
- pick it up.
- a short description of the changes
+#. Commits must show original author in the ``author`` field and include all of
- the ``Signed-off-by``, ``Reviewed-by``, etc, tags that have been submitted.
- the list of the affected boards / architectures etc.
+#. The final decision to accept or reject a patch comes down to the custodian
- in question.
- suggested tests
+#. If accepted, the custodian adds the patch to their public git repository.
- Ideally, they will also follow up on the mailing list with some notification
- that it has been applied. This is not always easy given different custodian
- workflows and environments however.
- Although the custodian is supposed to perform their own tests
- it is a well-known and accepted fact that they needs help from
- other developers who - for example - have access to the required
- hardware or tool chains.
- The custodian request help for tests and feedback from
- specific maintainers and U-Boot users.
+#. Although a custodian is supposed to perform their own tests it is a
- well-known and accepted fact that they needs help from other developers who
- for example - have access to the required hardware or other relevant
- environments. Custodians are expected to ask for assistance with testing
- when required.
-#. Once tests are passed, some agreed time limit expires, the custodian
- requests that the changes in their public git repository be merged into the
- main tree. If necessary, the custodian may have to adapt their changes to
- allow for a clean merge.
- Todo: define a reasonable time limit. 3 weeks?
+#. Custodians are expected to submit a timely pull request of their git
- repository to the main repository. It is strongly encouraged that a CI run
- have been complete prior to submission, but not required.
A run is singular.
Best regards
Heinrich
On Wed, Jul 13, 2022 at 07:46:28PM +0200, Heinrich Schuchardt wrote:
On 7/11/22 19:14, Tom Rini wrote:
The "Workflow of a Custodian" section on the wiki had not been changed in quite some time to reflect how the process has been functioning for some time. First, update some links to point to modern and current sources of information.
Second, and more overarching, reword much of the section. This expands on the expectations of both custodians and developers when it comes to rebasing patches. Rework the final points to be clearer that Custodians are expected to do their best to test the changes and ask for help when needed, as well as that pull requests are expected in a timely manner.
Cc: Claudius Heine ch@denx.de Cc: Martin Bonner martingreybeard@gmail.com Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- New patch
[snip]
-#. Once tests are passed, some agreed time limit expires, the custodian
- requests that the changes in their public git repository be merged into the
- main tree. If necessary, the custodian may have to adapt their changes to
- allow for a clean merge.
- Todo: define a reasonable time limit. 3 weeks?
+#. Custodians are expected to submit a timely pull request of their git
- repository to the main repository. It is strongly encouraged that a CI run
- have been complete prior to submission, but not required.
A run is singular.
Oops, thanks.
On // comments: a) I thought I had read recently that they are now accepted. b) Can we stop calling them "C++ style"? They have been legal in standard C for all of this millennium! There are university graduates who were born after // comments became legal in standard C. c) If we don't currently accept them, can we change the style now (see previous point)?
A response along the lines of "this is just moving the wiki into .rst files - we can actually change things separately" would seem entirely reasonable. Martin
On Mon, 11 Jul 2022 at 19:15, Tom Rini trini@konsulko.com wrote:
Move the current CodingStyle wiki page to doc/develop/codingstyle.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich
doc/develop/codingstyle.rst | 255 ++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 8 ++ 2 files changed, 263 insertions(+) create mode 100644 doc/develop/codingstyle.rst
diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst new file mode 100644 index 000000000000..bbeca42e656b --- /dev/null +++ b/doc/develop/codingstyle.rst @@ -0,0 +1,255 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+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 <
https://www.kernel.org/doc/html/latest/process/coding-style.html%3E%60_
- and the `Lindent script <
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scri...
`_.
- The exception for net files to the `multi-line comment
- <
https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
`_
- 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 ``scripts/checkpatch.pl``. For
- more information, read :doc:`checkpatch`. 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 +https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html`_ +documentation 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
+* 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 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. The common.h header (which is going +away at some point) should always be first, followed by other headers in order, +then headers with directories, then local files:
+.. code-block:: C
- #include <common.h>
- #include <bootstage.h>
- #include <dm.h>
- #include <others.h>
- #include <asm/...>
- #include <arm/arch/...>
- #include <dm/device_compat/.h>
- #include <linux/...>
- #include "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 <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 +< https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-do...
`_
+for style.
+Driver model +------------
+When declaring a device, try to use ``struct udevice *dev``, i.e. ``dev`` as the name:
+.. code-block:: C
- struct udevice *dev;
+Use ``ret`` as the return value:
+.. code-block:: C
- struct udevice *dev;
- int ret;
- ret = uclass_first_device_err(UCLASS_ACPI_PMC, &dev);
- if (ret)
return log_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:
+.. code-block:: C
- int dm_pci_find_class(uint find_class, int index, struct udevice
**devp)
- {
- ...
*devp = dev;return 0;- }
+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:
+.. code-block:: C
- struct simple_bus_plat {
u32 base;u32 size;u32 target;- };
- /* Davinci MMC board definitions */
- struct davinci_mmc_priv {
struct davinci_mmc_regs *reg_base; /* Register base address */uint input_clk; /* Input clock to MMC controller */struct gpio_desc cd_gpio; /* Card Detect GPIO */struct gpio_desc wp_gpio; /* Write Protect GPIO */- };
struct rcar_gpio_priv *priv = dev_get_priv(dev);struct pl01x_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:
+.. code-block:: C
- struct udevice *pci_get_controller(struct udevice *dev)
- {
while (device_is_on_pci_bus(dev))dev = dev->parent;return dev;- }
+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, travis, azure) using scripts in the +root of the U-Boot tree. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index fe3564a9fbf4..dde47994c71a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -3,6 +3,14 @@ Develop U-Boot ==============
+General +-------
+.. toctree::
- :maxdepth: 1
- codingstyle
Implementation
-- 2.25.1
On Mon, Jul 11, 2022 at 09:02:47PM +0200, Martin Bonner wrote:
On // comments: a) I thought I had read recently that they are now accepted. b) Can we stop calling them "C++ style"? They have been legal in standard C for all of this millennium! There are university graduates who were born after // comments became legal in standard C. c) If we don't currently accept them, can we change the style now (see previous point)?
A response along the lines of "this is just moving the wiki into .rst files
- we can actually change things separately" would seem entirely reasonable.
Martin
Yeah, I didn't cc you on https://patchwork.ozlabs.org/project/uboot/patch/20220711171439.1657280-3-tr..., sorry
On 7/11/22 19:14, Tom Rini wrote:
Move the current CodingStyle wiki page to doc/develop/codingstyle.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich
doc/develop/codingstyle.rst | 255 ++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 8 ++ 2 files changed, 263 insertions(+) create mode 100644 doc/develop/codingstyle.rst
diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst new file mode 100644 index 000000000000..bbeca42e656b --- /dev/null +++ b/doc/develop/codingstyle.rst @@ -0,0 +1,255 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+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 https://www.kernel.org/doc/html/latest/process/coding-style.html`_
- and the `Lindent script https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/Lindent`_.
- The exception for net files to the `multi-line comment
- https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting`_
- 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 ``scripts/checkpatch.pl``. For
- more information, read :doc:`checkpatch`. 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
This only holds true for C and assembler code. For Python we use 4 spaces per indent.
- Make sure NOT to use DOS ``\r\n`` line feeds
%s/DOS/Windows/ - The documentation is not dedicated to veterans. %s/line feeds/line ends/ - a line feed is always 0x0a.
\r\n are escape codes in C. On a Windows machine these will be rendered as CR CR LF.
Please, use CR LF instead of \r\n.
- 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)
No clue why 'The Right Thing' should be a trademark here. Please, remove this bogus.
+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
Do you mean the extra asterisk?
+documentation is strongly advised. The Linux kernel `kernel-doc +https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html`_ +documentation 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;
%s/error- prone/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 check_member() to verify that your structure is the expected size,
%s/check_member()/the check_member() macro/
+or that particular members appear at the right offset.
+Include files +-------------
+You should follow this ordering in U-Boot. The common.h header (which is going +away at some point) should always be first, followed by other headers in order, +then headers with directories, then local files:
+.. code-block:: C
- #include <common.h>
- #include <bootstage.h>
- #include <dm.h>
- #include <others.h>
- #include <asm/...>
- #include <arm/arch/...>
- #include <dm/device_compat/.h>
- #include <linux/...>
- #include "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 <dm.h> in the C file. Do not include
%s/uses/uses the/
Best regards
Heinrich
+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 +https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation`_ +for style.
+Driver model +------------
+When declaring a device, try to use ``struct udevice *dev``, i.e. ``dev`` as the name:
+.. code-block:: C
- struct udevice *dev;
+Use ``ret`` as the return value:
+.. code-block:: C
- struct udevice *dev;
- int ret;
- ret = uclass_first_device_err(UCLASS_ACPI_PMC, &dev);
- if (ret)
return log_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:
+.. code-block:: C
- int dm_pci_find_class(uint find_class, int index, struct udevice **devp)
- {
- ...
*devp = dev;return 0;- }
+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:
+.. code-block:: C
- struct simple_bus_plat {
u32 base;u32 size;u32 target;- };
- /* Davinci MMC board definitions */
- struct davinci_mmc_priv {
struct davinci_mmc_regs *reg_base; /* Register base address */uint input_clk; /* Input clock to MMC controller */struct gpio_desc cd_gpio; /* Card Detect GPIO */struct gpio_desc wp_gpio; /* Write Protect GPIO */- };
struct rcar_gpio_priv *priv = dev_get_priv(dev);struct pl01x_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:
+.. code-block:: C
- struct udevice *pci_get_controller(struct udevice *dev)
- {
while (device_is_on_pci_bus(dev))dev = dev->parent;return dev;- }
+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, travis, azure) using scripts in the +root of the U-Boot tree. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index fe3564a9fbf4..dde47994c71a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -3,6 +3,14 @@ Develop U-Boot ==============
+General +-------
+.. toctree::
- :maxdepth: 1
- codingstyle
Implementation
On Wed, Jul 13, 2022 at 07:06:56PM +0200, Heinrich Schuchardt wrote:
On 7/11/22 19:14, Tom Rini wrote:
Move the current CodingStyle wiki page to doc/develop/codingstyle.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich
doc/develop/codingstyle.rst | 255 ++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 8 ++ 2 files changed, 263 insertions(+) create mode 100644 doc/develop/codingstyle.rst
diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst new file mode 100644 index 000000000000..bbeca42e656b --- /dev/null +++ b/doc/develop/codingstyle.rst @@ -0,0 +1,255 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+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 https://www.kernel.org/doc/html/latest/process/coding-style.html`_
- and the `Lindent script https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/Lindent`_.
- The exception for net files to the `multi-line comment
- https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting`_
- 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 ``scripts/checkpatch.pl``. For
- more information, read :doc:`checkpatch`. 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
This only holds true for C and assembler code. For Python we use 4 spaces per indent.
- Make sure NOT to use DOS ``\r\n`` line feeds
%s/DOS/Windows/ - The documentation is not dedicated to veterans. %s/line feeds/line ends/ - a line feed is always 0x0a.
\r\n are escape codes in C. On a Windows machine these will be rendered as CR CR LF.
Please, use CR LF instead of \r\n.
- 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)
No clue why 'The Right Thing' should be a trademark here. Please, remove this bogus.
+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
Do you mean the extra asterisk?
+documentation is strongly advised. The Linux kernel `kernel-doc +https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html`_ +documentation 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;
%s/error- prone/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 check_member() to verify that your structure is the expected size,
%s/check_member()/the check_member() macro/
+or that particular members appear at the right offset.
+Include files +-------------
+You should follow this ordering in U-Boot. The common.h header (which is going +away at some point) should always be first, followed by other headers in order, +then headers with directories, then local files:
+.. code-block:: C
- #include <common.h>
- #include <bootstage.h>
- #include <dm.h>
- #include <others.h>
- #include <asm/...>
- #include <arm/arch/...>
- #include <dm/device_compat/.h>
- #include <linux/...>
- #include "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 <dm.h> in the C file. Do not include
%s/uses/uses the/
I'll do another iteration with some of the minor spelling / formatting fixes, but I do not want to start updating the document in the import patch.
On Wed, Jul 13, 2022 at 07:06:56PM +0200, Heinrich Schuchardt wrote:
On 7/11/22 19:14, Tom Rini wrote:
Move the current CodingStyle wiki page to doc/develop/codingstyle.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents.
Cc: Heinrich Schuchardt xypron.glpk@gmx.de Signed-off-by: Tom Rini trini@konsulko.com
Changes in v2:
- Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich
doc/develop/codingstyle.rst | 255 ++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 8 ++ 2 files changed, 263 insertions(+) create mode 100644 doc/develop/codingstyle.rst
diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst new file mode 100644 index 000000000000..bbeca42e656b --- /dev/null +++ b/doc/develop/codingstyle.rst @@ -0,0 +1,255 @@ +.. SPDX-License-Identifier: GPL-2.0+:
+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 https://www.kernel.org/doc/html/latest/process/coding-style.html`_
- and the `Lindent script https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/Lindent`_.
- The exception for net files to the `multi-line comment
- https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting`_
- 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 ``scripts/checkpatch.pl``. For
- more information, read :doc:`checkpatch`. 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
This only holds true for C and assembler code. For Python we use 4 spaces per indent.
- Make sure NOT to use DOS ``\r\n`` line feeds
%s/DOS/Windows/ - The documentation is not dedicated to veterans. %s/line feeds/line ends/ - a line feed is always 0x0a.
\r\n are escape codes in C. On a Windows machine these will be rendered as CR CR LF.
Please, use CR LF instead of \r\n.
- 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)
No clue why 'The Right Thing' should be a trademark here. Please, remove this bogus.
The phrase "The Right Thing (tm)" is I guess an old joke, as it implies it will probably work, but still might mess up from time to time. I'd rather keep it.
+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
Do you mean the extra asterisk?
Yes.
+documentation is strongly advised. The Linux kernel `kernel-doc +https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html`_ +documentation 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;
%s/error- prone/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 check_member() to verify that your structure is the expected size,
%s/check_member()/the check_member() macro/
Since I'm in here anyhow, sure.
+or that particular members appear at the right offset.
+Include files +-------------
+You should follow this ordering in U-Boot. The common.h header (which is going +away at some point) should always be first, followed by other headers in order, +then headers with directories, then local files:
+.. code-block:: C
- #include <common.h>
- #include <bootstage.h>
- #include <dm.h>
- #include <others.h>
- #include <asm/...>
- #include <arm/arch/...>
- #include <dm/device_compat/.h>
- #include <linux/...>
- #include "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 <dm.h> in the C file. Do not include
%s/uses/uses the/
We more consistently say "uses driver model" (9 times) not "uses the driver model" (1 time).
participants (3)
-
Heinrich Schuchardt -
Martin Bonner -
Tom Rini