Re: [docs] [PATCH] ref-manual: add uboot-extlinux-config class documentation

Hi Antonin,

On 8/4/26 5:24 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Add documentation for the uboot-extlinux-config class and the variables
> it defines, including how to enable it and how to customize the output
> extlinux.conf file.
> 
> [YOCTO #15629]
> 
> Signed-off-by: Antonin Godard <[email protected]>
> ---
>   documentation/ref-manual/classes.rst   |  55 ++++++++++++++
>   documentation/ref-manual/variables.rst | 135 +++++++++++++++++++++++++++++++++
>   2 files changed, 190 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 98dff1bac..9fbfc0b2f 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -3470,6 +3470,61 @@ possible.
>   See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
>   information.
>   
> +.. _ref-classes-uboot-extlinux-config:
> +
> +``uboot-extlinux-config``
> +=========================
> +
> +The :ref:`ref-classes-uboot-extlinux-config` class provides support for
> +generating an ``extlinux.conf`` file part of the `Boot Loader Specification
> +<https://uapi-group.org/specifications/specs/boot_loader_specification/>`__.
> +

I think this is incorrect. We don't actually implement the Boot Loader 
Specification in U-Boot and I'm not even sure it is related to extlinux 
at all (cannot check right now as I'm traveling).

In U-Boot, please have a look at the "Boot Configuration Files" section 
in doc/develop/distro.rst.

Specifically:

"""
The standard format for boot configuration files is that of 
extlinux.conf, as
handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This 
format is
not formally standardized and documented in a single location. However, 
other
implementations do document it and we attempt to be as compatible as 
possible.

* The UAPI Group Specifications `Boot Loader Specification`_

* The Syslinux Project documents both `PXELINUX`_ and `SYSLINUX`_ files 
and is
   the originator of the format.

That said, we have some differences to these documents, namely:
[...]
"""

I vaguely recall BSL v2 being discussed on the U-Boot mailing list in 
the past few months.

> +The class can be inherited in a `U-Boot <https://u-boot-project.org/>`__ recipe
> +with::
> +
> +   inherit uboot-extlinux-config
> +
> +However, the class functionality is disabled by default. To enable it, set the
> +:term:`UBOOT_EXTLINUX` variable to "1" from the U-Boot recipe or from a
> +``bbappend`` file::

This is likely more a task for the distro/machine conf file to take care 
of, though what you said is not incorrect :)

> +
> +   UBOOT_EXTLINUX = "1"
> +
> +In addition to :term:`UBOOT_EXTLINUX`, the :term:`UBOOT_EXTLINUX_ROOT` variable
> +must be set to the ``root=`` parameter of the `Linux kernel command-line
> +<https://docs.kernel.org/admin-guide/kernel-parameters.html>`__. For example,
> +the following would set this value to the second partition of MMC block device
> +0::
> +
> +   UBOOT_EXTLINUX_ROOT = "root=/dev/mmcblk0p2"
> +

I think that may be a mistake. It isn't always necessary (e.g. when 
using an initramfs). In any case, it reflects the logic we currently 
have in OE-Core so that's fine.

> +After building the U-Boot recipe, an ``extlinux.conf`` is generated and placed
> +in the deployment directory (:term:`DEPLOY_DIR_IMAGE`):
> +
> +.. code-block:: text
> +
> +   tmp/deploy/images/<MACHINE>/extlinux.conf
> +
> +This file can be customized using the variables beginning with
> +``UBOOT_EXTLINUX_`` in the :doc:`Variables Glossary </ref-manual/variables>`
> +section of the Yocto Project Reference Manual.
> +
> +.. note::
> +
> +   Multiple ``LABELS`` can be specified through the
> +   :term:`UBOOT_EXTLINUX_LABELS` variable (i.e. multiple boot entries).
> +   Override-style assignment should then be used to specify label-specific
> +   properties. See the definition of :term:`UBOOT_EXTLINUX_LABELS` for more
> +   information.
> +> +.. tip::
> +
> +   When using the :ref:`bootloader <ref-manual/kickstart:Command: bootloader>`
> +   command with WIC, you should explicitly configure the ``.wks.in`` file to use
> +   the ``extlinux.conf`` file generated by this class with
> +   ``--configfile="${DEPLOY_DIR_IMAGE}/extlinux.conf"``. Otherwise it generates
> +   a default ``extlinux.conf`` file without taking this class into account.
> +

