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

[PATCH v4] classes.rst variables.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   | 50 ++++++++++++++++++++++++++
 documentation/ref-manual/variables.rst | 42 ++++++++++++++++++++++
 2 files changed, 92 insertions(+)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index b92f4e4f20..ad22511b4d 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -3345,6 +3345,56 @@ 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, :term:`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
+:term:`Initramfs, ``systemd-boot`` as boot menu provider and have UEFI support
+on target hardware. 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
+: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>`.
+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:`EFI_ARCH`: architecture name within EFI standard, set in
+   :oe_git:`meta/conf/image-uefi.conf
+   <openembedded-core/tree/meta/conf/image-uefi.conf>`
+-  :term:`IMAGE_EFI_BOOT_FILES`: files to install to EFI boot partition
+   created by the ``bootimg-efi`` Wic plugin
+-  :term:`INITRAMFS_IMAGE`: initramfs recipe name
+-  :term:`KERNEL_DEVICETREE`: optional devicetree files to embed into UKI
+-  :term:`UKIFY_CMD`: `ukify
+   <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__
+   command to build the UKI image
+-  :term:`UKI_CMDLINE`: kernel command line to use with UKI
+-  :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 the UKI image
+-  :term:`UKI_KERNEL_FILENAME`: kernel image file name
+-  :term:`UKI_SB_CERT`: optional UEFI secureboot certificate matching the
+   private key
+-  :term:`UKI_SB_KEY`: optional UEFI secureboot private key to sign UKI with
+
+For examples on how to use this class see oeqa selftest
+:oe_git:`meta/lib/oeqa/selftest/cases/uki.py
+<openembedded-core/tree/meta/lib/oeqa/selftest/cases/uki.py>`.
+Also an oeqa runtime test :oe_git:`meta/lib/oeqa/runtime/cases/uki.py
+<openembedded-core/tree/meta/lib/oeqa/runtime/cases/uki.py>` 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``
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index ec4d7ab73f..1eee617d59 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -2355,6 +2355,11 @@ system and gives an overview of their function and contents.
       specifies the size of padding appended to the device tree blob, used as
       extra space typically for additional properties during boot.
 
+   :term:`EFI_ARCH`
+      The CPU architecture name within EFI standard. Set in
+      :oe_git:`meta/conf/image-uefi.conf
+      <openembedded-core/tree/meta/conf/image-uefi.conf>`.
+
    :term:`EFI_PROVIDER`
       When building bootable images (i.e. where ``hddimg``, ``iso``, or
       ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the
@@ -9846,6 +9851,43 @@ system and gives an overview of their function and contents.
       passes and uses "all" for the target during the U-Boot building
       process.
 
+   :term:`UKIFY_CMD`
+      When inheriting the :ref:`ref-classes-uki` class,
+      `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build
+      `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
+      Defaults to ``ukify build``.
+
+   :term:`UKI_CMDLINE`
+      When inheriting the :ref:`ref-classes-uki` class, the kernel command line
+      to use when booting the `Unified Kernel Image (UKI)
+      <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
+      Defaults to ``rootwait root=LABEL=root console=${KERNEL_CONSOLE}``.
+
+   :term:`UKI_CONFIG_FILE`
+      When inheriting the :ref:`ref-classes-uki` class, an optional config
+      file for the `ukify
+      <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__
+      command.
+
+   :term:`UKI_FILENAME`
+      When inheriting the :ref:`ref-classes-uki` class, the output file name
+      for the generated `Unified Kernel Image (UKI)
+      <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
+      Defaults to ``uki.efi``.
+
+   :term:`UKI_KERNEL_FILENAME`
+      When inheriting the :ref:`ref-classes-uki` class, the kernel image file
+      name to use as input. Defaults to :term:`KERNEL_IMAGETYPE`.
+
+   :term:`UKI_SB_CERT`
+      When inheriting the :ref:`ref-classes-uki` class, optional UEFI
+      secureboot certificate matching the private key in :term:`UKI_SB_KEY`.
+
+   :term:`UKI_SB_KEY`
+      When inheriting the :ref:`ref-classes-uki` class, optional UEFI
+      secureboot private key to sign the `Unified Kernel Image (UKI)
+      <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
+
    :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`
       Specifies a list of options that, if reported by the configure script
       as being invalid, should not generate a warning during the
-- 
2.43.0

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

[Antonin Godard]

Hi Mikko,

On Wed Nov 27, 2024 at 12:20 PM CET, 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   | 50 ++++++++++++++++++++++++++
>  documentation/ref-manual/variables.rst | 42 ++++++++++++++++++++++
>  2 files changed, 92 insertions(+)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index b92f4e4f20..ad22511b4d 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -3345,6 +3345,56 @@ 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, :term:`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
> +:term:`Initramfs, ``systemd-boot`` as boot menu provider and have UEFI support

There's a missing backtick after Initramfs here, which prompts an error message.

Otherwise the rest of the patch looks good to me.


Thank you!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

[Mikko Rapeli]

Hi,

On Wed, Nov 27, 2024 at 02:52:20PM +0100, Antonin Godard wrote:
> Hi Mikko,
> 
> On Wed Nov 27, 2024 at 12:20 PM CET, 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   | 50 ++++++++++++++++++++++++++
> >  documentation/ref-manual/variables.rst | 42 ++++++++++++++++++++++
> >  2 files changed, 92 insertions(+)
> >
> > diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> > index b92f4e4f20..ad22511b4d 100644
> > --- a/documentation/ref-manual/classes.rst
> > +++ b/documentation/ref-manual/classes.rst
> > @@ -3345,6 +3345,56 @@ 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, :term:`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
> > +:term:`Initramfs, ``systemd-boot`` as boot menu provider and have UEFI support
> 
> There's a missing backtick after Initramfs here, which prompts an error message.

Oops, will fix in v5.

Cheers,

-Mikko