diff mbox series

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

Message ID 20250304083842.2828763-1-jamin_lin@aspeedtech.com
State Superseded
Headers show
Series [v2] 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 4, 2025, 8:38 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   |  8 +++
 documentation/ref-manual/variables.rst | 72 ++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

Comments

Quentin Schulz March 4, 2025, 1:55 p.m. UTC | #1
Hi Jamin,

On 3/4/25 9:38 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   |  8 +++
>   documentation/ref-manual/variables.rst | 72 ++++++++++++++++++++++++++
>   2 files changed, 80 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index b93279ff6..d1669ed87 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -3401,6 +3401,14 @@ 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`: enable the ARM Trusted Firmware (ATF) image.

I would rather suggest:

include the ARM Trusted Firmware (ATF) image in the U-Boot FIT image.

Funnily enough ATF is the old name, it should now be called Trusted 
Firmware-A, shortened to TF-A. 
https://trustedfirmware-a.readthedocs.io/en/latest/index.html

> +-  :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE`: specifie the path to the ATF image.

s/specifie/specifies/

Please also reiterate what ATF stands for (ARM Trusted Firmware) and/or 
use the new name as well. I think it's a good idea to try to not use 
only abbreviations.

> +-  :term:`UBOOT_FIT_TEE`: enable the Trusted Execution Environment (TEE) image.

I would rather suggest:

include the Trusted Execution Environment (TEE) image in the U-Boot FIT 
image.

> +-  :term:`UBOOT_FIT_TEE_IMAGE`: specifie the path to the TEE image.

s/specifie/specifies/

Please also reiterate what TEE stands for (Tee Execution Environment). I 
think it's a good idea to try to not use only abbreviations.


> +-  :term:`UBOOT_FIT_USER_SETTINGS`: add a user-specific snippet to the ITS. Users can
> +   include their custom ITS snippet in this variable.

s/add/adds/

If I'm not mistaken, this is to be inserted in the /images node, before 
the /configurations node.

> +-  :term:`UBOOT_FIT_CONF_USER_LOADABLES`: adds a user-defined image to the loadable

s/a user-defined image/one or more user-defined images/

s/loadable/loadables/

> +   property of the configuration node. It should be a comma-separated list of strings.
>   

I believe the strings should be surrounded each by quotes as well?

