Lines Matching refs:the
7 This document describes the implementation where the Secure Partition Manager
9 S-EL0. The communication protocol is established through the Management Mode
18 authentication. The Global Platform TEE Client API specification defines the API
20 fulfils the requirements of a security service as described above.
22 Management services are typically implemented at the highest level of privilege
23 in the system, i.e. EL3 in Trusted Firmware-A (TF-A). The service requirements are
24 fulfilled by the execution environment provided by TF-A.
26 The following diagram illustrates the corresponding software stack:
31 centres and enterprise servers) the secure software stack typically does not
47 resources. Essentially, it is a software sandbox in the Secure world that runs
48 under the control of privileged software, provides one or more services and
49 accesses the following system resources:
51 - Memory and device regions in the system address map.
59 A Secure Partition enables TF-A to implement only the essential secure
60 services in EL3 and instantiate the rest in a partition in S-EL0.
64 The following diagram illustrates the place of a Secure Partition in a typical
66 services to software components in the Non-secure world and other Secure
71 The TF-A build system is responsible for including the Secure Partition image
72 in the FIP. During boot, BL2 includes support to authenticate and load the
74 (SPM)** is responsible for managing the partition. This is semantically
77 The SPM is responsible for the following actions during boot:
79 - Allocate resources requested by the Secure Partition.
81 - Perform architectural and system setup required by the Secure Partition to
87 The SPM is responsible for the following actions during runtime:
92 - Implement a standard interface that is used by the Non-secure world for
93 accessing the services exported by a Secure Partition. A service can be
97 the control of the SPM. Hence common programming concepts described below are
103 The previous section introduced some general aspects of the software
104 architecture of a Secure Partition. This section describes the specific choices
105 made in the current implementation of this software architecture. Subsequent
106 revisions of the implementation will include a richer set of features that
112 SPM is supported on the Arm FVP exclusively at the moment. The current
114 service always runs to completion (e.g. the requested services cannot be
115 preempted to give control back to the Normal world).
118 Payload Dispatcher (SPD) at the same time; they are mutually exclusive. In the
119 SPM bootflow, a Secure Partition image executing at S-EL0 replaces the Secure
123 A working prototype of a SP has been implemented by re-purposing the EDK2 code
124 and tools, leveraging the concept of the *Standalone Management Mode (MM)* in
125 the UEFI specification (see the PI v1.6 Volume 4: Management Mode Core
126 Interface). This will be referred to as the *Standalone MM Secure Partition* in
127 the rest of this document.
129 To enable SPM support in TF-A, the source code must be compiled with the build
131 On Arm platforms the build option ``ARM_BL31_IN_DRAM`` must be set to 1. Also, the
132 location of the binary that contains the BL32 image
135 First, build the Standalone MM Secure Partition. To build it, refer to the
136 `instructions in the EDK2 repository`_.
138 Then build TF-A with SPM support and include the Standalone MM Secure Partition
139 image in the FIP:
149 TF-A exports a porting interface that enables a platform to specify the system
150 resources required by the Secure Partition. Some instructions are given below.
154 - A Secure Partition is considered a BL32 image, so the same defines that apply
157 - The following defines are needed to allocate space for the translation tables
158 used by the Secure Partition: ``PLAT_SP_IMAGE_MMAP_REGIONS`` and
163 ``plat/arm/board/fvp/fvp_common.c`` can be used as an example. It uses the
167 describe the memory regions that the SPM needs to allocate for a Secure
171 ``spm_mm_boot_info_t`` struct that is populated by the platform
172 with information about the memory map of the Secure Partition.
174 For an example of all the changes in context, you may refer to commit
175 ``e29efeb1b4``, in which the port for FVP was introduced.
181 accessing services implemented in the Secure world. The ``MM_COMMUNICATE``
182 interface defined in the `Management Mode Interface Specification`_ (*Arm DEN
185 The mechanism used to identify a service within the partition depends on the
186 service implementation. It is assumed that the caller of the service will be
190 used to identify a management mode service. A client populates the GUID in the
191 ``EFI_MM_COMMUNICATE_HEADER``. The header is populated in the communication
192 buffer shared with the Secure Partition.
194 A Fast Call appears to be atomic from the perspective of the caller and returns
195 when the requested operation has completed. A service invoked through the
196 ``MM_COMMUNICATE`` SMC will run to completion in the partition on a given CPU.
200 Exchanging data with the Secure Partition
203 The exchange of data between the Non-secure world and the partition takes place
204 through a shared memory region. The location of data in the shared memory area
205 is passed as a parameter to the ``MM_COMMUNICATE`` SMC. The shared memory area
206 is statically allocated by the SPM and is expected to be either implicitly known
207 to the Non-secure world or discovered through a platform discovery mechanism
208 e.g. ACPI table or device tree. It is possible for the Non-secure world to
210 memory area. The shared memory area is implemented as per the guidelines
211 specified in Section 3.2.3 of the `Management Mode Interface Specification`_
214 The format of data structures used to encapsulate data in the shared memory is
215 agreed between the Non-secure world and the Secure Partition. For example, in
216 the `Management Mode Interface specification`_ (*Arm DEN 0060A*), Section 4
217 describes that the communication buffer shared between the Non-secure world and
218 the Management Mode (MM) in the Secure world must be of the type
221 Any caller of a MM service will have to use the ``EFI_MM_COMMUNICATE_HEADER``
224 Runtime model of the Secure Partition
227 This section describes how the Secure Partition interfaces with the SPM.
232 In order to instantiate one or more secure services in the Secure Partition in
233 S-EL0, the SPM should define the following types of interfaces:
237 amongst multiple software components in the Secure world or cannot be directly
240 - Interfaces that establish the control path between the SPM and the Secure
243 This section describes the APIs currently exported by the SPM that enable a
245 interfaces are not accessible from the Non-secure world.
250 The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the SMC
252 depending on the implemented Exception levels. In S-EL0, the Supervisor Call
253 exception (SVC) is the only architectural mechanism available for unprivileged
255 Hence, the SVC conduit must be used by the Secure Partition to access interfaces
256 implemented by the SPM.
260 from a Secure Partition as a SMC request to the SPM in EL3. Upon servicing the
267 The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the
268 32-bit and 64-bit calling conventions for the SMC and HVC conduits. The SVC
269 conduit introduces the concept of SVC32 and SVC64 calling conventions. The SVC32
270 and SVC64 calling conventions are equivalent to the 32-bit (SMC32) and the
276 A service request is initiated from the SPM through an exception return
277 instruction (ERET) to S-EL0. Later, the Secure Partition issues an SVC
278 instruction to signal completion of the request. Some example use cases are
281 - A request to initialise the Secure Partition during system boot.
288 A request is initiated from the Secure Partition by executing a SVC instruction.
289 An ERET instruction is used by TF-A to return to S-EL0 with the result of the
293 partition (e.g. management of memory attributes in the translation tables for
294 the Secure EL1&0 translation regime).
299 The current implementation reserves function IDs for Fast Calls in the Standard
301 specification) for each API exported by the SPM. This section defines the
303 or both of the SVC32 and SVC64 calling conventions can be used to invoke the
309 The Secure Partition provides an Event Management interface that is used by the
310 SPM to delegate service requests to the Secure Partition. The interface also
311 allows the Secure Partition to:
313 - Register with the SPM a service that it provides.
314 - Indicate completion of a service request delegated by the SPM
324 Returns the version of the interface exported by SPM.
336 On success, the format of the value is as follows:
339 - Bits [30:16]: Major Version. Must be 0 for this revision of the SPM
341 - Bits [15:0]: Minor Version. Must be 1 for this revision of the SPM
344 On error, the format of the value is as follows:
346 - ``NOT_SUPPORTED``: SPM interface is not supported or not available for the
351 This function returns the version of the Secure Partition Manager
352 implementation. The major version is 0 and the minor version is 1. The version
353 number is a 31-bit unsigned integer, with the upper 15 bits denoting the major
354 revision, and the lower 16 bits denoting the minor revision. The following
355 rules apply to the version numbering:
359 - For two revisions, A and B, for which the major revision values are
360 identical, if the minor revision value of revision B is greater than the
367 If this function returns a valid version number, all the functions that are
377 The SPM is responsible for initialising the architectural execution context to
378 enable initialisation of a service in S-EL0. The responsibilities of the SPM are
379 listed below. At the end of initialisation, the partition issues a
381 handling requests for services implemented by the Secure Partition. The
388 used as the target of the ERET instruction to start initialisation of the Secure
395 state unless otherwise specified. The SPM will perform the following
401 The platform port of a Secure Partition specifies to the SPM a list of regions
403 description and initialises the Secure EL1&0 translation regime as follows.
417 5. If the resource description does not explicitly describe the type of memory
427 System registers that influence software execution in S-EL0 are setup by the SPM
460 SPM will invoke the entry point of a service by executing an ERET instruction.
462 request through a SVC instruction. This is the first entry into S-EL0. The
463 general purpose register usage at the time of entry will be as specified in the
465 calls" of the `SMC Calling Convention`_ (*Arm DEN 0028B*) specification. In
470 A non-zero value will indicate that the SPM has initialised the stack pointer
471 for the current CPU.
481 Parameters passed by the SPM.
484 buffer will be mapped in the Secure EL1&0 translation regime with read-only
487 - ``X1``: Size of the buffer in bytes.
497 invocation (i.e. a SMC from the Non-secure world). These requests are delegated
498 to the partition by programming a return from the last
499 ``MM_SP_EVENT_COMPLETE_AARCH64`` call received from the partition. The last call
508 Signal completion of the last SP service request.
518 Zero or a positive value indicates that the event was handled successfully.
519 The values depend upon the original event that was delegated to the Secure
522 - ``SUCCESS`` : Used to indicate that the Secure Partition was initialised
529 on the original event.
535 Zero or a positive value specifies the unique ID of the event being
536 delegated to the partition by the SPM.
538 In the current implementation, this parameter contains the function ID of
539 the ``MM_COMMUNICATE`` SMC. This value indicates to the partition that an
541 from the Non-secure world.
543 A negative value indicates an error. The format of the value is as follows:
545 - ``NOT_SUPPORTED``: Function was called from the Non-secure world.
552 Address of a buffer shared between the SPM and Secure Partition to pass
553 event specific information. The format of the data populated in the buffer
556 The buffer is mapped in the Secure EL1&0 translation regime with read-only
559 For the SVC64 version, this parameter is a 64-bit Virtual Address (VA).
561 For the SVC32 version, this parameter is a 32-bit Virtual Address (VA).
565 Size of the memory starting at Event Address.
573 This function signals to the SPM that the handling of the last event delegated
575 A return from this function is in response to the next event that will be
576 delegated to the partition. The return parameters describe the next event.
581 completion of a request that was delegated to it by the SPM.
585 When the SPM receives this call from a Secure Partition, the corresponding
587 instruction, to the instruction immediately after the call in the Secure
589 system register values when the call was made.
591 The SPM must save this syndrome information and use it to delegate the next
592 event to the Secure Partition. The return parameters of this interface must
593 specify the properties of the event and be populated in ``X0-X3/W0-W3``
600 The SPM is responsible for enabling access to regions of memory in the system
602 the Secure EL1&0 Translation regime with appropriate memory attributes.
604 attributes used in the Translation tables. The definitions of these attributes
605 and their usage can be found in the `Armv8-A ARM`_ (*Arm DDI 0487*).
607 All memory required by the Secure Partition is allocated upfront in the SPM,
608 even before handing over to the Secure Partition for the first time. The initial
609 access permissions of the memory regions are statically provided by the platform
610 port and should allow the Secure Partition to run its initialisation code.
612 However, they might not suit the final needs of the Secure Partition because its
613 final memory layout might not be known until the Secure Partition initialises
614 itself. As the Secure Partition initialises its runtime environment it might,
618 a part of the Secure Partition image. The location of various sections in an
620 data and code) will be known only when the file is loaded into memory.
622 In this case, the Secure Partition needs a way to change the access permissions
623 of its memory regions. The SPM provides this feature through the
625 available to the Secure Partition during a specific time window: from the first
626 entry into the Secure Partition up to the first ``SP_EVENT_COMPLETE`` call that
627 signals the Secure Partition has finished its initialisation. Once the
628 initialisation is complete, the SPM does not allow changes to the memory
631 This section describes the standard SVC interface that is implemented by the SPM
640 Request the permission attributes of a memory region from S-EL0.
652 There are no alignment restrictions on the Base Address. The permission
653 attributes of the translation granule it lies in are returned.
657 This parameter is the number of translation granule size pages from
666 On success the format of the Return Code is as follows:
684 On failure the following error codes are returned:
686 - ``INVALID_PARAMETERS``: The Secure Partition is not allowed to access the
687 memory region the Base Address lies in.
690 any memory page that is accessible by the Secure Partition, or the
691 function was called from the Non-secure world. Also returned if it is
699 On success, the number of translation granule size pages from
700 the *Base address* whose permissions match those returned in the
709 This function is used to request the permission attributes for S-EL0 on a
710 memory region accessible from a Secure Partition. The size of the memory
711 region is equal to the Translation Granule size used in the Secure EL1&0
717 The caller must obtain the Translation Granule Size of the Secure EL1&0
718 translation regime from the SPM through an implementation defined method.
722 The SPM must not return the memory access controls for a page of memory that
730 Set the permission attributes of a memory region from S-EL0.
742 The alignment of the Base Address must be greater than or equal to the size
743 of the Translation Granule Size used in the Secure EL1&0 translation
748 Number of pages starting from the Base Address whose memory attributes
749 should be changed. The page size is equal to the Translation Granule Size.
767 A combination of attributes that mark the region with RW and Executable
777 - ``DENIED``: The SPM is servicing a request to change the attributes of a
778 memory region that overlaps with the region specified in this request.
782 Partition is not allowed to access part or all of the memory region
783 specified in the call.
785 - ``NO_MEMORY``: The SPM does not have memory resources to change the
786 attributes of the memory region in the translation tables.
789 memory region that is accessible by the Secure Partition. Function was
790 called from the Non-secure world. Also returned if it is used after
798 This function is used to change the permission attributes for S-EL0 on a
799 memory region accessible from a Secure Partition. The size of the memory
800 region is equal to the Translation Granule size used in the Secure EL1&0
805 the Secure Partition sends the first ``MM_SP_EVENT_COMPLETE_AARCH64`` to
810 The caller must obtain the Translation Granule Size of the Secure EL1&0
811 translation regime from the SPM through an implementation defined method.
815 The SPM must preserve the original memory access controls of the region of
816 memory in case of an unsuccessful call. The SPM must preserve the consistency
817 of the S-EL1 translation regime if this function is called on different PEs
818 concurrently and the memory regions specified overlap.
838 .. _instructions in the EDK2 repository: https://github.com/tianocore/edk2-staging/blob/AArch64Stan…