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_MTE 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 232References 233========== 234 235.. _[1]: 236 237[1] `Arm Firmware Framework for Arm A-profile <https://developer.arm.com/docs/den0077/latest>`__ 238 239.. _[2]: 240 241[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>` 242 243.. _[3]: 244 245[3] https://hafnium.readthedocs.io/en/latest/secure-partition-manager/secure-partition-manager.html#secure-partitions-layout-file 246 247.. _[4]: 248 249[4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/lib/el3_runtime/aarch64/context.S#n45 250 251.. _[5]: 252 253[5] https://hafnium.readthedocs.io/en/latest/secure-partition-manager/index.html 254 255.. _[6]: 256 257[6] :ref:`EL3 Secure Partition Manager<EL3 Secure Partition Manager>` 258 259.. _[7]: 260 261[7] https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#dynamic-configuration-during-cold-boot 262 263-------------- 264 265*Copyright (c) 2020-2024, Arm Limited and Contributors. All rights reserved.* 266