Merge tag 'efi-2024-10-rc1-3' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request efi-2024-10-rc1-3

Documentation:

* Move out-of-tree building info to HTML
* Enable ReadTheDocs addon management
* Remove FIT documentation that is elsewhere
* Update table of contents for FIT images
* Add description for more boot methods

UEFI:

* Correct finding distro device-path for media devices
* Fix typo in EFI_RT_VOLATILE_STORE description

Other:

* MAINTAINERS: Rename BOOTDEVICE

10 files changed, 227 insertions, 15 deletions

diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst
index f44401eab7d..09632c80ce7 100644
--- a/doc/develop/board_best_practices.rst
+++ b/doc/develop/board_best_practices.rst
@@ -7,7 +7,7 @@ In addition to the regular best practices such as using :doc:`checkpatch` and
 following the :doc:`docstyle` and the :doc:`codingstyle` there are some things
 which are specific to creating a new board port.
 
-* Implement :doc:`bootstd` to ensure that most operating systems will be
+* Implement :doc:`bootstd/index` to ensure that most operating systems will be
   supported by the platform.
 
 * The platform defconfig file must be generated via `make savedefconfig`.
diff --git a/doc/develop/bootstd/cros.rst b/doc/develop/bootstd/cros.rst
new file mode 100644
index 00000000000..85af10588c1
--- /dev/null
+++ b/doc/develop/bootstd/cros.rst
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+ChromiumOS Bootmeth
+===================
+
+ChromiumOS provides a mechanism for booting its Operating System from a block
+device, described
+`here <https://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot/>`_.
+
+U-Boot includes support for reading the associated data structures from the
+device and identifying a bootable ChromiumOS image. This structure includes the
+kernel itself, boot arguments (kernel command line), as well as the x86 setup
+block (for x86 only).
+
+When invoked on a bootdev, this bootmeth searches for kernel partitions with
+the appropriate GUID (Globally Unique Identifier). When found, the information
+is loaded and a bootflow is created.
+
+When the bootflow is booted, the bootmeth reads the kernel and boot arguments.
+It then boots the kernel using zboot (on x86) or bootm (on ARM). The boot
+arguments are adjusted to replace `%U` with the UUID of the selected kernel
+partition. This results in the correct root disk being used, which is the next
+partition after the kernel partition.
+
+For ARM, a :doc:`/usage/fit/index` is used. The `CONFIG_FIT_BEST_MATCH` option
+must be enabled for U-Boot to select the correct devicetree to boot with.
+
+Note that a ChromiumOS image typically has two copies of the Operating System,
+each with its own kernel and root disk. There is no initial ramdisk (initrd).
+This means that this bootmeth typically locates two separate images.
+
+The compatible string "u-boot,cros" is used for the driver. It is present
+if `CONFIG_BOOTMETH_CROS` is enabled.
diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst
new file mode 100644
index 00000000000..bf27dc57aaa
--- /dev/null
+++ b/doc/develop/bootstd/extlinux.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Extlinux Bootmeth
+=================
+
+`Extlinux <https://uapi-group.org/specifications/specs/boot_loader_specification>`_
+(sometimes called syslinux) allows U-Boot to provide a menu of available
+operating systems from which the user can choose.
+
+U-Boot includes a parser for the `extlinux.conf` file. It consists primarily of
+a list of named operating systems along with the kernel, initial ramdisk and
+other settings. The file is stored in the `extlinux/` subdirectory, possibly
+under the `boot/` subdirectory. This list of prefixes (``{"/", "/boot"}`` by
+default) can be selected with the `filename-prefixes` property in the bootstd
+device.
+
+Note that the :doc:`pxelinux` uses the same file format, but in a
+network context.
+
+When invoked on a bootdev, this bootmeth searches for the file and creates a
+bootflow if found.
+
+When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up
+the context, then ``pxe_process()`` to process the file. Depending on the
+contents, this may boot an operating system or provide a list of options to
+the user, perhaps with a timeout.
+
+The compatible string "u-boot,extlinux" is used for the driver. It is present
+if `CONFIG_BOOTMETH_EXTLINUX` is enabled.
diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
new file mode 100644
index 00000000000..9d35b567d55
--- /dev/null
+++ b/doc/develop/bootstd/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Standard Boot
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   extlinux
+   pxelinux
+   qfw
+   cros
+   script
+   sandbox
diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd/overview.rst
index bdda90fae3f..ff3cc48eb64 100644
--- a/doc/develop/bootstd.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0+:
 
