diff mbox series

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

Message ID 20230823195728.39438-1-heinrich.schuchardt@canonical.com
State Changes Requested
Delegated to: Tom Rini
Headers show
Series [1/1] doc: describe TPL/VPL/SPL boot | expand

Commit Message

Heinrich Schuchardt Aug. 23, 2023, 7:57 p.m. UTC
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@canonical.com>
---
 doc/usage/index.rst    |   1 +
 doc/usage/spl_boot.rst | 309 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 310 insertions(+)
 create mode 100644 doc/usage/spl_boot.rst

Comments

Pali Rohár Aug. 23, 2023, 8:14 p.m. UTC | #1
On Wednesday 23 August 2023 21:57:28 Heinrich Schuchardt wrote:
> +Booting from TPL/SPL
> +====================
> +
> +The main U-Boot binary may be to large to be loaded directly by the Boot ROM.
> +This was the main driver for splitting up U-Boot into multiple boot stages with
> +successively larger binaries.
> +
> +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
> +   Very early init, as tiny as possible. This loads SPL (or VPL if enabled).

This is not truth. SPL loads TPL. Or at least it was about year ago for powerpc plat.

> +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.

SPL initializes NAND then loads TPL from NAND, TPL initialize DDR and then loads U-Boot.
Marek Vasut Aug. 23, 2023, 8:25 p.m. UTC | #2
On 8/23/23 21:57, 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@canonical.com>
> ---
>   doc/usage/index.rst    |   1 +
>   doc/usage/spl_boot.rst | 309 +++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 310 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..05a3bf390d
> --- /dev/null
> +++ b/doc/usage/spl_boot.rst
> @@ -0,0 +1,309 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +Booting from TPL/SPL
> +====================
> +
> +The main U-Boot binary may be to 

too

> large to be loaded directly by the Boot ROM.
> +This was the main driver for splitting up U-Boot into multiple boot stages with
> +successively larger binaries.

Maybe not binaries, but something like "code working set" or so, since 
e.g. ATF BL31 may be smaller than SPL, but it is still loaded and 
started by SPL as PSCI provided e.g. on NXP MX8M.

> +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
> +   Very early init, as tiny as possible. This loads SPL (or VPL if enabled).

Tiny Program Loader ?

> +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.

boot logic can also be in SPL btw

> +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

Launching in caps or lowercase , consistency please.

> +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

fitImages too .

Also mention authentication of next stage.

> +Configuration
> +~~~~~~~~~~~~~
> +
> +Raw images are only supported in SPL if CONFIG_SPL_RAW_IMAGE_SUPPORT=y.

Shouldn't raw (non-fitImage) images be discouraged , as there is no 
protection from bitrot in those ?

> +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
> +six boot methods

Why six ?

I have an idea why, but this should be documented.

> and the sequence in which they are tried. 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.
> +
> +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 (CPGMAC)

Wat's CPGMAC ?

> +    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
> +
> +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
> +
> +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

Why CONFIG_MMC for PCI connected SDMMC controller in SPL ?

> +    * 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>"
> +
> +NAND
> +    This method loads the image from NAND flash. To read from raw NAND the
> +    following configuraton settings are required:

configuration (typo, missing i)

> +    * 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 the Ubi file system

UBI, abbreviation of Unsorted Block Images (iirc)

You also need to discern UBI (as in the FTL) and UBIFS (as in the 
filesystem on top of UBI)


> to read from NAND the following configuration
> +    settings are required:
> +
> +    * CONFIG_SPL_UBI=y of CONFIG_TPL_UBI=y
> +
> +NOR
> +    This method loads the image from NOR flash.
> +    Required configuration settings include:
> +
> +    * CONFIG_SPL_NOR_SUPPORT=y or CONFIG_TPL_NOR_SUPPORT=y
> +
> +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>"
> +
> +OneNAND
> +    This methods loads the image from a OneNAND device. To read from raw OneNAND
> +    the following configuraton settings are required:

configuration, typo

> +    * 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 of CONFIG_TPL_UBI=y

Maybe you should group the boot media in some logical manner, like, 
flash based (NOR, NAND, OneNAND) and block based (SDMMC, SCSI, NVMe...).

> +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.
> +
> +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>"
> +
> +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>
> +
> +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
> +
> +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
> +    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>"
> +
> +USB eth
> +    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_DM_USB_GADGET=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
[...]
Tom Rini Aug. 23, 2023, 8:27 p.m. UTC | #3
On Wed, Aug 23, 2023 at 10:14:00PM +0200, Pali Rohár wrote:
> On Wednesday 23 August 2023 21:57:28 Heinrich Schuchardt wrote:
> > +Booting from TPL/SPL
> > +====================
> > +
> > +The main U-Boot binary may be to large to be loaded directly by the Boot ROM.
> > +This was the main driver for splitting up U-Boot into multiple boot stages with
> > +successively larger binaries.
> > +
> > +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
> > +   Very early init, as tiny as possible. This loads SPL (or VPL if enabled).
> 
> This is not truth. SPL loads TPL. Or at least it was about year ago for powerpc plat.
> 
> > +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.
> 
> SPL initializes NAND then loads TPL from NAND, TPL initialize DDR and then loads U-Boot.

