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

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(+)

Hi Mikko,

On Wed Nov 27, 2024 at 2:59 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..33e1a4b435 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

Looking good to me, thank you!

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>


Antonin