[Concept,4/5] doc: bootstd: Add docs for EFI boot-manager bootmeth
Commit Message
From: Simon Glass <simon.glass@canonical.com>
The EFI boot-manager bootmeth is listed in the overview but has no
dedicated page. Add one describing its global nature, BootOrder-based
discovery and delegation to efi_bootmgr_run() for booting.
Co-developed-by: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Simon Glass <simon.glass@canonical.com>
---
doc/develop/bootstd/efi_mgr.rst | 29 +++++++++++++++++++++++++++++
doc/develop/bootstd/index.rst | 1 +
doc/develop/bootstd/overview.rst | 2 +-
doc/develop/uefi/uefi.rst | 3 +++
4 files changed, 34 insertions(+), 1 deletion(-)
create mode 100644 doc/develop/bootstd/efi_mgr.rst
new file mode 100644
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+EFI Boot Manager Bootmeth
+=========================
+
+The EFI boot-manager bootmeth delegates boot-device selection to the UEFI boot
+manager. Rather than scanning filesystems for a specific binary, it checks
+whether a ``BootOrder`` EFI variable exists and, if so, marks the bootflow as
+ready.
+
+This is a global bootmeth: it is not tied to a particular bootdev but is
+invoked once during each scan. The ``BOOTMETHF_GLOBAL`` flag is set at bind
+time, and the global priority is ``BOOTDEVP_6_NET_BASE`` so that it runs just
+before very slow devices, giving filesystem-based methods a chance to complete
+first.
+
+During discovery, ``efi_mgr_read_bootflow()`` initialises the EFI object list
+and looks up the ``BootOrder`` variable. If the variable is present the
+bootflow is marked ready; otherwise the method is skipped.
+
+At boot time, ``efi_mgr_boot()`` calls ``efi_bootmgr_run()`` which walks the
+``BootOrder`` list and launches the first viable EFI application. No file
+loading is done by the bootmeth itself.
+
+The compatible string "u-boot,efi-bootmgr" is used for the driver. It is
+present if `CONFIG_BOOTMETH_EFI_BOOTMGR` is enabled.
+
+See :doc:`/develop/uefi/uefi` for general UEFI implementation details and
+:doc:`/usage/cmd/eficonfig` for configuring boot entries.
@@ -11,6 +11,7 @@ Standard Boot
pxelinux
bls
efi
+ efi_mgr
pxe_api
qfw
android
@@ -441,7 +441,7 @@ Bootmeth drivers are provided for booting from various media:
- :doc:`BLS <bls>` Boot Loader Specification Type #1 entries
- :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
- :doc:`EFI <efi>` boot using bootefi from disk or network
- - EFI boot using boot manager
+ - :doc:`EFI boot manager <efi_mgr>` using UEFI BootOrder variables
- :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
@@ -666,6 +666,9 @@ UEFI variables. Booting according to these variables is possible via::
bootefi bootmgr [fdt address]
+See :doc:`/develop/bootstd/efi_mgr` for how standard boot integrates the
+EFI boot manager.
+
As of U-Boot v2020.10 UEFI variables cannot be set at runtime. The U-Boot
command 'efidebug' can be used to set the variables.