mirror of
https://github.com/u-boot/u-boot.git
synced 2025-04-17 10:24:49 +00:00
ac644df9a4
Update the documentation here to cover the meaning of xPL Signed-off-by: Simon Glass <sjg@chromium.org>
93 lines
3.3 KiB
ReStructuredText
93 lines
3.3 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0+
|
|
|
|
Board Initialisation Flow
|
|
-------------------------
|
|
|
|
This is the intended start-up flow for boards. This should apply for both
|
|
xPL and U-Boot proper (i.e. they both follow the same rules).
|
|
|
|
Note: "xPL" stands for "any Program Loader", including SPL (Secondary
|
|
Program Loader), TPL (Tertiary Program Loader) and VPL (Verifying Program
|
|
Loader). The boot sequence is TPL->VPL->SPL->U-Boot proper
|
|
|
|
At present, xPL mostly uses a separate code path, but the function names
|
|
and roles of each function are the same. Some boards or architectures
|
|
may not conform to this. At least most ARM boards which use
|
|
CONFIG_xPL_FRAMEWORK conform to this.
|
|
|
|
Execution typically starts with an architecture-specific (and possibly
|
|
CPU-specific) start.S file, such as:
|
|
|
|
- arch/arm/cpu/armv7/start.S
|
|
- arch/powerpc/cpu/mpc83xx/start.S
|
|
- arch/mips/cpu/start.S
|
|
|
|
and so on. From there, three functions are called; the purpose and
|
|
limitations of each of these functions are described below.
|
|
|
|
lowlevel_init()
|
|
~~~~~~~~~~~~~~~
|
|
|
|
- purpose: essential init to permit execution to reach board_init_f()
|
|
- no global_data or BSS
|
|
- there is no stack (ARMv7 may have one but it will soon be removed)
|
|
- must not set up SDRAM or use console
|
|
- must only do the bare minimum to allow execution to continue to
|
|
board_init_f()
|
|
- this is almost never needed
|
|
- return normally from this function
|
|
|
|
board_init_f()
|
|
~~~~~~~~~~~~~~
|
|
|
|
- purpose: set up the machine ready for running board_init_r():
|
|
i.e. SDRAM and serial UART
|
|
- global_data is available
|
|
- stack is in SRAM
|
|
- BSS is not available, so you cannot use global/static variables,
|
|
only stack variables and global_data
|
|
|
|
Non-xPL-specific notes:
|
|
|
|
- dram_init() is called to set up DRAM. If already done in xPL this
|
|
can do nothing
|
|
|
|
xPL-specific notes:
|
|
|
|
- you can override the entire board_init_f() function with your own
|
|
version as needed.
|
|
- preloader_console_init() can be called here in extremis
|
|
- should set up SDRAM, and anything needed to make the UART work
|
|
- there is no need to clear BSS, it will be done by crt0.S
|
|
- for specific scenarios on certain architectures an early BSS *can*
|
|
be made available (via CONFIG_SPL_EARLY_BSS by moving the clearing
|
|
of BSS prior to entering board_init_f()) but doing so is discouraged.
|
|
Instead it is strongly recommended to architect any code changes
|
|
or additions such to not depend on the availability of BSS during
|
|
board_init_f() as indicated in other sections of this README to
|
|
maintain compatibility and consistency across the entire code base.
|
|
- must return normally from this function (don't call board_init_r()
|
|
directly)
|
|
|
|
Here the BSS is cleared. For xPL, if CONFIG_xPL_STACK_R is defined, then at
|
|
this point the stack and global_data are relocated to below
|
|
CONFIG_xPL_STACK_R_ADDR. For non-xPL, U-Boot is relocated to run at the top of
|
|
memory.
|
|
|
|
board_init_r()
|
|
~~~~~~~~~~~~~~
|
|
|
|
- purpose: main execution, common code
|
|
- global_data is available
|
|
- SDRAM is available
|
|
- BSS is available, all static/global variables can be used
|
|
- execution eventually continues to main_loop()
|
|
|
|
Non-xPL-specific notes:
|
|
|
|
- U-Boot is relocated to the top of memory and is now running from
|
|
there.
|
|
|
|
xPL-specific notes:
|
|
|
|
- stack is optionally in SDRAM, if CONFIG_xPL_STACK_R is defined
|