From: Abdellatif El Khlifi <abdellatif.elkhl...@arm.com>
Add documentation
Signed-off-by: Abdellatif El Khlifi <abdellatif.elkhl...@arm.com>
Signed-off-by: Davidson kumaresan <davidson.kumare...@arm.com>
Cc: Heinrich Schuchardt <xypron.g...@gmx.de>
Cc: Sughosh Ganu <sughosh.g...@linaro.org>
Cc: Tom Rini <tr...@konsulko.com>
Cc: Ilias Apalodimas <ilias.apalodi...@linaro.org>
Cc: Simon Glass <s...@chromium.org>
Cc: Michal Simek <michal.si...@amd.com>
Cc: Marek Vasut <marek.vasut+rene...@mailbox.org>
Cc: Casey Connolly <casey.conno...@linaro.org>
Cc: Adriano Cordova <adria...@gmail.com>
---
Changelog of changes:
===========================
v2:
* As suggested by Heinrich: Removing the Corstone-1000 specific information
and addressing nits
v1:
* Add documentation
MAINTAINERS | 1 +
doc/develop/uefi/fwu_arm_psa.rst | 154 +++++++++++++++++++++++++++++++
doc/develop/uefi/index.rst | 1 +
3 files changed, 156 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.elkhl...@arm.com>
M: Davidson kumaresan <davidson.kumare...@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..8f27d31483b
--- /dev/null
+++ b/doc/develop/uefi/fwu_arm_psa.rst
@@ -0,0 +1,154 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2025 Arm Limited and/or its affiliates
<open-source-off...@arm.com>
+
+Firmware Update (FWU) Support for Arm PSA
+==========================================
+
+U-Boot implements Firmware Update (FWU) support for Arm `PSA Certified`_
+platforms.
+
+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, enable the following options in your board
+configuration:
+
+CONFIG_FWU_ARM_PSA
+ enables the PSA-compliant firmware update client in U-Boot.
+
+CONFIG_FWU_ARM_PSA_ACCEPT_IMAGES
+ enables auto-acceptance on ExitBootServices(). Disable this setting
+ if auto-acceptance shall be handled at a later boot stage.
+
+Platform Integration: Corstone-1000
+-----------------------------------
+
+`Corstone-1000`_ is the reference implementation for the FWU Arm PSA feature.
+
+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.elkhl...@arm.com>
+ * Davidson kumaresan <davidson.kumare...@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/
+.. _`Corstone-1000`:
https://corstone1000.docs.arm.com/en/latest/software-architecture.html
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
