| 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 |
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
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
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
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 --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.
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(+)