Secure Partition Manager ************************ .. contents:: .. toctree:: ffa-manifest-binding Acronyms ======== +--------+--------------------------------------+ | DTS | Device Tree Source | +--------+--------------------------------------+ | FF-A | Firmware Framework for Arm A-profile | +--------+--------------------------------------+ | NWd | Normal World | +--------+--------------------------------------+ | SP | Secure Partition | +--------+--------------------------------------+ | SPD | Secure Payload Dispatcher | +--------+--------------------------------------+ | SPM | Secure Partition Manager | +--------+--------------------------------------+ | SPMC | SPM Core | +--------+--------------------------------------+ | SPMD | SPM Dispatcher | +--------+--------------------------------------+ | SWd | Secure World | +--------+--------------------------------------+ Foreword ======== Three implementations of a Secure Partition Manager co-exist in the TF-A codebase: #. S-EL2 SPMC based on the FF-A specification `[1]`_, enabling virtualization in the secure world, managing multiple S-EL1 or S-EL0 partitions `[5]`_. #. EL3 SPMC based on the FF-A specification, managing a single S-EL1 partition without virtualization in the secure world `[6]`_. #. EL3 SPM based on the MM specification, legacy implementation managing a single S-EL0 partition `[2]`_. These implementations differ in their respective SW architecture and only one can be selected at build time. Support for legacy platforms ---------------------------- The SPM is split into a dispatcher and a core component (respectively SPMD and SPMC) residing at different exception levels. To permit the FF-A specification adoption and a smooth migration, the SPMD supports an SPMC residing either at S-EL1 or S-EL2: - The SPMD is located at EL3 and mainly relays the FF-A protocol from NWd (Hypervisor or OS kernel) to the SPMC. - The same SPMD component is used for both S-EL1 and S-EL2 SPMC configurations. - The SPMC exception level is a build time choice. TF-A supports both cases: - S-EL1 SPMC for platforms not supporting the FEAT_SEL2 architecture extension. The SPMD relays the FF-A protocol from EL3 to S-EL1. - S-EL2 SPMC for platforms implementing the FEAT_SEL2 architecture extension. The SPMD relays the FF-A protocol from EL3 to S-EL2. TF-A build options ================== This section explains the TF-A build options involved in building with support for an FF-A based SPM where the SPMD is located at EL3 and the SPMC located at S-EL1, S-EL2 or EL3: - **SPD=spmd**: this option selects the SPMD component to relay the FF-A protocol from NWd to SWd back and forth. It is not possible to enable another Secure Payload Dispatcher when this option is chosen. - **SPMD_SPM_AT_SEL2**: this option adjusts the SPMC exception level to being at S-EL2. It defaults to enabled (value 1) when SPD=spmd is chosen. - **SPMC_AT_EL3**: this option adjusts the SPMC exception level to being at EL3. If neither ``SPMD_SPM_AT_SEL2`` or ``SPMC_AT_EL3`` are enabled the SPMC exception level is set to S-EL1. ``SPMD_SPM_AT_SEL2`` is enabled. The context save/restore routine and exhaustive list of registers is visible at `[4]`_. - **SPMC_AT_EL3_SEL0_SP**: this option enables the support to load SEL0 SP when SPMC at EL3 support is enabled. - **SP_LAYOUT_FILE**: this option specifies a text description file providing paths to SP binary images and manifests in DTS format (see `[3]`_). It is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple secure partitions are to be loaded by BL2 on behalf of the SPMC. +---------------+------------------+-------------+-------------------------+ | | SPMD_SPM_AT_SEL2 | SPMC_AT_EL3 | CTX_INCLUDE_EL2_REGS(*) | +---------------+------------------+-------------+-------------------------+ | SPMC at S-EL1 | 0 | 0 | 0 | +---------------+------------------+-------------+-------------------------+ | SPMC at S-EL2 | 1 (default when | 0 | 1 | | | SPD=spmd) | | | +---------------+------------------+-------------+-------------------------+ | SPMC at EL3 | 0 | 1 | 0 | +---------------+------------------+-------------+-------------------------+ Other combinations of such build options either break the build or are not supported. Notes: - Only Arm's FVP platform is supported to use with the TF-A reference software stack. - When ``SPMD_SPM_AT_SEL2=1``, the reference software stack assumes enablement of FEAT_PAuth, FEAT_BTI and FEAT_MTE2 architecture extensions. - ``(*) CTX_INCLUDE_EL2_REGS``, this flag is |TF-A| internal and informational in this table. When set, it provides the generic support for saving/restoring EL2 registers required when S-EL2 firmware is present. - BL32 option is re-purposed to specify the SPMC image. It can specify either the Hafnium binary path (built for the secure world) or the path to a TEE binary implementing FF-A interfaces. - BL33 option can specify the TFTF binary or a normal world loader such as U-Boot or the UEFI framework payload. Sample TF-A build command line when the SPMC is located at S-EL1 (e.g. when the FEAT_SEL2 architecture extension is not implemented): .. code:: shell make \ CROSS_COMPILE=aarch64-none-elf- \ SPD=spmd \ SPMD_SPM_AT_SEL2=0 \ BL32= \ BL33= \ PLAT=fvp \ all fip Sample TF-A build command line when FEAT_SEL2 architecture extension is implemented and the SPMC is located at S-EL2: .. code:: shell make \ CROSS_COMPILE=aarch64-none-elf- \ PLAT=fvp \ SPD=spmd \ ARM_ARCH_MINOR=5 \ BRANCH_PROTECTION=1 \ CTX_INCLUDE_PAUTH_REGS=1 \ ENABLE_FEAT_MTE2=1 \ BL32= \ BL33= \ SP_LAYOUT_FILE=sp_layout.json \ all fip Sample TF-A build command line when FEAT_SEL2 architecture extension is implemented, the SPMC is located at S-EL2, and enabling secure boot: .. code:: shell make \ CROSS_COMPILE=aarch64-none-elf- \ PLAT=fvp \ SPD=spmd \ ARM_ARCH_MINOR=5 \ BRANCH_PROTECTION=1 \ CTX_INCLUDE_PAUTH_REGS=1 \ ENABLE_FEAT_MTE2=1 \ BL32= \ BL33= \ SP_LAYOUT_FILE=sp_layout.json \ MBEDTLS_DIR= \ TRUSTED_BOARD_BOOT=1 \ COT=dualroot \ ARM_ROTPK_LOCATION=devel_rsa \ ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ GENERATE_COT=1 \ all fip Sample TF-A build command line when the SPMC is located at EL3: .. code:: shell make \ CROSS_COMPILE=aarch64-none-elf- \ SPD=spmd \ SPMD_SPM_AT_SEL2=0 \ SPMC_AT_EL3=1 \ BL32= \ BL33= \ PLAT=fvp \ all fip Sample TF-A build command line when the SPMC is located at EL3 and SEL0 SP is enabled: .. code:: shell make \ CROSS_COMPILE=aarch64-none-elf- \ SPD=spmd \ SPMD_SPM_AT_SEL2=0 \ SPMC_AT_EL3=1 \ SPMC_AT_EL3_SEL0_SP=1 \ BL32= \ BL33= \ PLAT=fvp \ all fip Boot process ============ The boot process involving SPMC is highly dependent on the SPMC implementation. It is recommended to refer to corresponding SPMC documentation for further details. Some aspects of boot process are described here in the greater interest of the project. SPMC boot --------- When SPMC resides at a lower EL i.e., S-EL1 or S-EL2, it is loaded by BL2 as the BL32 image. The SPMC manifest is loaded by BL2 as the ``TOS_FW_CONFIG`` image `[7]`_. BL2 passes the SPMC manifest address to BL31 through a register. At boot time, the SPMD in BL31 runs from the primary core, initializes the core contexts and launches the SPMC (BL32) passing the following information through registers: - X0 holds the ``TOS_FW_CONFIG`` physical address (or SPMC manifest blob). - X1 holds the ``HW_CONFIG`` physical address. - X4 holds the currently running core linear id. Support for Secure Partition live activation ============================================ Live firmware activation, defined in the LFA spec `[9]`_, is implemented by the agent framework in TF-A BL31. The framework handles the LFA SMCs and expects each platform to describe every activatable firmware component (BL31, RMM, Secure Partitions, etc.) through a set of callbacks. Secure Partitions (SPs) require additional oversight because they are managed by the Secure Partition Manager Core (SPMC) through FF-A. Consequently, TF-A shall implement Logical Secure Partition (LSP) managed by SPMD at EL3 that bridges the LFA calls to FF-A framework messages understood by the SPMC. Note that support for live activation is limited to v1.3 compliant Secure Partitions with single execution context and managed by S-EL2 SPMC. A typical Secure Partition is highly platform specific given the way it is integrated by an OEM; every platform decides which SP packages are bundled in the FIP, how and where the new SP images are staged and so on. Therefore, the LSP in TF-A project needs to be independently implemented by the platform port based on the guidance in FF-A specification. TF-A code base supplies reusable helpers in ``services/std_svc/spmd/spmd_logical_sp.c``. Live Firmware Activation LSP responsibilities --------------------------------------------- An LSP must implement the ``prime`` and ``activate`` callbacks for the LFA framework to execute SP live activation. At a minimum, an LSP must: - Implement the platform-specific steps needed to stage a new partition package for SP. - Perform partition discovery and ensure the partition properties are suitable for live activation. - Translate ``LFA_ACTIVATE`` into the FF-A framework messages defined by FF-A v1.3 ALP2: ``FFA_FRAMEWORK_MSG_LIVE_ACTIVATION_START_REQ`` followed by ``FFA_FRAMEWORK_MSG_LIVE_ACTIVATION_FINISH_REQ``. The SPMC at S-EL2 then performs the in-place activation and responds with SUCCESS status code to the corresponding framework messages. Reference implementation ------------------------ The Arm FVP port implements all of the above in: - ``plat/arm/board/fvp/fvp_lfa.c`` – enumerates components and ties them to LFA. - ``plat/arm/board/fvp/fvp_spmd_logical_sp.c`` – provides the logical partition, prime/activate callbacks, and staging logic. - ``services/std_svc/spmd/spmd_logical_sp.c`` – common helpers that build and parse the FF-A framework messages on behalf of the platform LSP. Platforms that wish to add live activation for their own SPs can use the FVP code as a template, customize the staging strategy and component table, and ensure that the SP manifests include the live activation properties documented in the FF-A manifest binding (`docs/components/ffa-manifest-binding.rst`). Secure Partition live activation is guarded by few build options `[8]`_. References ========== .. _[1]: [1] `Arm Firmware Framework for Arm A-profile `__ .. _[2]: [2] :ref:`Secure Partition Manager using MM interface` .. _[3]: [3] https://hafnium.readthedocs.io/en/latest/secure-partition-manager/secure-partition-manager.html#secure-partitions-layout-file .. _[4]: [4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/lib/el3_runtime/aarch64/context.S#n45 .. _[5]: [5] https://hafnium.readthedocs.io/en/latest/secure-partition-manager/index.html .. _[6]: [6] :ref:`EL3 Secure Partition Manager` .. _[7]: [7] https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#dynamic-configuration-during-cold-boot .. _[8]: [8] :ref:`SP Live Activation build options` .. _[9]: [9] https://developer.arm.com/documentation/den0147/1-0bet1/?lang=en ---- *Copyright (c) 2020-2026, Arm Limited and Contributors. All rights reserved.*