ref-manual: document the usage of FIT_LOADABLES

Add documentation for the new logic and variables that can be used to
add additional arbitrary loadables to a FIT image.

Signed-off-by: Francesco Valla <francesco@valla.it>
---
 documentation/ref-manual/classes.rst   |  16 +-
 documentation/ref-manual/variables.rst | 193 +++++++++++++++++++++++++
 2 files changed, 207 insertions(+), 2 deletions(-)

Hi,

First, let me say that this is really nice and clear documentation, and I think
covers exactly what is needed, thanks!

I've added comments below.

On Fri Mar 27, 2026 at 10:10 AM CET, Francesco Valla wrote:
> Add documentation for the new logic and variables that can be used to
> add additional arbitrary loadables to a FIT image.
>
> Signed-off-by: Francesco Valla <francesco@valla.it>
> ---
>  documentation/ref-manual/classes.rst   |  16 +-
>  documentation/ref-manual/variables.rst | 193 +++++++++++++++++++++++++
>  2 files changed, 207 insertions(+), 2 deletions(-)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index dc131be9fb93..ec30d6417cb0 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -1420,12 +1420,13 @@ Its behavior is mainly controlled by the following variables:
>  ====================
>  
>  The :ref:`ref-classes-kernel-fit-image` class provides support to pack a kernel image,
> -device trees, a U-boot script, and an :term:`Initramfs` into a single FIT image.
> +device trees, a U-boot script, an :term:`Initramfs` and additional loadables into a
> +single FIT image.
>  In theory, a FIT image can support any number of kernels, U-boot scripts,
>  :term:`Initramfs`, and device trees.
>  However, :ref:`ref-classes-kernel-fit-image` currently only supports
>  limited usecases: just one kernel image, an optional U-boot script,
> -an optional :term:`Initramfs`, and any number of device trees.
> +an optional :term:`Initramfs`, and any number of device trees and loadables.
>  
>  The FIT image is created by a recipe which inherits the
>  :ref:`ref-classes-kernel-fit-image` class.
> @@ -1535,6 +1536,17 @@ allow configuration:
>     At run-time, U-boot's boot command can be configured to load the boot script
>     from the FIT image and source it.
>  
> +-  Multiple additional loadables (e.g.: firmwares for auxiliary processors) can
> +   be added to the FIT image created by :ref:`ref-classes-kernel-fit-image`.
> +   The addition of loadables is optional. The loadables are specified using the
> +   :term:`FIT_LOADABLES` variable; each of them can then be configured through
> +   flags on the following variables: :term:`FIT_LOADABLE_ARCH`,
> +   :term:`FIT_LOADABLE_COMPRESSION`, :term:`FIT_LOADABLE_DESCRIPTION`,
> +   :term:`FIT_LOADABLE_ENTRYPOINT`, :term:`FIT_LOADABLE_FILENAME`,
> +   :term:`FIT_LOADABLE_LOADADDRESS`, :term:`FIT_LOADABLE_OS` and
> +   :term:`FIT_LOADABLE_TYPE`. All loadables specified in this way will be added
> +   to all configurations present in the FIT image.
> +
>  -  The FIT image generated by the :ref:`ref-classes-kernel-fit-image` class is signed when the
>     variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
>     :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 9e0c5b0835a2..35c54130e7f6 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3510,6 +3510,199 @@ system and gives an overview of their function and contents.
>        The default value is set to "x509" by the
>        :ref:`ref-classes-kernel-fit-image` class.
>  
> +   :term:`FIT_LOADABLE_ARCH`
> +      Architecture the loadables defined in :term:`FIT_LOADABLES`; the value
> +      will be used for the ``arch`` property of the loadable.
> +      If no value is defined for a specific loadable, the kernel architecture
> +      will be used.
> +
> +      This variable cannot be used directly, but only defining flags on it.
> +
> +      Example::
> +
> +         FIT_LOADABLES = "foo"
> +         FIT_LOADABLE_ARCH[foo] = "arm"
> +
> +   :term:`FIT_LOADABLE_COMPRESSION`
> +      Compresssion for the loadables defined in :term:`FIT_LOADABLES`; the

s/Compresssion/Compression type/

