[PATCH] classes.rst: add documentation for uki.bbclass

[PATCH] classes.rst: add documentation for uki.bbclass

[Mikko Rapeli]

Documentation for the new class.

[YOCTO #15650]
https://bugzilla.yoctoproject.org/show_bug.cgi?id=15650

Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
---
 documentation/ref-manual/classes.rst | 34 ++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index b92f4e4f20..901d455f09 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -3345,6 +3345,40 @@ and the `signature process
 See also the description of :ref:`ref-classes-kernel-fitimage` class, which this class
 imitates.
 
+.. _ref-classes-uki:
+
+``uki``
+=======
+
+The :ref:`ref-classes-uki` class provides support for `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__
+format. UKIs combine kernel, initramfs, signatures, metadata etc to a single UEFI firmware
+compatible binary. The class is intended to be inherited by rootfs image recipes. The build configuration
+should also use an initramfs, systemd-boot as boot menu provider and have UEFI support on target
+HW. Using systemd as init is recommended. Image builds should create an ESP partition
+for UEFI firmware and copy systemd-boot and UKI files there. Sample configuration for Wic
+images is provided in ``scripts/lib/wic/canned-wks/efi-uki-bootdisk.wks.in``.
+UKIs are generated using systemd reference implementation `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__.
+This class uses a number of variables but tries to find sensible defaults for them.
+
+The variables used by this class are:
+
+-  :term:`INITRAMFS_IMAGE`: initramfs recipe name
+-  :term:`INITRD_ARCHIVE`: initramfs image file name
+-  :term:`UKIFY_CMD`: `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build UKI image
+-  :term:`UKI_CONFIG_FILE`: optional config file for `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__
+-  :term:`UKI_FILENAME`: output file name for UKI image
+-  :term:`UKI_KERNEL_FILENAME`: kernel image file name
+-  :term:`UKI_CMDLINE`: kernel command line to use with UKI
+-  :term:`UKI_SB_KEY`: optional UEFI secureboot private key to sign UKI with
+-  :term:`UKI_SB_CERT`: optional UEFI secureboot certificate mathing the private key
+-  :term:`IMAGE_EFI_BOOT_FILES`: files to install to EFI boot partition created by ``bootimg-efi`` Wic tool
+-  :term:`EFI_ARCH`: architecture name within EFI standard, set in ``meta/conf/image-uefi.conf``
+-  :term:`KERNEL_DEVICETREE`: optional devicetree files to embed into UKI
+
+For examples how to use this class see oeqa selftest ``meta/lib/oeqa/selftest/cases/uki.py``.
+Also an oeqa runtime test ``uki`` is provided which verifies that the target system
+booted the same UKI binary as was set at buildtime via :term:`UKI_FILENAME`.
+
 .. _ref-classes-uninative:
 
 ``uninative``
-- 
2.43.0

Re: [docs] [PATCH] classes.rst: add documentation for uki.bbclass

[Quentin Schulz]

Hi Mikko,

On 11/25/24 4:34 PM, Mikko Rapeli via lists.yoctoproject.org wrote:
> Documentation for the new class.
> 
> [YOCTO #15650]
> https://bugzilla.yoctoproject.org/show_bug.cgi?id=15650
> 
> Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
> ---
>   documentation/ref-manual/classes.rst | 34 ++++++++++++++++++++++++++++
>   1 file changed, 34 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index b92f4e4f20..901d455f09 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -3345,6 +3345,40 @@ and the `signature process
>   See also the description of :ref:`ref-classes-kernel-fitimage` class, which this class
>   imitates.
>   
> +.. _ref-classes-uki:
> +
> +``uki``
> +=======
> +
> +The :ref:`ref-classes-uki` class provides support for `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__
> +format. UKIs combine kernel, initramfs, signatures, metadata etc to a single UEFI firmware

s/initramfs/:term:`Initramfs`/

> +compatible binary. The class is intended to be inherited by rootfs image recipes. The build configuration
> +should also use an initramfs, systemd-boot as boot menu provider and have UEFI support on target

s/systemd-boot/:ref:`ref-classes-systemd-boot`/

or

s/systemd-boot/``systemd-boot``/
as we're talking about the binary and not the class.

> +HW. Using systemd as init is recommended. Image builds should create an ESP partition

s/systemd/``systemd``/

> +for UEFI firmware and copy systemd-boot and UKI files there. Sample configuration for Wic
> +images is provided in ``scripts/lib/wic/canned-wks/efi-uki-bootdisk.wks.in``.

Provide a link to it, c.f.

:oe_git:`scripts/lib/wic/canned-wks/efi-uki-bootdisk.wks.in 
<openembedded-core/tree/scripts/lib/wic/canned-wks/efi-uki-bootdisk.wks.in>`

maybe?

> +UKIs are generated using systemd reference implementation `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__.

s/systemd/``systemd``/

> +This class uses a number of variables but tries to find sensible defaults for them.
> +
> +The variables used by this class are:
> +
> +-  :term:`INITRAMFS_IMAGE`: initramfs recipe name
> +-  :term:`INITRD_ARCHIVE`: initramfs image file name
> +-  :term:`UKIFY_CMD`: `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build UKI image
> +-  :term:`UKI_CONFIG_FILE`: optional config file for `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__
> +-  :term:`UKI_FILENAME`: output file name for UKI image
> +-  :term:`UKI_KERNEL_FILENAME`: kernel image file name
> +-  :term:`UKI_CMDLINE`: kernel command line to use with UKI
> +-  :term:`UKI_SB_KEY`: optional UEFI secureboot private key to sign UKI with
> +-  :term:`UKI_SB_CERT`: optional UEFI secureboot certificate mathing the private key

You cannot use those here as they aren't defined yet. You have a 
circular dependency between this patch defining the class and the other 
one defining the variables, just merge both into one to get rid of it.

> +-  :term:`IMAGE_EFI_BOOT_FILES`: files to install to EFI boot partition created by ``bootimg-efi`` Wic tool
> +-  :term:`EFI_ARCH`: architecture name within EFI standard, set in ``meta/conf/image-uefi.conf``

Provide a link to the file?

> +-  :term:`KERNEL_DEVICETREE`: optional devicetree files to embed into UKI
> +
> +For examples how to use this class see oeqa selftest ``meta/lib/oeqa/selftest/cases/uki.py``.

Provide a link to the uki.py.

s/For examples/For examples on/ ?

Cheers,
Quentin

Re: [docs] [PATCH] classes.rst: add documentation for uki.bbclass

[Mikko Rapeli]

Hi,

On Tue, Nov 26, 2024 at 11:12:20AM +0100, Quentin Schulz wrote:
> Hi Mikko,
> 
> On 11/25/24 4:34 PM, Mikko Rapeli via lists.yoctoproject.org wrote:
> > Documentation for the new class.
> > 
> > [YOCTO #15650]
> > https://bugzilla.yoctoproject.org/show_bug.cgi?id=15650
> > 
> > Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org>
> > ---
> >   documentation/ref-manual/classes.rst | 34 ++++++++++++++++++++++++++++
> >   1 file changed, 34 insertions(+)
> > 
> > diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> > index b92f4e4f20..901d455f09 100644
> > --- a/documentation/ref-manual/classes.rst
> > +++ b/documentation/ref-manual/classes.rst
> > @@ -3345,6 +3345,40 @@ and the `signature process
> >   See also the description of :ref:`ref-classes-kernel-fitimage` class, which this class
> >   imitates.
> > +.. _ref-classes-uki:
> > +
> > +``uki``
> > +=======
> > +
> > +The :ref:`ref-classes-uki` class provides support for `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__
> > +format. UKIs combine kernel, initramfs, signatures, metadata etc to a single UEFI firmware
> 
> s/initramfs/:term:`Initramfs`/

Done

> > +compatible binary. The class is intended to be inherited by rootfs image recipes. The build configuration
> > +should also use an initramfs, systemd-boot as boot menu provider and have UEFI support on target
> 
> s/systemd-boot/:ref:`ref-classes-systemd-boot`/
> 
> or
> 
> s/systemd-boot/``systemd-boot``/
> as we're talking about the binary and not the class.

Done

> > +HW. Using systemd as init is recommended. Image builds should create an ESP partition
> 
> s/systemd/``systemd``/

Done
 
> > +for UEFI firmware and copy systemd-boot and UKI files there. Sample configuration for Wic
> > +images is provided in ``scripts/lib/wic/canned-wks/efi-uki-bootdisk.wks.in``.
> 
> Provide a link to it, c.f.
> 
> :oe_git:`scripts/lib/wic/canned-wks/efi-uki-bootdisk.wks.in
> <openembedded-core/tree/scripts/lib/wic/canned-wks/efi-uki-bootdisk.wks.in>`
> 
> maybe?

Done

> > +UKIs are generated using systemd reference implementation `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__.
> 
> s/systemd/``systemd``/

Done

> > +This class uses a number of variables but tries to find sensible defaults for them.
> > +
> > +The variables used by this class are:
> > +
> > +-  :term:`INITRAMFS_IMAGE`: initramfs recipe name
> > +-  :term:`INITRD_ARCHIVE`: initramfs image file name
> > +-  :term:`UKIFY_CMD`: `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build UKI image
> > +-  :term:`UKI_CONFIG_FILE`: optional config file for `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__
> > +-  :term:`UKI_FILENAME`: output file name for UKI image
> > +-  :term:`UKI_KERNEL_FILENAME`: kernel image file name
> > +-  :term:`UKI_CMDLINE`: kernel command line to use with UKI
> > +-  :term:`UKI_SB_KEY`: optional UEFI secureboot private key to sign UKI with
> > +-  :term:`UKI_SB_CERT`: optional UEFI secureboot certificate mathing the private key
> 
> You cannot use those here as they aren't defined yet. You have a circular
> dependency between this patch defining the class and the other one defining
> the variables, just merge both into one to get rid of it.

Done

> > +-  :term:`IMAGE_EFI_BOOT_FILES`: files to install to EFI boot partition created by ``bootimg-efi`` Wic tool
> > +-  :term:`EFI_ARCH`: architecture name within EFI standard, set in ``meta/conf/image-uefi.conf``
> 
> Provide a link to the file?

Done

> > +-  :term:`KERNEL_DEVICETREE`: optional devicetree files to embed into UKI
> > +
> > +For examples how to use this class see oeqa selftest ``meta/lib/oeqa/selftest/cases/uki.py``.
> 
> Provide a link to the uki.py.
> 
> s/For examples/For examples on/ ?

Done

Will send a v3.

Cheers,

-Mikko