[PATCH v2 1/1] doc: describe TPL/VPL/SPL boot

[Simon Glass]

Hi Heinrich,

On Wed, 23 Aug 2023 at 15:49, Heinrich Schuchardt
<heinrich.schuchardt at canonical.com> wrote:
>
> This is a stub describing how TPL, VPL, and SPL load the next boot stages
> on a detail level for users.
>
> For sure we will need a few patches on top to catch the whole complexity.
>
> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
> ---
> v2:
>         Mention that PowerPC uses a different naming convention.
>         Group boot devices by type
>         Correct reference to UBI
>         Fix typos
> ---
>  doc/usage/index.rst    |   1 +
>  doc/usage/spl_boot.rst | 321 +++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 322 insertions(+)
>  create mode 100644 doc/usage/spl_boot.rst
>
> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
> index 072db53614..7f0b26cc5a 100644
> --- a/doc/usage/index.rst
> +++ b/doc/usage/index.rst
> @@ -4,6 +4,7 @@ Use U-Boot
>  .. toctree::
>     :maxdepth: 1
>
> +   spl_boot
>     blkmap
>     dfu
>     environment
> diff --git a/doc/usage/spl_boot.rst b/doc/usage/spl_boot.rst
> new file mode 100644
> index 0000000000..7234d0b1b2
> --- /dev/null
> +++ b/doc/usage/spl_boot.rst
> @@ -0,0 +1,321 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +Booting from TPL/SPL
> +====================
> +
> +The main U-Boot binary may be too large to be loaded directly by the Boot ROM.
> +This was the own driver for splitting up U-Boot into multiple boot stages.

s/own/original/ ?

> +
> +U-Boot typically goes through the following boot phases where TPL, VPL, and SPL
> +are optional. While many boards use SPL only few use TPL.
> +
> +TPL
> +   Tiny program loader. Very early init, as tiny as possible. This loads SPL
> +   (or VPL if enabled).

Oh I thought that was tertiary! It helps us if we need yes another one
later...but if we go with Tiny, let's fix it everywhere.

> +
> +VPL

verifying program loader

> +   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 the logic to load an
> +   operating system, e.g. via UEFI.
> +
> +The naming convention on the PowerPC architecture deviates from the other
> +archtitectures. Here the boot sequence is SPL->TPL->U-Boot.
> +
> +Only main U-Boot has a command line interface.
> +
> +Further usages for U-Boot SPL comprise:
> +
> +* launching BL31 of ARM Trusted Firmware which invokes U-Boot as BL33
> +* launching EDK II
> +* launching Linux
> +* launching RISC-V OpenSBI which invokes main U-Boot
> +
> +Target binaries
> +---------------
> +
> +Binaries loaded by SPL/TPL can be:
> +
> +* raw binaries where the entry address equals the start address. This is the
> +  only binary format supported by TPL.
> +* :doc:`FIT <fit/index>` images
> +* legacy U-Boot images
> +
> +Configuration
> +~~~~~~~~~~~~~
> +
> +Raw images are only supported in SPL if CONFIG_SPL_RAW_IMAGE_SUPPORT=y.

I think it is better to drop the =y stuff on these.