> +      value will be used for the ``compression`` property of the loadable.
> +      If no value is defined for a specific loadable, its ``compression``
> +      property will be set to ``none``.
> +
> +      This variable cannot be used directly, but only defining flags on it.
> +
> +      Example::
> +
> +         FIT_LOADABLES = "foo"
> +         FIT_LOADABLE_COMPRESSION[foo] = "gzip"
> +
> +      .. note::
> +
> +         The binary to be included will be considered as already compressed, no
> +         operation will be performed on it.

How about "The binary should already be compressed, as no compression is
performed by the :ref:`ref-classes-kernel-fit-image` class."?

> +
> +   :term:`FIT_LOADABLE_DESCRIPTION`
> +      Description for the loadables defined in :term:`FIT_LOADABLES`; the value
> +      will be used for the ``description`` property of the loadable.
> +      If no value is defined for a specific loadable, its description will be
> +      set to the loadable name followed by a space plus the string ``loadable``.
> +
> +      This variable cannot be used directly, but only defining flags on it.
> +
> +      Example::
> +
> +         FIT_LOADABLES = "foo"
> +         FIT_LOADABLE_DESCRIPTION[foo] = "Foo firmware binary"
> +
> +   :term:`FIT_LOADABLE_ENTRYPOINT`
> +      Entry point for the loadables defined in :term:`FIT_LOADABLES`; the value
> +      will be used for the ``entry`` property of the loadable.
> +      If no value is defined for a specific loadable, the ``entry`` property
> +      will be omitted.
> +
> +      This variable cannot be used directly, but only defining flags on it.
> +
> +      Example::
> +
> +         FIT_LOADABLES = "foo"
> +         FIT_LOADABLE_ENTRYPOINT[foo] = "0x80234000"
> +
> +   :term:`FIT_LOADABLE_FILENAME`
> +      Filename (or relative path) for the loadables defined in
> +      :term:`FIT_LOADABLES`; this will be used to search for the binary to
> +      include and is therefore mandatory for each loadable. Binary files to be
> +      included need to be located in :term:`DEPLOY_DIR_IMAGE`.
> +
> +      This variable cannot be used directly, but only defining flags on it.
> +
> +      Example::
> +
> +         FIT_LOADABLES = "foo"
> +         FIT_LOADABLE_FILENAME[foo] = "foo-firmware.bin"
> +
> +   :term:`FIT_LOADABLE_LOADADDRESS`
> +      Load address for the loadables defined in :term:`FIT_LOADABLES`; the
> +      value will be used for the ``load`` property of the loadable.
> +      This is mandatory for each loadable.
> +
> +      This variable cannot be used directly, but only defining flags on it.
> +
> +      Example::
> +
> +         FIT_LOADABLES = "foo"
> +         FIT_LOADABLE_LOADADDRESS[foo] = "foo-firmware.bin"

I think there's a copy-paste error here, the example should show an address :)