-U-Boot Standard Boot
-====================
+Standard Boot Overview
+======================
 
 Introduction
 ------------
@@ -17,7 +17,7 @@ introduces the following concepts:
 For Linux, the distro (Linux distribution, e.g. Debian, Fedora) is responsible
 for creating a bootflow for each kernel combination that it wants to offer.
 These bootflows are stored on media so they can be discovered by U-Boot. This
-feature is typically called `distro boot` (see :doc:`distro`) because it is
+feature is typically called `distro boot` (see :doc:`../distro`) because it is
 a way for distributions to boot on any hardware.
 
 Traditionally U-Boot has relied on scripts to implement this feature. See
@@ -32,7 +32,7 @@ way to boot with U-Boot. The feature is extensible to different Operating
 Systems (such as Chromium OS) and devices (beyond just block and network
 devices). It supports EFI boot and EFI bootmgr too.
 
-Finally, standard boot supports the operation of :doc:`vbe`.
+Finally, standard boot supports the operation of :doc:`../vbe`.
 
 Bootflow
 --------
@@ -410,20 +410,39 @@ You should probably also enable `CONFIG_BOOTSTD_DEFAULTS`, which provides
 several filesystem and network features (if `CONFIG_NET` is enabled) so that
 a good selection of boot options is available.
 
+Some devicetree properties are supported in the bootstd node when
+`CONFIG_BOOTSTD_FULL` is enabled:
+
+    filename-prefixes
+        List of prefixes to use when searching for files on block devices. This
+        defaults to {"/", "/boot/"} if not provided.
+
+    bootdev-order
+        Lists the bootdev ordering to use. Note that the deprecated
+        `boot_targets` environment variable overrides this, if present.
+
+    theme (subnode)
+        Sets the theme to use for menus. See :doc:`/develop/expo`.
 
 Available bootmeth drivers
 --------------------------
 
-Bootmeth drivers are provided for:
+Bootmeth drivers are provided for booting from various media:
 
-   - extlinux / syslinux boot from a disk
-   - extlinux boot from a network (PXE)
-   - U-Boot scripts from disk, network or SPI flash
+   - Android bootflow (boot image v4)
+   - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
    - EFI boot using bootefi from disk
-   - VBE
    - EFI boot using boot manager
-   - Android bootflow (boot image v4)
+   - :doc:`extlinux / syslinux <extlinux>` boot from a storage device
+   - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE)
+   - :doc:`sandbox <sandbox>` used only for testing
+   - :doc:`U-Boot scripts <script>` from disk, network or SPI flash
+   - :doc:`QFW <qfw>`: QEMU firmware interface
+   - :doc:`VBE </develop/vbe>`: Verified Boot for Embedded
 
+Each driver is controlled by a Kconfig option. If no bootmeth driver is
+selected by a compatible string in the devicetree, all available bootmeth
+drivers are bound automatically.
 
 Command interface
 -----------------
@@ -432,16 +451,16 @@ Three commands are available:
 
 `bootdev`
     Allows listing of available bootdevs, selecting a particular one and
-    getting information about it. See :doc:`../usage/cmd/bootdev`
+    getting information about it. See :doc:`/usage/cmd/bootdev`
 
 `bootflow`
     Allows scanning one or more bootdevs for bootflows, listing available
     bootflows, selecting one, obtaining information about it and booting it.
-    See :doc:`../usage/cmd/bootflow`
+    See :doc:`/usage/cmd/bootflow`
 
 `bootmeth`
     Allow listing of available bootmethds and setting the order in which they
-    are tried. See :doc:`../usage/cmd/bootmeth`
+    are tried. See :doc:`/usage/cmd/bootmeth`
 
 .. _BootflowStates:
 
