[PATCH] ref-manual: add uboot-extlinux-config class documentation
Antonin Godard <[email protected]>
| Newsgroups | org.yoctoproject.lists.docs |
|---|---|
| Message-ID | <[email protected]> |
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/>`__. + +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:: + + 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" + +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. + .. _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:: + + 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. + + :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 + 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. + + :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. + + :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 + <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. + + .. 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. + + When multiple labels are specified in this list, all of the variable + ``UBOOT_EXTLINUX_`` variable should be specified with overrides-style + 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:: + + 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. + + :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. + + :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 + ``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" + :term:`UBOOT_FIT_ADDRESS_CELLS` Specifies the value of the ``#address-cells`` value for the description of the U-Boot FIT image. --- base-commit: 41dae3c3da3ada1745fc60228ff6269c64ee2361 change-id: 20260429-uboot-extlinux-config-ff587c00925b