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

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi,

On Thu Aug 6, 2026 at 11:54 AM CEST, Quentin Schulz wrote:
[...]
>> +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.

Thanks for the pointer! I'll link to here as it is more relevant indeed.

[...]
>> +   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?

I used the beaglebone-yocto machine and wks file from here:
https://git.yoctoproject.org/meta-yocto/tree/meta-yocto-bsp/files/wic/beaglebone-yocto.wks

And here's what I had to do to make it work:
diff --git a/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf b/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf
index b3c15d5aa6..bcc5838b99 100644
--- a/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf
+++ b/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf
@@ -12,7 +12,7 @@ include conf/machine/include/arm/armv7a/tune-cortexa8.inc
 
 IMAGE_FSTYPES += "tar.zst wic.zst wic.bmap"
 EXTRA_IMAGECMD:jffs2 = "-lnp "
-WKS_FILE ?= "beaglebone-yocto.wks"
+WKS_FILE ?= "beaglebone-yocto.wks.in"
 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "kernel-image kernel-devicetree"
 do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot virtual/bootloader:do_deploy"
 
diff --git a/meta-yocto-bsp/files/wic/beaglebone-yocto.wks b/meta-yocto-bsp/files/wic/beaglebone-yocto.wks.in
similarity index 82%
rename from meta-yocto-bsp/files/wic/beaglebone-yocto.wks
rename to meta-yocto-bsp/files/wic/beaglebone-yocto.wks.in
index 335e2b9bd5..5dc55cfb66 100644
--- a/meta-yocto-bsp/files/wic/beaglebone-yocto.wks
+++ b/meta-yocto-bsp/files/wic/beaglebone-yocto.wks.in
@@ -4,4 +4,4 @@
 
 part /boot --source bootimg_partition --ondisk mmcblk0 --fstype=vfat --label boot --active --align 4 --fixed-size 32 --sourceparams="loader=u-boot" --use-uuid
 part / --source rootfs --ondisk mmcblk0 --fstype=ext4 --label root --align 4 --use-uuid
-bootloader --append="console=ttyS0,115200"
+bootloader --append="console=ttyS0,115200" --configfile="${DEPLOY_DIR_IMAGE}/extlinux.conf"

And even with my UBOOT_EXTLINUX set to "1" (I could verify that it was properly
generated), it wasn't deployed in my boot partition. Instead I always got the
one generated by Wic:
https://git.yoctoproject.org/wic/tree/src/wic/plugins/source/bootimg_partition.py#n114

I had to hit this codepath to get mine used:
https://git.yoctoproject.org/wic/tree/src/wic/plugins/source/bootimg_partition.py#n80

Which is hit when cr.ks.bootloader.configfile is defined.

[...]
>> +      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.

Yes, this works.

[...]
>> +      ``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,

I'd rather document UBOOT_EXTLINUX_INSTALL_DIR and UBOOT_EXTLINUX_CONF_NAME
which really control how the file is named and where it's deployed. Will do in
v2.

> - UBOOT_EXTLINUX_TIMEOUT,
> - UBOOT_EXTLINUX_DEFAULT_LABEL,
> - UBOOT_EXTLINUX_INITRD,
>
> Cheers,
> Quentin

Thanks!
Antonin