[PATCH 25/25] fwu_arm_psa: Document FWU support for Arm PSA
abdellatif.elkhlifi at arm.com
abdellatif.elkhlifi at arm.com
Wed Jul 2 17:25:28 CEST 2025
From: Abdellatif El Khlifi <abdellatif.elkhlifi at arm.com>
Add a README
Signed-off-by: Abdellatif El Khlifi <abdellatif.elkhlifi at arm.com>
Signed-off-by: Davidson kumaresan <davidson.kumaresan at arm.com>
Cc: Heinrich Schuchardt <xypron.glpk at gmx.de>
Cc: Sughosh Ganu <sughosh.ganu at linaro.org>
Cc: Tom Rini <trini at konsulko.com>
Cc: Ilias Apalodimas <ilias.apalodimas at linaro.org>
Cc: Simon Glass <sjg at chromium.org>
Cc: Michal Simek <michal.simek at amd.com>
Cc: Marek Vasut <marek.vasut+renesas at mailbox.org>
Cc: Casey Connolly <casey.connolly at linaro.org>
Cc: Adriano Cordova <adrianox at gmail.com>
---
MAINTAINERS | 1 +
doc/develop/uefi/fwu_arm_psa.rst | 153 +++++++++++++++++++++++++++++++
doc/develop/uefi/index.rst | 1 +
3 files changed, 155 insertions(+)
create mode 100644 doc/develop/uefi/fwu_arm_psa.rst
diff --git a/MAINTAINERS b/MAINTAINERS
index fdf34c74049..a75bc1d2379 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1231,6 +1231,7 @@ FWU ARM PSA
M: Abdellatif El Khlifi <abdellatif.elkhlifi at arm.com>
M: Davidson kumaresan <davidson.kumaresan at arm.com>
S: Maintained
+F: doc/develop/uefi/fwu_arm_psa.rst
F: include/fwu_arm_psa.h
F: lib/fwu_updates/fwu_arm_psa.c
diff --git a/doc/develop/uefi/fwu_arm_psa.rst b/doc/develop/uefi/fwu_arm_psa.rst
new file mode 100644
index 00000000000..f91fd85f573
--- /dev/null
+++ b/doc/develop/uefi/fwu_arm_psa.rst
@@ -0,0 +1,153 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2025 Arm Limited and/or its affiliates <open-source-office at arm.com>
+
+Firmware Update (FWU) Support for Arm PSA
+==========================================
+
+This README provides an overview of the Firmware Update (FWU) support
+implemented in U-Boot for Arm `PSA Certified`_ platforms, such as
+Corstone-1000. The feature aligns with the Platform Security Firmware Update
+specification for the A-profile Arm Architecture
+(see `DEN0118 v1.0 A specification`_) and leverages the Trusted Services (TS)
+framework to interact with Secure world update agent.
+
+Overview
+--------
+
+The FWU subsystem enables secure firmware updates by
+delegating the update management to a Secure world agent. U-Boot acts as the
+FWU client, coordinating updates via a well-defined set of ABIs over the FF-A
+interface (see :doc:`Arm FF-A Support <../../arch/arm64.ffa>`).
+
+FWU for Arm PSA supports both on-disk and standard capsule updates.
+
+Key Features
+------------
+
+1. PSA Firmware Update Initialization
+-------------------------------------
+
+- Initialization of the update agent using the FF-A transport and discovery of
+ the Trusted Services FWU SP.
+
+- Discovery of the version of the ABIs using FWU_DISCOVER ABI.
+
+- Establishment and sharing of communication buffers between U-Boot
+ (Normal world) and Secure world.
+
+2. ESRT Support
+---------------
+
+Retrieval of ESRT (EFI System Resource Table) data from Secure world using
+FWU_READ_STREAM ABI, enabling compliance with UEFI standards
+(see `UEFI v2.10 specification`_).
+
+3. UEFI Capsule Handling
+------------------------
+
+- Runtime checks for capsule flags as per UEFI 2.10 specification:
+
+ - CAPSULE_FLAGS_PERSIST_ACROSS_RESET
+
+ - CAPSULE_FLAGS_POPULATE_SYSTEM_TABLE
+
+ - CAPSULE_FLAGS_INITIATE_RESET
+
+- Support for keeping the FMP payload header in Arm PSA mode to preserve
+ critical metadata required by Secure world.
+
+4. Staging and Update Flow
+--------------------------
+
+- Full support for update staging flow as per PSA spec:
+
+ - FWU_BEGIN_STAGING
+
+ - FWU_END_STAGING
+
+ - FWU_CANCEL_STAGING
+
+ - FWU_WRITE_STREAM
+
+- Capsules can contain multiple payloads (including start/end markers
+ and the update content).
+
+5. Directory Access
+-------------------
+
+- Reading the FWU directory from Secure world using FWU_READ_STREAM ABI.
+
+6. Image Update Lifecycle
+-------------------------
+
+- Implementation of get_image_info() and set_image() using raw EFI firmware
+ services provided by the FMP driver for raw images.
+
+- FWU_ACCEPT_IMAGE ABI issued on ExitBootServices() to commit successfully
+ booted trial images.
+
+- Option to disable automatic acceptance on ExitBootServices() via
+ CONFIG_FWU_ARM_PSA_ACCEPT_IMAGES.
+
+Configuration Options
+---------------------
+
+To enable FWU support for Arm PSA, include the following options in your board
+configuration:
+
+CONFIG_FWU_ARM_PSA=y enables the PSA-compliant firmware update client in U-Boot.
+
+CONFIG_FWU_ARM_PSA_ACCEPT_IMAGES=y Enables auto-acceptance on
+ExitBootServices(). This option is enabled by default. It can be disabled if
+image acceptance should not be done at ExitBootServices().
+
+Platform Integration: Corstone-1000
+-----------------------------------
+
+- Corstone-1000 is the reference implementation for the FWU Arm PSA feature.
+
+- ESP partition detection is automated by setting Boot0001 in the U-Boot bootcmd.
+
+ABIs Implemented
+----------------
+
+The following ABIs from the PSA FWU specification have been implemented:
+
+ - FWU_DISCOVER
+
+ - FWU_BEGIN_STAGING
+
+ - FWU_END_STAGING
+
+ - FWU_CANCEL_STAGING
+
+ - FWU_OPEN
+
+ - FWU_WRITE_STREAM
+
+ - FWU_READ_STREAM
+
+ - FWU_COMMIT
+
+ - FWU_ACCEPT_IMAGE
+
+ExitBootServices() Integration
+------------------------------
+
+- The U-Boot FWU client performs several key actions during ExitBootServices():
+
+- Notifies Secure world about successful boot.
+
+- Accepts updated images in trial state.
+
+- Supports board-level override of fwu_notify_exit_boot_services() for custom
+ behavior.
+
+Contributors
+------------
+ * Abdellatif El Khlifi <abdellatif.elkhlifi at arm.com>
+ * Davidson kumaresan <davidson.kumaresan at arm.com>
+
+.. _`DEN0118 v1.0 A specification`: https://developer.arm.com/documentation/den0118/latest/
+.. _`PSA Certified`: https://www.psacertified.org/
+.. _`UEFI v2.10 specification`: https://uefi.org/specs/UEFI/2.10/
diff --git a/doc/develop/uefi/index.rst b/doc/develop/uefi/index.rst
index e26b1fbe05c..573630740a0 100644
--- a/doc/develop/uefi/index.rst
+++ b/doc/develop/uefi/index.rst
@@ -10,6 +10,7 @@ can be run an UEFI payload.
.. toctree::
:maxdepth: 2
+ fwu_arm_psa.rst
uefi.rst
u-boot_on_efi.rst
iscsi.rst
--
2.25.1
More information about the U-Boot
mailing list