blob: 4f6718594cb2c24fc067567049ff73df7c756e3e [file] [log] [blame]
Paul Beesleyfc9ee362019-03-07 15:47:15 +00001Secure Partition Manager
2************************
Antonio Nino Diaz352c8522017-12-15 11:41:17 +00003
Antonio Nino Diaz352c8522017-12-15 11:41:17 +00004Background
5==========
6
7In some market segments that primarily deal with client-side devices like mobile
8phones, tablets, STBs and embedded devices, a Trusted OS instantiates trusted
9applications to provide security services like DRM, secure payment and
10authentication. The Global Platform TEE Client API specification defines the API
11used by Non-secure world applications to access these services. A Trusted OS
12fulfils the requirements of a security service as described above.
13
14Management services are typically implemented at the highest level of privilege
Dan Handley610e7e12018-03-01 18:44:00 +000015in the system, i.e. EL3 in Trusted Firmware-A (TF-A). The service requirements are
16fulfilled by the execution environment provided by TF-A.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +000017
18The following diagram illustrates the corresponding software stack:
19
20|Image 1|
21
22In other market segments that primarily deal with server-side devices (e.g. data
23centres and enterprise servers) the secure software stack typically does not
24include a Global Platform Trusted OS. Security functions are accessed through
25other interfaces (e.g. ACPI TCG TPM interface, UEFI runtime variable service).
26
27Placement of management and security functions with diverse requirements in a
28privileged Exception Level (i.e. EL3 or S-EL1) makes security auditing of
29firmware more difficult and does not allow isolation of unrelated services from
30each other either.
31
32Introduction
33============
34
35A **Secure Partition** is a software execution environment instantiated in
36S-EL0 that can be used to implement simple management and security services.
37Since S-EL0 is an unprivileged Exception Level, a Secure Partition relies on
Dan Handley610e7e12018-03-01 18:44:00 +000038privileged firmware (i.e. TF-A) to be granted access to system and processor
39resources. Essentially, it is a software sandbox in the Secure world that runs
40under the control of privileged software, provides one or more services and
41accesses the following system resources:
Antonio Nino Diaz352c8522017-12-15 11:41:17 +000042
43- Memory and device regions in the system address map.
44
45- PE system registers.
46
47- A range of synchronous exceptions (e.g. SMC function identifiers).
48
Dan Handley610e7e12018-03-01 18:44:00 +000049Note that currently TF-A only supports handling one Secure Partition.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +000050
Dan Handley610e7e12018-03-01 18:44:00 +000051A Secure Partition enables TF-A to implement only the essential secure
52services in EL3 and instantiate the rest in a partition in S-EL0.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +000053Furthermore, multiple Secure Partitions can be used to isolate unrelated
54services from each other.
55
56The following diagram illustrates the place of a Secure Partition in a typical
Dan Handley610e7e12018-03-01 18:44:00 +000057Armv8-A software stack. A single or multiple Secure Partitions provide secure
Antonio Nino Diaz352c8522017-12-15 11:41:17 +000058services to software components in the Non-secure world and other Secure
59Partitions.
60
61|Image 2|
62
Dan Handley610e7e12018-03-01 18:44:00 +000063The TF-A build system is responsible for including the Secure Partition image
64in the FIP. During boot, BL2 includes support to authenticate and load the
65Secure Partition image. A BL31 component called **Secure Partition Manager
66(SPM)** is responsible for managing the partition. This is semantically
Antonio Nino Diaz352c8522017-12-15 11:41:17 +000067similar to a hypervisor managing a virtual machine.
68
69The SPM is responsible for the following actions during boot:
70
71- Allocate resources requested by the Secure Partition.
72
73- Perform architectural and system setup required by the Secure Partition to
74 fulfil a service request.
75
76- Implement a standard interface that is used for initialising a Secure
77 Partition.
78
79The SPM is responsible for the following actions during runtime:
80
81- Implement a standard interface that is used by a Secure Partition to fulfil
82 service requests.
83
84- Implement a standard interface that is used by the Non-secure world for
85 accessing the services exported by a Secure Partition. A service can be
86 invoked through a SMC.
87
88Alternatively, a partition can be viewed as a thread of execution running under
89the control of the SPM. Hence common programming concepts described below are
90applicable to a partition.
91
92Description
93===========
94
95The previous section introduced some general aspects of the software
96architecture of a Secure Partition. This section describes the specific choices
97made in the current implementation of this software architecture. Subsequent
98revisions of the implementation will include a richer set of features that
99enable a more flexible architecture.
100
Dan Handley610e7e12018-03-01 18:44:00 +0000101Building TF-A with Secure Partition support
102-------------------------------------------
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000103
104SPM is supported on the Arm FVP exclusively at the moment. The current
105implementation supports inclusion of only a single Secure Partition in which a
106service always runs to completion (e.g. the requested services cannot be
107preempted to give control back to the Normal world).
108
109It is not currently possible for BL31 to integrate SPM support and a Secure
110Payload Dispatcher (SPD) at the same time; they are mutually exclusive. In the
111SPM bootflow, a Secure Partition image executing at S-EL0 replaces the Secure
112Payload image executing at S-EL1 (e.g. a Trusted OS). Both are referred to as
113BL32.
114
115A working prototype of a SP has been implemented by re-purposing the EDK2 code
116and tools, leveraging the concept of the *Standalone Management Mode (MM)* in
117the UEFI specification (see the PI v1.6 Volume 4: Management Mode Core
118Interface). This will be referred to as the *Standalone MM Secure Partition* in
119the rest of this document.
120
Dan Handley610e7e12018-03-01 18:44:00 +0000121To enable SPM support in TF-A, the source code must be compiled with the build
Manish Pandey24dbf3a2020-01-22 16:02:57 +0000122flag ``SPM_MM=1``, along with ``EL3_EXCEPTION_HANDLING=1``. On Arm
Sughosh Ganudf4db9c2018-11-14 10:40:33 +0530123platforms the build option ``ARM_BL31_IN_DRAM`` must be set to 1. Also, the
124location of the binary that contains the BL32 image
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000125(``BL32=path/to/image.bin``) must be specified.
126
127First, build the Standalone MM Secure Partition. To build it, refer to the
128`instructions in the EDK2 repository`_.
129
Dan Handley610e7e12018-03-01 18:44:00 +0000130Then build TF-A with SPM support and include the Standalone MM Secure Partition
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000131image in the FIP:
132
Paul Beesley493e3492019-03-13 15:11:04 +0000133.. code:: shell
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000134
135 BL32=path/to/standalone/mm/sp BL33=path/to/bl33.bin \
Manish Pandey24dbf3a2020-01-22 16:02:57 +0000136 make PLAT=fvp SPM_MM=1 EL3_EXCEPTION_HANDLING=1 ARM_BL31_IN_DRAM=1 all fip
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000137
138Describing Secure Partition resources
139-------------------------------------
140
Dan Handley610e7e12018-03-01 18:44:00 +0000141TF-A exports a porting interface that enables a platform to specify the system
142resources required by the Secure Partition. Some instructions are given below.
143However, this interface is under development and it may change as new features
144are implemented.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000145
146- A Secure Partition is considered a BL32 image, so the same defines that apply
147 to BL32 images apply to a Secure Partition: ``BL32_BASE`` and ``BL32_LIMIT``.
148
149- The following defines are needed to allocate space for the translation tables
150 used by the Secure Partition: ``PLAT_SP_IMAGE_MMAP_REGIONS`` and
151 ``PLAT_SP_IMAGE_MAX_XLAT_TABLES``.
152
153- The functions ``plat_get_secure_partition_mmap()`` and
154 ``plat_get_secure_partition_boot_info()`` have to be implemented. The file
155 ``plat/arm/board/fvp/fvp_common.c`` can be used as an example. It uses the
156 defines in ``include/plat/arm/common/arm_spm_def.h``.
157
158 - ``plat_get_secure_partition_mmap()`` returns an array of mmap regions that
159 describe the memory regions that the SPM needs to allocate for a Secure
160 Partition.
161
162 - ``plat_get_secure_partition_boot_info()`` returns a
Paul Beesley45f40282019-10-15 10:57:42 +0000163 ``spm_mm_boot_info_t`` struct that is populated by the platform
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000164 with information about the memory map of the Secure Partition.
165
166For an example of all the changes in context, you may refer to commit
167``e29efeb1b4``, in which the port for FVP was introduced.
168
169Accessing Secure Partition services
170-----------------------------------
171
Dan Handley610e7e12018-03-01 18:44:00 +0000172The `SMC Calling Convention`_ (*Arm DEN 0028B*) describes SMCs as a conduit for
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000173accessing services implemented in the Secure world. The ``MM_COMMUNICATE``
Dan Handley610e7e12018-03-01 18:44:00 +0000174interface defined in the `Management Mode Interface Specification`_ (*Arm DEN
Antonio Nino Diaz352c8522017-12-15 11:41:17 +00001750060A*) is used to invoke a Secure Partition service as a Fast Call.
176
177The mechanism used to identify a service within the partition depends on the
178service implementation. It is assumed that the caller of the service will be
179able to discover this mechanism through standard platform discovery mechanisms
180like ACPI and Device Trees. For example, *Volume 4: Platform Initialisation
181Specification v1.6. Management Mode Core Interface* specifies that a GUID is
182used to identify a management mode service. A client populates the GUID in the
183``EFI_MM_COMMUNICATE_HEADER``. The header is populated in the communication
184buffer shared with the Secure Partition.
185
186A Fast Call appears to be atomic from the perspective of the caller and returns
187when the requested operation has completed. A service invoked through the
188``MM_COMMUNICATE`` SMC will run to completion in the partition on a given CPU.
189The SPM is responsible for guaranteeing this behaviour. This means that there
190can only be a single outstanding Fast Call in a partition on a given CPU.
191
192Exchanging data with the Secure Partition
193-----------------------------------------
194
195The exchange of data between the Non-secure world and the partition takes place
196through a shared memory region. The location of data in the shared memory area
197is passed as a parameter to the ``MM_COMMUNICATE`` SMC. The shared memory area
198is statically allocated by the SPM and is expected to be either implicitly known
199to the Non-secure world or discovered through a platform discovery mechanism
200e.g. ACPI table or device tree. It is possible for the Non-secure world to
201exchange data with a partition only if it has been populated in this shared
202memory area. The shared memory area is implemented as per the guidelines
203specified in Section 3.2.3 of the `Management Mode Interface Specification`_
Dan Handley610e7e12018-03-01 18:44:00 +0000204(*Arm DEN 0060A*).
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000205
206The format of data structures used to encapsulate data in the shared memory is
207agreed between the Non-secure world and the Secure Partition. For example, in
Dan Handley610e7e12018-03-01 18:44:00 +0000208the `Management Mode Interface specification`_ (*Arm DEN 0060A*), Section 4
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000209describes that the communication buffer shared between the Non-secure world and
210the Management Mode (MM) in the Secure world must be of the type
211``EFI_MM_COMMUNICATE_HEADER``. This data structure is defined in *Volume 4:
212Platform Initialisation Specification v1.6. Management Mode Core Interface*.
213Any caller of a MM service will have to use the ``EFI_MM_COMMUNICATE_HEADER``
214data structure.
215
216Runtime model of the Secure Partition
217=====================================
218
219This section describes how the Secure Partition interfaces with the SPM.
220
221Interface with SPM
222------------------
223
224In order to instantiate one or more secure services in the Secure Partition in
225S-EL0, the SPM should define the following types of interfaces:
226
227- Interfaces that enable access to privileged operations from S-EL0. These
228 operations typically require access to system resources that are either shared
229 amongst multiple software components in the Secure world or cannot be directly
230 accessed from an unprivileged Exception Level.
231
232- Interfaces that establish the control path between the SPM and the Secure
233 Partition.
234
235This section describes the APIs currently exported by the SPM that enable a
236Secure Partition to initialise itself and export its services in S-EL0. These
237interfaces are not accessible from the Non-secure world.
238
239Conduit
240^^^^^^^
241
Dan Handley610e7e12018-03-01 18:44:00 +0000242The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the SMC
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000243and HVC conduits for accessing firmware services and their availability
244depending on the implemented Exception levels. In S-EL0, the Supervisor Call
245exception (SVC) is the only architectural mechanism available for unprivileged
246software to make a request for an operation implemented in privileged software.
247Hence, the SVC conduit must be used by the Secure Partition to access interfaces
248implemented by the SPM.
249
Dan Handley610e7e12018-03-01 18:44:00 +0000250A SVC causes an exception to be taken to S-EL1. TF-A assumes ownership of S-EL1
251and installs a simple exception vector table in S-EL1 that relays a SVC request
252from a Secure Partition as a SMC request to the SPM in EL3. Upon servicing the
John Tsichritzis63801cd2019-07-05 14:22:12 +0100253SMC request, Trusted Firmware-A returns control directly to S-EL0 through an
Dan Handley610e7e12018-03-01 18:44:00 +0000254ERET instruction.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000255
256Calling conventions
257^^^^^^^^^^^^^^^^^^^
258
Dan Handley610e7e12018-03-01 18:44:00 +0000259The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the
Antonio Nino Diaz352c8522017-12-15 11:41:17 +000026032-bit and 64-bit calling conventions for the SMC and HVC conduits. The SVC
261conduit introduces the concept of SVC32 and SVC64 calling conventions. The SVC32
262and SVC64 calling conventions are equivalent to the 32-bit (SMC32) and the
26364-bit (SMC64) calling conventions respectively.
264
265Communication initiated by SPM
266^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
267
268A service request is initiated from the SPM through an exception return
269instruction (ERET) to S-EL0. Later, the Secure Partition issues an SVC
270instruction to signal completion of the request. Some example use cases are
271given below:
272
273- A request to initialise the Secure Partition during system boot.
274
275- A request to handle a runtime service request.
276
277Communication initiated by Secure Partition
278^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
279
280A request is initiated from the Secure Partition by executing a SVC instruction.
Dan Handley610e7e12018-03-01 18:44:00 +0000281An ERET instruction is used by TF-A to return to S-EL0 with the result of the
282request.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000283
284For instance, a request to perform privileged operations on behalf of a
285partition (e.g. management of memory attributes in the translation tables for
286the Secure EL1&0 translation regime).
287
288Interfaces
289^^^^^^^^^^
290
291The current implementation reserves function IDs for Fast Calls in the Standard
Dan Handley610e7e12018-03-01 18:44:00 +0000292Secure Service calls range (see `SMC Calling Convention`_ (*Arm DEN 0028B*)
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000293specification) for each API exported by the SPM. This section defines the
294function prototypes for each function ID. The function IDs specify whether one
295or both of the SVC32 and SVC64 calling conventions can be used to invoke the
296corresponding interface.
297
298Secure Partition Event Management
299^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
300
301The Secure Partition provides an Event Management interface that is used by the
302SPM to delegate service requests to the Secure Partition. The interface also
303allows the Secure Partition to:
304
305- Register with the SPM a service that it provides.
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000306- Indicate completion of a service request delegated by the SPM
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000307
308Miscellaneous interfaces
309------------------------
310
Paul Beesleye9754e62019-10-15 12:51:55 +0000311``SPM_MM_VERSION_AARCH32``
312^^^^^^^^^^^^^^^^^^^^^^^^^^
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000313
314- Description
315
316 Returns the version of the interface exported by SPM.
317
318- Parameters
319
320 - **uint32** - Function ID
321
322 - SVC32 Version: **0x84000060**
323
324- Return parameters
325
326 - **int32** - Status
327
328 On success, the format of the value is as follows:
329
330 - Bit [31]: Must be 0
331 - Bits [30:16]: Major Version. Must be 0 for this revision of the SPM
332 interface.
333 - Bits [15:0]: Minor Version. Must be 1 for this revision of the SPM
334 interface.
335
336 On error, the format of the value is as follows:
337
338 - ``NOT_SUPPORTED``: SPM interface is not supported or not available for the
339 client.
340
341- Usage
342
343 This function returns the version of the Secure Partition Manager
344 implementation. The major version is 0 and the minor version is 1. The version
345 number is a 31-bit unsigned integer, with the upper 15 bits denoting the major
346 revision, and the lower 16 bits denoting the minor revision. The following
347 rules apply to the version numbering:
348
349 - Different major revision values indicate possibly incompatible functions.
350
351 - For two revisions, A and B, for which the major revision values are
352 identical, if the minor revision value of revision B is greater than the
353 minor revision value of revision A, then every function in revision A must
354 work in a compatible way with revision B. However, it is possible for
355 revision B to have a higher function count than revision A.
356
357- Implementation responsibilities
358
359 If this function returns a valid version number, all the functions that are
360 described subsequently must be implemented, unless it is explicitly stated
361 that a function is optional.
362
363See `Error Codes`_ for integer values that are associated with each return
364code.
365
366Secure Partition Initialisation
367-------------------------------
368
369The SPM is responsible for initialising the architectural execution context to
370enable initialisation of a service in S-EL0. The responsibilities of the SPM are
371listed below. At the end of initialisation, the partition issues a
Paul Beesleye9754e62019-10-15 12:51:55 +0000372``MM_SP_EVENT_COMPLETE_AARCH64`` call (described later) to signal readiness for
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000373handling requests for services implemented by the Secure Partition. The
374initialisation event is executed as a Fast Call.
375
376Entry point invocation
377^^^^^^^^^^^^^^^^^^^^^^
378
379The entry point for service requests that should be handled as Fast Calls is
380used as the target of the ERET instruction to start initialisation of the Secure
381Partition.
382
383Architectural Setup
384^^^^^^^^^^^^^^^^^^^
385
386At cold boot, system registers accessible from S-EL0 will be in their reset
387state unless otherwise specified. The SPM will perform the following
388architectural setup to enable execution in S-EL0
389
390MMU setup
391^^^^^^^^^
392
393The platform port of a Secure Partition specifies to the SPM a list of regions
394that it needs access to and their attributes. The SPM validates this resource
395description and initialises the Secure EL1&0 translation regime as follows.
396
3971. Device regions are mapped with nGnRE attributes and Execute Never
398 instruction access permissions.
399
4002. Code memory regions are mapped with RO data and Executable instruction access
401 permissions.
402
4033. Read Only data memory regions are mapped with RO data and Execute Never
404 instruction access permissions.
405
4064. Read Write data memory regions are mapped with RW data and Execute Never
407 instruction access permissions.
408
4095. If the resource description does not explicitly describe the type of memory
410 regions then all memory regions will be marked with Code memory region
411 attributes.
412
4136. The ``UXN`` and ``PXN`` bits are set for regions that are not executable by
414 S-EL0 or S-EL1.
415
416System Register Setup
417^^^^^^^^^^^^^^^^^^^^^
418
419System registers that influence software execution in S-EL0 are setup by the SPM
420as follows:
421
4221. ``SCTLR_EL1``
423
424 - ``UCI=1``
425 - ``EOE=0``
426 - ``WXN=1``
427 - ``nTWE=1``
428 - ``nTWI=1``
429 - ``UCT=1``
430 - ``DZE=1``
431 - ``I=1``
432 - ``UMA=0``
433 - ``SA0=1``
434 - ``C=1``
435 - ``A=1``
436 - ``M=1``
437
4382. ``CPACR_EL1``
439
440 - ``FPEN=b'11``
441
4423. ``PSTATE``
443
444 - ``D,A,I,F=1``
445 - ``CurrentEL=0`` (EL0)
446 - ``SpSel=0`` (Thread mode)
447 - ``NRW=0`` (AArch64)
448
449General Purpose Register Setup
450^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
451
452SPM will invoke the entry point of a service by executing an ERET instruction.
453This transition into S-EL0 is special since it is not in response to a previous
454request through a SVC instruction. This is the first entry into S-EL0. The
455general purpose register usage at the time of entry will be as specified in the
456"Return State" column of Table 3-1 in Section 3.1 "Register use in AArch64 SMC
Dan Handley610e7e12018-03-01 18:44:00 +0000457calls" of the `SMC Calling Convention`_ (*Arm DEN 0028B*) specification. In
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000458addition, certain other restrictions will be applied as described below.
459
4601. ``SP_EL0``
461
462 A non-zero value will indicate that the SPM has initialised the stack pointer
463 for the current CPU.
464
465 The value will be 0 otherwise.
466
4672. ``X4-X30``
468
469 The values of these registers will be 0.
470
4713. ``X0-X3``
472
473 Parameters passed by the SPM.
474
475 - ``X0``: Virtual address of a buffer shared between EL3 and S-EL0. The
476 buffer will be mapped in the Secure EL1&0 translation regime with read-only
477 memory attributes described earlier.
478
479 - ``X1``: Size of the buffer in bytes.
480
481 - ``X2``: Cookie value (*IMPLEMENTATION DEFINED*).
482
483 - ``X3``: Cookie value (*IMPLEMENTATION DEFINED*).
484
485Runtime Event Delegation
486------------------------
487
488The SPM receives requests for Secure Partition services through a synchronous
489invocation (i.e. a SMC from the Non-secure world). These requests are delegated
490to the partition by programming a return from the last
Paul Beesleye9754e62019-10-15 12:51:55 +0000491``MM_SP_EVENT_COMPLETE_AARCH64`` call received from the partition. The last call
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000492was made to signal either completion of Secure Partition initialisation or
493completion of a partition service request.
494
Paul Beesleye9754e62019-10-15 12:51:55 +0000495``MM_SP_EVENT_COMPLETE_AARCH64``
496^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000497
498- Description
499
500 Signal completion of the last SP service request.
501
502- Parameters
503
504 - **uint32** - Function ID
505
506 - SVC64 Version: **0xC4000061**
507
508 - **int32** - Event Status Code
509
510 Zero or a positive value indicates that the event was handled successfully.
511 The values depend upon the original event that was delegated to the Secure
512 partition. They are described as follows.
513
514 - ``SUCCESS`` : Used to indicate that the Secure Partition was initialised
515 or a runtime request was handled successfully.
516
517 - Any other value greater than 0 is used to pass a specific Event Status
518 code in response to a runtime event.
519
520 A negative value indicates an error. The values of Event Status code depend
521 on the original event.
522
523- Return parameters
524
525 - **int32** - Event ID/Return Code
526
527 Zero or a positive value specifies the unique ID of the event being
528 delegated to the partition by the SPM.
529
530 In the current implementation, this parameter contains the function ID of
531 the ``MM_COMMUNICATE`` SMC. This value indicates to the partition that an
532 event has been delegated to it in response to an ``MM_COMMUNICATE`` request
533 from the Non-secure world.
534
535 A negative value indicates an error. The format of the value is as follows:
536
537 - ``NOT_SUPPORTED``: Function was called from the Non-secure world.
538
539 See `Error Codes`_ for integer values that are associated with each return
540 code.
541
542 - **uint32** - Event Context Address
543
544 Address of a buffer shared between the SPM and Secure Partition to pass
545 event specific information. The format of the data populated in the buffer
546 is implementation defined.
547
548 The buffer is mapped in the Secure EL1&0 translation regime with read-only
549 memory attributes described earlier.
550
551 For the SVC64 version, this parameter is a 64-bit Virtual Address (VA).
552
553 For the SVC32 version, this parameter is a 32-bit Virtual Address (VA).
554
555 - **uint32** - Event context size
556
557 Size of the memory starting at Event Address.
558
559 - **uint32/uint64** - Event Cookie
560
561 This is an optional parameter. If unused its value is SBZ.
562
563- Usage
564
565 This function signals to the SPM that the handling of the last event delegated
566 to a partition has completed. The partition is ready to handle its next event.
567 A return from this function is in response to the next event that will be
568 delegated to the partition. The return parameters describe the next event.
569
570- Caller responsibilities
571
Paul Beesleye9754e62019-10-15 12:51:55 +0000572 A Secure Partition must only call ``MM_SP_EVENT_COMPLETE_AARCH64`` to signal
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000573 completion of a request that was delegated to it by the SPM.
574
575- Callee responsibilities
576
577 When the SPM receives this call from a Secure Partition, the corresponding
578 syndrome information can be used to return control through an ERET
579 instruction, to the instruction immediately after the call in the Secure
580 Partition context. This syndrome information comprises of general purpose and
581 system register values when the call was made.
582
583 The SPM must save this syndrome information and use it to delegate the next
584 event to the Secure Partition. The return parameters of this interface must
585 specify the properties of the event and be populated in ``X0-X3/W0-W3``
586 registers.
587
588Secure Partition Memory Management
589----------------------------------
590
591A Secure Partition executes at S-EL0, which is an unprivileged Exception Level.
592The SPM is responsible for enabling access to regions of memory in the system
593address map from a Secure Partition. This is done by mapping these regions in
594the Secure EL1&0 Translation regime with appropriate memory attributes.
595Attributes refer to memory type, permission, cacheability and shareability
596attributes used in the Translation tables. The definitions of these attributes
Dan Handley610e7e12018-03-01 18:44:00 +0000597and their usage can be found in the `Armv8-A ARM`_ (*Arm DDI 0487*).
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000598
599All memory required by the Secure Partition is allocated upfront in the SPM,
600even before handing over to the Secure Partition for the first time. The initial
601access permissions of the memory regions are statically provided by the platform
602port and should allow the Secure Partition to run its initialisation code.
603
604However, they might not suit the final needs of the Secure Partition because its
605final memory layout might not be known until the Secure Partition initialises
606itself. As the Secure Partition initialises its runtime environment it might,
607for example, load dynamically some modules. For instance, a Secure Partition
608could implement a loader for a standard executable file format (e.g. an PE-COFF
609loader for loading executable files at runtime). These executable files will be
610a part of the Secure Partition image. The location of various sections in an
611executable file and their permission attributes (e.g. read-write data, read-only
612data and code) will be known only when the file is loaded into memory.
613
614In this case, the Secure Partition needs a way to change the access permissions
615of its memory regions. The SPM provides this feature through the
Paul Beesleye9754e62019-10-15 12:51:55 +0000616``MM_SP_MEMORY_ATTRIBUTES_SET_AARCH64`` SVC interface. This interface is
617available to the Secure Partition during a specific time window: from the first
618entry into the Secure Partition up to the first ``SP_EVENT_COMPLETE`` call that
619signals the Secure Partition has finished its initialisation. Once the
620initialisation is complete, the SPM does not allow changes to the memory
621attributes.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000622
623This section describes the standard SVC interface that is implemented by the SPM
624to determine and change permission attributes of memory regions that belong to a
625Secure Partition.
626
Paul Beesleye9754e62019-10-15 12:51:55 +0000627``MM_SP_MEMORY_ATTRIBUTES_GET_AARCH64``
628^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000629
630- Description
631
632 Request the permission attributes of a memory region from S-EL0.
633
634- Parameters
635
636 - **uint32** Function ID
637
638 - SVC64 Version: **0xC4000064**
639
640 - **uint64** Base Address
641
642 This parameter is a 64-bit Virtual Address (VA).
643
644 There are no alignment restrictions on the Base Address. The permission
645 attributes of the translation granule it lies in are returned.
646
647- Return parameters
648
649 - **int32** - Memory Attributes/Return Code
650
651 On success the format of the Return Code is as follows:
652
653 - Bits[1:0] : Data access permission
654
655 - b'00 : No access
656 - b'01 : Read-Write access
657 - b'10 : Reserved
658 - b'11 : Read-only access
659
660 - Bit[2]: Instruction access permission
661
662 - b'0 : Executable
663 - b'1 : Non-executable
664
665 - Bit[30:3] : Reserved. SBZ.
666
667 - Bit[31] : Must be 0
668
669 On failure the following error codes are returned:
670
671 - ``INVALID_PARAMETERS``: The Secure Partition is not allowed to access the
672 memory region the Base Address lies in.
673
674 - ``NOT_SUPPORTED`` : The SPM does not support retrieval of attributes of
675 any memory page that is accessible by the Secure Partition, or the
676 function was called from the Non-secure world. Also returned if it is
Paul Beesleye9754e62019-10-15 12:51:55 +0000677 used after ``MM_SP_EVENT_COMPLETE_AARCH64``.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000678
679 See `Error Codes`_ for integer values that are associated with each return
680 code.
681
682- Usage
683
684 This function is used to request the permission attributes for S-EL0 on a
685 memory region accessible from a Secure Partition. The size of the memory
686 region is equal to the Translation Granule size used in the Secure EL1&0
687 translation regime. Requests to retrieve other memory region attributes are
688 not currently supported.
689
690- Caller responsibilities
691
692 The caller must obtain the Translation Granule Size of the Secure EL1&0
693 translation regime from the SPM through an implementation defined method.
694
695- Callee responsibilities
696
697 The SPM must not return the memory access controls for a page of memory that
698 is not accessible from a Secure Partition.
699
Paul Beesleye9754e62019-10-15 12:51:55 +0000700``MM_SP_MEMORY_ATTRIBUTES_SET_AARCH64``
701^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000702
703- Description
704
705 Set the permission attributes of a memory region from S-EL0.
706
707- Parameters
708
709 - **uint32** - Function ID
710
711 - SVC64 Version: **0xC4000065**
712
713 - **uint64** - Base Address
714
715 This parameter is a 64-bit Virtual Address (VA).
716
717 The alignment of the Base Address must be greater than or equal to the size
718 of the Translation Granule Size used in the Secure EL1&0 translation
719 regime.
720
721 - **uint32** - Page count
722
723 Number of pages starting from the Base Address whose memory attributes
724 should be changed. The page size is equal to the Translation Granule Size.
725
726 - **uint32** - Memory Access Controls
727
728 - Bits[1:0] : Data access permission
729
730 - b'00 : No access
731 - b'01 : Read-Write access
732 - b'10 : Reserved
733 - b'11 : Read-only access
734
735 - Bit[2] : Instruction access permission
736
737 - b'0 : Executable
738 - b'1 : Non-executable
739
740 - Bits[31:3] : Reserved. SBZ.
741
742 A combination of attributes that mark the region with RW and Executable
743 permissions is prohibited. A request to mark a device memory region with
744 Executable permissions is prohibited.
745
746- Return parameters
747
748 - **int32** - Return Code
749
750 - ``SUCCESS``: The Memory Access Controls were changed successfully.
751
752 - ``DENIED``: The SPM is servicing a request to change the attributes of a
753 memory region that overlaps with the region specified in this request.
754
755 - ``INVALID_PARAMETER``: An invalid combination of Memory Access Controls
756 has been specified. The Base Address is not correctly aligned. The Secure
757 Partition is not allowed to access part or all of the memory region
758 specified in the call.
759
760 - ``NO_MEMORY``: The SPM does not have memory resources to change the
761 attributes of the memory region in the translation tables.
762
763 - ``NOT_SUPPORTED``: The SPM does not permit change of attributes of any
764 memory region that is accessible by the Secure Partition. Function was
765 called from the Non-secure world. Also returned if it is used after
Paul Beesleye9754e62019-10-15 12:51:55 +0000766 ``MM_SP_EVENT_COMPLETE_AARCH64``.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000767
768 See `Error Codes`_ for integer values that are associated with each return
769 code.
770
771- Usage
772
773 This function is used to change the permission attributes for S-EL0 on a
774 memory region accessible from a Secure Partition. The size of the memory
775 region is equal to the Translation Granule size used in the Secure EL1&0
776 translation regime. Requests to change other memory region attributes are not
777 currently supported.
778
779 This function is only available at boot time. This interface is revoked after
Paul Beesleye9754e62019-10-15 12:51:55 +0000780 the Secure Partition sends the first ``MM_SP_EVENT_COMPLETE_AARCH64`` to
781 signal that it is initialised and ready to receive run-time requests.
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000782
783- Caller responsibilities
784
785 The caller must obtain the Translation Granule Size of the Secure EL1&0
786 translation regime from the SPM through an implementation defined method.
787
788- Callee responsibilities
789
790 The SPM must preserve the original memory access controls of the region of
791 memory in case of an unsuccessful call.  The SPM must preserve the consistency
792 of the S-EL1 translation regime if this function is called on different PEs
793 concurrently and the memory regions specified overlap.
794
795Error Codes
796-----------
797
798.. csv-table::
799 :header: "Name", "Value"
800
801 ``SUCCESS``,0
802 ``NOT_SUPPORTED``,-1
803 ``INVALID_PARAMETER``,-2
804 ``DENIED``,-3
805 ``NO_MEMORY``,-5
806 ``NOT_PRESENT``,-7
807
808--------------
809
laurenw-arm03e7e612020-04-16 10:02:17 -0500810*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.*
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000811
Dan Handley610e7e12018-03-01 18:44:00 +0000812.. _Armv8-A ARM: https://developer.arm.com/docs/ddi0487/latest/arm-architecture-reference-manual-armv8-for-armv8-a-architecture-profile
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000813.. _instructions in the EDK2 repository: https://github.com/tianocore/edk2-staging/blob/AArch64StandaloneMm/HowtoBuild.MD
814.. _Management Mode Interface Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf
815.. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
laurenw-arm03e7e612020-04-16 10:02:17 -0500816.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest
Antonio Nino Diaz352c8522017-12-15 11:41:17 +0000817
Paul Beesley814f8c02019-03-13 15:49:27 +0000818.. |Image 1| image:: ../resources/diagrams/secure_sw_stack_tos.png
819.. |Image 2| image:: ../resources/diagrams/secure_sw_stack_sp.png