[Concept,2/5] doc: bls: Add developer documentation for BLS bootmeth
Commit Message
From: Simon Glass <simon.glass@canonical.com>
The bootstd developer docs cover each bootmethod but are missing one for
BLS. Add a new page describing the implementation: discovery via
bls_read_bootflow(), zero-copy enum-based parsing in bls_parse_entry(),
and the PXE-label conversion used for booting. Also list BLS in the
available-bootmeth-drivers table in the overview.
Co-developed-by: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Simon Glass <simon.glass@canonical.com>
---
doc/develop/bootstd/bls.rst | 34 ++++++++++++++++++++++++++++++++
doc/develop/bootstd/index.rst | 1 +
doc/develop/bootstd/overview.rst | 1 +
3 files changed, 36 insertions(+)
create mode 100644 doc/develop/bootstd/bls.rst
new file mode 100644
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+BLS Bootmeth
+============
+
+The `Boot Loader Specification`_ (BLS) bootmeth allows U-Boot to boot
+operating systems configured with BLS Type #1 entries. This format is used by
+Fedora, RHEL and other distributions.
+
+.. _Boot Loader Specification: https://uapi-group.org/specifications/specs/boot_loader_specification/
+
+The entry file ``loader/entry.conf`` is searched for under each boot prefix
+(``{"/", "/boot"}`` by default). These prefixes can be selected with the
+`filename-prefixes` property in the bootstd device.
+
+When invoked on a bootdev, the ``bls_read_bootflow()`` function searches for the
+entry file, reads it and passes it to ``bls_parse_entry()`` which processes
+the key-value pairs into a ``struct bls_entry``. The parser uses an enum-based
+token lookup to map field names, with most values pointing directly into the
+bootflow buffer (zero-copy). Only ``options`` is allocated separately since
+multiple occurrences are concatenated. Unknown fields are silently ignored for
+forward compatibility. Images (kernel, initrd, devicetree) are registered in the
+bootflow with ``bootflow_img_add()`` during discovery but not loaded until boot.
+
+At boot time, ``bls_to_pxe_label()`` converts the bootflow into a PXE label
+structure, mapping BLS fields to their PXE equivalents (``title`` to menu,
+``options`` to append, etc.). The existing ``pxe_load_files()`` and
+``pxe_boot()`` infrastructure then handles file loading and execution, including
+FIT support.
+
+The compatible string "u-boot,boot-loader-specification" is used for the driver.
+It is present if `CONFIG_BOOTMETH_BLS` is enabled.
+
+See :doc:`/usage/bls` for usage details and field reference.
@@ -9,6 +9,7 @@ Standard Boot
overview
extlinux
pxelinux
+ bls
pxe_api
qfw
android
@@ -438,6 +438,7 @@ Available bootmeth drivers
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
- EFI boot using boot manager