diff mbox series

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

Message ID 20250313020253.2785661-1-jamin_lin@aspeedtech.com
State Under Review
Headers show
Series [v5] ref-manual: uboot-sign: Add how to enable ATF, TEE and User defined snippet ITS for U-Boot FIT image | expand

Commit Message

Jamin Lin March 13, 2025, 2:02 a.m. UTC
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(+)

Comments

Antonin Godard March 13, 2025, 9:01 a.m. UTC | #1
Hi Jamin,

On Thu Mar 13, 2025 at 3:02 AM CET, Jamin Lin wrote:
> Add how to enable ATF, TEE and User defined ITS for U-Boot FIT image generation.

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

Thanks for working on this,
Antonin
Quentin Schulz March 13, 2025, 10:58 a.m. UTC | #2
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
Jamin Lin March 14, 2025, 1:12 a.m. UTC | #3
Hi Quentin,

> Subject: Re: [docs] [PATCH v5] ref-manual: uboot-sign: Add how to enable ATF,
> TEE and User defined snippet ITS for U-Boot FIT image
> 
> 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/ver
> > ified-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.
> 


I don't understand it, could you please describe it more detail?

> > +
> > +         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"'
> 
> ?
> 

We need to add (\). If we add '"fwa", "fwb"', the generated ITS file appears as follows:
```loadables = "atf", "tee", fwa, fwb;  
```

The quotation marks (") are missing in the generated ITS file, which causes a build failure

> >      :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?
> 

We need to add (\).
If we do not add (\), the quotation marks (") are missing in the generated ITS file, which causes a build failure.

> > +      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!
> 
Thanks for review and suggestions.
Jamin
> Cheers,
> Quentin
Jamin Lin March 14, 2025, 2:19 a.m. UTC | #4
Hi Quentin,

> Subject: RE: [docs] [PATCH v5] ref-manual: uboot-sign: Add how to enable ATF,
> TEE and User defined snippet ITS for U-Boot FIT image
> 
> Hi Quentin,
> 
> > Subject: Re: [docs] [PATCH v5] ref-manual: uboot-sign: Add how to
> > enable ATF, TEE and User defined snippet ITS for U-Boot FIT image
> >
> > 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/v
> > > er ified-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.
> >
> 
> 
> I don't understand it, could you please describe it more detail?
> 


Please ignore this question.
This syntax works, :yocto_git:`meta-arm</meta-arm>`

> > > +         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"'
> >
> > ?
> >
> 
> We need to add (\). If we add '"fwa", "fwb"', the generated ITS file appears as
> follows:
> ```loadables = "atf", "tee", fwa, fwb; ```
> 
> The quotation marks (") are missing in the generated ITS file, which causes a
> build failure
> 
> > >      :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.
> >


Added

> > > +
> > > +         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?

Fixed
> >
> > > +      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?
> >
> 
> We need to add (\).
> If we do not add (\), the quotation marks (") are missing in the generated ITS
> file, which causes a build failure.
> 
> > > +      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!
> >

I resend v6 patch here, https://patchwork.yoctoproject.org/project/docs/patch/20250314021535.1677985-1-jamin_lin@aspeedtech.com/
 
Thanks-Jamin

> Thanks for review and suggestions.
> Jamin
> > Cheers,
> > Quentin
diff mbox series

Patch

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.
+-  :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 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.
+
+      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"::
+
+         UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin"
+
+      It is estimated that the image is placed in U-Boot's :term:`B` directory.
+      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
+      must add the necessary dependency in the U-boot ``.bbappend`` file. The
+      recipe name for Trusted Firmware-A (TF-A) image is ``trusted-firmware-a``
+      , which comes from the
+      `meta-arm <https://git.yoctoproject.org/meta-arm/>`__ layer::
+
+         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\"'
+
    :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.
+
+      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"
+
+      It is estimated that the image is placed in U-Boot's :term:`B` directory.
+      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
+      recipe, you must add the necessary dependency in the U-boot ``.bbappend``
+      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::
+
+         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/.
+
+      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.