One of the long standing issues here is that PowerPC is different from
everyone else, in terms of terminology here.
Tom Rini Aug. 23, 2023, 8:29 p.m. UTC | #4
On Wed, Aug 23, 2023 at 09:57:28PM +0200, 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@canonical.com>
[snip]
> +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
> +six boot methods and the sequence in which they are tried. 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.

Maybe some words about how some of these methods are SoC / SoC family
specific while others are more high level and so more generally
available.
Marek Vasut Aug. 23, 2023, 8:31 p.m. UTC | #5
On 8/23/23 22:14, Pali Rohár wrote:
> On Wednesday 23 August 2023 21:57:28 Heinrich Schuchardt wrote:
>> +Booting from TPL/SPL
>> +====================
>> +
>> +The main U-Boot binary may be to large to be loaded directly by the Boot ROM.
>> +This was the main driver for splitting up U-Boot into multiple boot stages with
>> +successively larger binaries.
>> +
>> +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
>> +   Very early init, as tiny as possible. This loads SPL (or VPL if enabled).
> 
> This is not truth. SPL loads TPL. Or at least it was about year ago for powerpc plat.

It goes both ways.
- It can be either TPL as the Tiny Program Loader, usually hand-rolled 
in assembly, used e.g. on OneNAND devices to fit into the OneNAND memory 
mapped window and used to load the next stage (SPL) from that OneNAND 
memory into SoC SRAM, and then jump to that next stage.
- It can be SPL that loads TPL as Tertiary Program Loader , apparently 
on PPC.

>> +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.
> 
> SPL initializes NAND then loads TPL from NAND, TPL initialize DDR and then loads U-Boot.

Nope.
Heinrich Schuchardt Aug. 23, 2023, 8:32 p.m. UTC | #6
On 8/23/23 22:14, Pali Rohár wrote:
> On Wednesday 23 August 2023 21:57:28 Heinrich Schuchardt wrote:
>> +Booting from TPL/SPL
>> +====================
>> +
>> +The main U-Boot binary may be to large to be loaded directly by the Boot ROM.
>> +This was the main driver for splitting up U-Boot into multiple boot stages with
>> +successively larger binaries.
>> +
>> +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
>> +   Very early init, as tiny as possible. This loads SPL (or VPL if enabled).
> 
> This is not truth. SPL loads TPL. Or at least it was about year ago for powerpc plat.

Thanks for reviewing.

Cf. doc/arch/sandbox/sandbox.rst

For roc-cc-rk3328_defconfig TPL is much smaller than SPL:

78224 spl/u-boot-spl-nodtb.bin
20744 tpl/u-boot-tpl-nodtb.bin

For P2020RDB-PC_NAND_defconfig SPL is much smaller than TPL:

63624 tpl/u-boot-tpl-nodtb.bin
4096 spl/u-boot-spl-nodtb.bin

If some boards are running TPL->SPL and others SPL->TPL, we really have 
a naming convention issue. We cannot expect any user to understand such 
a confusion.

Looking at the MAINTAINER file it seems that POWERPC should be set to 
orphaned.

Best regards

Heinrich

> 
>> +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.
> 
> SPL initializes NAND then loads TPL from NAND, TPL initialize DDR and then loads U-Boot.
Pali Rohár Aug. 23, 2023, 8:35 p.m. UTC | #7
On Wednesday 23 August 2023 22:32:18 Heinrich Schuchardt wrote:
> Looking at the MAINTAINER file it seems that POWERPC should be set to
> orphaned.

And this is only just because of your fault folks here, as you have been
completely ignoring any my patches for improving this situation here and
finally after more than year of my reminders more of you wrote me
officially that would ignore any changes from me.
So go and complain to somebody else, not me.
Marek Vasut Aug. 23, 2023, 8:46 p.m. UTC | #8
On 8/23/23 22:35, Pali Rohár wrote:
> On Wednesday 23 August 2023 22:32:18 Heinrich Schuchardt wrote:
>> Looking at the MAINTAINER file it seems that POWERPC should be set to
>> orphaned.
> 
> And this is only just because of your fault folks here, as you have been
> completely ignoring any my patches for improving this situation here and
> finally after more than year of my reminders more of you wrote me
> officially that would ignore any changes from me.
> So go and complain to somebody else, not me.

Why not pick up the PPC maintainership yourself ? You are qualified 
enough I think.

There is a whole thread on frustration about getting patches reviewed 
and upstream here too:

https://lore.kernel.org/all/20230816180808.GB2919664@perftesting/
Pali Rohár Aug. 23, 2023, 8:55 p.m. UTC | #9
On Wednesday 23 August 2023 22:46:13 Marek Vasut wrote:
> On 8/23/23 22:35, Pali Rohár wrote:
> > On Wednesday 23 August 2023 22:32:18 Heinrich Schuchardt wrote:
> > > Looking at the MAINTAINER file it seems that POWERPC should be set to
> > > orphaned.
> > 
> > And this is only just because of your fault folks here, as you have been
> > completely ignoring any my patches for improving this situation here and
> > finally after more than year of my reminders more of you wrote me
> > officially that would ignore any changes from me.
> > So go and complain to somebody else, not me.
> 
> Why not pick up the PPC maintainership yourself ? You are qualified enough I
> think.

