Re: [docs] [PATCH v5] ref-manual: uboot-sign: Add how to enable ATF, TEE and User defined snippet ITS for U-Boot FIT image

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Jamin,

I think we're almost there now!

On 3/13/25 3:02 AM, Jamin Lin via lists.yoctoproject.org wrote:
> Add how to enable ATF, TEE and User defined ITS for U-Boot FIT image generation.
> 
> Signed-off-by: Jamin Lin <jamin_lin@aspeedtech.com>
> ---
>   documentation/ref-manual/classes.rst   |  14 +++
>   documentation/ref-manual/variables.rst | 137 +++++++++++++++++++++++++
>   2 files changed, 151 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index b93279ff6..4b02daa58 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -3401,6 +3401,20 @@ The variables used by this class are:
>   -  :term:`UBOOT_FITIMAGE_ENABLE`: enable the generation of a U-Boot FIT image.
>   -  :term:`UBOOT_MKIMAGE_DTCOPTS`: DTC options for U-Boot ``mkimage`` when
>      rebuilding the FIT image containing the kernel.
> +-  :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE`: include the Trusted Firmware-A (TF-A)
> +   image in the U-Boot FIT image.
> +-  :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE`: specifies the path to the
> +   Trusted Firmware-A (TF-A) image.

s/image/binary/

> +-  :term:`UBOOT_FIT_TEE`: include the Trusted Execution Environment (TEE) image
> +   in the U-Boot FIT image.
> +-  :term:`UBOOT_FIT_TEE_IMAGE`: specifies the path to the Trusted Execution
> +   Environment (TEE) image.

s/image/binary/

> +-  :term:`UBOOT_FIT_USER_SETTINGS`: adds a user-specific snippet to the ITS.
> +   Users can include their custom ITS snippet in this variable.
> +-  :term:`UBOOT_FIT_CONF_USER_LOADABLES`: adds one or more user-defined images
> +   to the loadables property of the configuration node. It should be a

s/loadables/``loadables``/

> +   comma-separated list of strings and each string needs to be surrounded by
> +   quotes too.
>   
>   See U-Boot's documentation for details about `verified boot
>   <https://source.denx.de/u-boot/u-boot/-/blob/master/doc/uImage.FIT/verified-boot.txt>`__
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 861b04eaa..376782508 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -9949,6 +9949,45 @@ system and gives an overview of their function and contents.
>   
>         See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__.
>   
> +   :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE`
> +      `Trusted Firmware-A (TF-A) <https://www.trustedfirmware.org/projects/tf-a>`__
> +      is a reference implementation of secure world software for Arm A-Profile
> +      architectures (Armv8-A and Armv7-A), including an Exception Level 3 (EL3)
> +      Secure Monitor. This variable enables the generation of a U-Boot FIT image
> +      with an Trusted Firmware-A (TF-A) image.

s/image/binary/

> +
> +      Its default value is "0", so set it to "1" to enable this functionality::
> +
> +         UBOOT_FIT_ARM_TRUSTED_FIRMWARE = "1"
> +
> +   :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE`
> +      Specifies the path to the Trusted Firmware-A (TF-A) image. Its default

s/image/binary/

> +      value is "bl31.bin"::
> +
> +         UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin"
> +
> +      It is estimated that the image is placed in U-Boot's :term:`B` directory.

Maybe reword to:

If a relative path is provided, the file is expected to be relative to 
U-Boot's :term:`B` directory.

An absolute path can be provided too, e.g.::

    UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/bl31.bin"

> +      Users can specify an alternative location for the image, for example
> +      using :term:`DEPLOY_DIR_IMAGE`::
> +
> +         UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/bl31.bin"
> +
> +      If the Trusted Firmware-A (TF-A) image is built in a separate recipe, you

s/image/binary/

> +      must add the necessary dependency in the U-boot ``.bbappend`` file. The

s/the U-boot/a U-Boot/

(note the capitalization of B above).

> +      recipe name for Trusted Firmware-A (TF-A) image is ``trusted-firmware-a``

s/image/binary/

> +      , which comes from the
> +      `meta-arm <https://git.yoctoproject.org/meta-arm/>`__ layer::

s;`meta-arm 
<https://git.yoctoproject.org/meta-arm/>`__;:yocto_git:`meta-arm 
</meta-arm>`;

Please check this works, I'm not entirely sure about the syntax anymore, 
but please use :yocto_git: here.

> +
> +         do_compile[depends] += "trusted-firmware-a:do_deploy"
> +
> +   :term:`UBOOT_FIT_CONF_USER_LOADABLES`
> +      Adds one or more user-defined images to the ``loadables`` property of the
> +      configuration node of the U-Boot Image Tree Source (ITS). It should be a
> +      comma-separated list of strings and each string needs to be surrounded by
> +      quotes too, e.g.::
> +
> +         UBOOT_FIT_CONF_USER_LOADABLES = '\"fwa\", \"fwb\"'
> +

Question: do the quotes need to be escaped like in the example? or can 
we have:

UBOOT_FIT_CONF_USER_LOADABLES = '"fwa", "fwb"'

?