>   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..dbbaac56d 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -9884,6 +9884,78 @@ system and gives an overview of their function and contents.
>   
>         See the :ref:`ref-classes-uboot-sign` class for details.
>   
> +   :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE`

Please order this alphabetically, so before UBOOT_FIT_DESC.

> +      ARM Trusted Firmware (ATF) is a reference implementation of secure world

I would recommend also mentioning the new name (Trusted Firmware-A aka 
TF-A).

Additionally, provide a link to the project, e.g. 
https://www.trustedfirmware.org/projects/tf-a

> +      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 ATF 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 ATF image. Its default value is "bl31.bin"
> +

Missing the double colon here to make the line below a code-block.

Please also reiterate what ATF stands for and provide the new name (with 
its abbreviation as well).

> +         UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin"
> +
> +   :term:`UBOOT_FIT_TEE`

Please order this alphabetically, so before UBOOT_FITIMAGE_ENABLE.

> +      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 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 TEE image. Its default value is "tee-raw.bin"::

Please reiterate what TEE stands for.

> +
> +         UBOOT_FIT_TEE_IMAGE ?= "tee-raw.bin"
> +
> +   :term:`UBOOT_FIT_USER_SETTINGS`
> +      Add a user-specific snippet to the ITS. Users can include their custom ITS

Please mention it's for U-Boot ITS and specifically to add to the 
/images node.

Please specify what ITS stands for.

You could also provide a link to the specs, c.f. 
https://fitspec.osfw.foundation/

> +      snippet in this variable.
> +
> +      Ex::

s/snippet in this variable./snippet in this variable, e.g.::/

> +
> +         UBOOT_FIT_FWA_ITS = '\
> +             fwa {\n\
> +                 description = \"FW A\";\n\
> +                 data = /incbin/(\"fwa.bin\");\n\
> +                 type = \"fwtype\";\n\
> +                 arch = \"fwarch\";\n\
> +                 os = \"fwos\";\n\
> +                 load = <0xb2000000>;\n\
> +                 entry = <0xb2000000>;\n\
> +                 compression = \"none\";\n\
> +             };\n\
> +         '
> +

question: are the \n necessary? If so, we should document it that 
newlines are stripped and if they need to be added, they need to be 
explicitly added, via \n.

> +         UBOOT_FIT_USER_SETTINGS = "${UBOOT_FIT_FWA_ITS}"
> +
> +       The generated Image Tree Source (ITS):

Missing second colon to make the below a code block.

> +
> +         fwa {
> +             description = "FW A";
> +             data = /incbin/("fwa.bin");
> +             type = "fwtype";
> +             arch = "fwarch";
> +             os = "fwos";
> +             load = <0xb2000000>;
> +             entry = <0xb2000000>;
> +             compression = "none";
> +         };
> +

This is not properly aligned. It should be three whitespaces compared to 
the paragraph it's rattached to (i.e. where T character in "The 
generated Image Tree Source" is).

I am not entirely sure what should be understood from this example 
though? Maybe provide a full dummy ITS without this variable set and 
then with the variable set and show the changes?

> +   :term:`UBOOT_FIT_CONF_USER_LOADABLES`

Please order this alphabetically, so before UBOOT_FIT_USER_SETTINGS.

> +      Adds a user-defined image to the loadable property of the configuration node.

s/loadable/``loadables``/

s/of the configuration node/of the configuration node of the U-Boot 
Image Tree Source (ITS)/

> +      It should be a comma-separated list of strings.
> +
> +      Ex::
> +

s/It should be a comma-separated list of strings./It should be a 
comma-separated list of strings, e.g.::/

I believe each string needs to be surrounded by quotes too (like in your 
example)? If that really is the case, then we should mention it as well.

Looking good otherwise!

Cheers,
Quentin
Jamin Lin March 7, 2025, 8:21 a.m. UTC | #2
Hi Quentin

> 
> Hi Jamin,
> 
> On 3/4/25 9:38 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   |  8 +++
> >   documentation/ref-manual/variables.rst | 72
> ++++++++++++++++++++++++++
> >   2 files changed, 80 insertions(+)
> >
> > diff --git a/documentation/ref-manual/classes.rst
> > b/documentation/ref-manual/classes.rst
> > index b93279ff6..d1669ed87 100644
> > --- a/documentation/ref-manual/classes.rst
> > +++ b/documentation/ref-manual/classes.rst
> > @@ -3401,6 +3401,14 @@ 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`: enable the ARM
> Trusted Firmware (ATF) image.
> 
> I would rather suggest:
> 
> include the ARM Trusted Firmware (ATF) image in the U-Boot FIT image.
> 
> Funnily enough ATF is the old name, it should now be called Trusted
> Firmware-A, shortened to TF-A.
> https://trustedfirmware-a.readthedocs.io/en/latest/index.html
> 
> > +-  :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE`: specifie the
> path to the ATF image.
> 
> s/specifie/specifies/
> 
> Please also reiterate what ATF stands for (ARM Trusted Firmware) and/or use
> the new name as well. I think it's a good idea to try to not use only
> abbreviations.
> 
> > +-  :term:`UBOOT_FIT_TEE`: enable the Trusted Execution Environment (TEE)
> image.
> 
> I would rather suggest:
> 
> include the Trusted Execution Environment (TEE) image in the U-Boot FIT
> image.
> 
> > +-  :term:`UBOOT_FIT_TEE_IMAGE`: specifie the path to the TEE image.
> 
> s/specifie/specifies/
> 
> Please also reiterate what TEE stands for (Tee Execution Environment). I think
> it's a good idea to try to not use only abbreviations.
> 
> 
> > +-  :term:`UBOOT_FIT_USER_SETTINGS`: add a user-specific snippet to the
> ITS. Users can
> > +   include their custom ITS snippet in this variable.
> 
> s/add/adds/
> 
> If I'm not mistaken, this is to be inserted in the /images node, before
> the /configurations node.
> 
> > +-  :term:`UBOOT_FIT_CONF_USER_LOADABLES`: adds a user-defined
> image to the loadable
> 
> s/a user-defined image/one or more user-defined images/
> 
> s/loadable/loadables/
> 
> > +   property of the configuration node. It should be a comma-separated list
> of strings.
> >
> 
> I believe the strings should be surrounded each by quotes as well?
> 
> >   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..dbbaac56d 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -9884,6 +9884,78 @@ system and gives an overview of their function
> and contents.
> >
> >         See the :ref:`ref-classes-uboot-sign` class for details.
> >
> > +   :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE`
> 
> Please order this alphabetically, so before UBOOT_FIT_DESC.
> 
> > +      ARM Trusted Firmware (ATF) is a reference implementation of
> secure world
> 
> I would recommend also mentioning the new name (Trusted Firmware-A aka
> TF-A).
> 
> Additionally, provide a link to the project, e.g.
> https://www.trustedfirmware.org/projects/tf-a
> 
> > +      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 ATF 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 ATF image. Its default value is "bl31.bin"
> > +
> 
> Missing the double colon here to make the line below a code-block.
> 
> Please also reiterate what ATF stands for and provide the new name (with
> its abbreviation as well).
> 
> > +         UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin"
> > +
> > +   :term:`UBOOT_FIT_TEE`
> 
> Please order this alphabetically, so before UBOOT_FITIMAGE_ENABLE.
> 
> > +      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 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 TEE image. Its default value is
> "tee-raw.bin"::
> 
> Please reiterate what TEE stands for.
> 
> > +
> > +         UBOOT_FIT_TEE_IMAGE ?= "tee-raw.bin"
> > +
> > +   :term:`UBOOT_FIT_USER_SETTINGS`
> > +      Add a user-specific snippet to the ITS. Users can include their
> custom ITS
> 
> Please mention it's for U-Boot ITS and specifically to add to the
> /images node.
> 
> Please specify what ITS stands for.
> 
> You could also provide a link to the specs, c.f.
> https://fitspec.osfw.foundation/
> 
> > +      snippet in this variable.
> > +
> > +      Ex::
> 
> s/snippet in this variable./snippet in this variable, e.g.::/
> 
> > +
> > +         UBOOT_FIT_FWA_ITS = '\
> > +             fwa {\n\
> > +                 description = \"FW A\";\n\
> > +                 data = /incbin/(\"fwa.bin\");\n\
> > +                 type = \"fwtype\";\n\
> > +                 arch = \"fwarch\";\n\
> > +                 os = \"fwos\";\n\
> > +                 load = <0xb2000000>;\n\
> > +                 entry = <0xb2000000>;\n\
> > +                 compression = \"none\";\n\
> > +             };\n\
> > +         '
> > +
> 
> question: are the \n necessary? If so, we should document it that
> newlines are stripped and if they need to be added, they need to be
> explicitly added, via \n.
> 
> > +         UBOOT_FIT_USER_SETTINGS = "${UBOOT_FIT_FWA_ITS}"
> > +
> > +       The generated Image Tree Source (ITS):
> 
> Missing second colon to make the below a code block.
> 
> > +
> > +         fwa {
> > +             description = "FW A";
> > +             data = /incbin/("fwa.bin");
> > +             type = "fwtype";
> > +             arch = "fwarch";
> > +             os = "fwos";
> > +             load = <0xb2000000>;
> > +             entry = <0xb2000000>;
> > +             compression = "none";
> > +         };
> > +
> 
> This is not properly aligned. It should be three whitespaces compared to
> the paragraph it's rattached to (i.e. where T character in "The
> generated Image Tree Source" is).
> 
> I am not entirely sure what should be understood from this example
> though? Maybe provide a full dummy ITS without this variable set and
> then with the variable set and show the changes?
> 
> > +   :term:`UBOOT_FIT_CONF_USER_LOADABLES`
> 
> Please order this alphabetically, so before UBOOT_FIT_USER_SETTINGS.
> 
> > +      Adds a user-defined image to the loadable property of the
> configuration node.
> 
> s/loadable/``loadables``/
> 
> s/of the configuration node/of the configuration node of the U-Boot
> Image Tree Source (ITS)/
> 
> > +      It should be a comma-separated list of strings.
> > +
> > +      Ex::
> > +
> 
> s/It should be a comma-separated list of strings./It should be a
> comma-separated list of strings, e.g.::/
> 
> I believe each string needs to be surrounded by quotes too (like in your
> example)? If that really is the case, then we should mention it as well.
> 

