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 TRUSTED_BOARD_BOOT=1 \ 172 COT=dualroot \ 173 ARM_ROTPK_LOCATION=devel_rsa \ 174 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ 175 GENERATE_COT=1 \ 176 all fip 177 178Sample TF-A build command line when the SPMC is located at EL3: 179 180.. code:: shell 181 182 make \ 183 CROSS_COMPILE=aarch64-none-elf- \ 184 SPD=spmd \ 185 SPMD_SPM_AT_SEL2=0 \ 186 SPMC_AT_EL3=1 \ 187 BL32=<path-to-tee-binary> \ 188 BL33=<path-to-bl33-binary> \ 189 PLAT=fvp \ 190 all fip 191 192Sample TF-A build command line when the SPMC is located at EL3 and SEL0 SP is 193enabled: 194 195.. code:: shell 196 197 make \ 198 CROSS_COMPILE=aarch64-none-elf- \ 199 SPD=spmd \ 200 SPMD_SPM_AT_SEL2=0 \ 201 SPMC_AT_EL3=1 \ 202 SPMC_AT_EL3_SEL0_SP=1 \ 203 BL32=<path-to-tee-binary> \ 204 BL33=<path-to-bl33-binary> \ 205 PLAT=fvp \ 206 all fip 207 208Boot process 209============ 210 211The boot process involving SPMC is highly dependent on the SPMC implementation. 212It is recommended to refer to corresponding SPMC documentation for further 213details. Some aspects of boot process are described here in the greater interest 214of the project. 215 216SPMC boot 217--------- 218 219When SPMC resides at a lower EL i.e., S-EL1 or S-EL2, it is loaded by BL2 as the 220BL32 image. The SPMC manifest is loaded by BL2 as the ``TOS_FW_CONFIG`` image `[7]`_. 221 222BL2 passes the SPMC manifest address to BL31 through a register. At boot time, 223the SPMD in BL31 runs from the primary core, initializes the core contexts and 224launches the SPMC (BL32) passing the following information through registers: 225 226- X0 holds the ``TOS_FW_CONFIG`` physical address (or SPMC manifest blob). 227- X1 holds the ``HW_CONFIG`` physical address. 228- X4 holds the currently running core linear id. 229 230 231Support for Secure Partition live activation 232============================================ 233 234Live firmware activation, defined in the LFA spec `[9]`_, is implemented by the 235agent framework in TF-A BL31. The framework handles the LFA SMCs and expects 236each platform to describe every activatable firmware component (BL31, RMM, 237Secure Partitions, etc.) through a set of callbacks. Secure Partitions (SPs) 238require additional oversight because they are managed by the Secure Partition 239Manager Core (SPMC) through FF-A. 240 241Consequently, TF-A shall implement Logical Secure Partition (LSP) 242managed by SPMD at EL3 that bridges the LFA calls to FF-A framework messages 243understood by the SPMC. Note that support for live activation is limited to 244v1.3 compliant Secure Partitions with single execution context and managed by 245S-EL2 SPMC. 246 247A typical Secure Partition is highly platform specific given the way it is 248integrated by an OEM; every platform decides which SP packages are bundled in 249the FIP, how and where the new SP images are staged and so on. 250Therefore, the LSP in TF-A project needs to be independently implemented by 251the platform port based on the guidance in FF-A specification. TF-A code base 252supplies reusable helpers in ``services/std_svc/spmd/spmd_logical_sp.c``. 253 254 255Live Firmware Activation LSP responsibilities 256--------------------------------------------- 257 258An LSP must implement the ``prime`` and ``activate`` callbacks for the LFA 259framework to execute SP live activation. At a minimum, an LSP must: 260 261- Implement the platform-specific steps needed to stage a new partition package 262 for SP. 263- Perform partition discovery and ensure the partition properties are suitable 264 for live activation. 265- Translate ``LFA_ACTIVATE`` into the FF-A framework messages defined by 266 FF-A v1.3 ALP2: ``FFA_FRAMEWORK_MSG_LIVE_ACTIVATION_START_REQ`` followed by 267 ``FFA_FRAMEWORK_MSG_LIVE_ACTIVATION_FINISH_REQ``. The SPMC at S-EL2 then 268 performs the in-place activation and responds with SUCCESS status code to 269 the corresponding framework messages. 270 271Reference implementation 272------------------------ 273 274The Arm FVP port implements all of the above in: 275 276- ``plat/arm/board/fvp/fvp_lfa.c`` – enumerates components and ties them to LFA. 277- ``plat/arm/board/fvp/fvp_spmd_logical_sp.c`` – provides the logical 278 partition, prime/activate callbacks, and staging logic. 279- ``services/std_svc/spmd/spmd_logical_sp.c`` – common helpers that build and 280 parse the FF-A framework messages on behalf of the platform LSP. 281 282Platforms that wish to add live activation for their own SPs can use the FVP 283code as a template, customize the staging strategy and component table, and 284ensure that the SP manifests include the live activation properties documented 285in the FF-A manifest binding (`docs/components/ffa-manifest-binding.rst`). 286Secure Partition live activation is guarded by few build options `[8]`_. 287 288References 289========== 290 291.. _[1]: 292 293[1] `Arm Firmware Framework for Arm A-profile <https://developer.arm.com/docs/den0077/latest>`__ 294 295.. _[2]: 296 297[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>` 298 299.. _[3]: 300 301[3] https://hafnium.readthedocs.io/en/latest/secure-partition-manager/secure-partition-manager.html#secure-partitions-layout-file 302 303.. _[4]: 304 305[4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/lib/el3_runtime/aarch64/context.S#n45 306 307.. _[5]: 308 309[5] https://hafnium.readthedocs.io/en/latest/secure-partition-manager/index.html 310 311.. _[6]: 312 313[6] :ref:`EL3 Secure Partition Manager<EL3 Secure Partition Manager>` 314 315.. _[7]: 316 317[7] https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#dynamic-configuration-during-cold-boot 318 319.. _[8]: 320 321[8] :ref:`SP Live Activation build options<sp_live_activation_build_options>` 322 323.. _[9]: 324 325[9] https://developer.arm.com/documentation/den0147/1-0bet1/?lang=en 326 327---- 328 329*Copyright (c) 2020-2026, Arm Limited and Contributors. All rights reserved.* 330