>      :term:`UBOOT_FIT_DESC`
>         Specifies the description string encoded into a U-Boot fitImage. The default
>         value is set by the :ref:`ref-classes-uboot-sign` class as follows::
> @@ -9997,6 +10036,104 @@ system and gives an overview of their function and contents.
>         of bits. The default value for this variable is set to "2048"
>         by the :ref:`ref-classes-uboot-sign` class.
>   
> +   :term:`UBOOT_FIT_TEE`
> +      A Trusted Execution Environment (TEE) is a secure environment for
> +      executing code, ensuring high levels of trust in asset management within
> +      the surrounding system. This variable enables the generation of a U-Boot
> +      FIT image with a Trusted Execution Environment (TEE) image.

s/image/binary/

> +
> +      Its default value is "0", so set it to "1" to enable this functionality::
> +
> +         UBOOT_FIT_TEE = "1"
> +
> +   :term:`UBOOT_FIT_TEE_IMAGE`
> +      Specifies the path to the Trusted Execution Environment (TEE) image. Its

s/image/binary/

> +      default value is "tee-raw.bin"::
> +
> +         UBOOT_FIT_TEE_IMAGE ?= "tee-raw.bin"
> +
> +      It is estimated that the image is placed in U-Boot's :term:`B` directory.

Maybe reword to:

If a relative path is provided, the file is expected to be relative to 
U-Boot's :term:`B` directory.

An absolute path can be provided too, e.g.::

    UBOOT_FIT_TEE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/tee-raw.bin"

> +      Users can specify an alternative location for the image, for example> +      using :term:`DEPLOY_DIR_IMAGE`::
> +
> +         UBOOT_FIT_TEE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/tee-raw.bin"
> +
> +      If the Trusted Execution Environment (TEE) image is built in a separate

s/image/binary/

> +      recipe, you must add the necessary dependency in the U-boot ``.bbappend``

s/the U-boot/a U-Boot/

(note the capitalization of B above).

> +      file. The recipe name for Trusted Execution Environment (TEE) image is
> +      ``optee-os``, which comes from the
> +      `meta-arm <https://git.yoctoproject.org/meta-arm/>`__ layer::

s;`meta-arm 
<https://git.yoctoproject.org/meta-arm/>`__;:yocto_git:`meta-arm 
</meta-arm>`;

Please check this works, I'm not entirely sure about the syntax anymore, 
but please use :yocto_git: here.

> +
> +         do_compile[depends] += "optee-os:do_deploy"
> +
> +   :term:`UBOOT_FIT_USER_SETTINGS`
> +      Add a user-specific snippet to the U-Boot Image Tree Source (ITS). This
> +      variable allows the user to add one or more user-defined ``/images`` node
> +      to the U-Boot Image Tree Source (ITS). For more details, please refer to
> +      https://fitspec.osfw.foundation/.
> +

Since there'll be a v6, can you check this link actually works? I have 
some vague recollection the dot may be part of the URL. You may want to do

https://fitspec.osfw.foundation/\ .

instead?

> +      The original contents of the U-Boot Image Tree Source (ITS) are as

s/contents[...] are/content[...] is/

> +      follows::
> +
> +         images {
> +             uboot {
> +                 description = "U-Boot image";
> +                 data = /incbin/("u-boot-nodtb.bin");
> +                 type = "standalone";
> +                 os = "u-boot";
> +                 arch = "";
> +                 compression = "none";
> +                 load = <0x80000000>;
> +                 entry = <0x80000000>;
> +             };
> +         };
> +
> +      Users can include their custom ITS snippet in this variable, e.g.::
> +
> +         UBOOT_FIT_FWA_ITS = '\
> +             fwa {\n\
> +                 description = \"FW A\";\n\
> +                 data = /incbin/(\"fwa.bin\");\n\
> +                 type = \"firmware\";\n\
> +                 arch = \"\";\n\
> +                 os = \"\";\n\
> +                 load = <0xb2000000>;\n\
> +                 entry = <0xb2000000>;\n\
> +                 compression = \"none\";\n\
> +             };\n\
> +         '
> +
> +         UBOOT_FIT_USER_SETTINGS = "${UBOOT_FIT_FWA_ITS}"
> +
> +      Newlines are stripped, and if they need to be included, they must be
> +      explicitly added using ``\n``.
> +

Please specify the quotes need to be escaped too?

> +      The generated contents of the U-Boot Image Tree Source (ITS) are as
> +      follows::
> +

s/contents[...] are/content[...] is/

> +         images {
> +             uboot {
> +                 description = "U-Boot image";
> +                 data = /incbin/("u-boot-nodtb.bin");
> +                 type = "standalone";
> +                 os = "u-boot";
> +                 arch = "";
> +                 compression = "none";
> +                 load = <0x80000000>;
> +                 entry = <0x80000000>;
> +             };
> +             fwa {
> +                 description = "FW A";
> +                 data = /incbin/("fwa.bin");
> +                 type = "firmware";
> +                 arch = "";
> +                 os = "";
> +                 load = <0xb2000000>;
> +                 entry = <0xb2000000>;
> +                 compression = "none";
> +             };
> +         };
> +

Looks good otherwise!

Cheers,
Quentin