1Secure 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 129 registers is visible at `[4]`_. 130- **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 836[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>` 837 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.* 866
