From: Simon Glass <simon.glass@canonical.com> Use proper references in the "See Also" section and tighten some of the prose. Co-developed-by: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Simon Glass <simon.glass@canonical.com> --- doc/usage/bls.rst | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/doc/usage/bls.rst b/doc/usage/bls.rst index f96652bd242..128092ae25b 100644 --- a/doc/usage/bls.rst +++ b/doc/usage/bls.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0+ -Boot Loader Specification (BLS) Type #1 Support -================================================ +Boot Loader Specification (BLS) +=============================== U-Boot supports Boot Loader Specification (BLS) Type #1 boot entries as defined in the `Boot Loader Specification`_. @@ -26,7 +26,7 @@ Enable BLS support with:: CONFIG_BOOTMETH_BLS=y -This automatically selects ``CONFIG_PXE_UTILS`` for boot execution. +This automatically selects ``CONFIG_PXE_UTILS`` for booting. BLS Entry Format ---------------- @@ -75,6 +75,11 @@ are not currently supported by U-Boot: * ``uki-url`` - Remote UKI reference * ``profile`` - Multi-profile UKI selector +Fields that support multiple occurrences: + +* ``options`` - All values are concatenated with spaces +* ``initrd`` - All paths are loaded consecutively in memory + .. _Unified Kernel Images: https://uapi-group.org/specifications/specs/unified_kernel_image/ U-Boot Extensions @@ -109,26 +114,22 @@ FITs can be specified in two ways: fit /boot/image.fit The PXE boot infrastructure handles FIT parsing automatically in both cases. - -Multiple Values ---------------- - -Fields that support multiple occurrences: - -* ``options`` - All values are concatenated with spaces -* ``initrd`` - All paths are loaded consecutively in memory +The second option is preferred since the standard 'best match' algorithm +(enabled by ``CONFIG_FIT_BEST_MATCH=y``) should normally used to select the +correct configuration. Usage ----- -BLS boot entries are discovered automatically during standard boot:: +BLS boot entries are discovered automatically by standard boot:: => bootflow scan => bootflow list => bootflow select 0 => bootflow boot -The BLS entry at ``loader/entry.conf`` is discovered as a bootflow. +The BLS entry at ``loader/entry.conf`` on any available media is recognised as +a bootflow. Implementation Notes -------------------- @@ -154,5 +155,7 @@ Current Limitations See Also -------- -* doc/develop/bootstd.rst - Standard boot framework -* doc/usage/cmd/bootflow.rst - Bootflow command reference +* :doc:`/develop/bootstd/index` +* :doc:`/usage/cmd/bootflow` +* `Boot Loader Specification <https://uapi-group.org/specifications/specs/boot_loader_specification/>`_ +* `Unified Kernel Image <https://uapi-group.org/specifications/specs/unified_kernel_image/>`_ -- 2.43.0

From: Simon Glass <simon.glass@canonical.com> The bootstd developer docs are missing a page for the EFI bootmeth. Add one describing the discovery and boot phases for both block and network devices, and link it from the toctree and overview. Co-developed-by: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Simon Glass <simon.glass@canonical.com> --- doc/develop/bootstd/efi.rst | 25 +++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 2 +- doc/develop/uefi/uefi.rst | 3 +++ 4 files changed, 30 insertions(+), 1 deletion(-) create mode 100644 doc/develop/bootstd/efi.rst diff --git a/doc/develop/bootstd/efi.rst b/doc/develop/bootstd/efi.rst new file mode 100644 index 00000000000..abd1ab158aa --- /dev/null +++ b/doc/develop/bootstd/efi.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +EFI Bootmeth +============= + +The EFI bootmeth allows U-Boot to boot an operating system by loading and +running an EFI application from a disk or network device. This follows the +approach used by many Linux distributions to provide a standard boot path. + +When invoked on a block device, ``distro_efi_try_bootflow_files()`` searches for +the architecture-specific EFI binary in ``/EFI/BOOT/`` (e.g. +``bootaa64.efi``). If found, the bootflow is marked as ready. The function also +tries to locate a matching device tree using ``efi_get_distro_fdt_name()``. + +When invoked on a network device, ``distro_efi_read_bootflow_net()`` performs a +DHCP request with PXE vendor-class and architecture identifiers, then retrieves +the EFI binary via TFTP. A device tree is also fetched if available. + +At boot time, ``distro_efi_boot()`` loads the EFI binary into memory (for block +devices) and calls ``efi_bootflow_run()`` to execute it via the EFI loader. + +The compatible string "u-boot,distro-efi" is used for the driver. It is present +if `CONFIG_BOOTMETH_EFI` is enabled. + +See :doc:`/develop/uefi/uefi` for general UEFI implementation details. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index cee792ffc98..bbdcb154724 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -10,6 +10,7 @@ Standard Boot extlinux pxelinux bls + efi pxe_api qfw android diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 34ee42c79e0..60ba247e005 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -440,7 +440,7 @@ Bootmeth drivers are provided for booting from various media: - :doc:`Android <android>` bootflow (boot image v4) - :doc:`BLS <bls>` Boot Loader Specification Type #1 entries - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk - - EFI boot using bootefi from disk + - :doc:`EFI <efi>` boot using bootefi from disk or network - EFI boot using boot manager - :doc:`extlinux / syslinux <extlinux>` boot from a storage device - :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE) diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index ef53c4c35dd..a5131fa2d49 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -64,6 +64,9 @@ Therefore the bootefi command uses the device path of the block device partition or the network adapter and the file name of the most recently loaded PE-COFF file when setting up the loaded image protocol. +See :doc:`/develop/bootstd/efi` for how standard boot discovers and launches +EFI binaries automatically. + Launching a UEFI binary from a FIT image ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 2.43.0