> +
> +CONFIG_SPL_FIT=y and CONFIG_SPL_LOAD_FIT=y are needed to load FIT images.
> +
> +CONFIG_SPL_LEGACY_IMAGE_FORMAT=y is needed to load legacy U-Boot images.
> +CONFIG_SPL_LEGACY_IMAGE_CRC_CHECK=y enables checking the CRC32 of legacy U-Boot
> +images.
> +
> +Image load methods
> +------------------
> +
> +The image boot methods available for a board must be defined in two places:
> +
> +The board code implements a function board_boot_order() enumerating up to
> +five boot methods and the sequence in which they are tried. (The maximum
> +number of boot methods is currently hard coded as variable spl_boot_list[]).
> +If there is only one boot method function, spl_boot_device() may be implemented
> +instead.
> +
> +The configuration controls which of these boot methods are actually available.
> +
> +Loading from block devices
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +MMC1, MMC2, MMC2_2
> +    These methods read an image from SD card or eMMC. The first digit after
> +    'MMC' indicates the device number. Required configuration settings include:
> +
> +    * CONFIG_SPL_MMC=y or CONFIG_TPL_MMC=y
> +
> +    To use a PCI connected MMC controller you need to additionally specify:
> +
> +    * CONFIG_SPL_PCI=y
> +
> +    * CONFIG_SPL_PCI_PNP=y
> +
> +    * CONFIG_MMC=y
> +
> +    * CONFIG_MMC_PCI=y
> +
> +    * CONFIG_MMC_SDHCI=y
> +
> +    To load from a file system use:
> +
> +    * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y
> +
> +    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>"
> +
> +NVMe
> +    This methods load the image from an NVMe drive.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_PCI=y
> +
> +    * CONFIG_SPL_PCI_PNP=y
> +
> +    * CONFIG_SPL_NVME=y
> +
> +    * CONFIG_SPL_NVME_PCI=y
> +
> +    * CONFIG_SPL_NVME_BOOT_DEVICE (number of the NVMe device)
> +
> +    * CONFIG_SYS_NVME_BOOT_PARTITION (partition to read from)
> +
> +    To load from a file system use:
> +
> +    * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y
> +
> +    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>"
> +
> +SATA
> +    This method reads an image from a SATA drive.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_SATA=y or CONFIG_TPL_SATA=y
> +
> +    To use a PCIe connecte SATA controller you additionally need:
> +
> +    * CONFIG_SPL_PCI=y
> +
> +    * CONFIG_SPL_SATA=y
> +
> +    * CONFIG_SPL_AHCI_PCI=y
> +
> +    * CONFIG_SPL_PCI_PNP=y
> +
> +    To load from a file system use:
> +
> +    * CONFIG_SPL_FS_FAT=y
> +
> +    * CONFIG_SYS_SATA_FAT_BOOT_PARTITION=<partition number>
> +
> +    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>"
> +
> +USB
> +    The USB method loads an image from a USB block device.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_USB_HOST=y
> +
> +    * CONFIG_SPL_USB_STORAGE=y
> +
> +    To use a PCI connected USB 3.0 controller you additionally need:
> +
> +    * CONFIG_SPL_FS_FAT=y
> +
> +    * CONFIG_SPL_PCI=y
> +
> +    * CONFIG_SPL_PCI_PNP=y
> +
> +    * CONFIG_USB=y
> +
> +    * CONFIG_USB_XHCI_HCD=y
> +
> +    * CONFIG_USB_XHCI_PCI=y
> +
> +    To load from a file system use:
> +
> +    * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y
> +
> +    * CONFIG_SYS_USB_FAT_BOOT_PARTITION=<partition number>
> +
> +    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>"
> +
> +Loading from flash devices
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +NAND
> +    This method loads the image from NAND flash. To read from raw NAND the
> +    following configuration settings are required:
> +
> +    * CONFIG_SPL_NAND_SUPPORT=y or CONFIG_TPL_NAND_SUPPORT=y
> +
> +    If CONFIG_SPL_NAND_RAW_ONLY=y only raw images can be loaded.
> +
> +    For using UBI (Unsorted Block Images) volumes to read from NAND the
> +    following configuration settings are required:
> +
> +    * CONFIG_SPL_UBI=y or CONFIG_TPL_UBI=y
> +
> +    The UBI volume to read can either be specified
> +
> +    * by name using CONFIG_SPL_UBI_LOAD_BY_VOLNAME or
> +
> +    * by number using CONFIG_SPL_UBI_LOAD_MONITOR_ID.
> +
> +NOR
> +    This method loads the image from NOR flash.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_NOR_SUPPORT=y or CONFIG_TPL_NOR_SUPPORT=y
> +
> +OneNAND
> +    This methods loads the image from a OneNAND device. To read from raw OneNAND
> +    the following configuration settings are required:
> +
> +    * CONFIG_SPL_ONENAND_SUPPORT=y or CONFIG_TPL_ONENAND_SUPPORT=y
> +
> +    For using the Ubi file system to read from NAND the following configuration
> +    settings are required:
> +
> +    * CONFIG_SPL_UBI=y or CONFIG_TPL_UBI=y
> +
> +SPI
> +    This method loads an image form SPI NOR flash.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_DM_SPI=y
> +
> +    * CONFIG_SPL_SPI_FLASH=y
> +
> +    * CONFIG_SPI_LOAD=y or CONFIG_TPL_SPI_LOAD=y
> +
> +
> +Sunxi SPI
> +    This method which is specific to Allwinner SoCs loads an image form SPI NOR
> +    flash. Required configuration settings include:
> +
> +    * CONFIG_SPL_SPI_SUNXI=y
> +
> +Loading from other devices
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +BOOTROM
> +    The binary is loaded by the boot ROM.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_BOOTROM_SUPPORT=y or CONFIG_TPL_BOOTROM_SUPPORT=y
> +
> +DFU
> +    :doc:`Device Firmware Upgrade <dfu>` is used to load the binary into RAM.
> +    Required configuration settings include:
> +
> +    * CONFIG_DFU=y
> +
> +    * CONFIG_SPL_RAM_SUPPORT=y or CONFIG TPL_RAM_SUPPORT=y
> +
> +Ethernet
> +    This method loads an image over Ethernet. The BOOTP protocol is used to find
> +    a TFTP server and binary name. The binary is downloaded via the TFTP
> +    protocol. Required configuration settings include:
> +
> +    * CONFIG_SPL_NET=y or CONFIG_TPL_NET=y
> +
> +    * CONFIG_SPL_ETH_DEVICE=y or CONFIG_DM_USB_GADGET=y
> +
> +FEL
> +    This method does not actually load an image for U-Boot.
> +    FEL is a routine contained in the boot ROM of Allwinner SoCs which serves
> +    for the initial programming or recovery via USB
> +
> +RAM
> +    This method uses an image preloaded into RAM.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_RAM_SUPPORT=y or CONFIG_TPL_RAM_SUPPORT=y
> +
> +    * CONFIG_RAM_DEVICE=y
> +
> +Sandbox file
> +    On the sandbox this method loads an image from the host file system.
> +
> +Sandbox image
> +    On the sandbox this method loads an image from the host file system.
> +
> +SEMIHOSTING

