* [PATCH] ref-manual: document the usage of FIT_LOADABLES
@ 2026-03-27 9:10 Francesco Valla
2026-03-27 10:13 ` Antonin Godard
0 siblings, 1 reply; 2+ messages in thread
From: Francesco Valla @ 2026-03-27 9:10 UTC (permalink / raw)
To: docs; +Cc: Adrian Freihofer, Trevor Gamblin, Antonin Godard, Francesco Valla
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
+ 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.
+
+ :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"
+
+ :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"
+ 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";
+ };
+ };
+ };
+
: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
--
2.53.0
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] ref-manual: document the usage of FIT_LOADABLES
2026-03-27 9:10 [PATCH] ref-manual: document the usage of FIT_LOADABLES Francesco Valla
@ 2026-03-27 10:13 ` Antonin Godard
0 siblings, 0 replies; 2+ messages in thread
From: Antonin Godard @ 2026-03-27 10:13 UTC (permalink / raw)
To: Francesco Valla, docs; +Cc: Adrian Freihofer, Trevor Gamblin
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
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2026-03-27 10:13 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-03-27 9:10 [PATCH] ref-manual: document the usage of FIT_LOADABLES Francesco Valla
2026-03-27 10:13 ` Antonin Godard
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox