[PATCH 25/25] fwu_arm_psa: Document FWU support for Arm PSA
Michal Simek
michal.simek at amd.com
Fri Jul 4 11:01:44 CEST 2025
On 7/2/25 17:25, abdellatif.elkhlifi at arm.com wrote:
> 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
Is there a way how to run this on Qemu/FVP or so to see how it is working?
Thanks,
Michal
More information about the U-Boot
mailing list