1Secure Partition Manager 2************************ 3 4.. contents:: 5 6.. toctree:: 7 ffa-manifest-binding 8 9Acronyms 10======== 11 12+--------+--------------------------------------+ 13| DTS | Device Tree Source | 14+--------+--------------------------------------+ 15| FF-A | Firmware Framework for Arm A-profile | 16+--------+--------------------------------------+ 17| NWd | Normal World | 18+--------+--------------------------------------+ 19| SP | Secure Partition | 20+--------+--------------------------------------+ 21| SPD | Secure Payload Dispatcher | 22+--------+--------------------------------------+ 23| SPM | Secure Partition Manager | 24+--------+--------------------------------------+ 25| SPMC | SPM Core | 26+--------+--------------------------------------+ 27| SPMD | SPM Dispatcher | 28+--------+--------------------------------------+ 29| SWd | Secure World | 30+--------+--------------------------------------+ 31 32Foreword 33======== 34 35Three implementations of a Secure Partition Manager co-exist in the TF-A 36codebase: 37 38#. S-EL2 SPMC based on the FF-A specification `[1]`_, enabling virtualization in 39 the secure world, managing multiple S-EL1 or S-EL0 partitions `[5]`_. 40#. EL3 SPMC based on the FF-A specification, managing a single S-EL1 partition 41 without virtualization in the secure world `[6]`_. 42#. EL3 SPM based on the MM specification, legacy implementation managing a 43 single S-EL0 partition `[2]`_. 44 45These implementations differ in their respective SW architecture and only one 46can be selected at build time. 47 48Support for legacy platforms 49---------------------------- 50 51The SPM is split into a dispatcher and a core component (respectively SPMD and 52SPMC) residing at different exception levels. To permit the FF-A specification 53adoption and a smooth migration, the SPMD supports an SPMC residing either at 54S-EL1 or S-EL2: 55 56- The SPMD is located at EL3 and mainly relays the FF-A protocol from NWd 57 (Hypervisor or OS kernel) to the SPMC. 58- The same SPMD component is used for both S-EL1 and S-EL2 SPMC configurations. 59- The SPMC exception level is a build time choice. 60 61TF-A supports both cases: 62 63- S-EL1 SPMC for platforms not supporting the FEAT_SEL2 architecture 64 extension. The SPMD relays the FF-A protocol from EL3 to S-EL1. 65- S-EL2 SPMC for platforms implementing the FEAT_SEL2 architecture 66 extension. The SPMD relays the FF-A protocol from EL3 to S-EL2. 67 68TF-A build options 69================== 70 71This section explains the TF-A build options involved in building with 72support for an FF-A based SPM where the SPMD is located at EL3 and the 73SPMC located at S-EL1, S-EL2 or EL3: 74 75- **SPD=spmd**: this option selects the SPMD component to relay the FF-A 76 protocol from NWd to SWd back and forth. It is not possible to 77 enable another Secure Payload Dispatcher when this option is chosen. 78- **SPMD_SPM_AT_SEL2**: this option adjusts the SPMC exception 79 level to being at S-EL2. It defaults to enabled (value 1) when 80 SPD=spmd is chosen. 81- **SPMC_AT_EL3**: this option adjusts the SPMC exception level to being 82 at EL3. If neither ``SPMD_SPM_AT_SEL2`` or ``SPMC_AT_EL3`` are enabled the 83 SPMC exception level is set to S-EL1. 84 ``SPMD_SPM_AT_SEL2`` is enabled. The context save/restore routine 85 and exhaustive list of registers is visible at `[4]`_. 86- **SPMC_AT_EL3_SEL0_SP**: this option enables the support to load SEL0 SP 87 when SPMC at EL3 support is enabled. 88- **SP_LAYOUT_FILE**: this option specifies a text description file 89 providing paths to SP binary images and manifests in DTS format 90 (see `[3]`_). It 91 is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple 92 secure partitions are to be loaded by BL2 on behalf of the SPMC. 93 94+---------------+------------------+-------------+-------------------------+ 95| | SPMD_SPM_AT_SEL2 | SPMC_AT_EL3 | CTX_INCLUDE_EL2_REGS(*) | 96+---------------+------------------+-------------+-------------------------+ 97| SPMC at S-EL1 | 0 | 0 | 0 | 98+---------------+------------------+-------------+-------------------------+ 99| SPMC at S-EL2 | 1 (default when | 0 | 1 | 100| | SPD=spmd) | | | 101+---------------+------------------+-------------+-------------------------+ 102| SPMC at EL3 | 0 | 1 | 0 | 103+---------------+------------------+-------------+-------------------------+ 104 105Other combinations of such build options either break the build or are not 106supported. 107 108Notes: 109 110- Only Arm's FVP platform is supported to use with the TF-A reference software 111 stack. 112- When ``SPMD_SPM_AT_SEL2=1``, the reference software stack assumes enablement 113 of FEAT_PAuth, FEAT_BTI and FEAT_MTE2 architecture extensions. 114- ``(*) CTX_INCLUDE_EL2_REGS``, this flag is |TF-A| internal and informational 115 in this table. When set, it provides the generic support for saving/restoring 116 EL2 registers required when S-EL2 firmware is present. 117- BL32 option is re-purposed to specify the SPMC image. It can specify either 118 the Hafnium binary path (built for the secure world) or the path to a TEE 119 binary implementing FF-A interfaces. 120- BL33 option can specify the TFTF binary or a normal world loader 121 such as U-Boot or the UEFI framework payload. 122 123Sample TF-A build command line when the SPMC is located at S-EL1 124(e.g. when the FEAT_SEL2 architecture extension is not implemented): 125 126.. code:: shell 127 128 make \ 129 CROSS_COMPILE=aarch64-none-elf- \ 130 SPD=spmd \ 131 SPMD_SPM_AT_SEL2=0 \ 132 BL32=<path-to-tee-binary> \ 133 BL33=<path-to-bl33-binary> \ 134 PLAT=fvp \ 135 all fip 136 137Sample TF-A build command line when FEAT_SEL2 architecture extension is 138implemented and the SPMC is located at S-EL2: 139 140.. code:: shell 141 142 make \ 143 CROSS_COMPILE=aarch64-none-elf- \ 144 PLAT=fvp \ 145 SPD=spmd \ 146 ARM_ARCH_MINOR=5 \ 147 BRANCH_PROTECTION=1 \ 148 CTX_INCLUDE_PAUTH_REGS=1 \ 149 ENABLE_FEAT_MTE2=1 \ 150 BL32=<path-to-hafnium-binary> \ 151 BL33=<path-to-bl33-binary> \ 152 SP_LAYOUT_FILE=sp_layout.json \ 153 all fip 154 155Sample TF-A build command line when FEAT_SEL2 architecture extension is 156implemented, the SPMC is located at S-EL2, and enabling secure boot: 157 158.. code:: shell 159 160 make \ 161 CROSS_COMPILE=aarch64-none-elf- \ 162 PLAT=fvp \ 163 SPD=spmd \ 164 ARM_ARCH_MINOR=5 \ 165 BRANCH_PROTECTION=1 \ 166 CTX_INCLUDE_PAUTH_REGS=1 \ 167 ENABLE_FEAT_MTE2=1 \ 168 BL32=<path-to-hafnium-binary> \ 169 BL33=<path-to-bl33-binary> \ 170 SP_LAYOUT_FILE=sp_layout.json \ 171 MBEDTLS_DIR=<path-to-mbedtls-lib> \ 172 TRUSTED_BOARD_BOOT=1 \ 173 COT=dualroot \ 174 ARM_ROTPK_LOCATION=devel_rsa \ 175 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ 176 GENERATE_COT=1 \ 177 all fip 178 179Sample TF-A build command line when the SPMC is located at EL3: 180 181.. code:: shell 182 183 make \ 184 CROSS_COMPILE=aarch64-none-elf- \ 185 SPD=spmd \ 186 SPMD_SPM_AT_SEL2=0 \ 187 SPMC_AT_EL3=1 \ 188 BL32=<path-to-tee-binary> \ 189 BL33=<path-to-bl33-binary> \ 190 PLAT=fvp \ 191 all fip 192 193Sample TF-A build command line when the SPMC is located at EL3 and SEL0 SP is 194enabled: 195 196.. code:: shell 197 198 make \ 199 CROSS_COMPILE=aarch64-none-elf- \ 200 SPD=spmd \ 201 SPMD_SPM_AT_SEL2=0 \ 202 SPMC_AT_EL3=1 \ 203 SPMC_AT_EL3_SEL0_SP=1 \ 204 BL32=<path-to-tee-binary> \ 205 BL33=<path-to-bl33-binary> \ 206 PLAT=fvp \ 207 all fip 208 209Boot process 210============ 211 212The boot process involving SPMC is highly dependent on the SPMC implementation. 213It is recommended to refer to corresponding SPMC documentation for further 214details. Some aspects of boot process are described here in the greater interest 215of the project. 216 217SPMC boot 218--------- 219 220When SPMC resides at a lower EL i.e., S-EL1 or S-EL2, it is loaded by BL2 as the 221BL32 image. The SPMC manifest is loaded by BL2 as the ``TOS_FW_CONFIG`` image `[7]`_. 222 223BL2 passes the SPMC manifest address to BL31 through a register. At boot time, 224the SPMD in BL31 runs from the primary core, initializes the core contexts and 225launches the SPMC (BL32) passing the following information through registers: 226 227- X0 holds the ``TOS_FW_CONFIG`` physical address (or SPMC manifest blob). 228- X1 holds the ``HW_CONFIG`` physical address. 229- X4 holds the currently running core linear id. 230 231 232Support for Secure Partition live activation 233============================================ 234 235Live firmware activation, defined in the LFA spec `[9]`_, is implemented by the 236agent framework in TF-A BL31. The framework handles the LFA SMCs and expects 237each platform to describe every activatable firmware component (BL31, RMM, 238Secure Partitions, etc.) through a set of callbacks. Secure Partitions (SPs) 239require additional oversight because they are managed by the Secure Partition 240Manager Core (SPMC) through FF-A. 241 242Consequently, TF-A shall implement Logical Secure Partition (LSP) 243managed by SPMD at EL3 that bridges the LFA calls to FF-A framework messages 244understood by the SPMC. Note that support for live activation is limited to 245v1.3 compliant Secure Partitions with single execution context and managed by 246S-EL2 SPMC. 247 248A typical Secure Partition is highly platform specific given the way it is 249integrated by an OEM; every platform decides which SP packages are bundled in 250the FIP, how and where the new SP images are staged and so on. 251Therefore, the LSP in TF-A project needs to be independently implemented by 252the platform port based on the guidance in FF-A specification. TF-A code base 253supplies reusable helpers in ``services/std_svc/spmd/spmd_logical_sp.c``. 254 255 256Live Firmware Activation LSP responsibilities 257--------------------------------------------- 258 259An LSP must implement the ``prime`` and ``activate`` callbacks for the LFA 260framework to execute SP live activation. At a minimum, an LSP must: 261 262- Implement the platform-specific steps needed to stage a new partition package 263 for SP. 264- Perform partition discovery and ensure the partition properties are suitable 265 for live activation. 266- Translate ``LFA_ACTIVATE`` into the FF-A framework messages defined by 267 FF-A v1.3 ALP2: ``FFA_FRAMEWORK_MSG_LIVE_ACTIVATION_START_REQ`` followed by 268 ``FFA_FRAMEWORK_MSG_LIVE_ACTIVATION_FINISH_REQ``. The SPMC at S-EL2 then 269 performs the in-place activation and responds with SUCCESS status code to 270 the corresponding framework messages. 271 272Reference implementation 273------------------------ 274 275The Arm FVP port implements all of the above in: 276 277- ``plat/arm/board/fvp/fvp_lfa.c`` – enumerates components and ties them to LFA. 278- ``plat/arm/board/fvp/fvp_spmd_logical_sp.c`` – provides the logical 279 partition, prime/activate callbacks, and staging logic. 280- ``services/std_svc/spmd/spmd_logical_sp.c`` – common helpers that build and 281 parse the FF-A framework messages on behalf of the platform LSP. 282 283Platforms that wish to add live activation for their own SPs can use the FVP 284code as a template, customize the staging strategy and component table, and 285ensure that the SP manifests include the live activation properties documented 286in the FF-A manifest binding (`docs/components/ffa-manifest-binding.rst`). 287Secure Partition live activation is guarded by few build options `[8]`_. 288 289References 290========== 291 292.. _[1]: 293 294[1] `Arm Firmware Framework for Arm A-profile <https://developer.arm.com/docs/den0077/latest>`__ 295 296.. _[2]: 297 298[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>` 299 300.. _[3]: 301 302[3] https://hafnium.readthedocs.io/en/latest/secure-partition-manager/secure-partition-manager.html#secure-partitions-layout-file 303 304.. _[4]: 305 306[4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/lib/el3_runtime/aarch64/context.S#n45 307 308.. _[5]: 309 310[5] https://hafnium.readthedocs.io/en/latest/secure-partition-manager/index.html 311 312.. _[6]: 313 314[6] :ref:`EL3 Secure Partition Manager<EL3 Secure Partition Manager>` 315 316.. _[7]: 317 318[7] https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#dynamic-configuration-during-cold-boot 319 320.. _[8]: 321 322[8] :ref:`SP Live Activation build options<sp_live_activation_build_options>` 323 324.. _[9]: 325 326[9] https://developer.arm.com/documentation/den0147/1-0bet1/?lang=en 327 328---- 329 330*Copyright (c) 2020-2026, Arm Limited and Contributors. All rights reserved.* 331