blob: c58cd0801a07c54102197b7de88541b73af738b8 [file] [log] [blame]
Olivier Deprezecb2fe52020-04-02 15:38:02 +02001Secure Partition Manager
2************************
3
4.. contents::
5
6Acronyms
7========
8
9+--------+-----------------------------------+
10| DTB | Device Tree Blob |
11+--------+-----------------------------------+
12| DTS | Device Tree Source |
13+--------+-----------------------------------+
14| EC | Execution Context |
15+--------+-----------------------------------+
16| FIP | Firmware Image Package |
17+--------+-----------------------------------+
18| FF-A | Firmware Framework for A-class |
19+--------+-----------------------------------+
20| IPA | Intermediate Physical Address |
21+--------+-----------------------------------+
22| NWd | Normal World |
23+--------+-----------------------------------+
24| ODM | Original Design Manufacturer |
25+--------+-----------------------------------+
26| OEM | Original Equipment Manufacturer |
27+--------+-----------------------------------+
28| PA | Physical Address |
29+--------+-----------------------------------+
30| PE | Processing Element |
31+--------+-----------------------------------+
32| PVM | Primary VM |
33+--------+-----------------------------------+
34| PSA | Platform Security Architecture |
35+--------+-----------------------------------+
36| SP | Secure Partition |
37+--------+-----------------------------------+
38| SPM | Secure Partition Manager |
39+--------+-----------------------------------+
40| SPMC | SPM Core |
41+--------+-----------------------------------+
42| SPMD | SPM Dispatcher |
43+--------+-----------------------------------+
44| SiP | Silicon Provider |
45+--------+-----------------------------------+
46| SWd | Secure World |
47+--------+-----------------------------------+
48| TLV | Tag-Length-Value |
49+--------+-----------------------------------+
50| TOS | Trusted Operating System |
51+--------+-----------------------------------+
52| VM | Virtual Machine |
53+--------+-----------------------------------+
54
55Foreword
56========
57
58Two implementations of a Secure Partition Manager co-exist in the TF-A codebase:
59
60- SPM based on the PSA FF-A specification `[1]`_.
61- SPM based on the MM interface to communicate with an S-EL0 partition `[2]`_.
62
63Both implementations differ in their architectures and only one can be selected
64at build time.
65
66This document:
67
68- describes the PSA FF-A implementation where the Secure Partition Manager
69 resides at EL3 and S-EL2 (or EL3 and S-EL1).
70- is not an architecture specification and it might provide assumptions
71 on sections mandated as implementation-defined in the specification.
72- covers the implications to TF-A used as a bootloader, and Hafnium
73 used as a reference code base for an S-EL2 secure firmware on
74 platforms implementing Armv8.4-SecEL2.
75
76Terminology
77-----------
78
79- Hypervisor refers to the NS-EL2 component managing Virtual Machines (or
80 partitions) in the Normal World.
81- SPMC refers to the S-EL2 component managing Virtual Machines (or Secure
82 Partitions) in the Secure World when Armv8.4-SecEL2 extension is implemented.
83- Alternatively, SPMC can refer to an S-EL1 component, itself being a Secure
84 Partition and implementing the FF-A ABI on pre-Armv8.4 platforms.
85- VM refers to a Normal World Virtual Machine managed by an Hypervisor.
86- SP refers to a Secure World "Virtual Machine" managed by the SPMC component.
87
88Support for legacy platforms
89----------------------------
90
91In the implementation, the SPM is split into SPMD and SPMC components
92(although not strictly mandated by the specification). SPMD is located
93at EL3 and principally relays FF-A messages from NWd (Hypervisor or OS
94kernel) to SPMC located either at S-EL1 or S-EL2.
95
96Hence TF-A must support both cases where SPMC is either located at:
97
98- S-EL1 supporting pre-Armv8.4 platforms. SPMD conveys FF-A protocol
99 from EL3 to S-EL1.
100- S-EL2 supporting platforms implementing Armv8.4-SecEL2 extension.
101 SPMD conveys FF-A protocol from EL3 to S-EL2.
102
103The same SPMD component is used to support both configurations. The SPMC
104execution level is a build time choice.
105
106Sample reference stack
107======================
108
109The following diagram illustrates a possible configuration with SPMD and SPMC,
110one or multiple Secure Partitions, with or without an optional Hypervisor:
111
112.. image:: ../resources/diagrams/ff-a-spm-sel2.png
113
114TF-A build options
115==================
116
117The following TF-A build options are provisioned:
118
119- **SPD=spmd**: this option selects the SPMD component to relay FF-A
120 protocol from NWd to SWd back and forth. It is not possible to
121 enable another Secure Payload Dispatcher when this option is chosen.
122- **SPMD_SPM_AT_SEL2**: this option adjusts the SPMC execution
123 level to being S-EL1 or S-EL2. It defaults to enabled (value 1) when
124 SPD=spmd is chosen.
125- **CTX_INCLUDE_EL2_REGS**: this option permits saving (resp.
126 restoring) the EL2 system register context before entering (resp.
127 after leaving) the SPMC. It is mandatory when ``SPMD_SPM_AT_SEL2`` is
128 enabled. The context save/restore routine and exhaustive list of
Madhukar Pappireddy423d18c2020-08-06 12:36:17 -0500129 registers is visible at `[4]`_.
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200130- **SP_LAYOUT_FILE**: this option provides a text description file
131 providing paths to SP binary images and DTS format manifests
132 (see `Specifying partition binary image and DT`_). It
133 is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple
134 secure partitions are to be loaded on behalf of SPMC.
135
136+------------------------------+----------------------+------------------+
137| | CTX_INCLUDE_EL2_REGS | SPMD_SPM_AT_SEL2 |
138+------------------------------+----------------------+------------------+
139| SPMC at S-EL1 (e.g. OP-TEE) | 0 | 0 |
140+------------------------------+----------------------+------------------+
141| SPMC at S-EL2 (e.g. Hafnium) | 1 | 1 (default when |
142| | | SPD=spmd) |
143+------------------------------+----------------------+------------------+
144
145Other combinations of such build options either break the build or are not
146supported.
147
148Note, the ``CTX_INCLUDE_EL2_REGS`` option provides the generic support for
149barely saving/restoring EL2 registers from an Arm arch perspective. As such
150it is decoupled from the ``SPD=spmd`` option.
151
152BL32 option is re-purposed to specify the SPMC image. It can specify either the
153Hafnium binary path (built for the secure world) or the path to a TEE binary
154implementing the FF-A protocol.
155
156BL33 option can specify either:
157
158- the TFTF binary or
159- the Hafnium binary path (built for the normal world) if VMs were loaded by
160 TF-A beforehand or
161- a minimal loader performing the loading of VMs and Hafnium.
162
163Sample TF-A build command line when SPMC is located at S-EL1
164(typically pre-Armv8.4):
165
166.. code:: shell
167
168 make \
169 CROSS_COMPILE=aarch64-none-elf- \
170 SPD=spmd \
171 SPMD_SPM_AT_SEL2=0 \
172 BL32=<path-to-tee-binary> \
173 BL33=<path-to-nwd-binary> \
174 PLAT=fvp \
175 all fip
176
177Sample TF-A build command line for an Armv8.4-SecEL2 enabled system
178where SPMC is located at S-EL2:
179
180.. code:: shell
181
182 make \
183 CROSS_COMPILE=aarch64-none-elf- \
184 SPD=spmd \
185 CTX_INCLUDE_EL2_REGS=1 \
186 ARM_ARCH_MINOR=4 \
187 BL32=<path-to-swd-hafnium-binary>
188 BL33=<path-to-nwd-binary> \
189 SP_LAYOUT_FILE=sp_layout.json \
190 PLAT=fvp \
191 all fip
192
193Build options to enable secure boot:
194
195.. code:: shell
196
197 make \
198 CROSS_COMPILE=aarch64-none-elf- \
199 SPD=spmd \
200 CTX_INCLUDE_EL2_REGS=1 \
201 ARM_ARCH_MINOR=4 \
202 BL32=<path-to-swd-hafnium-binary>
203 BL33=<path-to-nwd-binary> \
204 SP_LAYOUT_FILE=../tf-a-tests/build/fvp/debug/sp_layout.json \
205 MBEDTLS_DIR=<path-to-mbedtls-lib> \
206 TRUSTED_BOARD_BOOT=1 \
207 COT=dualroot \
208 ARM_ROTPK_LOCATION=devel_rsa \
209 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
210 GENERATE_COT=1 \
211 PLAT=fvp \
212 all fip
213
214Boot process
215============
216
217Loading Hafnium and Secure Partitions in the secure world
218---------------------------------------------------------
219
220The Hafnium implementation in normal world requires VMs to be loaded in
221memory prior to booting. The mechanism upon which VMs are loaded and
222exposed to Hafnium are either:
223
224- by supplying a ramdisk image where VM images are concatenated (1)
225- or by providing VM load addresses within Hafnium manifest (2)
226
227TF-A is the bootlader for the Hafnium and SPs in the secure world. TF-A
228does not provide tooling or libraries manipulating ramdisks as required
229by (1). Thus BL2 loads SPs payloads independently.
230SPs may be signed by different parties (SiP, OEM/ODM, TOS vendor, etc.).
231Thus they are supplied as distinct ā€œself-containedā€ signed entities within
232the FIP flash image. The FIP image itself is not signed hence providing
233ability to upgrade SPs in the field.
234
235Booting through TF-A
236--------------------
237
238SP manifests
239~~~~~~~~~~~~
240
241An SP manifest describes SP attributes as defined in `[1]`_
242section 3.1 (partition manifest at virtual FF-A instance) in DTS text format. It
243is represented as a single file associated with the SP. A sample is
244provided by `[5]`_. A binding document is provided by `[6]`_.
245
246Secure Partition packages
247~~~~~~~~~~~~~~~~~~~~~~~~~
248
249Secure Partitions are bundled as independent package files consisting
250of:
251
252- a header
253- a DTB
254- an image payload
255
256The header starts with a magic value and offset values to SP DTB and
257image payload. Each SP package is loaded independently by BL2 loader
258and verified for authenticity and integrity.
259
260The SP package identified by its UUID (matching FF-A uuid) is inserted
261as a single entry into the FIP at end of the TF-A build flow as shown:
262
263.. code:: shell
264
265 Trusted Boot Firmware BL2: offset=0x1F0, size=0x8AE1, cmdline="--tb-fw"
266 EL3 Runtime Firmware BL31: offset=0x8CD1, size=0x13000, cmdline="--soc-fw"
267 Secure Payload BL32 (Trusted OS): offset=0x1BCD1, size=0x15270, cmdline="--tos-fw"
268 Non-Trusted Firmware BL33: offset=0x30F41, size=0x92E0, cmdline="--nt-fw"
269 HW_CONFIG: offset=0x3A221, size=0x2348, cmdline="--hw-config"
270 TB_FW_CONFIG: offset=0x3C569, size=0x37A, cmdline="--tb-fw-config"
271 SOC_FW_CONFIG: offset=0x3C8E3, size=0x48, cmdline="--soc-fw-config"
272 TOS_FW_CONFIG: offset=0x3C92B, size=0x427, cmdline="--tos-fw-config"
273 NT_FW_CONFIG: offset=0x3CD52, size=0x48, cmdline="--nt-fw-config"
274 B4B5671E-4A90-4FE1-B81F-FB13DAE1DACB: offset=0x3CD9A, size=0xC168, cmdline="--blob"
275 D1582309-F023-47B9-827C-4464F5578FC8: offset=0x48F02, size=0xC168, cmdline="--blob"
276
277.. uml:: ../resources/diagrams/plantuml/fip-secure-partitions.puml
278
279Specifying partition binary image and DT
280~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
281
282A description file (json format) is passed to the build flow specifying
283paths to the SP binary image and associated DTS partition manifest file.
284The latter is going through the dtc compiler to generate the dtb fed into
285the SP package.
286
287.. code:: shell
288
289 {
290 "tee1" : {
291 "image": "tee1.bin",
292 "pm": "tee1.dts"
293 },
294
295 "tee2" : {
296 "image": "tee2.bin",
297 "pm": "tee2.dts"
298 }
299 }
300
301SPMC manifest
302~~~~~~~~~~~~~
303
304This manifest contains an SPMC attributes node consumed by SPMD at boot time. It
305is implementing the description from `[1]`_ section 3.2 (SP manifest at physical
306FF-A instance). The SP manifest at physical FF-A instance is used by the SPMD to
307setup a SP that co-resides with the SPMC and executes at S-EL1 or Secure
308Supervisor mode.
309
310In this implementation its usage is extended to the secure physical FF-A
311instance where SPMC executes at S-EL2.
312
313.. code:: shell
314
315 attribute {
316 spmc_id = <0x8000>;
317 maj_ver = <0x1>;
318 min_ver = <0x0>;
319 exec_state = <0x0>;
320 load_address = <0x0 0x6000000>;
321 entrypoint = <0x0 0x6000000>;
322 binary_size = <0x60000>;
323 };
324
325- *spmc_id* defines the endpoint ID value that SPMC can query through
326 ``FFA_ID_GET``.
327- *maj_ver/min_ver*. SPMD checks provided version versus its internal
328 version and aborts if not matching.
329- *exec_state* defines SPMC execution state (can be AArch64 for
330 Hafnium, or AArch64/AArch32 for OP-TEE at S-EL1).
331- *load_address* and *binary_size* are mostly used to verify secondary
332 entry points fit into the loaded binary image.
333- *entrypoint* defines the cold boot primary core entry point used by
334 SPMD (currently matches ``BL32_BASE``)
335
336Other nodes in the manifest are consumed by Hafnium in the secure world.
337A sample can be found at [7]:
338
339- The *chosen* node is currently unused in SWd. It is meant for NWd to
340 specify the init ramdisk image.
341- The *hypervisor* node describes SPs. *is_ffa_partition* boolean
342 attribute indicates an SP. Load-addr field specifies the load address
343 at which TF-A loaded the SP package.
344- *cpus* node provide the platform topology and allows MPIDR to VMPIDR
345 mapping. Notice with current implementation primary cpu is declared
346 first, then secondary cpus must be declared in reverse order.
347
348SPMC boot
349~~~~~~~~~
350
351The SPMC is loaded by BL2 as the BL32 image.
352
353The SPMC manifest is loaded by BL2 as the ``TOS_FW_CONFIG`` image.
354
355BL2 passes the SPMC manifest address to BL31 through a register.
356
357BL31(SPMD) runs from primary core, initializes the core contexts and
358launches BL32 passing the SPMC manifest address through a register.
359
360Loading of SPs
361~~~~~~~~~~~~~~
362
363.. uml:: ../resources/diagrams/plantuml/bl2-loading-sp.puml
364
365
366Notice this boot flow is an implementation sample on Arm's FVP platform. Platforms
367not using FW_CONFIG would adjust to a different implementation.
368
369Secure boot
370~~~~~~~~~~~
371
372The SP content certificate is inserted as a separate FIP item so that BL2 loads SPMC,
373SPMC manifest and Secure Partitions and verifies them for authenticity and integrity.
374Refer to TBBR specification `[3]`_.
375
376The multiple-signing domain feature (in current state dual signing domain) allows
377the use of two root keys namely S-ROTPK and NS-ROTPK (see `[8]`_):
378
379- SPMC(BL32), SPMC manifest, SPs may be signed by the SiP using the S-ROTPK.
380- BL33 may be signed by the OEM using NS-ROTPK.
381
382Longer term multiple signing domain will allow additional signing keys, e.g.
383if SPs originate from different parties.
384
385See `TF-A build options`_ for a sample build command line.
386
387Hafnium in the secure world
388===========================
389
390**NOTE: this section is work in progress. Descriptions and implementation choices
391are subject to evolve.**
392
393General considerations
394----------------------
395
396Build platform for the secure world
397~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
398
399The implementation might add specific code parts only relevant to the
400secure world. Such code parts might be isolated into different files
401and/or conditional code enclosed by a ``SECURE_WORLD`` macro.
402
403Secure Partitions CPU scheduling
404~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
405
406In the normal world, VMs are scheduled by the FFA_RUN ABI invoked from the
407primary scheduler (in the primary VM), or by a direct message request or
408response.
409
410With the FF-A EAC specification, Secure Partitions are scheduled by direct
411message invocations from a NWd VM or another SP.
412
413Platform topology
414~~~~~~~~~~~~~~~~~
415
416As stated in `[1]`_ section 4.4.1 the SPMC implementation assumes the
417following SP types:
418
419- Pinned MP SPs: an Execution Context id matches a physical PE id. MP
420 SPs must implement the same number of ECs as the number of PEs in the
421 platform. Hence the *execution-ctx-count* as defined by
422 `[1]`_ (or NWd-Hafnium *vcpu_count*) can only take the
423 value of one or the number of physical PEs.
424- Migratable UP SPs: a single execution context can run and be migrated
425 on any physical PE. It declares a single EC in its SP manifest. An UP
426 SP can receive a direct message request on any physical core.
427
428Usage of PSCI services in the secure world
429~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
430
431- The normal world Hypervisor (optional) or OS kernel issues PSCI service
432 invocations e.g. to request PSCI version, wake-up a secondary core, or request
433 core suspend. This happens at the non-secure physical FF-A instance. In the
434 example case of Hafnium in the normal world, it boots on the primary core and
435 one of the first initialization step is to request the PSCI version. It then
436 launches the primary VM. The primary VM upon initializing performs PSCI service
437 calls (at non-secure virtual FF-A instance) which are trapped by the
438 Hypervisor. Invocation from OS Kernel ends straight at EL3. The PVM issues
439 ``PSCI_CPU_ON`` service calls to wake-up secondary cores by passing an
440 ``MPIDR``, entry point address and a CPU context address. The EL3 PSCI layer
441 then performs an exception return to the secondary core entry point on the
442 targeted core. Other PSCI calls can happen at run-time from the PVM e.g. to
443 request core suspend.
444- In the existing TF-A PSCI standard library, PSCI service calls are filtered at
445 EL3 to only originate from the NWd. Thus concerning the SPMC (at secure
446 physical FF-A instance) the PSCI service invocations cannot happen as in the
447 normal world. For example, a ``PSCI_CPU_ON`` service invocation from the SPMC
448 does not reach the PSCI layer.
449
450Parsing SP partition manifests
451------------------------------
452
453Hafnium must be able to consume SP manifests as defined in
454`[1]`_ section 3.1, at least for the mandatory fields.
455
456The SP manifest may contain memory and device regions nodes.
457
458- Memory regions shall be mapped in the SP Stage-2 translation regime at
459 load time. A memory region node can specify RX/TX buffer regions in which
460 case it is not necessary for an SP to explicitly call the ``FFA_RXTX_MAP``
461 service.
462- Device regions shall be mapped in SP Stage-2 translation regime as
463 peripherals and possibly allocate additional resources (e.g. interrupts)
464
465Base addresses for memory and device region nodes are IPAs provided SPMC
466identity maps IPAs to PAs within SP Stage-2 translation regime.
467
468Note: currently both VTTBR_EL2 and VSTTBR_EL2 resolve to the same set of page
469tables. It is still open whether two sets of page tables shall be provided per
470SP. The memory region node as defined in the spec (section 3.1 Table 10)
471provides a memory security attribute hinting to map either to the secure or
472non-secure stage-2 table.
473
474Passing boot data to the SP
475---------------------------
476
477`[1]`_ Section 3.4.2 ā€œProtocol for passing dataā€ defines a
478method to passing boot data to SPs (not currently implemented).
479
480Provided that the whole Secure Partition package image (see `Secure
481Partition packages`_) is mapped to the SP's secure Stage-2 translation
482regime, an SP can access its own manifest DTB blob and extract its partition
483manifest properties.
484
485SP Boot order
486-------------
487
488SP manifests provide an optional boot order attribute meant to resolve
489dependencies such as an SP providing a service required to properly boot
490another SP.
491
492Boot phases
493-----------
494
495Primary core boot-up
496~~~~~~~~~~~~~~~~~~~~
497
498The SPMC performs its platform initializations then loads and creates
499secure partitions based on SP packages and manifests. Then each secure
500partition is launched in sequence (see `SP Boot order`_) on their primary
501Execution Context.
502
503Notice the primary physical core may not be core 0. Hence if the primary
504core linear id is N, the 1:1 mapping requires MP SPs are launched using
505EC[N] on PE[N] (see `Platform topology`_).
506
507The SP's primary Execution Context (or the EC used when the partition is booted)
508exits through ``FFA_MSG_WAIT`` to indicate successful initialization.
509
510Secondary physical core boot-up
511~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
512
513Upon boot-up, the SPMC running on the primary core performs
514implementation-defined SPMD service calls at secure physical FF-A instance
515to register the secondary physical cores entry points and context information:
516
517- This is done through a direct message request invocation to the SPMD
518 (``SET_ENTRY_POINT``). This service call does not wake-up the targeted
519 core immediately. The secondary core is woken up later by a NWd
520 ``PSCI_CPU_ON`` service invocation. A notification is passed from EL3
521 PSCI layer to the SPMD, and then to SPMC through an implementation-defined
522 interface.
523- The SPMC/SPMD interface can consist of FF-A direct message requests/responses
524 transporting PM events.
525
526If there is no Hypervisor in the normal world, the OS Kernel issues
527``PSCI_CPU_ON`` calls that are directly trapped to EL3.
528
529When a secondary physical core wakes-up the SPMD notifies the SPMC which updates
530its internal states reflecting current physical core is being turned on.
531It might then return straight to the SPMD and then to the NWd.
532
533*(under discussion)* There may be possibility that an SP registers "PM events"
534(during primary EC boot stage) through an ad-hoc interface. Such events would
535be relayed by SPMC to one or more registered SPs on need basis
536(see `Power management`_).
537
538Secondary virtual core boot-up
539~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
540
541In the example case where Hafnium exists in the normal world, secondary VMs
542issue a ``PSCI_CPU_ON`` service call which is trapped to the Hypervisor. The
543latter then enables the vCPU context for the targeted core, and switches to
544the PVM down to the kernel driver with an ``HF_WAKE_UP`` message. The NWd
545driver in PVM can then schedule the newly woken up vCPU context.
546
547In the secure world the primary EC of a given SP passes the secondary EC entry
548point and context. The SMC service call is trapped into the SPMC. This can be
549either *(under discussion)*:
550
551- a specific interface registering the secondary EC entry point,
552 similarly to above ``SET_ENTRY_POINT`` service.
553- Re-purposing the ``PSCI_CPU_ON`` function id. It is
554 assumed that even if the input arguments are the same as the ones defined in
555 the PSCI standard, the usage deviates by the fact the secondary EC is not
556 woken up immediately. At least for the PSA-FF-A EAC where only
557 direct messaging is allowed, it is only after the first direct
558 message invocation that the secondary EC is entered. This option
559 might be preferred when the same code base is re-used for a VM or
560 an SP. The ABI to wake-up a secondary EC can remain similar.
561
562SPs are always scheduled from the NWd, this paradigm did not change from legacy
563TEEs. There must always be some logic (or driver) in the NWd to relinquish CPU
564cycles to the SWd. If primary core is 0, an SP EC[x>0] entry point is supplied
565by the SP EC[0] when the system boots in SWd. But this EC[x] is not immediately
566entered at boot. Later in the boot process when NWd is up, a direct message
567request issued from physical core 1 ends up in SP EC[1], and only at this stage
568this context is effectively scheduled.
569
570It should be possible for an SP to call into another SP through direct message
571provided the latter SP has been booted already. The "boot-order" field in
572partition manifests (`SP Boot order`_) fulfills the dependency towards availability
573of a service within an SP offered to another SP.
574
575Mandatory interfaces
576--------------------
577
578The following interfaces must be exposed to any VM or SP:
579
580- ``FFA_STATUS``
581- ``FFA_ERROR``
582- ``FFA_INTERRUPT``
583- ``FFA_VERSION``
584- ``FFA_FEATURES``
585- ``FFA_RX_RELEASE``
586- ``FFA_RXTX_MAP``
587- ``FFA_RXTX_UNMAP``
588- ``FFA_PARTITION_INFO_GET``
589- ``FFA_ID_GET``
590
591FFA_VERSION
592~~~~~~~~~~~
593
594Per `[1]`_ section 8.1 ``FFA_VERSION`` requires a
595*requested_version* parameter from the caller.
596
597In the current implementation when ``FFA_VERSION`` is invoked from:
598
599- Hypervisor in NS-EL2: the SPMD returns the SPMC version specified
600 in the SPMC manifest.
601- OS kernel in NS-EL1 when NS-EL2 is not present: the SPMD returns the
602 SPMC version specified in the SPMC manifest.
603- VM in NWd: the Hypervisor returns its implemented version.
604- SP in SWd: the SPMC returns its implemented version.
605- SPMC at S-EL1/S-EL2: the SPMD returns its implemented version.
606
607FFA_FEATURES
608~~~~~~~~~~~~
609
610FF-A features may be discovered by Secure Partitions while booting
611through the SPMC. However, SPMC cannot get features from Hypervisor
612early at boot time as NS world is not setup yet.
613
614The Hypervisor may decide to gather FF-A features from SPMC through SPMD
615once at boot time and store the result. Later when a VM requests FF-A
616features, the Hypervisor can adjust its own set of features with what
617SPMC advertised, if necessary. Another approach is to always forward FF-A
618features to the SPMC when a VM requests it to the Hypervisor. Although
619the result is not supposed to change over time so there may not be added
620value doing the systematic forwarding.
621
622FFA_RXTX_MAP/FFA_RXTX_UNMAP
623~~~~~~~~~~~~~~~~~~~~~~~~~~~
624
625VM mailboxes are re-purposed to serve as SP RX/TX buffers. The RX/TX
626map API maps the send and receive buffer IPAs to the SP Stage-2 translation regime.
627
628Hafnium in the normal world defines VMs and their attributes as logical structures,
629including a mailbox used for FF-A indirect messaging, memory sharing, or the
630`FFA_PARTITION_INFO_GET`_ ABI.
631This same mailbox structure is re-used in the SPMC. `[1]`_ states only direct
632messaging is allowed to SPs. Thus mailbox usage is restricted to implementing
633`FFA_PARTITION_INFO_GET`_ and memory sharing ABIs.
634
635FFA_PARTITION_INFO_GET
636~~~~~~~~~~~~~~~~~~~~~~
637
638Partition info get service call can originate:
639
640- from SP to SPM
641- from VM to Hypervisor
642- from Hypervisor to SPM
643
644For the latter case, the service call must be forwarded through the SPMD.
645
646FFA_ID_GET
647~~~~~~~~~~
648
649The SPMD returns:
650
651- a default zero value on invocation from the Hypervisor.
652- The ``spmc_id`` value specified in the SPMC manifest on invocation from
653 the SPMC (see `SPMC manifest`_)
654
655The FF-A id space is split into a non-secure space and secure space:
656
657- FF-A id with bit 15 clear refer to normal world VMs.
658- FF-A id with bit 15 set refer to secure world SPs
659
660Such convention helps the SPMC discriminating the origin and destination worlds
661in an FF-A service invocation. In particular the SPMC shall filter unauthorized
662transactions in its world switch routine. It must not be permitted for a VM to
663use a secure FF-A id as origin world through spoofing:
664
665- A VM-to-SP messaging passing shall have an origin world being non-secure
666 (FF-A id bit 15 clear) and destination world being secure (FF-A id bit 15
667 set).
668- Similarly, an SP-to-SP message shall have FF-A id bit 15 set for both origin
669 and destination ids.
670
671An incoming direct message request arriving at SPMD from NWd is forwarded to
672SPMC without a specific check. The SPMC is resumed through eret and "knows" the
673message is coming from normal world in this specific code path. Thus the origin
674endpoint id must be checked by SPMC for being a normal world id.
675
676An SP sending a direct message request must have bit 15 set in its origin
677endpoint id and this can be checked by the SPMC when the SP invokes the ABI.
678
679The SPMC shall reject the direct message if the claimed world in origin endpoint
680id is not consistent:
681
682- It is either forwarded by SPMD and thus origin endpoint id must be a "normal
683 world id",
684- or initiated by an SP and thus origin endpoint id must be a "secure world id".
685
686Direct messaging
687----------------
688
689This is a mandatory interface for Secure Partitions consisting in direct
690message request and responses.
691
692The ``ffa_handler`` Hafnium function may:
693
694- trigger a world change e.g. when an SP invokes the direct message
695 response ABI to a VM.
696- handle multiple requests from the NWd without resuming an SP.
697
698SP-to-SP
699~~~~~~~~
700
701- An SP can send a direct message request to another SP
702- An SP can receive a direct message response from another SP.
703
704VM-to-SP
705~~~~~~~~
706
707- A VM can send a direct message request to an SP
708- An SP can send a direct message response to a VM
709
710SPMC-SPMD messaging
711~~~~~~~~~~~~~~~~~~~
712
713Specific implementation-defined endpoint IDs are allocated to the SPMC and SPMD.
714Referring those IDs in source/destination fields of a direct message
715request/response permits SPMD to SPMC messaging back and forth.
716
717Per `[1]`_ Table 114 Config No. 1 (physical FF-A instance):
718
719- SPMC=>SPMD direct message request uses SMC conduit
720- SPMD=>SPMC direct message request uses ERET conduit
721
722Per `[1]`_ Table 118 Config No. 1 (physical FF-A instance):
723
724- SPMC=>SPMD direct message response uses SMC conduit
725- SPMD=>SPMC direct message response uses ERET conduit
726
727Memory management
728-----------------
729
730This section only deals with the PE MMU configuration.
731
732Hafnium in the normal world deals with NS buffers only and provisions
733a single root page table directory to VMs. In context of S-EL2 enabled
734firmware, two IPA spaces are output from Stage-1 translation (secure
735and non-secure). The Stage-2 translation handles:
736
737- A single secure IPA space when an SP Stage-1 MMU is disabled.
738- Two IPA spaces (secure and non-secure) when Stage-1 MMU is enabled.
739
740``VTCR_EL2`` and ``VSTCR_EL2`` provide additional bits for controlling the
741NS/S IPA translations (``VSTCR_EL2.SW``, ``VSTCR_EL2.SA``, ``VTCR_EL2.NSW``,
742``VTCR_EL2.NSA``). There may be two approaches:
743
744- secure and non-secure mappings are rooted as two separate root page
745 tables
746- secure and non-secure mappings use the same root page table. Access
747 from S-EL1 to an NS region translates to a secure physical address
748 space access.
749
750Interrupt management
751--------------------
752
753Road to a para-virtualized interface
754~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
755
756Current Hafnium implementation uses an ad-hoc mechanism for a VM to get
757a pending interrupt number through an hypercall. The PVM injects
758interrupts to VMs by delegation from the Hypervisor. The PVM probes a
759pending interrupt directly from the GIC distributor.
760
761The short-term plan is to have Hafnium/SPMC in the secure world owner
762of the GIC configuration.
763
764The SPMC fully owns the GIC configuration at S-EL2. The SPMC manages
765interrupt resources and allocates interrupt ID based on SP manifests.
766The SPMC acknowledges physical interrupts and injects virtual interrupts
767by setting the vIRQ bit when resuming an SP. A Secure Partition gathers
768the interrupt number through an hypercall.
769
770Notice the SPMC/SPMD has to handle Group0 secure interrupts in addition
771to Group1 S/NS interrupts.
772
773Power management
774----------------
775
776Assumption on the Nwd:
777
778- NWd is the best candidate to own the platform Power Management
779 policy. It is master to invoking PSCI service calls from physical
780 CPUs.
781- EL3 monitor is in charge of the PM control part (its PSCI layer
782 actually writing to platform registers).
783- It is fine for the Hypervisor to trap PSCI calls and relay to EL3, or
784 OS kernel driver to emit PSCI service calls.
785
786PSCI notification are relayed through the SPMD/SPD PM hooks to the SPMC.
787This can either be through re-use of PSCI FIDs or an FF-A direct message
788from SPMD to SPMC.
789
790The SPMD performs an exception return to the SPMC which is resumed to
791its ``eret_handler`` routine. It is then either consuming a PSCI FID or
792an FF-A FID. Depending on the servicing, the SPMC may return directly to
793the SPMD (and then NWd) without resuming an SP at this stage. An example
794of this is invocation of ``FFA_PARTITION_INFO_GET`` from NWd relayed by
795the SPMD to the SPMC. The SPMC returns the needed partition information
796to the SPMD (then NWd) without actually resuming a partition in secure world.
797
798*(under discussion)*
799About using PSCI FIDs from SPMD to SPMC to notify of PM events, it is still
800questioned what to use as the return code from the SPMC.
801If the function ID used by the SPMC is not an FF-A ID when doing SMC, then the
802EL3 std svc handler won't route the response to the SPMD. That's where comes the
803idea to embed the notification into an FF-A message. The SPMC can discriminate
804this message as being a PSCI event, process it, and reply with an FF-A return
805message that the SPMD receives as an acknowledgement.
806
807SP notification
808---------------
809
810Power management notifications are conveyed from PSCI library to the
811SPMD / SPD hooks. A range of events can be relayed to SPMC.
812
813SPs may need to be notified about specific PM events.
814
815- SPs might register PM events to the SPMC
816- On SPMD to SPMC notification, a limited range of SPs may be notified
817 through a direct message.
818- This assumes the mentioned SPs supports managed exit.
819
820The SPMC is the first to be notified about PM events from the SPMD. It is up
821to the SPMC to arbitrate to which SP it needs to send PM events.
822An SP explicitly registers to receive notifications to specific PM events.
823The register operation can either be an implementation-defined service call
824to the SPMC when the primary SP EC boots, or be supplied through the SP
825manifest.
826
827References
828==========
829
830.. _[1]:
831
832[1] `Platform Security Architecture Firmware Framework for ArmĀ® v8-A 1.0 Platform Design Document <https://developer.arm.com/docs/den0077/latest>`__
833
834.. _[2]:
835
Madhukar Pappireddy86350ae2020-07-29 09:37:25 -0500836[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>`
Olivier Deprezecb2fe52020-04-02 15:38:02 +0200837
838.. _[3]:
839
840[3] `Trusted Boot Board Requirements
841Client <https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a>`__
842
843.. _[4]:
844
845[4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/lib/el3_runtime/aarch64/context.S#n45
846
847.. _[5]:
848
849[5] https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/spm/cactus/cactus.dts
850
851.. _[6]:
852
853[6] https://trustedfirmware-a.readthedocs.io/en/latest/components/psa-ffa-manifest-binding.html
854
855.. _[7]:
856
857[7] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_spmc_manifest.dts
858
859.. _[8]:
860
861[8] https://developer.trustedfirmware.org/w/tf_a/poc-multiple-signing-domains/
862
863--------------
864
865*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*