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