blob: 18d870bdcafd8bd86f9206c4e6c4429c60ec077f [file] [log] [blame]
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001Secure Partition Manager
2************************
3
4.. contents::
5
Olivier Deprez3de57e32022-04-28 18:18:36 +02006.. toctree::
7 ffa-manifest-binding
8
Olivier Deprezecb2fe52020-04-02 15:38:02 +02009Acronyms
10========
11
Olivier Deprez2b0be752021-09-01 10:25:21 +020012+--------+--------------------------------------+
13| CoT | Chain of Trust |
14+--------+--------------------------------------+
15| DMA | Direct Memory Access |
16+--------+--------------------------------------+
17| DTB | Device Tree Blob |
18+--------+--------------------------------------+
19| DTS | Device Tree Source |
20+--------+--------------------------------------+
21| EC | Execution Context |
22+--------+--------------------------------------+
23| FIP | Firmware Image Package |
24+--------+--------------------------------------+
25| FF-A | Firmware Framework for Arm A-profile |
26+--------+--------------------------------------+
27| IPA | Intermediate Physical Address |
28+--------+--------------------------------------+
Olivier Deprez3de57e32022-04-28 18:18:36 +020029| JOP | Jump-Oriented Programming |
30+--------+--------------------------------------+
Olivier Deprez2b0be752021-09-01 10:25:21 +020031| NWd | Normal World |
32+--------+--------------------------------------+
33| ODM | Original Design Manufacturer |
34+--------+--------------------------------------+
35| OEM | Original Equipment Manufacturer |
36+--------+--------------------------------------+
37| PA | Physical Address |
38+--------+--------------------------------------+
39| PE | Processing Element |
40+--------+--------------------------------------+
41| PM | Power Management |
42+--------+--------------------------------------+
43| PVM | Primary VM |
44+--------+--------------------------------------+
Olivier Deprez3de57e32022-04-28 18:18:36 +020045| ROP | Return-Oriented Programming |
46+--------+--------------------------------------+
Olivier Deprez2b0be752021-09-01 10:25:21 +020047| SMMU | System Memory Management Unit |
48+--------+--------------------------------------+
49| SP | Secure Partition |
50+--------+--------------------------------------+
51| SPD | Secure Payload Dispatcher |
52+--------+--------------------------------------+
53| SPM | Secure Partition Manager |
54+--------+--------------------------------------+
55| SPMC | SPM Core |
56+--------+--------------------------------------+
57| SPMD | SPM Dispatcher |
58+--------+--------------------------------------+
59| SiP | Silicon Provider |
60+--------+--------------------------------------+
61| SWd | Secure World |
62+--------+--------------------------------------+
63| TLV | Tag-Length-Value |
64+--------+--------------------------------------+
65| TOS | Trusted Operating System |
66+--------+--------------------------------------+
67| VM | Virtual Machine |
68+--------+--------------------------------------+
Olivier Deprezecb2fe52020-04-02 15:38:02 +020069
70Foreword
71========
72
Olivier Deprez3de57e32022-04-28 18:18:36 +020073Three implementations of a Secure Partition Manager co-exist in the TF-A
74codebase:
Olivier Deprezecb2fe52020-04-02 15:38:02 +020075
Olivier Deprez3de57e32022-04-28 18:18:36 +020076#. S-EL2 SPMC based on the FF-A specification `[1]`_, enabling virtualization in
77 the secure world, managing multiple S-EL1 or S-EL0 partitions.
78#. EL3 SPMC based on the FF-A specification, managing a single S-EL1 partition
79 without virtualization in the secure world.
80#. EL3 SPM based on the MM specification, legacy implementation managing a
81 single S-EL0 partition `[2]`_.
Olivier Deprezecb2fe52020-04-02 15:38:02 +020082
Olivier Deprez3de57e32022-04-28 18:18:36 +020083These implementations differ in their respective SW architecture and only one
84can be selected at build time. This document:
Olivier Deprezecb2fe52020-04-02 15:38:02 +020085
Olivier Deprez3de57e32022-04-28 18:18:36 +020086- describes the implementation from bullet 1. when the SPMC resides at S-EL2.
Olivier Deprez5e0a73f2021-04-30 14:42:24 +020087- is not an architecture specification and it might provide assumptions
88 on sections mandated as implementation-defined in the specification.
Olivier Deprez3de57e32022-04-28 18:18:36 +020089- covers the implications to TF-A used as a bootloader, and Hafnium used as a
90 reference code base for an S-EL2/SPMC secure firmware on platforms
91 implementing the FEAT_SEL2 architecture extension.
Olivier Deprezecb2fe52020-04-02 15:38:02 +020092
93Terminology
94-----------
95
Olivier Deprez5e0a73f2021-04-30 14:42:24 +020096- The term Hypervisor refers to the NS-EL2 component managing Virtual Machines
97 (or partitions) in the normal world.
98- The term SPMC refers to the S-EL2 component managing secure partitions in
99 the secure world when the FEAT_SEL2 architecture extension is implemented.
100- Alternatively, SPMC can refer to an S-EL1 component, itself being a secure
101 partition and implementing the FF-A ABI on platforms not implementing the
102 FEAT_SEL2 architecture extension.
103- The term VM refers to a normal world Virtual Machine managed by an Hypervisor.
104- The term SP refers to a secure world "Virtual Machine" managed by an SPMC.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200105
106Support for legacy platforms
107----------------------------
108
Olivier Deprez3de57e32022-04-28 18:18:36 +0200109The SPM is split into a dispatcher and a core component (respectively SPMD and
110SPMC) residing at different exception levels. To permit the FF-A specification
111adoption and a smooth migration, the SPMD supports an SPMC residing either at
112S-EL1 or S-EL2:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200113
Olivier Deprez3de57e32022-04-28 18:18:36 +0200114- The SPMD is located at EL3 and mainly relays the FF-A protocol from NWd
115 (Hypervisor or OS kernel) to the SPMC.
116- The same SPMD component is used for both S-EL1 and S-EL2 SPMC configurations.
117- The SPMC exception level is a build time choice.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200118
Olivier Deprez3de57e32022-04-28 18:18:36 +0200119TF-A supports both cases:
120
121- S-EL1 SPMC for platforms not supporting the FEAT_SEL2 architecture
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200122 extension. The SPMD relays the FF-A protocol from EL3 to S-EL1.
Olivier Deprez3de57e32022-04-28 18:18:36 +0200123- S-EL2 SPMC for platforms implementing the FEAT_SEL2 architecture
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200124 extension. The SPMD relays the FF-A protocol from EL3 to S-EL2.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200125
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200126Sample reference stack
127======================
128
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200129The following diagram illustrates a possible configuration when the
130FEAT_SEL2 architecture extension is implemented, showing the SPMD
131and SPMC, one or multiple secure partitions, with an optional
132Hypervisor:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200133
134.. image:: ../resources/diagrams/ff-a-spm-sel2.png
135
136TF-A build options
137==================
138
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200139This section explains the TF-A build options involved in building with
140support for an FF-A based SPM where the SPMD is located at EL3 and the
Marc Bonniciabaac162021-12-01 18:00:40 +0000141SPMC located at S-EL1, S-EL2 or EL3:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200142
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200143- **SPD=spmd**: this option selects the SPMD component to relay the FF-A
144 protocol from NWd to SWd back and forth. It is not possible to
145 enable another Secure Payload Dispatcher when this option is chosen.
146- **SPMD_SPM_AT_SEL2**: this option adjusts the SPMC exception
Marc Bonniciabaac162021-12-01 18:00:40 +0000147 level to being at S-EL2. It defaults to enabled (value 1) when
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200148 SPD=spmd is chosen.
Marc Bonniciabaac162021-12-01 18:00:40 +0000149- **SPMC_AT_EL3**: this option adjusts the SPMC exception level to being
150 at EL3.
Olivier Deprez3de57e32022-04-28 18:18:36 +0200151- If neither ``SPMD_SPM_AT_SEL2`` or ``SPMC_AT_EL3`` are enabled the SPMC
Marc Bonniciabaac162021-12-01 18:00:40 +0000152 exception level is set to S-EL1.
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200153- **CTX_INCLUDE_EL2_REGS**: this option permits saving (resp.
154 restoring) the EL2 system register context before entering (resp.
155 after leaving) the SPMC. It is mandatorily enabled when
156 ``SPMD_SPM_AT_SEL2`` is enabled. The context save/restore routine
157 and exhaustive list of registers is visible at `[4]`_.
158- **SP_LAYOUT_FILE**: this option specifies a text description file
159 providing paths to SP binary images and manifests in DTS format
160 (see `Describing secure partitions`_). It
161 is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple
Olivier Deprez3de57e32022-04-28 18:18:36 +0200162 secure partitions are to be loaded by BL2 on behalf of the SPMC.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200163
Marc Bonniciabaac162021-12-01 18:00:40 +0000164+---------------+----------------------+------------------+-------------+
165| | CTX_INCLUDE_EL2_REGS | SPMD_SPM_AT_SEL2 | SPMC_AT_EL3 |
166+---------------+----------------------+------------------+-------------+
167| SPMC at S-EL1 | 0 | 0 | 0 |
168+---------------+----------------------+------------------+-------------+
169| SPMC at S-EL2 | 1 | 1 (default when | 0 |
170| | | SPD=spmd) | |
171+---------------+----------------------+------------------+-------------+
172| SPMC at EL3 | 0 | 0 | 1 |
173+---------------+----------------------+------------------+-------------+
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200174
175Other combinations of such build options either break the build or are not
176supported.
177
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200178Notes:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200179
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200180- Only Arm's FVP platform is supported to use with the TF-A reference software
181 stack.
Olivier Deprez3de57e32022-04-28 18:18:36 +0200182- When ``SPMD_SPM_AT_SEL2=1``, the reference software stack assumes enablement
183 of FEAT_PAuth, FEAT_BTI and FEAT_MTE architecture extensions.
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200184- The ``CTX_INCLUDE_EL2_REGS`` option provides the generic support for
185 barely saving/restoring EL2 registers from an Arm arch perspective. As such
186 it is decoupled from the ``SPD=spmd`` option.
187- BL32 option is re-purposed to specify the SPMC image. It can specify either
188 the Hafnium binary path (built for the secure world) or the path to a TEE
189 binary implementing FF-A interfaces.
190- BL33 option can specify the TFTF binary or a normal world loader
Olivier Deprez3de57e32022-04-28 18:18:36 +0200191 such as U-Boot or the UEFI framework payload.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200192
Olivier Deprez3de57e32022-04-28 18:18:36 +0200193Sample TF-A build command line when the SPMC is located at S-EL1
194(e.g. when the FEAT_SEL2 architecture extension is not implemented):
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200195
196.. code:: shell
197
198 make \
199 CROSS_COMPILE=aarch64-none-elf- \
200 SPD=spmd \
201 SPMD_SPM_AT_SEL2=0 \
202 BL32=<path-to-tee-binary> \
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200203 BL33=<path-to-bl33-binary> \
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200204 PLAT=fvp \
205 all fip
206
Olivier Deprez3de57e32022-04-28 18:18:36 +0200207Sample TF-A build command line when FEAT_SEL2 architecture extension is
208implemented and the SPMC is located at S-EL2:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200209.. code:: shell
210
211 make \
212 CROSS_COMPILE=aarch64-none-elf- \
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200213 PLAT=fvp \
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200214 SPD=spmd \
215 CTX_INCLUDE_EL2_REGS=1 \
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200216 ARM_ARCH_MINOR=5 \
217 BRANCH_PROTECTION=1 \
218 CTX_INCLUDE_PAUTH_REGS=1 \
Olivier Deprez3de57e32022-04-28 18:18:36 +0200219 CTX_INCLUDE_MTE_REGS=1 \
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200220 BL32=<path-to-hafnium-binary> \
221 BL33=<path-to-bl33-binary> \
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200222 SP_LAYOUT_FILE=sp_layout.json \
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200223 all fip
224
Olivier Deprez3de57e32022-04-28 18:18:36 +0200225Sample TF-A build command line when FEAT_SEL2 architecture extension is
226implemented, the SPMC is located at S-EL2, and enabling secure boot:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200227.. code:: shell
228
229 make \
230 CROSS_COMPILE=aarch64-none-elf- \
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200231 PLAT=fvp \
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200232 SPD=spmd \
233 CTX_INCLUDE_EL2_REGS=1 \
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200234 ARM_ARCH_MINOR=5 \
235 BRANCH_PROTECTION=1 \
236 CTX_INCLUDE_PAUTH_REGS=1 \
Olivier Deprez3de57e32022-04-28 18:18:36 +0200237 CTX_INCLUDE_MTE_REGS=1 \
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200238 BL32=<path-to-hafnium-binary> \
239 BL33=<path-to-bl33-binary> \
240 SP_LAYOUT_FILE=sp_layout.json \
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200241 MBEDTLS_DIR=<path-to-mbedtls-lib> \
242 TRUSTED_BOARD_BOOT=1 \
243 COT=dualroot \
244 ARM_ROTPK_LOCATION=devel_rsa \
245 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
246 GENERATE_COT=1 \
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200247 all fip
248
Olivier Deprez3de57e32022-04-28 18:18:36 +0200249Sample TF-A build command line when the SPMC is located at EL3:
Marc Bonniciabaac162021-12-01 18:00:40 +0000250
251.. code:: shell
252
253 make \
254 CROSS_COMPILE=aarch64-none-elf- \
255 SPD=spmd \
256 SPMD_SPM_AT_SEL2=0 \
257 SPMC_AT_EL3=1 \
258 BL32=<path-to-tee-binary> \
259 BL33=<path-to-bl33-binary> \
260 PLAT=fvp \
261 all fip
262
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200263FVP model invocation
264====================
265
266The FVP command line needs the following options to exercise the S-EL2 SPMC:
267
268+---------------------------------------------------+------------------------------------+
269| - cluster0.has_arm_v8-5=1 | Implements FEAT_SEL2, FEAT_PAuth, |
270| - cluster1.has_arm_v8-5=1 | and FEAT_BTI. |
271+---------------------------------------------------+------------------------------------+
272| - pci.pci_smmuv3.mmu.SMMU_AIDR=2 | Parameters required for the |
273| - pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B | SMMUv3.2 modeling. |
274| - pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 | |
275| - pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 | |
276| - pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0472 | |
277| - pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 | |
278| - pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 | |
279| - pci.pci_smmuv3.mmu.SMMU_S_IDR3=0 | |
280+---------------------------------------------------+------------------------------------+
281| - cluster0.has_branch_target_exception=1 | Implements FEAT_BTI. |
282| - cluster1.has_branch_target_exception=1 | |
283+---------------------------------------------------+------------------------------------+
Olivier Deprez3de57e32022-04-28 18:18:36 +0200284| - cluster0.has_pointer_authentication=2 | Implements FEAT_PAuth |
285| - cluster1.has_pointer_authentication=2 | |
286+---------------------------------------------------+------------------------------------+
287| - cluster0.memory_tagging_support_level=2 | Implements FEAT_MTE2 |
288| - cluster1.memory_tagging_support_level=2 | |
289| - bp.dram_metadata.is_enabled=1 | |
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200290+---------------------------------------------------+------------------------------------+
291
292Sample FVP command line invocation:
293
294.. code:: shell
295
Olivier Deprez3de57e32022-04-28 18:18:36 +0200296 <path-to-fvp-model>/FVP_Base_RevC-2xAEMvA -C pctl.startup=0.0.0.0 \
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200297 -C cluster0.NUM_CORES=4 -C cluster1.NUM_CORES=4 -C bp.secure_memory=1 \
298 -C bp.secureflashloader.fname=trusted-firmware-a/build/fvp/debug/bl1.bin \
299 -C bp.flashloader0.fname=trusted-firmware-a/build/fvp/debug/fip.bin \
300 -C bp.pl011_uart0.out_file=fvp-uart0.log -C bp.pl011_uart1.out_file=fvp-uart1.log \
301 -C bp.pl011_uart2.out_file=fvp-uart2.log \
Olivier Deprez3de57e32022-04-28 18:18:36 +0200302 -C cluster0.has_arm_v8-5=1 -C cluster1.has_arm_v8-5=1 \
303 -C cluster0.has_pointer_authentication=2 -C cluster1.has_pointer_authentication=2 \
304 -C cluster0.has_branch_target_exception=1 -C cluster1.has_branch_target_exception=1 \
305 -C cluster0.memory_tagging_support_level=2 -C cluster1.memory_tagging_support_level=2 \
306 -C bp.dram_metadata.is_enabled=1 \
307 -C pci.pci_smmuv3.mmu.SMMU_AIDR=2 -C pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B \
308 -C pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 -C pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 \
309 -C pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0472 -C pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 \
310 -C pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 -C pci.pci_smmuv3.mmu.SMMU_S_IDR3=0
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200311
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200312Boot process
313============
314
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200315Loading Hafnium and secure partitions in the secure world
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200316---------------------------------------------------------
317
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200318TF-A BL2 is the bootlader for the SPMC and SPs in the secure world.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200319
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200320SPs may be signed by different parties (SiP, OEM/ODM, TOS vendor, etc.).
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200321Thus they are supplied as distinct signed entities within the FIP flash
322image. The FIP image itself is not signed hence this provides the ability
323to upgrade SPs in the field.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200324
325Booting through TF-A
326--------------------
327
328SP manifests
329~~~~~~~~~~~~
330
331An SP manifest describes SP attributes as defined in `[1]`_
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200332(partition manifest at virtual FF-A instance) in DTS format. It is
333represented as a single file associated with the SP. A sample is
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200334provided by `[5]`_. A binding document is provided by `[6]`_.
335
336Secure Partition packages
337~~~~~~~~~~~~~~~~~~~~~~~~~
338
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200339Secure partitions are bundled as independent package files consisting
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200340of:
341
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200342- a header
343- a DTB
344- an image payload
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200345
346The header starts with a magic value and offset values to SP DTB and
347image payload. Each SP package is loaded independently by BL2 loader
348and verified for authenticity and integrity.
349
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200350The SP package identified by its UUID (matching FF-A uuid property) is
351inserted as a single entry into the FIP at end of the TF-A build flow
352as shown:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200353
354.. code:: shell
355
356 Trusted Boot Firmware BL2: offset=0x1F0, size=0x8AE1, cmdline="--tb-fw"
357 EL3 Runtime Firmware BL31: offset=0x8CD1, size=0x13000, cmdline="--soc-fw"
358 Secure Payload BL32 (Trusted OS): offset=0x1BCD1, size=0x15270, cmdline="--tos-fw"
359 Non-Trusted Firmware BL33: offset=0x30F41, size=0x92E0, cmdline="--nt-fw"
360 HW_CONFIG: offset=0x3A221, size=0x2348, cmdline="--hw-config"
361 TB_FW_CONFIG: offset=0x3C569, size=0x37A, cmdline="--tb-fw-config"
362 SOC_FW_CONFIG: offset=0x3C8E3, size=0x48, cmdline="--soc-fw-config"
363 TOS_FW_CONFIG: offset=0x3C92B, size=0x427, cmdline="--tos-fw-config"
364 NT_FW_CONFIG: offset=0x3CD52, size=0x48, cmdline="--nt-fw-config"
365 B4B5671E-4A90-4FE1-B81F-FB13DAE1DACB: offset=0x3CD9A, size=0xC168, cmdline="--blob"
366 D1582309-F023-47B9-827C-4464F5578FC8: offset=0x48F02, size=0xC168, cmdline="--blob"
367
368.. uml:: ../resources/diagrams/plantuml/fip-secure-partitions.puml
369
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200370Describing secure partitions
371~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200372
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200373A json-formatted description file is passed to the build flow specifying paths
374to the SP binary image and associated DTS partition manifest file. The latter
375is processed by the dtc compiler to generate a DTB fed into the SP package.
J-Alvescfc6e232022-05-24 12:13:08 +0100376Optionally, the partition's json description can contain offsets for both
377the image and partition manifest within the SP package. Both offsets need to be
3784KB aligned, because it is the translation granule supported by Hafnium SPMC.
379These fields can be leveraged to support SPs with S1 translation granules that
380differ from 4KB, and to configure the regions allocated within the SP package,
381as well as to comply with the requirements for the implementation of the boot
382information protocol (see `Passing boot data to the SP`_ for more details). In
383case the offsets are absent in their json node, they default to 0x1000 and
3840x4000 for the manifest offset and image offset respectively.
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200385This file also specifies the SP owner (as an optional field) identifying the
386signing domain in case of dual root CoT.
387The SP owner can either be the silicon or the platform provider. The
388corresponding "owner" field value can either take the value of "SiP" or "Plat".
389In absence of "owner" field, it defaults to "SiP" owner.
Imre Kis3f370fd2022-02-08 18:06:18 +0100390The UUID of the partition can be specified as a field in the description file or
391if it does not exist there the UUID is extracted from the DTS partition
392manifest.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200393
394.. code:: shell
395
396 {
397 "tee1" : {
398 "image": "tee1.bin",
Manish Pandey77870962020-08-12 17:06:25 +0100399 "pm": "tee1.dts",
Imre Kis3f370fd2022-02-08 18:06:18 +0100400 "owner": "SiP",
401 "uuid": "1b1820fe-48f7-4175-8999-d51da00b7c9f"
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200402 },
403
404 "tee2" : {
405 "image": "tee2.bin",
Manish Pandey77870962020-08-12 17:06:25 +0100406 "pm": "tee2.dts",
407 "owner": "Plat"
J-Alvescfc6e232022-05-24 12:13:08 +0100408 },
409
410 "tee3" : {
411 "image": {
412 "file": "tee3.bin",
413 "offset":"0x2000"
414 },
415 "pm": {
416 "file": "tee3.dts",
417 "offset":"0x6000"
418 },
419 "owner": "Plat"
420 },
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200421 }
422
423SPMC manifest
424~~~~~~~~~~~~~
425
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200426This manifest contains the SPMC *attribute* node consumed by the SPMD at boot
427time. It implements `[1]`_ (SP manifest at physical FF-A instance) and serves
428two different cases:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200429
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200430- The SPMC resides at S-EL1: the SPMC manifest is used by the SPMD to setup a
431 SP that co-resides with the SPMC and executes at S-EL1 or Secure Supervisor
432 mode.
433- The SPMC resides at S-EL2: the SPMC manifest is used by the SPMD to setup
434 the environment required by the SPMC to run at S-EL2. SPs run at S-EL1 or
435 S-EL0.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200436
437.. code:: shell
438
439 attribute {
440 spmc_id = <0x8000>;
441 maj_ver = <0x1>;
Olivier Deprez3de57e32022-04-28 18:18:36 +0200442 min_ver = <0x1>;
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200443 exec_state = <0x0>;
444 load_address = <0x0 0x6000000>;
445 entrypoint = <0x0 0x6000000>;
446 binary_size = <0x60000>;
447 };
448
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200449- *spmc_id* defines the endpoint ID value that SPMC can query through
450 ``FFA_ID_GET``.
451- *maj_ver/min_ver*. SPMD checks provided version versus its internal
452 version and aborts if not matching.
453- *exec_state* defines the SPMC execution state (AArch64 or AArch32).
454 Notice Hafnium used as a SPMC only supports AArch64.
455- *load_address* and *binary_size* are mostly used to verify secondary
456 entry points fit into the loaded binary image.
457- *entrypoint* defines the cold boot primary core entry point used by
458 SPMD (currently matches ``BL32_BASE``) to enter the SPMC.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200459
460Other nodes in the manifest are consumed by Hafnium in the secure world.
Olivier Deprez3de57e32022-04-28 18:18:36 +0200461A sample can be found at `[7]`_:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200462
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200463- The *hypervisor* node describes SPs. *is_ffa_partition* boolean attribute
464 indicates a FF-A compliant SP. The *load_address* field specifies the load
Olivier Deprez3de57e32022-04-28 18:18:36 +0200465 address at which BL2 loaded the SP package.
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200466- *cpus* node provide the platform topology and allows MPIDR to VMPIDR mapping.
Olivier Deprez3de57e32022-04-28 18:18:36 +0200467 Note the primary core is declared first, then secondary cores are declared
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200468 in reverse order.
469- The *memory* node provides platform information on the ranges of memory
470 available to the SPMC.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200471
472SPMC boot
473~~~~~~~~~
474
475The SPMC is loaded by BL2 as the BL32 image.
476
Olivier Deprez4ab7a4a2021-06-21 09:47:13 +0200477The SPMC manifest is loaded by BL2 as the ``TOS_FW_CONFIG`` image `[9]`_.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200478
479BL2 passes the SPMC manifest address to BL31 through a register.
480
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200481At boot time, the SPMD in BL31 runs from the primary core, initializes the core
Olivier Deprez4ab7a4a2021-06-21 09:47:13 +0200482contexts and launches the SPMC (BL32) passing the following information through
483registers:
484
485- X0 holds the ``TOS_FW_CONFIG`` physical address (or SPMC manifest blob).
486- X1 holds the ``HW_CONFIG`` physical address.
487- X4 holds the currently running core linear id.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200488
489Loading of SPs
490~~~~~~~~~~~~~~
491
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200492At boot time, BL2 loads SPs sequentially in addition to the SPMC as depicted
493below:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200494
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200495.. uml:: ../resources/diagrams/plantuml/bl2-loading-sp.puml
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200496
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200497Note this boot flow is an implementation sample on Arm's FVP platform.
498Platforms not using TF-A's *Firmware CONFiguration* framework would adjust to a
Olivier Deprez3de57e32022-04-28 18:18:36 +0200499different boot flow. The flow restricts to a maximum of 8 secure partitions.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200500
501Secure boot
502~~~~~~~~~~~
503
504The SP content certificate is inserted as a separate FIP item so that BL2 loads SPMC,
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200505SPMC manifest, secure partitions and verifies them for authenticity and integrity.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200506Refer to TBBR specification `[3]`_.
507
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200508The multiple-signing domain feature (in current state dual signing domain `[8]`_) allows
509the use of two root keys namely S-ROTPK and NS-ROTPK:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200510
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200511- SPMC (BL32) and SPMC manifest are signed by the SiP using the S-ROTPK.
512- BL33 may be signed by the OEM using NS-ROTPK.
513- An SP may be signed either by SiP (using S-ROTPK) or by OEM (using NS-ROTPK).
Olivier Deprez3de57e32022-04-28 18:18:36 +0200514- A maximum of 4 partitions can be signed with the S-ROTPK key and 4 partitions
515 signed with the NS-ROTPK key.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200516
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200517Also refer to `Describing secure partitions`_ and `TF-A build options`_ sections.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200518
519Hafnium in the secure world
520===========================
521
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200522General considerations
523----------------------
524
525Build platform for the secure world
526~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
527
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200528In the Hafnium reference implementation specific code parts are only relevant to
529the secure world. Such portions are isolated in architecture specific files
530and/or enclosed by a ``SECURE_WORLD`` macro.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200531
Olivier Deprez3de57e32022-04-28 18:18:36 +0200532Secure partitions scheduling
533~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200534
Olivier Deprez3de57e32022-04-28 18:18:36 +0200535The FF-A specification `[1]`_ provides two ways to relinquinsh CPU time to
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200536secure partitions. For this a VM (Hypervisor or OS kernel), or SP invokes one of:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200537
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200538- the FFA_MSG_SEND_DIRECT_REQ interface.
539- the FFA_RUN interface.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200540
Olivier Deprez3de57e32022-04-28 18:18:36 +0200541Additionally a secure interrupt can pre-empt the normal world execution and give
542CPU cycles by transitioning to EL3 and S-EL2.
543
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200544Platform topology
545~~~~~~~~~~~~~~~~~
546
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200547The *execution-ctx-count* SP manifest field can take the value of one or the
Olivier Deprez3de57e32022-04-28 18:18:36 +0200548total number of PEs. The FF-A specification `[1]`_ recommends the
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200549following SP types:
550
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200551- Pinned MP SPs: an execution context matches a physical PE. MP SPs must
552 implement the same number of ECs as the number of PEs in the platform.
553- Migratable UP SPs: a single execution context can run and be migrated on any
554 physical PE. Such SP declares a single EC in its SP manifest. An UP SP can
555 receive a direct message request originating from any physical core targeting
556 the single execution context.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200557
558Parsing SP partition manifests
559------------------------------
560
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200561Hafnium consumes SP manifests as defined in `[1]`_ and `SP manifests`_.
562Note the current implementation may not implement all optional fields.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200563
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200564The SP manifest may contain memory and device regions nodes. In case of
565an S-EL2 SPMC:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200566
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200567- Memory regions are mapped in the SP EL1&0 Stage-2 translation regime at
568 load time (or EL1&0 Stage-1 for an S-EL1 SPMC). A memory region node can
569 specify RX/TX buffer regions in which case it is not necessary for an SP
570 to explicitly invoke the ``FFA_RXTX_MAP`` interface.
571- Device regions are mapped in the SP EL1&0 Stage-2 translation regime (or
572 EL1&0 Stage-1 for an S-EL1 SPMC) as peripherals and possibly allocate
573 additional resources (e.g. interrupts).
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200574
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200575For the S-EL2 SPMC, base addresses for memory and device region nodes are IPAs
576provided the SPMC identity maps IPAs to PAs within SP EL1&0 Stage-2 translation
577regime.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200578
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200579Note: in the current implementation both VTTBR_EL2 and VSTTBR_EL2 point to the
580same set of page tables. It is still open whether two sets of page tables shall
581be provided per SP. The memory region node as defined in the specification
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200582provides a memory security attribute hinting to map either to the secure or
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200583non-secure EL1&0 Stage-2 table if it exists.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200584
585Passing boot data to the SP
586---------------------------
587
J-Alvescfc6e232022-05-24 12:13:08 +0100588In `[1]`_ , the section "Boot information protocol" defines a method for passing
589data to the SPs at boot time. It specifies the format for the boot information
590descriptor and boot information header structures, which describe the data to be
591exchanged between SPMC and SP.
592The specification also defines the types of data that can be passed.
593The aggregate of both the boot info structures and the data itself is designated
594the boot information blob, and is passed to a Partition as a contiguous memory
595region.
596
597Currently, the SPM implementation supports the FDT type which is used to pass the
598partition's DTB manifest.
599
600The region for the boot information blob is allocated through the SP package.
601
602.. image:: ../resources/diagrams/partition-package.png
603
604To adjust the space allocated for the boot information blob, the json description
605of the SP (see section `Describing secure partitions`_) shall be updated to contain
606the manifest offset. If no offset is provided the manifest offset defaults to 0x1000,
607which is the page size in the Hafnium SPMC.
608
609The configuration of the boot protocol is done in the SPs manifest. As defined by
610the specification, the manifest field 'gp-register-num' configures the GP register
611which shall be used to pass the address to the partitions boot information blob when
612booting the partition.
613In addition, the Hafnium SPMC implementation requires the boot information arguments
614to be listed in a designated DT node:
615
616.. code:: shell
617
618 boot-info {
619 compatible = "arm,ffa-manifest-boot-info";
620 ffa_manifest;
621 };
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200622
J-Alvescfc6e232022-05-24 12:13:08 +0100623The whole secure partition package image (see `Secure Partition packages`_) is
624mapped to the SP secure EL1&0 Stage-2 translation regime. As such, the SP can
625retrieve the address for the boot information blob in the designated GP register,
626process the boot information header and descriptors, access its own manifest
627DTB blob and extract its partition manifest properties.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200628
629SP Boot order
630-------------
631
632SP manifests provide an optional boot order attribute meant to resolve
633dependencies such as an SP providing a service required to properly boot
J-Alves855fc882021-12-14 16:02:27 +0000634another SP. SPMC boots the SPs in accordance to the boot order attribute,
635lowest to the highest value. If the boot order attribute is absent from the FF-A
636manifest, the SP is treated as if it had the highest boot order value
637(i.e. lowest booting priority).
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200638
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200639It is possible for an SP to call into another SP through a direct request
640provided the latter SP has already been booted.
641
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200642Boot phases
643-----------
644
645Primary core boot-up
646~~~~~~~~~~~~~~~~~~~~
647
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200648Upon boot-up, BL31 hands over to the SPMC (BL32) on the primary boot physical
649core. The SPMC performs its platform initializations and registers the SPMC
650secondary physical core entry point physical address by the use of the
J-Alvesc9ca31c2021-10-04 14:33:51 +0100651`FFA_SECONDARY_EP_REGISTER`_ interface (SMC invocation from the SPMC to the SPMD
652at secure physical FF-A instance).
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200653
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200654The SPMC then creates secure partitions based on SP packages and manifests. Each
655secure partition is launched in sequence (`SP Boot order`_) on their "primary"
656execution context. If the primary boot physical core linear id is N, an MP SP is
657started using EC[N] on PE[N] (see `Platform topology`_). If the partition is a
658UP SP, it is started using its unique EC0 on PE[N].
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200659
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200660The SP primary EC (or the EC used when the partition is booted as described
661above):
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200662
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200663- Performs the overall SP boot time initialization, and in case of a MP SP,
664 prepares the SP environment for other execution contexts.
665- In the case of a MP SP, it invokes the FFA_SECONDARY_EP_REGISTER at secure
666 virtual FF-A instance (SMC invocation from SP to SPMC) to provide the IPA
667 entry point for other execution contexts.
668- Exits through ``FFA_MSG_WAIT`` to indicate successful initialization or
669 ``FFA_ERROR`` in case of failure.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200670
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200671Secondary cores boot-up
672~~~~~~~~~~~~~~~~~~~~~~~
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200673
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200674Once the system is started and NWd brought up, a secondary physical core is
675woken up by the ``PSCI_CPU_ON`` service invocation. The TF-A SPD hook mechanism
676calls into the SPMD on the newly woken up physical core. Then the SPMC is
677entered at the secondary physical core entry point.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200678
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200679In the current implementation, the first SP is resumed on the coresponding EC
680(the virtual CPU which matches the physical core). The implication is that the
681first SP must be a MP SP.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200682
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200683In a linux based system, once secure and normal worlds are booted but prior to
684a NWd FF-A driver has been loaded:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200685
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200686- The first SP has initialized all its ECs in response to primary core boot up
687 (at system initialization) and secondary core boot up (as a result of linux
688 invoking PSCI_CPU_ON for all secondary cores).
689- Other SPs have their first execution context initialized as a result of secure
690 world initialization on the primary boot core. Other ECs for those SPs have to
691 be run first through ffa_run to complete their initialization (which results
692 in the EC completing with FFA_MSG_WAIT).
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200693
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200694Refer to `Power management`_ for further details.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200695
J-Alvesc9ca31c2021-10-04 14:33:51 +0100696Notifications
697-------------
698
699The FF-A v1.1 specification `[1]`_ defines notifications as an asynchronous
700communication mechanism with non-blocking semantics. It allows for one FF-A
701endpoint to signal another for service provision, without hindering its current
702progress.
703
704Hafnium currently supports 64 notifications. The IDs of each notification define
705a position in a 64-bit bitmap.
706
707The signaling of notifications can interchangeably happen between NWd and SWd
708FF-A endpoints.
709
710The SPMC is in charge of managing notifications from SPs to SPs, from SPs to
711VMs, and from VMs to SPs. An hypervisor component would only manage
712notifications from VMs to VMs. Given the SPMC has no visibility of the endpoints
713deployed in NWd, the Hypervisor or OS kernel must invoke the interface
714FFA_NOTIFICATION_BITMAP_CREATE to allocate the notifications bitmap per FF-A
715endpoint in the NWd that supports it.
716
717A sender can signal notifications once the receiver has provided it with
718permissions. Permissions are provided by invoking the interface
719FFA_NOTIFICATION_BIND.
720
721Notifications are signaled by invoking FFA_NOTIFICATION_SET. Henceforth
722they are considered to be in a pending sate. The receiver can retrieve its
723pending notifications invoking FFA_NOTIFICATION_GET, which, from that moment,
724are considered to be handled.
725
726Per the FF-A v1.1 spec, each FF-A endpoint must be associated with a scheduler
727that is in charge of donating CPU cycles for notifications handling. The
728FF-A driver calls FFA_NOTIFICATION_INFO_GET to retrieve the information about
729which FF-A endpoints have pending notifications. The receiver scheduler is
730called and informed by the FF-A driver, and it should allocate CPU cycles to the
731receiver.
732
733There are two types of notifications supported:
Olivier Deprez3de57e32022-04-28 18:18:36 +0200734
J-Alvesc9ca31c2021-10-04 14:33:51 +0100735- Global, which are targeted to a FF-A endpoint and can be handled within any of
Olivier Deprez3de57e32022-04-28 18:18:36 +0200736 its execution contexts, as determined by the scheduler of the system.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100737- Per-vCPU, which are targeted to a FF-A endpoint and to be handled within a
Olivier Deprez3de57e32022-04-28 18:18:36 +0200738 a specific execution context, as determined by the sender.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100739
740The type of a notification is set when invoking FFA_NOTIFICATION_BIND to give
741permissions to the sender.
742
743Notification signaling resorts to two interrupts:
J-Alvesc9ca31c2021-10-04 14:33:51 +0100744
Olivier Deprez3de57e32022-04-28 18:18:36 +0200745- Schedule Receiver Interrupt: non-secure physical interrupt to be handled by
746 the FF-A driver within the receiver scheduler. At initialization the SPMC
747 donates a SGI ID chosen from the secure SGI IDs range and configures it as
748 non-secure. The SPMC triggers this SGI on the currently running core when
749 there are pending notifications, and the respective receivers need CPU cycles
750 to handle them.
751- Notifications Pending Interrupt: virtual interrupt to be handled by the
752 receiver of the notification. Set when there are pending notifications for the
753 given secure partition. The NPI is pended when the NWd relinquishes CPU cycles
754 to an SP.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100755
Olivier Deprez3de57e32022-04-28 18:18:36 +0200756The notifications receipt support is enabled in the partition FF-A manifest.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100757
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200758Mandatory interfaces
759--------------------
760
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200761The following interfaces are exposed to SPs:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200762
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200763- ``FFA_VERSION``
764- ``FFA_FEATURES``
765- ``FFA_RX_RELEASE``
766- ``FFA_RXTX_MAP``
J-Alvesc9ca31c2021-10-04 14:33:51 +0100767- ``FFA_RXTX_UNMAP``
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200768- ``FFA_PARTITION_INFO_GET``
769- ``FFA_ID_GET``
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200770- ``FFA_MSG_WAIT``
771- ``FFA_MSG_SEND_DIRECT_REQ``
772- ``FFA_MSG_SEND_DIRECT_RESP``
773- ``FFA_MEM_DONATE``
774- ``FFA_MEM_LEND``
775- ``FFA_MEM_SHARE``
776- ``FFA_MEM_RETRIEVE_REQ``
777- ``FFA_MEM_RETRIEVE_RESP``
778- ``FFA_MEM_RELINQUISH``
Olivier Deprez3de57e32022-04-28 18:18:36 +0200779- ``FFA_MEM_FRAG_RX``
780- ``FFA_MEM_FRAG_TX``
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200781- ``FFA_MEM_RECLAIM``
Olivier Deprez3de57e32022-04-28 18:18:36 +0200782- ``FFA_RUN``
J-Alvesc9ca31c2021-10-04 14:33:51 +0100783
Olivier Deprez3de57e32022-04-28 18:18:36 +0200784As part of the FF-A v1.1 support, the following interfaces were added:
J-Alvesc9ca31c2021-10-04 14:33:51 +0100785
786 - ``FFA_NOTIFICATION_BITMAP_CREATE``
787 - ``FFA_NOTIFICATION_BITMAP_DESTROY``
788 - ``FFA_NOTIFICATION_BIND``
789 - ``FFA_NOTIFICATION_UNBIND``
790 - ``FFA_NOTIFICATION_SET``
791 - ``FFA_NOTIFICATION_GET``
792 - ``FFA_NOTIFICATION_INFO_GET``
793 - ``FFA_SPM_ID_GET``
794 - ``FFA_SECONDARY_EP_REGISTER``
Olivier Deprez3de57e32022-04-28 18:18:36 +0200795 - ``FFA_MEM_PERM_GET``
796 - ``FFA_MEM_PERM_SET``
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200797
798FFA_VERSION
799~~~~~~~~~~~
800
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200801``FFA_VERSION`` requires a *requested_version* parameter from the caller.
802The returned value depends on the caller:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200803
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200804- Hypervisor or OS kernel in NS-EL1/EL2: the SPMD returns the SPMC version
805 specified in the SPMC manifest.
806- SP: the SPMC returns its own implemented version.
807- SPMC at S-EL1/S-EL2: the SPMD returns its own implemented version.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200808
809FFA_FEATURES
810~~~~~~~~~~~~
811
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200812FF-A features supported by the SPMC may be discovered by secure partitions at
813boot (that is prior to NWd is booted) or run-time.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200814
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200815The SPMC calling FFA_FEATURES at secure physical FF-A instance always get
816FFA_SUCCESS from the SPMD.
817
818The request made by an Hypervisor or OS kernel is forwarded to the SPMC and
819the response relayed back to the NWd.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200820
821FFA_RXTX_MAP/FFA_RXTX_UNMAP
822~~~~~~~~~~~~~~~~~~~~~~~~~~~
823
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200824When invoked from a secure partition FFA_RXTX_MAP maps the provided send and
825receive buffers described by their IPAs to the SP EL1&0 Stage-2 translation
826regime as secure buffers in the MMU descriptors.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200827
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200828When invoked from the Hypervisor or OS kernel, the buffers are mapped into the
829SPMC EL2 Stage-1 translation regime and marked as NS buffers in the MMU
830descriptors.
831
J-Alvesc9ca31c2021-10-04 14:33:51 +0100832The FFA_RXTX_UNMAP unmaps the RX/TX pair from the translation regime of the
833caller, either it being the Hypervisor or OS kernel, as well as a secure
834partition.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200835
836FFA_PARTITION_INFO_GET
837~~~~~~~~~~~~~~~~~~~~~~
838
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200839Partition info get call can originate:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200840
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200841- from SP to SPMC
842- from Hypervisor or OS kernel to SPMC. The request is relayed by the SPMD.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200843
844FFA_ID_GET
845~~~~~~~~~~
846
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200847The FF-A id space is split into a non-secure space and secure space:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200848
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200849- FF-A ID with bit 15 clear relates to VMs.
850- FF-A ID with bit 15 set related to SPs.
851- FF-A IDs 0, 0xffff, 0x8000 are assigned respectively to the Hypervisor, SPMD
852 and SPMC.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200853
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200854The SPMD returns:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200855
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200856- The default zero value on invocation from the Hypervisor.
857- The ``spmc_id`` value specified in the SPMC manifest on invocation from
858 the SPMC (see `SPMC manifest`_)
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200859
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200860This convention helps the SPMC to determine the origin and destination worlds in
861an FF-A ABI invocation. In particular the SPMC shall filter unauthorized
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200862transactions in its world switch routine. It must not be permitted for a VM to
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200863use a secure FF-A ID as origin world by spoofing:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200864
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200865- A VM-to-SP direct request/response shall set the origin world to be non-secure
866 (FF-A ID bit 15 clear) and destination world to be secure (FF-A ID bit 15
867 set).
868- Similarly, an SP-to-SP direct request/response shall set the FF-A ID bit 15
869 for both origin and destination IDs.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200870
871An incoming direct message request arriving at SPMD from NWd is forwarded to
872SPMC without a specific check. The SPMC is resumed through eret and "knows" the
873message is coming from normal world in this specific code path. Thus the origin
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200874endpoint ID must be checked by SPMC for being a normal world ID.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200875
876An SP sending a direct message request must have bit 15 set in its origin
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200877endpoint ID and this can be checked by the SPMC when the SP invokes the ABI.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200878
879The SPMC shall reject the direct message if the claimed world in origin endpoint
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200880ID is not consistent:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200881
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200882- It is either forwarded by SPMD and thus origin endpoint ID must be a "normal
883 world ID",
884- or initiated by an SP and thus origin endpoint ID must be a "secure world ID".
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200885
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200886
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200887FFA_MSG_SEND_DIRECT_REQ/FFA_MSG_SEND_DIRECT_RESP
888~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200889
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200890This is a mandatory interface for secure partitions consisting in direct request
891and responses with the following rules:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200892
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200893- An SP can send a direct request to another SP.
894- An SP can receive a direct request from another SP.
895- An SP can send a direct response to another SP.
896- An SP cannot send a direct request to an Hypervisor or OS kernel.
897- An Hypervisor or OS kernel can send a direct request to an SP.
898- An SP can send a direct response to an Hypervisor or OS kernel.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200899
J-Alvesc9ca31c2021-10-04 14:33:51 +0100900FFA_NOTIFICATION_BITMAP_CREATE/FFA_NOTIFICATION_BITMAP_DESTROY
901~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
902
903The secure partitions notifications bitmap are statically allocated by the SPMC.
904Hence, this interface is not to be issued by secure partitions.
905
906At initialization, the SPMC is not aware of VMs/partitions deployed in the
907normal world. Hence, the Hypervisor or OS kernel must use both ABIs for SPMC
908to be prepared to handle notifications for the provided VM ID.
909
910FFA_NOTIFICATION_BIND/FFA_NOTIFICATION_UNBIND
911~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
912
913Pair of interfaces to manage permissions to signal notifications. Prior to
914handling notifications, an FF-A endpoint must allow a given sender to signal a
915bitmap of notifications.
916
917If the receiver doesn't have notification support enabled in its FF-A manifest,
918it won't be able to bind notifications, hence forbidding it to receive any
919notifications.
920
921FFA_NOTIFICATION_SET/FFA_NOTIFICATION_GET
922~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
923
Olivier Deprez3de57e32022-04-28 18:18:36 +0200924FFA_NOTIFICATION_GET retrieves all pending global notifications and
925per-vCPU notifications targeted to the current vCPU.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100926
Olivier Deprez3de57e32022-04-28 18:18:36 +0200927Hafnium maintains a global count of pending notifications which gets incremented
928and decremented when handling FFA_NOTIFICATION_SET and FFA_NOTIFICATION_GET
929respectively. A delayed SRI is triggered if the counter is non-zero when the
930SPMC returns to normal world.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100931
932FFA_NOTIFICATION_INFO_GET
933~~~~~~~~~~~~~~~~~~~~~~~~~
934
Olivier Deprez3de57e32022-04-28 18:18:36 +0200935Hafnium maintains a global count of pending notifications whose information
936has been retrieved by this interface. The count is incremented and decremented
937when handling FFA_NOTIFICATION_INFO_GET and FFA_NOTIFICATION_GET respectively.
938It also tracks notifications whose information has been retrieved individually,
J-Alvesc9ca31c2021-10-04 14:33:51 +0100939such that it avoids duplicating returned information for subsequent calls to
940FFA_NOTIFICATION_INFO_GET. For each notification, this state information is
941reset when receiver called FFA_NOTIFICATION_GET to retrieve them.
942
943FFA_SPM_ID_GET
944~~~~~~~~~~~~~~
945
Olivier Deprez3de57e32022-04-28 18:18:36 +0200946Returns the FF-A ID allocated to an SPM component which can be one of SPMD
947or SPMC.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100948
Olivier Deprez3de57e32022-04-28 18:18:36 +0200949At initialization, the SPMC queries the SPMD for the SPMC ID, using the
950FFA_ID_GET interface, and records it. The SPMC can also query the SPMD ID using
951the FFA_SPM_ID_GET interface at the secure physical FF-A instance.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100952
Olivier Deprez3de57e32022-04-28 18:18:36 +0200953Secure partitions call this interface at the virtual FF-A instance, to which
954the SPMC returns the priorly retrieved SPMC ID.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100955
Olivier Deprez3de57e32022-04-28 18:18:36 +0200956The Hypervisor or OS kernel can issue the FFA_SPM_ID_GET call handled by the
957SPMD, which returns the SPMC ID.
J-Alvesc9ca31c2021-10-04 14:33:51 +0100958
959FFA_SECONDARY_EP_REGISTER
960~~~~~~~~~~~~~~~~~~~~~~~~~
961
962When the SPMC boots, all secure partitions are initialized on their primary
963Execution Context.
964
Olivier Deprez3de57e32022-04-28 18:18:36 +0200965The FFA_SECONDARY_EP_REGISTER interface is to be used by a secure partition
J-Alvesc9ca31c2021-10-04 14:33:51 +0100966from its first execution context, to provide the entry point address for
967secondary execution contexts.
968
969A secondary EC is first resumed either upon invocation of PSCI_CPU_ON from
970the NWd or by invocation of FFA_RUN.
971
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200972SPMC-SPMD direct requests/responses
973-----------------------------------
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200974
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200975Implementation-defined FF-A IDs are allocated to the SPMC and SPMD.
976Using those IDs in source/destination fields of a direct request/response
977permits SPMD to SPMC communication and either way.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200978
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200979- SPMC to SPMD direct request/response uses SMC conduit.
980- SPMD to SPMC direct request/response uses ERET conduit.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200981
Olivier Deprez3de57e32022-04-28 18:18:36 +0200982This is used in particular to convey power management messages.
983
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200984PE MMU configuration
985--------------------
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200986
Olivier Deprez3de57e32022-04-28 18:18:36 +0200987With secure virtualization enabled (``HCR_EL2.VM = 1``) and for S-EL1
988partitions, two IPA spaces (secure and non-secure) are output from the
989secure EL1&0 Stage-1 translation.
990The EL1&0 Stage-2 translation hardware is fed by:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200991
Olivier Deprez3de57e32022-04-28 18:18:36 +0200992- A secure IPA when the SP EL1&0 Stage-1 MMU is disabled.
993- One of secure or non-secure IPA when the secure EL1&0 Stage-1 MMU is enabled.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200994
Olivier Deprez5e0a73f2021-04-30 14:42:24 +0200995``VTCR_EL2`` and ``VSTCR_EL2`` provide configuration bits for controlling the
Olivier Deprez3de57e32022-04-28 18:18:36 +0200996NS/S IPA translations. The following controls are set up:
997``VSTCR_EL2.SW = 0`` , ``VSTCR_EL2.SA = 0``, ``VTCR_EL2.NSW = 0``,
998``VTCR_EL2.NSA = 1``:
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200999
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001000- Stage-2 translations for the NS IPA space access the NS PA space.
1001- Stage-2 translation table walks for the NS IPA space are to the secure PA space.
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001002
Olivier Deprez3de57e32022-04-28 18:18:36 +02001003Secure and non-secure IPA regions (rooted to by ``VTTBR_EL2`` and ``VSTTBR_EL2``)
1004use the same set of Stage-2 page tables within a SP.
1005
1006The ``VTCR_EL2/VSTCR_EL2/VTTBR_EL2/VSTTBR_EL2`` virtual address space
1007configuration is made part of a vCPU context.
1008
1009For S-EL0 partitions with VHE enabled, a single secure EL2&0 Stage-1 translation
1010regime is used for both Hafnium and the partition.
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001011
1012Interrupt management
1013--------------------
1014
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001015GIC ownership
1016~~~~~~~~~~~~~
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001017
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001018The SPMC owns the GIC configuration. Secure and non-secure interrupts are
1019trapped at S-EL2. The SPMC manages interrupt resources and allocates interrupt
1020IDs based on SP manifests. The SPMC acknowledges physical interrupts and injects
1021virtual interrupts by setting the use of vIRQ/vFIQ bits before resuming a SP.
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001022
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001023Non-secure interrupt handling
1024~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001025
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001026The following illustrate the scenarios of non secure physical interrupts trapped
1027by the SPMC:
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001028
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001029- The SP handles a managed exit operation:
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001030
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001031.. image:: ../resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001032
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001033- The SP is pre-empted without managed exit:
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001034
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001035.. image:: ../resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001036
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001037Secure interrupt handling
Madhukar Pappireddyb3d37b12021-09-23 14:29:05 -05001038-------------------------
1039
1040This section documents the support implemented for secure interrupt handling in
1041SPMC as per the guidance provided by FF-A v1.1 Beta0 specification.
1042The following assumptions are made about the system configuration:
1043
1044 - In the current implementation, S-EL1 SPs are expected to use the para
1045 virtualized ABIs for interrupt management rather than accessing virtual GIC
1046 interface.
1047 - Unless explicitly stated otherwise, this support is applicable only for
1048 S-EL1 SPs managed by SPMC.
1049 - Secure interrupts are configured as G1S or G0 interrupts.
1050 - All physical interrupts are routed to SPMC when running a secure partition
1051 execution context.
1052
1053A physical secure interrupt could preempt normal world execution. Moreover, when
1054the execution is in secure world, it is highly likely that the target of a
1055secure interrupt is not the currently running execution context of an SP. It
1056could be targeted to another FF-A component. Consequently, secure interrupt
1057management depends on the state of the target execution context of the SP that
1058is responsible for handling the interrupt. Hence, the spec provides guidance on
1059how to signal start and completion of secure interrupt handling as discussed in
1060further sections.
1061
1062Secure interrupt signaling mechanisms
1063~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1064
1065Signaling refers to the mechanisms used by SPMC to indicate to the SP execution
1066context that it has a pending virtual interrupt and to further run the SP
1067execution context, such that it can handle the virtual interrupt. SPMC uses
1068either the FFA_INTERRUPT interface with ERET conduit or vIRQ signal for signaling
1069to S-EL1 SPs. When normal world execution is preempted by a secure interrupt,
1070the SPMD uses the FFA_INTERRUPT ABI with ERET conduit to signal interrupt to SPMC
1071running in S-EL2.
1072
1073+-----------+---------+---------------+---------------------------------------+
1074| SP State | Conduit | Interface and | Description |
1075| | | parameters | |
1076+-----------+---------+---------------+---------------------------------------+
1077| WAITING | ERET, | FFA_INTERRUPT,| SPMC signals to SP the ID of pending |
1078| | vIRQ | Interrupt ID | interrupt. It pends vIRQ signal and |
1079| | | | resumes execution context of SP |
1080| | | | through ERET. |
1081+-----------+---------+---------------+---------------------------------------+
1082| BLOCKED | ERET, | FFA_INTERRUPT | SPMC signals to SP that an interrupt |
1083| | vIRQ | | is pending. It pends vIRQ signal and |
1084| | | | resumes execution context of SP |
1085| | | | through ERET. |
1086+-----------+---------+---------------+---------------------------------------+
1087| PREEMPTED | vIRQ | NA | SPMC pends the vIRQ signal but does |
1088| | | | not resume execution context of SP. |
1089+-----------+---------+---------------+---------------------------------------+
1090| RUNNING | ERET, | NA | SPMC pends the vIRQ signal and resumes|
1091| | vIRQ | | execution context of SP through ERET. |
1092+-----------+---------+---------------+---------------------------------------+
1093
1094Secure interrupt completion mechanisms
1095~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1096
1097A SP signals secure interrupt handling completion to the SPMC through the
1098following mechanisms:
1099
1100 - ``FFA_MSG_WAIT`` ABI if it was in WAITING state.
1101 - ``FFA_RUN`` ABI if its was in BLOCKED state.
1102
1103In the current implementation, S-EL1 SPs use para-virtualized HVC interface
1104implemented by SPMC to perform priority drop and interrupt deactivation (we
1105assume EOImode = 0, i.e. priority drop and deactivation are done together).
1106
1107If normal world execution was preempted by secure interrupt, SPMC uses
1108FFA_NORMAL_WORLD_RESUME ABI to indicate completion of secure interrupt handling
1109and further return execution to normal world. If the current SP execution
1110context was preempted by a secure interrupt to be handled by execution context
1111of target SP, SPMC resumes current SP after signal completion by target SP
1112execution context.
1113
1114An action is broadly a set of steps taken by the SPMC in response to a physical
1115interrupt. In order to simplify the design, the current version of secure
1116interrupt management support in SPMC (Hafnium) does not fully implement the
1117Scheduling models and Partition runtime models. However, the current
1118implementation loosely maps to the following actions that are legally allowed
1119by the specification. Please refer to the Table 8.4 in the spec for further
1120description of actions. The action specified for a type of interrupt when the
1121SP is in the message processing running state cannot be less permissive than the
1122action specified for the same type of interrupt when the SP is in the interrupt
1123handling running state.
1124
1125+--------------------+--------------------+------------+-------------+
1126| Runtime Model | NS-Int | Self S-Int | Other S-Int |
1127+--------------------+--------------------+------------+-------------+
1128| Message Processing | Signalable with ME | Signalable | Signalable |
1129+--------------------+--------------------+------------+-------------+
1130| Interrupt Handling | Queued | Queued | Queued |
1131+--------------------+--------------------+------------+-------------+
1132
1133Abbreviations:
1134
1135 - NS-Int: A Non-secure physical interrupt. It requires a switch to the Normal
1136 world to be handled.
1137 - Other S-Int: A secure physical interrupt targeted to an SP different from
1138 the one that is currently running.
1139 - Self S-Int: A secure physical interrupt targeted to the SP that is currently
1140 running.
1141
1142The following figure describes interrupt handling flow when secure interrupt
1143triggers while in normal world:
1144
1145.. image:: ../resources/diagrams/ffa-secure-interrupt-handling-nwd.png
1146
1147A brief description of the events:
1148
1149 - 1) Secure interrupt triggers while normal world is running.
1150 - 2) FIQ gets trapped to EL3.
1151 - 3) SPMD signals secure interrupt to SPMC at S-EL2 using FFA_INTERRUPT ABI.
1152 - 4) SPMC identifies target vCPU of SP and injects virtual interrupt (pends
1153 vIRQ).
1154 - 5) Since SP1 vCPU is in WAITING state, SPMC signals using FFA_INTERRUPT with
1155 interrupt id as argument and resume it using ERET.
1156 - 6) Execution traps to vIRQ handler in SP1 provided that interrupt is not
1157 masked i.e., PSTATE.I = 0
1158 - 7) SP1 services the interrupt and invokes the de-activation HVC call.
1159 - 8) SPMC does internal state management and further de-activates the physical
1160 interrupt and resumes SP vCPU.
1161 - 9) SP performs secure interrupt completion through FFA_MSG_WAIT ABI.
1162 - 10) SPMC returns control to EL3 using FFA_NORMAL_WORLD_RESUME.
1163 - 11) EL3 resumes normal world execution.
1164
1165The following figure describes interrupt handling flow when secure interrupt
1166triggers while in secure world:
1167
1168.. image:: ../resources/diagrams/ffa-secure-interrupt-handling-swd.png
1169
1170A brief description of the events:
1171
1172 - 1) Secure interrupt triggers while SP2 is running and SP1 is blocked.
1173 - 2) Gets trapped to SPMC as IRQ.
1174 - 3) SPMC finds the target vCPU of secure partition responsible for handling
1175 this secure interrupt. In this scenario, it is SP1.
1176 - 4) SPMC pends vIRQ for SP1 and signals through FFA_INTERRUPT interface.
1177 SPMC further resumes SP1 through ERET conduit.
1178 - 5) Execution traps to vIRQ handler in SP1 provided that interrupt is not
1179 masked i.e., PSTATE.I = 0
1180 - 6) SP1 services the secure interrupt and invokes the de-activation HVC call.
1181 - 7) SPMC does internal state management, de-activates the physical interrupt
1182 and resumes SP1 vCPU.
1183 - 8) Assuming SP1 is in BLOCKED state, SP1 performs secure interrupt completion
1184 through FFA_RUN ABI.
1185 - 9) SPMC resumes the pre-empted vCPU of SP2.
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001186
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001187
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001188Power management
1189----------------
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001190
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001191In platforms with or without secure virtualization:
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001192
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001193- The NWd owns the platform PM policy.
1194- The Hypervisor or OS kernel is the component initiating PSCI service calls.
1195- The EL3 PSCI library is in charge of the PM coordination and control
1196 (eventually writing to platform registers).
1197- While coordinating PM events, the PSCI library calls backs into the Secure
1198 Payload Dispatcher for events the latter has statically registered to.
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001199
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001200When using the SPMD as a Secure Payload Dispatcher:
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001201
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001202- A power management event is relayed through the SPD hook to the SPMC.
1203- In the current implementation only cpu on (svc_on_finish) and cpu off
1204 (svc_off) hooks are registered.
1205- The behavior for the cpu on event is described in `Secondary cores boot-up`_.
1206 The SPMC is entered through its secondary physical core entry point.
Olivier Deprez3de57e32022-04-28 18:18:36 +02001207- The cpu off event occurs when the NWd calls PSCI_CPU_OFF. The PM event is
1208 signaled to the SPMC through a power management framework message.
1209 It consists in a SPMD-to-SPMC direct request/response (`SPMC-SPMD direct
1210 requests/responses`_) conveying the event details and SPMC response.
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001211 The SPMD performs a synchronous entry into the SPMC. The SPMC is entered and
1212 updates its internal state to reflect the physical core is being turned off.
1213 In the current implementation no SP is resumed as a consequence. This behavior
1214 ensures a minimal support for CPU hotplug e.g. when initiated by the NWd linux
1215 userspace.
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001216
Olivier Deprez3de57e32022-04-28 18:18:36 +02001217Arm architecture extensions for security hardening
1218==================================================
1219
1220Hafnium supports the following architecture extensions for security hardening:
1221
1222- Pointer authentication (FEAT_PAuth): the extension permits detection of forged
1223 pointers used by ROP type of attacks through the signing of the pointer
1224 value. Hafnium is built with the compiler branch protection option to permit
1225 generation of a pointer authentication code for return addresses (pointer
1226 authentication for instructions). The APIA key is used while Hafnium runs.
1227 A random key is generated at boot time and restored upon entry into Hafnium
1228 at run-time. APIA and other keys (APIB, APDA, APDB, APGA) are saved/restored
1229 in vCPU contexts permitting to enable pointer authentication in VMs/SPs.
1230- Branch Target Identification (FEAT_BTI): the extension permits detection of
1231 unexpected indirect branches used by JOP type of attacks. Hafnium is built
1232 with the compiler branch protection option, inserting land pads at function
1233 prologues that are reached by indirect branch instructions (BR/BLR).
1234 Hafnium code pages are marked as guarded in the EL2 Stage-1 MMU descriptors
1235 such that an indirect branch must always target a landpad. A fault is
1236 triggered otherwise. VMs/SPs can (independently) mark their code pages as
1237 guarded in the EL1&0 Stage-1 translation regime.
1238- Memory Tagging Extension (FEAT_MTE): the option permits detection of out of
1239 bound memory array accesses or re-use of an already freed memory region.
1240 Hafnium enables the compiler option permitting to leverage MTE stack tagging
1241 applied to core stacks. Core stacks are marked as normal tagged memory in the
1242 EL2 Stage-1 translation regime. A synchronous data abort is generated upon tag
1243 check failure on load/stores. A random seed is generated at boot time and
1244 restored upon entry into Hafnium. MTE system registers are saved/restored in
1245 vCPU contexts permitting MTE usage from VMs/SPs.
1246
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001247SMMUv3 support in Hafnium
1248=========================
Madhukar Pappireddya9859062021-02-28 14:01:34 -06001249
1250An SMMU is analogous to an MMU in a CPU. It performs address translations for
1251Direct Memory Access (DMA) requests from system I/O devices.
1252The responsibilities of an SMMU include:
1253
1254- Translation: Incoming DMA requests are translated from bus address space to
1255 system physical address space using translation tables compliant to
1256 Armv8/Armv7 VMSA descriptor format.
1257- Protection: An I/O device can be prohibited from read, write access to a
1258 memory region or allowed.
1259- Isolation: Traffic from each individial device can be independently managed.
1260 The devices are differentiated from each other using unique translation
1261 tables.
1262
1263The following diagram illustrates a typical SMMU IP integrated in a SoC with
1264several I/O devices along with Interconnect and Memory system.
1265
1266.. image:: ../resources/diagrams/MMU-600.png
1267
1268SMMU has several versions including SMMUv1, SMMUv2 and SMMUv3. Hafnium provides
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001269support for SMMUv3 driver in both normal and secure world. A brief introduction
Madhukar Pappireddya9859062021-02-28 14:01:34 -06001270of SMMUv3 functionality and the corresponding software support in Hafnium is
1271provided here.
1272
1273SMMUv3 features
1274---------------
1275
1276- SMMUv3 provides Stage1, Stage2 translation as well as nested (Stage1 + Stage2)
1277 translation support. It can either bypass or abort incoming translations as
1278 well.
1279- Traffic (memory transactions) from each upstream I/O peripheral device,
1280 referred to as Stream, can be independently managed using a combination of
1281 several memory based configuration structures. This allows the SMMUv3 to
1282 support a large number of streams with each stream assigned to a unique
1283 translation context.
1284- Support for Armv8.1 VMSA where the SMMU shares the translation tables with
1285 a Processing Element. AArch32(LPAE) and AArch64 translation table format
1286 are supported by SMMUv3.
1287- SMMUv3 offers non-secure stream support with secure stream support being
1288 optional. Logically, SMMUv3 behaves as if there is an indepdendent SMMU
1289 instance for secure and non-secure stream support.
1290- It also supports sub-streams to differentiate traffic from a virtualized
1291 peripheral associated with a VM/SP.
1292- Additionally, SMMUv3.2 provides support for PEs implementing Armv8.4-A
1293 extensions. Consequently, SPM depends on Secure EL2 support in SMMUv3.2
1294 for providing Secure Stage2 translation support to upstream peripheral
1295 devices.
1296
1297SMMUv3 Programming Interfaces
1298-----------------------------
1299
1300SMMUv3 has three software interfaces that are used by the Hafnium driver to
1301configure the behaviour of SMMUv3 and manage the streams.
1302
1303- Memory based data strutures that provide unique translation context for
1304 each stream.
1305- Memory based circular buffers for command queue and event queue.
1306- A large number of SMMU configuration registers that are memory mapped during
1307 boot time by Hafnium driver. Except a few registers, all configuration
1308 registers have independent secure and non-secure versions to configure the
1309 behaviour of SMMUv3 for translation of secure and non-secure streams
1310 respectively.
1311
1312Peripheral device manifest
1313--------------------------
1314
1315Currently, SMMUv3 driver in Hafnium only supports dependent peripheral devices.
1316These devices are dependent on PE endpoint to initiate and receive memory
1317management transactions on their behalf. The acccess to the MMIO regions of
1318any such device is assigned to the endpoint during boot. Moreover, SMMUv3 driver
1319uses the same stage 2 translations for the device as those used by partition
1320manager on behalf of the PE endpoint. This ensures that the peripheral device
1321has the same visibility of the physical address space as the endpoint. The
1322device node of the corresponding partition manifest (refer to `[1]`_ section 3.2
1323) must specify these additional properties for each peripheral device in the
1324system :
1325
1326- smmu-id: This field helps to identify the SMMU instance that this device is
1327 upstream of.
1328- stream-ids: List of stream IDs assigned to this device.
1329
1330.. code:: shell
1331
1332 smmuv3-testengine {
1333 base-address = <0x00000000 0x2bfe0000>;
1334 pages-count = <32>;
1335 attributes = <0x3>;
1336 smmu-id = <0>;
1337 stream-ids = <0x0 0x1>;
1338 interrupts = <0x2 0x3>, <0x4 0x5>;
1339 exclusive-access;
1340 };
1341
1342SMMUv3 driver limitations
1343-------------------------
1344
1345The primary design goal for the Hafnium SMMU driver is to support secure
1346streams.
1347
1348- Currently, the driver only supports Stage2 translations. No support for
1349 Stage1 or nested translations.
1350- Supports only AArch64 translation format.
1351- No support for features such as PCI Express (PASIDs, ATS, PRI), MSI, RAS,
1352 Fault handling, Performance Monitor Extensions, Event Handling, MPAM.
1353- No support for independent peripheral devices.
1354
Raghu Krishnamurthy7f3f7ce2021-10-17 16:48:29 -07001355S-EL0 Partition support
Olivier Deprez3de57e32022-04-28 18:18:36 +02001356=======================
Raghu Krishnamurthy7f3f7ce2021-10-17 16:48:29 -07001357The SPMC (Hafnium) has limited capability to run S-EL0 FF-A partitions using
1358FEAT_VHE (mandatory with ARMv8.1 in non-secure state, and in secure world
1359with ARMv8.4 and FEAT_SEL2).
1360
1361S-EL0 partitions are useful for simple partitions that don't require full
1362Trusted OS functionality. It is also useful to reduce jitter and cycle
1363stealing from normal world since they are more lightweight than VMs.
1364
1365S-EL0 partitions are presented, loaded and initialized the same as S-EL1 VMs by
1366the SPMC. They are differentiated primarily by the 'exception-level' property
1367and the 'execution-ctx-count' property in the SP manifest. They are host apps
1368under the single EL2&0 Stage-1 translation regime controlled by the SPMC and
1369call into the SPMC through SVCs as opposed to HVCs and SMCs. These partitions
1370can use FF-A defined services (FFA_MEM_PERM_*) to update or change permissions
1371for memory regions.
1372
1373S-EL0 partitions are required by the FF-A specification to be UP endpoints,
1374capable of migrating, and the SPMC enforces this requirement. The SPMC allows
1375a S-EL0 partition to accept a direct message from secure world and normal world,
1376and generate direct responses to them.
1377
1378Memory sharing between and with S-EL0 partitions is supported.
1379Indirect messaging, Interrupt handling and Notifications are not supported with
1380S-EL0 partitions and is work in progress, planned for future releases.
1381All S-EL0 partitions must use AArch64. AArch32 S-EL0 partitions are not
1382supported.
1383
1384
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001385References
1386==========
1387
1388.. _[1]:
1389
Olivier Deprez2b0be752021-09-01 10:25:21 +02001390[1] `Arm Firmware Framework for Arm A-profile <https://developer.arm.com/docs/den0077/latest>`__
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001391
1392.. _[2]:
1393
Madhukar Pappireddy86350ae2020-07-29 09:37:25 -05001394[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>`
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001395
1396.. _[3]:
1397
1398[3] `Trusted Boot Board Requirements
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001399Client <https://developer.arm.com/documentation/den0006/d/>`__
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001400
1401.. _[4]:
1402
1403[4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/lib/el3_runtime/aarch64/context.S#n45
1404
1405.. _[5]:
1406
Olivier Deprez5e0a73f2021-04-30 14:42:24 +02001407[5] https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/spm/cactus/plat/arm/fvp/fdts/cactus.dts
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001408
1409.. _[6]:
1410
Olivier Deprez9938c132021-04-21 11:22:23 +02001411[6] https://trustedfirmware-a.readthedocs.io/en/latest/components/ffa-manifest-binding.html
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001412
1413.. _[7]:
1414
1415[7] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_spmc_manifest.dts
1416
1417.. _[8]:
1418
Sandrine Bailleux1a4efb12022-04-21 10:17:22 +02001419[8] https://lists.trustedfirmware.org/archives/list/tf-a@lists.trustedfirmware.org/thread/CFQFGU6H2D5GZYMUYGTGUSXIU3OYZP6U/
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001420
Olivier Deprez4ab7a4a2021-06-21 09:47:13 +02001421.. _[9]:
1422
1423[9] https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#dynamic-configuration-during-cold-boot
1424
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001425--------------
1426
Imre Kis3f370fd2022-02-08 18:06:18 +01001427*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*