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