Merge branch 'master' of git://www.denx.de/git/u-boot-imx

[u-boot] / README

diff --git a/README b/README
index 322697bdd2a7e4c1587ce71b8687f97c029e7913..676f41e7f09fc1f87e3d4e6a2ef0cbe5df8ea87f 100644 (file)
--- 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.
+
+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-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
+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-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
+               CONFIG_SPL_STACK_R_ADDR points into SDRAM
+       - 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:
 ----------------------