jcs.org
"Das U-Boot" Source Tree
1.. SPDX-License-Identifier: GPL-2.0+
2
3Board Initialisation Flow
4-------------------------
5
6This is the intended start-up flow for boards. This should apply for both
7xPL and U-Boot proper (i.e. they both follow the same rules).
8
9Note: "xPL" stands for "any Program Loader", including SPL (Secondary
10Program Loader), TPL (Tertiary Program Loader) and VPL (Verifying Program
11Loader). The boot sequence is TPL->VPL->SPL->U-Boot proper
12
13At present, xPL mostly uses a separate code path, but the function names
14and roles of each function are the same. Some boards or architectures
15may not conform to this. At least most ARM boards which use
16CONFIG_xPL_FRAMEWORK conform to this.
17
18Execution typically starts with an architecture-specific (and possibly
19CPU-specific) start.S file, such as:
20
21- arch/arm/cpu/armv7/start.S
22- arch/powerpc/cpu/mpc83xx/start.S
23- arch/mips/cpu/start.S
24
25and so on. From there, three functions are called; the purpose and
26limitations of each of these functions are described below.
27
28lowlevel_init()
29~~~~~~~~~~~~~~~
30
31- purpose: essential init to permit execution to reach board_init_f()
32- no global_data or BSS
33- there is no stack (ARMv7 may have one but it will soon be removed)
34- must not set up SDRAM or use console
35- must only do the bare minimum to allow execution to continue to
36 board_init_f()
37- this is almost never needed
38- return normally from this function
39
40board_init_f()
41~~~~~~~~~~~~~~
42
43- purpose: set up the machine ready for running board_init_r():
44 i.e. SDRAM and serial UART
45- global_data is available
46- stack is in SRAM
47- BSS is not available, so you cannot use global/static variables,
48 only stack variables and global_data
49
50Non-xPL-specific notes:
51
52 - dram_init() is called to set up DRAM. If already done in xPL this
53 can do nothing
54
55xPL-specific notes:
56
57 - you can override the entire board_init_f() function with your own
58 version as needed.
59 - preloader_console_init() can be called here in extremis
60 - should set up SDRAM, and anything needed to make the UART work
61 - there is no need to clear BSS, it will be done by crt0.S
62 - for specific scenarios on certain architectures an early BSS *can*
63 be made available (via CONFIG_SPL_EARLY_BSS by moving the clearing
64 of BSS prior to entering board_init_f()) but doing so is discouraged.
65 Instead it is strongly recommended to architect any code changes
66 or additions such to not depend on the availability of BSS during
67 board_init_f() as indicated in other sections of this README to
68 maintain compatibility and consistency across the entire code base.
69 - must return normally from this function (don't call board_init_r()
70 directly)
71
72Here the BSS is cleared. For xPL, if CONFIG_xPL_STACK_R is defined, then at
73this point the stack and global_data are relocated to below
74CONFIG_xPL_STACK_R_ADDR. For non-xPL, U-Boot is relocated to run at the top of
75memory.
76
77board_init_r()
78~~~~~~~~~~~~~~
79
80 - purpose: main execution, common code
81 - global_data is available
82 - SDRAM is available
83 - BSS is available, all static/global variables can be used
84 - execution eventually continues to main_loop()
85
86Non-xPL-specific notes:
87
88 - U-Boot is relocated to the top of memory and is now running from
89 there.
90
91xPL-specific notes:
92
93 - stack is optionally in SDRAM, if CONFIG_xPL_STACK_R is defined