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