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. 286This file also specifies the owner of the SP, which is an optional field and 287identifies the signing domain in case of dualroot CoT. 288The possible owner of an SP could either be Silicon Provider or Platform, and 289the corresponding "owner" field value could either be "SiP" or "Plat". 290In absence of "owner" field, it defaults to "SiP". 291 292.. code:: shell 293 294 { 295 "tee1" : { 296 "image": "tee1.bin", 297 "pm": "tee1.dts", 298 "owner": "SiP" 299 }, 300 301 "tee2" : { 302 "image": "tee2.bin", 303 "pm": "tee2.dts", 304 "owner": "Plat" 305 } 306 } 307 308SPMC manifest 309~~~~~~~~~~~~~ 310 311This manifest contains an SPMC attributes node consumed by SPMD at boot time. It 312is implementing the description from `[1]`_ section 3.2 (SP manifest at physical 313FF-A instance). The SP manifest at physical FF-A instance is used by the SPMD to 314setup a SP that co-resides with the SPMC and executes at S-EL1 or Secure 315Supervisor mode. 316 317In this implementation its usage is extended to the secure physical FF-A 318instance where SPMC executes at S-EL2. 319 320.. code:: shell 321 322 attribute { 323 spmc_id = <0x8000>; 324 maj_ver = <0x1>; 325 min_ver = <0x0>; 326 exec_state = <0x0>; 327 load_address = <0x0 0x6000000>; 328 entrypoint = <0x0 0x6000000>; 329 binary_size = <0x60000>; 330 }; 331 332- *spmc_id* defines the endpoint ID value that SPMC can query through 333 ``FFA_ID_GET``. 334- *maj_ver/min_ver*. SPMD checks provided version versus its internal 335 version and aborts if not matching. 336- *exec_state* defines SPMC execution state (can be AArch64 for 337 Hafnium, or AArch64/AArch32 for OP-TEE at S-EL1). 338- *load_address* and *binary_size* are mostly used to verify secondary 339 entry points fit into the loaded binary image. 340- *entrypoint* defines the cold boot primary core entry point used by 341 SPMD (currently matches ``BL32_BASE``) 342 343Other nodes in the manifest are consumed by Hafnium in the secure world. 344A sample can be found at [7]: 345 346- The *chosen* node is currently unused in SWd. It is meant for NWd to 347 specify the init ramdisk image. 348- The *hypervisor* node describes SPs. *is_ffa_partition* boolean 349 attribute indicates an SP. Load-addr field specifies the load address 350 at which TF-A loaded the SP package. 351- *cpus* node provide the platform topology and allows MPIDR to VMPIDR 352 mapping. Notice with current implementation primary cpu is declared 353 first, then secondary cpus must be declared in reverse order. 354 355SPMC boot 356~~~~~~~~~ 357 358The SPMC is loaded by BL2 as the BL32 image. 359 360The SPMC manifest is loaded by BL2 as the ``TOS_FW_CONFIG`` image. 361 362BL2 passes the SPMC manifest address to BL31 through a register. 363 364BL31(SPMD) runs from primary core, initializes the core contexts and 365launches BL32 passing the SPMC manifest address through a register. 366 367Loading of SPs 368~~~~~~~~~~~~~~ 369 370.. uml:: ../resources/diagrams/plantuml/bl2-loading-sp.puml 371 372 373Notice this boot flow is an implementation sample on Arm's FVP platform. Platforms 374not using FW_CONFIG would adjust to a different implementation. 375 376Secure boot 377~~~~~~~~~~~ 378 379The SP content certificate is inserted as a separate FIP item so that BL2 loads SPMC, 380SPMC manifest and Secure Partitions and verifies them for authenticity and integrity. 381Refer to TBBR specification `[3]`_. 382 383The multiple-signing domain feature (in current state dual signing domain) allows 384the use of two root keys namely S-ROTPK and NS-ROTPK (see `[8]`_): 385 386- SPMC (BL32) and SPMC manifest are signed by the SiP using the S-ROTPK. 387- BL33 may be signed by the OEM using NS-ROTPK. 388- An SP may be signed either by SiP (using S-ROTPK) or by OEM (using NS-ROTPK). 389 390Longer term multiple signing domain will allow additional signing keys, e.g. 391if SPs originate from different parties. 392 393See `TF-A build options`_ for a sample build command line. 394 395Hafnium in the secure world 396=========================== 397 398**NOTE: this section is work in progress. Descriptions and implementation choices 399are subject to evolve.** 400 401General considerations 402---------------------- 403 404Build platform for the secure world 405~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 406 407The implementation might add specific code parts only relevant to the 408secure world. Such code parts might be isolated into different files 409and/or conditional code enclosed by a ``SECURE_WORLD`` macro. 410 411Secure Partitions CPU scheduling 412~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 413 414In the normal world, VMs are scheduled by the FFA_RUN ABI invoked from the 415primary scheduler (in the primary VM), or by a direct message request or 416response. 417 418With the FF-A EAC specification, Secure Partitions are scheduled by direct 419message invocations from a NWd VM or another SP. 420 421Platform topology 422~~~~~~~~~~~~~~~~~ 423 424As stated in `[1]`_ section 4.4.1 the SPMC implementation assumes the 425following SP types: 426 427- Pinned MP SPs: an Execution Context id matches a physical PE id. MP 428 SPs must implement the same number of ECs as the number of PEs in the 429 platform. Hence the *execution-ctx-count* as defined by 430 `[1]`_ (or NWd-Hafnium *vcpu_count*) can only take the 431 value of one or the number of physical PEs. 432- Migratable UP SPs: a single execution context can run and be migrated 433 on any physical PE. It declares a single EC in its SP manifest. An UP 434 SP can receive a direct message request on any physical core. 435 436Usage of PSCI services in the secure world 437~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 438 439- The normal world Hypervisor (optional) or OS kernel issues PSCI service 440 invocations e.g. to request PSCI version, wake-up a secondary core, or request 441 core suspend. This happens at the non-secure physical FF-A instance. In the 442 example case of Hafnium in the normal world, it boots on the primary core and 443 one of the first initialization step is to request the PSCI version. It then 444 launches the primary VM. The primary VM upon initializing performs PSCI service 445 calls (at non-secure virtual FF-A instance) which are trapped by the 446 Hypervisor. Invocation from OS Kernel ends straight at EL3. The PVM issues 447 ``PSCI_CPU_ON`` service calls to wake-up secondary cores by passing an 448 ``MPIDR``, entry point address and a CPU context address. The EL3 PSCI layer 449 then performs an exception return to the secondary core entry point on the 450 targeted core. Other PSCI calls can happen at run-time from the PVM e.g. to 451 request core suspend. 452- In the existing TF-A PSCI standard library, PSCI service calls are filtered at 453 EL3 to only originate from the NWd. Thus concerning the SPMC (at secure 454 physical FF-A instance) the PSCI service invocations cannot happen as in the 455 normal world. For example, a ``PSCI_CPU_ON`` service invocation from the SPMC 456 does not reach the PSCI layer. 457 458Parsing SP partition manifests 459------------------------------ 460 461Hafnium must be able to consume SP manifests as defined in 462`[1]`_ section 3.1, at least for the mandatory fields. 463 464The SP manifest may contain memory and device regions nodes. 465 466- Memory regions shall be mapped in the SP Stage-2 translation regime at 467 load time. A memory region node can specify RX/TX buffer regions in which 468 case it is not necessary for an SP to explicitly call the ``FFA_RXTX_MAP`` 469 service. 470- Device regions shall be mapped in SP Stage-2 translation regime as 471 peripherals and possibly allocate additional resources (e.g. interrupts) 472 473Base addresses for memory and device region nodes are IPAs provided SPMC 474identity maps IPAs to PAs within SP Stage-2 translation regime. 475 476Note: currently both VTTBR_EL2 and VSTTBR_EL2 resolve to the same set of page 477tables. It is still open whether two sets of page tables shall be provided per 478SP. The memory region node as defined in the spec (section 3.1 Table 10) 479provides a memory security attribute hinting to map either to the secure or 480non-secure stage-2 table. 481 482Passing boot data to the SP 483--------------------------- 484 485`[1]`_ Section 3.4.2 “Protocol for passing data” defines a 486method to passing boot data to SPs (not currently implemented). 487 488Provided that the whole Secure Partition package image (see `Secure 489Partition packages`_) is mapped to the SP's secure Stage-2 translation 490regime, an SP can access its own manifest DTB blob and extract its partition 491manifest properties. 492 493SP Boot order 494------------- 495 496SP manifests provide an optional boot order attribute meant to resolve 497dependencies such as an SP providing a service required to properly boot 498another SP. 499 500Boot phases 501----------- 502 503Primary core boot-up 504~~~~~~~~~~~~~~~~~~~~ 505 506The SPMC performs its platform initializations then loads and creates 507secure partitions based on SP packages and manifests. Then each secure 508partition is launched in sequence (see `SP Boot order`_) on their primary 509Execution Context. 510 511Notice the primary physical core may not be core 0. Hence if the primary 512core linear id is N, the 1:1 mapping requires MP SPs are launched using 513EC[N] on PE[N] (see `Platform topology`_). 514 515The SP's primary Execution Context (or the EC used when the partition is booted) 516exits through ``FFA_MSG_WAIT`` to indicate successful initialization. 517 518Secondary physical core boot-up 519~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 520 521Upon boot-up, the SPMC running on the primary core performs 522implementation-defined SPMD service calls at secure physical FF-A instance 523to register the secondary physical cores entry points and context information: 524 525- This is done through a direct message request invocation to the SPMD 526 (``SET_ENTRY_POINT``). This service call does not wake-up the targeted 527 core immediately. The secondary core is woken up later by a NWd 528 ``PSCI_CPU_ON`` service invocation. A notification is passed from EL3 529 PSCI layer to the SPMD, and then to SPMC through an implementation-defined 530 interface. 531- The SPMC/SPMD interface can consist of FF-A direct message requests/responses 532 transporting PM events. 533 534If there is no Hypervisor in the normal world, the OS Kernel issues 535``PSCI_CPU_ON`` calls that are directly trapped to EL3. 536 537When a secondary physical core wakes-up the SPMD notifies the SPMC which updates 538its internal states reflecting current physical core is being turned on. 539It might then return straight to the SPMD and then to the NWd. 540 541*(under discussion)* There may be possibility that an SP registers "PM events" 542(during primary EC boot stage) through an ad-hoc interface. Such events would 543be relayed by SPMC to one or more registered SPs on need basis 544(see `Power management`_). 545 546Secondary virtual core boot-up 547~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 548 549In the example case where Hafnium exists in the normal world, secondary VMs 550issue a ``PSCI_CPU_ON`` service call which is trapped to the Hypervisor. The 551latter then enables the vCPU context for the targeted core, and switches to 552the PVM down to the kernel driver with an ``HF_WAKE_UP`` message. The NWd 553driver in PVM can then schedule the newly woken up vCPU context. 554 555In the secure world the primary EC of a given SP passes the secondary EC entry 556point and context. The SMC service call is trapped into the SPMC. This can be 557either *(under discussion)*: 558 559- a specific interface registering the secondary EC entry point, 560 similarly to above ``SET_ENTRY_POINT`` service. 561- Re-purposing the ``PSCI_CPU_ON`` function id. It is 562 assumed that even if the input arguments are the same as the ones defined in 563 the PSCI standard, the usage deviates by the fact the secondary EC is not 564 woken up immediately. At least for the PSA-FF-A EAC where only 565 direct messaging is allowed, it is only after the first direct 566 message invocation that the secondary EC is entered. This option 567 might be preferred when the same code base is re-used for a VM or 568 an SP. The ABI to wake-up a secondary EC can remain similar. 569 570SPs are always scheduled from the NWd, this paradigm did not change from legacy 571TEEs. There must always be some logic (or driver) in the NWd to relinquish CPU 572cycles to the SWd. If primary core is 0, an SP EC[x>0] entry point is supplied 573by the SP EC[0] when the system boots in SWd. But this EC[x] is not immediately 574entered at boot. Later in the boot process when NWd is up, a direct message 575request issued from physical core 1 ends up in SP EC[1], and only at this stage 576this context is effectively scheduled. 577 578It should be possible for an SP to call into another SP through direct message 579provided the latter SP has been booted already. The "boot-order" field in 580partition manifests (`SP Boot order`_) fulfills the dependency towards availability 581of a service within an SP offered to another SP. 582 583Mandatory interfaces 584-------------------- 585 586The following interfaces must be exposed to any VM or SP: 587 588- ``FFA_STATUS`` 589- ``FFA_ERROR`` 590- ``FFA_INTERRUPT`` 591- ``FFA_VERSION`` 592- ``FFA_FEATURES`` 593- ``FFA_RX_RELEASE`` 594- ``FFA_RXTX_MAP`` 595- ``FFA_RXTX_UNMAP`` 596- ``FFA_PARTITION_INFO_GET`` 597- ``FFA_ID_GET`` 598 599FFA_VERSION 600~~~~~~~~~~~ 601 602Per `[1]`_ section 8.1 ``FFA_VERSION`` requires a 603*requested_version* parameter from the caller. 604 605In the current implementation when ``FFA_VERSION`` is invoked from: 606 607- Hypervisor in NS-EL2: the SPMD returns the SPMC version specified 608 in the SPMC manifest. 609- OS kernel in NS-EL1 when NS-EL2 is not present: the SPMD returns the 610 SPMC version specified in the SPMC manifest. 611- VM in NWd: the Hypervisor returns its implemented version. 612- SP in SWd: the SPMC returns its implemented version. 613- SPMC at S-EL1/S-EL2: the SPMD returns its implemented version. 614 615FFA_FEATURES 616~~~~~~~~~~~~ 617 618FF-A features may be discovered by Secure Partitions while booting 619through the SPMC. However, SPMC cannot get features from Hypervisor 620early at boot time as NS world is not setup yet. 621 622The Hypervisor may decide to gather FF-A features from SPMC through SPMD 623once at boot time and store the result. Later when a VM requests FF-A 624features, the Hypervisor can adjust its own set of features with what 625SPMC advertised, if necessary. Another approach is to always forward FF-A 626features to the SPMC when a VM requests it to the Hypervisor. Although 627the result is not supposed to change over time so there may not be added 628value doing the systematic forwarding. 629 630FFA_RXTX_MAP/FFA_RXTX_UNMAP 631~~~~~~~~~~~~~~~~~~~~~~~~~~~ 632 633VM mailboxes are re-purposed to serve as SP RX/TX buffers. The RX/TX 634map API maps the send and receive buffer IPAs to the SP Stage-2 translation regime. 635 636Hafnium in the normal world defines VMs and their attributes as logical structures, 637including a mailbox used for FF-A indirect messaging, memory sharing, or the 638`FFA_PARTITION_INFO_GET`_ ABI. 639This same mailbox structure is re-used in the SPMC. `[1]`_ states only direct 640messaging is allowed to SPs. Thus mailbox usage is restricted to implementing 641`FFA_PARTITION_INFO_GET`_ and memory sharing ABIs. 642 643FFA_PARTITION_INFO_GET 644~~~~~~~~~~~~~~~~~~~~~~ 645 646Partition info get service call can originate: 647 648- from SP to SPM 649- from VM to Hypervisor 650- from Hypervisor to SPM 651 652For the latter case, the service call must be forwarded through the SPMD. 653 654FFA_ID_GET 655~~~~~~~~~~ 656 657The SPMD returns: 658 659- a default zero value on invocation from the Hypervisor. 660- The ``spmc_id`` value specified in the SPMC manifest on invocation from 661 the SPMC (see `SPMC manifest`_) 662 663The FF-A id space is split into a non-secure space and secure space: 664 665- FF-A id with bit 15 clear refer to normal world VMs. 666- FF-A id with bit 15 set refer to secure world SPs 667 668Such convention helps the SPMC discriminating the origin and destination worlds 669in an FF-A service invocation. In particular the SPMC shall filter unauthorized 670transactions in its world switch routine. It must not be permitted for a VM to 671use a secure FF-A id as origin world through spoofing: 672 673- A VM-to-SP messaging passing shall have an origin world being non-secure 674 (FF-A id bit 15 clear) and destination world being secure (FF-A id bit 15 675 set). 676- Similarly, an SP-to-SP message shall have FF-A id bit 15 set for both origin 677 and destination ids. 678 679An incoming direct message request arriving at SPMD from NWd is forwarded to 680SPMC without a specific check. The SPMC is resumed through eret and "knows" the 681message is coming from normal world in this specific code path. Thus the origin 682endpoint id must be checked by SPMC for being a normal world id. 683 684An SP sending a direct message request must have bit 15 set in its origin 685endpoint id and this can be checked by the SPMC when the SP invokes the ABI. 686 687The SPMC shall reject the direct message if the claimed world in origin endpoint 688id is not consistent: 689 690- It is either forwarded by SPMD and thus origin endpoint id must be a "normal 691 world id", 692- or initiated by an SP and thus origin endpoint id must be a "secure world id". 693 694Direct messaging 695---------------- 696 697This is a mandatory interface for Secure Partitions consisting in direct 698message request and responses. 699 700The ``ffa_handler`` Hafnium function may: 701 702- trigger a world change e.g. when an SP invokes the direct message 703 response ABI to a VM. 704- handle multiple requests from the NWd without resuming an SP. 705 706SP-to-SP 707~~~~~~~~ 708 709- An SP can send a direct message request to another SP 710- An SP can receive a direct message response from another SP. 711 712VM-to-SP 713~~~~~~~~ 714 715- A VM can send a direct message request to an SP 716- An SP can send a direct message response to a VM 717 718SPMC-SPMD messaging 719~~~~~~~~~~~~~~~~~~~ 720 721Specific implementation-defined endpoint IDs are allocated to the SPMC and SPMD. 722Referring those IDs in source/destination fields of a direct message 723request/response permits SPMD to SPMC messaging back and forth. 724 725Per `[1]`_ Table 114 Config No. 1 (physical FF-A instance): 726 727- SPMC=>SPMD direct message request uses SMC conduit 728- SPMD=>SPMC direct message request uses ERET conduit 729 730Per `[1]`_ Table 118 Config No. 1 (physical FF-A instance): 731 732- SPMC=>SPMD direct message response uses SMC conduit 733- SPMD=>SPMC direct message response uses ERET conduit 734 735Memory management 736----------------- 737 738This section only deals with the PE MMU configuration. 739 740Hafnium in the normal world deals with NS buffers only and provisions 741a single root page table directory to VMs. In context of S-EL2 enabled 742firmware, two IPA spaces are output from Stage-1 translation (secure 743and non-secure). The Stage-2 translation handles: 744 745- A single secure IPA space when an SP Stage-1 MMU is disabled. 746- Two IPA spaces (secure and non-secure) when Stage-1 MMU is enabled. 747 748``VTCR_EL2`` and ``VSTCR_EL2`` provide additional bits for controlling the 749NS/S IPA translations (``VSTCR_EL2.SW``, ``VSTCR_EL2.SA``, ``VTCR_EL2.NSW``, 750``VTCR_EL2.NSA``). There may be two approaches: 751 752- secure and non-secure mappings are rooted as two separate root page 753 tables 754- secure and non-secure mappings use the same root page table. Access 755 from S-EL1 to an NS region translates to a secure physical address 756 space access. 757 758Interrupt management 759-------------------- 760 761Road to a para-virtualized interface 762~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 763 764Current Hafnium implementation uses an ad-hoc mechanism for a VM to get 765a pending interrupt number through an hypercall. The PVM injects 766interrupts to VMs by delegation from the Hypervisor. The PVM probes a 767pending interrupt directly from the GIC distributor. 768 769The short-term plan is to have Hafnium/SPMC in the secure world owner 770of the GIC configuration. 771 772The SPMC fully owns the GIC configuration at S-EL2. The SPMC manages 773interrupt resources and allocates interrupt ID based on SP manifests. 774The SPMC acknowledges physical interrupts and injects virtual interrupts 775by setting the vIRQ bit when resuming an SP. A Secure Partition gathers 776the interrupt number through an hypercall. 777 778Notice the SPMC/SPMD has to handle Group0 secure interrupts in addition 779to Group1 S/NS interrupts. 780 781Power management 782---------------- 783 784Assumption on the Nwd: 785 786- NWd is the best candidate to own the platform Power Management 787 policy. It is master to invoking PSCI service calls from physical 788 CPUs. 789- EL3 monitor is in charge of the PM control part (its PSCI layer 790 actually writing to platform registers). 791- It is fine for the Hypervisor to trap PSCI calls and relay to EL3, or 792 OS kernel driver to emit PSCI service calls. 793 794PSCI notification are relayed through the SPMD/SPD PM hooks to the SPMC. 795This can either be through re-use of PSCI FIDs or an FF-A direct message 796from SPMD to SPMC. 797 798The SPMD performs an exception return to the SPMC which is resumed to 799its ``eret_handler`` routine. It is then either consuming a PSCI FID or 800an FF-A FID. Depending on the servicing, the SPMC may return directly to 801the SPMD (and then NWd) without resuming an SP at this stage. An example 802of this is invocation of ``FFA_PARTITION_INFO_GET`` from NWd relayed by 803the SPMD to the SPMC. The SPMC returns the needed partition information 804to the SPMD (then NWd) without actually resuming a partition in secure world. 805 806*(under discussion)* 807About using PSCI FIDs from SPMD to SPMC to notify of PM events, it is still 808questioned what to use as the return code from the SPMC. 809If the function ID used by the SPMC is not an FF-A ID when doing SMC, then the 810EL3 std svc handler won't route the response to the SPMD. That's where comes the 811idea to embed the notification into an FF-A message. The SPMC can discriminate 812this message as being a PSCI event, process it, and reply with an FF-A return 813message that the SPMD receives as an acknowledgement. 814 815SP notification 816--------------- 817 818Power management notifications are conveyed from PSCI library to the 819SPMD / SPD hooks. A range of events can be relayed to SPMC. 820 821SPs may need to be notified about specific PM events. 822 823- SPs might register PM events to the SPMC 824- On SPMD to SPMC notification, a limited range of SPs may be notified 825 through a direct message. 826- This assumes the mentioned SPs supports managed exit. 827 828The SPMC is the first to be notified about PM events from the SPMD. It is up 829to the SPMC to arbitrate to which SP it needs to send PM events. 830An SP explicitly registers to receive notifications to specific PM events. 831The register operation can either be an implementation-defined service call 832to the SPMC when the primary SP EC boots, or be supplied through the SP 833manifest. 834 835References 836========== 837 838.. _[1]: 839 840[1] `Platform Security Architecture Firmware Framework for Arm® v8-A 1.0 Platform Design Document <https://developer.arm.com/docs/den0077/latest>`__ 841 842.. _[2]: 843 844[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>` 845 846.. _[3]: 847 848[3] `Trusted Boot Board Requirements 849Client <https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a>`__ 850 851.. _[4]: 852 853[4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/lib/el3_runtime/aarch64/context.S#n45 854 855.. _[5]: 856 857[5] https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/spm/cactus/cactus.dts 858 859.. _[6]: 860 861[6] https://trustedfirmware-a.readthedocs.io/en/latest/components/psa-ffa-manifest-binding.html 862 863.. _[7]: 864 865[7] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_spmc_manifest.dts 866 867.. _[8]: 868 869[8] https://developer.trustedfirmware.org/w/tf_a/poc-multiple-signing-domains/ 870 871-------------- 872 873*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* 874