Thanks for your review and all your suggestions.
I re-send v3 patch here, https://patchwork.yoctoproject.org/project/docs/patch/20250307081422.718699-1-jamin_lin@aspeedtech.com/
Thanks-Jamin

> Looking good otherwise!
> 
> Cheers,
> Quentin
diff mbox series

Patch

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index b93279ff6..d1669ed87 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -3401,6 +3401,14 @@  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`: enable the ARM Trusted Firmware (ATF) image.
+-  :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE`: specifie the path to the ATF image.
+-  :term:`UBOOT_FIT_TEE`: enable the Trusted Execution Environment (TEE) image.
+-  :term:`UBOOT_FIT_TEE_IMAGE`: specifie the path to the TEE image.
+-  :term:`UBOOT_FIT_USER_SETTINGS`: add a user-specific snippet to the ITS. Users can
+   include their custom ITS snippet in this variable.
+-  :term:`UBOOT_FIT_CONF_USER_LOADABLES`: adds a user-defined image to the loadable
+   property of the configuration node. It should be a comma-separated list of strings.
 
 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..dbbaac56d 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -9884,6 +9884,78 @@  system and gives an overview of their function and contents.
 
       See the :ref:`ref-classes-uboot-sign` class for details.
 
+   :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE`
+      ARM Trusted Firmware (ATF) 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 ATF 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 ATF image. Its default value is "bl31.bin"
+
+         UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin"
+
+   :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 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 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 ITS. Users can include their custom ITS
+      snippet in this variable.
+
+      Ex::
+
+         UBOOT_FIT_FWA_ITS = '\
+             fwa {\n\
+                 description = \"FW A\";\n\
+                 data = /incbin/(\"fwa.bin\");\n\
+                 type = \"fwtype\";\n\
+                 arch = \"fwarch\";\n\
+                 os = \"fwos\";\n\
+                 load = <0xb2000000>;\n\
+                 entry = <0xb2000000>;\n\
+                 compression = \"none\";\n\
+             };\n\
+         '
+
+         UBOOT_FIT_USER_SETTINGS = "${UBOOT_FIT_FWA_ITS}"
+
+       The generated Image Tree Source (ITS):
+
+         fwa {
+             description = "FW A";
+             data = /incbin/("fwa.bin");
+             type = "fwtype";
+             arch = "fwarch";
+             os = "fwos";
+             load = <0xb2000000>;
+             entry = <0xb2000000>;
+             compression = "none";
+         };
+
+   :term:`UBOOT_FIT_CONF_USER_LOADABLES`
+      Adds a user-defined image to the loadable property of the configuration node.
+      It should be a comma-separated list of strings.
+
+      Ex::
+
+         UBOOT_FIT_CONF_USER_LOADABLES = '\"fwa\", \"fwb\"'
+
    :term:`UBOOT_LOADADDRESS`
       Specifies the load address for the U-Boot image. During U-Boot image
       creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a