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
