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

[Jamin Lin <jamin_lin@aspeedtech.com>]

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..0a73a956e 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) binary in the U-Boot FIT binary.
+-  :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE`: specifies the path to the
+   Trusted Firmware-A (TF-A) binary.
+-  :term:`UBOOT_FIT_TEE`: include the Trusted Execution Environment (TEE)
+   binary in the U-Boot FIT binary.
+-  :term:`UBOOT_FIT_TEE_IMAGE`: specifies the path to the Trusted Execution
+   Environment (TEE) 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
+   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..4a8049e14 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
+      binary with an Trusted Firmware-A (TF-A) 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) binary. Its default
+      value is "bl31.bin"::
+
+         UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin"
+
+      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"
+
+      If the Trusted Firmware-A (TF-A) binary is built in a separate recipe,
+      you must add the necessary dependency in a U-Boot ``.bbappend`` file. The
+      recipe name for Trusted Firmware-A (TF-A) binary is
+      ``trusted-firmware-a``, which comes from the
+      :yocto_git:`meta-arm </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 binary with a Trusted Execution Environment (TEE) 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) binary. Its
+      default value is "tee-raw.bin"::
+
+         UBOOT_FIT_TEE_IMAGE ?= "tee-raw.bin"
+
+      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"
+
+      If the Trusted Execution Environment (TEE) binary is built in a separate
+      recipe, you must add the necessary dependency in a U-Boot ``.bbappend``
+      file. The recipe name for Trusted Execution Environment (TEE) binary is
+      ``optee-os``, which comes from the :yocto_git:`meta-arm </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 content of the U-Boot Image Tree Source (ITS) is 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 content of the U-Boot Image Tree Source (ITS) is 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.
-- 
2.34.1