[PATCH 2/7] doc: Migrate DesignPrinciples wiki page to Sphinx

Wed Jul 13 19:52:14 CEST 2022

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 at gmx.de>
> > Signed-off-by: Tom Rini <trini at 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".

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20220713/c8176e4c/attachment.sig>