3 files changed, 72 insertions, 17 deletions
diff --git a/doc/arch/sandbox.rst b/doc/arch/sandbox.rst
index e1119492b4..bc670b98b7 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 d32ec49022..fe3564a9fb 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 011fd42537..aec7b562fa 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'