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