From: Simon Glass <simon.glass@canonical.com> The FEL bootmeth has no documentation at all. Add a developer page describing how it detects FEL-booted sunxi boards via environment variables and executes the pre-loaded script. Also add it to the toctree and overview list. Co-developed-by: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Simon Glass <simon.glass@canonical.com> --- doc/board/allwinner/sunxi.rst | 3 +++ doc/develop/bootstd/fel.rst | 24 ++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 1 + 4 files changed, 29 insertions(+) create mode 100644 doc/develop/bootstd/fel.rst diff --git a/doc/board/allwinner/sunxi.rst b/doc/board/allwinner/sunxi.rst index d0c89b956b1..58e5848519e 100644 --- a/doc/board/allwinner/sunxi.rst +++ b/doc/board/allwinner/sunxi.rst @@ -306,6 +306,9 @@ bootstrap U-Boot by just providing our venerable u-boot-sunxi-with-spl.bin:: Additional binaries like a kernel, an initial ramdisk or a boot script, can also be uploaded via FEL, check the Wiki's `FEL page`_ for more details. +See :doc:`/develop/bootstd/fel` for details on how standard boot handles +FEL-booted boards. + .. _`Arm Trusted Firmware-A`: https://www.trustedfirmware.org/projects/tf-a/ .. _`docs/plat/allwinner.rst`: https://trustedfirmware-a.readthedocs.io/en/latest/plat/allwinner.html .. _`crust`: https://github.com/crust-firmware/crust diff --git a/doc/develop/bootstd/fel.rst b/doc/develop/bootstd/fel.rst new file mode 100644 index 00000000000..10001baeee5 --- /dev/null +++ b/doc/develop/bootstd/fel.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +FEL Bootmeth +============= + +The FEL bootmeth supports booting Allwinner (sunxi) boards that have been +started via the USB FEL protocol. The SPL places a boot script in memory and +records its address before jumping to U-Boot proper. + +This is a global bootmeth: it is not tied to a particular bootdev but is +invoked once during each scan. + +During discovery, ``fel_read_bootflow()`` checks for the ``fel_booted`` and +``fel_scriptaddr`` environment variables. These are set by SPL when the board +is FEL-booted. If either is missing the method is skipped. + +At boot time, ``fel_boot()`` reads the script address from ``fel_scriptaddr`` +and executes it with ``cmd_source_script()``. No files are loaded from a +filesystem; the script was already placed in memory by the FEL loader. + +The compatible string "u-boot,fel-bootmeth" is used for the driver. It is +present if `CONFIG_BOOTMETH_FEL` is enabled. + +See :doc:`/board/allwinner/sunxi` for general Allwinner board information. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 9f958da62de..5cbc020343f 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -12,6 +12,7 @@ Standard Boot bls efi efi_mgr + fel pxe_api qfw android diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 0bcf988a458..f219eb3adf7 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -442,6 +442,7 @@ Bootmeth drivers are provided for booting from various media: - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk - :doc:`EFI <efi>` boot using bootefi from disk or network - :doc:`EFI boot manager <efi_mgr>` using UEFI BootOrder variables + - :doc:`FEL <fel>` boot over USB on Allwinner (sunxi) boards - :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 -- 2.43.0