diff --git a/doc/develop/bootstd/pxelinux.rst b/doc/develop/bootstd/pxelinux.rst
new file mode 100644
index 00000000000..c4b7fbb4c9c
--- /dev/null
+++ b/doc/develop/bootstd/pxelinux.rst
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+PXE Bootmeth
+============
+
+PXE (Preboot eXecution-Environment) provides a way to boot an operating system
+over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to
+provide a menu of possible Operating Systems from which the user can choose.
+
+U-Boot includes a parser for the `extlinux.conf` file described
+`here <https://uapi-group.org/specifications/specs/boot_loader_specification>`_.
+It consists primarily of a list of named operating systems along with the
+kernel, initial ramdisk and other settings. The file is retrieved from a network
+server using the TFTP protocol.
+
+When invoked on a bootdev, this bootmeth searches for the file and creates a
+bootflow if found. See
+`PXELINUX <https://wiki.syslinux.org/wiki/index.php?title=PXELINUX>`_ for
+a full description of the search procedure.
+
+When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up
+the context, then ``pxe_process()`` to process the file. Depending on the
+contents, this may boot an Operating System or provide a list of options to the
+user, perhaps with a timeout.
+
+The compatible string "u-boot,extlinux-pxe" is used for the driver. It is
+present if `CONFIG_BOOTMETH_EXTLINUX_PXE` is enabled.
diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst
new file mode 100644
index 00000000000..70086ad1817
--- /dev/null
+++ b/doc/develop/bootstd/qfw.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+QFW Bootmeth
+============
+
+`QEMU <hhttps://www.qemu.org/>`_ is a system emulator which is able to boot
+Operating Systems. QEMU provides specific support for booting an OS image
+provided on the QEMU command line.
+
+When invoked on a bootdev for UCLASS_QFW, this bootmeth reads the kernel
+provided by the QEMU `-kernel` argument, the initial ramdisk provided by
+`-initrd` and the boot arguments (command line) provided by `-append` into
+memory ready for booting.
+
+When the bootflow is booted, the bootmeth tries the `booti` command first, then
+falls back to the `bootz` command. U-Boot's 'control' devicetree is passed
+through to the kernel.
+
+The compatible string "u-boot,qfw-bootmeth" is used for the driver. It is
+present if `CONFIG_QFW` is enabled.
diff --git a/doc/develop/bootstd/sandbox.rst b/doc/develop/bootstd/sandbox.rst
new file mode 100644
index 00000000000..d501518c39a
--- /dev/null
+++ b/doc/develop/bootstd/sandbox.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Sandbox Bootmeth
+================
+
+The sandbox bootmeth is only used for testing. It does not provide any facility
+for booting an OS. While sandbox can do all the processing before the actual
+boot, it is not connected in this bootmeth.
+
+When invoked on a bootdev, this bootmeth pretends to find a bootflow and creates
+the associated structure.
+
+When the bootflow is booted, the bootmeth returns `-ENOTSUPP` indicating that it
+is not supported.
+
+The compatible string "u-boot,sandbox-bootmeth" is used for the driver. It is present
+if `CONFIG_BOOTMETH_SANDBOX` is enabled.
diff --git a/doc/develop/bootstd/script.rst b/doc/develop/bootstd/script.rst
new file mode 100644
index 00000000000..47f3684b86b
--- /dev/null
+++ b/doc/develop/bootstd/script.rst
@@ -0,0 +1,52 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Script Bootmeth
+===============
+
+This bootmeth provides a way to locate and run a script on a block or network
+device. It can also support SPI flash.
+
+For a block device the file is read from the selected partition, which must use
+a supported filesystem. The subdirectory to search in is defined by the bootstd
+list of prefixes (``{"/", "/boot"}`` by default) and can be adjust with the
+`filename-prefixes` property in the bootstd device.
+
+For a network device, the filename is obtained from the `boot_script_dhcp`
+environment variable and the file is read using tftp. It must be in the
+top-level directory of the tftp server.
+
+In either case (file or network), the bootmeth searches for the file and creates
+a bootflow if found. The bootmeth searches for "boot.scr.uimg" first, then
+"boot.scr" if not found.
+
+For SPI flash, a script is read from flash using the offset provided by the
+"script_offset_f" environment variable.
+
+Some attempt is made to identify the Operating System: so far this only detects
+an `Armbian <https://www.armbian.com>`_
+distro. For block devices, if a file called "boot.bmp" exists in the same
+directory then it is used as the bootflow logo.
+
+When the bootflow is booted, the bootmeth sets these environment variables:
+
+    devtype
+        device type (e.g. "usb", "mmc", "ethernet" or "spi_flash")
+
+    devnum
+        device number, corresponding to the device 'sequence' number
+        ``dev_seq(dev)``
+
+    distro_bootpart
+        (block devices only) partition number on the device (numbered from 1)
+
+    prefix
+        prefix used to find the file
+
+    mmc_bootdev
+        device number (same as `devnum`), set for sunxi mmc devices only
+
+The script file must be a FIT or a legacy uImage. It is loaded into memory and
+executed.
+
+The compatible string "u-boot,script" is used for the driver. It is present
+if `CONFIG_BOOTMETH_SCRIPT` is enabled.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index f9c4bf839ee..c0107a783fc 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -29,7 +29,7 @@ Implementation
 
    directories
    bloblist
-   bootstd
+   bootstd/index
    ci_testing
    commands
    config_binding