[PATCH 25/25] fwu_arm_psa: Document FWU support for Arm PSA
Heinrich Schuchardt
xypron.glpk at gmx.de
Fri Jul 4 14:01:50 CEST 2025
On 02.07.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
There is no README here. How about:
U-Boot implements Firmware Update (FWU) support for Arm `PSA Certified`_
platforms.
> +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.
Please, use a formatting that lets the config parameters stick out:
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.
> +
> +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().
Enabled by default implies that it can be disabled.
"if .. should not be done" conveys no new information.
> +
> +Platform Integration: Corstone-1000
> +-----------------------------------
> +
> +- Corstone-1000 is the reference implementation for the FWU Arm PSA feature.
A link to the board page should be good enough.
What is implemented for a specific board should be described there.
> +
> +- ESP partition detection is automated by setting Boot0001 in the U-Boot bootcmd.
Please, state that you mean the environment variable bootcmd. How about
altbootcmd?
What would the variable bootcmd look like?
It is unclear to me which part of the information above is board
specific and which is not.
Best regards
Heinrich
> +
> +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
More information about the U-Boot
mailing list