Uh? We use extlinux.conf in meta-rockchip, as well as this WIC command 
and we don't have this set so not sure this is true?

>   .. _ref-classes-uboot-sign:
>   
>   ``uboot-sign``
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index e75f42afe..ccd864877 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -11570,6 +11570,141 @@ system and gives an overview of their function and contents.
>         The default is ``txt`` which means the script is installed as-is, with
>         no modification.
>   
> +   :term:`UBOOT_EXTLINUX`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class in a
> +      U-Boot recipe, the :term:`UBOOT_EXTLINUX` variable should be set to "1" to
> +      enable the class functionality (inheriting the class is not enough).
> +
> +   :term:`UBOOT_EXTLINUX_CONSOLE`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_CONSOLE` variable can be set to control the
> +      ``console=`` parameter of the `Linux kernel command-line
> +      <https://docs.kernel.org/admin-guide/kernel-parameters.html>`__. For
> +      example, use as follows::

You can remove ", use as follows", "For example:" is enough here. Ditto 
for all following occurrences.

> +
> +         UBOOT_EXTLINUX_CONSOLE = "console=ttyS0,115200n8"
> +
> +      This is added to the ``APPEND`` property of the ``extlinux.conf`` file
> +      used for booting.
> +
> +   :term:`UBOOT_EXTLINUX_FDT`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_FDT` variable can be set to control the ``FDT``
> +      property of the ``extlinux.conf`` file used for booting, which controls
> +      the Linux kernel device tree to use. For example, use as follows::
> +
> +         UBOOT_EXTLINUX_FDT = "../am335x-bone.dtb"
> +
> +      .. note::
> +
> +         This path is relative to the ``extlinux.conf`` file used for booting.

It can also be absolute, with the path being the one as stored in the 
partition from which the extlinux.conf is (that is, NOT necessarily the 
same as when the partition is mounted by the target). We use that in 
meta-rockchip (/boot/...).

This doesn't need to be set when a FIT image is to be used.

> +
> +   :term:`UBOOT_EXTLINUX_FDTDIR`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_FDTDIR` variable can be set to control the ``FDTDIR``
> +      property of the ``extlinux.conf`` file used for booting, which controls
> +      the directory location for locating and loading the Linux kernel device

s/for locating and loading/the/

> +      tree specified in the ``fdtfile`` U-Boot environment variable. For
> +      example, use as follows::
> +
> +         UBOOT_EXTLINUX_FDTDIR = "../"
> +
> +      .. note::
> +
> +         This path is relative to the ``extlinux.conf`` file used for booting.
> +

Same remark as above, can be an absolute path (we use it in meta-rockchip).

> +   :term:`UBOOT_EXTLINUX_FDTOVERLAYS`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_FDT` variable can be set to control the ``FDTOVERLAYS``
> +      property of the ``extlinux.conf`` file used for booting, which controls
> +      the Linux kernel device overlays tree to apply on top of the device tree.
> +      For example, use as follows::
> +
> +         UBOOT_EXTLINUX_FDTOVERLAYS = "../am335x-bone-wifi.dtbo"
> +
> +      .. note::
> +
> +         This path is relative to the ``extlinux.conf`` file used for booting.
> +

Ditto.

> +   :term:`UBOOT_EXTLINUX_KERNEL_ARGS`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_KERNEL_ARGS` variable can be used to pass extra
> +      parameters to add to the `Linux kernel command-line

s/to add/

> +      <https://docs.kernel.org/admin-guide/kernel-parameters.html>`__. For
> +      example, use as follows::
> +
> +         UBOOT_EXTLINUX_KERNEL_ARGS = "rootwait ro"
> +
> +      This is included in the ``APPEND`` property of the ``extlinux.conf`` file
> +      used for booting.
> +
> +   :term:`UBOOT_EXTLINUX_KERNEL_IMAGE`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_KERNEL_IMAGE` variable can be used to specify the
> +      ``KERNEL`` property of the ``extlinux.conf`` file used for booting, which controls
> +      the Linux kernel image to use. For example, use as follows::
> +
> +         UBOOT_EXTLINUX_KERNEL_IMAGE = "../zImage"
> +
> +      .. note::
> +
> +         This path is relative to the ``extlinux.conf`` file used for booting.
> +

Same remark as earlier, can be absolute.

> +      .. tip::
> +
> +         The :term:`KERNEL_IMAGETYPE` variable can be used to get the name of
> +         the current Linux kernel being built by its associated recipe.
> +
> +   :term:`UBOOT_EXTLINUX_LABELS`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_LABELS` variable contains a list of labels
> +      (``LABEL`` property of the ``extlinux.conf`` file used for booting) that
> +      can be used for booting. This list should contain at least one entry.
> +

