Merge patch series "Tidy up use of 'SPL' and CONFIG_SPL_BUILD"WIP/11Oct2024

Simon Glass <sjg@chromium.org> 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, 5 insertions, 95 deletions

diff --git a/README b/README
index d73042406b6..067c1ee2b64 100644
--- a/README
+++ b/README
@@ -133,96 +133,6 @@ run some of U-Boot's tests.
 
 See doc/arch/sandbox/sandbox.rst 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).
-
-Note: "SPL" stands for "Secondary Program Loader," which is explained in
-more detail later in this file.
-
-At present, SPL 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_SPL_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-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
-	- 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 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_SYS_FSL_HAS_CCI400
-
-		Defined For SoC that has cache coherent interconnect
-		CCN-400
-
-		CONFIG_SYS_FSL_HAS_CCN504
-
-		Defined for SoC that has cache coherent interconnect CCN-504
-
 The following options need to be configured:
 
 - CPU Type:	Define exactly one, e.g. CONFIG_MPC85XX.
@@ -1508,13 +1418,13 @@ Low Level (hardware related) configuration options:
 		This only takes effect if the memory commands are activated
 		globally (CONFIG_CMD_MEMORY).
 
-- CONFIG_SPL_BUILD
+- CONFIG_XPL_BUILD
 		Set when the currently running compilation is for an artifact
 		that will end up in one of the 'xPL' builds, i.e. SPL, TPL or
 		VPL. Code that needs phase-specific behaviour can check this,
-		or (where possible) use spl_phase() instead.
+		or (where possible) use xpl_phase() instead.
 
-		Note that CONFIG_SPL_BUILD *is* always defined when either
+		Note that CONFIG_XPL_BUILD *is* always defined when either
 		of CONFIG_TPL_BUILD / CONFIG_VPL_BUILD is defined. This can be
 		counter-intuitive and should perhaps be changed.
 
@@ -1522,13 +1432,13 @@ Low Level (hardware related) configuration options:
 		Set when the currently running compilation is for an artifact
 		that will end up in the TPL build (as opposed to SPL, VPL or
 		U-Boot proper). Code that needs phase-specific behaviour can
-		check this, or (where possible) use spl_phase() instead.
+		check this, or (where possible) use xpl_phase() instead.
 
 - CONFIG_VPL_BUILD
 		Set when the currently running compilation is for an artifact
 		that will end up in the VPL build (as opposed to the SPL, TPL
 		or U-Boot proper). Code that needs phase-specific behaviour can
-		check this, or (where possible) use spl_phase() instead.
+		check this, or (where possible) use xpl_phase() instead.
 
 - CONFIG_ARCH_MAP_SYSMEM
 		Generally U-Boot (and in particular the md command) uses