From patchwork Thu Mar 13 02:02:52 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jamin Lin X-Patchwork-Id: 58889 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id BD595C28B28 for ; Thu, 13 Mar 2025 02:03:06 +0000 (UTC) Received: from TWMBX01.aspeed.com (TWMBX01.aspeed.com [211.20.114.72]) by mx.groups.io with SMTP id smtpd.web11.5329.1741831380041229024 for ; Wed, 12 Mar 2025 19:03:00 -0700 Authentication-Results: mx.groups.io; dkim=none (message not signed); spf=pass (domain: aspeedtech.com, ip: 211.20.114.72, mailfrom: jamin_lin@aspeedtech.com) Received: from TWMBX01.aspeed.com (192.168.0.62) by TWMBX01.aspeed.com (192.168.0.62) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.1258.12; Thu, 13 Mar 2025 10:02:53 +0800 Received: from mail.aspeedtech.com (192.168.10.10) by TWMBX01.aspeed.com (192.168.0.62) with Microsoft SMTP Server id 15.2.1258.12 via Frontend Transport; Thu, 13 Mar 2025 10:02:53 +0800 From: Jamin Lin To: CC: , Subject: [PATCH v5] ref-manual: uboot-sign: Add how to enable ATF, TEE and User defined snippet ITS for U-Boot FIT image Date: Thu, 13 Mar 2025 10:02:52 +0800 Message-ID: <20250313020253.2785661-1-jamin_lin@aspeedtech.com> X-Mailer: git-send-email 2.43.0 MIME-Version: 1.0 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 13 Mar 2025 02:03:06 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/6548 Add how to enable ATF, TEE and User defined ITS for U-Boot FIT image generation. Signed-off-by: Jamin Lin Reviewed-by: Antonin Godard --- 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. +- :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 `__ 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 `__. + :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE` + `Trusted Firmware-A (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 `__ 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 `__ 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.