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

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Jamin,

On Fri Mar 7, 2025 at 9:14 AM CET, Jamin Lin 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   |  13 ++++
>  documentation/ref-manual/variables.rst | 102 +++++++++++++++++++++++++
>  2 files changed, 115 insertions(+)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index b93279ff6..02749df3d 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -3401,6 +3401,19 @@ 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.
> +-  :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.
> +-  :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 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 60984cc8f..3c7e627f5 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -9826,6 +9826,28 @@ 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

Can you use the hyperlink syntax instead:

  `Trusted Firmware-A (TF-A) <https://www.trustedfirmware.org/projects/tf-a>`__

Also when possible try to wrap the lines to 80 chars, as per our standards.md
file.

> +      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.
> +
> +      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 value is "bl31.bin"::

I suppose this path is relative to $DEPLOY_DIR_IMAGE? Or $B? Can you maybe
specify this here?

Same for the UBOOT_*_IMAGE variables added by this patch.

> +
> +         UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin"
> +
> +   :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\"'
> +
>     :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::
> @@ -9874,6 +9896,86 @@ 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.
> +
> +      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
> +      default value is "tee-raw.bin"::
> +
> +         UBOOT_FIT_TEE_IMAGE ?= "tee-raw.bin"
> +
> +   :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/>.

You can remove <> surrounding the link here

> +
> +      The original contents of the U-Boot Image Tree Source (ITS) are as 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``.
> +
> +      The generated contents of the U-Boot Image Tree Source (ITS) are as 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>;
> +              };
> +              fwa {
> +                  description = "FW A";
> +                  data = /incbin/("fwa.bin");
> +                  type = "firmware";
> +                  arch = "";
> +                  os = "";
> +                  load = <0xb2000000>;
> +                  entry = <0xb2000000>;
> +                  compression = "none";
> +              };
> +          };
> +
>     :term:`UBOOT_FITIMAGE_ENABLE`
>        This variable allows to generate a FIT image for U-Boot, which is one
>        of the ways to implement a verified boot process.

Thanks,
Antonin

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