path: root/README
diff options
authorSimon Glass <>2015-03-03 08:03:00 -0700
committerTom Rini <>2015-03-04 14:55:04 -0500
commitdb910353a126d84fe8dff7a694ea792f50fcfb6a (patch)
tree0cca558754e992284820fbc240690c13d0a00cb0 /README
parentbdfb34167f73afc7e04d52499fc14bc1cd33fec0 (diff)
arm: spl: Allow board_init_r() to run with a larger stack
At present SPL uses a single stack, either CONFIG_SPL_STACK or CONFIG_SYS_INIT_SP_ADDR. Since some SPL features (such as MMC and environment) require a lot of stack, some boards set CONFIG_SPL_STACK to point into SDRAM. They then set up SDRAM very early, before board_init_f(), so that the larger stack can be used. This is an abuse of lowlevel_init(). That function should only be used for essential start-up code which cannot be delayed. An example of a valid use is when only part of the SPL code is visible/executable, and the SoC must be set up so that board_init_f() can be reached. It should not be used for SDRAM init, console init, etc. Add a CONFIG_SPL_STACK_R option, which allows the stack to be moved to a new address before board_init_r() is called in SPL. The expected SPL flow (for CONFIG_SPL_FRAMEWORK) is documented in the README. Signed-off-by: Simon Glass <> For version 1: Acked-by: Albert ARIBAUD <> Reviewed-by: Stefan Roese <> Tested-by: Bo Shen <> Acked-by: Bo Shen <> Acked-by: Heiko Schocher <> Tested-by: Heiko Schocher <> Signed-off-by: Tom Rini <>
Diffstat (limited to 'README')
1 files changed, 69 insertions, 0 deletions
diff --git a/README b/README
index febefb50c2..3547ead07a 100644
--- a/README
+++ b/README
@@ -273,6 +273,75 @@ run some of U-Boot's tests.
See board/sandbox/README.sandbox for more details.
+Board Initialisation Flow:
+This is the intended start-up flow for boards. This should apply for both
+SPL and U-Boot proper (i.e. they both follow the same rules). At present SPL
+mostly uses a separate code path, but the funtion 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_SPL_FRAMEWORK conform to this.
+Execution starts with start.S with three functions called during init after
+that. The purpose and limitations of each is described below.
+ - 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
+ - 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-SPL-specific notes:
+ - dram_init() is called to set up DRAM. If already done in SPL this
+ can do nothing
+ SPL-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
+ - these is no need to clear BSS, it will be done by crt0.S
+ - must return normally from this function (don't call board_init_r()
+ directly)
+Here the BSS is cleared. For SPL, if CONFIG_SPL_STACK_R is defined, then at
+this point the stack and global_data are relocated to below
+CONFIG_SPL_STACK_R_ADDR. For non-SPL, U-Boot is relocated to run at the top of
+ - 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-SPL-specific notes:
+ - U-Boot is relocated to the top of memory and is now running from
+ there.
+ SPL-specific notes:
+ - stack is optionally in SDRAM, if CONFIG_SPL_STACK_R is defined and
+ - preloader_console_init() can be called here - typically this is
+ done by defining CONFIG_SPL_BOARD_INIT and then supplying a
+ spl_board_init() function containing this call
+ - loads U-Boot or (in falcon mode) Linux
Configuration Options:
OpenPOWER on IntegriCloud