[PATCH v3 1/1] doc: describe TPL/VPL/SPL boot
Heinrich Schuchardt
xypron.glpk at gmx.de
Sat Aug 26 15:28:44 CEST 2023
On 8/26/23 12:42, Paul Barker wrote:
> On 26/08/2023 10:13, Heinrich Schuchardt 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>
>> ---
>> v3:
>> Call TPL Tertiary Program Loader, VPL Verifying Program Loader
>> Put Power PC flow into an info box to stick out
>> Add link to Falcon Mode
>> Fix typos
>> 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 | 323 +++++++++++++++++++++++++++++++++++++++++
>> 2 files changed, 324 insertions(+)
>> create mode 100644 doc/usage/spl_boot.rst
>>
>> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
>> index 3326ec82ff..f45a7f5502 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..ad6bf0ab69
>> --- /dev/null
>> +++ b/doc/usage/spl_boot.rst
>> @@ -0,0 +1,323 @@
>> +.. 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 original driver for splitting up U-Boot into multiple boot stages.
>> +
>> +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
>> + Tertiary Program Loader. Very early init, as tiny as possible. This loads SPL
>> + (or VPL if enabled).
>> +
>> +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.
>
> I'd fold the bullet points below (BL31, EDK II, Falcon mode & OpenSBI
> loading) into this description to improve the flow of the document.
Thank you for reviewing.
I think when expanding this documenting with future patches we should
have a subsection for each of these boot flows with a diagram and
description. The list above I would prefer to restrict to the U-Boot
components.
>
>> +
>> +U-Boot
>> + U-Boot proper, containing the command line and the logic to load an
>> + operating system, e.g. via UEFI.
>
> Change after the first comma to "this is the only stage containing the
> command line...", then the extra line below the following note saying
> this can be dropped.
ok
>
>> +
>> +.. note::
>> +
>> + 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, e.g. :doc:`Falcon Mode' <../develop/falcon>`
>> +* 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.
>> +
>> +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
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> I'd say "raw flash devices" to make the distinction from flash block
> devices (e.g. SSD/NVMe) clear.
ok
Best regards
Heinrich
>
>> +
>> +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
>> + 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
>
> My comments above are minor style suggestions so whether or not they're
> changed:
>
> Reviewed-by: Paul Barker <paul.barker.ct at bp.renesas.com>
>
> Thanks,
> Paul
More information about the U-Boot
mailing list