diff options
Diffstat (limited to 'docs/components')
| -rw-r--r-- | docs/components/el3-spmc.rst | 597 | ||||
| -rw-r--r-- | docs/components/ffa-manifest-binding.rst | 13 | ||||
| -rw-r--r-- | docs/components/firmware-update.rst | 147 | ||||
| -rw-r--r-- | docs/components/index.rst | 3 | ||||
| -rw-r--r-- | docs/components/ras.rst | 19 | ||||
| -rw-r--r-- | docs/components/realm-management-extension.rst | 332 | ||||
| -rw-r--r-- | docs/components/rmm-el3-comms-spec.rst | 543 | ||||
| -rw-r--r-- | docs/components/secure-partition-manager.rst | 312 | ||||
| -rw-r--r-- | docs/components/spd/index.rst | 1 | ||||
| -rw-r--r-- | docs/components/spd/pnc-dispatcher.rst | 10 |
10 files changed, 1751 insertions, 226 deletions
diff --git a/docs/components/el3-spmc.rst b/docs/components/el3-spmc.rst new file mode 100644 index 000000000..1a2d4273b --- /dev/null +++ b/docs/components/el3-spmc.rst @@ -0,0 +1,597 @@ +EL3 Secure Partition Manager +**************************** + +.. contents:: + +Foreword +======== + +This document describes the design of the EL3 SPMC based on the FF-A specification. +EL3 SPMC provides reference FF-A compliant implementation without S-EL2 virtualization support, +to help adopt and migrate to FF-A early. +EL3 SPMC implementation in TF-A: + +- Manages a single S-EL1 Secure Partition +- Provides a standard protocol for communication and memory sharing between FF-A endpoints. +- Provides support for EL3 Logical Partitions to support easy migration from EL3 to S-EL1. + +Sample reference stack +====================== + +The following diagram illustrates a possible configuration when the +FEAT_SEL2 architecture extension is not implemented, showing the SPMD +and SPMC at EL3, one S-EL1 secure partition, with an optional +Hypervisor: + +.. image:: ../resources/diagrams/ff-a-spm-at-el3.png + +TF-A build options +================== + +This section explains the TF-A build options involved in building +an FF-A based SPM where the SPMD and SPMC are located at EL3: + +- **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. +- **SPMC_AT_EL3**: this option adjusts the SPMC exception level to being + at EL3. +- **ARM_SPMC_MANIFEST_DTS**: this option specifies a manifest file + providing SP description. It is required when + ``SPMC_AT_EL3`` is enabled, the secure partitions are loaded + by BL2 on behalf of the SPMC. + +Notes: + +- BL32 option is re-purposed to specify the S-EL1 TEE or SP image. + BL32 option can be omitted if using TF-A Test Secure Payload as SP. +- BL33 option can specify the TFTF binary or a normal world loader + such as U-Boot or the UEFI framework payload. + +Sample TF-A build command line when the SPMC is located at EL3: + +.. code:: shell + + make \ + CROSS_COMPILE=aarch64-none-elf- \ + SPD=spmd \ + SPMD_SPM_AT_SEL2=0 \ + SPMC_AT_EL3=1 \ + BL32=<path-to-tee-binary> (opt for TSP) \ + BL33=<path-to-bl33-binary> \ + PLAT=fvp \ + all fip + +FVP model invocation +==================== + +Sample FVP command line invocation: + +.. code:: shell + + <path-to-fvp-model>/FVP_Base_RevC-2xAEMvA -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 bp.vis.disable_visualisation=1 + + +Platform Guide +============== + +- Platform Hooks See - `[4]`_ + + - plat_spmc_shmem_begin + - plat_spmc_shmem_reclaim + +SPMC provides platform hooks related to memory management interfaces. +These hooks can be used for platform specific implementations like +for managing access control, programming TZ Controller or MPUs. +These hooks are called by SPMC before the initial share request completes, +and after the final reclaim has been completed. + +- Datastore + + - plat_spmc_shmem_datastore_get + + EL3 SPMC uses datastore for tracking memory transaction descriptors. + On FVP platform datastore is allocated from TZC DRAM section. + Other platforms need to allocate a similar secure memory region + to be used as shared memory datastore. + + The accessor function is used during SPMC initialization to obtain + address and size of the datastore. + SPMC will also zero out the provided memory region. + +- Platform Defines See - `[5]`_ + + - SECURE_PARTITION_COUNT + Number of Secure Partitions supported: must be 1. + + - NS_PARTITION_COUNT + Number of NWd Partitions supported. + + - MAX_EL3_LP_DESCS_COUNT + Number of Logical Partitions supported. + +Logical Secure Partition (LSP) +============================== + +- The SPMC provides support for statically allocated EL3 Logical Secure Partitions + as per FF-A v1.1 specification. +- The DECLARE_LOGICAL_PARTITION macro can be used to add a LSP. +- For reference implementation See - `[2]`_ + +.. image:: ../resources/diagrams/ff-a-lsp-at-el3.png + +SPMC boot +========= + +The SPMD and SPMC are built into the BL31 image along with TF-A's runtime components. +BL2 loads the BL31 image as a part of (secure) boot process. + +The SPMC manifest is loaded by BL2 as the ``TOS_FW_CONFIG`` image `[9]`_. + +BL2 passes the SPMC manifest address to BL31 through a register. + +At boot time, the SPMD in BL31 runs from the primary core, initializes the core +contexts and launches the SPMC passing the following information through +registers: + +- X0 holds the SPMC manifest blob address. +- X4 holds the currently running core linear id. + +Parsing SP partition manifests +------------------------------ + +SPMC consumes the SP manifest, as defined in `[7]`_. +SP manifest fields align with Hafnium SP manifest for easy porting. + +.. code:: shell + + compatible = "arm,ffa-manifest-1.0"; + + ffa-version = <0x00010001>; /* 31:16 - Major, 15:0 - Minor */ + id = <0x8001>; + uuid = <0x6b43b460 0x74a24b78 0xade24502 0x40682886>; + messaging-method = <0x3>; /* Direct Messaging Only */ + exception-level = <0x2>; /* S-EL1 */ + execution-state = <0>; + execution-ctx-count = <8>; + gp-register-num = <0>; + power-management-messages = <0x7>; + + +Passing boot data to the SP +--------------------------- + +In `[1]`_ , the section "Boot information protocol" defines a method for passing +data to the SPs at boot time. It specifies the format for the boot information +descriptor and boot information header structures, which describe the data to be +exchanged between SPMC and SP. +The specification also defines the types of data that can be passed. +The aggregate of both the boot info structures and the data itself is designated +the boot information blob, and is passed to a Partition as a contiguous memory +region. + +Currently, the SPM implementation supports the FDT type which is used to pass the +partition's DTB manifest. + +The region for the boot information blob is statically allocated (4K) by SPMC. +BLOB contains Boot Info Header, followed by SP Manifest contents. + +The configuration of the boot protocol is done in the SP manifest. As defined by +the specification, the manifest field 'gp-register-num' configures the GP register +which shall be used to pass the address to the partitions boot information blob when +booting the partition. + +Supported interfaces +==================== + +The following interfaces are exposed to SPs only: + +- ``FFA_MSG_WAIT`` +- ``FFA_MEM_RETRIEVE_REQ`` +- ``FFA_MEM_RETRIEVE_RESP`` +- ``FFA_MEM_RELINQUISH`` +- ``FFA_SECONDARY_EP_REGISTER`` + +The following interfaces are exposed to both NS Client and SPs: + +- ``FFA_VERSION`` +- ``FFA_FEATURES`` +- ``FFA_RX_RELEASE`` +- ``FFA_RXTX_MAP`` +- ``FFA_RXTX_UNMAP`` +- ``FFA_PARTITION_INFO_GET`` +- ``FFA_ID_GET`` +- ``FFA_MSG_SEND_DIRECT_REQ`` +- ``FFA_MSG_SEND_DIRECT_RESP`` +- ``FFA_MEM_FRAG_TX`` +- ``FFA_SPM_ID_GET`` + +The following additional interfaces are forwarded from SPMD to support NS Client: + +- ``FFA_RUN`` +- ``FFA_MEM_LEND`` +- ``FFA_MEM_SHARE`` +- ``FFA_MEM_FRAG_RX`` +- ``FFA_MEM_RECLAIM`` + + +FFA_VERSION +----------- + +``FFA_VERSION`` requires a *requested_version* parameter from the caller. +SPMD forwards call to SPMC, the SPMC returns its own implemented version. +SPMC asserts SP and SPMC are at same FF-A Version. + +FFA_FEATURES +------------ + +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 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 +-------------- + +When invoked from a secure partition FFA_RXTX_MAP maps the provided send and +receive buffers described by their PAs to the EL3 translation regime +as secure buffers in the MMU descriptors. + +When invoked from the Hypervisor or OS kernel, the buffers are mapped into the +SPMC EL3 translation regime and marked as NS buffers in the MMU +descriptors. + +The FFA_RXTX_UNMAP unmaps the RX/TX pair from the translation regime of the +caller, either it being the Hypervisor or OS kernel, as well as a secure +partition. + +FFA_PARTITION_INFO_GET +---------------------- + +Partition info get call can originate: + +- from SP to SPMC +- from Hypervisor or OS kernel to SPMC. The request is relayed by the SPMD. + +The format (v1.0 or v1.1) of the populated data structure returned is based upon the +FFA version of the calling entity. + +EL3 SPMC also supports returning only the count of partitions deployed. + +All LSPs and SP are discoverable from FFA_PARTITION_INFO_GET call made by +either SP or NWd entities. + +FFA_ID_GET +---------- + +The FF-A ID space is split into a non-secure space and secure space: + +- FF-A ID with bit 15 clear relates to VMs. +- FF-A ID with bit 15 set related to SPs or LSPs. +- FF-A IDs 0, 0xffff, 0x8000 are assigned respectively to the Hypervisor + (or OS Kernel if Hyp is absent), SPMD and SPMC. + +This convention helps the SPM to determine the origin and destination worlds in +an FF-A ABI invocation. In particular the SPM 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 by spoofing: + +- 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-LSP 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. + +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. + +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". + + +FFA_MSG_SEND_DIRECT_REQ +----------------------- + +FFA_MSG_SEND_DIRECT_RESP +------------------------ + +This is a mandatory interface for secure partitions participating in direct request +and responses with the following rules: + +- An SP can send a direct request to LSP. +- An LSP can send a direct response to 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 or LSP. +- An SP and LSP can send a direct response to an Hypervisor or OS kernel. +- SPMD can send direct request to SPMC. + +FFA_SPM_ID_GET +-------------- + +Returns the FF-A ID allocated to an SPM component which can be one of SPMD +or SPMC. + +At initialization, the SPMC queries the SPMD for the SPMC ID, using the +FFA_ID_GET interface, and records it. The SPMC can also query the SPMD ID using +the FFA_SPM_ID_GET interface at the secure physical FF-A instance. + +Secure partitions call this interface at the virtual FF-A instance, to which +the SPMC returns the SPMC ID. + +The Hypervisor or OS kernel can issue the FFA_SPM_ID_GET call handled by the +SPMD, which returns the SPMC ID. + +FFA_ID_GET +---------- + +Returns the FF-A ID of the calling endpoint. + +FFA_MEM_SHARE +------------- + +FFA_MEM_LEND +------------ + +- If SP is borrower in the memory transaction, these calls are forwarded to SPMC. + SPMC performs Relayer responsibilities, caches the memory descriptors in the datastore, + and allocates FF-A memory handle. +- If format of descriptor was v1.0, SPMC converts the descriptor to v1.1 before caching. + In case of fragmented sharing, conversion of memory descriptors happens after last + fragment has been received. +- Multiple borrowers (including NWd endpoint) and fragmented memory sharing are supported. + +FFA_MEM_RETRIEVE_REQ +-------------------- + +FFA_MEM_RETRIEVE_RESP +--------------------- + +- Memory retrieve is supported only from SP. +- SPMC fetches the cached memory descriptor from the datastore, +- Performs Relayer responsiilities and sends FFA_MEM_RETRIEVE_RESP back to SP. +- If descriptor size is more than RX buffer size, SPMC will send the descriptor in fragments. +- SPMC will set NS Bit to 1 in memory descriptor response. + +FFA_MEM_FRAG_RX +--------------- + +FFA_MEM_FRAG_TX +--------------- + +FFA_MEM_FRAG_RX is to be used by: + +- SP if FFA_MEM_RETRIEVE_RESP returned descriptor with fragment length less than total length. +- or by SPMC if FFA_MEM_SHARE/FFA_MEM_LEND is called with fragment length less than total length. + +SPMC validates handle and Endpoint ID and returns response with FFA_MEM_FRAG_TX. + +FFA_SECONDARY_EP_REGISTER +------------------------- + +When the SPMC boots, secure partition is initialized on its primary +Execution Context. + +The FFA_SECONDARY_EP_REGISTER interface is to be used by a secure partition +from its first execution context, to provide the entry point address for +secondary execution contexts. + +A secondary EC is first resumed either upon invocation of PSCI_CPU_ON from +the NWd or by invocation of FFA_RUN. + +Power management +================ + +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 CPU_ON (svc_on_finish), CPU_OFF + (svc_off), CPU_SUSPEND (svc_suspend) and CPU_SUSPEND_RESUME (svc_suspend_finish) + hooks are registered. + +Secure partitions scheduling +============================ + +The FF-A 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: + +- the FFA_MSG_SEND_DIRECT_REQ interface. +- the FFA_RUN interface. + +Additionally a secure interrupt can pre-empt the normal world execution and give +CPU cycles by transitioning to EL3. + +Partition Runtime State and Model +================================= + +EL3 SPMC implements Partition runtime states are described in v1.1 FF-A specification `[1]`_ + +An SP can be in one of the following state: + +- RT_STATE_WAITING +- RT_STATE_RUNNING +- RT_STATE_PREEMPTED +- RT_STATE_BLOCKED + +An SP will transition to one of the following runtime model when not in waiting state: + +- RT_MODEL_DIR_REQ +- RT_MODEL_RUN +- RT_MODEL_INIT +- RT_MODEL_INTR + +Platform topology +================= + +SPMC only supports a single Pinned MP S-EL1 SP. The *execution-ctx-count* +SP manifest field should match the number of physical PE. + +Interrupt handling +================== + +Secure Interrupt handling +------------------------- + +- SPMC is capable of forwarding Secure interrupt to S-EL1 SP + which has preempted the normal world. +- Interrupt is forwarded to SP using FFA_INTERRUPT interface. +- Interrupt Number is not passed, S-EL1 SP can access the GIC registers directly. +- Upon completion of Interrupt handling SP is expected to return to + SPMC using FFA_MSG_WAIT interface. +- SPMC returns to normal world after interrupt handling is completed. + +In the scenario when secure interrupt occurs while the secure partition is running, +the SPMC is not involved and the handling is implementation defined in the TOS. + +Non-Secure Interrupt handling +----------------------------- + +The 'managed exit' scenario is the responsibility of the TOS and the SPMC is not involved. + +Test Secure Payload (TSP) +========================= + +- TSP provides reference implementation of FF-A programming model. +- TSP has the following support: + + - SP initialization on all CPUs. + - Consuming Power Messages including CPU_ON, CPU_OFF, CPU_SUSPEND, CPU_SUSPEND_RESUME. + - Event Loop to receive Direct Requests. + - Sending Direct Response. + - Memory Sharing helper library. + - Ability to handle secure interrupt (timer). + +TSP Tests in CI +--------------- + +- TSP Tests are exercised in the TF-A CI using prebuilt FF-A Linux Test driver in NWd. +- Expected output: + +.. code:: shell + + #ioctl 255 + Test: Echo Message to SP. + Status: Completed Test Case: 1 + Test Executed Successfully + + Test: Message Relay vis SP to EL3 LSP. + Status: Completed Test Case: 2 + Test Executed Successfully + + Test: Memory Send. + Verified 1 constituents successfully + Status: Completed Test Case: 3 + Test Executed Successfully + + Test: Memory Send in Fragments. + Verified 256 constituents successfully + Status: Completed Test Case: 4 + Test Executed Successfully + + Test: Memory Lend. + Verified 1 constituents successfully + Status: Completed Test Case: 5 + Test Executed Successfully + + Test: Memory Lend in Fragments. + Verified 256 constituents successfully + Status: Completed Test Case: 6 + Test Executed Successfully + + Test: Memory Send with Multiple Endpoints. + random: fast init done + Verified 256 constituents successfully + Status: Completed Test Case: 7 + Test Executed Successfully + + Test: Memory Lend with Multiple Endpoints. + Verified 256 constituents successfully + Status: Completed Test Case: 8 + Test Executed Successfully + + Test: Ensure Duplicate Memory Send Requests are Rejected. + Status: Completed Test Case: 9 + Test Executed Successfully + + Test: Ensure Duplicate Memory Lend Requests are Rejected. + Status: Completed Test Case: 10 + Test Executed Successfully + + 0 Tests Failed + + Exiting Test Application - Total Failures: 0 + + +References +========== + +.. _[1]: + +[1] `Arm Firmware Framework for Arm A-profile <https://developer.arm.com/docs/den0077/latest>`__ + +.. _[2]: + +[2] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fvp_el3_spmc_logical_sp.c + +.. _[3]: + +[3] `Trusted Boot Board Requirements +Client <https://developer.arm.com/documentation/den0006/d/>`__ + +.. _[4]: + +[4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fvp_el3_spmc.c + +.. _[5]: + +[5] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/include/platform_def.h + +.. _[6]: + +[6] https://trustedfirmware-a.readthedocs.io/en/latest/components/ffa-manifest-binding.html + +.. _[7]: + +[7] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_tsp_sp_manifest.dts + +.. _[8]: + +[8] https://lists.trustedfirmware.org/archives/list/tf-a@lists.trustedfirmware.org/thread/CFQFGU6H2D5GZYMUYGTGUSXIU3OYZP6U/ + +.. _[9]: + +[9] https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#dynamic-configuration-during-cold-boot + +-------------- + +*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/components/ffa-manifest-binding.rst b/docs/components/ffa-manifest-binding.rst index 6d2f905a5..7483c9002 100644 --- a/docs/components/ffa-manifest-binding.rst +++ b/docs/components/ffa-manifest-binding.rst @@ -114,6 +114,19 @@ Partition Properties - managed-exit - value type: <empty> - Specifies if managed exit is supported. + - This field is deprecated in favor of ns-interrupts-action field in the FF-A + v1.1 EAC0 spec. + +- ns-interrupts-action [mandatory] + - value type: <u32> + - Specifies the action that the SPMC must take in response to a Non-secure + physical interrupt. + + - 0x0: Non-secure interrupt is queued + - 0x1: Non-secure interrupt is signaled after a managed exit + - 0x2: Non-secure interrupt is signaled + + - This field supersedes the managed-exit field in the FF-A v1.0 spec. - has-primary-scheduler - value type: <empty> diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst index a59156568..1ba1e1c6e 100644 --- a/docs/components/firmware-update.rst +++ b/docs/components/firmware-update.rst @@ -1,22 +1,118 @@ Firmware Update (FWU) ===================== +This document describes the design of the various Firmware Update (FWU) +mechanisms available in TF-A. + +1. PSA Firmware Update (PSA FWU) +2. TBBR Firmware Update (TBBR FWU) + +PSA Firmware Update implements the specification of the same name (Arm document +IHI 0093), which defines a standard firmware interface for installing firmware +updates. +On the other hand, TBBR Firmware Update only covers firmware recovery. Arguably, +its name is somewhat misleading but the TBBR specification and terminology +predates PSA FWU. Both mechanisms are complementary in the sense that PSA FWU +assumes that the device has a backup or recovery capability in the event of a +failed update, which can be fulfilled with TBBR FWU implementation. + +.. _PSA Firmware Update: + +PSA Firmware Update (PSA FWU) +----------------------------- + Introduction ------------- +~~~~~~~~~~~~ +The `PSA FW update specification`_ defines the concepts of ``Firmware Update +Client`` and ``Firmware Update Agent``. +The new firmware images are provided by the ``Client`` to the ``Update Agent`` +to flash them in non-volatile storage. -This document describes the design of the Firmware Update (FWU) feature, which -enables authenticated firmware to update firmware images from external -interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoC Non-Volatile -memories such as NAND Flash, LPDDR2-NVM or any memory determined by the -platform. This feature functions even when the current firmware in the system -is corrupt or missing; it therefore may be used as a recovery mode. It may also -be complemented by other, higher level firmware update software. +A common system design will place the ``Update Agent`` in the Secure-world +while the ``Client`` executes in the Normal-world. +The `PSA FW update specification`_ provides ABIs meant for a Normal-world +entity aka ``Client`` to transmit the firmware images to the ``Update Agent``. + +Scope +~~~~~ +The design of the ``Client`` and ``Update Agent`` is out of scope of this +document. +This document mainly covers ``Platform Boot`` details i.e. the role of +the second stage Bootloader after FWU has been done by ``Client`` and +``Update Agent``. + +Overview +~~~~~~~~ + +There are active and update banks in the non-volatile storage identified +by the ``active_index`` and the ``update_index`` respectively. +An active bank stores running firmware, whereas an update bank contains +firmware updates. + +Once Firmwares are updated in the update bank of the non-volatile +storage, then ``Update Agent`` marks the update bank as the active bank, +and write updated FWU metadata in non-volatile storage. +On subsequent reboot, the second stage Bootloader (BL2) performs the +following actions: + +- Read FWU metadata in memory +- Retrieve the image specification (offset and length) of updated images + present in non-volatile storage with the help of FWU metadata +- Set these image specification in the corresponding I/O policies of the + updated images using the FWU platform functions + ``plat_fwu_set_images_source()`` and ``plat_fwu_set_metadata_image_source()``, + please refer :ref:`Porting Guide` +- Use these I/O policies to read the images from this address into the memory + +By default, the platform uses the active bank of non-volatile storage to boot +the images in ``trial state``. If images pass through the authentication check +and also if the system successfully booted the Normal-world image then +``Update Agent`` marks this update as accepted after further sanitisation +checking at Normal-world. + +The second stage Bootloader (BL2) avoids upgrading the platform NV-counter until +it's been confirmed that given update is accepted. + +The following sequence diagram shows platform-boot flow: + +.. image:: ../resources/diagrams/PSA-FWU.png + +If the platform fails to boot from active bank due to any reasons such +as authentication failure or non-fuctionality of Normal-world software then the +watchdog will reset to give a chance to the platform to fix the issue. This +boot failure & reset sequence might be repeated up to ``trial state`` times. +After that, the platform can decide to boot from the ``previous_active_index`` +bank. + +If the images still does not boot successfully from the ``previous_active_index`` +bank (e.g. due to ageing effect of non-volatile storage) then the platform can +choose firmware recovery mechanism :ref:`TBBR Firmware Update` to bring system +back to life. + +.. _TBBR Firmware Update: + +TBBR Firmware Update (TBBR FWU) +------------------------------- + +Introduction +~~~~~~~~~~~~ + +This technique enables authenticated firmware to update firmware images from +external interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoC +Non-Volatile memories such as NAND Flash, LPDDR2-NVM or any memory determined +by the platform. +This feature functions even when the current firmware in the system is corrupt +or missing; it therefore may be used as a recovery mode. It may also be +complemented by other, higher level firmware update software. FWU implements a specific part of the Trusted Board Boot Requirements (TBBR) specification, Arm DEN0006C-1. It should be used in conjunction with the :ref:`Trusted Board Boot` design document, which describes the image authentication parts of the Trusted Firmware-A (TF-A) TBBR implementation. +It can be used as a last resort when all firmware updates that are carried out +as part of the :ref:`PSA Firmware Update` procedure have failed to function. + Scope ~~~~~ @@ -25,8 +121,8 @@ describe how normal world FWU images should operate. To implement normal world FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in the TBBR. -FWU Overview ------------- +Overview +~~~~~~~~ The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, and it is usually desirable to minimize the amount of ROM code, the design allows @@ -66,7 +162,7 @@ use all defined FWU images. Other platforms may use a subset of these. |Flow Diagram| Image Identification --------------------- +~~~~~~~~~~~~~~~~~~~~ Each FWU image and certificate is identified by a unique ID, defined by the platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a @@ -93,7 +189,7 @@ BL1 uses the FWU image descriptors to: - Initialize the execution state of the next FWU image. FWU State Machine ------------------ +~~~~~~~~~~~~~~~~~ BL1 maintains state for each FWU image during FWU execution. FWU images at lower Exception Levels raise SMCs to invoke FWU functionality in BL1, which causes @@ -126,10 +222,10 @@ The following is a brief description of the supported states: requested BL1 to resume normal world execution. BL1 SMC Interface ------------------ +~~~~~~~~~~~~~~~~~ BL1_SMC_CALL_COUNT -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ :: @@ -142,7 +238,7 @@ BL1_SMC_CALL_COUNT This SMC returns the number of SMCs supported by BL1. BL1_SMC_UID -~~~~~~~~~~~ +^^^^^^^^^^^ :: @@ -156,7 +252,7 @@ This SMC returns the 128-bit `Universally Unique Identifier`_ for the BL1 SMC service. BL1_SMC_VERSION -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ :: @@ -170,7 +266,7 @@ BL1_SMC_VERSION This SMC returns the current version of the BL1 SMC service. BL1_SMC_RUN_IMAGE -~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^ :: @@ -190,7 +286,7 @@ This SMC passes execution control to an EL3 image described by the provided this SMC for BL1 to pass execution control to BL31. FWU_SMC_IMAGE_COPY -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ :: @@ -239,7 +335,7 @@ contiguous memory. Once the SMC is handled, BL1 returns from exception to the normal world caller. FWU_SMC_IMAGE_AUTH -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ :: @@ -279,7 +375,7 @@ sets the image state to AUTHENTICATED. If authentication fails then BL1 returns the -EAUTH error and sets the image state back to RESET. FWU_SMC_IMAGE_EXECUTE -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ :: @@ -307,7 +403,7 @@ BL1 saves the normal world caller's context, sets the secure image state to EXECUTED, and returns from exception to the secure image. FWU_SMC_IMAGE_RESUME -~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^ :: @@ -334,7 +430,7 @@ the resuming world. If the call is successful then the caller provided returned to the caller. FWU_SMC_SEC_IMAGE_DONE -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ :: @@ -355,7 +451,7 @@ restores the normal world context and returns from exception into the normal world. FWU_SMC_UPDATE_DONE -~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^ :: @@ -371,7 +467,7 @@ function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` a ``void *``. The SMC does not return. FWU_SMC_IMAGE_RESET -~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^ :: @@ -393,8 +489,9 @@ This is only allowed if the image is not being executed. -------------- -*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2015-2022, Arm Limited and Contributors. All rights reserved.* .. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt .. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png .. |FWU state machine| image:: ../resources/diagrams/fwu_states.png +.. _PSA FW update specification: https://developer.arm.com/documentation/den0118/a/ diff --git a/docs/components/index.rst b/docs/components/index.rst index 2f81f23f2..30d80fcdd 100644 --- a/docs/components/index.rst +++ b/docs/components/index.rst @@ -4,7 +4,6 @@ Components .. toctree:: :maxdepth: 1 :caption: Contents - :numbered: spd/index activity-monitors @@ -20,8 +19,10 @@ Components romlib-design sdei secure-partition-manager + el3-spmc secure-partition-manager-mm xlat-tables-lib-v2-design cot-binding realm-management-extension + rmm-el3-comms-spec granule-protection-tables-design diff --git a/docs/components/ras.rst b/docs/components/ras.rst index 02207d8b7..871be2d76 100644 --- a/docs/components/ras.rst +++ b/docs/components/ras.rst @@ -6,10 +6,11 @@ Serviceability (RAS) extensions. RAS is a mandatory extension for Armv8.2 and later CPUs, and also an optional extension to the base Armv8.0 architecture. In conjunction with the |EHF|, support for RAS extension enables firmware-first -paradigm for handling platform errors: exceptions resulting from errors are -routed to and handled in EL3. Said errors are Synchronous External Abort (SEA), -Asynchronous External Abort (signalled as SErrors), Fault Handling and Error -Recovery interrupts. The |EHF| document mentions various :ref:`error handling +paradigm for handling platform errors: exceptions resulting from errors in +Non-secure world are routed to and handled in EL3. +Said errors are Synchronous External Abort (SEA), Asynchronous External Abort +(signalled as SErrors), Fault Handling and Error Recovery interrupts. +The |EHF| document mentions various :ref:`error handling use-cases <delegation-use-cases>` . For the description of Arm RAS extensions, Standard Error Records, and the @@ -29,9 +30,9 @@ introduced by the RAS extensions. .. __: `Standard Error Record helpers`_ The build option ``RAS_EXTENSION`` when set to ``1`` includes the RAS in run -time firmware; ``EL3_EXCEPTION_HANDLING`` and ``HANDLE_EA_EL3_FIRST`` must also -be set ``1``. ``RAS_TRAP_LOWER_EL_ERR_ACCESS`` controls the access to the RAS -error record registers from lower ELs. +time firmware; ``EL3_EXCEPTION_HANDLING`` and ``HANDLE_EA_EL3_FIRST_NS`` must also +be set ``1``. ``RAS_TRAP_NS_ERR_REC_ACCESS`` controls the access to the RAS +error record registers from Non-secure. .. _ras-figure: @@ -198,8 +199,8 @@ related, build options: - ``EL3_EXCEPTION_HANDLING=1`` enables handling of exceptions at EL3. See `Interaction with Exception Handling Framework`_; -- ``HANDLE_EA_EL3_FIRST=1`` enables routing of External Aborts and SErrors to - EL3. +- ``HANDLE_EA_EL3_FIRST_NS=1`` enables routing of External Aborts and SErrors, + resulting from errors in NS world, to EL3. The RAS support in |TF-A| introduces a default implementation of ``plat_ea_handler``, the External Abort handler in EL3. When ``RAS_EXTENSION`` diff --git a/docs/components/realm-management-extension.rst b/docs/components/realm-management-extension.rst index 5fa51400d..6fc0c2e25 100644 --- a/docs/components/realm-management-extension.rst +++ b/docs/components/realm-management-extension.rst @@ -73,6 +73,14 @@ RMMD is a new standard runtime service that handles the switch to the Realm world. It initializes the RMM and handles Realm Management Interface (RMI) SMC calls from Non-secure and Realm worlds. +There is a contract between RMM and RMMD that defines the arguments that the +former needs to take in order to initialize and also the possible return values. +This contract is defined in the RMM Boot Interface, which can be found at +:ref:`rmm_el3_boot_interface`. + +There is also a specification of the runtime services provided by TF-A +to RMM. This can be found at :ref:`runtime_services_and_interface`. + Test Realm Payload (TRP) ************************* TRP is a small test payload that runs at R-EL2 and implements a subset of @@ -87,66 +95,218 @@ Building and running TF-A with RME This section describes how you can build and run TF-A with RME enabled. We assume you have all the :ref:`Prerequisites` to build TF-A. -To enable RME, you need to set the ENABLE_RME build flag when building -TF-A. Currently, this feature is only supported for the FVP platform. - The following instructions show you how to build and run TF-A with RME -for two scenarios: TF-A with TF-A Tests, and four-world execution with -Hafnium and TF-A Tests. The instructions assume you have already obtained -TF-A. You can use the following command to clone TF-A. +for two scenarios: -.. code:: shell +- Three-world execution: TF-A with TF-A Tests or Linux. - git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git + - NS (TF-A Test or Linux), + - Root (TF-A) + - Realm (RMM or TRP) + +- Four-world execution: TF-A, Hafnium and TF-A Tests or Linux. + + - NS (TF-A Test or Linux), + - Root (TF-A) + - Realm (RMM or TRP) + - SPM (Hafnium) To run the tests, you need an FVP model. Please use the :ref:`latest version <Arm Fixed Virtual Platforms (FVP)>` of *FVP_Base_RevC-2xAEMvA* model. -.. note:: +Three World Testing with TF-A Tests +************************************* - ENABLE_RME build option is currently experimental. +**1. Obtain and build TF-A Tests with Realm Payload** + +The full set of instructions to setup build host and build options for +TF-A-Tests can be found in the `TFTF Getting Started`_. -Building TF-A with TF-A Tests -******************************************** Use the following instructions to build TF-A with `TF-A Tests`_ as the non-secure payload (BL33). -**1. Obtain and build TF-A Tests** - .. code:: shell git clone https://git.trustedfirmware.org/TF-A/tf-a-tests.git cd tf-a-tests - make CROSS_COMPILE=aarch64-none-elf- PLAT=fvp DEBUG=1 + make CROSS_COMPILE=aarch64-none-elf- PLAT=fvp DEBUG=1 all pack_realm -This produces a TF-A Tests binary (*tftf.bin*) in the *build/fvp/debug* directory. +This produces a TF-A Tests binary (**tftf.bin**) with Realm payload packaged +and **sp_layout.json** in the **build/fvp/debug** directory. -**2. Build TF-A** +**2. Obtain and build RMM Image** + +Please refer to the `RMM Getting Started`_ on how to setup +Host Environment and build RMM. + +The below command shows how to build RMM using the default build options for FVP. + +.. code:: shell + + git clone --recursive https://git.trustedfirmware.org/TF-RMM/tf-rmm.git + cd tf-rmm + cmake -DRMM_CONFIG=fvp_defcfg -S . -B build + cmake --build build + +This will generate **rmm.img** in **build** folder. + +**3. Build TF-A** + +The `TF-A Getting Started`_ has the necessary instructions to setup Host +machine and build TF-A. + +To build for RME, set ``ENABLE_RME`` build option to 1 and provide the path to +the RMM binary using the ``RMM`` build option. +Currently, this feature is only supported for the FVP platform. + +.. note:: + + ENABLE_RME build option is currently experimental. + +If the ``RMM`` option is not used, then the Test Realm Payload (TRP) in TF-A +will be built and used as the RMM. .. code:: shell + git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git cd trusted-firmware-a make CROSS_COMPILE=aarch64-none-elf- \ PLAT=fvp \ ENABLE_RME=1 \ + RMM=<path/to/rmm.img> \ FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ DEBUG=1 \ BL33=<path/to/tftf.bin> \ all fip -This produces *bl1.bin* and *fip.bin* binaries in the *build/fvp/debug* directory. -The above command also builds TRP. The TRP binary is packaged in *fip.bin*. +This produces **bl1.bin** and **fip.bin** binaries in the **build/fvp/debug** directory. + +Running the tests for a 3 world FVP setup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use the following command to run the tests on FVP. TF-A Tests should boot +and run the default tests including Realm world tests. + +.. code:: shell + + FVP_Base_RevC-2xAEMvA \ + -C bp.refcounter.non_arch_start_at_default=1 \ + -C bp.secureflashloader.fname=<path/to/bl1.bin> \ + -C bp.flashloader0.fname=<path/to/fip.bin> \ + -C bp.refcounter.use_real_time=0 \ + -C bp.ve_sysregs.exit_on_shutdown=1 \ + -C cache_state_modelled=1 \ + -C bp.dram_size=2 \ + -C bp.secure_memory=1 \ + -C pci.pci_smmuv3.mmu.SMMU_ROOT_IDR0=3 \ + -C pci.pci_smmuv3.mmu.SMMU_ROOT_IIDR=0x43B \ + -C pci.pci_smmuv3.mmu.root_register_page_offset=0x20000 \ + -C cluster0.NUM_CORES=4 \ + -C cluster0.PA_SIZE=48 \ + -C cluster0.ecv_support_level=2 \ + -C cluster0.gicv3.cpuintf-mmap-access-level=2 \ + -C cluster0.gicv3.without-DS-support=1 \ + -C cluster0.gicv4.mask-virtual-interrupt=1 \ + -C cluster0.has_arm_v8-6=1 \ + -C cluster0.has_amu=1 \ + -C cluster0.has_branch_target_exception=1 \ + -C cluster0.rme_support_level=2 \ + -C cluster0.has_rndr=1 \ + -C cluster0.has_v8_7_pmu_extension=2 \ + -C cluster0.max_32bit_el=-1 \ + -C cluster0.stage12_tlb_size=1024 \ + -C cluster0.check_memory_attributes=0 \ + -C cluster0.ish_is_osh=1 \ + -C cluster0.restriction_on_speculative_execution=2 \ + -C cluster0.restriction_on_speculative_execution_aarch32=2 \ + -C cluster1.NUM_CORES=4 \ + -C cluster1.PA_SIZE=48 \ + -C cluster1.ecv_support_level=2 \ + -C cluster1.gicv3.cpuintf-mmap-access-level=2 \ + -C cluster1.gicv3.without-DS-support=1 \ + -C cluster1.gicv4.mask-virtual-interrupt=1 \ + -C cluster1.has_arm_v8-6=1 \ + -C cluster1.has_amu=1 \ + -C cluster1.has_branch_target_exception=1 \ + -C cluster1.rme_support_level=2 \ + -C cluster1.has_rndr=1 \ + -C cluster1.has_v8_7_pmu_extension=2 \ + -C cluster1.max_32bit_el=-1 \ + -C cluster1.stage12_tlb_size=1024 \ + -C cluster1.check_memory_attributes=0 \ + -C cluster1.ish_is_osh=1 \ + -C cluster1.restriction_on_speculative_execution=2 \ + -C cluster1.restriction_on_speculative_execution_aarch32=2 \ + -C pctl.startup=0.0.0.0 \ + -C bp.smsc_91c111.enabled=1 \ + -C bp.hostbridge.userNetworking=1 + +The bottom of the output from *uart0* should look something like the following. + +.. code-block:: shell + + ... + + > Test suite 'FF-A Interrupt' + Passed + > Test suite 'SMMUv3 tests' + Passed + > Test suite 'PMU Leakage' + Passed + > Test suite 'DebugFS' + Passed + > Test suite 'RMI and SPM tests' + Passed + > Test suite 'Realm payload at EL1' + Passed + > Test suite 'Invalid memory access' + Passed + ... + +Building TF-A with RME enabled Linux Kernel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If an RME enabled Linux kernel and filesystem is available for testing, +and a suitable NS boot loader is not available, then this option can be used to +launch kernel directly after BL31: + +.. code-block:: shell + + cd trusted-firmware-a + make CROSS_COMPILE=aarch64-none-elf- \ + PLAT=fvp \ + ENABLE_RME=1 \ + RMM=<path/to/rmm.img> \ + FVP_HW_CONFIG_DTS=fdts/fvp-base-gicv3-psci-1t.dts \ + DEBUG=1 \ + ARM_LINUX_KERNEL_AS_BL33=1 \ + PRELOADED_BL33_BASE=0x84000000 \ + all fip + +Boot and run the RME enabled Linux Kernel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use the following additional arguments to boot the kernel on FVP. + +.. code-block:: shell + + --data cluster0.cpu0=<path_to_kernel_Image>@0x84000000 \ + -C bp.virtioblockdevice.image_path=<path_to_rootfs.ext4> + +.. tip:: + + Set the FVP option `cache_state_modelled=0` to run Linux based tests much faster. Four-world execution with Hafnium and TF-A Tests -**************************************************** -Four-world execution involves software components at each security state: root, +************************************************* + +Four-world execution involves software components in each security state: root, secure, realm and non-secure. This section describes how to build TF-A -with four-world support. We use TF-A as the root firmware, `Hafnium`_ as the -secure component, TRP as the realm-world firmware and TF-A Tests as the -non-secure payload. +with four-world support. -Before building TF-A, you first need to build the other software components. -You can find instructions on how to get and build TF-A Tests above. +We use TF-A as the root firmware, `Hafnium SPM`_ is the reference Secure world component +and the software components for the other 2 worlds (Realm and Non-Secure) +are as described in the previous section. **1. Obtain and build Hafnium** @@ -156,6 +316,27 @@ You can find instructions on how to get and build TF-A Tests above. cd hafnium # Use the default prebuilt LLVM/clang toolchain PATH=$PWD/prebuilts/linux-x64/clang/bin:$PWD/prebuilts/linux-x64/dtc:$PATH + +Feature MTE needs to be disabled in Hafnium build, apply following patch to +project/reference submodule + +.. code:: diff + + diff --git a/BUILD.gn b/BUILD.gn + index cc6a78f..234b20a 100644 + --- a/BUILD.gn + +++ b/BUILD.gn + @@ -83,7 +83,6 @@ aarch64_toolchains("secure_aem_v8a_fvp") { + pl011_base_address = "0x1c090000" + smmu_base_address = "0x2b400000" + smmu_memory_size = "0x100000" + - enable_mte = "1" + plat_log_level = "LOG_LEVEL_INFO" + } + } + +.. code:: shell + make PROJECT=reference The Hafnium binary should be located at @@ -165,6 +346,8 @@ The Hafnium binary should be located at Build TF-A with RME as well as SPM enabled. +Use sp_layout.json previously generated in tf-a-test build. + .. code:: shell make CROSS_COMPILE=aarch64-none-elf- \ @@ -176,92 +359,33 @@ Build TF-A with RME as well as SPM enabled. BRANCH_PROTECTION=1 \ CTX_INCLUDE_PAUTH_REGS=1 \ DEBUG=1 \ - SP_LAYOUT_FILE=<path/to/tf-a-tests>/build/fvp/debug/sp_layout.json> \ + SP_LAYOUT_FILE=<path/to/sp_layout.json> \ BL32=<path/to/hafnium.bin> \ BL33=<path/to/tftf.bin> \ + RMM=<path/to/rmm.img> \ all fip -Running the tests -********************* -Use the following command to run the tests on FVP. TF-A Tests should boot -and run the default tests including RME tests. +Running the tests for a 4 world FVP setup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code:: shell - - FVP_Base_RevC-2xAEMvA \ - -C bp.flashloader0.fname=<path/to/fip.bin> \ - -C bp.secureflashloader.fname=<path/to/bl1.bin> \ - -C bp.refcounter.non_arch_start_at_default=1 \ - -C bp.refcounter.use_real_time=0 \ - -C bp.ve_sysregs.exit_on_shutdown=1 \ - -C cache_state_modelled=1 \ - -C cluster0.NUM_CORES=4 \ - -C cluster0.PA_SIZE=48 \ - -C cluster0.ecv_support_level=2 \ - -C cluster0.gicv3.cpuintf-mmap-access-level=2 \ - -C cluster0.gicv3.without-DS-support=1 \ - -C cluster0.gicv4.mask-virtual-interrupt=1 \ - -C cluster0.has_arm_v8-6=1 \ - -C cluster0.has_branch_target_exception=1 \ - -C cluster0.has_rme=1 \ - -C cluster0.has_rndr=1 \ - -C cluster0.has_amu=1 \ - -C cluster0.has_v8_7_pmu_extension=2 \ - -C cluster0.max_32bit_el=-1 \ - -C cluster0.restriction_on_speculative_execution=2 \ - -C cluster0.restriction_on_speculative_execution_aarch32=2 \ - -C cluster1.NUM_CORES=4 \ - -C cluster1.PA_SIZE=48 \ - -C cluster1.ecv_support_level=2 \ - -C cluster1.gicv3.cpuintf-mmap-access-level=2 \ - -C cluster1.gicv3.without-DS-support=1 \ - -C cluster1.gicv4.mask-virtual-interrupt=1 \ - -C cluster1.has_arm_v8-6=1 \ - -C cluster1.has_branch_target_exception=1 \ - -C cluster1.has_rme=1 \ - -C cluster1.has_rndr=1 \ - -C cluster1.has_amu=1 \ - -C cluster1.has_v8_7_pmu_extension=2 \ - -C cluster1.max_32bit_el=-1 \ - -C cluster1.restriction_on_speculative_execution=2 \ - -C cluster1.restriction_on_speculative_execution_aarch32=2 \ - -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=0xFFFF0475 \ - -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 bp.pl011_uart0.out_file=uart0.log \ - -C bp.pl011_uart1.out_file=uart1.log \ - -C bp.pl011_uart2.out_file=uart2.log \ - -C pctl.startup=0.0.0.0 \ - -Q 1000 \ - "$@" +Use the following arguments in addition to +`Running the tests for a 3 world FVP setup`_ to run tests for 4 world setup. -The bottom of the output from *uart0* should look something like the following. - -.. code-block:: shell - - ... - - > Test suite 'FF-A Interrupt' - Passed - > Test suite 'SMMUv3 tests' - Passed - > Test suite 'PMU Leakage' - Passed - > Test suite 'DebugFS' - Passed - > Test suite 'Realm payload tests' - Passed - > Test suite 'Invalid memory access' - Passed - ... +.. code:: shell + -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=0xFFFF0475 \ + -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 .. _Arm Confidential Compute Architecture (Arm CCA): https://www.arm.com/why-arm/architecture/security-features/arm-confidential-compute-architecture .. _Arm Architecture Models website: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models +.. _TF-A Getting Started: https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/index.html .. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io/en/latest -.. _Hafnium: https://www.trustedfirmware.org/projects/hafnium +.. _TFTF Getting Started: https://trustedfirmware-a-tests.readthedocs.io/en/latest/getting_started/index.html +.. _Hafnium SPM: https://www.trustedfirmware.org/projects/hafnium +.. _RMM Getting Started: https://git.trustedfirmware.org/TF-RMM/tf-rmm.git/tree/docs/getting_started/index.rst diff --git a/docs/components/rmm-el3-comms-spec.rst b/docs/components/rmm-el3-comms-spec.rst new file mode 100644 index 000000000..8070ff446 --- /dev/null +++ b/docs/components/rmm-el3-comms-spec.rst @@ -0,0 +1,543 @@ +RMM-EL3 Communication interface +******************************* + +This document defines the communication interface between RMM and EL3. +There are two parts in this interface: the boot interface and the runtime +interface. + +The Boot Interface defines the ABI between EL3 and RMM when the CPU enters +R-EL2 for the first time after boot. The cold boot interface defines the ABI +for the cold boot path and the warm boot interface defines the same for the +warm path. + +The RMM-EL3 runtime interface defines the ABI for EL3 services which can be +invoked by RMM as well as the register save-restore convention when handling an +SMC call from NS. + +The below sections discuss these interfaces more in detail. + +.. _rmm_el3_ifc_versioning: + +RMM-EL3 Interface versioning +____________________________ + +The RMM Boot and Runtime Interface uses a version number to check +compatibility with the register arguments passed as part of Boot Interface and +RMM-EL3 runtime interface. + +The Boot Manifest, discussed later in section :ref:`rmm_el3_boot_manifest`, +uses a separate version number but with the same scheme. + +The version number is a 32-bit type with the following fields: + +.. csv-table:: + :header: "Bits", "Value" + + [0:15],``VERSION_MINOR`` + [16:30],``VERSION_MAJOR`` + [31],RES0 + +The version numbers are sequentially increased and the rules for updating them +are explained below: + + - ``VERSION_MAJOR``: This value is increased when changes break + compatibility with previous versions. If the changes + on the ABI are compatible with the previous one, ``VERSION_MAJOR`` + remains unchanged. + + - ``VERSION_MINOR``: This value is increased on any change that is backwards + compatible with the previous version. When ``VERSION_MAJOR`` is increased, + ``VERSION_MINOR`` must be set to 0. + + - ``RES0``: Bit 31 of the version number is reserved 0 as to maintain + consistency with the versioning schemes used in other parts of RMM. + +This document specifies the 0.1 version of Boot Interface ABI and RMM-EL3 +services specification and the 0.1 version of the Boot Manifest. + +.. _rmm_el3_boot_interface: + +RMM Boot Interface +__________________ + +This section deals with the Boot Interface part of the specification. + +One of the goals of the Boot Interface is to allow EL3 firmware to pass +down into RMM certain platform specific information dynamically. This allows +RMM to be less platform dependent and be more generic across platform +variations. It also allows RMM to be decoupled from the other boot loader +images in the boot sequence and remain agnostic of any particular format used +for configuration files. + +The Boot Interface ABI defines a set of register conventions and +also a memory based manifest file to pass information from EL3 to RMM. The +boot manifest and the associated platform data in it can be dynamically created +by EL3 and there is no restriction on how the data can be obtained (e.g by DTB, +hoblist or other). + +The register convention and the manifest are versioned separately to manage +future enhancements and compatibility. + +RMM completes the boot by issuing the ``RMM_BOOT_COMPLETE`` SMC (0xC40001CF) +back to EL3. After the RMM has finished the boot process, it can only be +entered from EL3 as part of RMI handling. + +If RMM returns an error during boot (in any CPU), then RMM must not be entered +from any CPU. + +.. _rmm_cold_boot_interface: + +Cold Boot Interface +~~~~~~~~~~~~~~~~~~~ + +During cold boot RMM expects the following register values: + +.. csv-table:: + :header: "Register", "Value" + :widths: 1, 5 + + x0,Linear index of this PE. This index starts from 0 and must be less than the maximum number of CPUs to be supported at runtime (see x2). + x1,Version for this Boot Interface as defined in :ref:`rmm_el3_ifc_versioning`. + x2,Maximum number of CPUs to be supported at runtime. RMM should ensure that it can support this maximum number. + x3,Base address for the shared buffer used for communication between EL3 firmware and RMM. This buffer must be of 4KB size (1 page). The boot manifest must be present at the base of this shared buffer during cold boot. + +During cold boot, EL3 firmware needs to allocate a 4K page that will be +passed to RMM in x3. This memory will be used as shared buffer for communication +between EL3 and RMM. It must be assigned to Realm world and must be mapped with +Normal memory attributes (IWB-OWB-ISH) at EL3. At boot, this memory will be +used to populate the Boot Manifest. Since the Boot Manifest can be accessed by +RMM prior to enabling its MMU, EL3 must ensure that proper cache maintenance +operations are performed after the Boot Manifest is populated. + +EL3 should also ensure that this shared buffer is always available for use by RMM +during the lifetime of the system and that it can be used for runtime +communication between RMM and EL3. For example, when RMM invokes attestation +service commands in EL3, this buffer can be used to exchange data between RMM +and EL3. It is also allowed for RMM to invoke runtime services provided by EL3 +utilizing this buffer during the boot phase, prior to return back to EL3 via +RMM_BOOT_COMPLETE SMC. + +RMM should map this memory page into its Stage 1 page-tables using Normal +memory attributes. + +During runtime, it is the RMM which initiates any communication with EL3. If that +communication requires the use of the shared area, it is expected that RMM needs +to do the necessary concurrency protection to prevent the use of the same buffer +by other PEs. + +The following sequence diagram shows how a generic EL3 Firmware would boot RMM. + +.. image:: ../resources/diagrams/rmm_cold_boot_generic.png + +Warm Boot Interface +~~~~~~~~~~~~~~~~~~~ + +At warm boot, RMM is already initialized and only some per-CPU initialization +is still pending. The only argument that is required by RMM at this stage is +the CPU Id, which will be passed through register x0 whilst x1 to x3 are RES0. +This is summarized in the following table: + +.. csv-table:: + :header: "Register", "Value" + :widths: 1, 5 + + x0,Linear index of this PE. This index starts from 0 and must be less than the maximum number of CPUs to be supported at runtime (see x2). + x1 - x3,RES0 + +Boot error handling and return values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After boot up and initialization, RMM returns control back to EL3 through a +``RMM_BOOT_COMPLETE`` SMC call. The only argument of this SMC call will +be returned in x1 and it will encode a signed integer with the error reason +as per the following table: + +.. csv-table:: + :header: "Error code", "Description", "ID" + :widths: 2 4 1 + + ``E_RMM_BOOT_SUCCESS``,Boot successful,0 + ``E_RMM_BOOT_ERR_UNKNOWN``,Unknown error,-1 + ``E_RMM_BOOT_VERSION_NOT_VALID``,Boot Interface version reported by EL3 is not supported by RMM,-2 + ``E_RMM_BOOT_CPUS_OUT_OF_RAGE``,Number of CPUs reported by EL3 larger than maximum supported by RMM,-3 + ``E_RMM_BOOT_CPU_ID_OUT_OF_RAGE``,Current CPU Id is higher or equal than the number of CPUs supported by RMM,-4 + ``E_RMM_BOOT_INVALID_SHARED_BUFFER``,Invalid pointer to shared memory area,-5 + ``E_RMM_BOOT_MANIFEST_VERSION_NOT_SUPPORTED``,Version reported by the boot manifest not supported by RMM,-6 + ``E_RMM_BOOT_MANIFEST_DATA_ERROR``,Error parsing core boot manifest,-7 + +For any error detected in RMM during cold or warm boot, RMM will return back to +EL3 using ``RMM_BOOT_COMPLETE`` SMC with an appropriate error code. It is +expected that EL3 will take necessary action to disable Realm world for further +entry from NS Host on receiving an error. This will be done across all the PEs +in the system so as to present a symmetric view to the NS Host. Any further +warm boot by any PE should not enter RMM using the warm boot interface. + +.. _rmm_el3_boot_manifest: + +Boot Manifest +~~~~~~~~~~~~~ + +During cold boot, EL3 Firmware passes a memory boot manifest to RMM containing +platform information. + +This boot manifest is versioned independently of the boot interface, to help +evolve the boot manifest independent of the rest of Boot Manifest. +The current version for the boot manifest is ``v0.1`` and the rules explained +in :ref:`rmm_el3_ifc_versioning` apply on this version as well. + +The boot manifest is divided into two different components: + + - Core Manifest: This is the generic parameters passed to RMM by EL3 common to all platforms. + - Platform data: This is defined by the platform owner and contains information specific to that platform. + +For the current version of the manifest, the core manifest contains a pointer +to the platform data. EL3 must ensure that the whole boot manifest, +including the platform data, if available, fits inside the RMM EL3 shared +buffer. + +For the type specification of the RMM Boot Manifest v0.1, refer to +:ref:`rmm_el3_manifest_struct` + +.. _runtime_services_and_interface: + +RMM-EL3 Runtime Interface +__________________________ + +This section defines the RMM-EL3 runtime interface which specifies the ABI for +EL3 services expected by RMM at runtime as well as the register save and +restore convention between EL3 and RMM as part of RMI call handling. It is +important to note that RMM is allowed to invoke EL3-RMM runtime interface +services during the boot phase as well. The EL3 runtime service handling must +not result in a world switch to another world unless specified. Both the RMM +and EL3 are allowed to make suitable optimizations based on this assumption. + +If the interface requires the use of memory, then the memory references should +be within the shared buffer communicated as part of the boot interface. See +:ref:`rmm_cold_boot_interface` for properties of this shared buffer which both +EL3 and RMM must adhere to. + +RMM-EL3 runtime service return codes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The return codes from EL3 to RMM is a 32 bit signed integer which encapsulates +error condition as described in the following table: + +.. csv-table:: + :header: "Error code", "Description", "ID" + :widths: 2 4 1 + + ``E_RMM_OK``,No errors detected,0 + ``E_RMM_UNK``,Unknown/Generic error,-1 + ``E_RMM_BAD_ADDR``,The value of an address used as argument was invalid,-2 + ``E_RMM_BAD_PAS``,Incorrect PAS,-3 + ``E_RMM_NOMEM``,Not enough memory to perform an operation,-4 + ``E_RMM_INVAL``,The value of an argument was invalid,-5 + +If multiple failure conditions are detected in an RMM to EL3 command, then EL3 +is allowed to return an error code corresponding to any of the failure +conditions. + +RMM-EL3 runtime services +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following table summarizes the RMM runtime services that need to be +implemented by EL3 Firmware. + +.. csv-table:: + :header: "FID", "Command" + :widths: 2 5 + + 0xC400018F,``RMM_RMI_REQ_COMPLETE`` + 0xC40001B0,``RMM_GTSI_DELEGATE`` + 0xC40001B1,``RMM_GTSI_UNDELEGATE`` + 0xC40001B2,``RMM_ATTEST_GET_REALM_KEY`` + 0xC40001B3,``RMM_ATTEST_GET_PLAT_TOKEN`` + +RMM_RMI_REQ_COMPLETE command +============================ + +Notifies the completion of an RMI call to the Non-Secure world. + +This call is the only function currently in RMM-EL3 runtime interface which +results in a world switch to NS. This call is the reply to the original RMI +call and it is forwarded by EL3 to the NS world. + +FID +--- + +``0xC400018F`` + +Input values +------------ + +.. csv-table:: + :header: "Name", "Register", "Field", "Type", "Description" + :widths: 1 1 1 1 5 + + fid,x0,[63:0],UInt64,Command FID + err_code,x1,[63:0],RmiCommandReturnCode,Error code returned by the RMI service invoked by NS World. See Realm Management Monitor specification for more info + +Output values +------------- + +This call does not return. + +Failure conditions +------------------ + +Since this call does not return to RMM, there is no failure condition which +can be notified back to RMM. + +RMM_GTSI_DELEGATE command +========================= + +Delegate a memory granule by changing its PAS from Non-Secure to Realm. + +FID +--- + +``0xC40001B0`` + +Input values +------------ + +.. csv-table:: + :header: "Name", "Register", "Field", "Type", "Description" + :widths: 1 1 1 1 5 + + fid,x0,[63:0],UInt64,Command FID + base_pa,x1,[63:0],Address,PA of the start of the granule to be delegated + +Output values +------------- + +.. csv-table:: + :header: "Name", "Register", "Field", "Type", "Description" + :widths: 1 1 1 2 4 + + Result,x0,[63:0],Error Code,Command return status + +Failure conditions +------------------ + +The table below shows all the possible error codes returned in ``Result`` upon +a failure. The errors are ordered by condition check. + +.. csv-table:: + :header: "ID", "Condition" + :widths: 1 5 + + ``E_RMM_BAD_ADDR``,``PA`` does not correspond to a valid granule address + ``E_RMM_BAD_PAS``,The granule pointed by ``PA`` does not belong to Non-Secure PAS + ``E_RMM_OK``,No errors detected + +RMM_GTSI_UNDELEGATE command +=========================== + +Undelegate a memory granule by changing its PAS from Realm to Non-Secure. + +FID +--- + +``0xC40001B1`` + +Input values +------------ + +.. csv-table:: + :header: "Name", "Register", "Field", "Type", "Description" + :widths: 1 1 1 1 5 + + fid,x0,[63:0],UInt64,Command FID + base_pa,x1,[63:0],Address,PA of the start of the granule to be undelegated + +Output values +------------- + +.. csv-table:: + :header: "Name", "Register", "Field", "Type", "Description" + :widths: 1 1 1 2 4 + + Result,x0,[63:0],Error Code,Command return status + +Failure conditions +------------------ + +The table below shows all the possible error codes returned in ``Result`` upon +a failure. The errors are ordered by condition check. + +.. csv-table:: + :header: "ID", "Condition" + :widths: 1 5 + + ``E_RMM_BAD_ADDR``,``PA`` does not correspond to a valid granule address + ``E_RMM_BAD_PAS``,The granule pointed by ``PA`` does not belong to Realm PAS + ``E_RMM_OK``,No errors detected + +RMM_ATTEST_GET_REALM_KEY command +================================ + +Retrieve the Realm Attestation Token Signing key from EL3. + +FID +--- + +``0xC40001B2`` + +Input values +------------ + +.. csv-table:: + :header: "Name", "Register", "Field", "Type", "Description" + :widths: 1 1 1 1 5 + + fid,x0,[63:0],UInt64,Command FID + buf_pa,x1,[63:0],Address,PA where the Realm Attestation Key must be stored by EL3. The PA must belong to the shared buffer + buf_size,x2,[63:0],Size,Size in bytes of the Realm Attestation Key buffer. ``bufPa + bufSize`` must lie within the shared buffer + ecc_curve,x3,[63:0],Enum,Type of the elliptic curve to which the requested attestation key belongs to. See :ref:`ecc_curves` + +Output values +------------- + +.. csv-table:: + :header: "Name", "Register", "Field", "Type", "Description" + :widths: 1 1 1 1 5 + + Result,x0,[63:0],Error Code,Command return status + keySize,x1,[63:0],Size,Size of the Realm Attestation Key + +Failure conditions +------------------ + +The table below shows all the possible error codes returned in ``Result`` upon +a failure. The errors are ordered by condition check. + +.. csv-table:: + :header: "ID", "Condition" + :widths: 1 5 + + ``E_RMM_BAD_ADDR``,``PA`` is outside the shared buffer + ``E_RMM_INVAL``,``PA + BSize`` is outside the shared buffer + ``E_RMM_INVAL``,``Curve`` is not one of the listed in :ref:`ecc_curves` + ``E_RMM_UNK``,An unknown error occurred whilst processing the command + ``E_RMM_OK``,No errors detected + +.. _ecc_curves: + +Supported ECC Curves +-------------------- + +.. csv-table:: + :header: "ID", "Curve" + :widths: 1 5 + + 0,ECC SECP384R1 + +RMM_ATTEST_GET_PLAT_TOKEN command +================================= + +Retrieve the Platform Token from EL3. + +FID +--- + +``0xC40001B3`` + +Input values +------------ + +.. csv-table:: + :header: "Name", "Register", "Field", "Type", "Description" + :widths: 1 1 1 1 5 + + fid,x0,[63:0],UInt64,Command FID + buf_pa,x1,[63:0],Address,PA of the platform attestation token. The challenge object is passed in this buffer. The PA must belong to the shared buffer + buf_size,x2,[63:0],Size,Size in bytes of the platform attestation token buffer. ``bufPa + bufSize`` must lie within the shared buffer + c_size,x3,[63:0],Size,Size in bytes of the challenge object. It corresponds to the size of one of the defined SHA algorithms + +Output values +------------- + +.. csv-table:: + :header: "Name", "Register", "Field", "Type", "Description" + :widths: 1 1 1 1 5 + + Result,x0,[63:0],Error Code,Command return status + tokenSize,x1,[63:0],Size,Size of the platform token + +Failure conditions +------------------ + +The table below shows all the possible error codes returned in ``Result`` upon +a failure. The errors are ordered by condition check. + +.. csv-table:: + :header: "ID", "Condition" + :widths: 1 5 + + ``E_RMM_BAD_ADDR``,``PA`` is outside the shared buffer + ``E_RMM_INVAL``,``PA + BSize`` is outside the shared buffer + ``E_RMM_INVAL``,``CSize`` does not represent the size of a supported SHA algorithm + ``E_RMM_UNK``,An unknown error occurred whilst processing the command + ``E_RMM_OK``,No errors detected + +RMM-EL3 world switch register save restore convention +_____________________________________________________ + +As part of NS world switch, EL3 is expected to maintain a register context +specific to each world and will save and restore the registers +appropriately. This section captures the contract between EL3 and RMM on the +register set to be saved and restored. + +EL3 must maintain a separate register context for the following: + + #. General purpose registers (x0-x30) and ``sp_el0``, ``sp_el2`` stack pointers + #. EL2 system register context for all enabled features by EL3. These include system registers with the ``_EL2`` prefix. The EL2 physical and virtual timer registers must not be included in this. + +As part of SMC forwarding between the NS world and Realm world, EL3 allows x0-x7 to be passed +as arguments to Realm and x0-x4 to be used for return arguments back to Non Secure. +As per SMCCCv1.2, x4 must be preserved if not being used as return argument by the SMC function +and it is the responsibility of RMM to preserve this or use this as a return argument. +EL3 will always copy x0-x4 from Realm context to NS Context. + +EL3 will not save some registers as mentioned in the below list. It is the +responsibility of RMM to ensure that these are appropriately saved if the +Realm World makes use of them: + + #. FP/SIMD registers + #. SVE registers + #. SME registers + #. EL1/0 registers + +It is the responsibility of EL3 that any other registers other than the ones mentioned above +will not be leaked to the NS Host and to maintain the confidentiality of the Realm World. + +SMCCC v1.3 allows NS world to specify whether SVE context is in use. In this +case, RMM could choose to not save the incoming SVE context but must ensure +to clear SVE registers if they have been used in Realm World. The same applies +to SME registers. + +Types +_____ + +.. _rmm_el3_manifest_struct: + +RMM-EL3 Boot Manifest Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The RMM-EL3 Boot Manifest structure contains platform boot information passed +from EL3 to RMM. The width of the Boot Manifest is 128 bits + +.. image:: ../resources/diagrams/rmm_el3_manifest_struct.png + +The members of the RMM-EL3 Boot Manifest structure are shown in the following +table: + +.. csv-table:: + :header: "Name", "Range", "Type", Description + :widths: 2 1 1 4 + + ``Version Minor``,15:0,uint16_t,Version Minor part of the Boot Manifest Version. + ``Version Major``,30:16,uint16_t,Version Major part of the Boot Manifest Version. + ``RES0``,31,bit,Reserved. Set to 0. + ``Platform Data``,127:64,Address,Pointer to the Platform Data section of the Boot Manifest. diff --git a/docs/components/secure-partition-manager.rst b/docs/components/secure-partition-manager.rst index 18d870bdc..cd439ad6f 100644 --- a/docs/components/secure-partition-manager.rst +++ b/docs/components/secure-partition-manager.rst @@ -794,6 +794,8 @@ As part of the FF-A v1.1 support, the following interfaces were added: - ``FFA_SECONDARY_EP_REGISTER`` - ``FFA_MEM_PERM_GET`` - ``FFA_MEM_PERM_SET`` + - ``FFA_MSG_SEND2`` + - ``FFA_RX_ACQUIRE`` FFA_VERSION ~~~~~~~~~~~ @@ -827,7 +829,11 @@ regime as secure buffers in the MMU descriptors. 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. +descriptors. The provided addresses may be owned by a VM in the normal world, +which is expected to receive messages from the secure world. The SPMC will in +this case allocate internal state structures to facilitate RX buffer access +synchronization (through FFA_RX_ACQUIRE interface), and to permit SPs to send +messages. The FFA_RXTX_UNMAP unmaps the RX/TX pair from the translation regime of the caller, either it being the Hypervisor or OS kernel, as well as a secure @@ -969,6 +975,53 @@ secondary execution contexts. A secondary EC is first resumed either upon invocation of PSCI_CPU_ON from the NWd or by invocation of FFA_RUN. +FFA_RX_ACQUIRE/FFA_RX_RELEASE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The RX buffers can be used to pass information to an FF-A endpoint in the +following scenarios: + + - When it was targetted by a FFA_MSG_SEND2 invokation from another endpoint. + - Return the result of calling ``FFA_PARTITION_INFO_GET``. + - In a memory share operation, as part of the ``FFA_MEM_RETRIEVE_RESP``, + with the memory descriptor of the shared memory. + +If a normal world VM is expected to exchange messages with secure world, +its RX/TX buffer addresses are forwarded to the SPMC via FFA_RXTX_MAP ABI, +and are from this moment owned by the SPMC. +The hypervisor must call the FFA_RX_ACQUIRE interface before attempting +to use the RX buffer, in any of the aforementioned scenarios. A successful +call to FFA_RX_ACQUIRE transfers ownership of RX buffer to hypervisor, such +that it can be safely used. + +The FFA_RX_RELEASE interface is used after the FF-A endpoint is done with +processing the data received in its RX buffer. If the RX buffer has been +acquired by the hypervisor, the FFA_RX_RELEASE call must be forwarded to +the SPMC to reestablish SPMC's RX ownership. + +An attempt from an SP to send a message to a normal world VM whose RX buffer +was acquired by the hypervisor fails with error code FFA_BUSY, to preserve +the RX buffer integrity. +The operation could then be conducted after FFA_RX_RELEASE. + +FFA_MSG_SEND2 +~~~~~~~~~~~~~ + +Hafnium copies a message from the sender TX buffer into receiver's RX buffer. +For messages from SPs to VMs, operation is only possible if the SPMC owns +the receiver's RX buffer. + +Both receiver and sender need to enable support for indirect messaging, +in their respective partition manifest. The discovery of support +of such feature can be done via FFA_PARTITION_INFO_GET. + +On a successful message send, Hafnium pends an RX buffer full framework +notification for the receiver, to inform it about a message in the RX buffer. + +The handling of framework notifications is similar to that of +global notifications. Binding of these is not necessary, as these are +reserved to be used by the hypervisor or SPMC. + SPMC-SPMD direct requests/responses ----------------------------------- @@ -1009,6 +1062,40 @@ configuration is made part of a vCPU context. For S-EL0 partitions with VHE enabled, a single secure EL2&0 Stage-1 translation regime is used for both Hafnium and the partition. +Schedule modes and SP Call chains +--------------------------------- + +An SP execution context is said to be in SPMC scheduled mode if CPU cycles are +allocated to it by SPMC. Correspondingly, an SP execution context is said to be +in Normal world scheduled mode if CPU cycles are allocated by the normal world. + +A call chain represents all SPs in a sequence of invocations of a direct message +request. When execution on a PE is in the secure state, only a single call chain +that runs in the Normal World scheduled mode can exist. FF-A v1.1 spec allows +any number of call chains to run in the SPMC scheduled mode but the Hafnium +SPMC restricts the number of call chains in SPMC scheduled mode to only one for +keeping the implementation simple. + +Partition runtime models +------------------------ + +The runtime model of an endpoint describes the transitions permitted for an +execution context between various states. These are the four partition runtime +models supported (refer to `[1]`_ section 7): + + - RTM_FFA_RUN: runtime model presented to an execution context that is + allocated CPU cycles through FFA_RUN interface. + - RTM_FFA_DIR_REQ: runtime model presented to an execution context that is + allocated CPU cycles through FFA_MSG_SEND_DIRECT_REQ interface. + - RTM_SEC_INTERRUPT: runtime model presented to an execution context that is + allocated CPU cycles by SPMC to handle a secure interrupt. + - RTM_SP_INIT: runtime model presented to an execution context that is + allocated CPU cycles by SPMC to initialize its state. + +If an endpoint execution context attempts to make an invalid transition or a +valid transition that could lead to a loop in the call chain, SPMC denies the +transition with the help of above runtime models. + Interrupt management -------------------- @@ -1020,44 +1107,58 @@ 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. -Non-secure interrupt handling -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Abbreviations: -The following illustrate the scenarios of non secure physical interrupts trapped -by the SPMC: + - NS-Int: A non-secure physical interrupt. It requires a switch to the normal + world to be handled if it triggers while execution is in secure world. + - Other S-Int: A secure physical interrupt targeted to an SP different from + the one that is currently running. + - Self S-Int: A secure physical interrupt targeted to the SP that is currently + running. -- The SP handles a managed exit operation: +Non-secure interrupt handling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. image:: ../resources/diagrams/ffa-ns-interrupt-handling-managed-exit.png +This section documents the actions supported in SPMC in response to a non-secure +interrupt as per the guidance provided by FF-A v1.1 EAC0 specification. +An SP specifies one of the following actions in its partition manifest: -- The SP is pre-empted without managed exit: + - Non-secure interrupt is signaled. + - Non-secure interrupt is signaled after a managed exit. + - Non-secure interrupt is queued. -.. image:: ../resources/diagrams/ffa-ns-interrupt-handling-sp-preemption.png +An SP execution context in a call chain could specify a less permissive action +than subsequent SP execution contexts in the same call chain. The less +permissive action takes precedence over the more permissive actions specified +by the subsequent execution contexts. Please refer to FF-A v1.1 EAC0 section +8.3.1 for further explanation. Secure interrupt handling -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ This section documents the support implemented for secure interrupt handling in -SPMC as per the guidance provided by FF-A v1.1 Beta0 specification. +SPMC as per the guidance provided by FF-A v1.1 EAC0 specification. The following assumptions are made about the system configuration: - In the current implementation, S-EL1 SPs are expected to use the para - virtualized ABIs for interrupt management rather than accessing virtual GIC - interface. + virtualized ABIs for interrupt management rather than accessing the virtual + GIC interface. - Unless explicitly stated otherwise, this support is applicable only for S-EL1 SPs managed by SPMC. - Secure interrupts are configured as G1S or G0 interrupts. - All physical interrupts are routed to SPMC when running a secure partition execution context. - -A physical secure interrupt could preempt normal world execution. Moreover, when -the execution is in secure world, it is highly likely that the target of a -secure interrupt is not the currently running execution context of an SP. It -could be targeted to another FF-A component. Consequently, secure interrupt -management depends on the state of the target execution context of the SP that -is responsible for handling the interrupt. Hence, the spec provides guidance on -how to signal start and completion of secure interrupt handling as discussed in -further sections. + - All endpoints with multiple execution contexts have their contexts pinned + to corresponding CPUs. Hence, a secure virtual interrupt cannot be signaled + to a target vCPU that is currently running or blocked on a different + physical CPU. + +A physical secure interrupt could trigger while CPU is executing in normal world +or secure world. +The action of SPMC for a secure interrupt depends on: the state of the target +execution context of the SP that is responsible for handling the interrupt; +whether the interrupt triggered while execution was in normal world or secure +world. Secure interrupt signaling mechanisms ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1100,47 +1201,46 @@ following mechanisms: - ``FFA_MSG_WAIT`` ABI if it was in WAITING state. - ``FFA_RUN`` ABI if its was in BLOCKED state. -In the current implementation, S-EL1 SPs use para-virtualized HVC interface -implemented by SPMC to perform priority drop and interrupt deactivation (we -assume EOImode = 0, i.e. priority drop and deactivation are done together). - -If normal world execution was preempted by secure interrupt, SPMC uses +This is a remnant of SPMC implementation based on the FF-A v1.0 specification. +In the current implementation, S-EL1 SPs use the para-virtualized HVC interface +implemented by SPMC to perform priority drop and interrupt deactivation (SPMC +configures EOImode = 0, i.e. priority drop and deactivation are done together). +The SPMC performs checks to deny the state transition upon invocation of +either FFA_MSG_WAIT or FFA_RUN interface if the SP didn't perform the +deactivation of the secure virtual interrupt. + +If the current SP execution context was preempted by a secure interrupt to be +handled by execution context of target SP, SPMC resumes current SP after signal +completion by target SP execution context. + +Actions for a secure interrupt triggered while execution is in normal world +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------------------+----------+-----------------------------------------------+ +| State of target | Action | Description | +| execution context | | | ++-------------------+----------+-----------------------------------------------+ +| WAITING | Signaled | This starts a new call chain in SPMC scheduled| +| | | mode. | ++-------------------+----------+-----------------------------------------------+ +| PREEMPTED | Queued | The target execution must have been preempted | +| | | by a non-secure interrupt. SPMC queues the | +| | | secure virtual interrupt now. It is signaled | +| | | when the target execution context next enters | +| | | the RUNNING state. | ++-------------------+----------+-----------------------------------------------+ +| BLOCKED, RUNNING | NA | The target execution context is blocked or | +| | | running on a different CPU. This is not | +| | | supported by current SPMC implementation and | +| | | execution hits panic. | ++-------------------+----------+-----------------------------------------------+ + +If normal world execution was preempted by a secure interrupt, SPMC uses FFA_NORMAL_WORLD_RESUME ABI to indicate completion of secure interrupt handling -and further return execution to normal world. If the current SP execution -context was preempted by a secure interrupt to be handled by execution context -of target SP, SPMC resumes current SP after signal completion by target SP -execution context. - -An action is broadly a set of steps taken by the SPMC in response to a physical -interrupt. In order to simplify the design, the current version of secure -interrupt management support in SPMC (Hafnium) does not fully implement the -Scheduling models and Partition runtime models. However, the current -implementation loosely maps to the following actions that are legally allowed -by the specification. Please refer to the Table 8.4 in the spec for further -description of actions. The action specified for a type of interrupt when the -SP is in the message processing running state cannot be less permissive than the -action specified for the same type of interrupt when the SP is in the interrupt -handling running state. - -+--------------------+--------------------+------------+-------------+ -| Runtime Model | NS-Int | Self S-Int | Other S-Int | -+--------------------+--------------------+------------+-------------+ -| Message Processing | Signalable with ME | Signalable | Signalable | -+--------------------+--------------------+------------+-------------+ -| Interrupt Handling | Queued | Queued | Queued | -+--------------------+--------------------+------------+-------------+ +and further returns execution to normal world. -Abbreviations: - - - NS-Int: A Non-secure physical interrupt. It requires a switch to the Normal - world to be handled. - - Other S-Int: A secure physical interrupt targeted to an SP different from - the one that is currently running. - - Self S-Int: A secure physical interrupt targeted to the SP that is currently - running. - -The following figure describes interrupt handling flow when secure interrupt -triggers while in normal world: +The following figure describes interrupt handling flow when a secure interrupt +triggers while execution is in normal world: .. image:: ../resources/diagrams/ffa-secure-interrupt-handling-nwd.png @@ -1151,40 +1251,78 @@ A brief description of the events: - 3) SPMD signals secure interrupt to SPMC at S-EL2 using FFA_INTERRUPT ABI. - 4) SPMC identifies target vCPU of SP and injects virtual interrupt (pends vIRQ). - - 5) Since SP1 vCPU is in WAITING state, SPMC signals using FFA_INTERRUPT with - interrupt id as argument and resume it using ERET. - - 6) Execution traps to vIRQ handler in SP1 provided that interrupt is not - masked i.e., PSTATE.I = 0 - - 7) SP1 services the interrupt and invokes the de-activation HVC call. - - 8) SPMC does internal state management and further de-activates the physical - interrupt and resumes SP vCPU. - - 9) SP performs secure interrupt completion through FFA_MSG_WAIT ABI. + - 5) Assuming SP1 vCPU is in WAITING state, SPMC signals virtual interrupt + using FFA_INTERRUPT with interrupt id as an argument and resumes the SP1 + vCPU using ERET in SPMC scheduled mode. + - 6) Execution traps to vIRQ handler in SP1 provided that the virtual + interrupt is not masked i.e., PSTATE.I = 0 + - 7) SP1 queries for the pending virtual interrupt id using a paravirtualized + HVC call. SPMC clears the pending virtual interrupt state management + and returns the pending virtual interrupt id. + - 8) SP1 services the virtual interrupt and invokes the paravirtualized + de-activation HVC call. SPMC de-activates the physical interrupt, + clears the fields tracking the secure interrupt and resumes SP1 vCPU. + - 9) SP1 performs secure interrupt completion through FFA_MSG_WAIT ABI. - 10) SPMC returns control to EL3 using FFA_NORMAL_WORLD_RESUME. - 11) EL3 resumes normal world execution. -The following figure describes interrupt handling flow when secure interrupt -triggers while in secure world: +Actions for a secure interrupt triggered while execution is in secure world +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------------------+----------+------------------------------------------------+ +| State of target | Action | Description | +| execution context | | | ++-------------------+----------+------------------------------------------------+ +| WAITING | Signaled | This starts a new call chain in SPMC scheduled | +| | | mode. | ++-------------------+----------+------------------------------------------------+ +| PREEMPTED by Self | Signaled | The target execution context reenters the | +| S-Int | | RUNNING state to handle the secure virtual | +| | | interrupt. | ++-------------------+----------+------------------------------------------------+ +| PREEMPTED by | Queued | SPMC queues the secure virtual interrupt now. | +| NS-Int | | It is signaled when the target execution | +| | | context next enters the RUNNING state. | ++-------------------+----------+------------------------------------------------+ +| BLOCKED | Signaled | Both preempted and target execution contexts | +| | | must have been part of the Normal world | +| | | scheduled call chain. Refer scenario 1 of | +| | | Table 8.4 in the FF-A v1.1 EAC0 spec. | ++-------------------+----------+------------------------------------------------+ +| RUNNING | NA | The target execution context is running on a | +| | | different CPU. This scenario is not supported | +| | | by current SPMC implementation and execution | +| | | hits panic. | ++-------------------+----------+------------------------------------------------+ + +The following figure describes interrupt handling flow when a secure interrupt +triggers while execution is in secure world. We assume OS kernel sends a direct +request message to SP1. Further, SP1 sends a direct request message to SP2. SP1 +enters BLOCKED state and SPMC resumes SP2. .. image:: ../resources/diagrams/ffa-secure-interrupt-handling-swd.png A brief description of the events: - - 1) Secure interrupt triggers while SP2 is running and SP1 is blocked. - - 2) Gets trapped to SPMC as IRQ. + - 1) Secure interrupt triggers while SP2 is running. + - 2) SP2 gets preempted and execution traps to SPMC as IRQ. - 3) SPMC finds the target vCPU of secure partition responsible for handling this secure interrupt. In this scenario, it is SP1. - 4) SPMC pends vIRQ for SP1 and signals through FFA_INTERRUPT interface. - SPMC further resumes SP1 through ERET conduit. - - 5) Execution traps to vIRQ handler in SP1 provided that interrupt is not - masked i.e., PSTATE.I = 0 - - 6) SP1 services the secure interrupt and invokes the de-activation HVC call. - - 7) SPMC does internal state management, de-activates the physical interrupt - and resumes SP1 vCPU. - - 8) Assuming SP1 is in BLOCKED state, SP1 performs secure interrupt completion - through FFA_RUN ABI. + SPMC further resumes SP1 through ERET conduit. Note that SP1 remains in + Normal world schedule mode. + - 6) Execution traps to vIRQ handler in SP1 provided that the virtual + interrupt is not masked i.e., PSTATE.I = 0 + - 7) SP1 queries for the pending virtual interrupt id using a paravirtualized + HVC call. SPMC clears the pending virtual interrupt state management + and returns the pending virtual interrupt id. + - 8) SP1 services the virtual interrupt and invokes the paravirtualized + de-activation HVC call. SPMC de-activates the physical interrupt and + clears the fields tracking the secure interrupt and resumes SP1 vCPU. + - 9) Since SP1 direct request completed with FFA_INTERRUPT, it resumes the + direct request to SP2 by invoking FFA_RUN. - 9) SPMC resumes the pre-empted vCPU of SP2. - Power management ---------------- @@ -1374,13 +1512,13 @@ S-EL0 partitions are required by the FF-A specification to be UP endpoints, capable of migrating, and the SPMC enforces this requirement. The SPMC allows a S-EL0 partition to accept a direct message from secure world and normal world, and generate direct responses to them. +All S-EL0 partitions must use AArch64. AArch32 S-EL0 partitions are not supported. -Memory sharing between and with S-EL0 partitions is supported. -Indirect messaging, Interrupt handling and Notifications are not supported with -S-EL0 partitions and is work in progress, planned for future releases. -All S-EL0 partitions must use AArch64. AArch32 S-EL0 partitions are not -supported. +Memory sharing, indirect messaging, and notifications functionality with S-EL0 +partitions is supported. +Interrupt handling is not supported with S-EL0 partitions and is work in +progress. References ========== diff --git a/docs/components/spd/index.rst b/docs/components/spd/index.rst index 25d0124b1..6857806c2 100644 --- a/docs/components/spd/index.rst +++ b/docs/components/spd/index.rst @@ -8,3 +8,4 @@ Secure Payload Dispatcher (SPD) optee-dispatcher tlk-dispatcher trusty-dispatcher + pnc-dispatcher diff --git a/docs/components/spd/pnc-dispatcher.rst b/docs/components/spd/pnc-dispatcher.rst new file mode 100644 index 000000000..5be2fc7dc --- /dev/null +++ b/docs/components/spd/pnc-dispatcher.rst @@ -0,0 +1,10 @@ +ProvenCore Dispatcher +===================== + +ProvenCore dispatcher (PnC-D) adds support for ProvenRun's ProvenCore micro-kernel +to work with Trusted Firmware-A (TF-A). + +ProvenCore is a secure OS developed by ProvenRun S.A.S. using deductive formal methods. + +Once a BL32 is ready, PnC-D can be included in the image by adding "SPD=pncd" +to the build command. |