> +
> +   :term:`FIT_LOADABLE_OS`
> +      Operating system for the loadables defined in :term:`FIT_LOADABLES`; the
> +      value will be used for the ``os`` property of the loadable.
> +      If no value is defined for a specific loadable, the ``os`` property will
> +      be set to ``linux``.
> +
> +      This variable cannot be used directly, but only defining flags on it.
> +
> +      Example::
> +
> +         FIT_LOADABLES = "foo"
> +         FIT_LOADABLE_OS[foo] = "linux"
> +
> +   :term:`FIT_LOADABLE_TYPE`
> +      Type for the loadables defined in :term:`FIT_LOADABLES`; the value will
> +      be used for the ``type`` property of the loadable.
> +      If no value is defined for a specific loadable, the ``type`` property
> +      will be set to ``firmware``.
> +
> +      This variable cannot be used directly, but only defining flags on it.
> +
> +      Example::
> +
> +         FIT_LOADABLES = "foo"
> +         FIT_LOADABLE_TYPE[foo] = "firmware"
> +
> +   :term:`FIT_LOADABLES`
> +      Space-separated list of loadables to add to a FIT image in addition to
> +      regular ones (kernel, initramfs, dtsb etc.).
> +      Values specified here will be used as node names inside the FIT image;
> +      all of them will be included in all configurations by using the
> +      ``loadables`` property.
> +
> +      For each loadable specified in this variable, additional parameters can be
> +      defined using :term:`FIT_LOADABLE_ARCH`, :term:`FIT_LOADABLE_COMPRESSION`,
> +      :term:`FIT_LOADABLE_DESCRIPTION`, :term:`FIT_LOADABLE_ENTRYPOINT`,
> +      :term:`FIT_LOADABLE_FILENAME`, :term:`FIT_LOADABLE_LOADADDRESS`,
> +      :term:`FIT_LOADABLE_OS` and :term:`FIT_LOADABLE_TYPE`.
> +
> +      This variable is used by the :ref:`ref-classes-kernel-fit-image` class and
> +      is empty by default.
> +
> +      For example, the following configuration adds as loadables a TF-A BL31
> +      firmware and a (compressed) TEE firmware, to be loaded respectively at
> +      0x204E0000 and 0x96000000::
> +
> +         FIT_LOADABLES = "atf tee"
> +
> +         FIT_LOADABLE_FILENAME[atf] = "bl31.bin"
> +         FIT_LOADABLE_DESCRIPTION[atf] = "TF-A Firmware"
> +         FIT_LOADABLE_TYPE[atf] = "tfa-bl31"
> +         FIT_LOADABLE_ARCH[atf] = "arm64"
> +         FIT_LOADABLE_OS[atf] = "arm-trusted-firmware"
> +         FIT_LOADABLE_LOADADDRESS[atf] = "0x204E0000"
> +         FIT_LOADABLE_ENTRYPOINT[atf] = "0x204E0000"
> +
> +         FIT_LOADABLE_FILENAME[tee] = "tee.bin.gz"
> +         FIT_LOADABLE_COMPRESSSION[tee] = "gzip"

s/FIT_LOADABLE_COMPRESSSION/FIT_LOADABLE_COMPRESSION/

> +         FIT_LOADABLE_TYPE[tee] = "tee"
> +         FIT_LOADABLE_OS[tee] = "tee"
> +         FIT_LOADABLE_LOADADDRESS[tee] = "0x96000000"
> +
> +      and will be converted to the following FIT source::
> +
> +         images {
> +                 atf {
> +                         description = "TF-A Firmware";
> +                         type = "tfa-bl31";
> +                         compression = "none";
> +                         data = /incbin/("<DEPLOY_DIR_IMAGE>/bl31.bin");
> +                         arch = "arm64";
> +                         os = "arm-trusted-firmware";
> +                         load = <0x204E0000>;
> +                         entry = <0x204E0000>;
> +                         hash-1 {
> +                                 algo = "sha256";
> +                         };
> +                 };
> +                 tee {
> +                         description = "tee loadable";
> +                         type = "tee";
> +                         compression = "gzip";
> +                         data = /incbin/("<DEPLOY_DIR_IMAGE>/tee.bin.gz");
> +                         arch = "arm64";
> +                         os = "tee";
> +                         load = <0x96000000>;
> +                         hash-1 {
> +                                 algo = "sha256";
> +                         };
> +                 };
> +         };
> +
> +         configurations {
> +                 default = "<my-board>.dtb";
> +                 <my-board>.dtb {
> +                         description = "1 Linux kernel, FDT blob, loadables";
> +                         kernel = "kernel-1";
> +                         fdt = "<my-board>.dtb";
> +                         loadables = "atf", "tee";
> +                         hash-1 {
> +                                 algo = "sha256";
> +                         };
> +                         signature-1 {
> +                                 algo = "sha256,rsa2048";
> +                                 key-name-hint = "temp";
> +                                 padding = "pkcs-1.5";
> +                                 sign-images = "kernel", "fdt", "loadables";
> +                         };

For this example I think we can omit the signature/hash nodes to make it easier
to read

> +                 };
> +         };
> +
>     :term:`FIT_MKIMAGE_EXTRA_OPTS`
>        When inheriting the :ref:`ref-classes-kernel-fit-image`, the
>        :term:`FIT_MKIMAGE_EXTRA_OPTS` variable allows passing extra options to

Antonin