Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 1 | ******************************* |
| 2 | Secure Partition Manager Design |
| 3 | ******************************* |
| 4 | |
| 5 | .. section-numbering:: |
| 6 | :suffix: . |
| 7 | |
| 8 | .. contents:: |
| 9 | |
| 10 | Background |
| 11 | ========== |
| 12 | |
| 13 | In some market segments that primarily deal with client-side devices like mobile |
| 14 | phones, tablets, STBs and embedded devices, a Trusted OS instantiates trusted |
| 15 | applications to provide security services like DRM, secure payment and |
| 16 | authentication. The Global Platform TEE Client API specification defines the API |
| 17 | used by Non-secure world applications to access these services. A Trusted OS |
| 18 | fulfils the requirements of a security service as described above. |
| 19 | |
| 20 | Management services are typically implemented at the highest level of privilege |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 21 | in the system, i.e. EL3 in Trusted Firmware-A (TF-A). The service requirements are |
| 22 | fulfilled by the execution environment provided by TF-A. |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 23 | |
| 24 | The following diagram illustrates the corresponding software stack: |
| 25 | |
| 26 | |Image 1| |
| 27 | |
| 28 | In other market segments that primarily deal with server-side devices (e.g. data |
| 29 | centres and enterprise servers) the secure software stack typically does not |
| 30 | include a Global Platform Trusted OS. Security functions are accessed through |
| 31 | other interfaces (e.g. ACPI TCG TPM interface, UEFI runtime variable service). |
| 32 | |
| 33 | Placement of management and security functions with diverse requirements in a |
| 34 | privileged Exception Level (i.e. EL3 or S-EL1) makes security auditing of |
| 35 | firmware more difficult and does not allow isolation of unrelated services from |
| 36 | each other either. |
| 37 | |
| 38 | Introduction |
| 39 | ============ |
| 40 | |
| 41 | A **Secure Partition** is a software execution environment instantiated in |
| 42 | S-EL0 that can be used to implement simple management and security services. |
| 43 | Since S-EL0 is an unprivileged Exception Level, a Secure Partition relies on |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 44 | privileged firmware (i.e. TF-A) to be granted access to system and processor |
| 45 | resources. Essentially, it is a software sandbox in the Secure world that runs |
| 46 | under the control of privileged software, provides one or more services and |
| 47 | accesses the following system resources: |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 48 | |
| 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 Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 55 | Note that currently TF-A only supports handling one Secure Partition. |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 56 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 57 | A Secure Partition enables TF-A to implement only the essential secure |
| 58 | services in EL3 and instantiate the rest in a partition in S-EL0. |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 59 | Furthermore, multiple Secure Partitions can be used to isolate unrelated |
| 60 | services from each other. |
| 61 | |
| 62 | The following diagram illustrates the place of a Secure Partition in a typical |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 63 | Armv8-A software stack. A single or multiple Secure Partitions provide secure |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 64 | services to software components in the Non-secure world and other Secure |
| 65 | Partitions. |
| 66 | |
| 67 | |Image 2| |
| 68 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 69 | The TF-A build system is responsible for including the Secure Partition image |
| 70 | in the FIP. During boot, BL2 includes support to authenticate and load the |
| 71 | Secure Partition image. A BL31 component called **Secure Partition Manager |
| 72 | (SPM)** is responsible for managing the partition. This is semantically |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 73 | similar to a hypervisor managing a virtual machine. |
| 74 | |
| 75 | The 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 | |
| 85 | The 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 | |
| 94 | Alternatively, a partition can be viewed as a thread of execution running under |
| 95 | the control of the SPM. Hence common programming concepts described below are |
| 96 | applicable to a partition. |
| 97 | |
| 98 | Description |
| 99 | =========== |
| 100 | |
| 101 | The previous section introduced some general aspects of the software |
| 102 | architecture of a Secure Partition. This section describes the specific choices |
| 103 | made in the current implementation of this software architecture. Subsequent |
| 104 | revisions of the implementation will include a richer set of features that |
| 105 | enable a more flexible architecture. |
| 106 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 107 | Building TF-A with Secure Partition support |
| 108 | ------------------------------------------- |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 109 | |
| 110 | SPM is supported on the Arm FVP exclusively at the moment. The current |
| 111 | implementation supports inclusion of only a single Secure Partition in which a |
| 112 | service always runs to completion (e.g. the requested services cannot be |
| 113 | preempted to give control back to the Normal world). |
| 114 | |
| 115 | It is not currently possible for BL31 to integrate SPM support and a Secure |
| 116 | Payload Dispatcher (SPD) at the same time; they are mutually exclusive. In the |
| 117 | SPM bootflow, a Secure Partition image executing at S-EL0 replaces the Secure |
| 118 | Payload image executing at S-EL1 (e.g. a Trusted OS). Both are referred to as |
| 119 | BL32. |
| 120 | |
| 121 | A working prototype of a SP has been implemented by re-purposing the EDK2 code |
| 122 | and tools, leveraging the concept of the *Standalone Management Mode (MM)* in |
| 123 | the UEFI specification (see the PI v1.6 Volume 4: Management Mode Core |
| 124 | Interface). This will be referred to as the *Standalone MM Secure Partition* in |
| 125 | the rest of this document. |
| 126 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 127 | To enable SPM support in TF-A, the source code must be compiled with the build |
Sughosh Ganu | 8a3588a | 2018-11-14 10:40:33 +0530 | [diff] [blame] | 128 | flag ``ENABLE_SPM=1``, along with ``EL3_EXCEPTION_HANDLING=1``. On Arm |
| 129 | platforms the build option ``ARM_BL31_IN_DRAM`` must be set to 1. Also, the |
| 130 | location of the binary that contains the BL32 image |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 131 | (``BL32=path/to/image.bin``) must be specified. |
| 132 | |
| 133 | First, build the Standalone MM Secure Partition. To build it, refer to the |
| 134 | `instructions in the EDK2 repository`_. |
| 135 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 136 | Then build TF-A with SPM support and include the Standalone MM Secure Partition |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 137 | image in the FIP: |
| 138 | |
| 139 | :: |
| 140 | |
| 141 | BL32=path/to/standalone/mm/sp BL33=path/to/bl33.bin \ |
Antonio Nino Diaz | e829a37 | 2018-05-24 09:14:58 +0100 | [diff] [blame] | 142 | make PLAT=fvp ENABLE_SPM=1 ARM_BL31_IN_DRAM=1 fip all |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 143 | |
| 144 | Describing Secure Partition resources |
| 145 | ------------------------------------- |
| 146 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 147 | TF-A exports a porting interface that enables a platform to specify the system |
| 148 | resources required by the Secure Partition. Some instructions are given below. |
| 149 | However, this interface is under development and it may change as new features |
| 150 | are implemented. |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 151 | |
| 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 | |
| 172 | For an example of all the changes in context, you may refer to commit |
| 173 | ``e29efeb1b4``, in which the port for FVP was introduced. |
| 174 | |
| 175 | Accessing Secure Partition services |
| 176 | ----------------------------------- |
| 177 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 178 | The `SMC Calling Convention`_ (*Arm DEN 0028B*) describes SMCs as a conduit for |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 179 | accessing services implemented in the Secure world. The ``MM_COMMUNICATE`` |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 180 | interface defined in the `Management Mode Interface Specification`_ (*Arm DEN |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 181 | 0060A*) is used to invoke a Secure Partition service as a Fast Call. |
| 182 | |
| 183 | The mechanism used to identify a service within the partition depends on the |
| 184 | service implementation. It is assumed that the caller of the service will be |
| 185 | able to discover this mechanism through standard platform discovery mechanisms |
| 186 | like ACPI and Device Trees. For example, *Volume 4: Platform Initialisation |
| 187 | Specification v1.6. Management Mode Core Interface* specifies that a GUID is |
| 188 | used 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 |
| 190 | buffer shared with the Secure Partition. |
| 191 | |
| 192 | A Fast Call appears to be atomic from the perspective of the caller and returns |
| 193 | when 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. |
| 195 | The SPM is responsible for guaranteeing this behaviour. This means that there |
| 196 | can only be a single outstanding Fast Call in a partition on a given CPU. |
| 197 | |
| 198 | Exchanging data with the Secure Partition |
| 199 | ----------------------------------------- |
| 200 | |
| 201 | The exchange of data between the Non-secure world and the partition takes place |
| 202 | through a shared memory region. The location of data in the shared memory area |
| 203 | is passed as a parameter to the ``MM_COMMUNICATE`` SMC. The shared memory area |
| 204 | is statically allocated by the SPM and is expected to be either implicitly known |
| 205 | to the Non-secure world or discovered through a platform discovery mechanism |
| 206 | e.g. ACPI table or device tree. It is possible for the Non-secure world to |
| 207 | exchange data with a partition only if it has been populated in this shared |
| 208 | memory area. The shared memory area is implemented as per the guidelines |
| 209 | specified in Section 3.2.3 of the `Management Mode Interface Specification`_ |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 210 | (*Arm DEN 0060A*). |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 211 | |
| 212 | The format of data structures used to encapsulate data in the shared memory is |
| 213 | agreed between the Non-secure world and the Secure Partition. For example, in |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 214 | the `Management Mode Interface specification`_ (*Arm DEN 0060A*), Section 4 |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 215 | describes that the communication buffer shared between the Non-secure world and |
| 216 | the 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: |
| 218 | Platform Initialisation Specification v1.6. Management Mode Core Interface*. |
| 219 | Any caller of a MM service will have to use the ``EFI_MM_COMMUNICATE_HEADER`` |
| 220 | data structure. |
| 221 | |
| 222 | Runtime model of the Secure Partition |
| 223 | ===================================== |
| 224 | |
| 225 | This section describes how the Secure Partition interfaces with the SPM. |
| 226 | |
| 227 | Interface with SPM |
| 228 | ------------------ |
| 229 | |
| 230 | In order to instantiate one or more secure services in the Secure Partition in |
| 231 | S-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 | |
| 241 | This section describes the APIs currently exported by the SPM that enable a |
| 242 | Secure Partition to initialise itself and export its services in S-EL0. These |
| 243 | interfaces are not accessible from the Non-secure world. |
| 244 | |
| 245 | Conduit |
| 246 | ^^^^^^^ |
| 247 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 248 | The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the SMC |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 249 | and HVC conduits for accessing firmware services and their availability |
| 250 | depending on the implemented Exception levels. In S-EL0, the Supervisor Call |
| 251 | exception (SVC) is the only architectural mechanism available for unprivileged |
| 252 | software to make a request for an operation implemented in privileged software. |
| 253 | Hence, the SVC conduit must be used by the Secure Partition to access interfaces |
| 254 | implemented by the SPM. |
| 255 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 256 | A SVC causes an exception to be taken to S-EL1. TF-A assumes ownership of S-EL1 |
| 257 | and installs a simple exception vector table in S-EL1 that relays a SVC request |
| 258 | from a Secure Partition as a SMC request to the SPM in EL3. Upon servicing the |
| 259 | SMC request, Arm Trusted Firmware returns control directly to S-EL0 through an |
| 260 | ERET instruction. |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 261 | |
| 262 | Calling conventions |
| 263 | ^^^^^^^^^^^^^^^^^^^ |
| 264 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 265 | The `SMC Calling Convention`_ (*Arm DEN 0028B*) specification describes the |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 266 | 32-bit and 64-bit calling conventions for the SMC and HVC conduits. The SVC |
| 267 | conduit introduces the concept of SVC32 and SVC64 calling conventions. The SVC32 |
| 268 | and SVC64 calling conventions are equivalent to the 32-bit (SMC32) and the |
| 269 | 64-bit (SMC64) calling conventions respectively. |
| 270 | |
| 271 | Communication initiated by SPM |
| 272 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 273 | |
| 274 | A service request is initiated from the SPM through an exception return |
| 275 | instruction (ERET) to S-EL0. Later, the Secure Partition issues an SVC |
| 276 | instruction to signal completion of the request. Some example use cases are |
| 277 | given below: |
| 278 | |
| 279 | - A request to initialise the Secure Partition during system boot. |
| 280 | |
| 281 | - A request to handle a runtime service request. |
| 282 | |
| 283 | Communication initiated by Secure Partition |
| 284 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 285 | |
| 286 | A request is initiated from the Secure Partition by executing a SVC instruction. |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 287 | An ERET instruction is used by TF-A to return to S-EL0 with the result of the |
| 288 | request. |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 289 | |
| 290 | For instance, a request to perform privileged operations on behalf of a |
| 291 | partition (e.g. management of memory attributes in the translation tables for |
| 292 | the Secure EL1&0 translation regime). |
| 293 | |
| 294 | Interfaces |
| 295 | ^^^^^^^^^^ |
| 296 | |
| 297 | The current implementation reserves function IDs for Fast Calls in the Standard |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 298 | Secure Service calls range (see `SMC Calling Convention`_ (*Arm DEN 0028B*) |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 299 | specification) for each API exported by the SPM. This section defines the |
| 300 | function prototypes for each function ID. The function IDs specify whether one |
| 301 | or both of the SVC32 and SVC64 calling conventions can be used to invoke the |
| 302 | corresponding interface. |
| 303 | |
| 304 | Secure Partition Event Management |
| 305 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 306 | |
| 307 | The Secure Partition provides an Event Management interface that is used by the |
| 308 | SPM to delegate service requests to the Secure Partition. The interface also |
| 309 | allows the Secure Partition to: |
| 310 | |
| 311 | - Register with the SPM a service that it provides. |
Paul Beesley | 8aabea3 | 2019-01-11 18:26:51 +0000 | [diff] [blame^] | 312 | - Indicate completion of a service request delegated by the SPM |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 313 | |
| 314 | Miscellaneous 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 | |
| 369 | See `Error Codes`_ for integer values that are associated with each return |
| 370 | code. |
| 371 | |
| 372 | Secure Partition Initialisation |
| 373 | ------------------------------- |
| 374 | |
| 375 | The SPM is responsible for initialising the architectural execution context to |
| 376 | enable initialisation of a service in S-EL0. The responsibilities of the SPM are |
| 377 | listed below. At the end of initialisation, the partition issues a |
| 378 | ``SP_EVENT_COMPLETE_AARCH64`` call (described later) to signal readiness for |
| 379 | handling requests for services implemented by the Secure Partition. The |
| 380 | initialisation event is executed as a Fast Call. |
| 381 | |
| 382 | Entry point invocation |
| 383 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 384 | |
| 385 | The entry point for service requests that should be handled as Fast Calls is |
| 386 | used as the target of the ERET instruction to start initialisation of the Secure |
| 387 | Partition. |
| 388 | |
| 389 | Architectural Setup |
| 390 | ^^^^^^^^^^^^^^^^^^^ |
| 391 | |
| 392 | At cold boot, system registers accessible from S-EL0 will be in their reset |
| 393 | state unless otherwise specified. The SPM will perform the following |
| 394 | architectural setup to enable execution in S-EL0 |
| 395 | |
| 396 | MMU setup |
| 397 | ^^^^^^^^^ |
| 398 | |
| 399 | The platform port of a Secure Partition specifies to the SPM a list of regions |
| 400 | that it needs access to and their attributes. The SPM validates this resource |
| 401 | description and initialises the Secure EL1&0 translation regime as follows. |
| 402 | |
| 403 | 1. Device regions are mapped with nGnRE attributes and Execute Never |
| 404 | instruction access permissions. |
| 405 | |
| 406 | 2. Code memory regions are mapped with RO data and Executable instruction access |
| 407 | permissions. |
| 408 | |
| 409 | 3. Read Only data memory regions are mapped with RO data and Execute Never |
| 410 | instruction access permissions. |
| 411 | |
| 412 | 4. Read Write data memory regions are mapped with RW data and Execute Never |
| 413 | instruction access permissions. |
| 414 | |
| 415 | 5. 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 | |
| 419 | 6. The ``UXN`` and ``PXN`` bits are set for regions that are not executable by |
| 420 | S-EL0 or S-EL1. |
| 421 | |
| 422 | System Register Setup |
| 423 | ^^^^^^^^^^^^^^^^^^^^^ |
| 424 | |
| 425 | System registers that influence software execution in S-EL0 are setup by the SPM |
| 426 | as follows: |
| 427 | |
| 428 | 1. ``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 | |
| 444 | 2. ``CPACR_EL1`` |
| 445 | |
| 446 | - ``FPEN=b'11`` |
| 447 | |
| 448 | 3. ``PSTATE`` |
| 449 | |
| 450 | - ``D,A,I,F=1`` |
| 451 | - ``CurrentEL=0`` (EL0) |
| 452 | - ``SpSel=0`` (Thread mode) |
| 453 | - ``NRW=0`` (AArch64) |
| 454 | |
| 455 | General Purpose Register Setup |
| 456 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 457 | |
| 458 | SPM will invoke the entry point of a service by executing an ERET instruction. |
| 459 | This transition into S-EL0 is special since it is not in response to a previous |
| 460 | request through a SVC instruction. This is the first entry into S-EL0. The |
| 461 | general 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 Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 463 | calls" of the `SMC Calling Convention`_ (*Arm DEN 0028B*) specification. In |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 464 | addition, certain other restrictions will be applied as described below. |
| 465 | |
| 466 | 1. ``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 | |
| 473 | 2. ``X4-X30`` |
| 474 | |
| 475 | The values of these registers will be 0. |
| 476 | |
| 477 | 3. ``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 | |
| 491 | Runtime Event Delegation |
| 492 | ------------------------ |
| 493 | |
| 494 | The SPM receives requests for Secure Partition services through a synchronous |
| 495 | invocation (i.e. a SMC from the Non-secure world). These requests are delegated |
| 496 | to the partition by programming a return from the last |
| 497 | ``SP_EVENT_COMPLETE_AARCH64`` call received from the partition. The last call |
| 498 | was made to signal either completion of Secure Partition initialisation or |
| 499 | completion 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 | |
| 594 | Secure Partition Memory Management |
| 595 | ---------------------------------- |
| 596 | |
| 597 | A Secure Partition executes at S-EL0, which is an unprivileged Exception Level. |
| 598 | The SPM is responsible for enabling access to regions of memory in the system |
| 599 | address map from a Secure Partition. This is done by mapping these regions in |
| 600 | the Secure EL1&0 Translation regime with appropriate memory attributes. |
| 601 | Attributes refer to memory type, permission, cacheability and shareability |
| 602 | attributes used in the Translation tables. The definitions of these attributes |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 603 | and their usage can be found in the `Armv8-A ARM`_ (*Arm DDI 0487*). |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 604 | |
| 605 | All memory required by the Secure Partition is allocated upfront in the SPM, |
| 606 | even before handing over to the Secure Partition for the first time. The initial |
| 607 | access permissions of the memory regions are statically provided by the platform |
| 608 | port and should allow the Secure Partition to run its initialisation code. |
| 609 | |
| 610 | However, they might not suit the final needs of the Secure Partition because its |
| 611 | final memory layout might not be known until the Secure Partition initialises |
| 612 | itself. As the Secure Partition initialises its runtime environment it might, |
| 613 | for example, load dynamically some modules. For instance, a Secure Partition |
| 614 | could implement a loader for a standard executable file format (e.g. an PE-COFF |
| 615 | loader for loading executable files at runtime). These executable files will be |
| 616 | a part of the Secure Partition image. The location of various sections in an |
| 617 | executable file and their permission attributes (e.g. read-write data, read-only |
| 618 | data and code) will be known only when the file is loaded into memory. |
| 619 | |
| 620 | In this case, the Secure Partition needs a way to change the access permissions |
| 621 | of its memory regions. The SPM provides this feature through the |
| 622 | ``SP_MEMORY_ATTRIBUTES_SET_AARCH64`` SVC interface. This interface is available |
| 623 | to the Secure Partition during a specific time window: from the first entry into |
| 624 | the Secure Partition up to the first ``SP_EVENT_COMPLETE`` call that signals the |
| 625 | Secure Partition has finished its initialisation. Once the initialisation is |
| 626 | complete, the SPM does not allow changes to the memory attributes. |
| 627 | |
| 628 | This section describes the standard SVC interface that is implemented by the SPM |
| 629 | to determine and change permission attributes of memory regions that belong to a |
| 630 | Secure 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 | |
| 800 | Error 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 Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 815 | *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.* |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 816 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 817 | .. _Armv8-A ARM: https://developer.arm.com/docs/ddi0487/latest/arm-architecture-reference-manual-armv8-for-armv8-a-architecture-profile |
Antonio Nino Diaz | 100ac09 | 2017-12-15 11:41:17 +0000 | [diff] [blame] | 818 | .. _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 |