[PATCH 2/4] doc: Migrate DesignPrinciples wiki page to sphinx

[Heinrich Schuchardt]

On 6/27/22 19:17, 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.
>
> Signed-off-by: Tom Rini <trini at konsulko.com>
> ---
>   doc/develop/designprinciples.rst | 197 +++++++++++++++++++++++++++++++
>   doc/develop/index.rst            |   1 +
>   2 files changed, 198 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..79694db77604
> --- /dev/null
> +++ b/doc/develop/designprinciples.rst
> @@ -0,0 +1,197 @@
> +.. 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 -

%s/!KiB/KiB/g

Are these numbers still true? U-Boot typically is larger than 512 KiB.

> +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...

%s/\.\.\././

> +
> +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.

%s/!//

This number seems to be outdated. Typically U-Boot fits into 1 MiB.

> +
> +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

Separate bullet points by blank lines, please.

> +* 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

%s/  / /

> +  devices after using them  - otherwise nasty things may happen when you try to

%s/  / /

> +  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

%/$/./

I cannot see how this sentence is related to the heading. The sentence
is repeated below.

> +
> +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

%s/initializations/initalization/

> +subroutines or inline macros. These functions represent some

Is extensive use of inline macros good coding style?

> +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.

%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.

Please, add blank lines between bullet points.

> +* All initialization steps shall print some "begin doing this" message before
> +  they actually start, and some "done" message when they complete. For example,

Do we really want unnecessary output? This conflicts with improving boot
time.

Isn't using log_debug() preferred here?

> +  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

%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.
> +* U-Boot should be debuggable with simple JTAG or BDM equipment.  It shall use

%s/  / /

> +  a simple, single-threaded execution model.  Avoid any magic, which could

%s/  / /

> +  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.)

Missing empty lines.

> +* 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

%s/and whatever//

> +  short, they want as many features supported as possible. And some more.

Avoid non-information:
%s/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.

%s/$/\n/

Best regards

Heinrich

> +* 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
>   --------------