Re: [PATCH 2/4] doc: Migrate DesignPrinciples wiki page to sphinx
On Sat, Jul 09, 2022 at 08:37:12AM +0200, Heinrich Schuchardt wrote: > 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 > > --- > > 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 ..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 I fixed that in a follow-up. > Are these numbers still true? U-Boot typically is larger than 512 KiB. More true than not still, yes. And then very much so something to keep in mind for SPL. It's more true that NOR isn't common than less than 512KiB isn't true. [snip] > > +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. It's also verbatim what the original page says. It's repetition for emphasis. -- Tom signature.asc Description: PGP signature
Re: [PATCH 2/4] doc: Migrate DesignPrinciples wiki page to sphinx
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 --- 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 ..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 drive
Re: [PATCH 2/4] doc: Migrate DesignPrinciples wiki page to sphinx
Hi Tom, On 2022-06-27 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 --- 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 ..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 - +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 he is -> they are +run some application code, and that as soon as possible after switching +on his device. his -> their + +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 . is missing at the end of the sentence + +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 wil
Re: [PATCH 2/4] doc: Migrate DesignPrinciples wiki page to sphinx
On Mon, 27 Jun 2022 at 11:18, 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 > --- > doc/develop/designprinciples.rst | 197 +++ > doc/develop/index.rst| 1 + > 2 files changed, 198 insertions(+) > create mode 100644 doc/develop/designprinciples.rst Reviewed-by: Simon Glass
[PATCH 2/4] 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. Signed-off-by: Tom Rini --- 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 ..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 - +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 cur
