aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOlivier Deprez <olivier.deprez@arm.com>2021-05-14 15:49:25 +0200
committerTrustedFirmware Code Review <review@review.trustedfirmware.org>2021-05-14 15:49:25 +0200
commit304c96207462f74002f4160fc83cbb74f29bd422 (patch)
treec537a118a86830aedf2e14a724b9a1b44b6069cc
parent96404aa27efbf1c9051d515075a60c3cf4fa47be (diff)
parentb5dd2422a043b2f6166e530574d9bde45ee84b98 (diff)
downloadtrusted-firmware-a-304c96207462f74002f4160fc83cbb74f29bd422.tar.gz
Merge "docs: spm design document refresh" into integration
-rw-r--r--docs/components/secure-partition-manager.rst931
-rw-r--r--docs/resources/diagrams/ff-a-spm-sel2.pngbin83369 -> 53363 bytes
-rw-r--r--docs/resources/diagrams/ffa-ns-interrupt-handling-managed-exit.pngbin0 -> 86234 bytes
-rw-r--r--docs/resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.pngbin0 -> 70490 bytes
4 files changed, 452 insertions, 479 deletions
diff --git a/docs/components/secure-partition-manager.rst b/docs/components/secure-partition-manager.rst
index 8b02e7d9f6..a5e7e8ed5b 100644
--- a/docs/components/secure-partition-manager.rst
+++ b/docs/components/secure-partition-manager.rst
@@ -7,6 +7,8 @@ Acronyms
========
+--------+-----------------------------------+
+| CoT | Chain of Trust |
++--------+-----------------------------------+
| DMA | Direct Memory Access |
+--------+-----------------------------------+
| DTB | Device Tree Blob |
@@ -17,7 +19,7 @@ Acronyms
+--------+-----------------------------------+
| FIP | Firmware Image Package |
+--------+-----------------------------------+
-| FF-A | Firmware Framework for A-class |
+| FF-A | Firmware Framework for Armv8-A |
+--------+-----------------------------------+
| IPA | Intermediate Physical Address |
+--------+-----------------------------------+
@@ -31,12 +33,16 @@ Acronyms
+--------+-----------------------------------+
| PE | Processing Element |
+--------+-----------------------------------+
+| PM | Power Management |
++--------+-----------------------------------+
| PVM | Primary VM |
+--------+-----------------------------------+
| SMMU | System Memory Management Unit |
+--------+-----------------------------------+
| SP | Secure Partition |
+--------+-----------------------------------+
+| SPD | Secure Payload Dispatcher |
++--------+-----------------------------------+
| SPM | Secure Partition Manager |
+--------+-----------------------------------+
| SPMC | SPM Core |
@@ -59,111 +65,117 @@ Foreword
Two implementations of a Secure Partition Manager co-exist in the TF-A codebase:
-- SPM based on the FF-A specification `[1]`_.
-- SPM based on the MM interface to communicate with an S-EL0 partition `[2]`_.
+- SPM based on the FF-A specification `[1]`_.
+- SPM based on the MM interface to communicate with an S-EL0 partition `[2]`_.
Both implementations differ in their architectures and only one can be selected
at build time.
This document:
-- describes the FF-A implementation where the Secure Partition Manager
- resides at EL3 and S-EL2 (or EL3 and S-EL1).
-- is not an architecture specification and it might provide assumptions
- on sections mandated as implementation-defined in the specification.
-- covers the implications to TF-A used as a bootloader, and Hafnium
- used as a reference code base for an S-EL2 secure firmware on
- platforms implementing Armv8.4-SecEL2.
+- describes the FF-A implementation where the Secure Partition Manager
+ resides at EL3 and S-EL2 (or EL3 and S-EL1).
+- is not an architecture specification and it might provide assumptions
+ on sections mandated as implementation-defined in the specification.
+- covers the implications to TF-A used as a bootloader, and Hafnium
+ used as a reference code base for an S-EL2 secure firmware on
+ platforms implementing the FEAT_SEL2 (formerly Armv8.4 Secure EL2)
+ architecture extension.
Terminology
-----------
-- Hypervisor refers to the NS-EL2 component managing Virtual Machines (or
- partitions) in the Normal World.
-- SPMC refers to the S-EL2 component managing Virtual Machines (or Secure
- Partitions) in the Secure World when Armv8.4-SecEL2 extension is implemented.
-- Alternatively, SPMC can refer to an S-EL1 component, itself being a Secure
- Partition and implementing the FF-A ABI on pre-Armv8.4 platforms.
-- VM refers to a Normal World Virtual Machine managed by an Hypervisor.
-- SP refers to a Secure World "Virtual Machine" managed by the SPMC component.
+- The term Hypervisor refers to the NS-EL2 component managing Virtual Machines
+ (or partitions) in the normal world.
+- The term SPMC refers to the S-EL2 component managing secure partitions in
+ the secure world when the FEAT_SEL2 architecture extension is implemented.
+- Alternatively, SPMC can refer to an S-EL1 component, itself being a secure
+ partition and implementing the FF-A ABI on platforms not implementing the
+ FEAT_SEL2 architecture extension.
+- The term VM refers to a normal world Virtual Machine managed by an Hypervisor.
+- The term SP refers to a secure world "Virtual Machine" managed by an SPMC.
Support for legacy platforms
----------------------------
-In the implementation, the SPM is split into SPMD and SPMC components
-(although not strictly mandated by the specification). SPMD is located
-at EL3 and principally relays FF-A messages from NWd (Hypervisor or OS
-kernel) to SPMC located either at S-EL1 or S-EL2.
+In the implementation, the SPM is split into SPMD and SPMC components.
+The SPMD is located at EL3 and mainly relays FF-A messages from
+NWd (Hypervisor or OS kernel) to SPMC located either at S-EL1 or S-EL2.
-Hence TF-A must support both cases where SPMC is either located at:
+Hence TF-A supports both cases where the SPMC is located either at:
-- S-EL1 supporting pre-Armv8.4 platforms. SPMD conveys FF-A protocol
- from EL3 to S-EL1.
-- S-EL2 supporting platforms implementing Armv8.4-SecEL2 extension.
- SPMD conveys FF-A protocol from EL3 to S-EL2.
+- S-EL1 supporting platforms not implementing the FEAT_SEL2 architecture
+ extension. The SPMD relays the FF-A protocol from EL3 to S-EL1.
+- or S-EL2 supporting platforms implementing the FEAT_SEL2 architecture
+ extension. The SPMD relays the FF-A protocol from EL3 to S-EL2.
-The same SPMD component is used to support both configurations. The SPMC
-execution level is a build time choice.
+The same TF-A SPMD component is used to support both configurations.
+The SPMC exception level is a build time choice.
Sample reference stack
======================
-The following diagram illustrates a possible configuration with SPMD and SPMC,
-one or multiple Secure Partitions, with or without an optional Hypervisor:
+The following diagram illustrates a possible configuration when the
+FEAT_SEL2 architecture extension is implemented, showing the SPMD
+and SPMC, one or multiple secure partitions, with an optional
+Hypervisor:
.. image:: ../resources/diagrams/ff-a-spm-sel2.png
TF-A build options
==================
-The following TF-A build options are provisioned:
-
-- **SPD=spmd**: this option selects the SPMD component to relay FF-A
- protocol from NWd to SWd back and forth. It is not possible to
- enable another Secure Payload Dispatcher when this option is chosen.
-- **SPMD_SPM_AT_SEL2**: this option adjusts the SPMC execution
- level to being S-EL1 or S-EL2. It defaults to enabled (value 1) when
- SPD=spmd is chosen.
-- **CTX_INCLUDE_EL2_REGS**: this option permits saving (resp.
- restoring) the EL2 system register context before entering (resp.
- after leaving) the SPMC. It is mandatory when ``SPMD_SPM_AT_SEL2`` is
- enabled. The context save/restore routine and exhaustive list of
- registers is visible at `[4]`_.
-- **SP_LAYOUT_FILE**: this option provides a text description file
- providing paths to SP binary images and DTS format manifests
- (see `Specifying partition binary image and DT`_). It
- is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple
- secure partitions are to be loaded on behalf of SPMC.
-
-+------------------------------+----------------------+------------------+
-| | CTX_INCLUDE_EL2_REGS | SPMD_SPM_AT_SEL2 |
-+------------------------------+----------------------+------------------+
-| SPMC at S-EL1 (e.g. OP-TEE) | 0 | 0 |
-+------------------------------+----------------------+------------------+
-| SPMC at S-EL2 (e.g. Hafnium) | 1 | 1 (default when |
-| | | SPD=spmd) |
-+------------------------------+----------------------+------------------+
+This section explains the TF-A build options involved in building with
+support for an FF-A based SPM where the SPMD is located at EL3 and the
+SPMC located at S-EL1 or S-EL2:
+
+- **SPD=spmd**: this option selects the SPMD component to relay the FF-A
+ protocol from NWd to SWd back and forth. It is not possible to
+ enable another Secure Payload Dispatcher when this option is chosen.
+- **SPMD_SPM_AT_SEL2**: this option adjusts the SPMC exception
+ level to being S-EL1 or S-EL2. It defaults to enabled (value 1) when
+ SPD=spmd is chosen.
+- **CTX_INCLUDE_EL2_REGS**: this option permits saving (resp.
+ restoring) the EL2 system register context before entering (resp.
+ after leaving) the SPMC. It is mandatorily enabled when
+ ``SPMD_SPM_AT_SEL2`` is enabled. The context save/restore routine
+ and exhaustive list of registers is visible at `[4]`_.
+- **SP_LAYOUT_FILE**: this option specifies a text description file
+ providing paths to SP binary images and manifests in DTS format
+ (see `Describing secure partitions`_). It
+ is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple
+ secure partitions are to be loaded on behalf of the SPMC.
+
++---------------+----------------------+------------------+
+| | CTX_INCLUDE_EL2_REGS | SPMD_SPM_AT_SEL2 |
++---------------+----------------------+------------------+
+| SPMC at S-EL1 | 0 | 0 |
++---------------+----------------------+------------------+
+| SPMC at S-EL2 | 1 | 1 (default when |
+| | | SPD=spmd) |
++---------------+----------------------+------------------+
Other combinations of such build options either break the build or are not
supported.
-Note, the ``CTX_INCLUDE_EL2_REGS`` option provides the generic support for
-barely saving/restoring EL2 registers from an Arm arch perspective. As such
-it is decoupled from the ``SPD=spmd`` option.
-
-BL32 option is re-purposed to specify the SPMC image. It can specify either the
-Hafnium binary path (built for the secure world) or the path to a TEE binary
-implementing the FF-A protocol.
-
-BL33 option can specify either:
-
-- the TFTF binary or
-- the Hafnium binary path (built for the normal world) if VMs were loaded by
- TF-A beforehand or
-- a minimal loader performing the loading of VMs and Hafnium.
+Notes:
+
+- Only Arm's FVP platform is supported to use with the TF-A reference software
+ stack.
+- The reference software stack uses FEAT_PAuth (formerly Armv8.3-PAuth) and
+ FEAT_BTI (formerly Armv8.5-BTI) architecture extensions by default at EL3
+ and S-EL2.
+- The ``CTX_INCLUDE_EL2_REGS`` option provides the generic support for
+ barely saving/restoring EL2 registers from an Arm arch perspective. As such
+ it is decoupled from the ``SPD=spmd`` option.
+- BL32 option is re-purposed to specify the SPMC image. It can specify either
+ the Hafnium binary path (built for the secure world) or the path to a TEE
+ binary implementing FF-A interfaces.
+- BL33 option can specify the TFTF binary or a normal world loader
+ such as U-Boot or the UEFI framework.
Sample TF-A build command line when SPMC is located at S-EL1
-(typically pre-Armv8.4):
+(e.g. when the FEAT_EL2 architecture extension is not implemented):
.. code:: shell
@@ -172,67 +184,108 @@ Sample TF-A build command line when SPMC is located at S-EL1
SPD=spmd \
SPMD_SPM_AT_SEL2=0 \
BL32=<path-to-tee-binary> \
- BL33=<path-to-nwd-binary> \
+ BL33=<path-to-bl33-binary> \
PLAT=fvp \
all fip
-Sample TF-A build command line for an Armv8.4-SecEL2 enabled system
-where SPMC is located at S-EL2:
+Sample TF-A build command line for a FEAT_SEL2 enabled system where the SPMC is
+located at S-EL2:
.. code:: shell
make \
CROSS_COMPILE=aarch64-none-elf- \
+ PLAT=fvp \
SPD=spmd \
CTX_INCLUDE_EL2_REGS=1 \
- ARM_ARCH_MINOR=4 \
- BL32=<path-to-swd-hafnium-binary>
- BL33=<path-to-nwd-binary> \
+ ARM_ARCH_MINOR=5 \
+ BRANCH_PROTECTION=1 \
+ CTX_INCLUDE_PAUTH_REGS=1 \
+ BL32=<path-to-hafnium-binary> \
+ BL33=<path-to-bl33-binary> \
SP_LAYOUT_FILE=sp_layout.json \
- PLAT=fvp \
all fip
-Build options to enable secure boot:
+Same as above with enabling secure boot in addition:
.. code:: shell
make \
CROSS_COMPILE=aarch64-none-elf- \
+ PLAT=fvp \
SPD=spmd \
CTX_INCLUDE_EL2_REGS=1 \
- ARM_ARCH_MINOR=4 \
- BL32=<path-to-swd-hafnium-binary>
- BL33=<path-to-nwd-binary> \
- SP_LAYOUT_FILE=../tf-a-tests/build/fvp/debug/sp_layout.json \
+ ARM_ARCH_MINOR=5 \
+ BRANCH_PROTECTION=1 \
+ CTX_INCLUDE_PAUTH_REGS=1 \
+ BL32=<path-to-hafnium-binary> \
+ BL33=<path-to-bl33-binary> \
+ SP_LAYOUT_FILE=sp_layout.json \
MBEDTLS_DIR=<path-to-mbedtls-lib> \
TRUSTED_BOARD_BOOT=1 \
COT=dualroot \
ARM_ROTPK_LOCATION=devel_rsa \
ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
GENERATE_COT=1 \
- PLAT=fvp \
all fip
+FVP model invocation
+====================
+
+The FVP command line needs the following options to exercise the S-EL2 SPMC:
+
++---------------------------------------------------+------------------------------------+
+| - cluster0.has_arm_v8-5=1 | Implements FEAT_SEL2, FEAT_PAuth, |
+| - cluster1.has_arm_v8-5=1 | and FEAT_BTI. |
++---------------------------------------------------+------------------------------------+
+| - pci.pci_smmuv3.mmu.SMMU_AIDR=2 | Parameters required for the |
+| - pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B | SMMUv3.2 modeling. |
+| - pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 | |
+| - pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 | |
+| - pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0472 | |
+| - pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 | |
+| - pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 | |
+| - pci.pci_smmuv3.mmu.SMMU_S_IDR3=0 | |
++---------------------------------------------------+------------------------------------+
+| - cluster0.has_branch_target_exception=1 | Implements FEAT_BTI. |
+| - cluster1.has_branch_target_exception=1 | |
++---------------------------------------------------+------------------------------------+
+| - cluster0.restriction_on_speculative_execution=2 | Required by the EL2 context |
+| - cluster1.restriction_on_speculative_execution=2 | save/restore routine. |
++---------------------------------------------------+------------------------------------+
+
+Sample FVP command line invocation:
+
+.. code:: shell
+
+ <path-to-fvp-model>/FVP_Base_RevC-2xAEMv8A -C pctl.startup=0.0.0.0
+ -C cluster0.NUM_CORES=4 -C cluster1.NUM_CORES=4 -C bp.secure_memory=1 \
+ -C bp.secureflashloader.fname=trusted-firmware-a/build/fvp/debug/bl1.bin \
+ -C bp.flashloader0.fname=trusted-firmware-a/build/fvp/debug/fip.bin \
+ -C bp.pl011_uart0.out_file=fvp-uart0.log -C bp.pl011_uart1.out_file=fvp-uart1.log \
+ -C bp.pl011_uart2.out_file=fvp-uart2.log \
+ -C cluster0.has_arm_v8-5=1 -C cluster1.has_arm_v8-5=1 -C pci.pci_smmuv3.mmu.SMMU_AIDR=2 \
+ -C pci.pci_smmuv3.mmu.SMMU_IDR0=0x0046123B -C pci.pci_smmuv3.mmu.SMMU_IDR1=0x00600002 \
+ -C pci.pci_smmuv3.mmu.SMMU_IDR3=0x1714 -C pci.pci_smmuv3.mmu.SMMU_IDR5=0xFFFF0472 \
+ -C pci.pci_smmuv3.mmu.SMMU_S_IDR1=0xA0000002 -C pci.pci_smmuv3.mmu.SMMU_S_IDR2=0 \
+ -C pci.pci_smmuv3.mmu.SMMU_S_IDR3=0 \
+ -C cluster0.has_branch_target_exception=1 \
+ -C cluster1.has_branch_target_exception=1 \
+ -C cluster0.restriction_on_speculative_execution=2 \
+ -C cluster1.restriction_on_speculative_execution=2
+
Boot process
============
-Loading Hafnium and Secure Partitions in the secure world
+Loading Hafnium and secure partitions in the secure world
---------------------------------------------------------
-The Hafnium implementation in normal world requires VMs to be loaded in
-memory prior to booting. The mechanism upon which VMs are loaded and
-exposed to Hafnium are either:
+TF-A BL2 is the bootlader for the SPMC and SPs in the secure world.
-- by supplying a ramdisk image where VM images are concatenated (1)
-- or by providing VM load addresses within Hafnium manifest (2)
-
-TF-A is the bootlader for the Hafnium and SPs in the secure world. TF-A
-does not provide tooling or libraries manipulating ramdisks as required
-by (1). Thus BL2 loads SPs payloads independently.
SPs may be signed by different parties (SiP, OEM/ODM, TOS vendor, etc.).
-Thus they are supplied as distinct “self-contained” signed entities within
-the FIP flash image. The FIP image itself is not signed hence providing
-ability to upgrade SPs in the field.
+Thus they are supplied as distinct signed entities within the FIP flash
+image. The FIP image itself is not signed hence this provides the ability
+to upgrade SPs in the field.
Booting through TF-A
--------------------
@@ -241,26 +294,27 @@ SP manifests
~~~~~~~~~~~~
An SP manifest describes SP attributes as defined in `[1]`_
-section 3.1 (partition manifest at virtual FF-A instance) in DTS text format. It
-is represented as a single file associated with the SP. A sample is
+(partition manifest at virtual FF-A instance) in DTS format. It is
+represented as a single file associated with the SP. A sample is
provided by `[5]`_. A binding document is provided by `[6]`_.
Secure Partition packages
~~~~~~~~~~~~~~~~~~~~~~~~~
-Secure Partitions are bundled as independent package files consisting
+Secure partitions are bundled as independent package files consisting
of:
-- a header
-- a DTB
-- an image payload
+- a header
+- a DTB
+- an image payload
The header starts with a magic value and offset values to SP DTB and
image payload. Each SP package is loaded independently by BL2 loader
and verified for authenticity and integrity.
-The SP package identified by its UUID (matching FF-A uuid) is inserted
-as a single entry into the FIP at end of the TF-A build flow as shown:
+The SP package identified by its UUID (matching FF-A uuid property) is
+inserted as a single entry into the FIP at end of the TF-A build flow
+as shown:
.. code:: shell
@@ -278,18 +332,17 @@ as a single entry into the FIP at end of the TF-A build flow as shown:
.. uml:: ../resources/diagrams/plantuml/fip-secure-partitions.puml
-Specifying partition binary image and DT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Describing secure partitions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A description file (json format) is passed to the build flow specifying
-paths to the SP binary image and associated DTS partition manifest file.
-The latter is going through the dtc compiler to generate the dtb fed into
-the SP package.
-This file also specifies the owner of the SP, which is an optional field and
-identifies the signing domain in case of dualroot CoT.
-The possible owner of an SP could either be Silicon Provider or Platform, and
-the corresponding "owner" field value could either be "SiP" or "Plat".
-In absence of "owner" field, it defaults to "SiP".
+A json-formatted description file is passed to the build flow specifying paths
+to the SP binary image and associated DTS partition manifest file. The latter
+is processed by the dtc compiler to generate a DTB fed into the SP package.
+This file also specifies the SP owner (as an optional field) identifying the
+signing domain in case of dual root CoT.
+The SP owner can either be the silicon or the platform provider. The
+corresponding "owner" field value can either take the value of "SiP" or "Plat".
+In absence of "owner" field, it defaults to "SiP" owner.
.. code:: shell
@@ -310,14 +363,16 @@ In absence of "owner" field, it defaults to "SiP".
SPMC manifest
~~~~~~~~~~~~~
-This manifest contains an SPMC attributes node consumed by SPMD at boot time. It
-is implementing the description from `[1]`_ section 3.2 (SP manifest at physical
-FF-A instance). The SP manifest at physical FF-A instance is used by the SPMD to
-setup a SP that co-resides with the SPMC and executes at S-EL1 or Secure
-Supervisor mode.
+This manifest contains the SPMC *attribute* node consumed by the SPMD at boot
+time. It implements `[1]`_ (SP manifest at physical FF-A instance) and serves
+two different cases:
-In this implementation its usage is extended to the secure physical FF-A
-instance where SPMC executes at S-EL2.
+- The SPMC resides at S-EL1: the SPMC manifest is used by the SPMD to setup a
+ SP that co-resides with the SPMC and executes at S-EL1 or Secure Supervisor
+ mode.
+- The SPMC resides at S-EL2: the SPMC manifest is used by the SPMD to setup
+ the environment required by the SPMC to run at S-EL2. SPs run at S-EL1 or
+ S-EL0.
.. code:: shell
@@ -331,28 +386,28 @@ instance where SPMC executes at S-EL2.
binary_size = <0x60000>;
};
-- *spmc_id* defines the endpoint ID value that SPMC can query through
- ``FFA_ID_GET``.
-- *maj_ver/min_ver*. SPMD checks provided version versus its internal
- version and aborts if not matching.
-- *exec_state* defines SPMC execution state (can be AArch64 for
- Hafnium, or AArch64/AArch32 for OP-TEE at S-EL1).
-- *load_address* and *binary_size* are mostly used to verify secondary
- entry points fit into the loaded binary image.
-- *entrypoint* defines the cold boot primary core entry point used by
- SPMD (currently matches ``BL32_BASE``)
+- *spmc_id* defines the endpoint ID value that SPMC can query through
+ ``FFA_ID_GET``.
+- *maj_ver/min_ver*. SPMD checks provided version versus its internal
+ version and aborts if not matching.
+- *exec_state* defines the SPMC execution state (AArch64 or AArch32).
+ Notice Hafnium used as a SPMC only supports AArch64.
+- *load_address* and *binary_size* are mostly used to verify secondary
+ entry points fit into the loaded binary image.
+- *entrypoint* defines the cold boot primary core entry point used by
+ SPMD (currently matches ``BL32_BASE``) to enter the SPMC.
Other nodes in the manifest are consumed by Hafnium in the secure world.
A sample can be found at [7]:
-- The *chosen* node is currently unused in SWd. It is meant for NWd to
- specify the init ramdisk image.
-- The *hypervisor* node describes SPs. *is_ffa_partition* boolean
- attribute indicates an SP. Load-addr field specifies the load address
- at which TF-A loaded the SP package.
-- *cpus* node provide the platform topology and allows MPIDR to VMPIDR
- mapping. Notice with current implementation primary cpu is declared
- first, then secondary cpus must be declared in reverse order.
+- The *hypervisor* node describes SPs. *is_ffa_partition* boolean attribute
+ indicates a FF-A compliant SP. The *load_address* field specifies the load
+ address at which TF-A loaded the SP package.
+- *cpus* node provide the platform topology and allows MPIDR to VMPIDR mapping.
+ Note the primary core is declared first, then secondary core are declared
+ in reverse order.
+- The *memory* node provides platform information on the ranges of memory
+ available to the SPMC.
SPMC boot
~~~~~~~~~
@@ -363,134 +418,111 @@ The SPMC manifest is loaded by BL2 as the ``TOS_FW_CONFIG`` image.
BL2 passes the SPMC manifest address to BL31 through a register.
-BL31(SPMD) runs from primary core, initializes the core contexts and
-launches BL32 passing the SPMC manifest address through a register.
+At boot time, the SPMD in BL31 runs from the primary core, initializes the core
+contexts and launches the SPMC (BL32) passing the SPMC manifest address through
+a register.
Loading of SPs
~~~~~~~~~~~~~~
-.. uml:: ../resources/diagrams/plantuml/bl2-loading-sp.puml
+At boot time, BL2 loads SPs sequentially in addition to the SPMC as depicted
+below:
+.. uml:: ../resources/diagrams/plantuml/bl2-loading-sp.puml
-Notice this boot flow is an implementation sample on Arm's FVP platform. Platforms
-not using FW_CONFIG would adjust to a different implementation.
+Note this boot flow is an implementation sample on Arm's FVP platform.
+Platforms not using TF-A's *Firmware CONFiguration* framework would adjust to a
+different implementation.
Secure boot
~~~~~~~~~~~
The SP content certificate is inserted as a separate FIP item so that BL2 loads SPMC,
-SPMC manifest and Secure Partitions and verifies them for authenticity and integrity.
+SPMC manifest, secure partitions and verifies them for authenticity and integrity.
Refer to TBBR specification `[3]`_.
-The multiple-signing domain feature (in current state dual signing domain) allows
-the use of two root keys namely S-ROTPK and NS-ROTPK (see `[8]`_):
+The multiple-signing domain feature (in current state dual signing domain `[8]`_) allows
+the use of two root keys namely S-ROTPK and NS-ROTPK:
-- SPMC (BL32) and SPMC manifest are signed by the SiP using the S-ROTPK.
-- BL33 may be signed by the OEM using NS-ROTPK.
-- An SP may be signed either by SiP (using S-ROTPK) or by OEM (using NS-ROTPK).
+- SPMC (BL32) and SPMC manifest are signed by the SiP using the S-ROTPK.
+- BL33 may be signed by the OEM using NS-ROTPK.
+- An SP may be signed either by SiP (using S-ROTPK) or by OEM (using NS-ROTPK).
-Longer term multiple signing domain will allow additional signing keys, e.g.
-if SPs originate from different parties.
-
-See `TF-A build options`_ for a sample build command line.
+Also refer to `Describing secure partitions`_ and `TF-A build options`_ sections.
Hafnium in the secure world
===========================
-**NOTE: this section is work in progress. Descriptions and implementation choices
-are subject to evolve.**
-
General considerations
----------------------
Build platform for the secure world
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The implementation might add specific code parts only relevant to the
-secure world. Such code parts might be isolated into different files
-and/or conditional code enclosed by a ``SECURE_WORLD`` macro.
+In the Hafnium reference implementation specific code parts are only relevant to
+the secure world. Such portions are isolated in architecture specific files
+and/or enclosed by a ``SECURE_WORLD`` macro.
-Secure Partitions CPU scheduling
+Secure partitions CPU scheduling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In the normal world, VMs are scheduled by the FFA_RUN ABI invoked from the
-primary scheduler (in the primary VM), or by a direct message request or
-response.
+The FF-A v1.0 specification `[1]`_ provides two ways to relinquinsh CPU time to
+secure partitions. For this a VM (Hypervisor or OS kernel), or SP invokes one of:
-With the FF-A EAC specification, Secure Partitions are scheduled by direct
-message invocations from a NWd VM or another SP.
+- the FFA_MSG_SEND_DIRECT_REQ interface.
+- the FFA_RUN interface.
Platform topology
~~~~~~~~~~~~~~~~~
-As stated in `[1]`_ section 4.4.1 the SPMC implementation assumes the
+The *execution-ctx-count* SP manifest field can take the value of one or the
+total number of PEs. The FF-A v1.0 specification `[1]`_ recommends the
following SP types:
-- Pinned MP SPs: an Execution Context id matches a physical PE id. MP
- SPs must implement the same number of ECs as the number of PEs in the
- platform. Hence the *execution-ctx-count* as defined by
- `[1]`_ (or NWd-Hafnium *vcpu_count*) can only take the
- value of one or the number of physical PEs.
-- Migratable UP SPs: a single execution context can run and be migrated
- on any physical PE. It declares a single EC in its SP manifest. An UP
- SP can receive a direct message request on any physical core.
-
-Usage of PSCI services in the secure world
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-- The normal world Hypervisor (optional) or OS kernel issues PSCI service
- invocations e.g. to request PSCI version, wake-up a secondary core, or request
- core suspend. This happens at the non-secure physical FF-A instance. In the
- example case of Hafnium in the normal world, it boots on the primary core and
- one of the first initialization step is to request the PSCI version. It then
- launches the primary VM. The primary VM upon initializing performs PSCI service
- calls (at non-secure virtual FF-A instance) which are trapped by the
- Hypervisor. Invocation from OS Kernel ends straight at EL3. The PVM issues
- ``PSCI_CPU_ON`` service calls to wake-up secondary cores by passing an
- ``MPIDR``, entry point address and a CPU context address. The EL3 PSCI layer
- then performs an exception return to the secondary core entry point on the
- targeted core. Other PSCI calls can happen at run-time from the PVM e.g. to
- request core suspend.
-- In the existing TF-A PSCI standard library, PSCI service calls are filtered at
- EL3 to only originate from the NWd. Thus concerning the SPMC (at secure
- physical FF-A instance) the PSCI service invocations cannot happen as in the
- normal world. For example, a ``PSCI_CPU_ON`` service invocation from the SPMC
- does not reach the PSCI layer.
+- Pinned MP SPs: an execution context matches a physical PE. MP SPs must
+ implement the same number of ECs as the number of PEs in the platform.
+- Migratable UP SPs: a single execution context can run and be migrated on any
+ physical PE. Such SP declares a single EC in its SP manifest. An UP SP can
+ receive a direct message request originating from any physical core targeting
+ the single execution context.
Parsing SP partition manifests
------------------------------
-Hafnium must be able to consume SP manifests as defined in
-`[1]`_ section 3.1, at least for the mandatory fields.
+Hafnium consumes SP manifests as defined in `[1]`_ and `SP manifests`_.
+Note the current implementation may not implement all optional fields.
-The SP manifest may contain memory and device regions nodes.
+The SP manifest may contain memory and device regions nodes. In case of
+an S-EL2 SPMC:
-- Memory regions shall be mapped in the SP Stage-2 translation regime at
- load time. A memory region node can specify RX/TX buffer regions in which
- case it is not necessary for an SP to explicitly call the ``FFA_RXTX_MAP``
- service.
-- Device regions shall be mapped in SP Stage-2 translation regime as
- peripherals and possibly allocate additional resources (e.g. interrupts)
+- Memory regions are mapped in the SP EL1&0 Stage-2 translation regime at
+ load time (or EL1&0 Stage-1 for an S-EL1 SPMC). A memory region node can
+ specify RX/TX buffer regions in which case it is not necessary for an SP
+ to explicitly invoke the ``FFA_RXTX_MAP`` interface.
+- Device regions are mapped in the SP EL1&0 Stage-2 translation regime (or
+ EL1&0 Stage-1 for an S-EL1 SPMC) as peripherals and possibly allocate
+ additional resources (e.g. interrupts).
-Base addresses for memory and device region nodes are IPAs provided SPMC
-identity maps IPAs to PAs within SP Stage-2 translation regime.
+For the S-EL2 SPMC, base addresses for memory and device region nodes are IPAs
+provided the SPMC identity maps IPAs to PAs within SP EL1&0 Stage-2 translation
+regime.
-Note: currently both VTTBR_EL2 and VSTTBR_EL2 resolve to the same set of page
-tables. It is still open whether two sets of page tables shall be provided per
-SP. The memory region node as defined in the spec (section 3.1 Table 10)
+Note: in the current implementation both VTTBR_EL2 and VSTTBR_EL2 point to the
+same set of page tables. It is still open whether two sets of page tables shall
+be provided per SP. The memory region node as defined in the specification
provides a memory security attribute hinting to map either to the secure or
-non-secure stage-2 table.
+non-secure EL1&0 Stage-2 table if it exists.
Passing boot data to the SP
---------------------------
-`[1]`_ Section 3.4.2 “Protocol for passing data” defines a
-method to passing boot data to SPs (not currently implemented).
+In `[1]`_ , the "Protocol for passing data" section defines a method for passing
+boot data to SPs (not currently implemented).
-Provided that the whole Secure Partition package image (see `Secure
-Partition packages`_) is mapped to the SP's secure Stage-2 translation
-regime, an SP can access its own manifest DTB blob and extract its partition
-manifest properties.
+Provided that the whole secure partition package image (see
+`Secure Partition packages`_) is mapped to the SP secure EL1&0 Stage-2
+translation regime, an SP can access its own manifest DTB blob and extract its
+partition manifest properties.
SP Boot order
-------------
@@ -499,343 +531,284 @@ SP manifests provide an optional boot order attribute meant to resolve
dependencies such as an SP providing a service required to properly boot
another SP.
+It is possible for an SP to call into another SP through a direct request
+provided the latter SP has already been booted.
+
Boot phases
-----------
Primary core boot-up
~~~~~~~~~~~~~~~~~~~~
-The SPMC performs its platform initializations then loads and creates
-secure partitions based on SP packages and manifests. Then each secure
-partition is launched in sequence (see `SP Boot order`_) on their primary
-Execution Context.
-
-Notice the primary physical core may not be core 0. Hence if the primary
-core linear id is N, the 1:1 mapping requires MP SPs are launched using
-EC[N] on PE[N] (see `Platform topology`_).
-
-The SP's primary Execution Context (or the EC used when the partition is booted)
-exits through ``FFA_MSG_WAIT`` to indicate successful initialization.
-
-Secondary physical core boot-up
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Upon boot-up, the SPMC running on the primary core performs
-implementation-defined SPMD service calls at secure physical FF-A instance
-to register the secondary physical cores entry points and context information:
-
-- This is done through a direct message request invocation to the SPMD
- (``SET_ENTRY_POINT``). This service call does not wake-up the targeted
- core immediately. The secondary core is woken up later by a NWd
- ``PSCI_CPU_ON`` service invocation. A notification is passed from EL3
- PSCI layer to the SPMD, and then to SPMC through an implementation-defined
- interface.
-- The SPMC/SPMD interface can consist of FF-A direct message requests/responses
- transporting PM events.
-
-If there is no Hypervisor in the normal world, the OS Kernel issues
-``PSCI_CPU_ON`` calls that are directly trapped to EL3.
-
-When a secondary physical core wakes-up the SPMD notifies the SPMC which updates
-its internal states reflecting current physical core is being turned on.
-It might then return straight to the SPMD and then to the NWd.
-
-*(under discussion)* There may be possibility that an SP registers "PM events"
-(during primary EC boot stage) through an ad-hoc interface. Such events would
-be relayed by SPMC to one or more registered SPs on need basis
-(see `Power management`_).
-
-Secondary virtual core boot-up
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In the example case where Hafnium exists in the normal world, secondary VMs
-issue a ``PSCI_CPU_ON`` service call which is trapped to the Hypervisor. The
-latter then enables the vCPU context for the targeted core, and switches to
-the PVM down to the kernel driver with an ``HF_WAKE_UP`` message. The NWd
-driver in PVM can then schedule the newly woken up vCPU context.
-
-In the secure world the primary EC of a given SP passes the secondary EC entry
-point and context. The SMC service call is trapped into the SPMC. This can be
-either *(under discussion)*:
-
-- a specific interface registering the secondary EC entry point,
- similarly to above ``SET_ENTRY_POINT`` service.
-- Re-purposing the ``PSCI_CPU_ON`` function id. It is
- assumed that even if the input arguments are the same as the ones defined in
- the PSCI standard, the usage deviates by the fact the secondary EC is not
- woken up immediately. At least for the FF-A EAC where only
- direct messaging is allowed, it is only after the first direct
- message invocation that the secondary EC is entered. This option
- might be preferred when the same code base is re-used for a VM or
- an SP. The ABI to wake-up a secondary EC can remain similar.
-
-SPs are always scheduled from the NWd, this paradigm did not change from legacy
-TEEs. There must always be some logic (or driver) in the NWd to relinquish CPU
-cycles to the SWd. If primary core is 0, an SP EC[x>0] entry point is supplied
-by the SP EC[0] when the system boots in SWd. But this EC[x] is not immediately
-entered at boot. Later in the boot process when NWd is up, a direct message
-request issued from physical core 1 ends up in SP EC[1], and only at this stage
-this context is effectively scheduled.
-
-It should be possible for an SP to call into another SP through direct message
-provided the latter SP has been booted already. The "boot-order" field in
-partition manifests (`SP Boot order`_) fulfills the dependency towards availability
-of a service within an SP offered to another SP.
+Upon boot-up, BL31 hands over to the SPMC (BL32) on the primary boot physical
+core. The SPMC performs its platform initializations and registers the SPMC
+secondary physical core entry point physical address by the use of the
+FFA_SECONDARY_EP_REGISTER interface (SMC invocation from the SPMC to the SPMD
+at secure physical FF-A instance). This interface is implementation-defined in
+context of FF-A v1.0.
+
+The SPMC then creates secure partitions based on SP packages and manifests. Each
+secure partition is launched in sequence (`SP Boot order`_) on their "primary"
+execution context. If the primary boot physical core linear id is N, an MP SP is
+started using EC[N] on PE[N] (see `Platform topology`_). If the partition is a
+UP SP, it is started using its unique EC0 on PE[N].
+
+The SP primary EC (or the EC used when the partition is booted as described
+above):
+
+- Performs the overall SP boot time initialization, and in case of a MP SP,
+ prepares the SP environment for other execution contexts.
+- In the case of a MP SP, it invokes the FFA_SECONDARY_EP_REGISTER at secure
+ virtual FF-A instance (SMC invocation from SP to SPMC) to provide the IPA
+ entry point for other execution contexts.
+- Exits through ``FFA_MSG_WAIT`` to indicate successful initialization or
+ ``FFA_ERROR`` in case of failure.
+
+Secondary cores boot-up
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the system is started and NWd brought up, a secondary physical core is
+woken up by the ``PSCI_CPU_ON`` service invocation. The TF-A SPD hook mechanism
+calls into the SPMD on the newly woken up physical core. Then the SPMC is
+entered at the secondary physical core entry point.
+
+In the current implementation, the first SP is resumed on the coresponding EC
+(the virtual CPU which matches the physical core). The implication is that the
+first SP must be a MP SP.
+
+In a linux based system, once secure and normal worlds are booted but prior to
+a NWd FF-A driver has been loaded:
+
+- The first SP has initialized all its ECs in response to primary core boot up
+ (at system initialization) and secondary core boot up (as a result of linux
+ invoking PSCI_CPU_ON for all secondary cores).
+- Other SPs have their first execution context initialized as a result of secure
+ world initialization on the primary boot core. Other ECs for those SPs have to
+ be run first through ffa_run to complete their initialization (which results
+ in the EC completing with FFA_MSG_WAIT).
+
+Refer to `Power management`_ for further details.
Mandatory interfaces
--------------------
-The following interfaces must be exposed to any VM or SP:
+The following interfaces are exposed to SPs:
-- ``FFA_STATUS``
-- ``FFA_ERROR``
-- ``FFA_INTERRUPT``
- ``FFA_VERSION``
- ``FFA_FEATURES``
- ``FFA_RX_RELEASE``
- ``FFA_RXTX_MAP``
-- ``FFA_RXTX_UNMAP``
+- ``FFA_RXTX_UNMAP`` (not implemented)
- ``FFA_PARTITION_INFO_GET``
- ``FFA_ID_GET``
+- ``FFA_MSG_WAIT``
+- ``FFA_MSG_SEND_DIRECT_REQ``
+- ``FFA_MSG_SEND_DIRECT_RESP``
+- ``FFA_MEM_DONATE``
+- ``FFA_MEM_LEND``
+- ``FFA_MEM_SHARE``
+- ``FFA_MEM_RETRIEVE_REQ``
+- ``FFA_MEM_RETRIEVE_RESP``
+- ``FFA_MEM_RELINQUISH``
+- ``FFA_MEM_RECLAIM``
+- ``FFA_SECONDARY_EP_REGISTER``
FFA_VERSION
~~~~~~~~~~~
-Per `[1]`_ section 8.1 ``FFA_VERSION`` requires a
-*requested_version* parameter from the caller.
+``FFA_VERSION`` requires a *requested_version* parameter from the caller.
+The returned value depends on the caller:
-In the current implementation when ``FFA_VERSION`` is invoked from:
-
-- Hypervisor in NS-EL2: the SPMD returns the SPMC version specified
- in the SPMC manifest.
-- OS kernel in NS-EL1 when NS-EL2 is not present: the SPMD returns the
- SPMC version specified in the SPMC manifest.
-- VM in NWd: the Hypervisor returns its implemented version.
-- SP in SWd: the SPMC returns its implemented version.
-- SPMC at S-EL1/S-EL2: the SPMD returns its implemented version.
+- Hypervisor or OS kernel in NS-EL1/EL2: the SPMD returns the SPMC version
+ specified in the SPMC manifest.
+- SP: the SPMC returns its own implemented version.
+- SPMC at S-EL1/S-EL2: the SPMD returns its own implemented version.
FFA_FEATURES
~~~~~~~~~~~~
-FF-A features may be discovered by Secure Partitions while booting
-through the SPMC. However, SPMC cannot get features from Hypervisor
-early at boot time as NS world is not setup yet.
+FF-A features supported by the SPMC may be discovered by secure partitions at
+boot (that is prior to NWd is booted) or run-time.
+
+The SPMC calling FFA_FEATURES at secure physical FF-A instance always get
+FFA_SUCCESS from the SPMD.
-The Hypervisor may decide to gather FF-A features from SPMC through SPMD
-once at boot time and store the result. Later when a VM requests FF-A
-features, the Hypervisor can adjust its own set of features with what
-SPMC advertised, if necessary. Another approach is to always forward FF-A
-features to the SPMC when a VM requests it to the Hypervisor. Although
-the result is not supposed to change over time so there may not be added
-value doing the systematic forwarding.
+The request made by an Hypervisor or OS kernel is forwarded to the SPMC and
+the response relayed back to the NWd.
FFA_RXTX_MAP/FFA_RXTX_UNMAP
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-VM mailboxes are re-purposed to serve as SP RX/TX buffers. The RX/TX
-map API maps the send and receive buffer IPAs to the SP Stage-2 translation regime.
+When invoked from a secure partition FFA_RXTX_MAP maps the provided send and
+receive buffers described by their IPAs to the SP EL1&0 Stage-2 translation
+regime as secure buffers in the MMU descriptors.
-Hafnium in the normal world defines VMs and their attributes as logical structures,
-including a mailbox used for FF-A indirect messaging, memory sharing, or the
-`FFA_PARTITION_INFO_GET`_ ABI.
-This same mailbox structure is re-used in the SPMC. `[1]`_ states only direct
-messaging is allowed to SPs. Thus mailbox usage is restricted to implementing
-`FFA_PARTITION_INFO_GET`_ and memory sharing ABIs.
+When invoked from the Hypervisor or OS kernel, the buffers are mapped into the
+SPMC EL2 Stage-1 translation regime and marked as NS buffers in the MMU
+descriptors.
+
+Note:
+
+- FFA_RXTX_UNMAP is not implemented.
FFA_PARTITION_INFO_GET
~~~~~~~~~~~~~~~~~~~~~~
-Partition info get service call can originate:
-
-- from SP to SPM
-- from VM to Hypervisor
-- from Hypervisor to SPM
+Partition info get call can originate:
-For the latter case, the service call must be forwarded through the SPMD.
+- from SP to SPMC
+- from Hypervisor or OS kernel to SPMC. The request is relayed by the SPMD.
FFA_ID_GET
~~~~~~~~~~
-The SPMD returns:
+The FF-A id space is split into a non-secure space and secure space:
-- a default zero value on invocation from the Hypervisor.
-- The ``spmc_id`` value specified in the SPMC manifest on invocation from
- the SPMC (see `SPMC manifest`_)
+- FF-A ID with bit 15 clear relates to VMs.
+- FF-A ID with bit 15 set related to SPs.
+- FF-A IDs 0, 0xffff, 0x8000 are assigned respectively to the Hypervisor, SPMD
+ and SPMC.
-The FF-A id space is split into a non-secure space and secure space:
+The SPMD returns:
-- FF-A id with bit 15 clear refer to normal world VMs.
-- FF-A id with bit 15 set refer to secure world SPs
+- The default zero value on invocation from the Hypervisor.
+- The ``spmc_id`` value specified in the SPMC manifest on invocation from
+ the SPMC (see `SPMC manifest`_)
-Such convention helps the SPMC discriminating the origin and destination worlds
-in an FF-A service invocation. In particular the SPMC shall filter unauthorized
+This convention helps the SPMC to determine the origin and destination worlds in
+an FF-A ABI invocation. In particular the SPMC shall filter unauthorized
transactions in its world switch routine. It must not be permitted for a VM to
-use a secure FF-A id as origin world through spoofing:
+use a secure FF-A ID as origin world by spoofing:
-- A VM-to-SP messaging passing shall have an origin world being non-secure
- (FF-A id bit 15 clear) and destination world being secure (FF-A id bit 15
- set).
-- Similarly, an SP-to-SP message shall have FF-A id bit 15 set for both origin
- and destination ids.
+- A VM-to-SP direct request/response shall set the origin world to be non-secure
+ (FF-A ID bit 15 clear) and destination world to be secure (FF-A ID bit 15
+ set).
+- Similarly, an SP-to-SP direct request/response shall set the FF-A ID bit 15
+ for both origin and destination IDs.
An incoming direct message request arriving at SPMD from NWd is forwarded to
SPMC without a specific check. The SPMC is resumed through eret and "knows" the
message is coming from normal world in this specific code path. Thus the origin
-endpoint id must be checked by SPMC for being a normal world id.
+endpoint ID must be checked by SPMC for being a normal world ID.
An SP sending a direct message request must have bit 15 set in its origin
-endpoint id and this can be checked by the SPMC when the SP invokes the ABI.
+endpoint ID and this can be checked by the SPMC when the SP invokes the ABI.
The SPMC shall reject the direct message if the claimed world in origin endpoint
-id is not consistent:
-
-- It is either forwarded by SPMD and thus origin endpoint id must be a "normal
- world id",
-- or initiated by an SP and thus origin endpoint id must be a "secure world id".
-
-Direct messaging
-----------------
-
-This is a mandatory interface for Secure Partitions consisting in direct
-message request and responses.
-
-The ``ffa_handler`` Hafnium function may:
+ID is not consistent:
-- trigger a world change e.g. when an SP invokes the direct message
- response ABI to a VM.
-- handle multiple requests from the NWd without resuming an SP.
+- It is either forwarded by SPMD and thus origin endpoint ID must be a "normal
+ world ID",
+- or initiated by an SP and thus origin endpoint ID must be a "secure world ID".
-SP-to-SP
-~~~~~~~~
-- An SP can send a direct message request to another SP
-- An SP can receive a direct message response from another SP.
+FFA_MSG_SEND_DIRECT_REQ/FFA_MSG_SEND_DIRECT_RESP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-VM-to-SP
-~~~~~~~~
+This is a mandatory interface for secure partitions consisting in direct request
+and responses with the following rules:
-- A VM can send a direct message request to an SP
-- An SP can send a direct message response to a VM
+- An SP can send a direct request to another SP.
+- An SP can receive a direct request from another SP.
+- An SP can send a direct response to another SP.
+- An SP cannot send a direct request to an Hypervisor or OS kernel.
+- An Hypervisor or OS kernel can send a direct request to an SP.
+- An SP can send a direct response to an Hypervisor or OS kernel.
-SPMC-SPMD messaging
-~~~~~~~~~~~~~~~~~~~
+SPMC-SPMD direct requests/responses
+-----------------------------------
-Specific implementation-defined endpoint IDs are allocated to the SPMC and SPMD.
-Referring those IDs in source/destination fields of a direct message
-request/response permits SPMD to SPMC messaging back and forth.
+Implementation-defined FF-A IDs are allocated to the SPMC and SPMD.
+Using those IDs in source/destination fields of a direct request/response
+permits SPMD to SPMC communication and either way.
-Per `[1]`_ Table 114 Config No. 1 (physical FF-A instance):
+- SPMC to SPMD direct request/response uses SMC conduit.
+- SPMD to SPMC direct request/response uses ERET conduit.
-- SPMC=>SPMD direct message request uses SMC conduit
-- SPMD=>SPMC direct message request uses ERET conduit
-
-Per `[1]`_ Table 118 Config No. 1 (physical FF-A instance):
-
-- SPMC=>SPMD direct message response uses SMC conduit
-- SPMD=>SPMC direct message response uses ERET conduit
-
-Memory management
------------------
+PE MMU configuration
+--------------------
-This section only deals with the PE MMU configuration.
+With secure virtualization enabled, two IPA spaces are output from the secure
+EL1&0 Stage-1 translation (secure and non-secure). The EL1&0 Stage-2 translation
+hardware is fed by:
-Hafnium in the normal world deals with NS buffers only and provisions
-a single root page table directory to VMs. In context of S-EL2 enabled
-firmware, two IPA spaces are output from Stage-1 translation (secure
-and non-secure). The Stage-2 translation handles:
+- A single secure IPA space when the SP EL1&0 Stage-1 MMU is disabled.
+- Two IPA spaces (secure and non-secure) when the SP EL1&0 Stage-1 MMU is
+ enabled.
-- A single secure IPA space when an SP Stage-1 MMU is disabled.
-- Two IPA spaces (secure and non-secure) when Stage-1 MMU is enabled.
+``VTCR_EL2`` and ``VSTCR_EL2`` provide configuration bits for controlling the
+NS/S IPA translations.
+``VSTCR_EL2.SW`` = 0, ``VSTCR_EL2.SA`` = 0,``VTCR_EL2.NSW`` = 0, ``VTCR_EL2.NSA`` = 1:
-``VTCR_EL2`` and ``VSTCR_EL2`` provide additional bits for controlling the
-NS/S IPA translations (``VSTCR_EL2.SW``, ``VSTCR_EL2.SA``, ``VTCR_EL2.NSW``,
-``VTCR_EL2.NSA``). There may be two approaches:
+- Stage-2 translations for the NS IPA space access the NS PA space.
+- Stage-2 translation table walks for the NS IPA space are to the secure PA space.
-- secure and non-secure mappings are rooted as two separate root page
- tables
-- secure and non-secure mappings use the same root page table. Access
- from S-EL1 to an NS region translates to a secure physical address
- space access.
+Secure and non-secure IPA regions use the same set of Stage-2 page tables within
+a SP.
Interrupt management
--------------------
-Road to a para-virtualized interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+GIC ownership
+~~~~~~~~~~~~~
-Current Hafnium implementation uses an ad-hoc mechanism for a VM to get
-a pending interrupt number through an hypercall. The PVM injects
-interrupts to VMs by delegation from the Hypervisor. The PVM probes a
-pending interrupt directly from the GIC distributor.
+The SPMC owns the GIC configuration. Secure and non-secure interrupts are
+trapped at S-EL2. The SPMC manages interrupt resources and allocates interrupt
+IDs based on SP manifests. The SPMC acknowledges physical interrupts and injects
+virtual interrupts by setting the use of vIRQ/vFIQ bits before resuming a SP.
-The short-term plan is to have Hafnium/SPMC in the secure world owner
-of the GIC configuration.
+Non-secure interrupt handling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The SPMC fully owns the GIC configuration at S-EL2. The SPMC manages
-interrupt resources and allocates interrupt ID based on SP manifests.
-The SPMC acknowledges physical interrupts and injects virtual interrupts
-by setting the vIRQ bit when resuming an SP. A Secure Partition gathers
-the interrupt number through an hypercall.
+The following illustrate the scenarios of non secure physical interrupts trapped
+by the SPMC:
-Notice the SPMC/SPMD has to handle Group0 secure interrupts in addition
-to Group1 S/NS interrupts.
+- The SP handles a managed exit operation:
-Power management
-----------------
+.. image:: ../resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png
-Assumption on the Nwd:
-
-- NWd is the best candidate to own the platform Power Management
- policy. It is master to invoking PSCI service calls from physical
- CPUs.
-- EL3 monitor is in charge of the PM control part (its PSCI layer
- actually writing to platform registers).
-- It is fine for the Hypervisor to trap PSCI calls and relay to EL3, or
- OS kernel driver to emit PSCI service calls.
-
-PSCI notification are relayed through the SPMD/SPD PM hooks to the SPMC.
-This can either be through re-use of PSCI FIDs or an FF-A direct message
-from SPMD to SPMC.
-
-The SPMD performs an exception return to the SPMC which is resumed to
-its ``eret_handler`` routine. It is then either consuming a PSCI FID or
-an FF-A FID. Depending on the servicing, the SPMC may return directly to
-the SPMD (and then NWd) without resuming an SP at this stage. An example
-of this is invocation of ``FFA_PARTITION_INFO_GET`` from NWd relayed by
-the SPMD to the SPMC. The SPMC returns the needed partition information
-to the SPMD (then NWd) without actually resuming a partition in secure world.
-
-*(under discussion)*
-About using PSCI FIDs from SPMD to SPMC to notify of PM events, it is still
-questioned what to use as the return code from the SPMC.
-If the function ID used by the SPMC is not an FF-A ID when doing SMC, then the
-EL3 std svc handler won't route the response to the SPMD. That's where comes the
-idea to embed the notification into an FF-A message. The SPMC can discriminate
-this message as being a PSCI event, process it, and reply with an FF-A return
-message that the SPMD receives as an acknowledgement.
-
-SP notification
----------------
+- The SP is pre-empted without managed exit:
-Power management notifications are conveyed from PSCI library to the
-SPMD / SPD hooks. A range of events can be relayed to SPMC.
+.. image:: ../resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png
-SPs may need to be notified about specific PM events.
+Secure interrupt handling
+~~~~~~~~~~~~~~~~~~~~~~~~~
-- SPs might register PM events to the SPMC
-- On SPMD to SPMC notification, a limited range of SPs may be notified
- through a direct message.
-- This assumes the mentioned SPs supports managed exit.
+The current implementation does not support handling of secure interrupts
+trapped by the SPMC at S-EL2. This is work in progress planned for future
+releases.
-The SPMC is the first to be notified about PM events from the SPMD. It is up
-to the SPMC to arbitrate to which SP it needs to send PM events.
-An SP explicitly registers to receive notifications to specific PM events.
-The register operation can either be an implementation-defined service call
-to the SPMC when the primary SP EC boots, or be supplied through the SP
-manifest.
+Power management
+----------------
-Support for SMMUv3 in Hafnium
-=============================
+In platforms with or without secure virtualization:
+
+- The NWd owns the platform PM policy.
+- The Hypervisor or OS kernel is the component initiating PSCI service calls.
+- The EL3 PSCI library is in charge of the PM coordination and control
+ (eventually writing to platform registers).
+- While coordinating PM events, the PSCI library calls backs into the Secure
+ Payload Dispatcher for events the latter has statically registered to.
+
+When using the SPMD as a Secure Payload Dispatcher:
+
+- A power management event is relayed through the SPD hook to the SPMC.
+- In the current implementation only cpu on (svc_on_finish) and cpu off
+ (svc_off) hooks are registered.
+- The behavior for the cpu on event is described in `Secondary cores boot-up`_.
+ The SPMC is entered through its secondary physical core entry point.
+- The cpu off event occurs when the NWd calls PSCI_CPU_OFF. The method by which
+ the PM event is conveyed to the SPMC is implementation-defined in context of
+ FF-A v1.0 (`SPMC-SPMD direct requests/responses`_). It consists in a SPMD-to-SPMC
+ direct request/response conveying the PM event details and SPMC response.
+ The SPMD performs a synchronous entry into the SPMC. The SPMC is entered and
+ updates its internal state to reflect the physical core is being turned off.
+ In the current implementation no SP is resumed as a consequence. This behavior
+ ensures a minimal support for CPU hotplug e.g. when initiated by the NWd linux
+ userspace.
+
+SMMUv3 support in Hafnium
+=========================
An SMMU is analogous to an MMU in a CPU. It performs address translations for
Direct Memory Access (DMA) requests from system I/O devices.
@@ -856,7 +829,7 @@ several I/O devices along with Interconnect and Memory system.
.. image:: ../resources/diagrams/MMU-600.png
SMMU has several versions including SMMUv1, SMMUv2 and SMMUv3. Hafnium provides
-support for SMMUv3 driver in both Normal and Secure World. A brief introduction
+support for SMMUv3 driver in both normal and secure world. A brief introduction
of SMMUv3 functionality and the corresponding software support in Hafnium is
provided here.
@@ -956,7 +929,7 @@ References
.. _[3]:
[3] `Trusted Boot Board Requirements
-Client <https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a>`__
+Client <https://developer.arm.com/documentation/den0006/d/>`__
.. _[4]:
@@ -964,7 +937,7 @@ Client <https://developer.arm.com/docs/den0006/latest/trusted-board-boot-require
.. _[5]:
-[5] https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/spm/cactus/cactus.dts
+[5] https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/spm/cactus/plat/arm/fvp/fdts/cactus.dts
.. _[6]:
@@ -976,7 +949,7 @@ Client <https://developer.arm.com/docs/den0006/latest/trusted-board-boot-require
.. _[8]:
-[8] https://developer.trustedfirmware.org/w/tf_a/poc-multiple-signing-domains/
+[8] https://lists.trustedfirmware.org/pipermail/tf-a/2020-February/000296.html
--------------
diff --git a/docs/resources/diagrams/ff-a-spm-sel2.png b/docs/resources/diagrams/ff-a-spm-sel2.png
index 6479ff5598..605fd9b21d 100644
--- a/docs/resources/diagrams/ff-a-spm-sel2.png
+++ b/docs/resources/diagrams/ff-a-spm-sel2.png
Binary files differ
diff --git a/docs/resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png b/docs/resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png
new file mode 100644
index 0000000000..0619cf260b
--- /dev/null
+++ b/docs/resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png
Binary files differ
diff --git a/docs/resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png b/docs/resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png
new file mode 100644
index 0000000000..f110028897
--- /dev/null
+++ b/docs/resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png
Binary files differ