diff --git a/docs/components/index.rst b/docs/components/index.rst index 18b1e38..861a85d 100644 --- a/docs/components/index.rst +++ b/docs/components/index.rst @@ -16,7 +16,8 @@ ras romlib-design sdei - secure-partition-manager-design + secure-partition-manager + secure-partition-manager-mm psa-ffa-manifest-binding xlat-tables-lib-v2-design cot-binding diff --git a/docs/components/secure-partition-manager-design.rst b/docs/components/secure-partition-manager-design.rst deleted file mode 100644 index 4f67185..0000000 --- a/docs/components/secure-partition-manager-design.rst +++ /dev/null @@ -1,819 +0,0 @@ -Secure Partition Manager -************************ - -Background -========== - -In some market segments that primarily deal with client-side devices like mobile -phones, tablets, STBs and embedded devices, a Trusted OS instantiates trusted -applications to provide security services like DRM, secure payment and -authentication. The Global Platform TEE Client API specification defines the API -used by Non-secure world applications to access these services. A Trusted OS -fulfils the requirements of a security service as described above. - -Management services are typically implemented at the highest level of privilege -in the system, i.e. EL3 in Trusted Firmware-A (TF-A). The service requirements are -fulfilled by the execution environment provided by TF-A. - -The following diagram illustrates the corresponding software stack: - -|Image 1| - -In other market segments that primarily deal with server-side devices (e.g. data -centres and enterprise servers) the secure software stack typically does not -include a Global Platform Trusted OS. Security functions are accessed through -other interfaces (e.g. ACPI TCG TPM interface, UEFI runtime variable service). - -Placement of management and security functions with diverse requirements in a -privileged Exception Level (i.e. EL3 or S-EL1) makes security auditing of -firmware more difficult and does not allow isolation of unrelated services from -each other either. - -Introduction -============ - -A **Secure Partition** is a software execution environment instantiated in -S-EL0 that can be used to implement simple management and security services. -Since S-EL0 is an unprivileged Exception Level, a Secure Partition relies on -privileged firmware (i.e. TF-A) to be granted access to system and processor -resources. Essentially, it is a software sandbox in the Secure world that runs -under the control of privileged software, provides one or more services and -accesses the following system resources: - -- Memory and device regions in the system address map. - -- PE system registers. - -- A range of synchronous exceptions (e.g. SMC function identifiers). - -Note that currently TF-A only supports handling one Secure Partition. - -A Secure Partition enables TF-A to implement only the essential secure -services in EL3 and instantiate the rest in a partition in S-EL0. -Furthermore, multiple Secure Partitions can be used to isolate unrelated -services from each other. - -The following diagram illustrates the place of a Secure Partition in a typical -Armv8-A software stack. A single or multiple Secure Partitions provide secure -services to software components in the Non-secure world and other Secure -Partitions. - -|Image 2| - -The TF-A build system is responsible for including the Secure Partition image -in the FIP. During boot, BL2 includes support to authenticate and load the -Secure Partition image. A BL31 component called **Secure Partition Manager -(SPM)** is responsible for managing the partition. This is semantically -similar to a hypervisor managing a virtual machine. - -The SPM is responsible for the following actions during boot: - -- Allocate resources requested by the Secure Partition. - -- Perform architectural and system setup required by the Secure Partition to - fulfil a service request. - -- Implement a standard interface that is used for initialising a Secure - Partition. - -The SPM is responsible for the following actions during runtime: - -- Implement a standard interface that is used by a Secure Partition to fulfil - service requests. - -- Implement a standard interface that is used by the Non-secure world for - accessing the services exported by a Secure Partition. A service can be - invoked through a SMC. - -Alternatively, a partition can be viewed as a thread of execution running under -the control of the SPM. Hence common programming concepts described below are -applicable to a partition. - -Description -=========== - -The previous section introduced some general aspects of the software -architecture of a Secure Partition. This section describes the specific choices -made in the current implementation of this software architecture. Subsequent -revisions of the implementation will include a richer set of features that -enable a more flexible architecture. - -Building TF-A with Secure Partition support -------------------------------------------- - -SPM is supported on the Arm FVP exclusively at the moment. The current -implementation supports inclusion of only a single Secure Partition in which a -service always runs to completion (e.g. the requested services cannot be -preempted to give control back to the Normal world). - -It is not currently possible for BL31 to integrate SPM support and a Secure -Payload Dispatcher (SPD) at the same time; they are mutually exclusive. In the -SPM bootflow, a Secure Partition image executing at S-EL0 replaces the Secure -Payload image executing at S-EL1 (e.g. a Trusted OS). Both are referred to as -BL32. - -A working prototype of a SP has been implemented by re-purposing the EDK2 code -and tools, leveraging the concept of the *Standalone Management Mode (MM)* in -the UEFI specification (see the PI v1.6 Volume 4: Management Mode Core -Interface). This will be referred to as the *Standalone MM Secure Partition* in -the rest of this document. - -To enable SPM support in TF-A, the source code must be compiled with the build -flag ``SPM_MM=1``, along with ``EL3_EXCEPTION_HANDLING=1``. On Arm -platforms the build option ``ARM_BL31_IN_DRAM`` must be set to 1. Also, the -location of the binary that contains the BL32 image -(``BL32=path/to/image.bin``) must be specified. - -First, build the Standalone MM Secure Partition. To build it, refer to the -`instructions in the EDK2 repository`_. - -Then build TF-A with SPM support and include the Standalone MM Secure Partition -image in the FIP: - -.. code:: shell - - BL32=path/to/standalone/mm/sp BL33=path/to/bl33.bin \ - make PLAT=fvp SPM_MM=1 EL3_EXCEPTION_HANDLING=1 ARM_BL31_IN_DRAM=1 all fip - -Describing Secure Partition resources -------------------------------------- - -TF-A exports a porting interface that enables a platform to specify the system -resources required by the Secure Partition. Some instructions are given below. -However, this interface is under development and it may change as new features -are implemented. - -- A Secure Partition is considered a BL32 image, so the same defines that apply - to BL32 images apply to a Secure Partition: ``BL32_BASE`` and ``BL32_LIMIT``. - -- The following defines are needed to allocate space for the translation tables - used by the Secure Partition: ``PLAT_SP_IMAGE_MMAP_REGIONS`` and - ``PLAT_SP_IMAGE_MAX_XLAT_TABLES``. - -- The functions ``plat_get_secure_partition_mmap()`` and - ``plat_get_secure_partition_boot_info()`` have to be implemented. The file - ``plat/arm/board/fvp/fvp_common.c`` can be used as an example. It uses the - defines in ``include/plat/arm/common/arm_spm_def.h``. - - - ``plat_get_secure_partition_mmap()`` returns an array of mmap regions that - describe the memory regions that the SPM needs to allocate for a Secure - Partition. - - - ``plat_get_secure_partition_boot_info()`` returns a - ``spm_mm_boot_info_t`` struct that is populated by the platform - with information about the memory map of the Secure Partition. - -For an example of all the changes in context, you may refer to commit -``e29efeb1b4``, in which the port for FVP was introduced. - -Accessing Secure Partition services ------------------------------------ - -The `SMC Calling Convention`_ (*Arm DEN 0028B*) describes SMCs as a conduit for -accessing services implemented in the Secure world. The ``MM_COMMUNICATE`` -interface defined in the `Management Mode Interface Specification`_ (*Arm DEN -0060A*) is used to invoke a Secure Partition service as a Fast Call. - -The mechanism used to identify a service within the partition depends on the -service implementation. It is assumed that the caller of the service will be -able to discover this mechanism through standard platform discovery mechanisms -like ACPI and Device Trees. For example, *Volume 4: Platform Initialisation -Specification v1.6. Management Mode Core Interface* specifies that a GUID is -used to identify a management mode service. A client populates the GUID in the -``EFI_MM_COMMUNICATE_HEADER``. The header is populated in the communication -buffer shared with the Secure Partition. - -A Fast Call appears to be atomic from the perspective of the caller and returns -when the requested operation has completed. A service invoked through the -``MM_COMMUNICATE`` SMC will run to completion in the partition on a given CPU. -The SPM is responsible for guaranteeing this behaviour. This means that there -can only be a single outstanding Fast Call in a partition on a given CPU. - -Exchanging data with the Secure Partition ------------------------------------------ - -The exchange of data between the Non-secure world and the partition takes place -through a shared memory region. The location of data in the shared memory area -is passed as a parameter to the ``MM_COMMUNICATE`` SMC. The shared memory area -is statically allocated by the SPM and is expected to be either implicitly known -to the Non-secure world or discovered through a platform discovery mechanism -e.g. ACPI table or device tree. It is possible for the Non-secure world to -exchange data with a partition only if it has been populated in this shared -memory area. The shared memory area is implemented as per the guidelines -specified in Section 3.2.3 of the `Management Mode Interface Specification`_ -(*Arm DEN 0060A*). - -The format of data structures used to encapsulate data in the shared memory is -agreed between the Non-secure world and the Secure Partition. For example, in -the `Management Mode Interface specification`_ (*Arm DEN 0060A*), Section 4 -describes that the communication buffer shared between the Non-secure world and -the Management Mode (MM) in the Secure world must be of the type -``EFI_MM_COMMUNICATE_HEADER``. This data structure is defined in *Volume 4: -Platform Initialisation Specification v1.6. Management Mode Core Interface*. -Any caller of a MM service will have to use the ``EFI_MM_COMMUNICATE_HEADER`` -data structure. - -Runtime model of the Secure Partition -===================================== - -This section describes how the Secure Partition interfaces with the SPM. - -Interface with SPM ------------------- - -In order to instantiate one or more secure services in the Secure Partition in -S-EL0, the SPM should define the following types of interfaces: - -- Interfaces that enable access to privileged operations from S-EL0. These - operations typically require access to system resources that are either shared - amongst multiple software components in the Secure world or cannot be directly - accessed from an unprivileged Exception Level. - -- Interfaces that establish the control path between the SPM and the Secure - Partition. - -This section describes the APIs currently exported by the SPM that enable a -Secure Partition to initialise itself and export its services in S-EL0. These -interfaces are not accessible from the Non-secure world. - -Conduit -^^^^^^^ - -The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the SMC -and HVC conduits for accessing firmware services and their availability -depending on the implemented Exception levels. In S-EL0, the Supervisor Call -exception (SVC) is the only architectural mechanism available for unprivileged -software to make a request for an operation implemented in privileged software. -Hence, the SVC conduit must be used by the Secure Partition to access interfaces -implemented by the SPM. - -A SVC causes an exception to be taken to S-EL1. TF-A assumes ownership of S-EL1 -and installs a simple exception vector table in S-EL1 that relays a SVC request -from a Secure Partition as a SMC request to the SPM in EL3. Upon servicing the -SMC request, Trusted Firmware-A returns control directly to S-EL0 through an -ERET instruction. - -Calling conventions -^^^^^^^^^^^^^^^^^^^ - -The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the -32-bit and 64-bit calling conventions for the SMC and HVC conduits. The SVC -conduit introduces the concept of SVC32 and SVC64 calling conventions. The SVC32 -and SVC64 calling conventions are equivalent to the 32-bit (SMC32) and the -64-bit (SMC64) calling conventions respectively. - -Communication initiated by SPM -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A service request is initiated from the SPM through an exception return -instruction (ERET) to S-EL0. Later, the Secure Partition issues an SVC -instruction to signal completion of the request. Some example use cases are -given below: - -- A request to initialise the Secure Partition during system boot. - -- A request to handle a runtime service request. - -Communication initiated by Secure Partition -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A request is initiated from the Secure Partition by executing a SVC instruction. -An ERET instruction is used by TF-A to return to S-EL0 with the result of the -request. - -For instance, a request to perform privileged operations on behalf of a -partition (e.g. management of memory attributes in the translation tables for -the Secure EL1&0 translation regime). - -Interfaces -^^^^^^^^^^ - -The current implementation reserves function IDs for Fast Calls in the Standard -Secure Service calls range (see `SMC Calling Convention`_ (*Arm DEN 0028B*) -specification) for each API exported by the SPM. This section defines the -function prototypes for each function ID. The function IDs specify whether one -or both of the SVC32 and SVC64 calling conventions can be used to invoke the -corresponding interface. - -Secure Partition Event Management -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The Secure Partition provides an Event Management interface that is used by the -SPM to delegate service requests to the Secure Partition. The interface also -allows the Secure Partition to: - -- Register with the SPM a service that it provides. -- Indicate completion of a service request delegated by the SPM - -Miscellaneous interfaces ------------------------- - -``SPM_MM_VERSION_AARCH32`` -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- Description - - Returns the version of the interface exported by SPM. - -- Parameters - - - **uint32** - Function ID - - - SVC32 Version: **0x84000060** - -- Return parameters - - - **int32** - Status - - On success, the format of the value is as follows: - - - Bit [31]: Must be 0 - - Bits [30:16]: Major Version. Must be 0 for this revision of the SPM - interface. - - Bits [15:0]: Minor Version. Must be 1 for this revision of the SPM - interface. - - On error, the format of the value is as follows: - - - ``NOT_SUPPORTED``: SPM interface is not supported or not available for the - client. - -- Usage - - This function returns the version of the Secure Partition Manager - implementation. The major version is 0 and the minor version is 1. The version - number is a 31-bit unsigned integer, with the upper 15 bits denoting the major - revision, and the lower 16 bits denoting the minor revision. The following - rules apply to the version numbering: - - - Different major revision values indicate possibly incompatible functions. - - - For two revisions, A and B, for which the major revision values are - identical, if the minor revision value of revision B is greater than the - minor revision value of revision A, then every function in revision A must - work in a compatible way with revision B. However, it is possible for - revision B to have a higher function count than revision A. - -- Implementation responsibilities - - If this function returns a valid version number, all the functions that are - described subsequently must be implemented, unless it is explicitly stated - that a function is optional. - -See `Error Codes`_ for integer values that are associated with each return -code. - -Secure Partition Initialisation -------------------------------- - -The SPM is responsible for initialising the architectural execution context to -enable initialisation of a service in S-EL0. The responsibilities of the SPM are -listed below. At the end of initialisation, the partition issues a -``MM_SP_EVENT_COMPLETE_AARCH64`` call (described later) to signal readiness for -handling requests for services implemented by the Secure Partition. The -initialisation event is executed as a Fast Call. - -Entry point invocation -^^^^^^^^^^^^^^^^^^^^^^ - -The entry point for service requests that should be handled as Fast Calls is -used as the target of the ERET instruction to start initialisation of the Secure -Partition. - -Architectural Setup -^^^^^^^^^^^^^^^^^^^ - -At cold boot, system registers accessible from S-EL0 will be in their reset -state unless otherwise specified. The SPM will perform the following -architectural setup to enable execution in S-EL0 - -MMU setup -^^^^^^^^^ - -The platform port of a Secure Partition specifies to the SPM a list of regions -that it needs access to and their attributes. The SPM validates this resource -description and initialises the Secure EL1&0 translation regime as follows. - -1. Device regions are mapped with nGnRE attributes and Execute Never - instruction access permissions. - -2. Code memory regions are mapped with RO data and Executable instruction access - permissions. - -3. Read Only data memory regions are mapped with RO data and Execute Never - instruction access permissions. - -4. Read Write data memory regions are mapped with RW data and Execute Never - instruction access permissions. - -5. If the resource description does not explicitly describe the type of memory - regions then all memory regions will be marked with Code memory region - attributes. - -6. The ``UXN`` and ``PXN`` bits are set for regions that are not executable by - S-EL0 or S-EL1. - -System Register Setup -^^^^^^^^^^^^^^^^^^^^^ - -System registers that influence software execution in S-EL0 are setup by the SPM -as follows: - -1. ``SCTLR_EL1`` - - - ``UCI=1`` - - ``EOE=0`` - - ``WXN=1`` - - ``nTWE=1`` - - ``nTWI=1`` - - ``UCT=1`` - - ``DZE=1`` - - ``I=1`` - - ``UMA=0`` - - ``SA0=1`` - - ``C=1`` - - ``A=1`` - - ``M=1`` - -2. ``CPACR_EL1`` - - - ``FPEN=b'11`` - -3. ``PSTATE`` - - - ``D,A,I,F=1`` - - ``CurrentEL=0`` (EL0) - - ``SpSel=0`` (Thread mode) - - ``NRW=0`` (AArch64) - -General Purpose Register Setup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -SPM will invoke the entry point of a service by executing an ERET instruction. -This transition into S-EL0 is special since it is not in response to a previous -request through a SVC instruction. This is the first entry into S-EL0. The -general purpose register usage at the time of entry will be as specified in the -"Return State" column of Table 3-1 in Section 3.1 "Register use in AArch64 SMC -calls" of the `SMC Calling Convention`_ (*Arm DEN 0028B*) specification. In -addition, certain other restrictions will be applied as described below. - -1. ``SP_EL0`` - - A non-zero value will indicate that the SPM has initialised the stack pointer - for the current CPU. - - The value will be 0 otherwise. - -2. ``X4-X30`` - - The values of these registers will be 0. - -3. ``X0-X3`` - - Parameters passed by the SPM. - - - ``X0``: Virtual address of a buffer shared between EL3 and S-EL0. The - buffer will be mapped in the Secure EL1&0 translation regime with read-only - memory attributes described earlier. - - - ``X1``: Size of the buffer in bytes. - - - ``X2``: Cookie value (*IMPLEMENTATION DEFINED*). - - - ``X3``: Cookie value (*IMPLEMENTATION DEFINED*). - -Runtime Event Delegation ------------------------- - -The SPM receives requests for Secure Partition services through a synchronous -invocation (i.e. a SMC from the Non-secure world). These requests are delegated -to the partition by programming a return from the last -``MM_SP_EVENT_COMPLETE_AARCH64`` call received from the partition. The last call -was made to signal either completion of Secure Partition initialisation or -completion of a partition service request. - -``MM_SP_EVENT_COMPLETE_AARCH64`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- Description - - Signal completion of the last SP service request. - -- Parameters - - - **uint32** - Function ID - - - SVC64 Version: **0xC4000061** - - - **int32** - Event Status Code - - Zero or a positive value indicates that the event was handled successfully. - The values depend upon the original event that was delegated to the Secure - partition. They are described as follows. - - - ``SUCCESS`` : Used to indicate that the Secure Partition was initialised - or a runtime request was handled successfully. - - - Any other value greater than 0 is used to pass a specific Event Status - code in response to a runtime event. - - A negative value indicates an error. The values of Event Status code depend - on the original event. - -- Return parameters - - - **int32** - Event ID/Return Code - - Zero or a positive value specifies the unique ID of the event being - delegated to the partition by the SPM. - - In the current implementation, this parameter contains the function ID of - the ``MM_COMMUNICATE`` SMC. This value indicates to the partition that an - event has been delegated to it in response to an ``MM_COMMUNICATE`` request - from the Non-secure world. - - A negative value indicates an error. The format of the value is as follows: - - - ``NOT_SUPPORTED``: Function was called from the Non-secure world. - - See `Error Codes`_ for integer values that are associated with each return - code. - - - **uint32** - Event Context Address - - Address of a buffer shared between the SPM and Secure Partition to pass - event specific information. The format of the data populated in the buffer - is implementation defined. - - The buffer is mapped in the Secure EL1&0 translation regime with read-only - memory attributes described earlier. - - For the SVC64 version, this parameter is a 64-bit Virtual Address (VA). - - For the SVC32 version, this parameter is a 32-bit Virtual Address (VA). - - - **uint32** - Event context size - - Size of the memory starting at Event Address. - - - **uint32/uint64** - Event Cookie - - This is an optional parameter. If unused its value is SBZ. - -- Usage - - This function signals to the SPM that the handling of the last event delegated - to a partition has completed. The partition is ready to handle its next event. - A return from this function is in response to the next event that will be - delegated to the partition. The return parameters describe the next event. - -- Caller responsibilities - - A Secure Partition must only call ``MM_SP_EVENT_COMPLETE_AARCH64`` to signal - completion of a request that was delegated to it by the SPM. - -- Callee responsibilities - - When the SPM receives this call from a Secure Partition, the corresponding - syndrome information can be used to return control through an ERET - instruction, to the instruction immediately after the call in the Secure - Partition context. This syndrome information comprises of general purpose and - system register values when the call was made. - - The SPM must save this syndrome information and use it to delegate the next - event to the Secure Partition. The return parameters of this interface must - specify the properties of the event and be populated in ``X0-X3/W0-W3`` - registers. - -Secure Partition Memory Management ----------------------------------- - -A Secure Partition executes at S-EL0, which is an unprivileged Exception Level. -The SPM is responsible for enabling access to regions of memory in the system -address map from a Secure Partition. This is done by mapping these regions in -the Secure EL1&0 Translation regime with appropriate memory attributes. -Attributes refer to memory type, permission, cacheability and shareability -attributes used in the Translation tables. The definitions of these attributes -and their usage can be found in the `Armv8-A ARM`_ (*Arm DDI 0487*). - -All memory required by the Secure Partition is allocated upfront in the SPM, -even before handing over to the Secure Partition for the first time. The initial -access permissions of the memory regions are statically provided by the platform -port and should allow the Secure Partition to run its initialisation code. - -However, they might not suit the final needs of the Secure Partition because its -final memory layout might not be known until the Secure Partition initialises -itself. As the Secure Partition initialises its runtime environment it might, -for example, load dynamically some modules. For instance, a Secure Partition -could implement a loader for a standard executable file format (e.g. an PE-COFF -loader for loading executable files at runtime). These executable files will be -a part of the Secure Partition image. The location of various sections in an -executable file and their permission attributes (e.g. read-write data, read-only -data and code) will be known only when the file is loaded into memory. - -In this case, the Secure Partition needs a way to change the access permissions -of its memory regions. The SPM provides this feature through the -``MM_SP_MEMORY_ATTRIBUTES_SET_AARCH64`` SVC interface. This interface is -available to the Secure Partition during a specific time window: from the first -entry into the Secure Partition up to the first ``SP_EVENT_COMPLETE`` call that -signals the Secure Partition has finished its initialisation. Once the -initialisation is complete, the SPM does not allow changes to the memory -attributes. - -This section describes the standard SVC interface that is implemented by the SPM -to determine and change permission attributes of memory regions that belong to a -Secure Partition. - -``MM_SP_MEMORY_ATTRIBUTES_GET_AARCH64`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- Description - - Request the permission attributes of a memory region from S-EL0. - -- Parameters - - - **uint32** Function ID - - - SVC64 Version: **0xC4000064** - - - **uint64** Base Address - - This parameter is a 64-bit Virtual Address (VA). - - There are no alignment restrictions on the Base Address. The permission - attributes of the translation granule it lies in are returned. - -- Return parameters - - - **int32** - Memory Attributes/Return Code - - On success the format of the Return Code is as follows: - - - Bits[1:0] : Data access permission - - - b'00 : No access - - b'01 : Read-Write access - - b'10 : Reserved - - b'11 : Read-only access - - - Bit[2]: Instruction access permission - - - b'0 : Executable - - b'1 : Non-executable - - - Bit[30:3] : Reserved. SBZ. - - - Bit[31] : Must be 0 - - On failure the following error codes are returned: - - - ``INVALID_PARAMETERS``: The Secure Partition is not allowed to access the - memory region the Base Address lies in. - - - ``NOT_SUPPORTED`` : The SPM does not support retrieval of attributes of - any memory page that is accessible by the Secure Partition, or the - function was called from the Non-secure world. Also returned if it is - used after ``MM_SP_EVENT_COMPLETE_AARCH64``. - - See `Error Codes`_ for integer values that are associated with each return - code. - -- Usage - - This function is used to request the permission attributes for S-EL0 on a - memory region accessible from a Secure Partition. The size of the memory - region is equal to the Translation Granule size used in the Secure EL1&0 - translation regime. Requests to retrieve other memory region attributes are - not currently supported. - -- Caller responsibilities - - The caller must obtain the Translation Granule Size of the Secure EL1&0 - translation regime from the SPM through an implementation defined method. - -- Callee responsibilities - - The SPM must not return the memory access controls for a page of memory that - is not accessible from a Secure Partition. - -``MM_SP_MEMORY_ATTRIBUTES_SET_AARCH64`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- Description - - Set the permission attributes of a memory region from S-EL0. - -- Parameters - - - **uint32** - Function ID - - - SVC64 Version: **0xC4000065** - - - **uint64** - Base Address - - This parameter is a 64-bit Virtual Address (VA). - - The alignment of the Base Address must be greater than or equal to the size - of the Translation Granule Size used in the Secure EL1&0 translation - regime. - - - **uint32** - Page count - - Number of pages starting from the Base Address whose memory attributes - should be changed. The page size is equal to the Translation Granule Size. - - - **uint32** - Memory Access Controls - - - Bits[1:0] : Data access permission - - - b'00 : No access - - b'01 : Read-Write access - - b'10 : Reserved - - b'11 : Read-only access - - - Bit[2] : Instruction access permission - - - b'0 : Executable - - b'1 : Non-executable - - - Bits[31:3] : Reserved. SBZ. - - A combination of attributes that mark the region with RW and Executable - permissions is prohibited. A request to mark a device memory region with - Executable permissions is prohibited. - -- Return parameters - - - **int32** - Return Code - - - ``SUCCESS``: The Memory Access Controls were changed successfully. - - - ``DENIED``: The SPM is servicing a request to change the attributes of a - memory region that overlaps with the region specified in this request. - - - ``INVALID_PARAMETER``: An invalid combination of Memory Access Controls - has been specified. The Base Address is not correctly aligned. The Secure - Partition is not allowed to access part or all of the memory region - specified in the call. - - - ``NO_MEMORY``: The SPM does not have memory resources to change the - attributes of the memory region in the translation tables. - - - ``NOT_SUPPORTED``: The SPM does not permit change of attributes of any - memory region that is accessible by the Secure Partition. Function was - called from the Non-secure world. Also returned if it is used after - ``MM_SP_EVENT_COMPLETE_AARCH64``. - - See `Error Codes`_ for integer values that are associated with each return - code. - -- Usage - - This function is used to change the permission attributes for S-EL0 on a - memory region accessible from a Secure Partition. The size of the memory - region is equal to the Translation Granule size used in the Secure EL1&0 - translation regime. Requests to change other memory region attributes are not - currently supported. - - This function is only available at boot time. This interface is revoked after - the Secure Partition sends the first ``MM_SP_EVENT_COMPLETE_AARCH64`` to - signal that it is initialised and ready to receive run-time requests. - -- Caller responsibilities - - The caller must obtain the Translation Granule Size of the Secure EL1&0 - translation regime from the SPM through an implementation defined method. - -- Callee responsibilities - - The SPM must preserve the original memory access controls of the region of - memory in case of an unsuccessful call.  The SPM must preserve the consistency - of the S-EL1 translation regime if this function is called on different PEs - concurrently and the memory regions specified overlap. - -Error Codes ------------ - -.. csv-table:: - :header: "Name", "Value" - - ``SUCCESS``,0 - ``NOT_SUPPORTED``,-1 - ``INVALID_PARAMETER``,-2 - ``DENIED``,-3 - ``NO_MEMORY``,-5 - ``NOT_PRESENT``,-7 - --------------- - -*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.* - -.. _Armv8-A ARM: https://developer.arm.com/docs/ddi0487/latest/arm-architecture-reference-manual-armv8-for-armv8-a-architecture-profile -.. _instructions in the EDK2 repository: https://github.com/tianocore/edk2-staging/blob/AArch64StandaloneMm/HowtoBuild.MD -.. _Management Mode Interface Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf -.. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf -.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest - -.. |Image 1| image:: ../resources/diagrams/secure_sw_stack_tos.png -.. |Image 2| image:: ../resources/diagrams/secure_sw_stack_sp.png diff --git a/docs/components/secure-partition-manager-mm.rst b/docs/components/secure-partition-manager-mm.rst new file mode 100644 index 0000000..87fc91d --- /dev/null +++ b/docs/components/secure-partition-manager-mm.rst @@ -0,0 +1,836 @@ +Secure Partition Manager (MM) +***************************** + +Foreword +======== + +Two implementations of a Secure Partition Manager co-exist in the TF-A codebase: + +- SPM based on the PSA FF-A specification (`Secure Partition Manager`__). +- SPM based on the MM interface. + +.. __: secure-partition-manager.html + +Both implementations differ in their architectures and only one can be selected +at build time. + +This document describes the latter implementation where the Secure Partition Manager +resides at EL3 and management services run from isolated Secure Partitions at S-EL0. +The communication protocol is established through the Management Mode (MM) interface. + +Background +========== + +In some market segments that primarily deal with client-side devices like mobile +phones, tablets, STBs and embedded devices, a Trusted OS instantiates trusted +applications to provide security services like DRM, secure payment and +authentication. The Global Platform TEE Client API specification defines the API +used by Non-secure world applications to access these services. A Trusted OS +fulfils the requirements of a security service as described above. + +Management services are typically implemented at the highest level of privilege +in the system, i.e. EL3 in Trusted Firmware-A (TF-A). The service requirements are +fulfilled by the execution environment provided by TF-A. + +The following diagram illustrates the corresponding software stack: + +|Image 1| + +In other market segments that primarily deal with server-side devices (e.g. data +centres and enterprise servers) the secure software stack typically does not +include a Global Platform Trusted OS. Security functions are accessed through +other interfaces (e.g. ACPI TCG TPM interface, UEFI runtime variable service). + +Placement of management and security functions with diverse requirements in a +privileged Exception Level (i.e. EL3 or S-EL1) makes security auditing of +firmware more difficult and does not allow isolation of unrelated services from +each other either. + +Introduction +============ + +A **Secure Partition** is a software execution environment instantiated in +S-EL0 that can be used to implement simple management and security services. +Since S-EL0 is an unprivileged Exception Level, a Secure Partition relies on +privileged firmware (i.e. TF-A) to be granted access to system and processor +resources. Essentially, it is a software sandbox in the Secure world that runs +under the control of privileged software, provides one or more services and +accesses the following system resources: + +- Memory and device regions in the system address map. + +- PE system registers. + +- A range of synchronous exceptions (e.g. SMC function identifiers). + +Note that currently TF-A only supports handling one Secure Partition. + +A Secure Partition enables TF-A to implement only the essential secure +services in EL3 and instantiate the rest in a partition in S-EL0. +Furthermore, multiple Secure Partitions can be used to isolate unrelated +services from each other. + +The following diagram illustrates the place of a Secure Partition in a typical +Armv8-A software stack. A single or multiple Secure Partitions provide secure +services to software components in the Non-secure world and other Secure +Partitions. + +|Image 2| + +The TF-A build system is responsible for including the Secure Partition image +in the FIP. During boot, BL2 includes support to authenticate and load the +Secure Partition image. A BL31 component called **Secure Partition Manager +(SPM)** is responsible for managing the partition. This is semantically +similar to a hypervisor managing a virtual machine. + +The SPM is responsible for the following actions during boot: + +- Allocate resources requested by the Secure Partition. + +- Perform architectural and system setup required by the Secure Partition to + fulfil a service request. + +- Implement a standard interface that is used for initialising a Secure + Partition. + +The SPM is responsible for the following actions during runtime: + +- Implement a standard interface that is used by a Secure Partition to fulfil + service requests. + +- Implement a standard interface that is used by the Non-secure world for + accessing the services exported by a Secure Partition. A service can be + invoked through a SMC. + +Alternatively, a partition can be viewed as a thread of execution running under +the control of the SPM. Hence common programming concepts described below are +applicable to a partition. + +Description +=========== + +The previous section introduced some general aspects of the software +architecture of a Secure Partition. This section describes the specific choices +made in the current implementation of this software architecture. Subsequent +revisions of the implementation will include a richer set of features that +enable a more flexible architecture. + +Building TF-A with Secure Partition support +------------------------------------------- + +SPM is supported on the Arm FVP exclusively at the moment. The current +implementation supports inclusion of only a single Secure Partition in which a +service always runs to completion (e.g. the requested services cannot be +preempted to give control back to the Normal world). + +It is not currently possible for BL31 to integrate SPM support and a Secure +Payload Dispatcher (SPD) at the same time; they are mutually exclusive. In the +SPM bootflow, a Secure Partition image executing at S-EL0 replaces the Secure +Payload image executing at S-EL1 (e.g. a Trusted OS). Both are referred to as +BL32. + +A working prototype of a SP has been implemented by re-purposing the EDK2 code +and tools, leveraging the concept of the *Standalone Management Mode (MM)* in +the UEFI specification (see the PI v1.6 Volume 4: Management Mode Core +Interface). This will be referred to as the *Standalone MM Secure Partition* in +the rest of this document. + +To enable SPM support in TF-A, the source code must be compiled with the build +flag ``SPM_MM=1``, along with ``EL3_EXCEPTION_HANDLING=1``. On Arm +platforms the build option ``ARM_BL31_IN_DRAM`` must be set to 1. Also, the +location of the binary that contains the BL32 image +(``BL32=path/to/image.bin``) must be specified. + +First, build the Standalone MM Secure Partition. To build it, refer to the +`instructions in the EDK2 repository`_. + +Then build TF-A with SPM support and include the Standalone MM Secure Partition +image in the FIP: + +.. code:: shell + + BL32=path/to/standalone/mm/sp BL33=path/to/bl33.bin \ + make PLAT=fvp SPM_MM=1 EL3_EXCEPTION_HANDLING=1 ARM_BL31_IN_DRAM=1 all fip + +Describing Secure Partition resources +------------------------------------- + +TF-A exports a porting interface that enables a platform to specify the system +resources required by the Secure Partition. Some instructions are given below. +However, this interface is under development and it may change as new features +are implemented. + +- A Secure Partition is considered a BL32 image, so the same defines that apply + to BL32 images apply to a Secure Partition: ``BL32_BASE`` and ``BL32_LIMIT``. + +- The following defines are needed to allocate space for the translation tables + used by the Secure Partition: ``PLAT_SP_IMAGE_MMAP_REGIONS`` and + ``PLAT_SP_IMAGE_MAX_XLAT_TABLES``. + +- The functions ``plat_get_secure_partition_mmap()`` and + ``plat_get_secure_partition_boot_info()`` have to be implemented. The file + ``plat/arm/board/fvp/fvp_common.c`` can be used as an example. It uses the + defines in ``include/plat/arm/common/arm_spm_def.h``. + + - ``plat_get_secure_partition_mmap()`` returns an array of mmap regions that + describe the memory regions that the SPM needs to allocate for a Secure + Partition. + + - ``plat_get_secure_partition_boot_info()`` returns a + ``spm_mm_boot_info_t`` struct that is populated by the platform + with information about the memory map of the Secure Partition. + +For an example of all the changes in context, you may refer to commit +``e29efeb1b4``, in which the port for FVP was introduced. + +Accessing Secure Partition services +----------------------------------- + +The `SMC Calling Convention`_ (*Arm DEN 0028B*) describes SMCs as a conduit for +accessing services implemented in the Secure world. The ``MM_COMMUNICATE`` +interface defined in the `Management Mode Interface Specification`_ (*Arm DEN +0060A*) is used to invoke a Secure Partition service as a Fast Call. + +The mechanism used to identify a service within the partition depends on the +service implementation. It is assumed that the caller of the service will be +able to discover this mechanism through standard platform discovery mechanisms +like ACPI and Device Trees. For example, *Volume 4: Platform Initialisation +Specification v1.6. Management Mode Core Interface* specifies that a GUID is +used to identify a management mode service. A client populates the GUID in the +``EFI_MM_COMMUNICATE_HEADER``. The header is populated in the communication +buffer shared with the Secure Partition. + +A Fast Call appears to be atomic from the perspective of the caller and returns +when the requested operation has completed. A service invoked through the +``MM_COMMUNICATE`` SMC will run to completion in the partition on a given CPU. +The SPM is responsible for guaranteeing this behaviour. This means that there +can only be a single outstanding Fast Call in a partition on a given CPU. + +Exchanging data with the Secure Partition +----------------------------------------- + +The exchange of data between the Non-secure world and the partition takes place +through a shared memory region. The location of data in the shared memory area +is passed as a parameter to the ``MM_COMMUNICATE`` SMC. The shared memory area +is statically allocated by the SPM and is expected to be either implicitly known +to the Non-secure world or discovered through a platform discovery mechanism +e.g. ACPI table or device tree. It is possible for the Non-secure world to +exchange data with a partition only if it has been populated in this shared +memory area. The shared memory area is implemented as per the guidelines +specified in Section 3.2.3 of the `Management Mode Interface Specification`_ +(*Arm DEN 0060A*). + +The format of data structures used to encapsulate data in the shared memory is +agreed between the Non-secure world and the Secure Partition. For example, in +the `Management Mode Interface specification`_ (*Arm DEN 0060A*), Section 4 +describes that the communication buffer shared between the Non-secure world and +the Management Mode (MM) in the Secure world must be of the type +``EFI_MM_COMMUNICATE_HEADER``. This data structure is defined in *Volume 4: +Platform Initialisation Specification v1.6. Management Mode Core Interface*. +Any caller of a MM service will have to use the ``EFI_MM_COMMUNICATE_HEADER`` +data structure. + +Runtime model of the Secure Partition +===================================== + +This section describes how the Secure Partition interfaces with the SPM. + +Interface with SPM +------------------ + +In order to instantiate one or more secure services in the Secure Partition in +S-EL0, the SPM should define the following types of interfaces: + +- Interfaces that enable access to privileged operations from S-EL0. These + operations typically require access to system resources that are either shared + amongst multiple software components in the Secure world or cannot be directly + accessed from an unprivileged Exception Level. + +- Interfaces that establish the control path between the SPM and the Secure + Partition. + +This section describes the APIs currently exported by the SPM that enable a +Secure Partition to initialise itself and export its services in S-EL0. These +interfaces are not accessible from the Non-secure world. + +Conduit +^^^^^^^ + +The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the SMC +and HVC conduits for accessing firmware services and their availability +depending on the implemented Exception levels. In S-EL0, the Supervisor Call +exception (SVC) is the only architectural mechanism available for unprivileged +software to make a request for an operation implemented in privileged software. +Hence, the SVC conduit must be used by the Secure Partition to access interfaces +implemented by the SPM. + +A SVC causes an exception to be taken to S-EL1. TF-A assumes ownership of S-EL1 +and installs a simple exception vector table in S-EL1 that relays a SVC request +from a Secure Partition as a SMC request to the SPM in EL3. Upon servicing the +SMC request, Trusted Firmware-A returns control directly to S-EL0 through an +ERET instruction. + +Calling conventions +^^^^^^^^^^^^^^^^^^^ + +The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the +32-bit and 64-bit calling conventions for the SMC and HVC conduits. The SVC +conduit introduces the concept of SVC32 and SVC64 calling conventions. The SVC32 +and SVC64 calling conventions are equivalent to the 32-bit (SMC32) and the +64-bit (SMC64) calling conventions respectively. + +Communication initiated by SPM +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A service request is initiated from the SPM through an exception return +instruction (ERET) to S-EL0. Later, the Secure Partition issues an SVC +instruction to signal completion of the request. Some example use cases are +given below: + +- A request to initialise the Secure Partition during system boot. + +- A request to handle a runtime service request. + +Communication initiated by Secure Partition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A request is initiated from the Secure Partition by executing a SVC instruction. +An ERET instruction is used by TF-A to return to S-EL0 with the result of the +request. + +For instance, a request to perform privileged operations on behalf of a +partition (e.g. management of memory attributes in the translation tables for +the Secure EL1&0 translation regime). + +Interfaces +^^^^^^^^^^ + +The current implementation reserves function IDs for Fast Calls in the Standard +Secure Service calls range (see `SMC Calling Convention`_ (*Arm DEN 0028B*) +specification) for each API exported by the SPM. This section defines the +function prototypes for each function ID. The function IDs specify whether one +or both of the SVC32 and SVC64 calling conventions can be used to invoke the +corresponding interface. + +Secure Partition Event Management +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Secure Partition provides an Event Management interface that is used by the +SPM to delegate service requests to the Secure Partition. The interface also +allows the Secure Partition to: + +- Register with the SPM a service that it provides. +- Indicate completion of a service request delegated by the SPM + +Miscellaneous interfaces +------------------------ + +``SPM_MM_VERSION_AARCH32`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Description + + Returns the version of the interface exported by SPM. + +- Parameters + + - **uint32** - Function ID + + - SVC32 Version: **0x84000060** + +- Return parameters + + - **int32** - Status + + On success, the format of the value is as follows: + + - Bit [31]: Must be 0 + - Bits [30:16]: Major Version. Must be 0 for this revision of the SPM + interface. + - Bits [15:0]: Minor Version. Must be 1 for this revision of the SPM + interface. + + On error, the format of the value is as follows: + + - ``NOT_SUPPORTED``: SPM interface is not supported or not available for the + client. + +- Usage + + This function returns the version of the Secure Partition Manager + implementation. The major version is 0 and the minor version is 1. The version + number is a 31-bit unsigned integer, with the upper 15 bits denoting the major + revision, and the lower 16 bits denoting the minor revision. The following + rules apply to the version numbering: + + - Different major revision values indicate possibly incompatible functions. + + - For two revisions, A and B, for which the major revision values are + identical, if the minor revision value of revision B is greater than the + minor revision value of revision A, then every function in revision A must + work in a compatible way with revision B. However, it is possible for + revision B to have a higher function count than revision A. + +- Implementation responsibilities + + If this function returns a valid version number, all the functions that are + described subsequently must be implemented, unless it is explicitly stated + that a function is optional. + +See `Error Codes`_ for integer values that are associated with each return +code. + +Secure Partition Initialisation +------------------------------- + +The SPM is responsible for initialising the architectural execution context to +enable initialisation of a service in S-EL0. The responsibilities of the SPM are +listed below. At the end of initialisation, the partition issues a +``MM_SP_EVENT_COMPLETE_AARCH64`` call (described later) to signal readiness for +handling requests for services implemented by the Secure Partition. The +initialisation event is executed as a Fast Call. + +Entry point invocation +^^^^^^^^^^^^^^^^^^^^^^ + +The entry point for service requests that should be handled as Fast Calls is +used as the target of the ERET instruction to start initialisation of the Secure +Partition. + +Architectural Setup +^^^^^^^^^^^^^^^^^^^ + +At cold boot, system registers accessible from S-EL0 will be in their reset +state unless otherwise specified. The SPM will perform the following +architectural setup to enable execution in S-EL0 + +MMU setup +^^^^^^^^^ + +The platform port of a Secure Partition specifies to the SPM a list of regions +that it needs access to and their attributes. The SPM validates this resource +description and initialises the Secure EL1&0 translation regime as follows. + +1. Device regions are mapped with nGnRE attributes and Execute Never + instruction access permissions. + +2. Code memory regions are mapped with RO data and Executable instruction access + permissions. + +3. Read Only data memory regions are mapped with RO data and Execute Never + instruction access permissions. + +4. Read Write data memory regions are mapped with RW data and Execute Never + instruction access permissions. + +5. If the resource description does not explicitly describe the type of memory + regions then all memory regions will be marked with Code memory region + attributes. + +6. The ``UXN`` and ``PXN`` bits are set for regions that are not executable by + S-EL0 or S-EL1. + +System Register Setup +^^^^^^^^^^^^^^^^^^^^^ + +System registers that influence software execution in S-EL0 are setup by the SPM +as follows: + +1. ``SCTLR_EL1`` + + - ``UCI=1`` + - ``EOE=0`` + - ``WXN=1`` + - ``nTWE=1`` + - ``nTWI=1`` + - ``UCT=1`` + - ``DZE=1`` + - ``I=1`` + - ``UMA=0`` + - ``SA0=1`` + - ``C=1`` + - ``A=1`` + - ``M=1`` + +2. ``CPACR_EL1`` + + - ``FPEN=b'11`` + +3. ``PSTATE`` + + - ``D,A,I,F=1`` + - ``CurrentEL=0`` (EL0) + - ``SpSel=0`` (Thread mode) + - ``NRW=0`` (AArch64) + +General Purpose Register Setup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SPM will invoke the entry point of a service by executing an ERET instruction. +This transition into S-EL0 is special since it is not in response to a previous +request through a SVC instruction. This is the first entry into S-EL0. The +general purpose register usage at the time of entry will be as specified in the +"Return State" column of Table 3-1 in Section 3.1 "Register use in AArch64 SMC +calls" of the `SMC Calling Convention`_ (*Arm DEN 0028B*) specification. In +addition, certain other restrictions will be applied as described below. + +1. ``SP_EL0`` + + A non-zero value will indicate that the SPM has initialised the stack pointer + for the current CPU. + + The value will be 0 otherwise. + +2. ``X4-X30`` + + The values of these registers will be 0. + +3. ``X0-X3`` + + Parameters passed by the SPM. + + - ``X0``: Virtual address of a buffer shared between EL3 and S-EL0. The + buffer will be mapped in the Secure EL1&0 translation regime with read-only + memory attributes described earlier. + + - ``X1``: Size of the buffer in bytes. + + - ``X2``: Cookie value (*IMPLEMENTATION DEFINED*). + + - ``X3``: Cookie value (*IMPLEMENTATION DEFINED*). + +Runtime Event Delegation +------------------------ + +The SPM receives requests for Secure Partition services through a synchronous +invocation (i.e. a SMC from the Non-secure world). These requests are delegated +to the partition by programming a return from the last +``MM_SP_EVENT_COMPLETE_AARCH64`` call received from the partition. The last call +was made to signal either completion of Secure Partition initialisation or +completion of a partition service request. + +``MM_SP_EVENT_COMPLETE_AARCH64`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Description + + Signal completion of the last SP service request. + +- Parameters + + - **uint32** - Function ID + + - SVC64 Version: **0xC4000061** + + - **int32** - Event Status Code + + Zero or a positive value indicates that the event was handled successfully. + The values depend upon the original event that was delegated to the Secure + partition. They are described as follows. + + - ``SUCCESS`` : Used to indicate that the Secure Partition was initialised + or a runtime request was handled successfully. + + - Any other value greater than 0 is used to pass a specific Event Status + code in response to a runtime event. + + A negative value indicates an error. The values of Event Status code depend + on the original event. + +- Return parameters + + - **int32** - Event ID/Return Code + + Zero or a positive value specifies the unique ID of the event being + delegated to the partition by the SPM. + + In the current implementation, this parameter contains the function ID of + the ``MM_COMMUNICATE`` SMC. This value indicates to the partition that an + event has been delegated to it in response to an ``MM_COMMUNICATE`` request + from the Non-secure world. + + A negative value indicates an error. The format of the value is as follows: + + - ``NOT_SUPPORTED``: Function was called from the Non-secure world. + + See `Error Codes`_ for integer values that are associated with each return + code. + + - **uint32** - Event Context Address + + Address of a buffer shared between the SPM and Secure Partition to pass + event specific information. The format of the data populated in the buffer + is implementation defined. + + The buffer is mapped in the Secure EL1&0 translation regime with read-only + memory attributes described earlier. + + For the SVC64 version, this parameter is a 64-bit Virtual Address (VA). + + For the SVC32 version, this parameter is a 32-bit Virtual Address (VA). + + - **uint32** - Event context size + + Size of the memory starting at Event Address. + + - **uint32/uint64** - Event Cookie + + This is an optional parameter. If unused its value is SBZ. + +- Usage + + This function signals to the SPM that the handling of the last event delegated + to a partition has completed. The partition is ready to handle its next event. + A return from this function is in response to the next event that will be + delegated to the partition. The return parameters describe the next event. + +- Caller responsibilities + + A Secure Partition must only call ``MM_SP_EVENT_COMPLETE_AARCH64`` to signal + completion of a request that was delegated to it by the SPM. + +- Callee responsibilities + + When the SPM receives this call from a Secure Partition, the corresponding + syndrome information can be used to return control through an ERET + instruction, to the instruction immediately after the call in the Secure + Partition context. This syndrome information comprises of general purpose and + system register values when the call was made. + + The SPM must save this syndrome information and use it to delegate the next + event to the Secure Partition. The return parameters of this interface must + specify the properties of the event and be populated in ``X0-X3/W0-W3`` + registers. + +Secure Partition Memory Management +---------------------------------- + +A Secure Partition executes at S-EL0, which is an unprivileged Exception Level. +The SPM is responsible for enabling access to regions of memory in the system +address map from a Secure Partition. This is done by mapping these regions in +the Secure EL1&0 Translation regime with appropriate memory attributes. +Attributes refer to memory type, permission, cacheability and shareability +attributes used in the Translation tables. The definitions of these attributes +and their usage can be found in the `Armv8-A ARM`_ (*Arm DDI 0487*). + +All memory required by the Secure Partition is allocated upfront in the SPM, +even before handing over to the Secure Partition for the first time. The initial +access permissions of the memory regions are statically provided by the platform +port and should allow the Secure Partition to run its initialisation code. + +However, they might not suit the final needs of the Secure Partition because its +final memory layout might not be known until the Secure Partition initialises +itself. As the Secure Partition initialises its runtime environment it might, +for example, load dynamically some modules. For instance, a Secure Partition +could implement a loader for a standard executable file format (e.g. an PE-COFF +loader for loading executable files at runtime). These executable files will be +a part of the Secure Partition image. The location of various sections in an +executable file and their permission attributes (e.g. read-write data, read-only +data and code) will be known only when the file is loaded into memory. + +In this case, the Secure Partition needs a way to change the access permissions +of its memory regions. The SPM provides this feature through the +``MM_SP_MEMORY_ATTRIBUTES_SET_AARCH64`` SVC interface. This interface is +available to the Secure Partition during a specific time window: from the first +entry into the Secure Partition up to the first ``SP_EVENT_COMPLETE`` call that +signals the Secure Partition has finished its initialisation. Once the +initialisation is complete, the SPM does not allow changes to the memory +attributes. + +This section describes the standard SVC interface that is implemented by the SPM +to determine and change permission attributes of memory regions that belong to a +Secure Partition. + +``MM_SP_MEMORY_ATTRIBUTES_GET_AARCH64`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Description + + Request the permission attributes of a memory region from S-EL0. + +- Parameters + + - **uint32** Function ID + + - SVC64 Version: **0xC4000064** + + - **uint64** Base Address + + This parameter is a 64-bit Virtual Address (VA). + + There are no alignment restrictions on the Base Address. The permission + attributes of the translation granule it lies in are returned. + +- Return parameters + + - **int32** - Memory Attributes/Return Code + + On success the format of the Return Code is as follows: + + - Bits[1:0] : Data access permission + + - b'00 : No access + - b'01 : Read-Write access + - b'10 : Reserved + - b'11 : Read-only access + + - Bit[2]: Instruction access permission + + - b'0 : Executable + - b'1 : Non-executable + + - Bit[30:3] : Reserved. SBZ. + + - Bit[31] : Must be 0 + + On failure the following error codes are returned: + + - ``INVALID_PARAMETERS``: The Secure Partition is not allowed to access the + memory region the Base Address lies in. + + - ``NOT_SUPPORTED`` : The SPM does not support retrieval of attributes of + any memory page that is accessible by the Secure Partition, or the + function was called from the Non-secure world. Also returned if it is + used after ``MM_SP_EVENT_COMPLETE_AARCH64``. + + See `Error Codes`_ for integer values that are associated with each return + code. + +- Usage + + This function is used to request the permission attributes for S-EL0 on a + memory region accessible from a Secure Partition. The size of the memory + region is equal to the Translation Granule size used in the Secure EL1&0 + translation regime. Requests to retrieve other memory region attributes are + not currently supported. + +- Caller responsibilities + + The caller must obtain the Translation Granule Size of the Secure EL1&0 + translation regime from the SPM through an implementation defined method. + +- Callee responsibilities + + The SPM must not return the memory access controls for a page of memory that + is not accessible from a Secure Partition. + +``MM_SP_MEMORY_ATTRIBUTES_SET_AARCH64`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Description + + Set the permission attributes of a memory region from S-EL0. + +- Parameters + + - **uint32** - Function ID + + - SVC64 Version: **0xC4000065** + + - **uint64** - Base Address + + This parameter is a 64-bit Virtual Address (VA). + + The alignment of the Base Address must be greater than or equal to the size + of the Translation Granule Size used in the Secure EL1&0 translation + regime. + + - **uint32** - Page count + + Number of pages starting from the Base Address whose memory attributes + should be changed. The page size is equal to the Translation Granule Size. + + - **uint32** - Memory Access Controls + + - Bits[1:0] : Data access permission + + - b'00 : No access + - b'01 : Read-Write access + - b'10 : Reserved + - b'11 : Read-only access + + - Bit[2] : Instruction access permission + + - b'0 : Executable + - b'1 : Non-executable + + - Bits[31:3] : Reserved. SBZ. + + A combination of attributes that mark the region with RW and Executable + permissions is prohibited. A request to mark a device memory region with + Executable permissions is prohibited. + +- Return parameters + + - **int32** - Return Code + + - ``SUCCESS``: The Memory Access Controls were changed successfully. + + - ``DENIED``: The SPM is servicing a request to change the attributes of a + memory region that overlaps with the region specified in this request. + + - ``INVALID_PARAMETER``: An invalid combination of Memory Access Controls + has been specified. The Base Address is not correctly aligned. The Secure + Partition is not allowed to access part or all of the memory region + specified in the call. + + - ``NO_MEMORY``: The SPM does not have memory resources to change the + attributes of the memory region in the translation tables. + + - ``NOT_SUPPORTED``: The SPM does not permit change of attributes of any + memory region that is accessible by the Secure Partition. Function was + called from the Non-secure world. Also returned if it is used after + ``MM_SP_EVENT_COMPLETE_AARCH64``. + + See `Error Codes`_ for integer values that are associated with each return + code. + +- Usage + + This function is used to change the permission attributes for S-EL0 on a + memory region accessible from a Secure Partition. The size of the memory + region is equal to the Translation Granule size used in the Secure EL1&0 + translation regime. Requests to change other memory region attributes are not + currently supported. + + This function is only available at boot time. This interface is revoked after + the Secure Partition sends the first ``MM_SP_EVENT_COMPLETE_AARCH64`` to + signal that it is initialised and ready to receive run-time requests. + +- Caller responsibilities + + The caller must obtain the Translation Granule Size of the Secure EL1&0 + translation regime from the SPM through an implementation defined method. + +- Callee responsibilities + + The SPM must preserve the original memory access controls of the region of + memory in case of an unsuccessful call.  The SPM must preserve the consistency + of the S-EL1 translation regime if this function is called on different PEs + concurrently and the memory regions specified overlap. + +Error Codes +----------- + +.. csv-table:: + :header: "Name", "Value" + + ``SUCCESS``,0 + ``NOT_SUPPORTED``,-1 + ``INVALID_PARAMETER``,-2 + ``DENIED``,-3 + ``NO_MEMORY``,-5 + ``NOT_PRESENT``,-7 + +-------------- + +*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.* + +.. _Armv8-A ARM: https://developer.arm.com/docs/ddi0487/latest/arm-architecture-reference-manual-armv8-for-armv8-a-architecture-profile +.. _instructions in the EDK2 repository: https://github.com/tianocore/edk2-staging/blob/AArch64StandaloneMm/HowtoBuild.MD +.. _Management Mode Interface Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf +.. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf +.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest + +.. |Image 1| image:: ../resources/diagrams/secure_sw_stack_tos.png +.. |Image 2| image:: ../resources/diagrams/secure_sw_stack_sp.png diff --git a/docs/components/secure-partition-manager.rst b/docs/components/secure-partition-manager.rst new file mode 100644 index 0000000..2169f30 --- /dev/null +++ b/docs/components/secure-partition-manager.rst @@ -0,0 +1,867 @@ +Secure Partition Manager +************************ + +.. contents:: + +Acronyms +======== + ++--------+-----------------------------------+ +| DTB | Device Tree Blob | ++--------+-----------------------------------+ +| DTS | Device Tree Source | ++--------+-----------------------------------+ +| EC | Execution Context | ++--------+-----------------------------------+ +| FIP | Firmware Image Package | ++--------+-----------------------------------+ +| FF-A | Firmware Framework for A-class | ++--------+-----------------------------------+ +| IPA | Intermediate Physical Address | ++--------+-----------------------------------+ +| NWd | Normal World | ++--------+-----------------------------------+ +| ODM | Original Design Manufacturer | ++--------+-----------------------------------+ +| OEM | Original Equipment Manufacturer | ++--------+-----------------------------------+ +| PA | Physical Address | ++--------+-----------------------------------+ +| PE | Processing Element | ++--------+-----------------------------------+ +| PVM | Primary VM | ++--------+-----------------------------------+ +| PSA | Platform Security Architecture | ++--------+-----------------------------------+ +| SP | Secure Partition | ++--------+-----------------------------------+ +| SPM | Secure Partition Manager | ++--------+-----------------------------------+ +| SPMC | SPM Core | ++--------+-----------------------------------+ +| SPMD | SPM Dispatcher | ++--------+-----------------------------------+ +| SiP | Silicon Provider | ++--------+-----------------------------------+ +| SWd | Secure World | ++--------+-----------------------------------+ +| TLV | Tag-Length-Value | ++--------+-----------------------------------+ +| TOS | Trusted Operating System | ++--------+-----------------------------------+ +| VM | Virtual Machine | ++--------+-----------------------------------+ + +Foreword +======== + +Two implementations of a Secure Partition Manager co-exist in the TF-A codebase: + +- SPM based on the PSA 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 PSA 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. + +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. + +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. + +Hence TF-A must support both cases where SPMC is either located 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. + +The same SPMD component is used to support both configurations. The SPMC +execution 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: + +.. 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] <#References>`__. +- **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) | ++------------------------------+----------------------+------------------+ + +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. + +Sample TF-A build command line when SPMC is located at S-EL1 +(typically pre-Armv8.4): + +.. code:: shell + + make \ + CROSS_COMPILE=aarch64-none-elf- \ + SPD=spmd \ + SPMD_SPM_AT_SEL2=0 \ + BL32= \ + BL33= \ + PLAT=fvp \ + all fip + +Sample TF-A build command line for an Armv8.4-SecEL2 enabled system +where SPMC is located at S-EL2: + +.. code:: shell + + make \ + CROSS_COMPILE=aarch64-none-elf- \ + SPD=spmd \ + CTX_INCLUDE_EL2_REGS=1 \ + ARM_ARCH_MINOR=4 \ + BL32= + BL33= \ + SP_LAYOUT_FILE=sp_layout.json \ + PLAT=fvp \ + all fip + +Build options to enable secure boot: + +.. code:: shell + + make \ + CROSS_COMPILE=aarch64-none-elf- \ + SPD=spmd \ + CTX_INCLUDE_EL2_REGS=1 \ + ARM_ARCH_MINOR=4 \ + BL32= + BL33= \ + SP_LAYOUT_FILE=../tf-a-tests/build/fvp/debug/sp_layout.json \ + MBEDTLS_DIR= \ + 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 + +Boot process +============ + +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: + +- 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. + +Booting through TF-A +-------------------- + +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 +provided by `[5]`_. A binding document is provided by `[6]`_. + +Secure Partition packages +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Secure Partitions are bundled as independent package files consisting +of: + +- 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: + +.. code:: shell + + Trusted Boot Firmware BL2: offset=0x1F0, size=0x8AE1, cmdline="--tb-fw" + EL3 Runtime Firmware BL31: offset=0x8CD1, size=0x13000, cmdline="--soc-fw" + Secure Payload BL32 (Trusted OS): offset=0x1BCD1, size=0x15270, cmdline="--tos-fw" + Non-Trusted Firmware BL33: offset=0x30F41, size=0x92E0, cmdline="--nt-fw" + HW_CONFIG: offset=0x3A221, size=0x2348, cmdline="--hw-config" + TB_FW_CONFIG: offset=0x3C569, size=0x37A, cmdline="--tb-fw-config" + SOC_FW_CONFIG: offset=0x3C8E3, size=0x48, cmdline="--soc-fw-config" + TOS_FW_CONFIG: offset=0x3C92B, size=0x427, cmdline="--tos-fw-config" + NT_FW_CONFIG: offset=0x3CD52, size=0x48, cmdline="--nt-fw-config" + B4B5671E-4A90-4FE1-B81F-FB13DAE1DACB: offset=0x3CD9A, size=0xC168, cmdline="--blob" + D1582309-F023-47B9-827C-4464F5578FC8: offset=0x48F02, size=0xC168, cmdline="--blob" + +.. uml:: ../resources/diagrams/plantuml/fip-secure-partitions.puml + +Specifying partition binary image and DT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +.. code:: shell + + { + "tee1" : { + "image": "tee1.bin", + "pm": "tee1.dts" + }, + + "tee2" : { + "image": "tee2.bin", + "pm": "tee2.dts" + } + } + +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. + +In this implementation its usage is extended to the secure physical FF-A +instance where SPMC executes at S-EL2. + +.. code:: shell + + attribute { + spmc_id = <0x8000>; + maj_ver = <0x1>; + min_ver = <0x0>; + exec_state = <0x0>; + load_address = <0x0 0x6000000>; + entrypoint = <0x0 0x6000000>; + 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``) + +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. + +SPMC boot +~~~~~~~~~ + +The SPMC is loaded by BL2 as the BL32 image. + +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. + +Loading of SPs +~~~~~~~~~~~~~~ + +.. 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. + +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. +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]`_): + +- SPMC(BL32), SPMC manifest, SPs may be signed by the SiP using the S-ROTPK. +- BL33 may be signed by the 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. + +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. + +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. + +With the FF-A EAC specification, Secure Partitions are scheduled by direct +message invocations from a NWd VM or another SP. + +Platform topology +~~~~~~~~~~~~~~~~~ + +As stated in `[1]`_ section 4.4.1 the SPMC implementation assumes 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. + +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. + +The SP manifest may contain memory and device regions nodes. + +- 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) + +Base addresses for memory and device region nodes are IPAs provided SPMC +identity maps IPAs to PAs within SP 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) +provides a memory security attribute hinting to map either to the secure or +non-secure stage-2 table. + +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). + +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. + +SP Boot order +------------- + +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. + +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 PSA-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. + +Mandatory interfaces +-------------------- + +The following interfaces must be exposed to any VM or SP: + +- ``FFA_STATUS`` +- ``FFA_ERROR`` +- ``FFA_INTERRUPT`` +- ``FFA_VERSION`` +- ``FFA_FEATURES`` +- ``FFA_RX_RELEASE`` +- ``FFA_RXTX_MAP`` +- ``FFA_RXTX_UNMAP`` +- ``FFA_PARTITION_INFO_GET`` +- ``FFA_ID_GET`` + +FFA_VERSION +~~~~~~~~~~~ + +Per `[1]`_ section 8.1 ``FFA_VERSION`` requires a +*requested_version* parameter from 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. + +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. + +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. + +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. + +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. + +FFA_PARTITION_INFO_GET +~~~~~~~~~~~~~~~~~~~~~~ + +Partition info get service call can originate: + +- from SP to SPM +- from VM to Hypervisor +- from Hypervisor to SPM + +For the latter case, the service call must be forwarded through the SPMD. + +FFA_ID_GET +~~~~~~~~~~ + +The SPMD returns: + +- 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`_) + +The FF-A id space is split into a non-secure space and secure space: + +- FF-A id with bit 15 clear refer to normal world VMs. +- FF-A id with bit 15 set refer to secure world SPs + +Such convention helps the SPMC discriminating the origin and destination worlds +in an FF-A service 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: + +- 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. + +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". + +Direct messaging +---------------- + +This is a mandatory interface for Secure Partitions consisting in direct +message request and responses. + +The ``ffa_handler`` Hafnium function may: + +- 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. + +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. + +VM-to-SP +~~~~~~~~ + +- A VM can send a direct message request to an SP +- An SP can send a direct message response to a VM + +SPMC-SPMD messaging +~~~~~~~~~~~~~~~~~~~ + +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. + +Per `[1]`_ Table 114 Config No. 1 (physical FF-A instance): + +- 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 +----------------- + +This section only deals with the PE MMU configuration. + +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 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 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: + +- 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. + +Interrupt management +-------------------- + +Road to a para-virtualized interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 short-term plan is to have Hafnium/SPMC in the secure world owner +of the GIC configuration. + +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. + +Notice the SPMC/SPMD has to handle Group0 secure interrupts in addition +to Group1 S/NS interrupts. + +Power management +---------------- + +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 +--------------- + +Power management notifications are conveyed from PSCI library to the +SPMD / SPD hooks. A range of events can be relayed to SPMC. + +SPs may need to be notified about specific PM events. + +- 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 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. + +References +========== + +.. _[1]: + +[1] `Platform Security Architecture Firmware Framework for Arm® v8-A 1.0 Platform Design Document `__ + +.. _[2]: + +[2] `Secure Partition Manager using MM interface`__ + +.. __: secure-partition-manager-mm.html + +.. _[3]: + +[3] `Trusted Boot Board Requirements +Client `__ + +.. _[4]: + +[4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/lib/el3_runtime/aarch64/context.S#n45 + +.. _[5]: + +[5] https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/spm/cactus/cactus.dts + +.. _[6]: + +[6] https://trustedfirmware-a.readthedocs.io/en/latest/components/psa-ffa-manifest-binding.html + +.. _[7]: + +[7] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_spmc_manifest.dts + +.. _[8]: + +[8] https://developer.trustedfirmware.org/w/tf_a/poc-multiple-signing-domains/ + +-------------- + +*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/resources/diagrams/ff-a-spm-sel2.png b/docs/resources/diagrams/ff-a-spm-sel2.png new file mode 100644 index 0000000..6479ff5 --- /dev/null +++ b/docs/resources/diagrams/ff-a-spm-sel2.png Binary files differ diff --git a/docs/resources/diagrams/plantuml/bl2-loading-sp.puml b/docs/resources/diagrams/plantuml/bl2-loading-sp.puml new file mode 100644 index 0000000..3cf7c36 --- /dev/null +++ b/docs/resources/diagrams/plantuml/bl2-loading-sp.puml @@ -0,0 +1,44 @@ +/' + ' Copyright (c) 2020, ARM Limited and Contributors. All rights reserved. + ' + ' SPDX-License-Identifier: BSD-3-Clause + '/ + +@startuml +participant bl1 +participant FIP + +bl1 -> FIP : read(FW_CONFIG) +create FW_CONFIG +bl1 -> FW_CONFIG : load + +bl1 -> FIP : read(bl2) +create bl2 +bl1 -> bl2 : load +bl1 --> bl2 : hand off (FW_CONFIG) + +bl2 -> FW_CONFIG : read_node(SPKs) +loop for each spkg subnode + bl2 -> FW_CONFIG : read(UUID) + bl2 -> FW_CONFIG : read(load_address) + bl2 -> FIP : read(spkg@UUID) + create SPKG + bl2 -> SPKG : load +end loop + +bl2 -> FW_CONFIG : read_node(TOS_FW_CONFIG) +create TOS_FW_CONFIG +bl2 -> TOS_FW_CONFIG : load + +bl2 -> FIP : read(bl32/SPMC) +create SPMC +bl2 -> SPMC : load + +bl2 -> FIP : read(bl31) +create bl31 +bl2 -> bl31 : load +bl2 --> bl31 : hand off (TOS_FW_CONFIG) + +bl31 --> SPMC : hand off (TOS_FW_CONFIG) + +@enduml diff --git a/docs/resources/diagrams/plantuml/fip-secure-partitions.puml b/docs/resources/diagrams/plantuml/fip-secure-partitions.puml new file mode 100644 index 0000000..40621db --- /dev/null +++ b/docs/resources/diagrams/plantuml/fip-secure-partitions.puml @@ -0,0 +1,122 @@ +/' + ' Copyright (c) 2020, ARM Limited and Contributors. All rights reserved. + ' + ' SPDX-License-Identifier: BSD-3-Clause + '/ + +@startuml + +folder SP_vendor_1 { + artifact sp_binary_1 + artifact sp_manifest_1 [ + sp_manifest_1 + === + UUID = xxx + load_address = 0xaaa + ... + ] +} + +folder SP_vendor_2 { + artifact sp_binary_2 + artifact sp_manifest_2 [ + sp_manifest_2 + === + UUID = yyy + load_address = 0xbbb + ] +} + +artifact config.json [ + SP_LAYOUT.json + === + path to sp_binary_1 + path to sp_manifest_1 + --- + path to sp_binary_2 + path to sp_manifest_2 + --- + ... +] + +control sp_mk_generator + +artifact fconf_node [ + fconf_sp.dts + === + spkg_1 UUID + spkg_1 load_address + --- + spkg_2 UUID + spkg_2 load_address +] + +artifact sp_gen [ + sp_gen.mk + === + FDT_SOURCE = ... + SPTOOL_ARGS = ... + FIP_ARG = ... +] + +control dtc +control sptool + +artifact FW_CONFIG + +artifact spkg_1 [ + spkg_1.bin + === + header + --- + manifest + --- + binary +] + +artifact spkg_2 [ + spkg_2.bin + === + header + --- + manifest + --- + binary +] + +control fiptool + +artifact fip [ + fip.bin + === + FW_CONFIG.dtb + --- + ... + --- + SPKG1 + --- + SPKG2 + --- + ... +] + +config.json .up.> SP_vendor_1 +config.json .up.> SP_vendor_2 +config.json --> sp_mk_generator +sp_mk_generator --> fconf_node +sp_mk_generator --> sp_gen + +sp_gen --> sptool +sptool --> spkg_1 +sptool --> spkg_2 + +fconf_node -down-> dtc +dtc --> FW_CONFIG + +sp_gen --> fiptool +FW_CONFIG --> fiptool +spkg_1 -down-> fiptool +spkg_2 -down-> fiptool +fiptool -down-> fip + +@enduml