Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 1 | ARM Trusted Firmware Design |
| 2 | =========================== |
| 3 | |
| 4 | |
| 5 | .. section-numbering:: |
| 6 | :suffix: . |
| 7 | |
| 8 | .. contents:: |
| 9 | |
| 10 | The ARM Trusted Firmware implements a subset of the Trusted Board Boot |
Douglas Raillard | 668c502 | 2017-06-28 16:14:55 +0100 | [diff] [blame] | 11 | Requirements (TBBR) Platform Design Document (PDD) [1]_ for ARM reference |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 12 | platforms. The TBB sequence starts when the platform is powered on and runs up |
| 13 | to the stage where it hands-off control to firmware running in the normal |
| 14 | world in DRAM. This is the cold boot path. |
| 15 | |
| 16 | The ARM Trusted Firmware also implements the Power State Coordination Interface |
Douglas Raillard | 668c502 | 2017-06-28 16:14:55 +0100 | [diff] [blame] | 17 | PDD [2]_ as a runtime service. PSCI is the interface from normal world software |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 18 | to firmware implementing power management use-cases (for example, secondary CPU |
| 19 | boot, hotplug and idle). Normal world software can access ARM Trusted Firmware |
| 20 | runtime services via the ARM SMC (Secure Monitor Call) instruction. The SMC |
Douglas Raillard | 668c502 | 2017-06-28 16:14:55 +0100 | [diff] [blame] | 21 | instruction must be used as mandated by the SMC Calling Convention [3]_. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 22 | |
| 23 | The ARM Trusted Firmware implements a framework for configuring and managing |
| 24 | interrupts generated in either security state. The details of the interrupt |
| 25 | management framework and its design can be found in ARM Trusted Firmware |
Douglas Raillard | 668c502 | 2017-06-28 16:14:55 +0100 | [diff] [blame] | 26 | Interrupt Management Design guide [4]_. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 27 | |
Antonio Nino Diaz | 6feb9e8 | 2017-05-23 11:49:22 +0100 | [diff] [blame] | 28 | The ARM Trusted Firmware also implements a library for setting up and managing |
| 29 | the translation tables. The details of this library can be found in |
| 30 | `Xlat_tables design`_. |
| 31 | |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 32 | The ARM Trusted Firmware can be built to support either AArch64 or AArch32 |
| 33 | execution state. |
| 34 | |
| 35 | Cold boot |
| 36 | --------- |
| 37 | |
| 38 | The cold boot path starts when the platform is physically turned on. If |
| 39 | ``COLD_BOOT_SINGLE_CPU=0``, one of the CPUs released from reset is chosen as the |
| 40 | primary CPU, and the remaining CPUs are considered secondary CPUs. The primary |
| 41 | CPU is chosen through platform-specific means. The cold boot path is mainly |
| 42 | executed by the primary CPU, other than essential CPU initialization executed by |
| 43 | all CPUs. The secondary CPUs are kept in a safe platform-specific state until |
| 44 | the primary CPU has performed enough initialization to boot them. |
| 45 | |
| 46 | Refer to the `Reset Design`_ for more information on the effect of the |
| 47 | ``COLD_BOOT_SINGLE_CPU`` platform build option. |
| 48 | |
| 49 | The cold boot path in this implementation of the ARM Trusted Firmware, |
| 50 | depends on the execution state. |
| 51 | For AArch64, it is divided into five steps (in order of execution): |
| 52 | |
| 53 | - Boot Loader stage 1 (BL1) *AP Trusted ROM* |
| 54 | - Boot Loader stage 2 (BL2) *Trusted Boot Firmware* |
| 55 | - Boot Loader stage 3-1 (BL31) *EL3 Runtime Software* |
| 56 | - Boot Loader stage 3-2 (BL32) *Secure-EL1 Payload* (optional) |
| 57 | - Boot Loader stage 3-3 (BL33) *Non-trusted Firmware* |
| 58 | |
| 59 | For AArch32, it is divided into four steps (in order of execution): |
| 60 | |
| 61 | - Boot Loader stage 1 (BL1) *AP Trusted ROM* |
| 62 | - Boot Loader stage 2 (BL2) *Trusted Boot Firmware* |
| 63 | - Boot Loader stage 3-2 (BL32) *EL3 Runtime Software* |
| 64 | - Boot Loader stage 3-3 (BL33) *Non-trusted Firmware* |
| 65 | |
| 66 | ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a |
| 67 | combination of the following types of memory regions. Each bootloader stage uses |
| 68 | one or more of these memory regions. |
| 69 | |
| 70 | - Regions accessible from both non-secure and secure states. For example, |
| 71 | non-trusted SRAM, ROM and DRAM. |
| 72 | - Regions accessible from only the secure state. For example, trusted SRAM and |
| 73 | ROM. The FVPs also implement the trusted DRAM which is statically |
| 74 | configured. Additionally, the Base FVPs and Juno development platform |
| 75 | configure the TrustZone Controller (TZC) to create a region in the DRAM |
| 76 | which is accessible only from the secure state. |
| 77 | |
| 78 | The sections below provide the following details: |
| 79 | |
| 80 | - initialization and execution of the first three stages during cold boot |
| 81 | - specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for |
| 82 | AArch32) entrypoint requirements for use by alternative Trusted Boot |
| 83 | Firmware in place of the provided BL1 and BL2 |
| 84 | |
| 85 | BL1 |
| 86 | ~~~ |
| 87 | |
| 88 | This stage begins execution from the platform's reset vector at EL3. The reset |
| 89 | address is platform dependent but it is usually located in a Trusted ROM area. |
| 90 | The BL1 data section is copied to trusted SRAM at runtime. |
| 91 | |
| 92 | On the ARM development platforms, BL1 code starts execution from the reset |
| 93 | vector defined by the constant ``BL1_RO_BASE``. The BL1 data section is copied |
| 94 | to the top of trusted SRAM as defined by the constant ``BL1_RW_BASE``. |
| 95 | |
| 96 | The functionality implemented by this stage is as follows. |
| 97 | |
| 98 | Determination of boot path |
| 99 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 100 | |
| 101 | Whenever a CPU is released from reset, BL1 needs to distinguish between a warm |
| 102 | boot and a cold boot. This is done using platform-specific mechanisms (see the |
| 103 | ``plat_get_my_entrypoint()`` function in the `Porting Guide`_). In the case of a |
| 104 | warm boot, a CPU is expected to continue execution from a separate |
| 105 | entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe |
| 106 | platform-specific state (see the ``plat_secondary_cold_boot_setup()`` function in |
| 107 | the `Porting Guide`_) while the primary CPU executes the remaining cold boot path |
| 108 | as described in the following sections. |
| 109 | |
| 110 | This step only applies when ``PROGRAMMABLE_RESET_ADDRESS=0``. Refer to the |
| 111 | `Reset Design`_ for more information on the effect of the |
| 112 | ``PROGRAMMABLE_RESET_ADDRESS`` platform build option. |
| 113 | |
| 114 | Architectural initialization |
| 115 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 116 | |
| 117 | BL1 performs minimal architectural initialization as follows. |
| 118 | |
| 119 | - Exception vectors |
| 120 | |
| 121 | BL1 sets up simple exception vectors for both synchronous and asynchronous |
| 122 | exceptions. The default behavior upon receiving an exception is to populate |
| 123 | a status code in the general purpose register ``X0/R0`` and call the |
| 124 | ``plat_report_exception()`` function (see the `Porting Guide`_). The status |
| 125 | code is one of: |
| 126 | |
| 127 | For AArch64: |
| 128 | |
| 129 | :: |
| 130 | |
| 131 | 0x0 : Synchronous exception from Current EL with SP_EL0 |
| 132 | 0x1 : IRQ exception from Current EL with SP_EL0 |
| 133 | 0x2 : FIQ exception from Current EL with SP_EL0 |
| 134 | 0x3 : System Error exception from Current EL with SP_EL0 |
| 135 | 0x4 : Synchronous exception from Current EL with SP_ELx |
| 136 | 0x5 : IRQ exception from Current EL with SP_ELx |
| 137 | 0x6 : FIQ exception from Current EL with SP_ELx |
| 138 | 0x7 : System Error exception from Current EL with SP_ELx |
| 139 | 0x8 : Synchronous exception from Lower EL using aarch64 |
| 140 | 0x9 : IRQ exception from Lower EL using aarch64 |
| 141 | 0xa : FIQ exception from Lower EL using aarch64 |
| 142 | 0xb : System Error exception from Lower EL using aarch64 |
| 143 | 0xc : Synchronous exception from Lower EL using aarch32 |
| 144 | 0xd : IRQ exception from Lower EL using aarch32 |
| 145 | 0xe : FIQ exception from Lower EL using aarch32 |
| 146 | 0xf : System Error exception from Lower EL using aarch32 |
| 147 | |
| 148 | For AArch32: |
| 149 | |
| 150 | :: |
| 151 | |
| 152 | 0x10 : User mode |
| 153 | 0x11 : FIQ mode |
| 154 | 0x12 : IRQ mode |
| 155 | 0x13 : SVC mode |
| 156 | 0x16 : Monitor mode |
| 157 | 0x17 : Abort mode |
| 158 | 0x1a : Hypervisor mode |
| 159 | 0x1b : Undefined mode |
| 160 | 0x1f : System mode |
| 161 | |
| 162 | The ``plat_report_exception()`` implementation on the ARM FVP port programs |
| 163 | the Versatile Express System LED register in the following format to |
| 164 | indicate the occurence of an unexpected exception: |
| 165 | |
| 166 | :: |
| 167 | |
| 168 | SYS_LED[0] - Security state (Secure=0/Non-Secure=1) |
| 169 | SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0) |
| 170 | For AArch32 it is always 0x0 |
| 171 | SYS_LED[7:3] - Exception Class (Sync/Async & origin). This is the value |
| 172 | of the status code |
| 173 | |
| 174 | A write to the LED register reflects in the System LEDs (S6LED0..7) in the |
| 175 | CLCD window of the FVP. |
| 176 | |
| 177 | BL1 does not expect to receive any exceptions other than the SMC exception. |
| 178 | For the latter, BL1 installs a simple stub. The stub expects to receive a |
| 179 | limited set of SMC types (determined by their function IDs in the general |
| 180 | purpose register ``X0/R0``): |
| 181 | |
| 182 | - ``BL1_SMC_RUN_IMAGE``: This SMC is raised by BL2 to make BL1 pass control |
| 183 | to EL3 Runtime Software. |
| 184 | - All SMCs listed in section "BL1 SMC Interface" in the `Firmware Update`_ |
| 185 | Design Guide are supported for AArch64 only. These SMCs are currently |
| 186 | not supported when BL1 is built for AArch32. |
| 187 | |
| 188 | Any other SMC leads to an assertion failure. |
| 189 | |
| 190 | - CPU initialization |
| 191 | |
| 192 | BL1 calls the ``reset_handler()`` function which in turn calls the CPU |
| 193 | specific reset handler function (see the section: "CPU specific operations |
| 194 | framework"). |
| 195 | |
| 196 | - Control register setup (for AArch64) |
| 197 | |
| 198 | - ``SCTLR_EL3``. Instruction cache is enabled by setting the ``SCTLR_EL3.I`` |
| 199 | bit. Alignment and stack alignment checking is enabled by setting the |
| 200 | ``SCTLR_EL3.A`` and ``SCTLR_EL3.SA`` bits. Exception endianness is set to |
| 201 | little-endian by clearing the ``SCTLR_EL3.EE`` bit. |
| 202 | |
| 203 | - ``SCR_EL3``. The register width of the next lower exception level is set |
| 204 | to AArch64 by setting the ``SCR.RW`` bit. The ``SCR.EA`` bit is set to trap |
| 205 | both External Aborts and SError Interrupts in EL3. The ``SCR.SIF`` bit is |
| 206 | also set to disable instruction fetches from Non-secure memory when in |
| 207 | secure state. |
| 208 | |
| 209 | - ``CPTR_EL3``. Accesses to the ``CPACR_EL1`` register from EL1 or EL2, or the |
| 210 | ``CPTR_EL2`` register from EL2 are configured to not trap to EL3 by |
| 211 | clearing the ``CPTR_EL3.TCPAC`` bit. Access to the trace functionality is |
| 212 | configured not to trap to EL3 by clearing the ``CPTR_EL3.TTA`` bit. |
| 213 | Instructions that access the registers associated with Floating Point |
| 214 | and Advanced SIMD execution are configured to not trap to EL3 by |
| 215 | clearing the ``CPTR_EL3.TFP`` bit. |
| 216 | |
| 217 | - ``DAIF``. The SError interrupt is enabled by clearing the SError interrupt |
| 218 | mask bit. |
| 219 | |
| 220 | - ``MDCR_EL3``. The trap controls, ``MDCR_EL3.TDOSA``, ``MDCR_EL3.TDA`` and |
| 221 | ``MDCR_EL3.TPM``, are set so that accesses to the registers they control |
| 222 | do not trap to EL3. AArch64 Secure self-hosted debug is disabled by |
| 223 | setting the ``MDCR_EL3.SDD`` bit. Also ``MDCR_EL3.SPD32`` is set to |
| 224 | disable AArch32 Secure self-hosted privileged debug from S-EL1. |
| 225 | |
| 226 | - Control register setup (for AArch32) |
| 227 | |
| 228 | - ``SCTLR``. Instruction cache is enabled by setting the ``SCTLR.I`` bit. |
| 229 | Alignment checking is enabled by setting the ``SCTLR.A`` bit. |
| 230 | Exception endianness is set to little-endian by clearing the |
| 231 | ``SCTLR.EE`` bit. |
| 232 | |
| 233 | - ``SCR``. The ``SCR.SIF`` bit is set to disable instruction fetches from |
| 234 | Non-secure memory when in secure state. |
| 235 | |
| 236 | - ``CPACR``. Allow execution of Advanced SIMD instructions at PL0 and PL1, |
| 237 | by clearing the ``CPACR.ASEDIS`` bit. Access to the trace functionality |
| 238 | is configured not to trap to undefined mode by clearing the |
| 239 | ``CPACR.TRCDIS`` bit. |
| 240 | |
| 241 | - ``NSACR``. Enable non-secure access to Advanced SIMD functionality and |
| 242 | system register access to implemented trace registers. |
| 243 | |
| 244 | - ``FPEXC``. Enable access to the Advanced SIMD and floating-point |
| 245 | functionality from all Exception levels. |
| 246 | |
| 247 | - ``CPSR.A``. The Asynchronous data abort interrupt is enabled by clearing |
| 248 | the Asynchronous data abort interrupt mask bit. |
| 249 | |
| 250 | - ``SDCR``. The ``SDCR.SPD`` field is set to disable AArch32 Secure |
| 251 | self-hosted privileged debug. |
| 252 | |
| 253 | Platform initialization |
| 254 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 255 | |
| 256 | On ARM platforms, BL1 performs the following platform initializations: |
| 257 | |
| 258 | - Enable the Trusted Watchdog. |
| 259 | - Initialize the console. |
| 260 | - Configure the Interconnect to enable hardware coherency. |
| 261 | - Enable the MMU and map the memory it needs to access. |
| 262 | - Configure any required platform storage to load the next bootloader image |
| 263 | (BL2). |
| 264 | |
| 265 | Firmware Update detection and execution |
| 266 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 267 | |
| 268 | After performing platform setup, BL1 common code calls |
| 269 | ``bl1_plat_get_next_image_id()`` to determine if `Firmware Update`_ is required or |
| 270 | to proceed with the normal boot process. If the platform code returns |
| 271 | ``BL2_IMAGE_ID`` then the normal boot sequence is executed as described in the |
| 272 | next section, else BL1 assumes that `Firmware Update`_ is required and execution |
| 273 | passes to the first image in the `Firmware Update`_ process. In either case, BL1 |
| 274 | retrieves a descriptor of the next image by calling ``bl1_plat_get_image_desc()``. |
| 275 | The image descriptor contains an ``entry_point_info_t`` structure, which BL1 |
| 276 | uses to initialize the execution state of the next image. |
| 277 | |
| 278 | BL2 image load and execution |
| 279 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 280 | |
| 281 | In the normal boot flow, BL1 execution continues as follows: |
| 282 | |
| 283 | #. BL1 prints the following string from the primary CPU to indicate successful |
| 284 | execution of the BL1 stage: |
| 285 | |
| 286 | :: |
| 287 | |
| 288 | "Booting Trusted Firmware" |
| 289 | |
| 290 | #. BL1 determines the amount of free trusted SRAM memory available by |
| 291 | calculating the extent of its own data section, which also resides in |
| 292 | trusted SRAM. BL1 loads a BL2 raw binary image from platform storage, at a |
| 293 | platform-specific base address. If the BL2 image file is not present or if |
| 294 | there is not enough free trusted SRAM the following error message is |
| 295 | printed: |
| 296 | |
| 297 | :: |
| 298 | |
| 299 | "Failed to load BL2 firmware." |
| 300 | |
| 301 | BL1 calculates the amount of Trusted SRAM that can be used by the BL2 |
| 302 | image. The exact load location of the image is provided as a base address |
| 303 | in the platform header. Further description of the memory layout can be |
| 304 | found later in this document. |
| 305 | |
| 306 | #. BL1 passes control to the BL2 image at Secure EL1 (for AArch64) or at |
| 307 | Secure SVC mode (for AArch32), starting from its load address. |
| 308 | |
| 309 | #. BL1 also passes information about the amount of trusted SRAM used and |
| 310 | available for use. This information is populated at a platform-specific |
| 311 | memory address. |
| 312 | |
| 313 | BL2 |
| 314 | ~~~ |
| 315 | |
| 316 | BL1 loads and passes control to BL2 at Secure-EL1 (for AArch64) or at Secure |
| 317 | SVC mode (for AArch32) . BL2 is linked against and loaded at a platform-specific |
| 318 | base address (more information can be found later in this document). |
| 319 | The functionality implemented by BL2 is as follows. |
| 320 | |
| 321 | Architectural initialization |
| 322 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 323 | |
| 324 | For AArch64, BL2 performs the minimal architectural initialization required |
| 325 | for subsequent stages of the ARM Trusted Firmware and normal world software. |
| 326 | EL1 and EL0 are given access to Floating Point and Advanced SIMD registers |
| 327 | by clearing the ``CPACR.FPEN`` bits. |
| 328 | |
| 329 | For AArch32, the minimal architectural initialization required for subsequent |
| 330 | stages of the ARM Trusted Firmware and normal world software is taken care of |
| 331 | in BL1 as both BL1 and BL2 execute at PL1. |
| 332 | |
| 333 | Platform initialization |
| 334 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 335 | |
| 336 | On ARM platforms, BL2 performs the following platform initializations: |
| 337 | |
| 338 | - Initialize the console. |
| 339 | - Configure any required platform storage to allow loading further bootloader |
| 340 | images. |
| 341 | - Enable the MMU and map the memory it needs to access. |
| 342 | - Perform platform security setup to allow access to controlled components. |
| 343 | - Reserve some memory for passing information to the next bootloader image |
| 344 | EL3 Runtime Software and populate it. |
| 345 | - Define the extents of memory available for loading each subsequent |
| 346 | bootloader image. |
| 347 | |
| 348 | Image loading in BL2 |
| 349 | ^^^^^^^^^^^^^^^^^^^^ |
| 350 | |
| 351 | Image loading scheme in BL2 depends on ``LOAD_IMAGE_V2`` build option. If the |
| 352 | flag is disabled, the BLxx images are loaded, by calling the respective |
| 353 | load\_blxx() function from BL2 generic code. If the flag is enabled, the BL2 |
| 354 | generic code loads the images based on the list of loadable images provided |
| 355 | by the platform. BL2 passes the list of executable images provided by the |
| 356 | platform to the next handover BL image. By default, this flag is disabled for |
| 357 | AArch64 and the AArch32 build is supported only if this flag is enabled. |
| 358 | |
| 359 | SCP\_BL2 (System Control Processor Firmware) image load |
| 360 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 361 | |
| 362 | Some systems have a separate System Control Processor (SCP) for power, clock, |
| 363 | reset and system control. BL2 loads the optional SCP\_BL2 image from platform |
| 364 | storage into a platform-specific region of secure memory. The subsequent |
| 365 | handling of SCP\_BL2 is platform specific. For example, on the Juno ARM |
| 366 | development platform port the image is transferred into SCP's internal memory |
| 367 | using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM |
| 368 | memory. The SCP executes SCP\_BL2 and signals to the Application Processor (AP) |
| 369 | for BL2 execution to continue. |
| 370 | |
| 371 | EL3 Runtime Software image load |
| 372 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 373 | |
| 374 | BL2 loads the EL3 Runtime Software image from platform storage into a platform- |
| 375 | specific address in trusted SRAM. If there is not enough memory to load the |
| 376 | image or image is missing it leads to an assertion failure. If ``LOAD_IMAGE_V2`` |
| 377 | is disabled and if image loads successfully, BL2 updates the amount of trusted |
| 378 | SRAM used and available for use by EL3 Runtime Software. This information is |
| 379 | populated at a platform-specific memory address. |
| 380 | |
| 381 | AArch64 BL32 (Secure-EL1 Payload) image load |
| 382 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 383 | |
| 384 | BL2 loads the optional BL32 image from platform storage into a platform- |
| 385 | specific region of secure memory. The image executes in the secure world. BL2 |
| 386 | relies on BL31 to pass control to the BL32 image, if present. Hence, BL2 |
| 387 | populates a platform-specific area of memory with the entrypoint/load-address |
| 388 | of the BL32 image. The value of the Saved Processor Status Register (``SPSR``) |
| 389 | for entry into BL32 is not determined by BL2, it is initialized by the |
| 390 | Secure-EL1 Payload Dispatcher (see later) within BL31, which is responsible for |
| 391 | managing interaction with BL32. This information is passed to BL31. |
| 392 | |
| 393 | BL33 (Non-trusted Firmware) image load |
| 394 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 395 | |
| 396 | BL2 loads the BL33 image (e.g. UEFI or other test or boot software) from |
| 397 | platform storage into non-secure memory as defined by the platform. |
| 398 | |
| 399 | BL2 relies on EL3 Runtime Software to pass control to BL33 once secure state |
| 400 | initialization is complete. Hence, BL2 populates a platform-specific area of |
| 401 | memory with the entrypoint and Saved Program Status Register (``SPSR``) of the |
| 402 | normal world software image. The entrypoint is the load address of the BL33 |
| 403 | image. The ``SPSR`` is determined as specified in Section 5.13 of the |
| 404 | `PSCI PDD`_. This information is passed to the EL3 Runtime Software. |
| 405 | |
| 406 | AArch64 BL31 (EL3 Runtime Software) execution |
| 407 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 408 | |
| 409 | BL2 execution continues as follows: |
| 410 | |
| 411 | #. BL2 passes control back to BL1 by raising an SMC, providing BL1 with the |
| 412 | BL31 entrypoint. The exception is handled by the SMC exception handler |
| 413 | installed by BL1. |
| 414 | |
| 415 | #. BL1 turns off the MMU and flushes the caches. It clears the |
| 416 | ``SCTLR_EL3.M/I/C`` bits, flushes the data cache to the point of coherency |
| 417 | and invalidates the TLBs. |
| 418 | |
| 419 | #. BL1 passes control to BL31 at the specified entrypoint at EL3. |
| 420 | |
| 421 | AArch64 BL31 |
| 422 | ~~~~~~~~~~~~ |
| 423 | |
| 424 | The image for this stage is loaded by BL2 and BL1 passes control to BL31 at |
| 425 | EL3. BL31 executes solely in trusted SRAM. BL31 is linked against and |
| 426 | loaded at a platform-specific base address (more information can be found later |
| 427 | in this document). The functionality implemented by BL31 is as follows. |
| 428 | |
| 429 | Architectural initialization |
| 430 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 431 | |
| 432 | Currently, BL31 performs a similar architectural initialization to BL1 as |
| 433 | far as system register settings are concerned. Since BL1 code resides in ROM, |
| 434 | architectural initialization in BL31 allows override of any previous |
| 435 | initialization done by BL1. |
| 436 | |
| 437 | BL31 initializes the per-CPU data framework, which provides a cache of |
| 438 | frequently accessed per-CPU data optimised for fast, concurrent manipulation |
| 439 | on different CPUs. This buffer includes pointers to per-CPU contexts, crash |
| 440 | buffer, CPU reset and power down operations, PSCI data, platform data and so on. |
| 441 | |
| 442 | It then replaces the exception vectors populated by BL1 with its own. BL31 |
| 443 | exception vectors implement more elaborate support for handling SMCs since this |
| 444 | is the only mechanism to access the runtime services implemented by BL31 (PSCI |
| 445 | for example). BL31 checks each SMC for validity as specified by the |
| 446 | `SMC calling convention PDD`_ before passing control to the required SMC |
| 447 | handler routine. |
| 448 | |
| 449 | BL31 programs the ``CNTFRQ_EL0`` register with the clock frequency of the system |
| 450 | counter, which is provided by the platform. |
| 451 | |
| 452 | Platform initialization |
| 453 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 454 | |
| 455 | BL31 performs detailed platform initialization, which enables normal world |
| 456 | software to function correctly. |
| 457 | |
| 458 | On ARM platforms, this consists of the following: |
| 459 | |
| 460 | - Initialize the console. |
| 461 | - Configure the Interconnect to enable hardware coherency. |
| 462 | - Enable the MMU and map the memory it needs to access. |
| 463 | - Initialize the generic interrupt controller. |
| 464 | - Initialize the power controller device. |
| 465 | - Detect the system topology. |
| 466 | |
| 467 | Runtime services initialization |
| 468 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 469 | |
| 470 | BL31 is responsible for initializing the runtime services. One of them is PSCI. |
| 471 | |
| 472 | As part of the PSCI initializations, BL31 detects the system topology. It also |
| 473 | initializes the data structures that implement the state machine used to track |
| 474 | the state of power domain nodes. The state can be one of ``OFF``, ``RUN`` or |
| 475 | ``RETENTION``. All secondary CPUs are initially in the ``OFF`` state. The cluster |
| 476 | that the primary CPU belongs to is ``ON``; any other cluster is ``OFF``. It also |
| 477 | initializes the locks that protect them. BL31 accesses the state of a CPU or |
| 478 | cluster immediately after reset and before the data cache is enabled in the |
| 479 | warm boot path. It is not currently possible to use 'exclusive' based spinlocks, |
| 480 | therefore BL31 uses locks based on Lamport's Bakery algorithm instead. |
| 481 | |
| 482 | The runtime service framework and its initialization is described in more |
| 483 | detail in the "EL3 runtime services framework" section below. |
| 484 | |
| 485 | Details about the status of the PSCI implementation are provided in the |
| 486 | "Power State Coordination Interface" section below. |
| 487 | |
| 488 | AArch64 BL32 (Secure-EL1 Payload) image initialization |
| 489 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 490 | |
| 491 | If a BL32 image is present then there must be a matching Secure-EL1 Payload |
| 492 | Dispatcher (SPD) service (see later for details). During initialization |
| 493 | that service must register a function to carry out initialization of BL32 |
| 494 | once the runtime services are fully initialized. BL31 invokes such a |
| 495 | registered function to initialize BL32 before running BL33. This initialization |
| 496 | is not necessary for AArch32 SPs. |
| 497 | |
| 498 | Details on BL32 initialization and the SPD's role are described in the |
| 499 | "Secure-EL1 Payloads and Dispatchers" section below. |
| 500 | |
| 501 | BL33 (Non-trusted Firmware) execution |
| 502 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 503 | |
| 504 | EL3 Runtime Software initializes the EL2 or EL1 processor context for normal- |
| 505 | world cold boot, ensuring that no secure state information finds its way into |
| 506 | the non-secure execution state. EL3 Runtime Software uses the entrypoint |
| 507 | information provided by BL2 to jump to the Non-trusted firmware image (BL33) |
| 508 | at the highest available Exception Level (EL2 if available, otherwise EL1). |
| 509 | |
| 510 | Using alternative Trusted Boot Firmware in place of BL1 & BL2 (AArch64 only) |
| 511 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 512 | |
| 513 | Some platforms have existing implementations of Trusted Boot Firmware that |
| 514 | would like to use ARM Trusted Firmware BL31 for the EL3 Runtime Software. To |
| 515 | enable this firmware architecture it is important to provide a fully documented |
| 516 | and stable interface between the Trusted Boot Firmware and BL31. |
| 517 | |
| 518 | Future changes to the BL31 interface will be done in a backwards compatible |
| 519 | way, and this enables these firmware components to be independently enhanced/ |
| 520 | updated to develop and exploit new functionality. |
| 521 | |
| 522 | Required CPU state when calling ``bl31_entrypoint()`` during cold boot |
| 523 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 524 | |
| 525 | This function must only be called by the primary CPU. |
| 526 | |
| 527 | On entry to this function the calling primary CPU must be executing in AArch64 |
| 528 | EL3, little-endian data access, and all interrupt sources masked: |
| 529 | |
| 530 | :: |
| 531 | |
| 532 | PSTATE.EL = 3 |
| 533 | PSTATE.RW = 1 |
| 534 | PSTATE.DAIF = 0xf |
| 535 | SCTLR_EL3.EE = 0 |
| 536 | |
| 537 | X0 and X1 can be used to pass information from the Trusted Boot Firmware to the |
| 538 | platform code in BL31: |
| 539 | |
| 540 | :: |
| 541 | |
| 542 | X0 : Reserved for common Trusted Firmware information |
| 543 | X1 : Platform specific information |
| 544 | |
| 545 | BL31 zero-init sections (e.g. ``.bss``) should not contain valid data on entry, |
| 546 | these will be zero filled prior to invoking platform setup code. |
| 547 | |
| 548 | Use of the X0 and X1 parameters |
| 549 | ''''''''''''''''''''''''''''''' |
| 550 | |
| 551 | The parameters are platform specific and passed from ``bl31_entrypoint()`` to |
| 552 | ``bl31_early_platform_setup()``. The value of these parameters is never directly |
| 553 | used by the common BL31 code. |
| 554 | |
| 555 | The convention is that ``X0`` conveys information regarding the BL31, BL32 and |
| 556 | BL33 images from the Trusted Boot firmware and ``X1`` can be used for other |
| 557 | platform specific purpose. This convention allows platforms which use ARM |
| 558 | Trusted Firmware's BL1 and BL2 images to transfer additional platform specific |
| 559 | information from Secure Boot without conflicting with future evolution of the |
| 560 | Trusted Firmware using ``X0`` to pass a ``bl31_params`` structure. |
| 561 | |
| 562 | BL31 common and SPD initialization code depends on image and entrypoint |
| 563 | information about BL33 and BL32, which is provided via BL31 platform APIs. |
| 564 | This information is required until the start of execution of BL33. This |
| 565 | information can be provided in a platform defined manner, e.g. compiled into |
| 566 | the platform code in BL31, or provided in a platform defined memory location |
| 567 | by the Trusted Boot firmware, or passed from the Trusted Boot Firmware via the |
| 568 | Cold boot Initialization parameters. This data may need to be cleaned out of |
| 569 | the CPU caches if it is provided by an earlier boot stage and then accessed by |
| 570 | BL31 platform code before the caches are enabled. |
| 571 | |
| 572 | ARM Trusted Firmware's BL2 implementation passes a ``bl31_params`` structure in |
| 573 | ``X0`` and the ARM development platforms interpret this in the BL31 platform |
| 574 | code. |
| 575 | |
| 576 | MMU, Data caches & Coherency |
| 577 | '''''''''''''''''''''''''''' |
| 578 | |
| 579 | BL31 does not depend on the enabled state of the MMU, data caches or |
| 580 | interconnect coherency on entry to ``bl31_entrypoint()``. If these are disabled |
| 581 | on entry, these should be enabled during ``bl31_plat_arch_setup()``. |
| 582 | |
| 583 | Data structures used in the BL31 cold boot interface |
| 584 | '''''''''''''''''''''''''''''''''''''''''''''''''''' |
| 585 | |
| 586 | These structures are designed to support compatibility and independent |
| 587 | evolution of the structures and the firmware images. For example, a version of |
| 588 | BL31 that can interpret the BL3x image information from different versions of |
| 589 | BL2, a platform that uses an extended entry\_point\_info structure to convey |
| 590 | additional register information to BL31, or a ELF image loader that can convey |
| 591 | more details about the firmware images. |
| 592 | |
| 593 | To support these scenarios the structures are versioned and sized, which enables |
| 594 | BL31 to detect which information is present and respond appropriately. The |
| 595 | ``param_header`` is defined to capture this information: |
| 596 | |
| 597 | .. code:: c |
| 598 | |
| 599 | typedef struct param_header { |
| 600 | uint8_t type; /* type of the structure */ |
| 601 | uint8_t version; /* version of this structure */ |
| 602 | uint16_t size; /* size of this structure in bytes */ |
| 603 | uint32_t attr; /* attributes: unused bits SBZ */ |
| 604 | } param_header_t; |
| 605 | |
| 606 | The structures using this format are ``entry_point_info``, ``image_info`` and |
| 607 | ``bl31_params``. The code that allocates and populates these structures must set |
| 608 | the header fields appropriately, and the ``SET_PARAM_HEAD()`` a macro is defined |
| 609 | to simplify this action. |
| 610 | |
| 611 | Required CPU state for BL31 Warm boot initialization |
| 612 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 613 | |
| 614 | When requesting a CPU power-on, or suspending a running CPU, ARM Trusted |
| 615 | Firmware provides the platform power management code with a Warm boot |
| 616 | initialization entry-point, to be invoked by the CPU immediately after the |
| 617 | reset handler. On entry to the Warm boot initialization function the calling |
| 618 | CPU must be in AArch64 EL3, little-endian data access and all interrupt sources |
| 619 | masked: |
| 620 | |
| 621 | :: |
| 622 | |
| 623 | PSTATE.EL = 3 |
| 624 | PSTATE.RW = 1 |
| 625 | PSTATE.DAIF = 0xf |
| 626 | SCTLR_EL3.EE = 0 |
| 627 | |
| 628 | The PSCI implementation will initialize the processor state and ensure that the |
| 629 | platform power management code is then invoked as required to initialize all |
| 630 | necessary system, cluster and CPU resources. |
| 631 | |
| 632 | AArch32 EL3 Runtime Software entrypoint interface |
| 633 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 634 | |
| 635 | To enable this firmware architecture it is important to provide a fully |
| 636 | documented and stable interface between the Trusted Boot Firmware and the |
| 637 | AArch32 EL3 Runtime Software. |
| 638 | |
| 639 | Future changes to the entrypoint interface will be done in a backwards |
| 640 | compatible way, and this enables these firmware components to be independently |
| 641 | enhanced/updated to develop and exploit new functionality. |
| 642 | |
| 643 | Required CPU state when entering during cold boot |
| 644 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 645 | |
| 646 | This function must only be called by the primary CPU. |
| 647 | |
| 648 | On entry to this function the calling primary CPU must be executing in AArch32 |
| 649 | EL3, little-endian data access, and all interrupt sources masked: |
| 650 | |
| 651 | :: |
| 652 | |
| 653 | PSTATE.AIF = 0x7 |
| 654 | SCTLR.EE = 0 |
| 655 | |
| 656 | R0 and R1 are used to pass information from the Trusted Boot Firmware to the |
| 657 | platform code in AArch32 EL3 Runtime Software: |
| 658 | |
| 659 | :: |
| 660 | |
| 661 | R0 : Reserved for common Trusted Firmware information |
| 662 | R1 : Platform specific information |
| 663 | |
| 664 | Use of the R0 and R1 parameters |
| 665 | ''''''''''''''''''''''''''''''' |
| 666 | |
| 667 | The parameters are platform specific and the convention is that ``R0`` conveys |
| 668 | information regarding the BL3x images from the Trusted Boot firmware and ``R1`` |
| 669 | can be used for other platform specific purpose. This convention allows |
| 670 | platforms which use ARM Trusted Firmware's BL1 and BL2 images to transfer |
| 671 | additional platform specific information from Secure Boot without conflicting |
| 672 | with future evolution of the Trusted Firmware using ``R0`` to pass a ``bl_params`` |
| 673 | structure. |
| 674 | |
| 675 | The AArch32 EL3 Runtime Software is responsible for entry into BL33. This |
| 676 | information can be obtained in a platform defined manner, e.g. compiled into |
| 677 | the AArch32 EL3 Runtime Software, or provided in a platform defined memory |
| 678 | location by the Trusted Boot firmware, or passed from the Trusted Boot Firmware |
| 679 | via the Cold boot Initialization parameters. This data may need to be cleaned |
| 680 | out of the CPU caches if it is provided by an earlier boot stage and then |
| 681 | accessed by AArch32 EL3 Runtime Software before the caches are enabled. |
| 682 | |
| 683 | When using AArch32 EL3 Runtime Software, the ARM development platforms pass a |
| 684 | ``bl_params`` structure in ``R0`` from BL2 to be interpreted by AArch32 EL3 Runtime |
| 685 | Software platform code. |
| 686 | |
| 687 | MMU, Data caches & Coherency |
| 688 | '''''''''''''''''''''''''''' |
| 689 | |
| 690 | AArch32 EL3 Runtime Software must not depend on the enabled state of the MMU, |
| 691 | data caches or interconnect coherency in its entrypoint. They must be explicitly |
| 692 | enabled if required. |
| 693 | |
| 694 | Data structures used in cold boot interface |
| 695 | ''''''''''''''''''''''''''''''''''''''''''' |
| 696 | |
| 697 | The AArch32 EL3 Runtime Software cold boot interface uses ``bl_params`` instead |
| 698 | of ``bl31_params``. The ``bl_params`` structure is based on the convention |
| 699 | described in AArch64 BL31 cold boot interface section. |
| 700 | |
| 701 | Required CPU state for warm boot initialization |
| 702 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 703 | |
| 704 | When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3 |
| 705 | Runtime Software must ensure execution of a warm boot initialization entrypoint. |
| 706 | If ARM Trusted Firmware BL1 is used and the PROGRAMMABLE\_RESET\_ADDRESS build |
| 707 | flag is false, then AArch32 EL3 Runtime Software must ensure that BL1 branches |
| 708 | to the warm boot entrypoint by arranging for the BL1 platform function, |
| 709 | plat\_get\_my\_entrypoint(), to return a non-zero value. |
| 710 | |
| 711 | In this case, the warm boot entrypoint must be in AArch32 EL3, little-endian |
| 712 | data access and all interrupt sources masked: |
| 713 | |
| 714 | :: |
| 715 | |
| 716 | PSTATE.AIF = 0x7 |
| 717 | SCTLR.EE = 0 |
| 718 | |
| 719 | The warm boot entrypoint may be implemented by using the ARM Trusted Firmware |
| 720 | ``psci_warmboot_entrypoint()`` function. In that case, the platform must fulfil |
| 721 | the pre-requisites mentioned in the `PSCI Library integration guide`_. |
| 722 | |
| 723 | EL3 runtime services framework |
| 724 | ------------------------------ |
| 725 | |
| 726 | Software executing in the non-secure state and in the secure state at exception |
| 727 | levels lower than EL3 will request runtime services using the Secure Monitor |
| 728 | Call (SMC) instruction. These requests will follow the convention described in |
| 729 | the SMC Calling Convention PDD (`SMCCC`_). The `SMCCC`_ assigns function |
| 730 | identifiers to each SMC request and describes how arguments are passed and |
| 731 | returned. |
| 732 | |
| 733 | The EL3 runtime services framework enables the development of services by |
| 734 | different providers that can be easily integrated into final product firmware. |
| 735 | The following sections describe the framework which facilitates the |
| 736 | registration, initialization and use of runtime services in EL3 Runtime |
| 737 | Software (BL31). |
| 738 | |
| 739 | The design of the runtime services depends heavily on the concepts and |
| 740 | definitions described in the `SMCCC`_, in particular SMC Function IDs, Owning |
| 741 | Entity Numbers (OEN), Fast and Yielding calls, and the SMC32 and SMC64 calling |
| 742 | conventions. Please refer to that document for more detailed explanation of |
| 743 | these terms. |
| 744 | |
| 745 | The following runtime services are expected to be implemented first. They have |
| 746 | not all been instantiated in the current implementation. |
| 747 | |
| 748 | #. Standard service calls |
| 749 | |
| 750 | This service is for management of the entire system. The Power State |
| 751 | Coordination Interface (`PSCI`_) is the first set of standard service calls |
| 752 | defined by ARM (see PSCI section later). |
| 753 | |
| 754 | #. Secure-EL1 Payload Dispatcher service |
| 755 | |
| 756 | If a system runs a Trusted OS or other Secure-EL1 Payload (SP) then |
| 757 | it also requires a *Secure Monitor* at EL3 to switch the EL1 processor |
| 758 | context between the normal world (EL1/EL2) and trusted world (Secure-EL1). |
| 759 | The Secure Monitor will make these world switches in response to SMCs. The |
| 760 | `SMCCC`_ provides for such SMCs with the Trusted OS Call and Trusted |
| 761 | Application Call OEN ranges. |
| 762 | |
| 763 | The interface between the EL3 Runtime Software and the Secure-EL1 Payload is |
| 764 | not defined by the `SMCCC`_ or any other standard. As a result, each |
| 765 | Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime |
| 766 | service - within ARM Trusted Firmware this service is referred to as the |
| 767 | Secure-EL1 Payload Dispatcher (SPD). |
| 768 | |
| 769 | ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and its |
| 770 | associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation |
| 771 | are described in the "Secure-EL1 Payloads and Dispatchers" section below. |
| 772 | |
| 773 | #. CPU implementation service |
| 774 | |
| 775 | This service will provide an interface to CPU implementation specific |
| 776 | services for a given platform e.g. access to processor errata workarounds. |
| 777 | This service is currently unimplemented. |
| 778 | |
| 779 | Additional services for ARM Architecture, SiP and OEM calls can be implemented. |
| 780 | Each implemented service handles a range of SMC function identifiers as |
| 781 | described in the `SMCCC`_. |
| 782 | |
| 783 | Registration |
| 784 | ~~~~~~~~~~~~ |
| 785 | |
| 786 | A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying |
| 787 | the name of the service, the range of OENs covered, the type of service and |
| 788 | initialization and call handler functions. This macro instantiates a ``const struct rt_svc_desc`` for the service with these details (see ``runtime_svc.h``). |
| 789 | This structure is allocated in a special ELF section ``rt_svc_descs``, enabling |
| 790 | the framework to find all service descriptors included into BL31. |
| 791 | |
| 792 | The specific service for a SMC Function is selected based on the OEN and call |
| 793 | type of the Function ID, and the framework uses that information in the service |
| 794 | descriptor to identify the handler for the SMC Call. |
| 795 | |
| 796 | The service descriptors do not include information to identify the precise set |
| 797 | of SMC function identifiers supported by this service implementation, the |
| 798 | security state from which such calls are valid nor the capability to support |
| 799 | 64-bit and/or 32-bit callers (using SMC32 or SMC64). Responding appropriately |
| 800 | to these aspects of a SMC call is the responsibility of the service |
| 801 | implementation, the framework is focused on integration of services from |
| 802 | different providers and minimizing the time taken by the framework before the |
| 803 | service handler is invoked. |
| 804 | |
| 805 | Details of the parameters, requirements and behavior of the initialization and |
| 806 | call handling functions are provided in the following sections. |
| 807 | |
| 808 | Initialization |
| 809 | ~~~~~~~~~~~~~~ |
| 810 | |
| 811 | ``runtime_svc_init()`` in ``runtime_svc.c`` initializes the runtime services |
| 812 | framework running on the primary CPU during cold boot as part of the BL31 |
| 813 | initialization. This happens prior to initializing a Trusted OS and running |
| 814 | Normal world boot firmware that might in turn use these services. |
| 815 | Initialization involves validating each of the declared runtime service |
| 816 | descriptors, calling the service initialization function and populating the |
| 817 | index used for runtime lookup of the service. |
| 818 | |
| 819 | The BL31 linker script collects all of the declared service descriptors into a |
| 820 | single array and defines symbols that allow the framework to locate and traverse |
| 821 | the array, and determine its size. |
| 822 | |
| 823 | The framework does basic validation of each descriptor to halt firmware |
| 824 | initialization if service declaration errors are detected. The framework does |
| 825 | not check descriptors for the following error conditions, and may behave in an |
| 826 | unpredictable manner under such scenarios: |
| 827 | |
| 828 | #. Overlapping OEN ranges |
| 829 | #. Multiple descriptors for the same range of OENs and ``call_type`` |
| 830 | #. Incorrect range of owning entity numbers for a given ``call_type`` |
| 831 | |
| 832 | Once validated, the service ``init()`` callback is invoked. This function carries |
| 833 | out any essential EL3 initialization before servicing requests. The ``init()`` |
| 834 | function is only invoked on the primary CPU during cold boot. If the service |
| 835 | uses per-CPU data this must either be initialized for all CPUs during this call, |
| 836 | or be done lazily when a CPU first issues an SMC call to that service. If |
| 837 | ``init()`` returns anything other than ``0``, this is treated as an initialization |
| 838 | error and the service is ignored: this does not cause the firmware to halt. |
| 839 | |
| 840 | The OEN and call type fields present in the SMC Function ID cover a total of |
| 841 | 128 distinct services, but in practice a single descriptor can cover a range of |
| 842 | OENs, e.g. SMCs to call a Trusted OS function. To optimize the lookup of a |
| 843 | service handler, the framework uses an array of 128 indices that map every |
| 844 | distinct OEN/call-type combination either to one of the declared services or to |
| 845 | indicate the service is not handled. This ``rt_svc_descs_indices[]`` array is |
| 846 | populated for all of the OENs covered by a service after the service ``init()`` |
| 847 | function has reported success. So a service that fails to initialize will never |
| 848 | have it's ``handle()`` function invoked. |
| 849 | |
| 850 | The following figure shows how the ``rt_svc_descs_indices[]`` index maps the SMC |
| 851 | Function ID call type and OEN onto a specific service handler in the |
| 852 | ``rt_svc_descs[]`` array. |
| 853 | |
| 854 | |Image 1| |
| 855 | |
| 856 | Handling an SMC |
| 857 | ~~~~~~~~~~~~~~~ |
| 858 | |
| 859 | When the EL3 runtime services framework receives a Secure Monitor Call, the SMC |
| 860 | Function ID is passed in W0 from the lower exception level (as per the |
| 861 | `SMCCC`_). If the calling register width is AArch32, it is invalid to invoke an |
| 862 | SMC Function which indicates the SMC64 calling convention: such calls are |
| 863 | ignored and return the Unknown SMC Function Identifier result code ``0xFFFFFFFF`` |
| 864 | in R0/X0. |
| 865 | |
| 866 | Bit[31] (fast/yielding call) and bits[29:24] (owning entity number) of the SMC |
| 867 | Function ID are combined to index into the ``rt_svc_descs_indices[]`` array. The |
| 868 | resulting value might indicate a service that has no handler, in this case the |
| 869 | framework will also report an Unknown SMC Function ID. Otherwise, the value is |
| 870 | used as a further index into the ``rt_svc_descs[]`` array to locate the required |
| 871 | service and handler. |
| 872 | |
| 873 | The service's ``handle()`` callback is provided with five of the SMC parameters |
| 874 | directly, the others are saved into memory for retrieval (if needed) by the |
| 875 | handler. The handler is also provided with an opaque ``handle`` for use with the |
| 876 | supporting library for parameter retrieval, setting return values and context |
| 877 | manipulation; and with ``flags`` indicating the security state of the caller. The |
| 878 | framework finally sets up the execution stack for the handler, and invokes the |
| 879 | services ``handle()`` function. |
| 880 | |
| 881 | On return from the handler the result registers are populated in X0-X3 before |
| 882 | restoring the stack and CPU state and returning from the original SMC. |
| 883 | |
| 884 | Power State Coordination Interface |
| 885 | ---------------------------------- |
| 886 | |
| 887 | TODO: Provide design walkthrough of PSCI implementation. |
| 888 | |
Roberto Vargas | fe3e40e | 2017-09-12 10:28:35 +0100 | [diff] [blame] | 889 | The PSCI v1.1 specification categorizes APIs as optional and mandatory. All the |
| 890 | mandatory APIs in PSCI v1.1, PSCI v1.0 and in PSCI v0.2 draft specification |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 891 | `Power State Coordination Interface PDD`_ are implemented. The table lists |
Roberto Vargas | fe3e40e | 2017-09-12 10:28:35 +0100 | [diff] [blame] | 892 | the PSCI v1.1 APIs and their support in generic code. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 893 | |
| 894 | An API implementation might have a dependency on platform code e.g. CPU\_SUSPEND |
| 895 | requires the platform to export a part of the implementation. Hence the level |
| 896 | of support of the mandatory APIs depends upon the support exported by the |
| 897 | platform port as well. The Juno and FVP (all variants) platforms export all the |
| 898 | required support. |
| 899 | |
| 900 | +-----------------------------+-------------+-------------------------------+ |
Roberto Vargas | fe3e40e | 2017-09-12 10:28:35 +0100 | [diff] [blame] | 901 | | PSCI v1.1 API | Supported | Comments | |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 902 | +=============================+=============+===============================+ |
Roberto Vargas | fe3e40e | 2017-09-12 10:28:35 +0100 | [diff] [blame] | 903 | | ``PSCI_VERSION`` | Yes | The version returned is 1.1 | |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 904 | +-----------------------------+-------------+-------------------------------+ |
| 905 | | ``CPU_SUSPEND`` | Yes\* | | |
| 906 | +-----------------------------+-------------+-------------------------------+ |
| 907 | | ``CPU_OFF`` | Yes\* | | |
| 908 | +-----------------------------+-------------+-------------------------------+ |
| 909 | | ``CPU_ON`` | Yes\* | | |
| 910 | +-----------------------------+-------------+-------------------------------+ |
| 911 | | ``AFFINITY_INFO`` | Yes | | |
| 912 | +-----------------------------+-------------+-------------------------------+ |
| 913 | | ``MIGRATE`` | Yes\*\* | | |
| 914 | +-----------------------------+-------------+-------------------------------+ |
| 915 | | ``MIGRATE_INFO_TYPE`` | Yes\*\* | | |
| 916 | +-----------------------------+-------------+-------------------------------+ |
| 917 | | ``MIGRATE_INFO_CPU`` | Yes\*\* | | |
| 918 | +-----------------------------+-------------+-------------------------------+ |
| 919 | | ``SYSTEM_OFF`` | Yes\* | | |
| 920 | +-----------------------------+-------------+-------------------------------+ |
| 921 | | ``SYSTEM_RESET`` | Yes\* | | |
| 922 | +-----------------------------+-------------+-------------------------------+ |
| 923 | | ``PSCI_FEATURES`` | Yes | | |
| 924 | +-----------------------------+-------------+-------------------------------+ |
| 925 | | ``CPU_FREEZE`` | No | | |
| 926 | +-----------------------------+-------------+-------------------------------+ |
| 927 | | ``CPU_DEFAULT_SUSPEND`` | No | | |
| 928 | +-----------------------------+-------------+-------------------------------+ |
| 929 | | ``NODE_HW_STATE`` | Yes\* | | |
| 930 | +-----------------------------+-------------+-------------------------------+ |
| 931 | | ``SYSTEM_SUSPEND`` | Yes\* | | |
| 932 | +-----------------------------+-------------+-------------------------------+ |
| 933 | | ``PSCI_SET_SUSPEND_MODE`` | No | | |
| 934 | +-----------------------------+-------------+-------------------------------+ |
| 935 | | ``PSCI_STAT_RESIDENCY`` | Yes\* | | |
| 936 | +-----------------------------+-------------+-------------------------------+ |
| 937 | | ``PSCI_STAT_COUNT`` | Yes\* | | |
| 938 | +-----------------------------+-------------+-------------------------------+ |
Roberto Vargas | fe3e40e | 2017-09-12 10:28:35 +0100 | [diff] [blame] | 939 | | ``SYSTEM_RESET2`` | Yes\* | | |
| 940 | +-----------------------------+-------------+-------------------------------+ |
| 941 | | ``MEM_PROTECT`` | Yes\* | | |
| 942 | +-----------------------------+-------------+-------------------------------+ |
| 943 | | ``MEM_PROTECT_CHECK_RANGE`` | Yes\* | | |
| 944 | +-----------------------------+-------------+-------------------------------+ |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 945 | |
| 946 | \*Note : These PSCI APIs require platform power management hooks to be |
| 947 | registered with the generic PSCI code to be supported. |
| 948 | |
| 949 | \*\*Note : These PSCI APIs require appropriate Secure Payload Dispatcher |
| 950 | hooks to be registered with the generic PSCI code to be supported. |
| 951 | |
| 952 | The PSCI implementation in ARM Trusted Firmware is a library which can be |
| 953 | integrated with AArch64 or AArch32 EL3 Runtime Software for ARMv8-A systems. |
| 954 | A guide to integrating PSCI library with AArch32 EL3 Runtime Software |
| 955 | can be found `here`_. |
| 956 | |
| 957 | Secure-EL1 Payloads and Dispatchers |
| 958 | ----------------------------------- |
| 959 | |
| 960 | On a production system that includes a Trusted OS running in Secure-EL1/EL0, |
| 961 | the Trusted OS is coupled with a companion runtime service in the BL31 |
| 962 | firmware. This service is responsible for the initialisation of the Trusted |
| 963 | OS and all communications with it. The Trusted OS is the BL32 stage of the |
| 964 | boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load |
| 965 | and execute a BL32 image. |
| 966 | |
| 967 | ARM Trusted Firmware uses a more general term for the BL32 software that runs |
| 968 | at Secure-EL1 - the *Secure-EL1 Payload* - as it is not always a Trusted OS. |
| 969 | |
| 970 | The ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and a Test |
| 971 | Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS |
| 972 | is supported on a production system using the Runtime Services Framework. On |
| 973 | such a system, the Test BL32 image and service are replaced by the Trusted OS |
| 974 | and its dispatcher service. The ARM Trusted Firmware build system expects that |
| 975 | the dispatcher will define the build flag ``NEED_BL32`` to enable it to include |
| 976 | the BL32 in the build either as a binary or to compile from source depending |
| 977 | on whether the ``BL32`` build option is specified or not. |
| 978 | |
| 979 | The TSP runs in Secure-EL1. It is designed to demonstrate synchronous |
| 980 | communication with the normal-world software running in EL1/EL2. Communication |
| 981 | is initiated by the normal-world software |
| 982 | |
| 983 | - either directly through a Fast SMC (as defined in the `SMCCC`_) |
| 984 | |
| 985 | - or indirectly through a `PSCI`_ SMC. The `PSCI`_ implementation in turn |
| 986 | informs the TSPD about the requested power management operation. This allows |
| 987 | the TSP to prepare for or respond to the power state change |
| 988 | |
| 989 | The TSPD service is responsible for. |
| 990 | |
| 991 | - Initializing the TSP |
| 992 | |
| 993 | - Routing requests and responses between the secure and the non-secure |
| 994 | states during the two types of communications just described |
| 995 | |
| 996 | Initializing a BL32 Image |
| 997 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 998 | |
| 999 | The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing |
| 1000 | the BL32 image. It needs access to the information passed by BL2 to BL31 to do |
| 1001 | so. This is provided by: |
| 1002 | |
| 1003 | .. code:: c |
| 1004 | |
| 1005 | entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t); |
| 1006 | |
| 1007 | which returns a reference to the ``entry_point_info`` structure corresponding to |
| 1008 | the image which will be run in the specified security state. The SPD uses this |
| 1009 | API to get entry point information for the SECURE image, BL32. |
| 1010 | |
| 1011 | In the absence of a BL32 image, BL31 passes control to the normal world |
| 1012 | bootloader image (BL33). When the BL32 image is present, it is typical |
| 1013 | that the SPD wants control to be passed to BL32 first and then later to BL33. |
| 1014 | |
| 1015 | To do this the SPD has to register a BL32 initialization function during |
| 1016 | initialization of the SPD service. The BL32 initialization function has this |
| 1017 | prototype: |
| 1018 | |
| 1019 | .. code:: c |
| 1020 | |
| 1021 | int32_t init(void); |
| 1022 | |
| 1023 | and is registered using the ``bl31_register_bl32_init()`` function. |
| 1024 | |
| 1025 | Trusted Firmware supports two approaches for the SPD to pass control to BL32 |
| 1026 | before returning through EL3 and running the non-trusted firmware (BL33): |
| 1027 | |
| 1028 | #. In the BL32 setup function, use ``bl31_set_next_image_type()`` to |
| 1029 | request that the exit from ``bl31_main()`` is to the BL32 entrypoint in |
| 1030 | Secure-EL1. BL31 will exit to BL32 using the asynchronous method by |
| 1031 | calling ``bl31_prepare_next_image_entry()`` and ``el3_exit()``. |
| 1032 | |
| 1033 | When the BL32 has completed initialization at Secure-EL1, it returns to |
| 1034 | BL31 by issuing an SMC, using a Function ID allocated to the SPD. On |
| 1035 | receipt of this SMC, the SPD service handler should switch the CPU context |
| 1036 | from trusted to normal world and use the ``bl31_set_next_image_type()`` and |
| 1037 | ``bl31_prepare_next_image_entry()`` functions to set up the initial return to |
| 1038 | the normal world firmware BL33. On return from the handler the framework |
| 1039 | will exit to EL2 and run BL33. |
| 1040 | |
| 1041 | #. The BL32 setup function registers an initialization function using |
| 1042 | ``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to |
| 1043 | invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32 |
| 1044 | entrypoint. |
| 1045 | NOTE: The Test SPD service included with the Trusted Firmware provides one |
| 1046 | implementation of such a mechanism. |
| 1047 | |
| 1048 | On completion BL32 returns control to BL31 via a SMC, and on receipt the |
| 1049 | SPD service handler invokes the synchronous call return mechanism to return |
| 1050 | to the BL32 initialization function. On return from this function, |
| 1051 | ``bl31_main()`` will set up the return to the normal world firmware BL33 and |
| 1052 | continue the boot process in the normal world. |
| 1053 | |
Jeenu Viswambharan | 579b4ad | 2017-08-24 15:43:44 +0100 | [diff] [blame] | 1054 | Crash Reporting in BL31 |
| 1055 | ----------------------- |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 1056 | |
| 1057 | BL31 implements a scheme for reporting the processor state when an unhandled |
| 1058 | exception is encountered. The reporting mechanism attempts to preserve all the |
| 1059 | register contents and report it via a dedicated UART (PL011 console). BL31 |
| 1060 | reports the general purpose, EL3, Secure EL1 and some EL2 state registers. |
| 1061 | |
| 1062 | A dedicated per-CPU crash stack is maintained by BL31 and this is retrieved via |
| 1063 | the per-CPU pointer cache. The implementation attempts to minimise the memory |
| 1064 | required for this feature. The file ``crash_reporting.S`` contains the |
| 1065 | implementation for crash reporting. |
| 1066 | |
| 1067 | The sample crash output is shown below. |
| 1068 | |
| 1069 | :: |
| 1070 | |
| 1071 | x0 :0x000000004F00007C |
| 1072 | x1 :0x0000000007FFFFFF |
| 1073 | x2 :0x0000000004014D50 |
| 1074 | x3 :0x0000000000000000 |
| 1075 | x4 :0x0000000088007998 |
| 1076 | x5 :0x00000000001343AC |
| 1077 | x6 :0x0000000000000016 |
| 1078 | x7 :0x00000000000B8A38 |
| 1079 | x8 :0x00000000001343AC |
| 1080 | x9 :0x00000000000101A8 |
| 1081 | x10 :0x0000000000000002 |
| 1082 | x11 :0x000000000000011C |
| 1083 | x12 :0x00000000FEFDC644 |
| 1084 | x13 :0x00000000FED93FFC |
| 1085 | x14 :0x0000000000247950 |
| 1086 | x15 :0x00000000000007A2 |
| 1087 | x16 :0x00000000000007A4 |
| 1088 | x17 :0x0000000000247950 |
| 1089 | x18 :0x0000000000000000 |
| 1090 | x19 :0x00000000FFFFFFFF |
| 1091 | x20 :0x0000000004014D50 |
| 1092 | x21 :0x000000000400A38C |
| 1093 | x22 :0x0000000000247950 |
| 1094 | x23 :0x0000000000000010 |
| 1095 | x24 :0x0000000000000024 |
| 1096 | x25 :0x00000000FEFDC868 |
| 1097 | x26 :0x00000000FEFDC86A |
| 1098 | x27 :0x00000000019EDEDC |
| 1099 | x28 :0x000000000A7CFDAA |
| 1100 | x29 :0x0000000004010780 |
| 1101 | x30 :0x000000000400F004 |
| 1102 | scr_el3 :0x0000000000000D3D |
| 1103 | sctlr_el3 :0x0000000000C8181F |
| 1104 | cptr_el3 :0x0000000000000000 |
| 1105 | tcr_el3 :0x0000000080803520 |
| 1106 | daif :0x00000000000003C0 |
| 1107 | mair_el3 :0x00000000000004FF |
| 1108 | spsr_el3 :0x00000000800003CC |
| 1109 | elr_el3 :0x000000000400C0CC |
| 1110 | ttbr0_el3 :0x00000000040172A0 |
| 1111 | esr_el3 :0x0000000096000210 |
| 1112 | sp_el3 :0x0000000004014D50 |
| 1113 | far_el3 :0x000000004F00007C |
| 1114 | spsr_el1 :0x0000000000000000 |
| 1115 | elr_el1 :0x0000000000000000 |
| 1116 | spsr_abt :0x0000000000000000 |
| 1117 | spsr_und :0x0000000000000000 |
| 1118 | spsr_irq :0x0000000000000000 |
| 1119 | spsr_fiq :0x0000000000000000 |
| 1120 | sctlr_el1 :0x0000000030C81807 |
| 1121 | actlr_el1 :0x0000000000000000 |
| 1122 | cpacr_el1 :0x0000000000300000 |
| 1123 | csselr_el1 :0x0000000000000002 |
| 1124 | sp_el1 :0x0000000004028800 |
| 1125 | esr_el1 :0x0000000000000000 |
| 1126 | ttbr0_el1 :0x000000000402C200 |
| 1127 | ttbr1_el1 :0x0000000000000000 |
| 1128 | mair_el1 :0x00000000000004FF |
| 1129 | amair_el1 :0x0000000000000000 |
| 1130 | tcr_el1 :0x0000000000003520 |
| 1131 | tpidr_el1 :0x0000000000000000 |
| 1132 | tpidr_el0 :0x0000000000000000 |
| 1133 | tpidrro_el0 :0x0000000000000000 |
| 1134 | dacr32_el2 :0x0000000000000000 |
| 1135 | ifsr32_el2 :0x0000000000000000 |
| 1136 | par_el1 :0x0000000000000000 |
| 1137 | far_el1 :0x0000000000000000 |
| 1138 | afsr0_el1 :0x0000000000000000 |
| 1139 | afsr1_el1 :0x0000000000000000 |
| 1140 | contextidr_el1 :0x0000000000000000 |
| 1141 | vbar_el1 :0x0000000004027000 |
| 1142 | cntp_ctl_el0 :0x0000000000000000 |
| 1143 | cntp_cval_el0 :0x0000000000000000 |
| 1144 | cntv_ctl_el0 :0x0000000000000000 |
| 1145 | cntv_cval_el0 :0x0000000000000000 |
| 1146 | cntkctl_el1 :0x0000000000000000 |
| 1147 | fpexc32_el2 :0x0000000004000700 |
| 1148 | sp_el0 :0x0000000004010780 |
| 1149 | |
| 1150 | Guidelines for Reset Handlers |
| 1151 | ----------------------------- |
| 1152 | |
| 1153 | Trusted Firmware implements a framework that allows CPU and platform ports to |
| 1154 | perform actions very early after a CPU is released from reset in both the cold |
| 1155 | and warm boot paths. This is done by calling the ``reset_handler()`` function in |
| 1156 | both the BL1 and BL31 images. It in turn calls the platform and CPU specific |
| 1157 | reset handling functions. |
| 1158 | |
| 1159 | Details for implementing a CPU specific reset handler can be found in |
| 1160 | Section 8. Details for implementing a platform specific reset handler can be |
| 1161 | found in the `Porting Guide`_ (see the ``plat_reset_handler()`` function). |
| 1162 | |
| 1163 | When adding functionality to a reset handler, keep in mind that if a different |
| 1164 | reset handling behavior is required between the first and the subsequent |
| 1165 | invocations of the reset handling code, this should be detected at runtime. |
| 1166 | In other words, the reset handler should be able to detect whether an action has |
| 1167 | already been performed and act as appropriate. Possible courses of actions are, |
| 1168 | e.g. skip the action the second time, or undo/redo it. |
| 1169 | |
Jeenu Viswambharan | c639e8e | 2017-09-22 08:32:09 +0100 | [diff] [blame] | 1170 | Configuring secure interrupts |
| 1171 | ----------------------------- |
| 1172 | |
| 1173 | The GIC driver is responsible for performing initial configuration of secure |
| 1174 | interrupts on the platform. To this end, the platform is expected to provide the |
| 1175 | GIC driver (either GICv2 or GICv3, as selected by the platform) with the |
| 1176 | interrupt configuration during the driver initialisation. |
| 1177 | |
| 1178 | There are two ways to specify secure interrupt configuration: |
| 1179 | |
| 1180 | #. Array of secure interrupt properties: In this scheme, in both GICv2 and GICv3 |
| 1181 | driver data structures, the ``interrupt_props`` member points to an array of |
| 1182 | interrupt properties. Each element of the array specifies the interrupt |
| 1183 | number and its configuration, viz. priority, group, configuration. Each |
| 1184 | element of the array shall be populated by the macro ``INTR_PROP_DESC()``. |
| 1185 | The macro takes the following arguments: |
| 1186 | |
| 1187 | - 10-bit interrupt number, |
| 1188 | |
| 1189 | - 8-bit interrupt priority, |
| 1190 | |
| 1191 | - Interrupt type (one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``, |
| 1192 | ``INTR_TYPE_NS``), |
| 1193 | |
| 1194 | - Interrupt configuration (either ``GIC_INTR_CFG_LEVEL`` or |
| 1195 | ``GIC_INTR_CFG_EDGE``). |
| 1196 | |
| 1197 | #. Array of secure interrupts: In this scheme, the GIC driver is provided an |
| 1198 | array of secure interrupt numbers. The GIC driver, at the time of |
| 1199 | initialisation, iterates through the array and assigns each interrupt |
| 1200 | the appropriate group. |
| 1201 | |
| 1202 | - For the GICv2 driver, in ``gicv2_driver_data`` structure, the |
| 1203 | ``g0_interrupt_array`` member of the should point to the array of |
| 1204 | interrupts to be assigned to *Group 0*, and the ``g0_interrupt_num`` |
| 1205 | member of the should be set to the number of interrupts in the array. |
| 1206 | |
| 1207 | - For the GICv3 driver, in ``gicv3_driver_data`` structure: |
| 1208 | |
| 1209 | - The ``g0_interrupt_array`` member of the should point to the array of |
| 1210 | interrupts to be assigned to *Group 0*, and the ``g0_interrupt_num`` |
| 1211 | member of the should be set to the number of interrupts in the array. |
| 1212 | |
| 1213 | - The ``g1s_interrupt_array`` member of the should point to the array of |
| 1214 | interrupts to be assigned to *Group 1 Secure*, and the |
| 1215 | ``g1s_interrupt_num`` member of the should be set to the number of |
| 1216 | interrupts in the array. |
| 1217 | |
| 1218 | **Note that this scheme is deprecated.** |
| 1219 | |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 1220 | CPU specific operations framework |
| 1221 | --------------------------------- |
| 1222 | |
| 1223 | Certain aspects of the ARMv8 architecture are implementation defined, |
| 1224 | that is, certain behaviours are not architecturally defined, but must be defined |
| 1225 | and documented by individual processor implementations. The ARM Trusted |
| 1226 | Firmware implements a framework which categorises the common implementation |
| 1227 | defined behaviours and allows a processor to export its implementation of that |
| 1228 | behaviour. The categories are: |
| 1229 | |
| 1230 | #. Processor specific reset sequence. |
| 1231 | |
| 1232 | #. Processor specific power down sequences. |
| 1233 | |
| 1234 | #. Processor specific register dumping as a part of crash reporting. |
| 1235 | |
| 1236 | #. Errata status reporting. |
| 1237 | |
| 1238 | Each of the above categories fulfils a different requirement. |
| 1239 | |
| 1240 | #. allows any processor specific initialization before the caches and MMU |
| 1241 | are turned on, like implementation of errata workarounds, entry into |
| 1242 | the intra-cluster coherency domain etc. |
| 1243 | |
| 1244 | #. allows each processor to implement the power down sequence mandated in |
| 1245 | its Technical Reference Manual (TRM). |
| 1246 | |
| 1247 | #. allows a processor to provide additional information to the developer |
| 1248 | in the event of a crash, for example Cortex-A53 has registers which |
| 1249 | can expose the data cache contents. |
| 1250 | |
| 1251 | #. allows a processor to define a function that inspects and reports the status |
| 1252 | of all errata workarounds on that processor. |
| 1253 | |
| 1254 | Please note that only 2. is mandated by the TRM. |
| 1255 | |
| 1256 | The CPU specific operations framework scales to accommodate a large number of |
| 1257 | different CPUs during power down and reset handling. The platform can specify |
| 1258 | any CPU optimization it wants to enable for each CPU. It can also specify |
| 1259 | the CPU errata workarounds to be applied for each CPU type during reset |
| 1260 | handling by defining CPU errata compile time macros. Details on these macros |
| 1261 | can be found in the `cpu-specific-build-macros.rst`_ file. |
| 1262 | |
| 1263 | The CPU specific operations framework depends on the ``cpu_ops`` structure which |
| 1264 | needs to be exported for each type of CPU in the platform. It is defined in |
| 1265 | ``include/lib/cpus/aarch64/cpu_macros.S`` and has the following fields : ``midr``, |
| 1266 | ``reset_func()``, ``cpu_pwr_down_ops`` (array of power down functions) and |
| 1267 | ``cpu_reg_dump()``. |
| 1268 | |
| 1269 | The CPU specific files in ``lib/cpus`` export a ``cpu_ops`` data structure with |
| 1270 | suitable handlers for that CPU. For example, ``lib/cpus/aarch64/cortex_a53.S`` |
| 1271 | exports the ``cpu_ops`` for Cortex-A53 CPU. According to the platform |
| 1272 | configuration, these CPU specific files must be included in the build by |
| 1273 | the platform makefile. The generic CPU specific operations framework code exists |
| 1274 | in ``lib/cpus/aarch64/cpu_helpers.S``. |
| 1275 | |
| 1276 | CPU specific Reset Handling |
| 1277 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1278 | |
| 1279 | After a reset, the state of the CPU when it calls generic reset handler is: |
| 1280 | MMU turned off, both instruction and data caches turned off and not part |
| 1281 | of any coherency domain. |
| 1282 | |
| 1283 | The BL entrypoint code first invokes the ``plat_reset_handler()`` to allow |
| 1284 | the platform to perform any system initialization required and any system |
| 1285 | errata workarounds that needs to be applied. The ``get_cpu_ops_ptr()`` reads |
| 1286 | the current CPU midr, finds the matching ``cpu_ops`` entry in the ``cpu_ops`` |
| 1287 | array and returns it. Note that only the part number and implementer fields |
| 1288 | in midr are used to find the matching ``cpu_ops`` entry. The ``reset_func()`` in |
| 1289 | the returned ``cpu_ops`` is then invoked which executes the required reset |
| 1290 | handling for that CPU and also any errata workarounds enabled by the platform. |
| 1291 | This function must preserve the values of general purpose registers x20 to x29. |
| 1292 | |
| 1293 | Refer to Section "Guidelines for Reset Handlers" for general guidelines |
| 1294 | regarding placement of code in a reset handler. |
| 1295 | |
| 1296 | CPU specific power down sequence |
| 1297 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1298 | |
| 1299 | During the BL31 initialization sequence, the pointer to the matching ``cpu_ops`` |
| 1300 | entry is stored in per-CPU data by ``init_cpu_ops()`` so that it can be quickly |
| 1301 | retrieved during power down sequences. |
| 1302 | |
| 1303 | Various CPU drivers register handlers to perform power down at certain power |
| 1304 | levels for that specific CPU. The PSCI service, upon receiving a power down |
| 1305 | request, determines the highest power level at which to execute power down |
| 1306 | sequence for a particular CPU. It uses the ``prepare_cpu_pwr_dwn()`` function to |
| 1307 | pick the right power down handler for the requested level. The function |
| 1308 | retrieves ``cpu_ops`` pointer member of per-CPU data, and from that, further |
| 1309 | retrieves ``cpu_pwr_down_ops`` array, and indexes into the required level. If the |
| 1310 | requested power level is higher than what a CPU driver supports, the handler |
| 1311 | registered for highest level is invoked. |
| 1312 | |
| 1313 | At runtime the platform hooks for power down are invoked by the PSCI service to |
| 1314 | perform platform specific operations during a power down sequence, for example |
| 1315 | turning off CCI coherency during a cluster power down. |
| 1316 | |
| 1317 | CPU specific register reporting during crash |
| 1318 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1319 | |
| 1320 | If the crash reporting is enabled in BL31, when a crash occurs, the crash |
| 1321 | reporting framework calls ``do_cpu_reg_dump`` which retrieves the matching |
| 1322 | ``cpu_ops`` using ``get_cpu_ops_ptr()`` function. The ``cpu_reg_dump()`` in |
| 1323 | ``cpu_ops`` is invoked, which then returns the CPU specific register values to |
| 1324 | be reported and a pointer to the ASCII list of register names in a format |
| 1325 | expected by the crash reporting framework. |
| 1326 | |
| 1327 | CPU errata status reporting |
| 1328 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1329 | |
| 1330 | Errata workarounds for CPUs supported in ARM Trusted Firmware are applied during |
| 1331 | both cold and warm boots, shortly after reset. Individual Errata workarounds are |
| 1332 | enabled as build options. Some errata workarounds have potential run-time |
| 1333 | implications; therefore some are enabled by default, others not. Platform ports |
| 1334 | shall override build options to enable or disable errata as appropriate. The CPU |
| 1335 | drivers take care of applying errata workarounds that are enabled and applicable |
| 1336 | to a given CPU. Refer to the section titled *CPU Errata Workarounds* in `CPUBM`_ |
| 1337 | for more information. |
| 1338 | |
| 1339 | Functions in CPU drivers that apply errata workaround must follow the |
| 1340 | conventions listed below. |
| 1341 | |
| 1342 | The errata workaround must be authored as two separate functions: |
| 1343 | |
| 1344 | - One that checks for errata. This function must determine whether that errata |
| 1345 | applies to the current CPU. Typically this involves matching the current |
| 1346 | CPUs revision and variant against a value that's known to be affected by the |
| 1347 | errata. If the function determines that the errata applies to this CPU, it |
| 1348 | must return ``ERRATA_APPLIES``; otherwise, it must return |
| 1349 | ``ERRATA_NOT_APPLIES``. The utility functions ``cpu_get_rev_var`` and |
| 1350 | ``cpu_rev_var_ls`` functions may come in handy for this purpose. |
| 1351 | |
| 1352 | For an errata identified as ``E``, the check function must be named |
| 1353 | ``check_errata_E``. |
| 1354 | |
| 1355 | This function will be invoked at different times, both from assembly and from |
| 1356 | C run time. Therefore it must follow AAPCS, and must not use stack. |
| 1357 | |
| 1358 | - Another one that applies the errata workaround. This function would call the |
| 1359 | check function described above, and applies errata workaround if required. |
| 1360 | |
| 1361 | CPU drivers that apply errata workaround can optionally implement an assembly |
| 1362 | function that report the status of errata workarounds pertaining to that CPU. |
| 1363 | For a driver that registers the CPU, for example, ``cpux`` via. ``declare_cpu_ops`` |
| 1364 | macro, the errata reporting function, if it exists, must be named |
| 1365 | ``cpux_errata_report``. This function will always be called with MMU enabled; it |
| 1366 | must follow AAPCS and may use stack. |
| 1367 | |
| 1368 | In a debug build of ARM Trusted Firmware, on a CPU that comes out of reset, both |
| 1369 | BL1 and the run time firmware (BL31 in AArch64, and BL32 in AArch32) will invoke |
| 1370 | errata status reporting function, if one exists, for that type of CPU. |
| 1371 | |
| 1372 | To report the status of each errata workaround, the function shall use the |
| 1373 | assembler macro ``report_errata``, passing it: |
| 1374 | |
| 1375 | - The build option that enables the errata; |
| 1376 | |
| 1377 | - The name of the CPU: this must be the same identifier that CPU driver |
| 1378 | registered itself with, using ``declare_cpu_ops``; |
| 1379 | |
| 1380 | - And the errata identifier: the identifier must match what's used in the |
| 1381 | errata's check function described above. |
| 1382 | |
| 1383 | The errata status reporting function will be called once per CPU type/errata |
| 1384 | combination during the software's active life time. |
| 1385 | |
| 1386 | It's expected that whenever an errata workaround is submitted to ARM Trusted |
| 1387 | Firmware, the errata reporting function is appropriately extended to report its |
| 1388 | status as well. |
| 1389 | |
| 1390 | Reporting the status of errata workaround is for informational purpose only; it |
| 1391 | has no functional significance. |
| 1392 | |
| 1393 | Memory layout of BL images |
| 1394 | -------------------------- |
| 1395 | |
| 1396 | Each bootloader image can be divided in 2 parts: |
| 1397 | |
| 1398 | - the static contents of the image. These are data actually stored in the |
| 1399 | binary on the disk. In the ELF terminology, they are called ``PROGBITS`` |
| 1400 | sections; |
| 1401 | |
| 1402 | - the run-time contents of the image. These are data that don't occupy any |
| 1403 | space in the binary on the disk. The ELF binary just contains some |
| 1404 | metadata indicating where these data will be stored at run-time and the |
| 1405 | corresponding sections need to be allocated and initialized at run-time. |
| 1406 | In the ELF terminology, they are called ``NOBITS`` sections. |
| 1407 | |
| 1408 | All PROGBITS sections are grouped together at the beginning of the image, |
| 1409 | followed by all NOBITS sections. This is true for all Trusted Firmware images |
| 1410 | and it is governed by the linker scripts. This ensures that the raw binary |
| 1411 | images are as small as possible. If a NOBITS section was inserted in between |
| 1412 | PROGBITS sections then the resulting binary file would contain zero bytes in |
| 1413 | place of this NOBITS section, making the image unnecessarily bigger. Smaller |
| 1414 | images allow faster loading from the FIP to the main memory. |
| 1415 | |
| 1416 | Linker scripts and symbols |
| 1417 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1418 | |
| 1419 | Each bootloader stage image layout is described by its own linker script. The |
| 1420 | linker scripts export some symbols into the program symbol table. Their values |
| 1421 | correspond to particular addresses. The trusted firmware code can refer to these |
| 1422 | symbols to figure out the image memory layout. |
| 1423 | |
| 1424 | Linker symbols follow the following naming convention in the trusted firmware. |
| 1425 | |
| 1426 | - ``__<SECTION>_START__`` |
| 1427 | |
| 1428 | Start address of a given section named ``<SECTION>``. |
| 1429 | |
| 1430 | - ``__<SECTION>_END__`` |
| 1431 | |
| 1432 | End address of a given section named ``<SECTION>``. If there is an alignment |
| 1433 | constraint on the section's end address then ``__<SECTION>_END__`` corresponds |
| 1434 | to the end address of the section's actual contents, rounded up to the right |
| 1435 | boundary. Refer to the value of ``__<SECTION>_UNALIGNED_END__`` to know the |
| 1436 | actual end address of the section's contents. |
| 1437 | |
| 1438 | - ``__<SECTION>_UNALIGNED_END__`` |
| 1439 | |
| 1440 | End address of a given section named ``<SECTION>`` without any padding or |
| 1441 | rounding up due to some alignment constraint. |
| 1442 | |
| 1443 | - ``__<SECTION>_SIZE__`` |
| 1444 | |
| 1445 | Size (in bytes) of a given section named ``<SECTION>``. If there is an |
| 1446 | alignment constraint on the section's end address then ``__<SECTION>_SIZE__`` |
| 1447 | corresponds to the size of the section's actual contents, rounded up to the |
| 1448 | right boundary. In other words, ``__<SECTION>_SIZE__ = __<SECTION>_END__ - _<SECTION>_START__``. Refer to the value of ``__<SECTION>_UNALIGNED_SIZE__`` |
| 1449 | to know the actual size of the section's contents. |
| 1450 | |
| 1451 | - ``__<SECTION>_UNALIGNED_SIZE__`` |
| 1452 | |
| 1453 | Size (in bytes) of a given section named ``<SECTION>`` without any padding or |
| 1454 | rounding up due to some alignment constraint. In other words, |
| 1455 | ``__<SECTION>_UNALIGNED_SIZE__ = __<SECTION>_UNALIGNED_END__ - __<SECTION>_START__``. |
| 1456 | |
| 1457 | Some of the linker symbols are mandatory as the trusted firmware code relies on |
| 1458 | them to be defined. They are listed in the following subsections. Some of them |
| 1459 | must be provided for each bootloader stage and some are specific to a given |
| 1460 | bootloader stage. |
| 1461 | |
| 1462 | The linker scripts define some extra, optional symbols. They are not actually |
| 1463 | used by any code but they help in understanding the bootloader images' memory |
| 1464 | layout as they are easy to spot in the link map files. |
| 1465 | |
| 1466 | Common linker symbols |
| 1467 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1468 | |
| 1469 | All BL images share the following requirements: |
| 1470 | |
| 1471 | - The BSS section must be zero-initialised before executing any C code. |
| 1472 | - The coherent memory section (if enabled) must be zero-initialised as well. |
| 1473 | - The MMU setup code needs to know the extents of the coherent and read-only |
| 1474 | memory regions to set the right memory attributes. When |
| 1475 | ``SEPARATE_CODE_AND_RODATA=1``, it needs to know more specifically how the |
| 1476 | read-only memory region is divided between code and data. |
| 1477 | |
| 1478 | The following linker symbols are defined for this purpose: |
| 1479 | |
| 1480 | - ``__BSS_START__`` |
| 1481 | - ``__BSS_SIZE__`` |
| 1482 | - ``__COHERENT_RAM_START__`` Must be aligned on a page-size boundary. |
| 1483 | - ``__COHERENT_RAM_END__`` Must be aligned on a page-size boundary. |
| 1484 | - ``__COHERENT_RAM_UNALIGNED_SIZE__`` |
| 1485 | - ``__RO_START__`` |
| 1486 | - ``__RO_END__`` |
| 1487 | - ``__TEXT_START__`` |
| 1488 | - ``__TEXT_END__`` |
| 1489 | - ``__RODATA_START__`` |
| 1490 | - ``__RODATA_END__`` |
| 1491 | |
| 1492 | BL1's linker symbols |
| 1493 | ^^^^^^^^^^^^^^^^^^^^ |
| 1494 | |
| 1495 | BL1 being the ROM image, it has additional requirements. BL1 resides in ROM and |
| 1496 | it is entirely executed in place but it needs some read-write memory for its |
| 1497 | mutable data. Its ``.data`` section (i.e. its allocated read-write data) must be |
| 1498 | relocated from ROM to RAM before executing any C code. |
| 1499 | |
| 1500 | The following additional linker symbols are defined for BL1: |
| 1501 | |
| 1502 | - ``__BL1_ROM_END__`` End address of BL1's ROM contents, covering its code |
| 1503 | and ``.data`` section in ROM. |
| 1504 | - ``__DATA_ROM_START__`` Start address of the ``.data`` section in ROM. Must be |
| 1505 | aligned on a 16-byte boundary. |
| 1506 | - ``__DATA_RAM_START__`` Address in RAM where the ``.data`` section should be |
| 1507 | copied over. Must be aligned on a 16-byte boundary. |
| 1508 | - ``__DATA_SIZE__`` Size of the ``.data`` section (in ROM or RAM). |
| 1509 | - ``__BL1_RAM_START__`` Start address of BL1 read-write data. |
| 1510 | - ``__BL1_RAM_END__`` End address of BL1 read-write data. |
| 1511 | |
| 1512 | How to choose the right base addresses for each bootloader stage image |
| 1513 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1514 | |
| 1515 | There is currently no support for dynamic image loading in the Trusted Firmware. |
| 1516 | This means that all bootloader images need to be linked against their ultimate |
| 1517 | runtime locations and the base addresses of each image must be chosen carefully |
| 1518 | such that images don't overlap each other in an undesired way. As the code |
| 1519 | grows, the base addresses might need adjustments to cope with the new memory |
| 1520 | layout. |
| 1521 | |
| 1522 | The memory layout is completely specific to the platform and so there is no |
| 1523 | general recipe for choosing the right base addresses for each bootloader image. |
| 1524 | However, there are tools to aid in understanding the memory layout. These are |
| 1525 | the link map files: ``build/<platform>/<build-type>/bl<x>/bl<x>.map``, with ``<x>`` |
| 1526 | being the stage bootloader. They provide a detailed view of the memory usage of |
| 1527 | each image. Among other useful information, they provide the end address of |
| 1528 | each image. |
| 1529 | |
| 1530 | - ``bl1.map`` link map file provides ``__BL1_RAM_END__`` address. |
| 1531 | - ``bl2.map`` link map file provides ``__BL2_END__`` address. |
| 1532 | - ``bl31.map`` link map file provides ``__BL31_END__`` address. |
| 1533 | - ``bl32.map`` link map file provides ``__BL32_END__`` address. |
| 1534 | |
| 1535 | For each bootloader image, the platform code must provide its start address |
| 1536 | as well as a limit address that it must not overstep. The latter is used in the |
| 1537 | linker scripts to check that the image doesn't grow past that address. If that |
| 1538 | happens, the linker will issue a message similar to the following: |
| 1539 | |
| 1540 | :: |
| 1541 | |
| 1542 | aarch64-none-elf-ld: BLx has exceeded its limit. |
| 1543 | |
| 1544 | Additionally, if the platform memory layout implies some image overlaying like |
| 1545 | on FVP, BL31 and TSP need to know the limit address that their PROGBITS |
| 1546 | sections must not overstep. The platform code must provide those. |
| 1547 | |
| 1548 | When LOAD\_IMAGE\_V2 is disabled, Trusted Firmware provides a mechanism to |
| 1549 | verify at boot time that the memory to load a new image is free to prevent |
| 1550 | overwriting a previously loaded image. For this mechanism to work, the platform |
| 1551 | must specify the memory available in the system as regions, where each region |
| 1552 | consists of base address, total size and the free area within it (as defined |
| 1553 | in the ``meminfo_t`` structure). Trusted Firmware retrieves these memory regions |
| 1554 | by calling the corresponding platform API: |
| 1555 | |
| 1556 | - ``meminfo_t *bl1_plat_sec_mem_layout(void)`` |
| 1557 | - ``meminfo_t *bl2_plat_sec_mem_layout(void)`` |
| 1558 | - ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)`` |
| 1559 | - ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)`` |
| 1560 | - ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)`` |
| 1561 | |
| 1562 | For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will |
| 1563 | return the region defined by the platform where BL1 intends to load BL2. The |
| 1564 | ``load_image()`` function will check that the memory where BL2 will be loaded is |
| 1565 | within the specified region and marked as free. |
| 1566 | |
| 1567 | The actual number of regions and their base addresses and sizes is platform |
| 1568 | specific. The platform may return the same region or define a different one for |
| 1569 | each API. However, the overlap verification mechanism applies only to a single |
| 1570 | region. Hence, it is the platform responsibility to guarantee that different |
| 1571 | regions do not overlap, or that if they do, the overlapping images are not |
| 1572 | accessed at the same time. This could be used, for example, to load temporary |
| 1573 | images (e.g. certificates) or firmware images prior to being transfered to its |
| 1574 | corresponding processor (e.g. the SCP BL2 image). |
| 1575 | |
| 1576 | To reduce fragmentation and simplify the tracking of free memory, all the free |
| 1577 | memory within a region is always located in one single buffer defined by its |
| 1578 | base address and size. Trusted Firmware implements a top/bottom load approach: |
| 1579 | after a new image is loaded, it checks how much memory remains free above and |
| 1580 | below the image. The smallest area is marked as unavailable, while the larger |
| 1581 | area becomes the new free memory buffer. Platforms should take this behaviour |
| 1582 | into account when defining the base address for each of the images. For example, |
| 1583 | if an image is loaded near the middle of the region, small changes in image size |
| 1584 | could cause a flip between a top load and a bottom load, which may result in an |
| 1585 | unexpected memory layout. |
| 1586 | |
| 1587 | The following diagram is an example of an image loaded in the bottom part of |
| 1588 | the memory region. The region is initially free (nothing has been loaded yet): |
| 1589 | |
| 1590 | :: |
| 1591 | |
| 1592 | Memory region |
| 1593 | +----------+ |
| 1594 | | | |
| 1595 | | | <<<<<<<<<<<<< Free |
| 1596 | | | |
| 1597 | |----------| +------------+ |
| 1598 | | image | <<<<<<<<<<<<< | image | |
| 1599 | |----------| +------------+ |
| 1600 | | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable |
| 1601 | +----------+ |
| 1602 | |
| 1603 | And the following diagram is an example of an image loaded in the top part: |
| 1604 | |
| 1605 | :: |
| 1606 | |
| 1607 | Memory region |
| 1608 | +----------+ |
| 1609 | | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable |
| 1610 | |----------| +------------+ |
| 1611 | | image | <<<<<<<<<<<<< | image | |
| 1612 | |----------| +------------+ |
| 1613 | | | |
| 1614 | | | <<<<<<<<<<<<< Free |
| 1615 | | | |
| 1616 | +----------+ |
| 1617 | |
| 1618 | When LOAD\_IMAGE\_V2 is enabled, Trusted Firmware does not provide any mechanism |
| 1619 | to verify at boot time that the memory to load a new image is free to prevent |
| 1620 | overwriting a previously loaded image. The platform must specify the memory |
| 1621 | available in the system for all the relevant BL images to be loaded. |
| 1622 | |
| 1623 | For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will |
| 1624 | return the region defined by the platform where BL1 intends to load BL2. The |
| 1625 | ``load_image()`` function performs bounds check for the image size based on the |
| 1626 | base and maximum image size provided by the platforms. Platforms must take |
| 1627 | this behaviour into account when defining the base/size for each of the images. |
| 1628 | |
| 1629 | Memory layout on ARM development platforms |
| 1630 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1631 | |
| 1632 | The following list describes the memory layout on the ARM development platforms: |
| 1633 | |
| 1634 | - A 4KB page of shared memory is used for communication between Trusted |
| 1635 | Firmware and the platform's power controller. This is located at the base of |
| 1636 | Trusted SRAM. The amount of Trusted SRAM available to load the bootloader |
| 1637 | images is reduced by the size of the shared memory. |
| 1638 | |
| 1639 | The shared memory is used to store the CPUs' entrypoint mailbox. On Juno, |
| 1640 | this is also used for the MHU payload when passing messages to and from the |
| 1641 | SCP. |
| 1642 | |
| 1643 | - On FVP, BL1 is originally sitting in the Trusted ROM at address ``0x0``. On |
| 1644 | Juno, BL1 resides in flash memory at address ``0x0BEC0000``. BL1 read-write |
| 1645 | data are relocated to the top of Trusted SRAM at runtime. |
| 1646 | |
| 1647 | - EL3 Runtime Software, BL31 for AArch64 and BL32 for AArch32 (e.g. SP\_MIN), |
| 1648 | is loaded at the top of the Trusted SRAM, such that its NOBITS sections will |
| 1649 | overwrite BL1 R/W data. This implies that BL1 global variables remain valid |
| 1650 | only until execution reaches the EL3 Runtime Software entry point during a |
| 1651 | cold boot. |
| 1652 | |
| 1653 | - BL2 is loaded below EL3 Runtime Software. |
| 1654 | |
| 1655 | - On Juno, SCP\_BL2 is loaded temporarily into the EL3 Runtime Software memory |
| 1656 | region and transfered to the SCP before being overwritten by EL3 Runtime |
| 1657 | Software. |
| 1658 | |
| 1659 | - BL32 (for AArch64) can be loaded in one of the following locations: |
| 1660 | |
| 1661 | - Trusted SRAM |
| 1662 | - Trusted DRAM (FVP only) |
| 1663 | - Secure region of DRAM (top 16MB of DRAM configured by the TrustZone |
| 1664 | controller) |
| 1665 | |
| 1666 | When BL32 (for AArch64) is loaded into Trusted SRAM, its NOBITS sections |
| 1667 | are allowed to overlay BL2. This memory layout is designed to give the |
| 1668 | BL32 image as much memory as possible when it is loaded into Trusted SRAM. |
| 1669 | |
| 1670 | When LOAD\_IMAGE\_V2 is disabled the memory regions for the overlap detection |
| 1671 | mechanism at boot time are defined as follows (shown per API): |
| 1672 | |
| 1673 | - ``meminfo_t *bl1_plat_sec_mem_layout(void)`` |
| 1674 | |
| 1675 | This region corresponds to the whole Trusted SRAM except for the shared |
| 1676 | memory at the base. This region is initially free. At boot time, BL1 will |
| 1677 | mark the BL1(rw) section within this region as occupied. The BL1(rw) section |
| 1678 | is placed at the top of Trusted SRAM. |
| 1679 | |
| 1680 | - ``meminfo_t *bl2_plat_sec_mem_layout(void)`` |
| 1681 | |
| 1682 | This region corresponds to the whole Trusted SRAM as defined by |
| 1683 | ``bl1_plat_sec_mem_layout()``, but with the BL1(rw) section marked as |
| 1684 | occupied. This memory region is used to check that BL2 and BL31 do not |
| 1685 | overlap with each other. BL2\_BASE and BL1\_RW\_BASE are carefully chosen so |
| 1686 | that the memory for BL31 is top loaded above BL2. |
| 1687 | |
| 1688 | - ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)`` |
| 1689 | |
| 1690 | This region is an exact copy of the region defined by |
| 1691 | ``bl2_plat_sec_mem_layout()``. Being a disconnected copy means that all the |
| 1692 | changes made to this region by the Trusted Firmware will not be propagated. |
| 1693 | This approach is valid because the SCP BL2 image is loaded temporarily |
| 1694 | while it is being transferred to the SCP, so this memory is reused |
| 1695 | afterwards. |
| 1696 | |
| 1697 | - ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)`` |
| 1698 | |
| 1699 | This region depends on the location of the BL32 image. Currently, ARM |
| 1700 | platforms support three different locations (detailed below): Trusted SRAM, |
| 1701 | Trusted DRAM and the TZC-Secured DRAM. |
| 1702 | |
| 1703 | - ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)`` |
| 1704 | |
| 1705 | This region corresponds to the Non-Secure DDR-DRAM, excluding the |
| 1706 | TZC-Secured area. |
| 1707 | |
| 1708 | The location of the BL32 image will result in different memory maps. This is |
| 1709 | illustrated for both FVP and Juno in the following diagrams, using the TSP as |
| 1710 | an example. |
| 1711 | |
| 1712 | Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory |
| 1713 | layout of the other images in Trusted SRAM. |
| 1714 | |
| 1715 | **FVP with TSP in Trusted SRAM (default option):** |
| 1716 | (These diagrams only cover the AArch64 case) |
| 1717 | |
| 1718 | :: |
| 1719 | |
| 1720 | Trusted SRAM |
| 1721 | 0x04040000 +----------+ loaded by BL2 ------------------ |
| 1722 | | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | |
| 1723 | |----------| <<<<<<<<<<<<< |----------------| |
| 1724 | | | <<<<<<<<<<<<< | BL31 PROGBITS | |
| 1725 | |----------| ------------------ |
| 1726 | | BL2 | <<<<<<<<<<<<< | BL32 NOBITS | |
| 1727 | |----------| <<<<<<<<<<<<< |----------------| |
| 1728 | | | <<<<<<<<<<<<< | BL32 PROGBITS | |
| 1729 | 0x04001000 +----------+ ------------------ |
| 1730 | | Shared | |
| 1731 | 0x04000000 +----------+ |
| 1732 | |
| 1733 | Trusted ROM |
| 1734 | 0x04000000 +----------+ |
| 1735 | | BL1 (ro) | |
| 1736 | 0x00000000 +----------+ |
| 1737 | |
| 1738 | **FVP with TSP in Trusted DRAM:** |
| 1739 | |
| 1740 | :: |
| 1741 | |
| 1742 | Trusted DRAM |
| 1743 | 0x08000000 +----------+ |
| 1744 | | BL32 | |
| 1745 | 0x06000000 +----------+ |
| 1746 | |
| 1747 | Trusted SRAM |
| 1748 | 0x04040000 +----------+ loaded by BL2 ------------------ |
| 1749 | | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | |
| 1750 | |----------| <<<<<<<<<<<<< |----------------| |
| 1751 | | | <<<<<<<<<<<<< | BL31 PROGBITS | |
| 1752 | |----------| ------------------ |
| 1753 | | BL2 | |
| 1754 | |----------| |
| 1755 | | | |
| 1756 | 0x04001000 +----------+ |
| 1757 | | Shared | |
| 1758 | 0x04000000 +----------+ |
| 1759 | |
| 1760 | Trusted ROM |
| 1761 | 0x04000000 +----------+ |
| 1762 | | BL1 (ro) | |
| 1763 | 0x00000000 +----------+ |
| 1764 | |
| 1765 | **FVP with TSP in TZC-Secured DRAM:** |
| 1766 | |
| 1767 | :: |
| 1768 | |
| 1769 | DRAM |
| 1770 | 0xffffffff +----------+ |
| 1771 | | BL32 | (secure) |
| 1772 | 0xff000000 +----------+ |
| 1773 | | | |
| 1774 | : : (non-secure) |
| 1775 | | | |
| 1776 | 0x80000000 +----------+ |
| 1777 | |
| 1778 | Trusted SRAM |
| 1779 | 0x04040000 +----------+ loaded by BL2 ------------------ |
| 1780 | | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | |
| 1781 | |----------| <<<<<<<<<<<<< |----------------| |
| 1782 | | | <<<<<<<<<<<<< | BL31 PROGBITS | |
| 1783 | |----------| ------------------ |
| 1784 | | BL2 | |
| 1785 | |----------| |
| 1786 | | | |
| 1787 | 0x04001000 +----------+ |
| 1788 | | Shared | |
| 1789 | 0x04000000 +----------+ |
| 1790 | |
| 1791 | Trusted ROM |
| 1792 | 0x04000000 +----------+ |
| 1793 | | BL1 (ro) | |
| 1794 | 0x00000000 +----------+ |
| 1795 | |
| 1796 | **Juno with BL32 in Trusted SRAM (default option):** |
| 1797 | |
| 1798 | :: |
| 1799 | |
| 1800 | Flash0 |
| 1801 | 0x0C000000 +----------+ |
| 1802 | : : |
| 1803 | 0x0BED0000 |----------| |
| 1804 | | BL1 (ro) | |
| 1805 | 0x0BEC0000 |----------| |
| 1806 | : : |
| 1807 | 0x08000000 +----------+ BL31 is loaded |
| 1808 | after SCP_BL2 has |
| 1809 | Trusted SRAM been sent to SCP |
| 1810 | 0x04040000 +----------+ loaded by BL2 ------------------ |
| 1811 | | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | |
| 1812 | |----------| <<<<<<<<<<<<< |----------------| |
| 1813 | | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | |
| 1814 | |----------| ------------------ |
| 1815 | | BL2 | <<<<<<<<<<<<< | BL32 NOBITS | |
| 1816 | |----------| <<<<<<<<<<<<< |----------------| |
| 1817 | | | <<<<<<<<<<<<< | BL32 PROGBITS | |
| 1818 | 0x04001000 +----------+ ------------------ |
| 1819 | | MHU | |
| 1820 | 0x04000000 +----------+ |
| 1821 | |
| 1822 | **Juno with BL32 in TZC-secured DRAM:** |
| 1823 | |
| 1824 | :: |
| 1825 | |
| 1826 | DRAM |
| 1827 | 0xFFE00000 +----------+ |
| 1828 | | BL32 | (secure) |
| 1829 | 0xFF000000 |----------| |
| 1830 | | | |
| 1831 | : : (non-secure) |
| 1832 | | | |
| 1833 | 0x80000000 +----------+ |
| 1834 | |
| 1835 | Flash0 |
| 1836 | 0x0C000000 +----------+ |
| 1837 | : : |
| 1838 | 0x0BED0000 |----------| |
| 1839 | | BL1 (ro) | |
| 1840 | 0x0BEC0000 |----------| |
| 1841 | : : |
| 1842 | 0x08000000 +----------+ BL31 is loaded |
| 1843 | after SCP_BL2 has |
| 1844 | Trusted SRAM been sent to SCP |
| 1845 | 0x04040000 +----------+ loaded by BL2 ------------------ |
| 1846 | | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | |
| 1847 | |----------| <<<<<<<<<<<<< |----------------| |
| 1848 | | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | |
| 1849 | |----------| ------------------ |
| 1850 | | BL2 | |
| 1851 | |----------| |
| 1852 | | | |
| 1853 | 0x04001000 +----------+ |
| 1854 | | MHU | |
| 1855 | 0x04000000 +----------+ |
| 1856 | |
| 1857 | Firmware Image Package (FIP) |
| 1858 | ---------------------------- |
| 1859 | |
| 1860 | Using a Firmware Image Package (FIP) allows for packing bootloader images (and |
| 1861 | potentially other payloads) into a single archive that can be loaded by the ARM |
| 1862 | Trusted Firmware from non-volatile platform storage. A driver to load images |
| 1863 | from a FIP has been added to the storage layer and allows a package to be read |
| 1864 | from supported platform storage. A tool to create Firmware Image Packages is |
| 1865 | also provided and described below. |
| 1866 | |
| 1867 | Firmware Image Package layout |
| 1868 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1869 | |
| 1870 | The FIP layout consists of a table of contents (ToC) followed by payload data. |
| 1871 | The ToC itself has a header followed by one or more table entries. The ToC is |
| 1872 | terminated by an end marker entry. All ToC entries describe some payload data |
| 1873 | that has been appended to the end of the binary package. With the information |
| 1874 | provided in the ToC entry the corresponding payload data can be retrieved. |
| 1875 | |
| 1876 | :: |
| 1877 | |
| 1878 | ------------------ |
| 1879 | | ToC Header | |
| 1880 | |----------------| |
| 1881 | | ToC Entry 0 | |
| 1882 | |----------------| |
| 1883 | | ToC Entry 1 | |
| 1884 | |----------------| |
| 1885 | | ToC End Marker | |
| 1886 | |----------------| |
| 1887 | | | |
| 1888 | | Data 0 | |
| 1889 | | | |
| 1890 | |----------------| |
| 1891 | | | |
| 1892 | | Data 1 | |
| 1893 | | | |
| 1894 | ------------------ |
| 1895 | |
| 1896 | The ToC header and entry formats are described in the header file |
| 1897 | ``include/tools_share/firmware_image_package.h``. This file is used by both the |
| 1898 | tool and the ARM Trusted firmware. |
| 1899 | |
| 1900 | The ToC header has the following fields: |
| 1901 | |
| 1902 | :: |
| 1903 | |
| 1904 | `name`: The name of the ToC. This is currently used to validate the header. |
| 1905 | `serial_number`: A non-zero number provided by the creation tool |
| 1906 | `flags`: Flags associated with this data. |
| 1907 | Bits 0-31: Reserved |
| 1908 | Bits 32-47: Platform defined |
| 1909 | Bits 48-63: Reserved |
| 1910 | |
| 1911 | A ToC entry has the following fields: |
| 1912 | |
| 1913 | :: |
| 1914 | |
| 1915 | `uuid`: All files are referred to by a pre-defined Universally Unique |
| 1916 | IDentifier [UUID] . The UUIDs are defined in |
| 1917 | `include/tools_share/firmware_image_package.h`. The platform translates |
| 1918 | the requested image name into the corresponding UUID when accessing the |
| 1919 | package. |
| 1920 | `offset_address`: The offset address at which the corresponding payload data |
| 1921 | can be found. The offset is calculated from the ToC base address. |
| 1922 | `size`: The size of the corresponding payload data in bytes. |
Etienne Carriere | d591d76 | 2017-08-23 15:43:33 +0200 | [diff] [blame] | 1923 | `flags`: Flags associated with this entry. None are yet defined. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 1924 | |
| 1925 | Firmware Image Package creation tool |
| 1926 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1927 | |
| 1928 | The FIP creation tool can be used to pack specified images into a binary package |
| 1929 | that can be loaded by the ARM Trusted Firmware from platform storage. The tool |
| 1930 | currently only supports packing bootloader images. Additional image definitions |
| 1931 | can be added to the tool as required. |
| 1932 | |
| 1933 | The tool can be found in ``tools/fiptool``. |
| 1934 | |
| 1935 | Loading from a Firmware Image Package (FIP) |
| 1936 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1937 | |
| 1938 | The Firmware Image Package (FIP) driver can load images from a binary package on |
| 1939 | non-volatile platform storage. For the ARM development platforms, this is |
| 1940 | currently NOR FLASH. |
| 1941 | |
| 1942 | Bootloader images are loaded according to the platform policy as specified by |
| 1943 | the function ``plat_get_image_source()``. For the ARM development platforms, this |
| 1944 | means the platform will attempt to load images from a Firmware Image Package |
| 1945 | located at the start of NOR FLASH0. |
| 1946 | |
| 1947 | The ARM development platforms' policy is to only allow loading of a known set of |
| 1948 | images. The platform policy can be modified to allow additional images. |
| 1949 | |
| 1950 | Use of coherent memory in Trusted Firmware |
| 1951 | ------------------------------------------ |
| 1952 | |
| 1953 | There might be loss of coherency when physical memory with mismatched |
| 1954 | shareability, cacheability and memory attributes is accessed by multiple CPUs |
| 1955 | (refer to section B2.9 of `ARM ARM`_ for more details). This possibility occurs |
| 1956 | in Trusted Firmware during power up/down sequences when coherency, MMU and |
| 1957 | caches are turned on/off incrementally. |
| 1958 | |
| 1959 | Trusted Firmware defines coherent memory as a region of memory with Device |
| 1960 | nGnRE attributes in the translation tables. The translation granule size in |
| 1961 | Trusted Firmware is 4KB. This is the smallest possible size of the coherent |
| 1962 | memory region. |
| 1963 | |
| 1964 | By default, all data structures which are susceptible to accesses with |
| 1965 | mismatched attributes from various CPUs are allocated in a coherent memory |
| 1966 | region (refer to section 2.1 of `Porting Guide`_). The coherent memory region |
| 1967 | accesses are Outer Shareable, non-cacheable and they can be accessed |
| 1968 | with the Device nGnRE attributes when the MMU is turned on. Hence, at the |
| 1969 | expense of at least an extra page of memory, Trusted Firmware is able to work |
| 1970 | around coherency issues due to mismatched memory attributes. |
| 1971 | |
| 1972 | The alternative to the above approach is to allocate the susceptible data |
| 1973 | structures in Normal WriteBack WriteAllocate Inner shareable memory. This |
| 1974 | approach requires the data structures to be designed so that it is possible to |
| 1975 | work around the issue of mismatched memory attributes by performing software |
| 1976 | cache maintenance on them. |
| 1977 | |
| 1978 | Disabling the use of coherent memory in Trusted Firmware |
| 1979 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1980 | |
| 1981 | It might be desirable to avoid the cost of allocating coherent memory on |
| 1982 | platforms which are memory constrained. Trusted Firmware enables inclusion of |
| 1983 | coherent memory in firmware images through the build flag ``USE_COHERENT_MEM``. |
| 1984 | This flag is enabled by default. It can be disabled to choose the second |
| 1985 | approach described above. |
| 1986 | |
| 1987 | The below sections analyze the data structures allocated in the coherent memory |
| 1988 | region and the changes required to allocate them in normal memory. |
| 1989 | |
| 1990 | Coherent memory usage in PSCI implementation |
| 1991 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1992 | |
| 1993 | The ``psci_non_cpu_pd_nodes`` data structure stores the platform's power domain |
| 1994 | tree information for state management of power domains. By default, this data |
| 1995 | structure is allocated in the coherent memory region in the Trusted Firmware |
| 1996 | because it can be accessed by multple CPUs, either with caches enabled or |
| 1997 | disabled. |
| 1998 | |
| 1999 | .. code:: c |
| 2000 | |
| 2001 | typedef struct non_cpu_pwr_domain_node { |
| 2002 | /* |
| 2003 | * Index of the first CPU power domain node level 0 which has this node |
| 2004 | * as its parent. |
| 2005 | */ |
| 2006 | unsigned int cpu_start_idx; |
| 2007 | |
| 2008 | /* |
| 2009 | * Number of CPU power domains which are siblings of the domain indexed |
| 2010 | * by 'cpu_start_idx' i.e. all the domains in the range 'cpu_start_idx |
| 2011 | * -> cpu_start_idx + ncpus' have this node as their parent. |
| 2012 | */ |
| 2013 | unsigned int ncpus; |
| 2014 | |
| 2015 | /* |
| 2016 | * Index of the parent power domain node. |
| 2017 | * TODO: Figure out whether to whether using pointer is more efficient. |
| 2018 | */ |
| 2019 | unsigned int parent_node; |
| 2020 | |
| 2021 | plat_local_state_t local_state; |
| 2022 | |
| 2023 | unsigned char level; |
| 2024 | |
| 2025 | /* For indexing the psci_lock array*/ |
| 2026 | unsigned char lock_index; |
| 2027 | } non_cpu_pd_node_t; |
| 2028 | |
| 2029 | In order to move this data structure to normal memory, the use of each of its |
| 2030 | fields must be analyzed. Fields like ``cpu_start_idx``, ``ncpus``, ``parent_node`` |
| 2031 | ``level`` and ``lock_index`` are only written once during cold boot. Hence removing |
| 2032 | them from coherent memory involves only doing a clean and invalidate of the |
| 2033 | cache lines after these fields are written. |
| 2034 | |
| 2035 | The field ``local_state`` can be concurrently accessed by multiple CPUs in |
| 2036 | different cache states. A Lamport's Bakery lock ``psci_locks`` is used to ensure |
| 2037 | mutual exlusion to this field and a clean and invalidate is needed after it |
| 2038 | is written. |
| 2039 | |
| 2040 | Bakery lock data |
| 2041 | ~~~~~~~~~~~~~~~~ |
| 2042 | |
| 2043 | The bakery lock data structure ``bakery_lock_t`` is allocated in coherent memory |
| 2044 | and is accessed by multiple CPUs with mismatched attributes. ``bakery_lock_t`` is |
| 2045 | defined as follows: |
| 2046 | |
| 2047 | .. code:: c |
| 2048 | |
| 2049 | typedef struct bakery_lock { |
| 2050 | /* |
| 2051 | * The lock_data is a bit-field of 2 members: |
| 2052 | * Bit[0] : choosing. This field is set when the CPU is |
| 2053 | * choosing its bakery number. |
| 2054 | * Bits[1 - 15] : number. This is the bakery number allocated. |
| 2055 | */ |
| 2056 | volatile uint16_t lock_data[BAKERY_LOCK_MAX_CPUS]; |
| 2057 | } bakery_lock_t; |
| 2058 | |
| 2059 | It is a characteristic of Lamport's Bakery algorithm that the volatile per-CPU |
| 2060 | fields can be read by all CPUs but only written to by the owning CPU. |
| 2061 | |
| 2062 | Depending upon the data cache line size, the per-CPU fields of the |
| 2063 | ``bakery_lock_t`` structure for multiple CPUs may exist on a single cache line. |
| 2064 | These per-CPU fields can be read and written during lock contention by multiple |
| 2065 | CPUs with mismatched memory attributes. Since these fields are a part of the |
| 2066 | lock implementation, they do not have access to any other locking primitive to |
| 2067 | safeguard against the resulting coherency issues. As a result, simple software |
| 2068 | cache maintenance is not enough to allocate them in coherent memory. Consider |
| 2069 | the following example. |
| 2070 | |
| 2071 | CPU0 updates its per-CPU field with data cache enabled. This write updates a |
| 2072 | local cache line which contains a copy of the fields for other CPUs as well. Now |
| 2073 | CPU1 updates its per-CPU field of the ``bakery_lock_t`` structure with data cache |
| 2074 | disabled. CPU1 then issues a DCIVAC operation to invalidate any stale copies of |
| 2075 | its field in any other cache line in the system. This operation will invalidate |
| 2076 | the update made by CPU0 as well. |
| 2077 | |
| 2078 | To use bakery locks when ``USE_COHERENT_MEM`` is disabled, the lock data structure |
| 2079 | has been redesigned. The changes utilise the characteristic of Lamport's Bakery |
| 2080 | algorithm mentioned earlier. The bakery\_lock structure only allocates the memory |
| 2081 | for a single CPU. The macro ``DEFINE_BAKERY_LOCK`` allocates all the bakery locks |
| 2082 | needed for a CPU into a section ``bakery_lock``. The linker allocates the memory |
| 2083 | for other cores by using the total size allocated for the bakery\_lock section |
| 2084 | and multiplying it with (PLATFORM\_CORE\_COUNT - 1). This enables software to |
| 2085 | perform software cache maintenance on the lock data structure without running |
| 2086 | into coherency issues associated with mismatched attributes. |
| 2087 | |
| 2088 | The bakery lock data structure ``bakery_info_t`` is defined for use when |
| 2089 | ``USE_COHERENT_MEM`` is disabled as follows: |
| 2090 | |
| 2091 | .. code:: c |
| 2092 | |
| 2093 | typedef struct bakery_info { |
| 2094 | /* |
| 2095 | * The lock_data is a bit-field of 2 members: |
| 2096 | * Bit[0] : choosing. This field is set when the CPU is |
| 2097 | * choosing its bakery number. |
| 2098 | * Bits[1 - 15] : number. This is the bakery number allocated. |
| 2099 | */ |
| 2100 | volatile uint16_t lock_data; |
| 2101 | } bakery_info_t; |
| 2102 | |
| 2103 | The ``bakery_info_t`` represents a single per-CPU field of one lock and |
| 2104 | the combination of corresponding ``bakery_info_t`` structures for all CPUs in the |
| 2105 | system represents the complete bakery lock. The view in memory for a system |
| 2106 | with n bakery locks are: |
| 2107 | |
| 2108 | :: |
| 2109 | |
| 2110 | bakery_lock section start |
| 2111 | |----------------| |
| 2112 | | `bakery_info_t`| <-- Lock_0 per-CPU field |
| 2113 | | Lock_0 | for CPU0 |
| 2114 | |----------------| |
| 2115 | | `bakery_info_t`| <-- Lock_1 per-CPU field |
| 2116 | | Lock_1 | for CPU0 |
| 2117 | |----------------| |
| 2118 | | .... | |
| 2119 | |----------------| |
| 2120 | | `bakery_info_t`| <-- Lock_N per-CPU field |
| 2121 | | Lock_N | for CPU0 |
| 2122 | ------------------ |
| 2123 | | XXXXX | |
| 2124 | | Padding to | |
| 2125 | | next Cache WB | <--- Calculate PERCPU_BAKERY_LOCK_SIZE, allocate |
| 2126 | | Granule | continuous memory for remaining CPUs. |
| 2127 | ------------------ |
| 2128 | | `bakery_info_t`| <-- Lock_0 per-CPU field |
| 2129 | | Lock_0 | for CPU1 |
| 2130 | |----------------| |
| 2131 | | `bakery_info_t`| <-- Lock_1 per-CPU field |
| 2132 | | Lock_1 | for CPU1 |
| 2133 | |----------------| |
| 2134 | | .... | |
| 2135 | |----------------| |
| 2136 | | `bakery_info_t`| <-- Lock_N per-CPU field |
| 2137 | | Lock_N | for CPU1 |
| 2138 | ------------------ |
| 2139 | | XXXXX | |
| 2140 | | Padding to | |
| 2141 | | next Cache WB | |
| 2142 | | Granule | |
| 2143 | ------------------ |
| 2144 | |
| 2145 | Consider a system of 2 CPUs with 'N' bakery locks as shown above. For an |
| 2146 | operation on Lock\_N, the corresponding ``bakery_info_t`` in both CPU0 and CPU1 |
| 2147 | ``bakery_lock`` section need to be fetched and appropriate cache operations need |
| 2148 | to be performed for each access. |
| 2149 | |
| 2150 | On ARM Platforms, bakery locks are used in psci (``psci_locks``) and power controller |
| 2151 | driver (``arm_lock``). |
| 2152 | |
| 2153 | Non Functional Impact of removing coherent memory |
| 2154 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 2155 | |
| 2156 | Removal of the coherent memory region leads to the additional software overhead |
| 2157 | of performing cache maintenance for the affected data structures. However, since |
| 2158 | the memory where the data structures are allocated is cacheable, the overhead is |
| 2159 | mostly mitigated by an increase in performance. |
| 2160 | |
| 2161 | There is however a performance impact for bakery locks, due to: |
| 2162 | |
| 2163 | - Additional cache maintenance operations, and |
| 2164 | - Multiple cache line reads for each lock operation, since the bakery locks |
| 2165 | for each CPU are distributed across different cache lines. |
| 2166 | |
| 2167 | The implementation has been optimized to minimize this additional overhead. |
| 2168 | Measurements indicate that when bakery locks are allocated in Normal memory, the |
| 2169 | minimum latency of acquiring a lock is on an average 3-4 micro seconds whereas |
| 2170 | in Device memory the same is 2 micro seconds. The measurements were done on the |
| 2171 | Juno ARM development platform. |
| 2172 | |
| 2173 | As mentioned earlier, almost a page of memory can be saved by disabling |
| 2174 | ``USE_COHERENT_MEM``. Each platform needs to consider these trade-offs to decide |
| 2175 | whether coherent memory should be used. If a platform disables |
| 2176 | ``USE_COHERENT_MEM`` and needs to use bakery locks in the porting layer, it can |
| 2177 | optionally define macro ``PLAT_PERCPU_BAKERY_LOCK_SIZE`` (see the |
| 2178 | `Porting Guide`_). Refer to the reference platform code for examples. |
| 2179 | |
| 2180 | Isolating code and read-only data on separate memory pages |
| 2181 | ---------------------------------------------------------- |
| 2182 | |
| 2183 | In the ARMv8 VMSA, translation table entries include fields that define the |
| 2184 | properties of the target memory region, such as its access permissions. The |
| 2185 | smallest unit of memory that can be addressed by a translation table entry is |
| 2186 | a memory page. Therefore, if software needs to set different permissions on two |
| 2187 | memory regions then it needs to map them using different memory pages. |
| 2188 | |
| 2189 | The default memory layout for each BL image is as follows: |
| 2190 | |
| 2191 | :: |
| 2192 | |
| 2193 | | ... | |
| 2194 | +-------------------+ |
| 2195 | | Read-write data | |
| 2196 | +-------------------+ Page boundary |
| 2197 | | <Padding> | |
| 2198 | +-------------------+ |
| 2199 | | Exception vectors | |
| 2200 | +-------------------+ 2 KB boundary |
| 2201 | | <Padding> | |
| 2202 | +-------------------+ |
| 2203 | | Read-only data | |
| 2204 | +-------------------+ |
| 2205 | | Code | |
| 2206 | +-------------------+ BLx_BASE |
| 2207 | |
| 2208 | Note: The 2KB alignment for the exception vectors is an architectural |
| 2209 | requirement. |
| 2210 | |
| 2211 | The read-write data start on a new memory page so that they can be mapped with |
| 2212 | read-write permissions, whereas the code and read-only data below are configured |
| 2213 | as read-only. |
| 2214 | |
| 2215 | However, the read-only data are not aligned on a page boundary. They are |
| 2216 | contiguous to the code. Therefore, the end of the code section and the beginning |
| 2217 | of the read-only data one might share a memory page. This forces both to be |
| 2218 | mapped with the same memory attributes. As the code needs to be executable, this |
| 2219 | means that the read-only data stored on the same memory page as the code are |
| 2220 | executable as well. This could potentially be exploited as part of a security |
| 2221 | attack. |
| 2222 | |
| 2223 | TF provides the build flag ``SEPARATE_CODE_AND_RODATA`` to isolate the code and |
| 2224 | read-only data on separate memory pages. This in turn allows independent control |
| 2225 | of the access permissions for the code and read-only data. In this case, |
| 2226 | platform code gets a finer-grained view of the image layout and can |
| 2227 | appropriately map the code region as executable and the read-only data as |
| 2228 | execute-never. |
| 2229 | |
| 2230 | This has an impact on memory footprint, as padding bytes need to be introduced |
| 2231 | between the code and read-only data to ensure the segragation of the two. To |
| 2232 | limit the memory cost, this flag also changes the memory layout such that the |
| 2233 | code and exception vectors are now contiguous, like so: |
| 2234 | |
| 2235 | :: |
| 2236 | |
| 2237 | | ... | |
| 2238 | +-------------------+ |
| 2239 | | Read-write data | |
| 2240 | +-------------------+ Page boundary |
| 2241 | | <Padding> | |
| 2242 | +-------------------+ |
| 2243 | | Read-only data | |
| 2244 | +-------------------+ Page boundary |
| 2245 | | <Padding> | |
| 2246 | +-------------------+ |
| 2247 | | Exception vectors | |
| 2248 | +-------------------+ 2 KB boundary |
| 2249 | | <Padding> | |
| 2250 | +-------------------+ |
| 2251 | | Code | |
| 2252 | +-------------------+ BLx_BASE |
| 2253 | |
| 2254 | With this more condensed memory layout, the separation of read-only data will |
| 2255 | add zero or one page to the memory footprint of each BL image. Each platform |
| 2256 | should consider the trade-off between memory footprint and security. |
| 2257 | |
| 2258 | This build flag is disabled by default, minimising memory footprint. On ARM |
| 2259 | platforms, it is enabled. |
| 2260 | |
Jeenu Viswambharan | 8e743bc | 2017-09-22 08:32:10 +0100 | [diff] [blame] | 2261 | Publish and Subscribe Framework |
| 2262 | ------------------------------- |
| 2263 | |
| 2264 | The Publish and Subscribe Framework allows EL3 components to define and publish |
| 2265 | events, to which other EL3 components can subscribe. |
| 2266 | |
| 2267 | The following macros are provided by the framework: |
| 2268 | |
| 2269 | - ``REGISTER_PUBSUB_EVENT(event)``: Defines an event, and takes one argument, |
| 2270 | the event name, which must be a valid C identifier. All calls to |
| 2271 | ``REGISTER_PUBSUB_EVENT`` macro must be placed in the file |
| 2272 | ``pubsub_events.h``. |
| 2273 | |
| 2274 | - ``PUBLISH_EVENT_ARG(event, arg)``: Publishes a defined event, by iterating |
| 2275 | subscribed handlers and calling them in turn. The handlers will be passed the |
| 2276 | parameter ``arg``. The expected use-case is to broadcast an event. |
| 2277 | |
| 2278 | - ``PUBLISH_EVENT(event)``: Like ``PUBLISH_EVENT_ARG``, except that the value |
| 2279 | ``NULL`` is passed to subscribed handlers. |
| 2280 | |
| 2281 | - ``SUBSCRIBE_TO_EVENT(event, handler)``: Registers the ``handler`` to |
| 2282 | subscribe to ``event``. The handler will be executed whenever the ``event`` |
| 2283 | is published. |
| 2284 | |
| 2285 | - ``for_each_subscriber(event, subscriber)``: Iterates through all handlers |
| 2286 | subscribed for ``event``. ``subscriber`` must be a local variable of type |
| 2287 | ``pubsub_cb_t *``, and will point to each subscribed handler in turn during |
| 2288 | iteration. This macro can be used for those patterns that none of the |
| 2289 | ``PUBLISH_EVENT_*()`` macros cover. |
| 2290 | |
| 2291 | Publishing an event that wasn't defined using ``REGISTER_PUBSUB_EVENT`` will |
| 2292 | result in build error. Subscribing to an undefined event however won't. |
| 2293 | |
| 2294 | Subscribed handlers must be of type ``pubsub_cb_t``, with following function |
| 2295 | signature: |
| 2296 | |
| 2297 | :: |
| 2298 | |
| 2299 | typedef void* (*pubsub_cb_t)(const void *arg); |
| 2300 | |
| 2301 | There may be arbitrary number of handlers registered to the same event. The |
| 2302 | order in which subscribed handlers are notified when that event is published is |
| 2303 | not defined. Subscribed handlers may be executed in any order; handlers should |
| 2304 | not assume any relative ordering amongst them. |
| 2305 | |
| 2306 | Publishing an event on a PE will result in subscribed handlers executing on that |
| 2307 | PE only; it won't cause handlers to execute on a different PE. |
| 2308 | |
| 2309 | Note that publishing an event on a PE blocks until all the subscribed handlers |
| 2310 | finish executing on the PE. |
| 2311 | |
Dimitris Papastamos | 17b4c0d | 2017-10-13 15:27:58 +0100 | [diff] [blame] | 2312 | ARM Trusted Firmware generic code publishes and subscribes to some events |
| 2313 | within. Platform ports are discouraged from subscribing to them. These events |
| 2314 | may be withdrawn, renamed, or have their semantics altered in the future. |
| 2315 | Platforms may however register, publish, and subscribe to platform-specific |
| 2316 | events. |
| 2317 | |
Jeenu Viswambharan | 8e743bc | 2017-09-22 08:32:10 +0100 | [diff] [blame] | 2318 | Publish and Subscribe Example |
| 2319 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 2320 | |
| 2321 | A publisher that wants to publish event ``foo`` would: |
| 2322 | |
| 2323 | - Define the event ``foo`` in the ``pubsub_events.h``. |
| 2324 | |
| 2325 | :: |
| 2326 | |
| 2327 | REGISTER_PUBSUB_EVENT(foo); |
| 2328 | |
| 2329 | - Depending on the nature of event, use one of ``PUBLISH_EVENT_*()`` macros to |
| 2330 | publish the event at the appropriate path and time of execution. |
| 2331 | |
| 2332 | A subscriber that wants to subscribe to event ``foo`` published above would |
| 2333 | implement: |
| 2334 | |
| 2335 | :: |
| 2336 | |
| 2337 | void *foo_handler(const void *arg) |
| 2338 | { |
| 2339 | void *result; |
| 2340 | |
| 2341 | /* Do handling ... */ |
| 2342 | |
| 2343 | return result; |
| 2344 | } |
| 2345 | |
| 2346 | SUBSCRIBE_TO_EVENT(foo, foo_handler); |
| 2347 | |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 2348 | Performance Measurement Framework |
| 2349 | --------------------------------- |
| 2350 | |
| 2351 | The Performance Measurement Framework (PMF) facilitates collection of |
| 2352 | timestamps by registered services and provides interfaces to retrieve |
| 2353 | them from within the ARM Trusted Firmware. A platform can choose to |
| 2354 | expose appropriate SMCs to retrieve these collected timestamps. |
| 2355 | |
| 2356 | By default, the global physical counter is used for the timestamp |
| 2357 | value and is read via ``CNTPCT_EL0``. The framework allows to retrieve |
| 2358 | timestamps captured by other CPUs. |
| 2359 | |
| 2360 | Timestamp identifier format |
| 2361 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 2362 | |
| 2363 | A PMF timestamp is uniquely identified across the system via the |
| 2364 | timestamp ID or ``tid``. The ``tid`` is composed as follows: |
| 2365 | |
| 2366 | :: |
| 2367 | |
| 2368 | Bits 0-7: The local timestamp identifier. |
| 2369 | Bits 8-9: Reserved. |
| 2370 | Bits 10-15: The service identifier. |
| 2371 | Bits 16-31: Reserved. |
| 2372 | |
| 2373 | #. The service identifier. Each PMF service is identified by a |
| 2374 | service name and a service identifier. Both the service name and |
| 2375 | identifier are unique within the system as a whole. |
| 2376 | |
| 2377 | #. The local timestamp identifier. This identifier is unique within a given |
| 2378 | service. |
| 2379 | |
| 2380 | Registering a PMF service |
| 2381 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 2382 | |
| 2383 | To register a PMF service, the ``PMF_REGISTER_SERVICE()`` macro from ``pmf.h`` |
| 2384 | is used. The arguments required are the service name, the service ID, |
| 2385 | the total number of local timestamps to be captured and a set of flags. |
| 2386 | |
| 2387 | The ``flags`` field can be specified as a bitwise-OR of the following values: |
| 2388 | |
| 2389 | :: |
| 2390 | |
| 2391 | PMF_STORE_ENABLE: The timestamp is stored in memory for later retrieval. |
| 2392 | PMF_DUMP_ENABLE: The timestamp is dumped on the serial console. |
| 2393 | |
| 2394 | The ``PMF_REGISTER_SERVICE()`` reserves memory to store captured |
| 2395 | timestamps in a PMF specific linker section at build time. |
| 2396 | Additionally, it defines necessary functions to capture and |
| 2397 | retrieve a particular timestamp for the given service at runtime. |
| 2398 | |
| 2399 | The macro ``PMF_REGISTER_SERVICE()`` only enables capturing PMF |
| 2400 | timestamps from within ARM Trusted Firmware. In order to retrieve |
| 2401 | timestamps from outside of ARM Trusted Firmware, the |
| 2402 | ``PMF_REGISTER_SERVICE_SMC()`` macro must be used instead. This macro |
| 2403 | accepts the same set of arguments as the ``PMF_REGISTER_SERVICE()`` |
| 2404 | macro but additionally supports retrieving timestamps using SMCs. |
| 2405 | |
| 2406 | Capturing a timestamp |
| 2407 | ~~~~~~~~~~~~~~~~~~~~~ |
| 2408 | |
| 2409 | PMF timestamps are stored in a per-service timestamp region. On a |
| 2410 | system with multiple CPUs, each timestamp is captured and stored |
| 2411 | in a per-CPU cache line aligned memory region. |
| 2412 | |
| 2413 | Having registered the service, the ``PMF_CAPTURE_TIMESTAMP()`` macro can be |
| 2414 | used to capture a timestamp at the location where it is used. The macro |
| 2415 | takes the service name, a local timestamp identifier and a flag as arguments. |
| 2416 | |
| 2417 | The ``flags`` field argument can be zero, or ``PMF_CACHE_MAINT`` which |
| 2418 | instructs PMF to do cache maintenance following the capture. Cache |
| 2419 | maintenance is required if any of the service's timestamps are captured |
| 2420 | with data cache disabled. |
| 2421 | |
| 2422 | To capture a timestamp in assembly code, the caller should use |
| 2423 | ``pmf_calc_timestamp_addr`` macro (defined in ``pmf_asm_macros.S``) to |
| 2424 | calculate the address of where the timestamp would be stored. The |
| 2425 | caller should then read ``CNTPCT_EL0`` register to obtain the timestamp |
| 2426 | and store it at the determined address for later retrieval. |
| 2427 | |
| 2428 | Retrieving a timestamp |
| 2429 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 2430 | |
| 2431 | From within ARM Trusted Firmware, timestamps for individual CPUs can |
| 2432 | be retrieved using either ``PMF_GET_TIMESTAMP_BY_MPIDR()`` or |
| 2433 | ``PMF_GET_TIMESTAMP_BY_INDEX()`` macros. These macros accept the CPU's MPIDR |
| 2434 | value, or its ordinal position, respectively. |
| 2435 | |
| 2436 | From outside ARM Trusted Firmware, timestamps for individual CPUs can be |
| 2437 | retrieved by calling into ``pmf_smc_handler()``. |
| 2438 | |
| 2439 | .. code:: c |
| 2440 | |
| 2441 | Interface : pmf_smc_handler() |
| 2442 | Argument : unsigned int smc_fid, u_register_t x1, |
| 2443 | u_register_t x2, u_register_t x3, |
| 2444 | u_register_t x4, void *cookie, |
| 2445 | void *handle, u_register_t flags |
| 2446 | Return : uintptr_t |
| 2447 | |
| 2448 | smc_fid: Holds the SMC identifier which is either `PMF_SMC_GET_TIMESTAMP_32` |
| 2449 | when the caller of the SMC is running in AArch32 mode |
| 2450 | or `PMF_SMC_GET_TIMESTAMP_64` when the caller is running in AArch64 mode. |
| 2451 | x1: Timestamp identifier. |
| 2452 | x2: The `mpidr` of the CPU for which the timestamp has to be retrieved. |
| 2453 | This can be the `mpidr` of a different core to the one initiating |
| 2454 | the SMC. In that case, service specific cache maintenance may be |
| 2455 | required to ensure the updated copy of the timestamp is returned. |
| 2456 | x3: A flags value that is either 0 or `PMF_CACHE_MAINT`. If |
| 2457 | `PMF_CACHE_MAINT` is passed, then the PMF code will perform a |
| 2458 | cache invalidate before reading the timestamp. This ensures |
| 2459 | an updated copy is returned. |
| 2460 | |
| 2461 | The remaining arguments, ``x4``, ``cookie``, ``handle`` and ``flags`` are unused |
| 2462 | in this implementation. |
| 2463 | |
| 2464 | PMF code structure |
| 2465 | ~~~~~~~~~~~~~~~~~~ |
| 2466 | |
| 2467 | #. ``pmf_main.c`` consists of core functions that implement service registration, |
| 2468 | initialization, storing, dumping and retrieving timestamps. |
| 2469 | |
| 2470 | #. ``pmf_smc.c`` contains the SMC handling for registered PMF services. |
| 2471 | |
| 2472 | #. ``pmf.h`` contains the public interface to Performance Measurement Framework. |
| 2473 | |
| 2474 | #. ``pmf_asm_macros.S`` consists of macros to facilitate capturing timestamps in |
| 2475 | assembly code. |
| 2476 | |
| 2477 | #. ``pmf_helpers.h`` is an internal header used by ``pmf.h``. |
| 2478 | |
Jeenu Viswambharan | 579b4ad | 2017-08-24 15:43:44 +0100 | [diff] [blame] | 2479 | ARMv8 Architecture Extensions |
| 2480 | ----------------------------- |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 2481 | |
| 2482 | ARM Trusted Firmware makes use of ARMv8 Architecture Extensions where |
| 2483 | applicable. This section lists the usage of Architecture Extensions, and build |
| 2484 | flags controlling them. |
| 2485 | |
| 2486 | In general, and unless individually mentioned, the build options |
| 2487 | ``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` selects the Architecture Extension to |
| 2488 | target when building ARM Trusted Firmware. Subsequent ARM Architecture |
| 2489 | Extensions are backward compatible with previous versions. |
| 2490 | |
| 2491 | The build system only requires that ``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` have a |
| 2492 | valid numeric value. These build options only control whether or not |
| 2493 | Architecture Extension-specific code is included in the build. Otherwise, ARM |
| 2494 | Trusted Firmware targets the base ARMv8.0 architecture; i.e. as if |
| 2495 | ``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` == 0, which are also their respective |
| 2496 | default values. |
| 2497 | |
| 2498 | See also the *Summary of build options* in `User Guide`_. |
| 2499 | |
| 2500 | For details on the Architecture Extension and available features, please refer |
| 2501 | to the respective Architecture Extension Supplement. |
| 2502 | |
| 2503 | ARMv8.1 |
| 2504 | ~~~~~~~ |
| 2505 | |
| 2506 | This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when |
| 2507 | ``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 1. |
| 2508 | |
| 2509 | - The Compare and Swap instruction is used to implement spinlocks. Otherwise, |
| 2510 | the load-/store-exclusive instruction pair is used. |
| 2511 | |
Isla Mitchell | 9fce272 | 2017-08-07 11:20:13 +0100 | [diff] [blame] | 2512 | ARMv8.2 |
| 2513 | ~~~~~~~ |
| 2514 | |
| 2515 | This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 8 and |
| 2516 | ``ARM_ARCH_MINOR`` >= 2. |
| 2517 | |
| 2518 | - The Common not Private (CnP) bit is enabled to indicate that multiple |
| 2519 | Page Entries in the same Inner Shareable domain use the same translation |
| 2520 | table entries for a given stage of translation for a particular translation |
| 2521 | regime. |
| 2522 | |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 2523 | Code Structure |
| 2524 | -------------- |
| 2525 | |
| 2526 | Trusted Firmware code is logically divided between the three boot loader |
| 2527 | stages mentioned in the previous sections. The code is also divided into the |
| 2528 | following categories (present as directories in the source code): |
| 2529 | |
| 2530 | - **Platform specific.** Choice of architecture specific code depends upon |
| 2531 | the platform. |
| 2532 | - **Common code.** This is platform and architecture agnostic code. |
| 2533 | - **Library code.** This code comprises of functionality commonly used by all |
| 2534 | other code. The PSCI implementation and other EL3 runtime frameworks reside |
| 2535 | as Library components. |
| 2536 | - **Stage specific.** Code specific to a boot stage. |
| 2537 | - **Drivers.** |
| 2538 | - **Services.** EL3 runtime services (eg: SPD). Specific SPD services |
| 2539 | reside in the ``services/spd`` directory (e.g. ``services/spd/tspd``). |
| 2540 | |
| 2541 | Each boot loader stage uses code from one or more of the above mentioned |
| 2542 | categories. Based upon the above, the code layout looks like this: |
| 2543 | |
| 2544 | :: |
| 2545 | |
| 2546 | Directory Used by BL1? Used by BL2? Used by BL31? |
| 2547 | bl1 Yes No No |
| 2548 | bl2 No Yes No |
| 2549 | bl31 No No Yes |
| 2550 | plat Yes Yes Yes |
| 2551 | drivers Yes No Yes |
| 2552 | common Yes Yes Yes |
| 2553 | lib Yes Yes Yes |
| 2554 | services No No Yes |
| 2555 | |
| 2556 | The build system provides a non configurable build option IMAGE\_BLx for each |
| 2557 | boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE\_BL1 will be |
| 2558 | defined by the build system. This enables the Trusted Firmware to compile |
| 2559 | certain code only for specific boot loader stages |
| 2560 | |
| 2561 | All assembler files have the ``.S`` extension. The linker source files for each |
| 2562 | boot stage have the extension ``.ld.S``. These are processed by GCC to create the |
| 2563 | linker scripts which have the extension ``.ld``. |
| 2564 | |
| 2565 | FDTs provide a description of the hardware platform and are used by the Linux |
| 2566 | kernel at boot time. These can be found in the ``fdts`` directory. |
| 2567 | |
| 2568 | References |
| 2569 | ---------- |
| 2570 | |
Qixiang Xu | 67b6690 | 2017-10-16 17:29:18 +0800 | [diff] [blame] | 2571 | .. [#] Trusted Board Boot Requirements CLIENT PDD (ARM DEN0006C-1). Available |
Douglas Raillard | 668c502 | 2017-06-28 16:14:55 +0100 | [diff] [blame] | 2572 | under NDA through your ARM account representative. |
| 2573 | .. [#] `Power State Coordination Interface PDD`_ |
| 2574 | .. [#] `SMC Calling Convention PDD`_ |
| 2575 | .. [#] `ARM Trusted Firmware Interrupt Management Design guide`_. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 2576 | |
| 2577 | -------------- |
| 2578 | |
Antonio Nino Diaz | 6feb9e8 | 2017-05-23 11:49:22 +0100 | [diff] [blame] | 2579 | *Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.* |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 2580 | |
| 2581 | .. _Reset Design: ./reset-design.rst |
| 2582 | .. _Porting Guide: ./porting-guide.rst |
| 2583 | .. _Firmware Update: ./firmware-update.rst |
| 2584 | .. _PSCI PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf |
| 2585 | .. _SMC calling convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf |
| 2586 | .. _PSCI Library integration guide: ./psci-lib-integration-guide.rst |
| 2587 | .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf |
| 2588 | .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf |
| 2589 | .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf |
| 2590 | .. _here: ./psci-lib-integration-guide.rst |
| 2591 | .. _cpu-specific-build-macros.rst: ./cpu-specific-build-macros.rst |
| 2592 | .. _CPUBM: ./cpu-specific-build-macros.rst |
| 2593 | .. _ARM ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html |
| 2594 | .. _User Guide: ./user-guide.rst |
| 2595 | .. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf |
| 2596 | .. _ARM Trusted Firmware Interrupt Management Design guide: ./interrupt-framework-design.rst |
Antonio Nino Diaz | 6feb9e8 | 2017-05-23 11:49:22 +0100 | [diff] [blame] | 2597 | .. _Xlat_tables design: xlat-tables-lib-v2-design.rst |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 2598 | |
| 2599 | .. |Image 1| image:: diagrams/rt-svc-descs-layout.png?raw=true |