Merge patch series "Tidy up use of 'SPL' and CONFIG_SPL_BUILD"

Simon Glass <[email protected]> says:

When the SPL build-phase was first created it was designed to solve a
particular problem (the need to init SDRAM so that U-Boot proper could
be loaded). It has since expanded to become an important part of U-Boot,
with three phases now present: TPL, VPL and SPL

Due to this history, the term 'SPL' is used to mean both a particular
phase (the one before U-Boot proper) and all the non-proper phases.
This has become confusing.

For a similar reason CONFIG_SPL_BUILD is set to 'y' for all 'SPL'
phases, not just SPL. So code which can only be compiled for actual SPL,
for example, must use something like this:

   #if defined(CONFIG_SPL_BUILD) && !defined(CONFIG_TPL_BUILD)

In Makefiles we have similar issues. SPL_ has been used as a variable
which expands to either SPL_ or nothing, to chose between options like
CONFIG_BLK and CONFIG_SPL_BLK. When TPL appeared, a new SPL_TPL variable
was created which expanded to 'SPL_', 'TPL_' or nothing. Later it was
updated to support 'VPL_' as well.

This series starts a change in terminology and usage to resolve the
above issues:

- The word 'xPL' is used instead of 'SPL' to mean a non-proper build
- A new CONFIG_XPL_BUILD define indicates that the current build is an
  'xPL' build
- The existing CONFIG_SPL_BUILD is changed to mean SPL; it is not now
  defined for TPL and VPL phases
- The existing SPL_ Makefile variable is renamed to SPL_
- The existing SPL_TPL Makefile variable is renamed to PHASE_

It should be noted that xpl_phase() can generally be used instead of
the above CONFIGs without a code-space or run-time penalty.

This series does not attempt to convert all of U-Boot to use this new
terminology but it makes a start. In particular, renaming spl.h and
common/spl seems like a bridge too far at this point.

The series is fully bisectable. It has also been checked to ensure there
are no code-size changes on any commit.

1 files changed, 93 insertions, 0 deletions

diff --git a/doc/develop/init.rst b/doc/develop/init.rst
new file mode 100644
index 00000000000..ce985781bb4
--- /dev/null
+++ b/doc/develop/init.rst
@@ -0,0 +1,93 @@
+.. 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