[Concept,5/5] doc: bootstd: Add developer documentation for FEL bootmeth
Commit Message
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
@@ -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
new file mode 100644
@@ -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.
@@ -12,6 +12,7 @@ Standard Boot
bls
efi
efi_mgr
+ fel
pxe_api
qfw
android
@@ -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