| Message ID | 20250307081422.718699-1-jamin_lin@aspeedtech.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v3] ref-manual: uboot-sign: Add how to enable ATF, TEE and User defined snippet ITS for U-Boot FIT image | expand |
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
Hi Antonin > From: docs@lists.yoctoproject.org <docs@lists.yoctoproject.org> On Behalf Of > Antonin Godard via lists.yoctoproject.org > Sent: Tuesday, March 11, 2025 6:23 PM > To: Jamin Lin <jamin_lin@aspeedtech.com>; docs@lists.yoctoproject.org > Cc: Troy Lee <troy_lee@aspeedtech.com> > Subject: Re: [docs] [PATCH v3] ref-manual: uboot-sign: Add how to enable ATF, > TEE and User defined snippet ITS for U-Boot FIT image > > 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/ver > > ified-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 > Thanks for all your suggestions and review. I re-send v4 patch here, https://patchwork.yoctoproject.org/project/docs/patch/20250312024235.2154311-1-jamin_lin@aspeedtech.com/ Thanks-Jamin > -- > Antonin Godard, Bootlin > Embedded Linux and Kernel engineering > https://bootlin.com
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 + 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" + + :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/>. + + 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.
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(+)