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.g...@gmx.de> > > Signed-off-by: Tom Rini <tr...@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
signature.asc
Description: PGP signature