1Secure Partition Manager (MM)
2*****************************
3
4Foreword
5========
6
7Two implementations of a Secure Partition Manager co-exist in the TF-A codebase:
8
9-  SPM based on the FF-A specification (:ref:`Secure Partition Manager`).
10-  SPM based on the MM interface.
11
12Both 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.
18
19Background
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
30in the system, i.e. EL3 in Trusted Firmware-A (TF-A). The service requirements are
31fulfilled by the execution environment provided by TF-A.
32
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
53privileged 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:
57
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
64Note that currently TF-A only supports handling one Secure Partition.
65
66A Secure Partition enables TF-A to implement only the essential secure
67services in EL3 and instantiate the rest in a partition in S-EL0.
68Furthermore, 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
72Armv8-A software stack. A single or multiple Secure Partitions provide secure
73services to software components in the Non-secure world and other Secure
74Partitions.
75
76|Image 2|
77
78The 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
82similar 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
116Building TF-A with Secure Partition support
117-------------------------------------------
118
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
136To enable SPM support in TF-A, the source code must be compiled with the build
137flag ``SPM_MM=1``, along with ``EL3_EXCEPTION_HANDLING=1``. On Arm
138platforms the build option ``ARM_BL31_IN_DRAM`` must be set to 1. Also, the
139location of the binary that contains the BL32 image
140(``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
145Then build TF-A with SPM support and include the Standalone MM Secure Partition
146image in the FIP:
147
148.. code:: shell
149
150    BL32=path/to/standalone/mm/sp BL33=path/to/bl33.bin \
151    make PLAT=fvp SPM_MM=1 EL3_EXCEPTION_HANDLING=1 ARM_BL31_IN_DRAM=1 all fip
152
153Describing Secure Partition resources
154-------------------------------------
155
156TF-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.
160
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
178    ``spm_mm_boot_info_t`` struct that is populated by the platform
179    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
187The `SMC Calling Convention`_ (*Arm DEN 0028B*) describes SMCs as a conduit for
188accessing services implemented in the Secure world. The ``MM_COMMUNICATE``
189interface defined in the `Management Mode Interface Specification`_ (*Arm DEN
1900060A*) 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`_
219(*Arm DEN 0060A*).
220
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
223the `Management Mode Interface specification`_ (*Arm DEN 0060A*), Section 4
224describes 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
257The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the SMC
258and 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
265A 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
268SMC request, Trusted Firmware-A returns control directly to S-EL0 through an
269ERET instruction.
270
271Calling conventions
272^^^^^^^^^^^^^^^^^^^
273
274The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the
27532-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.
296An ERET instruction is used by TF-A to return to S-EL0 with the result of the
297request.
298
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
307Secure Service calls range (see `SMC Calling Convention`_ (*Arm DEN 0028B*)
308specification) 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.
321- Indicate completion of a service request delegated by the SPM
322
323Miscellaneous interfaces
324------------------------
325
326``SPM_MM_VERSION_AARCH32``
327^^^^^^^^^^^^^^^^^^^^^^^^^^
328
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
387``MM_SP_EVENT_COMPLETE_AARCH64`` call (described later) to signal readiness for
388handling 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
472calls" of the `SMC Calling Convention`_ (*Arm DEN 0028B*) specification. In
473addition, 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
506``MM_SP_EVENT_COMPLETE_AARCH64`` call received from the partition. The last call
507was made to signal either completion of Secure Partition initialisation or
508completion of a partition service request.
509
510``MM_SP_EVENT_COMPLETE_AARCH64``
511^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
512
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
587  A Secure Partition must only call ``MM_SP_EVENT_COMPLETE_AARCH64`` to signal
588  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
612and their usage can be found in the `Armv8-A ARM`_ (*Arm DDI 0487*).
613
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
631``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.
637
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
642``MM_SP_MEMORY_ATTRIBUTES_GET_AARCH64``
643^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
644
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
692      used after ``MM_SP_EVENT_COMPLETE_AARCH64``.
693
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
715``MM_SP_MEMORY_ATTRIBUTES_SET_AARCH64``
716^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
717
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
781      ``MM_SP_EVENT_COMPLETE_AARCH64``.
782
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
795  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.
797
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
825*Copyright (c) 2017-2021, Arm Limited and Contributors. All rights reserved.*
826
827.. _Armv8-A ARM: https://developer.arm.com/docs/ddi0487/latest/arm-architecture-reference-manual-armv8-for-armv8-a-architecture-profile
828.. _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
831.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest
832
833.. |Image 1| image:: ../resources/diagrams/secure_sw_stack_tos.png
834.. |Image 2| image:: ../resources/diagrams/secure_sw_stack_sp.png
835