I'm not sure if you cannot read or understand above written text, but I
will repeat it once again and the last time specially for you: I'm not
going to send any changes, improvements or fixes to any people anymore
who either implicitly or explicitly wrote that will ignore me or my
contributions.

> There is a whole thread on frustration about getting patches reviewed and
> upstream here too:
> 
> https://lore.kernel.org/all/20230816180808.GB2919664@perftesting/
Marek Vasut Aug. 24, 2023, 1:06 p.m. UTC | #10
On 8/23/23 22:55, Pali Rohár wrote:
> On Wednesday 23 August 2023 22:46:13 Marek Vasut wrote:
>> On 8/23/23 22:35, Pali Rohár wrote:
>>> On Wednesday 23 August 2023 22:32:18 Heinrich Schuchardt wrote:
>>>> Looking at the MAINTAINER file it seems that POWERPC should be set to
>>>> orphaned.
>>>
>>> And this is only just because of your fault folks here, as you have been
>>> completely ignoring any my patches for improving this situation here and
>>> finally after more than year of my reminders more of you wrote me
>>> officially that would ignore any changes from me.
>>> So go and complain to somebody else, not me.
>>
>> Why not pick up the PPC maintainership yourself ? You are qualified enough I
>> think.
> 
> I'm not sure if you cannot read or understand above written text, but I
> will repeat it once again and the last time specially for you: I'm not
> going to send any changes, improvements or fixes to any people anymore
> who either implicitly or explicitly wrote that will ignore me or my
> contributions.

So pick up the PPC maintainership, apply the outstanding patches, send a 
PR to Tom and problem with stuck patches is solved. Why not do it this way?

>> There is a whole thread on frustration about getting patches reviewed and
>> upstream here too:
>>
>> https://lore.kernel.org/all/20230816180808.GB2919664@perftesting/
Pali Rohár Aug. 24, 2023, 11:31 p.m. UTC | #11
On Thursday 24 August 2023 15:06:44 Marek Vasut wrote:
> On 8/23/23 22:55, Pali Rohár wrote:
> > On Wednesday 23 August 2023 22:46:13 Marek Vasut wrote:
> > > On 8/23/23 22:35, Pali Rohár wrote:
> > > > On Wednesday 23 August 2023 22:32:18 Heinrich Schuchardt wrote:
> > > > > Looking at the MAINTAINER file it seems that POWERPC should be set to
> > > > > orphaned.
> > > > 
> > > > And this is only just because of your fault folks here, as you have been
> > > > completely ignoring any my patches for improving this situation here and
> > > > finally after more than year of my reminders more of you wrote me
> > > > officially that would ignore any changes from me.
> > > > So go and complain to somebody else, not me.
> > > 
> > > Why not pick up the PPC maintainership yourself ? You are qualified enough I
> > > think.
> > 
> > I'm not sure if you cannot read or understand above written text, but I
> > will repeat it once again and the last time specially for you: I'm not
> > going to send any changes, improvements or fixes to any people anymore
> > who either implicitly or explicitly wrote that will ignore me or my
> > contributions.
> 
> So pick up the PPC maintainership, apply the outstanding patches, send a PR
> to Tom and problem with stuck patches is solved. Why not do it this way?

As you have proved that you are either troll or continuously trying to
make me a fool, you have been added to the black list of idiots. Do not
contact me again.

> > > There is a whole thread on frustration about getting patches reviewed and
> > > upstream here too:
> > > 
> > > https://lore.kernel.org/all/20230816180808.GB2919664@perftesting/
diff mbox series

Patch

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..05a3bf390d
--- /dev/null
+++ b/doc/usage/spl_boot.rst
@@ -0,0 +1,309 @@ 
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Booting from TPL/SPL
+====================
+
+The main U-Boot binary may be to large to be loaded directly by the Boot ROM.
+This was the main driver for splitting up U-Boot into multiple boot stages with
+successively larger binaries.
+
+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
+   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.
+
+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.
+
+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
+six boot methods and the sequence in which they are tried. 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.
+
+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 (CPGMAC)
+    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
+
+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
+
+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>"
+
+NAND
+    This method loads the image from NAND flash. To read from raw NAND the
+    following configuraton 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 the Ubi file system to read from NAND the following configuration
+    settings are required:
+
+    * CONFIG_SPL_UBI=y of CONFIG_TPL_UBI=y
+
+NOR
+    This method loads the image from NOR flash.
+    Required configuration settings include:
+
+    * CONFIG_SPL_NOR_SUPPORT=y or CONFIG_TPL_NOR_SUPPORT=y
+
+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>"
+
+OneNAND
+    This methods loads the image from a OneNAND device. To read from raw OneNAND
+    the following configuraton 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 of CONFIG_TPL_UBI=y
+
+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.
+
+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>"
+
+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>
+
+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
+
+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
+    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>"
+
+USB eth
+    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_DM_USB_GADGET=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