[Concept,12/12] doc: bootstd: Document multi-entry bootflow scanning
Commit Message
From: Simon Glass <sjg@chromium.org>
Update the overview to show the entry column in the iteration table
and describe how BOOTMETHF_MULTI bootmeths produce multiple bootflows
per partition, including the entry_name shown in bootflow info.
Update the extlinux doc to explain that each label becomes a separate
bootflow, that include directives are processed during scanning, and
that pxe_boot_entry() boots a specific entry directly.
Update the BLS doc to mention multi-entry support for entries
directory scanning.
Signed-off-by: Simon Glass <sjg@chromium.org>
---
doc/develop/bootstd/bls.rst | 4 ++++
doc/develop/bootstd/extlinux.rst | 12 ++++++-----
doc/develop/bootstd/overview.rst | 37 +++++++++++++++++++++-----------
3 files changed, 36 insertions(+), 17 deletions(-)
@@ -13,6 +13,10 @@ 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.
+The bootmeth sets ``BOOTMETHF_MULTI`` so that each ``.conf`` file in the
+entries directory produces a separate bootflow. The ``bflow->entry`` field
+selects which file to use during scanning.
+
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
@@ -18,12 +18,14 @@ Note that the :doc:`pxelinux` uses the same file format, but in a
network context.
When invoked on a bootdev, this bootmeth searches for the file and creates a
-bootflow if found.
+bootflow for each label defined in the configuration. Since an extlinux config
+can contain several labels (each pointing to a different kernel), the bootmeth
+sets the ``BOOTMETHF_MULTI`` flag so that the iterator produces one bootflow per
+label. The ``bflow->entry`` field selects which label to use. Include directives
+are processed during scanning so labels from included files are also discovered.
-When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up
-the context, then ``pxe_process_str()`` to process the file. Depending on the
-contents, this may boot an operating system or provide a list of options to
-the user, perhaps with a timeout.
+When the bootflow is booted, ``pxe_boot_entry()`` parses the config, walks to
+the selected label and boots it directly.
The compatible string "u-boot,extlinux" is used for the driver. It is present
if `CONFIG_BOOTMETH_EXTLINUX` is enabled.
@@ -654,19 +654,32 @@ sets it to zero and increments the second counter. You can think of all the
counters together as a number with three digits which increment in order, with
the least-sigificant digit on the right, counting like this:
- ======== ======= =======
- bootdev part method
- ======== ======= =======
- 0 0 0
- 0 0 1
- 0 0 2
- 0 1 0
- 0 1 1
- 0 1 2
- 1 0 0
- 1 0 1
+ ======== ======= ======= =======
+ bootdev part method entry
+ ======== ======= ======= =======
+ 0 0 0 0
+ 0 0 0 1
+ 0 0 0 2
+ 0 0 1 0
+ 0 0 2 0
+ 0 1 0 0
+ 0 1 0 1
+ 0 1 0 2
+ 0 1 1 0
+ 0 1 2 0
+ 1 0 0 0
+ 1 0 0 1
...
- ======== ======= =======
+ ======== ======= ======= =======
+
+If a bootmeth sets the ``BOOTMETHF_MULTI`` flag, it can produce multiple
+bootflows from a single partition. Each bootflow is called an `entry`. In the
+table above, the `entry` column shows how the iterator tries entry 0, 1, 2, ...
+for such a bootmeth before moving to the next method. For bootmeths without
+``BOOTMETHF_MULTI``, the entry is always 0 and the column can be ignored. The
+entry index is passed to the bootmeth via ``bflow->entry``. Each bootflow also
+stores an ``entry_name`` (e.g. the extlinux label or BLS title) which is shown
+in ``bootflow info`` alongside the entry number.
The maximum value for `method` is `num_methods - 1` so when it exceeds that, it
goes back to 0 and the next `part` is considered. The maximum value for that is