..
 # SPDX-FileCopyrightText: <text>Copyright 2025-2026 Arm Limited and/or its
 # affiliates <open-source-office@arm.com></text>
 #
 # SPDX-License-Identifier: MIT

.. _design_secure_firmware_update:

######################
Secure Firmware Update
######################

************
Introduction
************

The Reference Software Stack implements Secure Firmware Update (Secure FWU)
following the :link_subs:`common:plat-sec-fu`,
:link_subs:`common:uefi-specification` and
:link_subs:`common:psa-cert-fwu-api`.
Secure Firmware Update provides two configurations with the following
firmware images included in them:

RD-Aspen CFG1:

  * RSE BL2 image
  * RSE Runtime image
  * SCP-Firmware image
  * TF-A Firmware Image Package (FIP) image

RD-Aspen CFG2:

  * RSE BL2 image
  * RSE Runtime image
  * SCP-Firmware image
  * TF-A FIP image
  * Safety Island Cluster 1 (SI CL1) image

The new images are packaged within a UEFI capsule. RD-Aspen enables UEFI
capsule generation, UEFI capsule update and the capsule authentication
features.

.. _design_secure_firmware_update_architecture:

************
Architecture
************

As standardized in the :link_subs:`common:plat-sec-fu` and
:link_subs:`common:psa-cert-fwu-api`, each one of the RSE flash and AP secure
flash is divided into two banks, where one bank has the currently running
images and the other bank is used for storing new images. See the
``ap-flash-image`` and ``rse-flash-image`` in the :ref:`rd-aspen_images_layout`
section for details about how A/B firmware image banks are arranged.

RD-Aspen Secure FWU maintains 2 types of metadata in the Secure Flash to track
the firmware update states.

  - FWU metadata: Defined in :link_subs:`common:plat-sec-fu`. RSE updates
    FWU metadata to share firmware update states with AP bootloader.
  - FWU Private metadata: Used by RSE to track and manage the firmware update,
    including the image bank selection.

The following diagram illustrates the components and data flow that implement
the Secure Firmware Update:

|

.. figure:: ../images/secure_firmware_update.*
   :align: center
   :alt: Secure Firmware Update Architecture

   Secure Firmware Update Architecture

|

A typical Secure Firmware Update process can be described in the
following steps:

  1. The capsule image is generated by the EDK2 ``GenerateCapsule`` tool.
     Extra arguments for capsule generation can be defined using
     ``CAPSULE_EXTRA_ARGS`` and path to the private key for signing the capsule
     can be set using ``CAPSULE_PRIV_KEY_FILE`` as described in
     :ref:`build_env_vars`.
  2. The capsule file is stored in VirtIO block 1. After the capsule file is
     copied to the ``EFI/UpdateCapsule`` directory on VirtIO block 0, U-Boot
     will detect this capsule file in the next reboot.
  3. For each image payload in the capsule, U-Boot verifies the image using the
     public key certificate which is built-in into U-boot and is provided by
     ``CONFIG_EFI_CAPSULE_CRT_FILE`` and transfers the image data to the
     Trusted Services SE-Proxy Firmware Update proxy using the
     :link_subs:`common:plat-sec-fu` ABI.
  4. Trusted Services FWU Proxy forwards the request to RSE, using the API
     defined in :link_subs:`common:psa-cert-fwu-api`.
  5. The RSE Firmware Update Secure Partition receives the firmware image data
     and writes it to the update bank in the Secure Flash. Once the complete image
     data is received, RSE validates the version and updates the metadata.
     The system will attempt to boot with the new firmware images in the next
     reboot.
  6. If the system boots up successfully with the new firmware images, U-Boot
     will accept the new images resulting in a successful capsule update.