Should that be in lower case?

> +    When running in an ARM or RISC-V virtual machine the semihosting method can
> +    be used to load an image from the host file system.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_SEMIHOSTING=y
> +
> +    * CONFIG_SPL_SEMIHOSTING_FALLBACK=y
> +
> +    * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME=<path to file>
> +
> +UART
> +    This method loads an image via the Y-Modem protocol from the UART.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_YMODEM_SUPPORT=y or CONFIG_TPL_YMODEM_SUPPORT=y
> +
> +USB SDP
> +    This method loads the image using the Serial Download Protocol as
> +    implemented by the boot ROM of the i.MX family of SoCs.
> +
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_SERIAL=y
> +
> +    * CONFIG_SPL_USB_SDP_SUPPORT=y or CONFIG_TPL_USB_SDP_SUPPORT
> +
> +VBE Simple
> +    This method is used by the VPL stage to extract the next stage image from
> +    the loaded image.
> +
> +    Required configuration settings include:
> +
> +    * CONFIG_VPL=y
> +
> +    * CONFIG_SPL_BOOTMETH_VBE_SIMPLE_FW=y or CONFIG_TPL_BOOTMETH_VBE_SIMPLE_FW=y
> +
> +XIP
> +    This method executes an image in place.
> +
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_XIP_SUPPORT
> --
> 2.40.1
>

It is great to see this written down in one place.

It is quite a mess. I hope we can simplify this in the future.

Regards,
Simon