No, it must :) And it defaults to "linux".

> +      When multiple labels are specified in this list, all of the variable
> +      ``UBOOT_EXTLINUX_`` variable should be specified with overrides-style

variable [...] variable? One ought to be enough :) Please use the plural 
as well.

> +      assignments. For example, if the :term:`UBOOT_EXTLINUX_LABELS` variable
> +      contains::
> +
> +         UBOOT_EXTLINUX_LABELS = "compressed uncompressed"
> +
> +      Then the :term:`UBOOT_EXTLINUX_KERNEL_IMAGE` variable can be specified
> +      multiple times as follows::
> +
> +         UBOOT_EXTLINUX_KERNEL_IMAGE:compressed = "../zImage"
> +         UBOOT_EXTLINUX_KERNEL_IMAGE:uncompressed = "../Image"
> +
> +      This will make the value of the ``KERNEL`` property be different in each
> +      of the associated labels.
> +
> +      Note that default values are used when no overrides-style assignments are
> +      found for the current label. For example, taking the above example again,
> +      the following assignment would apply to both ``compressed`` and
> +      ``uncompressed`` labels::

**if and only if** UBOOT_EXTLINUX_FDT:compressed and/or 
UBOOT_EXTLINUX_FDT:uncompressed aren't set.

I'm assuming all operators can be used when this override-style is used? 
E.g. UBOOT_EXTLINUX_FDT:compressed:append = " something"? I do have an 
:append and :remove in meta-cherry-es, but not with an override-style 
syntax.

> +
> +         UBOOT_EXTLINUX_FDT = "../am335x-bone-wifi.dtbo"
> +
> +   :term:`UBOOT_EXTLINUX_MENU_DESCRIPTION`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_MENU_DESCRIPTION` variable sets a description for
> +      the label. If not specified, the name of the label itself is used as the
> +      description.
> +

It defaults to the current label when parsing the variables. Funnily 
enough, this will set the LABEL property in extlinux.conf so we should 
probably say that here as well.

> +   :term:`UBOOT_EXTLINUX_MENU_TITLE`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_MENU_TITLE` variable sets the ``MENU TITLE``
> +      property of the ``extlinux.conf`` file used for booting.
> +

Please specify this doesn't actually support the override-style syntax 
as it applies to the whole file.

> +   :term:`UBOOT_EXTLINUX_ROOT`
> +      When inheriting the :ref:`ref-classes-uboot-extlinux-config` class, the
> +      :term:`UBOOT_EXTLINUX_ROOT` variable is mandatory and should contain the

s/should contain/contains/?

> +      ``root=`` parameter of the `Linux kernel command-line
> +      <https://docs.kernel.org/admin-guide/kernel-parameters.html>`__. For
> +      example, the following would set this value to instruct the kernel to use
> +      the second partition of MMC block device 0 as its root partition::
> +
> +         UBOOT_EXTLINUX_ROOT = "root=/dev/mmcblk0p2"
> +

We're also missing:
- UBOOT_EXTLINUX_CONFIG,
- UBOOT_EXTLINUX_TIMEOUT,
- UBOOT_EXTLINUX_DEFAULT_LABEL,
- UBOOT_EXTLINUX_INITRD,

Cheers,
Quentin