Re: [PATCH 2/7] doc: Migrate DesignPrinciples wiki page to Sphinx
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 > > Signed-off-by: Tom Rini > > --- > > 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 ..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
Re: [PATCH 2/7] doc: Migrate DesignPrinciples wiki page to Sphinx
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 Signed-off-by: Tom Rini --- 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 ..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
[PATCH 2/7] doc: Migrate DesignPrinciples wiki page to Sphinx
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 Signed-off-by: Tom Rini --- 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 ..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
