Merge branch '2022-05-02-add-verifying-program-loader'

To quote the author:

U-Boot provides a verified-boot feature based around FIT, but there is
no standard way of implementing it for a board. At present the various
required pieces must be built up separately, to produce a working
implementation. In particular, there is no built-in support for selecting
A/B boot or recovery mode.

This series introduces VPL, a verified program loader phase for U-Boot.
Its purpose is to run the verified-boot process and decide which SPL
binary should be run. It is critical that this decision happens before
SPL runs, since SPL sets up SDRAM and we need to be able to update the
SDRAM-init code in the field.

Adding VPL into the boot flow provides a standard place to implement
verified boot. This series includes the phase itself, some useful Kconfig
options and a sandbox_vpl build for sandbox. No verfied-boot support is
provided in this series.

Most of the patches in this series are fixes and improvements to docs and
various Kconfig conditions for SPL.

3 files changed, 72 insertions, 17 deletions

diff --git a/doc/arch/sandbox.rst b/doc/arch/sandbox.rst
index e1119492b45..bc670b98b7e 100644
--- a/doc/arch/sandbox.rst
+++ b/doc/arch/sandbox.rst
@@ -420,6 +420,19 @@ state_setprop() which does this automatically and avoids running out of
 space. See existing code for examples.
 
 
+VPL (Verifying Program Loader)
+------------------------------
+
+Sandbox provides an example build of vpl called `sandbox_vpl`. This can be run
+using::
+
+   /path/to/sandbox_vpl/tpl/u-boot-tpl -D
+
+It starts up TPL (first-stage init), then VPL, then runs SPL and finally U-Boot
+proper, following the normal flow for a verified boot. At present, no
+verification is actually implemented.
+
+
 Debugging the init sequence
 ---------------------------
 
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index d32ec490221..fe3564a9fbf 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -25,6 +25,7 @@ Implementation
    menus
    printf
    smbios
+   spl
    uefi/index
    version
 
diff --git a/doc/README.SPL b/doc/develop/spl.rst
index 011fd42537a..aec7b562faa 100644
--- a/doc/README.SPL
+++ b/doc/develop/spl.rst
@@ -20,19 +20,19 @@ u-boot-spl.map.
 A config option named CONFIG_SPL_BUILD is enabled by Kconfig for SPL.
 Source files can therefore be compiled for SPL with different settings.
 
-For example:
+For example::
 
-ifeq ($(CONFIG_SPL_BUILD),y)
-obj-y += board_spl.o
-else
-obj-y += board.o
-endif
+   ifeq ($(CONFIG_SPL_BUILD),y)
+   obj-y += board_spl.o
+   else
+   obj-y += board.o
+   endif
 
-obj-$(CONFIG_SPL_BUILD) += foo.o
+   obj-$(CONFIG_SPL_BUILD) += foo.o
 
-#ifdef CONFIG_SPL_BUILD
-	foo();
-#endif
+   #ifdef CONFIG_SPL_BUILD
+           foo();
+   #endif
 
 
 The building of SPL images can be enabled by CONFIG_SPL option in Kconfig.
@@ -66,16 +66,57 @@ CONFIG_SPL_SPI_LOAD (drivers/mtd/spi/spi_spl_load.o)
 CONFIG_SPL_RAM_DEVICE (common/spl/spl.c)
 CONFIG_SPL_WATCHDOG (drivers/watchdog/libwatchdog.o)
 
+Adding SPL-specific code
+------------------------
+
+To check whether a feature is enabled, use CONFIG_IS_ENABLED()::
+
+  if (CONFIG_IS_ENABLED(CLK))
+      ...
+
+This checks CONFIG_CLK for the main build, CONFIG_SPL_CLK for the SPL build,
+CONFIG_TPL_CLK for the TPL build, etc.
+
+U-Boot Phases
+-------------
+
+U-Boot boots through the following phases:
+
+TPL
+   Very early init, as tiny as possible. This loads SPL (or VPL if enabled).
+
+VPL
+   Optional verification step, which can select one of several SPL binaries,
+   if A/B verified boot is enabled. Implementation of the VPL logic is
+   work-in-progress. For now it just boots into SPL.
+
+SPL
+   Secondary program loader. Sets up SDRAM and loads U-Boot proper. It may also
+   load other firmware components.
+
+U-Boot
+   U-Boot proper, containing the command line and boot logic.
+
+
+Checking the boot phase
+-----------------------
+
+Use `spl_phase()` to find the current U-Boot phase, e.g. `PHASE_SPL`. You can
+also find the previous and next phase and get the phase name.
+
+
 Device tree
 -----------
 The U-Boot device tree is filtered by the fdtgrep tools during the build
 process to generate a much smaller device tree used in SPL (spl/u-boot-spl.dtb)
 with:
+
 - the mandatory nodes (/alias, /chosen, /config)
 - the nodes with one pre-relocation property:
   'u-boot,dm-pre-reloc' or 'u-boot,dm-spl'
 
 fdtgrep is also used to remove:
+
 - the properties defined in CONFIG_OF_SPL_REMOVE_PROPS
 - all the pre-relocation properties
   ('u-boot,dm-pre-reloc', 'u-boot,dm-spl' and 'u-boot,dm-tpl')
@@ -98,14 +139,14 @@ stack usage at various points in run sequence of SPL.  The -fstack-usage option
 to gcc will produce '.su' files (such as arch/arm/cpu/armv7/syslib.su) that
 will give stack usage information and cflow can construct program flow.
 
-Must have gcc 4.6 or later, which supports -fstack-usage
+Must have gcc 4.6 or later, which supports -fstack-usage:
 
-1) Build normally
-2) Perform the following shell command to generate a list of C files used in
-SPL:
-$ find spl -name '*.su' | sed -e 's:^spl/::' -e 's:[.]su$:.c:' > used-spl.list
-3) Execute cflow:
-$ cflow --main=board_init_r `cat used-spl.list` 2>&1 | $PAGER
+#. Build normally
+#. Perform the following shell command to generate a list of C files used in
+   SPL:
+#. `find spl -name '*.su' | sed -e 's:^spl/::' -e 's:[.]su$:.c:' > used-spl.list`
+#. Execute cflow:
+   `$ cflow --main=board_init_r $(cat used-spl.list) 2>&1 | $PAGER`
 
 cflow will spit out a number of warnings as it does not parse
 the config files and picks functions based on #ifdef.  Parsing the '.i'