[PATCH v2 13/13] doc: bootstd: describe the BLS bootmeth

Every other bootmeth has a page under doc/develop/bootstd/; add one for
BLS and list it in the index and in the overview's table of drivers.

Besides what the bootmeth does, record the two things a reader is most
likely to trip over: how paths inside an entry are resolved when $BOOT is
a directory rather than a partition, and which parts of the spec's entry
ordering and boot counting are not implemented yet.

Signed-off-by: Alexey Charkov <[email protected]>
---
 doc/develop/bootstd/bls.rst      | 56 ++++++++++++++++++++++++++++++++++++++++
 doc/develop/bootstd/index.rst    |  1 +
 doc/develop/bootstd/overview.rst |  1 +
 3 files changed, 58 insertions(+)

diff --git a/doc/develop/bootstd/bls.rst b/doc/develop/bootstd/bls.rst
new file mode 100644
index 000000000000..52e691b70165
--- /dev/null
+++ b/doc/develop/bootstd/bls.rst
@@ -0,0 +1,56 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+BLS Bootmeth
+============
+
+The `Boot Loader Specification
+<https://uapi-group.org/specifications/specs/boot_loader_specification>`_ (BLS)
+describes a drop-in directory of boot entries, so that a distribution can add
+and remove kernels without rewriting a central configuration file. Type #1
+entries are plain text files, one per bootable kernel; this bootmeth implements
+those. Type #2 entries are EFI binaries and are out of scope here, since the
+EFI bootmeth already covers them.
+
+Entries live in ``<prefix>loader/entries/*.conf``, where ``<prefix>`` comes from
+the bootstd list of prefixes (``{"/", "/boot/"}`` by default, settable with the
+`filename-prefixes` property on the bootstd device). systemd's
+``kernel-install`` writes them in this layout when ``loader=bls``.
+
+The format is close enough to `extlinux.conf` that U-Boot reuses the same
+parser. Two extra keywords are recognised for it: ``title`` (the human-readable
+entry name, equivalent to extlinux's ``menu label``) and ``options`` (the kernel
+command line, equivalent to ``append``). Some spec-envisaged keys such as
+``version``, ``machine-id``, ``sort-key`` and ``architecture`` are not yet
+implemented and are skipped.
+
+Paths inside an entry are used as written: the spec has them "always relative
+to the root directory of the partition they are referenced from", which is
+what the bootmeth sees whichever prefix the entry itself was found under.
+systemd's ``90-loaderentry.install`` agrees, since it strips the mount point
+from the entry directory and so keeps the ``/boot`` component when $BOOT is
+not a mount point of its own.
+
+Entry selection
+---------------
+
+Only the highest-sorting entry on a partition is returned, because the bootstd
+framework currently allows one bootflow per (bootmeth, partition) pair.
+
+Ordering is by filename alone, which suits the common case of distros encoding
+the kernel version into the filename. The spec envisages more than this, none
+of which is implemented yet:
+
+* entries should be ordered by ``sort-key`` first and ``version`` second,
+  falling back to the filename only when those tie;
+
+* an entry may carry a boot counter as a ``+TRIES_LEFT[-TRIES_DONE]`` suffix on
+  its filename, to be decremented on each attempt and skipped once it reaches
+  zero. For now that suffix is left intact in the entry name and otherwise
+  ignored.
+
+When the bootflow is booted, the bootmeth re-parses the entry it read during
+the scan and hands the resulting label to ``label_boot()``, the same code path
+extlinux uses.
+
+The compatible string "u-boot,bls" is used for the driver. It is present if
+``CONFIG_BOOTMETH_BLS`` is enabled.
diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
index ec74fc2fb9d7..9271b5eef14e 100644
--- a/doc/develop/bootstd/index.rst
+++ b/doc/develop/bootstd/index.rst
@@ -9,6 +9,7 @@ Standard Boot
    overview
    extlinux
    pxelinux
+   bls
    qfw
    android
    cros
diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
index ec9fafa0fa05..eb0f68d9bb87 100644
--- a/doc/develop/bootstd/overview.rst
+++ b/doc/develop/bootstd/overview.rst
@@ -445,6 +445,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 from a disk
    - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
    - EFI boot using bootefi from disk
    - EFI boot using boot manager

-- 
2.54.0