1Trusted Firmware-A Porting Guide 2================================ 3 4 5.. section-numbering:: 6 :suffix: . 7 8.. contents:: 9 10-------------- 11 12Introduction 13------------ 14 15Porting Trusted Firmware-A (TF-A) to a new platform involves making some 16mandatory and optional modifications for both the cold and warm boot paths. 17Modifications consist of: 18 19- Implementing a platform-specific function or variable, 20- Setting up the execution context in a certain way, or 21- Defining certain constants (for example #defines). 22 23The platform-specific functions and variables are declared in 24`include/plat/common/platform.h`_. The firmware provides a default implementation 25of variables and functions to fulfill the optional requirements. These 26implementations are all weakly defined; they are provided to ease the porting 27effort. Each platform port can override them with its own implementation if the 28default implementation is inadequate. 29 30Platform ports that want to be aligned with standard Arm platforms (for example 31FVP and Juno) may also use `include/plat/arm/common/plat\_arm.h`_ and the 32corresponding source files in ``plat/arm/common/``. These provide standard 33implementations for some of the required platform porting functions. However, 34using these functions requires the platform port to implement additional 35Arm standard platform porting functions. These additional functions are not 36documented here. 37 38Some modifications are common to all Boot Loader (BL) stages. Section 2 39discusses these in detail. The subsequent sections discuss the remaining 40modifications for each BL stage in detail. 41 42This document should be read in conjunction with the TF-A `User Guide`_. 43 44Common modifications 45-------------------- 46 47This section covers the modifications that should be made by the platform for 48each BL stage to correctly port the firmware stack. They are categorized as 49either mandatory or optional. 50 51Common mandatory modifications 52------------------------------ 53 54A platform port must enable the Memory Management Unit (MMU) as well as the 55instruction and data caches for each BL stage. Setting up the translation 56tables is the responsibility of the platform port because memory maps differ 57across platforms. A memory translation library (see ``lib/xlat_tables/``) is 58provided to help in this setup. 59 60Note that although this library supports non-identity mappings, this is intended 61only for re-mapping peripheral physical addresses and allows platforms with high 62I/O addresses to reduce their virtual address space. All other addresses 63corresponding to code and data must currently use an identity mapping. 64 65Also, the only translation granule size supported in TF-A is 4KB, as various 66parts of the code assume that is the case. It is not possible to switch to 6716 KB or 64 KB granule sizes at the moment. 68 69In Arm standard platforms, each BL stage configures the MMU in the 70platform-specific architecture setup function, ``blX_plat_arch_setup()``, and uses 71an identity mapping for all addresses. 72 73If the build option ``USE_COHERENT_MEM`` is enabled, each platform can allocate a 74block of identity mapped secure memory with Device-nGnRE attributes aligned to 75page boundary (4K) for each BL stage. All sections which allocate coherent 76memory are grouped under ``coherent_ram``. For ex: Bakery locks are placed in a 77section identified by name ``bakery_lock`` inside ``coherent_ram`` so that its 78possible for the firmware to place variables in it using the following C code 79directive: 80 81:: 82 83 __section("bakery_lock") 84 85Or alternatively the following assembler code directive: 86 87:: 88 89 .section bakery_lock 90 91The ``coherent_ram`` section is a sum of all sections like ``bakery_lock`` which are 92used to allocate any data structures that are accessed both when a CPU is 93executing with its MMU and caches enabled, and when it's running with its MMU 94and caches disabled. Examples are given below. 95 96The following variables, functions and constants must be defined by the platform 97for the firmware to work correctly. 98 99File : platform\_def.h [mandatory] 100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 101 102Each platform must ensure that a header file of this name is in the system 103include path with the following constants defined. This may require updating the 104list of ``PLAT_INCLUDES`` in the ``platform.mk`` file. In the Arm development 105platforms, this file is found in ``plat/arm/board/<plat_name>/include/``. 106 107Platform ports may optionally use the file `include/plat/common/common\_def.h`_, 108which provides typical values for some of the constants below. These values are 109likely to be suitable for all platform ports. 110 111Platform ports that want to be aligned with standard Arm platforms (for example 112FVP and Juno) may also use `include/plat/arm/common/arm\_def.h`_, which provides 113standard values for some of the constants below. However, this requires the 114platform port to define additional platform porting constants in 115``platform_def.h``. These additional constants are not documented here. 116 117- **#define : PLATFORM\_LINKER\_FORMAT** 118 119 Defines the linker format used by the platform, for example 120 ``elf64-littleaarch64``. 121 122- **#define : PLATFORM\_LINKER\_ARCH** 123 124 Defines the processor architecture for the linker by the platform, for 125 example ``aarch64``. 126 127- **#define : PLATFORM\_STACK\_SIZE** 128 129 Defines the normal stack memory available to each CPU. This constant is used 130 by `plat/common/aarch64/platform\_mp\_stack.S`_ and 131 `plat/common/aarch64/platform\_up\_stack.S`_. 132 133- **define : CACHE\_WRITEBACK\_GRANULE** 134 135 Defines the size in bits of the largest cache line across all the cache 136 levels in the platform. 137 138- **#define : FIRMWARE\_WELCOME\_STR** 139 140 Defines the character string printed by BL1 upon entry into the ``bl1_main()`` 141 function. 142 143- **#define : PLATFORM\_CORE\_COUNT** 144 145 Defines the total number of CPUs implemented by the platform across all 146 clusters in the system. 147 148- **#define : PLAT\_NUM\_PWR\_DOMAINS** 149 150 Defines the total number of nodes in the power domain topology 151 tree at all the power domain levels used by the platform. 152 This macro is used by the PSCI implementation to allocate 153 data structures to represent power domain topology. 154 155- **#define : PLAT\_MAX\_PWR\_LVL** 156 157 Defines the maximum power domain level that the power management operations 158 should apply to. More often, but not always, the power domain level 159 corresponds to affinity level. This macro allows the PSCI implementation 160 to know the highest power domain level that it should consider for power 161 management operations in the system that the platform implements. For 162 example, the Base AEM FVP implements two clusters with a configurable 163 number of CPUs and it reports the maximum power domain level as 1. 164 165- **#define : PLAT\_MAX\_OFF\_STATE** 166 167 Defines the local power state corresponding to the deepest power down 168 possible at every power domain level in the platform. The local power 169 states for each level may be sparsely allocated between 0 and this value 170 with 0 being reserved for the RUN state. The PSCI implementation uses this 171 value to initialize the local power states of the power domain nodes and 172 to specify the requested power state for a PSCI\_CPU\_OFF call. 173 174- **#define : PLAT\_MAX\_RET\_STATE** 175 176 Defines the local power state corresponding to the deepest retention state 177 possible at every power domain level in the platform. This macro should be 178 a value less than PLAT\_MAX\_OFF\_STATE and greater than 0. It is used by the 179 PSCI implementation to distinguish between retention and power down local 180 power states within PSCI\_CPU\_SUSPEND call. 181 182- **#define : PLAT\_MAX\_PWR\_LVL\_STATES** 183 184 Defines the maximum number of local power states per power domain level 185 that the platform supports. The default value of this macro is 2 since 186 most platforms just support a maximum of two local power states at each 187 power domain level (power-down and retention). If the platform needs to 188 account for more local power states, then it must redefine this macro. 189 190 Currently, this macro is used by the Generic PSCI implementation to size 191 the array used for PSCI\_STAT\_COUNT/RESIDENCY accounting. 192 193- **#define : BL1\_RO\_BASE** 194 195 Defines the base address in secure ROM where BL1 originally lives. Must be 196 aligned on a page-size boundary. 197 198- **#define : BL1\_RO\_LIMIT** 199 200 Defines the maximum address in secure ROM that BL1's actual content (i.e. 201 excluding any data section allocated at runtime) can occupy. 202 203- **#define : BL1\_RW\_BASE** 204 205 Defines the base address in secure RAM where BL1's read-write data will live 206 at runtime. Must be aligned on a page-size boundary. 207 208- **#define : BL1\_RW\_LIMIT** 209 210 Defines the maximum address in secure RAM that BL1's read-write data can 211 occupy at runtime. 212 213- **#define : BL2\_BASE** 214 215 Defines the base address in secure RAM where BL1 loads the BL2 binary image. 216 Must be aligned on a page-size boundary. This constant is not applicable 217 when BL2_IN_XIP_MEM is set to '1'. 218 219- **#define : BL2\_LIMIT** 220 221 Defines the maximum address in secure RAM that the BL2 image can occupy. 222 This constant is not applicable when BL2_IN_XIP_MEM is set to '1'. 223 224- **#define : BL2\_RO\_BASE** 225 226 Defines the base address in secure XIP memory where BL2 RO section originally 227 lives. Must be aligned on a page-size boundary. This constant is only needed 228 when BL2_IN_XIP_MEM is set to '1'. 229 230- **#define : BL2\_RO\_LIMIT** 231 232 Defines the maximum address in secure XIP memory that BL2's actual content 233 (i.e. excluding any data section allocated at runtime) can occupy. This 234 constant is only needed when BL2_IN_XIP_MEM is set to '1'. 235 236- **#define : BL2\_RW\_BASE** 237 238 Defines the base address in secure RAM where BL2's read-write data will live 239 at runtime. Must be aligned on a page-size boundary. This constant is only 240 needed when BL2_IN_XIP_MEM is set to '1'. 241 242- **#define : BL2\_RW\_LIMIT** 243 244 Defines the maximum address in secure RAM that BL2's read-write data can 245 occupy at runtime. This constant is only needed when BL2_IN_XIP_MEM is set 246 to '1'. 247 248- **#define : BL31\_BASE** 249 250 Defines the base address in secure RAM where BL2 loads the BL31 binary 251 image. Must be aligned on a page-size boundary. 252 253- **#define : BL31\_LIMIT** 254 255 Defines the maximum address in secure RAM that the BL31 image can occupy. 256 257For every image, the platform must define individual identifiers that will be 258used by BL1 or BL2 to load the corresponding image into memory from non-volatile 259storage. For the sake of performance, integer numbers will be used as 260identifiers. The platform will use those identifiers to return the relevant 261information about the image to be loaded (file handler, load address, 262authentication information, etc.). The following image identifiers are 263mandatory: 264 265- **#define : BL2\_IMAGE\_ID** 266 267 BL2 image identifier, used by BL1 to load BL2. 268 269- **#define : BL31\_IMAGE\_ID** 270 271 BL31 image identifier, used by BL2 to load BL31. 272 273- **#define : BL33\_IMAGE\_ID** 274 275 BL33 image identifier, used by BL2 to load BL33. 276 277If Trusted Board Boot is enabled, the following certificate identifiers must 278also be defined: 279 280- **#define : TRUSTED\_BOOT\_FW\_CERT\_ID** 281 282 BL2 content certificate identifier, used by BL1 to load the BL2 content 283 certificate. 284 285- **#define : TRUSTED\_KEY\_CERT\_ID** 286 287 Trusted key certificate identifier, used by BL2 to load the trusted key 288 certificate. 289 290- **#define : SOC\_FW\_KEY\_CERT\_ID** 291 292 BL31 key certificate identifier, used by BL2 to load the BL31 key 293 certificate. 294 295- **#define : SOC\_FW\_CONTENT\_CERT\_ID** 296 297 BL31 content certificate identifier, used by BL2 to load the BL31 content 298 certificate. 299 300- **#define : NON\_TRUSTED\_FW\_KEY\_CERT\_ID** 301 302 BL33 key certificate identifier, used by BL2 to load the BL33 key 303 certificate. 304 305- **#define : NON\_TRUSTED\_FW\_CONTENT\_CERT\_ID** 306 307 BL33 content certificate identifier, used by BL2 to load the BL33 content 308 certificate. 309 310- **#define : FWU\_CERT\_ID** 311 312 Firmware Update (FWU) certificate identifier, used by NS\_BL1U to load the 313 FWU content certificate. 314 315- **#define : PLAT\_CRYPTOCELL\_BASE** 316 317 This defines the base address of Arm® TrustZone® CryptoCell and must be 318 defined if CryptoCell crypto driver is used for Trusted Board Boot. For 319 capable Arm platforms, this driver is used if ``ARM_CRYPTOCELL_INTEG`` is 320 set. 321 322If the AP Firmware Updater Configuration image, BL2U is used, the following 323must also be defined: 324 325- **#define : BL2U\_BASE** 326 327 Defines the base address in secure memory where BL1 copies the BL2U binary 328 image. Must be aligned on a page-size boundary. 329 330- **#define : BL2U\_LIMIT** 331 332 Defines the maximum address in secure memory that the BL2U image can occupy. 333 334- **#define : BL2U\_IMAGE\_ID** 335 336 BL2U image identifier, used by BL1 to fetch an image descriptor 337 corresponding to BL2U. 338 339If the SCP Firmware Update Configuration Image, SCP\_BL2U is used, the following 340must also be defined: 341 342- **#define : SCP\_BL2U\_IMAGE\_ID** 343 344 SCP\_BL2U image identifier, used by BL1 to fetch an image descriptor 345 corresponding to SCP\_BL2U. 346 NOTE: TF-A does not provide source code for this image. 347 348If the Non-Secure Firmware Updater ROM, NS\_BL1U is used, the following must 349also be defined: 350 351- **#define : NS\_BL1U\_BASE** 352 353 Defines the base address in non-secure ROM where NS\_BL1U executes. 354 Must be aligned on a page-size boundary. 355 NOTE: TF-A does not provide source code for this image. 356 357- **#define : NS\_BL1U\_IMAGE\_ID** 358 359 NS\_BL1U image identifier, used by BL1 to fetch an image descriptor 360 corresponding to NS\_BL1U. 361 362If the Non-Secure Firmware Updater, NS\_BL2U is used, the following must also 363be defined: 364 365- **#define : NS\_BL2U\_BASE** 366 367 Defines the base address in non-secure memory where NS\_BL2U executes. 368 Must be aligned on a page-size boundary. 369 NOTE: TF-A does not provide source code for this image. 370 371- **#define : NS\_BL2U\_IMAGE\_ID** 372 373 NS\_BL2U image identifier, used by BL1 to fetch an image descriptor 374 corresponding to NS\_BL2U. 375 376For the the Firmware update capability of TRUSTED BOARD BOOT, the following 377macros may also be defined: 378 379- **#define : PLAT\_FWU\_MAX\_SIMULTANEOUS\_IMAGES** 380 381 Total number of images that can be loaded simultaneously. If the platform 382 doesn't specify any value, it defaults to 10. 383 384If a SCP\_BL2 image is supported by the platform, the following constants must 385also be defined: 386 387- **#define : SCP\_BL2\_IMAGE\_ID** 388 389 SCP\_BL2 image identifier, used by BL2 to load SCP\_BL2 into secure memory 390 from platform storage before being transfered to the SCP. 391 392- **#define : SCP\_FW\_KEY\_CERT\_ID** 393 394 SCP\_BL2 key certificate identifier, used by BL2 to load the SCP\_BL2 key 395 certificate (mandatory when Trusted Board Boot is enabled). 396 397- **#define : SCP\_FW\_CONTENT\_CERT\_ID** 398 399 SCP\_BL2 content certificate identifier, used by BL2 to load the SCP\_BL2 400 content certificate (mandatory when Trusted Board Boot is enabled). 401 402If a BL32 image is supported by the platform, the following constants must 403also be defined: 404 405- **#define : BL32\_IMAGE\_ID** 406 407 BL32 image identifier, used by BL2 to load BL32. 408 409- **#define : TRUSTED\_OS\_FW\_KEY\_CERT\_ID** 410 411 BL32 key certificate identifier, used by BL2 to load the BL32 key 412 certificate (mandatory when Trusted Board Boot is enabled). 413 414- **#define : TRUSTED\_OS\_FW\_CONTENT\_CERT\_ID** 415 416 BL32 content certificate identifier, used by BL2 to load the BL32 content 417 certificate (mandatory when Trusted Board Boot is enabled). 418 419- **#define : BL32\_BASE** 420 421 Defines the base address in secure memory where BL2 loads the BL32 binary 422 image. Must be aligned on a page-size boundary. 423 424- **#define : BL32\_LIMIT** 425 426 Defines the maximum address that the BL32 image can occupy. 427 428If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the 429platform, the following constants must also be defined: 430 431- **#define : TSP\_SEC\_MEM\_BASE** 432 433 Defines the base address of the secure memory used by the TSP image on the 434 platform. This must be at the same address or below ``BL32_BASE``. 435 436- **#define : TSP\_SEC\_MEM\_SIZE** 437 438 Defines the size of the secure memory used by the BL32 image on the 439 platform. ``TSP_SEC_MEM_BASE`` and ``TSP_SEC_MEM_SIZE`` must fully accomodate 440 the memory required by the BL32 image, defined by ``BL32_BASE`` and 441 ``BL32_LIMIT``. 442 443- **#define : TSP\_IRQ\_SEC\_PHY\_TIMER** 444 445 Defines the ID of the secure physical generic timer interrupt used by the 446 TSP's interrupt handling code. 447 448If the platform port uses the translation table library code, the following 449constants must also be defined: 450 451- **#define : PLAT\_XLAT\_TABLES\_DYNAMIC** 452 453 Optional flag that can be set per-image to enable the dynamic allocation of 454 regions even when the MMU is enabled. If not defined, only static 455 functionality will be available, if defined and set to 1 it will also 456 include the dynamic functionality. 457 458- **#define : MAX\_XLAT\_TABLES** 459 460 Defines the maximum number of translation tables that are allocated by the 461 translation table library code. To minimize the amount of runtime memory 462 used, choose the smallest value needed to map the required virtual addresses 463 for each BL stage. If ``PLAT_XLAT_TABLES_DYNAMIC`` flag is enabled for a BL 464 image, ``MAX_XLAT_TABLES`` must be defined to accommodate the dynamic regions 465 as well. 466 467- **#define : MAX\_MMAP\_REGIONS** 468 469 Defines the maximum number of regions that are allocated by the translation 470 table library code. A region consists of physical base address, virtual base 471 address, size and attributes (Device/Memory, RO/RW, Secure/Non-Secure), as 472 defined in the ``mmap_region_t`` structure. The platform defines the regions 473 that should be mapped. Then, the translation table library will create the 474 corresponding tables and descriptors at runtime. To minimize the amount of 475 runtime memory used, choose the smallest value needed to register the 476 required regions for each BL stage. If ``PLAT_XLAT_TABLES_DYNAMIC`` flag is 477 enabled for a BL image, ``MAX_MMAP_REGIONS`` must be defined to accommodate 478 the dynamic regions as well. 479 480- **#define : PLAT\_VIRT\_ADDR\_SPACE\_SIZE** 481 482 Defines the total size of the virtual address space in bytes. For example, 483 for a 32 bit virtual address space, this value should be ``(1ULL << 32)``. 484 485- **#define : PLAT\_PHY\_ADDR\_SPACE\_SIZE** 486 487 Defines the total size of the physical address space in bytes. For example, 488 for a 32 bit physical address space, this value should be ``(1ULL << 32)``. 489 490If the platform port uses the IO storage framework, the following constants 491must also be defined: 492 493- **#define : MAX\_IO\_DEVICES** 494 495 Defines the maximum number of registered IO devices. Attempting to register 496 more devices than this value using ``io_register_device()`` will fail with 497 -ENOMEM. 498 499- **#define : MAX\_IO\_HANDLES** 500 501 Defines the maximum number of open IO handles. Attempting to open more IO 502 entities than this value using ``io_open()`` will fail with -ENOMEM. 503 504- **#define : MAX\_IO\_BLOCK\_DEVICES** 505 506 Defines the maximum number of registered IO block devices. Attempting to 507 register more devices this value using ``io_dev_open()`` will fail 508 with -ENOMEM. MAX\_IO\_BLOCK\_DEVICES should be less than MAX\_IO\_DEVICES. 509 With this macro, multiple block devices could be supported at the same 510 time. 511 512If the platform needs to allocate data within the per-cpu data framework in 513BL31, it should define the following macro. Currently this is only required if 514the platform decides not to use the coherent memory section by undefining the 515``USE_COHERENT_MEM`` build flag. In this case, the framework allocates the 516required memory within the the per-cpu data to minimize wastage. 517 518- **#define : PLAT\_PCPU\_DATA\_SIZE** 519 520 Defines the memory (in bytes) to be reserved within the per-cpu data 521 structure for use by the platform layer. 522 523The following constants are optional. They should be defined when the platform 524memory layout implies some image overlaying like in Arm standard platforms. 525 526- **#define : BL31\_PROGBITS\_LIMIT** 527 528 Defines the maximum address in secure RAM that the BL31's progbits sections 529 can occupy. 530 531- **#define : TSP\_PROGBITS\_LIMIT** 532 533 Defines the maximum address that the TSP's progbits sections can occupy. 534 535If the platform port uses the PL061 GPIO driver, the following constant may 536optionally be defined: 537 538- **PLAT\_PL061\_MAX\_GPIOS** 539 Maximum number of GPIOs required by the platform. This allows control how 540 much memory is allocated for PL061 GPIO controllers. The default value is 541 542 #. $(eval $(call add\_define,PLAT\_PL061\_MAX\_GPIOS)) 543 544If the platform port uses the partition driver, the following constant may 545optionally be defined: 546 547- **PLAT\_PARTITION\_MAX\_ENTRIES** 548 Maximum number of partition entries required by the platform. This allows 549 control how much memory is allocated for partition entries. The default 550 value is 128. 551 `For example, define the build flag in platform.mk`_: 552 PLAT\_PARTITION\_MAX\_ENTRIES := 12 553 $(eval $(call add\_define,PLAT\_PARTITION\_MAX\_ENTRIES)) 554 555The following constant is optional. It should be defined to override the default 556behaviour of the ``assert()`` function (for example, to save memory). 557 558- **PLAT\_LOG\_LEVEL\_ASSERT** 559 If ``PLAT_LOG_LEVEL_ASSERT`` is higher or equal than ``LOG_LEVEL_VERBOSE``, 560 ``assert()`` prints the name of the file, the line number and the asserted 561 expression. Else if it is higher than ``LOG_LEVEL_INFO``, it prints the file 562 name and the line number. Else if it is lower than ``LOG_LEVEL_INFO``, it 563 doesn't print anything to the console. If ``PLAT_LOG_LEVEL_ASSERT`` isn't 564 defined, it defaults to ``LOG_LEVEL``. 565 566If the platform port uses the Activity Monitor Unit, the following constants 567may be defined: 568 569- **PLAT\_AMU\_GROUP1\_COUNTERS\_MASK** 570 This mask reflects the set of group counters that should be enabled. The 571 maximum number of group 1 counters supported by AMUv1 is 16 so the mask 572 can be at most 0xffff. If the platform does not define this mask, no group 1 573 counters are enabled. If the platform defines this mask, the following 574 constant needs to also be defined. 575 576- **PLAT\_AMU\_GROUP1\_NR\_COUNTERS** 577 This value is used to allocate an array to save and restore the counters 578 specified by ``PLAT_AMU_GROUP1_COUNTERS_MASK`` on CPU suspend. 579 This value should be equal to the highest bit position set in the 580 mask, plus 1. The maximum number of group 1 counters in AMUv1 is 16. 581 582File : plat\_macros.S [mandatory] 583~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 584 585Each platform must ensure a file of this name is in the system include path with 586the following macro defined. In the Arm development platforms, this file is 587found in ``plat/arm/board/<plat_name>/include/plat_macros.S``. 588 589- **Macro : plat\_crash\_print\_regs** 590 591 This macro allows the crash reporting routine to print relevant platform 592 registers in case of an unhandled exception in BL31. This aids in debugging 593 and this macro can be defined to be empty in case register reporting is not 594 desired. 595 596 For instance, GIC or interconnect registers may be helpful for 597 troubleshooting. 598 599Handling Reset 600-------------- 601 602BL1 by default implements the reset vector where execution starts from a cold 603or warm boot. BL31 can be optionally set as a reset vector using the 604``RESET_TO_BL31`` make variable. 605 606For each CPU, the reset vector code is responsible for the following tasks: 607 608#. Distinguishing between a cold boot and a warm boot. 609 610#. In the case of a cold boot and the CPU being a secondary CPU, ensuring that 611 the CPU is placed in a platform-specific state until the primary CPU 612 performs the necessary steps to remove it from this state. 613 614#. In the case of a warm boot, ensuring that the CPU jumps to a platform- 615 specific address in the BL31 image in the same processor mode as it was 616 when released from reset. 617 618The following functions need to be implemented by the platform port to enable 619reset vector code to perform the above tasks. 620 621Function : plat\_get\_my\_entrypoint() [mandatory when PROGRAMMABLE\_RESET\_ADDRESS == 0] 622~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 623 624:: 625 626 Argument : void 627 Return : uintptr_t 628 629This function is called with the MMU and caches disabled 630(``SCTLR_EL3.M`` = 0 and ``SCTLR_EL3.C`` = 0). The function is responsible for 631distinguishing between a warm and cold reset for the current CPU using 632platform-specific means. If it's a warm reset, then it returns the warm 633reset entrypoint point provided to ``plat_setup_psci_ops()`` during 634BL31 initialization. If it's a cold reset then this function must return zero. 635 636This function does not follow the Procedure Call Standard used by the 637Application Binary Interface for the Arm 64-bit architecture. The caller should 638not assume that callee saved registers are preserved across a call to this 639function. 640 641This function fulfills requirement 1 and 3 listed above. 642 643Note that for platforms that support programming the reset address, it is 644expected that a CPU will start executing code directly at the right address, 645both on a cold and warm reset. In this case, there is no need to identify the 646type of reset nor to query the warm reset entrypoint. Therefore, implementing 647this function is not required on such platforms. 648 649Function : plat\_secondary\_cold\_boot\_setup() [mandatory when COLD\_BOOT\_SINGLE\_CPU == 0] 650~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 651 652:: 653 654 Argument : void 655 656This function is called with the MMU and data caches disabled. It is responsible 657for placing the executing secondary CPU in a platform-specific state until the 658primary CPU performs the necessary actions to bring it out of that state and 659allow entry into the OS. This function must not return. 660 661In the Arm FVP port, when using the normal boot flow, each secondary CPU powers 662itself off. The primary CPU is responsible for powering up the secondary CPUs 663when normal world software requires them. When booting an EL3 payload instead, 664they stay powered on and are put in a holding pen until their mailbox gets 665populated. 666 667This function fulfills requirement 2 above. 668 669Note that for platforms that can't release secondary CPUs out of reset, only the 670primary CPU will execute the cold boot code. Therefore, implementing this 671function is not required on such platforms. 672 673Function : plat\_is\_my\_cpu\_primary() [mandatory when COLD\_BOOT\_SINGLE\_CPU == 0] 674~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 675 676:: 677 678 Argument : void 679 Return : unsigned int 680 681This function identifies whether the current CPU is the primary CPU or a 682secondary CPU. A return value of zero indicates that the CPU is not the 683primary CPU, while a non-zero return value indicates that the CPU is the 684primary CPU. 685 686Note that for platforms that can't release secondary CPUs out of reset, only the 687primary CPU will execute the cold boot code. Therefore, there is no need to 688distinguish between primary and secondary CPUs and implementing this function is 689not required. 690 691Function : platform\_mem\_init() [mandatory] 692~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 693 694:: 695 696 Argument : void 697 Return : void 698 699This function is called before any access to data is made by the firmware, in 700order to carry out any essential memory initialization. 701 702Function: plat\_get\_rotpk\_info() 703~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 704 705:: 706 707 Argument : void *, void **, unsigned int *, unsigned int * 708 Return : int 709 710This function is mandatory when Trusted Board Boot is enabled. It returns a 711pointer to the ROTPK stored in the platform (or a hash of it) and its length. 712The ROTPK must be encoded in DER format according to the following ASN.1 713structure: 714 715:: 716 717 AlgorithmIdentifier ::= SEQUENCE { 718 algorithm OBJECT IDENTIFIER, 719 parameters ANY DEFINED BY algorithm OPTIONAL 720 } 721 722 SubjectPublicKeyInfo ::= SEQUENCE { 723 algorithm AlgorithmIdentifier, 724 subjectPublicKey BIT STRING 725 } 726 727In case the function returns a hash of the key: 728 729:: 730 731 DigestInfo ::= SEQUENCE { 732 digestAlgorithm AlgorithmIdentifier, 733 digest OCTET STRING 734 } 735 736The function returns 0 on success. Any other value is treated as error by the 737Trusted Board Boot. The function also reports extra information related 738to the ROTPK in the flags parameter: 739 740:: 741 742 ROTPK_IS_HASH : Indicates that the ROTPK returned by the platform is a 743 hash. 744 ROTPK_NOT_DEPLOYED : This allows the platform to skip certificate ROTPK 745 verification while the platform ROTPK is not deployed. 746 When this flag is set, the function does not need to 747 return a platform ROTPK, and the authentication 748 framework uses the ROTPK in the certificate without 749 verifying it against the platform value. This flag 750 must not be used in a deployed production environment. 751 752Function: plat\_get\_nv\_ctr() 753~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 754 755:: 756 757 Argument : void *, unsigned int * 758 Return : int 759 760This function is mandatory when Trusted Board Boot is enabled. It returns the 761non-volatile counter value stored in the platform in the second argument. The 762cookie in the first argument may be used to select the counter in case the 763platform provides more than one (for example, on platforms that use the default 764TBBR CoT, the cookie will correspond to the OID values defined in 765TRUSTED\_FW\_NVCOUNTER\_OID or NON\_TRUSTED\_FW\_NVCOUNTER\_OID). 766 767The function returns 0 on success. Any other value means the counter value could 768not be retrieved from the platform. 769 770Function: plat\_set\_nv\_ctr() 771~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 772 773:: 774 775 Argument : void *, unsigned int 776 Return : int 777 778This function is mandatory when Trusted Board Boot is enabled. It sets a new 779counter value in the platform. The cookie in the first argument may be used to 780select the counter (as explained in plat\_get\_nv\_ctr()). The second argument is 781the updated counter value to be written to the NV counter. 782 783The function returns 0 on success. Any other value means the counter value could 784not be updated. 785 786Function: plat\_set\_nv\_ctr2() 787~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 788 789:: 790 791 Argument : void *, const auth_img_desc_t *, unsigned int 792 Return : int 793 794This function is optional when Trusted Board Boot is enabled. If this 795interface is defined, then ``plat_set_nv_ctr()`` need not be defined. The 796first argument passed is a cookie and is typically used to 797differentiate between a Non Trusted NV Counter and a Trusted NV 798Counter. The second argument is a pointer to an authentication image 799descriptor and may be used to decide if the counter is allowed to be 800updated or not. The third argument is the updated counter value to 801be written to the NV counter. 802 803The function returns 0 on success. Any other value means the counter value 804either could not be updated or the authentication image descriptor indicates 805that it is not allowed to be updated. 806 807Common mandatory function modifications 808--------------------------------------- 809 810The following functions are mandatory functions which need to be implemented 811by the platform port. 812 813Function : plat\_my\_core\_pos() 814~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 815 816:: 817 818 Argument : void 819 Return : unsigned int 820 821This funtion returns the index of the calling CPU which is used as a 822CPU-specific linear index into blocks of memory (for example while allocating 823per-CPU stacks). This function will be invoked very early in the 824initialization sequence which mandates that this function should be 825implemented in assembly and should not rely on the avalability of a C 826runtime environment. This function can clobber x0 - x8 and must preserve 827x9 - x29. 828 829This function plays a crucial role in the power domain topology framework in 830PSCI and details of this can be found in `Power Domain Topology Design`_. 831 832Function : plat\_core\_pos\_by\_mpidr() 833~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 834 835:: 836 837 Argument : u_register_t 838 Return : int 839 840This function validates the ``MPIDR`` of a CPU and converts it to an index, 841which can be used as a CPU-specific linear index into blocks of memory. In 842case the ``MPIDR`` is invalid, this function returns -1. This function will only 843be invoked by BL31 after the power domain topology is initialized and can 844utilize the C runtime environment. For further details about how TF-A 845represents the power domain topology and how this relates to the linear CPU 846index, please refer `Power Domain Topology Design`_. 847 848Common optional modifications 849----------------------------- 850 851The following are helper functions implemented by the firmware that perform 852common platform-specific tasks. A platform may choose to override these 853definitions. 854 855Function : plat\_set\_my\_stack() 856~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 857 858:: 859 860 Argument : void 861 Return : void 862 863This function sets the current stack pointer to the normal memory stack that 864has been allocated for the current CPU. For BL images that only require a 865stack for the primary CPU, the UP version of the function is used. The size 866of the stack allocated to each CPU is specified by the platform defined 867constant ``PLATFORM_STACK_SIZE``. 868 869Common implementations of this function for the UP and MP BL images are 870provided in `plat/common/aarch64/platform\_up\_stack.S`_ and 871`plat/common/aarch64/platform\_mp\_stack.S`_ 872 873Function : plat\_get\_my\_stack() 874~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 875 876:: 877 878 Argument : void 879 Return : uintptr_t 880 881This function returns the base address of the normal memory stack that 882has been allocated for the current CPU. For BL images that only require a 883stack for the primary CPU, the UP version of the function is used. The size 884of the stack allocated to each CPU is specified by the platform defined 885constant ``PLATFORM_STACK_SIZE``. 886 887Common implementations of this function for the UP and MP BL images are 888provided in `plat/common/aarch64/platform\_up\_stack.S`_ and 889`plat/common/aarch64/platform\_mp\_stack.S`_ 890 891Function : plat\_report\_exception() 892~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 893 894:: 895 896 Argument : unsigned int 897 Return : void 898 899A platform may need to report various information about its status when an 900exception is taken, for example the current exception level, the CPU security 901state (secure/non-secure), the exception type, and so on. This function is 902called in the following circumstances: 903 904- In BL1, whenever an exception is taken. 905- In BL2, whenever an exception is taken. 906 907The default implementation doesn't do anything, to avoid making assumptions 908about the way the platform displays its status information. 909 910For AArch64, this function receives the exception type as its argument. 911Possible values for exceptions types are listed in the 912`include/common/bl\_common.h`_ header file. Note that these constants are not 913related to any architectural exception code; they are just a TF-A convention. 914 915For AArch32, this function receives the exception mode as its argument. 916Possible values for exception modes are listed in the 917`include/lib/aarch32/arch.h`_ header file. 918 919Function : plat\_reset\_handler() 920~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 921 922:: 923 924 Argument : void 925 Return : void 926 927A platform may need to do additional initialization after reset. This function 928allows the platform to do the platform specific intializations. Platform 929specific errata workarounds could also be implemented here. The api should 930preserve the values of callee saved registers x19 to x29. 931 932The default implementation doesn't do anything. If a platform needs to override 933the default implementation, refer to the `Firmware Design`_ for general 934guidelines. 935 936Function : plat\_disable\_acp() 937~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 938 939:: 940 941 Argument : void 942 Return : void 943 944This API allows a platform to disable the Accelerator Coherency Port (if 945present) during a cluster power down sequence. The default weak implementation 946doesn't do anything. Since this API is called during the power down sequence, 947it has restrictions for stack usage and it can use the registers x0 - x17 as 948scratch registers. It should preserve the value in x18 register as it is used 949by the caller to store the return address. 950 951Function : plat\_error\_handler() 952~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 953 954:: 955 956 Argument : int 957 Return : void 958 959This API is called when the generic code encounters an error situation from 960which it cannot continue. It allows the platform to perform error reporting or 961recovery actions (for example, reset the system). This function must not return. 962 963The parameter indicates the type of error using standard codes from ``errno.h``. 964Possible errors reported by the generic code are: 965 966- ``-EAUTH``: a certificate or image could not be authenticated (when Trusted 967 Board Boot is enabled) 968- ``-ENOENT``: the requested image or certificate could not be found or an IO 969 error was detected 970- ``-ENOMEM``: resources exhausted. TF-A does not use dynamic memory, so this 971 error is usually an indication of an incorrect array size 972 973The default implementation simply spins. 974 975Function : plat\_panic\_handler() 976~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 977 978:: 979 980 Argument : void 981 Return : void 982 983This API is called when the generic code encounters an unexpected error 984situation from which it cannot recover. This function must not return, 985and must be implemented in assembly because it may be called before the C 986environment is initialized. 987 988Note: The address from where it was called is stored in x30 (Link Register). 989The default implementation simply spins. 990 991Function : plat\_get\_bl\_image\_load\_info() 992~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 993 994:: 995 996 Argument : void 997 Return : bl_load_info_t * 998 999This function returns pointer to the list of images that the platform has 1000populated to load. This function is currently invoked in BL2 to load the 1001BL3xx images, when LOAD\_IMAGE\_V2 is enabled. 1002 1003Function : plat\_get\_next\_bl\_params() 1004~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1005 1006:: 1007 1008 Argument : void 1009 Return : bl_params_t * 1010 1011This function returns a pointer to the shared memory that the platform has 1012kept aside to pass TF-A related information that next BL image needs. This 1013function is currently invoked in BL2 to pass this information to the next BL 1014image, when LOAD\_IMAGE\_V2 is enabled. 1015 1016Function : plat\_get\_stack\_protector\_canary() 1017~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1018 1019:: 1020 1021 Argument : void 1022 Return : u_register_t 1023 1024This function returns a random value that is used to initialize the canary used 1025when the stack protector is enabled with ENABLE\_STACK\_PROTECTOR. A predictable 1026value will weaken the protection as the attacker could easily write the right 1027value as part of the attack most of the time. Therefore, it should return a 1028true random number. 1029 1030Note: For the protection to be effective, the global data need to be placed at 1031a lower address than the stack bases. Failure to do so would allow an attacker 1032to overwrite the canary as part of the stack buffer overflow attack. 1033 1034Function : plat\_flush\_next\_bl\_params() 1035~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1036 1037:: 1038 1039 Argument : void 1040 Return : void 1041 1042This function flushes to main memory all the image params that are passed to 1043next image. This function is currently invoked in BL2 to flush this information 1044to the next BL image, when LOAD\_IMAGE\_V2 is enabled. 1045 1046Function : plat\_log\_get\_prefix() 1047~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1048 1049:: 1050 1051 Argument : unsigned int 1052 Return : const char * 1053 1054This function defines the prefix string corresponding to the `log_level` to be 1055prepended to all the log output from TF-A. The `log_level` (argument) will 1056correspond to one of the standard log levels defined in debug.h. The platform 1057can override the common implementation to define a different prefix string for 1058the log output. The implementation should be robust to future changes that 1059increase the number of log levels. 1060 1061Function : plat\_get\_mbedtls\_heap() 1062~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1063 1064:: 1065 1066 Arguments : void **heap_addr, size_t *heap_size 1067 Return : int 1068 1069This function is invoked during Mbed TLS library initialisation to get 1070a heap, by means of a starting address and a size. This heap will then be used 1071internally by the Mbed TLS library. The heap is requested from the current BL 1072stage, i.e. the current BL image inside which Mbed TLS is used. 1073 1074In the default implementation a heap is statically allocated inside every image 1075(i.e. every BL stage) that utilises Mbed TLS. So, in this case, the function 1076simply returns the address and size of this "pre-allocated" heap. However, by 1077overriding the default implementation, platforms have the potential to optimise 1078memory usage. For example, on some Arm platforms, the Mbed TLS heap is shared 1079between BL1 and BL2 stages and, thus, the necessary space is not reserved 1080twice. 1081 1082On success the function should return 0 and a negative error code otherwise. 1083 1084Modifications specific to a Boot Loader stage 1085--------------------------------------------- 1086 1087Boot Loader Stage 1 (BL1) 1088------------------------- 1089 1090BL1 implements the reset vector where execution starts from after a cold or 1091warm boot. For each CPU, BL1 is responsible for the following tasks: 1092 1093#. Handling the reset as described in section 2.2 1094 1095#. In the case of a cold boot and the CPU being the primary CPU, ensuring that 1096 only this CPU executes the remaining BL1 code, including loading and passing 1097 control to the BL2 stage. 1098 1099#. Identifying and starting the Firmware Update process (if required). 1100 1101#. Loading the BL2 image from non-volatile storage into secure memory at the 1102 address specified by the platform defined constant ``BL2_BASE``. 1103 1104#. Populating a ``meminfo`` structure with the following information in memory, 1105 accessible by BL2 immediately upon entry. 1106 1107 :: 1108 1109 meminfo.total_base = Base address of secure RAM visible to BL2 1110 meminfo.total_size = Size of secure RAM visible to BL2 1111 meminfo.free_base = Base address of secure RAM available for 1112 allocation to BL2 1113 meminfo.free_size = Size of secure RAM available for allocation to BL2 1114 1115 By default, BL1 places this ``meminfo`` structure at the beginning of the 1116 free memory available for its use. Since BL1 cannot allocate memory 1117 dynamically at the moment, its free memory will be available for BL2's use 1118 as-is. However, this means that BL2 must read the ``meminfo`` structure 1119 before it starts using its free memory (this is discussed in Section 3.2). 1120 1121 It is possible for the platform to decide where it wants to place the 1122 ``meminfo`` structure for BL2 or restrict the amount of memory visible to 1123 BL2 by overriding the weak default implementation of 1124 ``bl1_plat_handle_post_image_load`` API. 1125 1126The following functions need to be implemented by the platform port to enable 1127BL1 to perform the above tasks. 1128 1129Function : bl1\_early\_platform\_setup() [mandatory] 1130~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1131 1132:: 1133 1134 Argument : void 1135 Return : void 1136 1137This function executes with the MMU and data caches disabled. It is only called 1138by the primary CPU. 1139 1140On Arm standard platforms, this function: 1141 1142- Enables a secure instance of SP805 to act as the Trusted Watchdog. 1143 1144- Initializes a UART (PL011 console), which enables access to the ``printf`` 1145 family of functions in BL1. 1146 1147- Enables issuing of snoop and DVM (Distributed Virtual Memory) requests to 1148 the CCI slave interface corresponding to the cluster that includes the 1149 primary CPU. 1150 1151Function : bl1\_plat\_arch\_setup() [mandatory] 1152~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1153 1154:: 1155 1156 Argument : void 1157 Return : void 1158 1159This function performs any platform-specific and architectural setup that the 1160platform requires. Platform-specific setup might include configuration of 1161memory controllers and the interconnect. 1162 1163In Arm standard platforms, this function enables the MMU. 1164 1165This function helps fulfill requirement 2 above. 1166 1167Function : bl1\_platform\_setup() [mandatory] 1168~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1169 1170:: 1171 1172 Argument : void 1173 Return : void 1174 1175This function executes with the MMU and data caches enabled. It is responsible 1176for performing any remaining platform-specific setup that can occur after the 1177MMU and data cache have been enabled. 1178 1179if support for multiple boot sources is required, it initializes the boot 1180sequence used by plat\_try\_next\_boot\_source(). 1181 1182In Arm standard platforms, this function initializes the storage abstraction 1183layer used to load the next bootloader image. 1184 1185This function helps fulfill requirement 4 above. 1186 1187Function : bl1\_plat\_sec\_mem\_layout() [mandatory] 1188~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1189 1190:: 1191 1192 Argument : void 1193 Return : meminfo * 1194 1195This function should only be called on the cold boot path. It executes with the 1196MMU and data caches enabled. The pointer returned by this function must point to 1197a ``meminfo`` structure containing the extents and availability of secure RAM for 1198the BL1 stage. 1199 1200:: 1201 1202 meminfo.total_base = Base address of secure RAM visible to BL1 1203 meminfo.total_size = Size of secure RAM visible to BL1 1204 meminfo.free_base = Base address of secure RAM available for allocation 1205 to BL1 1206 meminfo.free_size = Size of secure RAM available for allocation to BL1 1207 1208This information is used by BL1 to load the BL2 image in secure RAM. BL1 also 1209populates a similar structure to tell BL2 the extents of memory available for 1210its own use. 1211 1212This function helps fulfill requirements 4 and 5 above. 1213 1214Function : bl1\_plat\_prepare\_exit() [optional] 1215~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1216 1217:: 1218 1219 Argument : entry_point_info_t * 1220 Return : void 1221 1222This function is called prior to exiting BL1 in response to the 1223``BL1_SMC_RUN_IMAGE`` SMC request raised by BL2. It should be used to perform 1224platform specific clean up or bookkeeping operations before transferring 1225control to the next image. It receives the address of the ``entry_point_info_t`` 1226structure passed from BL2. This function runs with MMU disabled. 1227 1228Function : bl1\_plat\_set\_ep\_info() [optional] 1229~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1230 1231:: 1232 1233 Argument : unsigned int image_id, entry_point_info_t *ep_info 1234 Return : void 1235 1236This function allows platforms to override ``ep_info`` for the given ``image_id``. 1237 1238The default implementation just returns. 1239 1240Function : bl1\_plat\_get\_next\_image\_id() [optional] 1241~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1242 1243:: 1244 1245 Argument : void 1246 Return : unsigned int 1247 1248This and the following function must be overridden to enable the FWU feature. 1249 1250BL1 calls this function after platform setup to identify the next image to be 1251loaded and executed. If the platform returns ``BL2_IMAGE_ID`` then BL1 proceeds 1252with the normal boot sequence, which loads and executes BL2. If the platform 1253returns a different image id, BL1 assumes that Firmware Update is required. 1254 1255The default implementation always returns ``BL2_IMAGE_ID``. The Arm development 1256platforms override this function to detect if firmware update is required, and 1257if so, return the first image in the firmware update process. 1258 1259Function : bl1\_plat\_get\_image\_desc() [optional] 1260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1261 1262:: 1263 1264 Argument : unsigned int image_id 1265 Return : image_desc_t * 1266 1267BL1 calls this function to get the image descriptor information ``image_desc_t`` 1268for the provided ``image_id`` from the platform. 1269 1270The default implementation always returns a common BL2 image descriptor. Arm 1271standard platforms return an image descriptor corresponding to BL2 or one of 1272the firmware update images defined in the Trusted Board Boot Requirements 1273specification. 1274 1275Function : bl1\_plat\_handle\_pre\_image\_load() [optional] 1276~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1277 1278:: 1279 1280 Argument : unsigned int image_id 1281 Return : int 1282 1283This function can be used by the platforms to update/use image information 1284corresponding to ``image_id``. This function is invoked in BL1, both in cold 1285boot and FWU code path, before loading the image. 1286 1287Function : bl1\_plat\_handle\_post\_image\_load() [optional] 1288~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1289 1290:: 1291 1292 Argument : unsigned int image_id 1293 Return : int 1294 1295This function can be used by the platforms to update/use image information 1296corresponding to ``image_id``. This function is invoked in BL1, both in cold 1297boot and FWU code path, after loading and authenticating the image. 1298 1299The default weak implementation of this function calculates the amount of 1300Trusted SRAM that can be used by BL2 and allocates a ``meminfo_t`` 1301structure at the beginning of this free memory and populates it. The address 1302of ``meminfo_t`` structure is updated in ``arg1`` of the entrypoint 1303information to BL2. 1304 1305Function : bl1\_plat\_fwu\_done() [optional] 1306~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1307 1308:: 1309 1310 Argument : unsigned int image_id, uintptr_t image_src, 1311 unsigned int image_size 1312 Return : void 1313 1314BL1 calls this function when the FWU process is complete. It must not return. 1315The platform may override this function to take platform specific action, for 1316example to initiate the normal boot flow. 1317 1318The default implementation spins forever. 1319 1320Function : bl1\_plat\_mem\_check() [mandatory] 1321~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1322 1323:: 1324 1325 Argument : uintptr_t mem_base, unsigned int mem_size, 1326 unsigned int flags 1327 Return : int 1328 1329BL1 calls this function while handling FWU related SMCs, more specifically when 1330copying or authenticating an image. Its responsibility is to ensure that the 1331region of memory identified by ``mem_base`` and ``mem_size`` is mapped in BL1, and 1332that this memory corresponds to either a secure or non-secure memory region as 1333indicated by the security state of the ``flags`` argument. 1334 1335This function can safely assume that the value resulting from the addition of 1336``mem_base`` and ``mem_size`` fits into a ``uintptr_t`` type variable and does not 1337overflow. 1338 1339This function must return 0 on success, a non-null error code otherwise. 1340 1341The default implementation of this function asserts therefore platforms must 1342override it when using the FWU feature. 1343 1344Boot Loader Stage 2 (BL2) 1345------------------------- 1346 1347The BL2 stage is executed only by the primary CPU, which is determined in BL1 1348using the ``platform_is_primary_cpu()`` function. BL1 passed control to BL2 at 1349``BL2_BASE``. BL2 executes in Secure EL1 and is responsible for: 1350 1351#. (Optional) Loading the SCP\_BL2 binary image (if present) from platform 1352 provided non-volatile storage. To load the SCP\_BL2 image, BL2 makes use of 1353 the ``meminfo`` returned by the ``bl2_plat_get_scp_bl2_meminfo()`` function. 1354 The platform also defines the address in memory where SCP\_BL2 is loaded 1355 through the optional constant ``SCP_BL2_BASE``. BL2 uses this information 1356 to determine if there is enough memory to load the SCP\_BL2 image. 1357 Subsequent handling of the SCP\_BL2 image is platform-specific and is 1358 implemented in the ``bl2_plat_handle_scp_bl2()`` function. 1359 If ``SCP_BL2_BASE`` is not defined then this step is not performed. 1360 1361#. Loading the BL31 binary image into secure RAM from non-volatile storage. To 1362 load the BL31 image, BL2 makes use of the ``meminfo`` structure passed to it 1363 by BL1. This structure allows BL2 to calculate how much secure RAM is 1364 available for its use. The platform also defines the address in secure RAM 1365 where BL31 is loaded through the constant ``BL31_BASE``. BL2 uses this 1366 information to determine if there is enough memory to load the BL31 image. 1367 1368#. (Optional) Loading the BL32 binary image (if present) from platform 1369 provided non-volatile storage. To load the BL32 image, BL2 makes use of 1370 the ``meminfo`` returned by the ``bl2_plat_get_bl32_meminfo()`` function. 1371 The platform also defines the address in memory where BL32 is loaded 1372 through the optional constant ``BL32_BASE``. BL2 uses this information 1373 to determine if there is enough memory to load the BL32 image. 1374 If ``BL32_BASE`` is not defined then this and the next step is not performed. 1375 1376#. (Optional) Arranging to pass control to the BL32 image (if present) that 1377 has been pre-loaded at ``BL32_BASE``. BL2 populates an ``entry_point_info`` 1378 structure in memory provided by the platform with information about how 1379 BL31 should pass control to the BL32 image. 1380 1381#. (Optional) Loading the normal world BL33 binary image (if not loaded by 1382 other means) into non-secure DRAM from platform storage and arranging for 1383 BL31 to pass control to this image. This address is determined using the 1384 ``plat_get_ns_image_entrypoint()`` function described below. 1385 1386#. BL2 populates an ``entry_point_info`` structure in memory provided by the 1387 platform with information about how BL31 should pass control to the 1388 other BL images. 1389 1390The following functions must be implemented by the platform port to enable BL2 1391to perform the above tasks. 1392 1393Function : bl2\_early\_platform\_setup() [mandatory] 1394~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1395 1396:: 1397 1398 Argument : meminfo * 1399 Return : void 1400 1401This function executes with the MMU and data caches disabled. It is only called 1402by the primary CPU. The arguments to this function is the address of the 1403``meminfo`` structure populated by BL1. 1404 1405The platform may copy the contents of the ``meminfo`` structure into a private 1406variable as the original memory may be subsequently overwritten by BL2. The 1407copied structure is made available to all BL2 code through the 1408``bl2_plat_sec_mem_layout()`` function. 1409 1410On Arm standard platforms, this function also: 1411 1412- Initializes a UART (PL011 console), which enables access to the ``printf`` 1413 family of functions in BL2. 1414 1415- Initializes the storage abstraction layer used to load further bootloader 1416 images. It is necessary to do this early on platforms with a SCP\_BL2 image, 1417 since the later ``bl2_platform_setup`` must be done after SCP\_BL2 is loaded. 1418 1419Function : bl2\_plat\_arch\_setup() [mandatory] 1420~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1421 1422:: 1423 1424 Argument : void 1425 Return : void 1426 1427This function executes with the MMU and data caches disabled. It is only called 1428by the primary CPU. 1429 1430The purpose of this function is to perform any architectural initialization 1431that varies across platforms. 1432 1433On Arm standard platforms, this function enables the MMU. 1434 1435Function : bl2\_platform\_setup() [mandatory] 1436~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1437 1438:: 1439 1440 Argument : void 1441 Return : void 1442 1443This function may execute with the MMU and data caches enabled if the platform 1444port does the necessary initialization in ``bl2_plat_arch_setup()``. It is only 1445called by the primary CPU. 1446 1447The purpose of this function is to perform any platform initialization 1448specific to BL2. 1449 1450In Arm standard platforms, this function performs security setup, including 1451configuration of the TrustZone controller to allow non-secure masters access 1452to most of DRAM. Part of DRAM is reserved for secure world use. 1453 1454Function : bl2\_plat\_sec\_mem\_layout() [mandatory] 1455~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1456 1457:: 1458 1459 Argument : void 1460 Return : meminfo * 1461 1462This function should only be called on the cold boot path. It may execute with 1463the MMU and data caches enabled if the platform port does the necessary 1464initialization in ``bl2_plat_arch_setup()``. It is only called by the primary CPU. 1465 1466The purpose of this function is to return a pointer to a ``meminfo`` structure 1467populated with the extents of secure RAM available for BL2 to use. See 1468``bl2_early_platform_setup()`` above. 1469 1470Following functions are optionally used only when LOAD\_IMAGE\_V2 is enabled. 1471 1472Function : bl2\_plat\_handle\_pre\_image\_load() [optional] 1473~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1474 1475:: 1476 1477 Argument : unsigned int 1478 Return : int 1479 1480This function can be used by the platforms to update/use image information 1481for given ``image_id``. This function is currently invoked in BL2 before 1482loading each image, when LOAD\_IMAGE\_V2 is enabled. 1483 1484Function : bl2\_plat\_handle\_post\_image\_load() [optional] 1485~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1486 1487:: 1488 1489 Argument : unsigned int 1490 Return : int 1491 1492This function can be used by the platforms to update/use image information 1493for given ``image_id``. This function is currently invoked in BL2 after 1494loading each image, when LOAD\_IMAGE\_V2 is enabled. 1495 1496Following functions are required only when LOAD\_IMAGE\_V2 is disabled. 1497 1498Function : bl2\_plat\_get\_scp\_bl2\_meminfo() [mandatory] 1499~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1500 1501:: 1502 1503 Argument : meminfo * 1504 Return : void 1505 1506This function is used to get the memory limits where BL2 can load the 1507SCP\_BL2 image. The meminfo provided by this is used by load\_image() to 1508validate whether the SCP\_BL2 image can be loaded within the given 1509memory from the given base. 1510 1511Function : bl2\_plat\_handle\_scp\_bl2() [mandatory] 1512~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1513 1514:: 1515 1516 Argument : image_info * 1517 Return : int 1518 1519This function is called after loading SCP\_BL2 image and it is used to perform 1520any platform-specific actions required to handle the SCP firmware. Typically it 1521transfers the image into SCP memory using a platform-specific protocol and waits 1522until SCP executes it and signals to the Application Processor (AP) for BL2 1523execution to continue. 1524 1525This function returns 0 on success, a negative error code otherwise. 1526 1527Function : bl2\_plat\_get\_bl31\_params() [mandatory] 1528~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1529 1530:: 1531 1532 Argument : void 1533 Return : bl31_params * 1534 1535BL2 platform code needs to return a pointer to a ``bl31_params`` structure it 1536will use for passing information to BL31. The ``bl31_params`` structure carries 1537the following information. 1538- Header describing the version information for interpreting the bl31\_param 1539structure 1540- Information about executing the BL33 image in the ``bl33_ep_info`` field 1541- Information about executing the BL32 image in the ``bl32_ep_info`` field 1542- Information about the type and extents of BL31 image in the 1543``bl31_image_info`` field 1544- Information about the type and extents of BL32 image in the 1545``bl32_image_info`` field 1546- Information about the type and extents of BL33 image in the 1547``bl33_image_info`` field 1548 1549The memory pointed by this structure and its sub-structures should be 1550accessible from BL31 initialisation code. BL31 might choose to copy the 1551necessary content, or maintain the structures until BL33 is initialised. 1552 1553Funtion : bl2\_plat\_get\_bl31\_ep\_info() [mandatory] 1554~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1555 1556:: 1557 1558 Argument : void 1559 Return : entry_point_info * 1560 1561BL2 platform code returns a pointer which is used to populate the entry point 1562information for BL31 entry point. The location pointed by it should be 1563accessible from BL1 while processing the synchronous exception to run to BL31. 1564 1565In Arm standard platforms this is allocated inside a bl2\_to\_bl31\_params\_mem 1566structure in BL2 memory. 1567 1568Function : bl2\_plat\_set\_bl31\_ep\_info() [mandatory] 1569~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1570 1571:: 1572 1573 Argument : image_info *, entry_point_info * 1574 Return : void 1575 1576In the normal boot flow, this function is called after loading BL31 image and 1577it can be used to overwrite the entry point set by loader and also set the 1578security state and SPSR which represents the entry point system state for BL31. 1579 1580When booting an EL3 payload instead, this function is called after populating 1581its entry point address and can be used for the same purpose for the payload 1582image. It receives a null pointer as its first argument in this case. 1583 1584Function : bl2\_plat\_set\_bl32\_ep\_info() [mandatory] 1585~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1586 1587:: 1588 1589 Argument : image_info *, entry_point_info * 1590 Return : void 1591 1592This function is called after loading BL32 image and it can be used to 1593overwrite the entry point set by loader and also set the security state 1594and SPSR which represents the entry point system state for BL32. 1595 1596Function : bl2\_plat\_set\_bl33\_ep\_info() [mandatory] 1597~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1598 1599:: 1600 1601 Argument : image_info *, entry_point_info * 1602 Return : void 1603 1604This function is called after loading BL33 image and it can be used to 1605overwrite the entry point set by loader and also set the security state 1606and SPSR which represents the entry point system state for BL33. 1607 1608In the preloaded BL33 alternative boot flow, this function is called after 1609populating its entry point address. It is passed a null pointer as its first 1610argument in this case. 1611 1612Function : bl2\_plat\_get\_bl32\_meminfo() [mandatory] 1613~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1614 1615:: 1616 1617 Argument : meminfo * 1618 Return : void 1619 1620This function is used to get the memory limits where BL2 can load the 1621BL32 image. The meminfo provided by this is used by load\_image() to 1622validate whether the BL32 image can be loaded with in the given 1623memory from the given base. 1624 1625Function : bl2\_plat\_get\_bl33\_meminfo() [mandatory] 1626~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1627 1628:: 1629 1630 Argument : meminfo * 1631 Return : void 1632 1633This function is used to get the memory limits where BL2 can load the 1634BL33 image. The meminfo provided by this is used by load\_image() to 1635validate whether the BL33 image can be loaded with in the given 1636memory from the given base. 1637 1638This function isn't needed if either ``PRELOADED_BL33_BASE`` or ``EL3_PAYLOAD_BASE`` 1639build options are used. 1640 1641Function : bl2\_plat\_flush\_bl31\_params() [mandatory] 1642~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1643 1644:: 1645 1646 Argument : void 1647 Return : void 1648 1649Once BL2 has populated all the structures that needs to be read by BL1 1650and BL31 including the bl31\_params structures and its sub-structures, 1651the bl31\_ep\_info structure and any platform specific data. It flushes 1652all these data to the main memory so that it is available when we jump to 1653later Bootloader stages with MMU off 1654 1655Function : plat\_get\_ns\_image\_entrypoint() [mandatory] 1656~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1657 1658:: 1659 1660 Argument : void 1661 Return : uintptr_t 1662 1663As previously described, BL2 is responsible for arranging for control to be 1664passed to a normal world BL image through BL31. This function returns the 1665entrypoint of that image, which BL31 uses to jump to it. 1666 1667BL2 is responsible for loading the normal world BL33 image (e.g. UEFI). 1668 1669This function isn't needed if either ``PRELOADED_BL33_BASE`` or ``EL3_PAYLOAD_BASE`` 1670build options are used. 1671 1672Function : bl2\_plat\_preload\_setup [optional] 1673~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1674 1675:: 1676 1677 Argument : void 1678 Return : void 1679 1680This optional function performs any BL2 platform initialization 1681required before image loading, that is not done later in 1682bl2\_platform\_setup(). Specifically, if support for multiple 1683boot sources is required, it initializes the boot sequence used by 1684plat\_try\_next\_boot\_source(). 1685 1686Function : plat\_try\_next\_boot\_source() [optional] 1687~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1688 1689:: 1690 1691 Argument : void 1692 Return : int 1693 1694This optional function passes to the next boot source in the redundancy 1695sequence. 1696 1697This function moves the current boot redundancy source to the next 1698element in the boot sequence. If there are no more boot sources then it 1699must return 0, otherwise it must return 1. The default implementation 1700of this always returns 0. 1701 1702Boot Loader Stage 2 (BL2) at EL3 1703-------------------------------- 1704 1705When the platform has a non-TF-A Boot ROM it is desirable to jump 1706directly to BL2 instead of TF-A BL1. In this case BL2 is expected to 1707execute at EL3 instead of executing at EL1. Refer to the `Firmware 1708Design`_ for more information. 1709 1710All mandatory functions of BL2 must be implemented, except the functions 1711bl2\_early\_platform\_setup and bl2\_el3\_plat\_arch\_setup, because 1712their work is done now by bl2\_el3\_early\_platform\_setup and 1713bl2\_el3\_plat\_arch\_setup. These functions should generally implement 1714the bl1\_plat\_xxx() and bl2\_plat\_xxx() functionality combined. 1715 1716 1717Function : bl2\_el3\_early\_platform\_setup() [mandatory] 1718~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1719 1720:: 1721 1722 Argument : u_register_t, u_register_t, u_register_t, u_register_t 1723 Return : void 1724 1725This function executes with the MMU and data caches disabled. It is only called 1726by the primary CPU. This function receives four parameters which can be used 1727by the platform to pass any needed information from the Boot ROM to BL2. 1728 1729On Arm standard platforms, this function does the following: 1730 1731- Initializes a UART (PL011 console), which enables access to the ``printf`` 1732 family of functions in BL2. 1733 1734- Initializes the storage abstraction layer used to load further bootloader 1735 images. It is necessary to do this early on platforms with a SCP\_BL2 image, 1736 since the later ``bl2_platform_setup`` must be done after SCP\_BL2 is loaded. 1737 1738- Initializes the private variables that define the memory layout used. 1739 1740Function : bl2\_el3\_plat\_arch\_setup() [mandatory] 1741~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1742 1743:: 1744 1745 Argument : void 1746 Return : void 1747 1748This function executes with the MMU and data caches disabled. It is only called 1749by the primary CPU. 1750 1751The purpose of this function is to perform any architectural initialization 1752that varies across platforms. 1753 1754On Arm standard platforms, this function enables the MMU. 1755 1756Function : bl2\_el3\_plat\_prepare\_exit() [optional] 1757~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1758 1759:: 1760 1761 Argument : void 1762 Return : void 1763 1764This function is called prior to exiting BL2 and run the next image. 1765It should be used to perform platform specific clean up or bookkeeping 1766operations before transferring control to the next image. This function 1767runs with MMU disabled. 1768 1769FWU Boot Loader Stage 2 (BL2U) 1770------------------------------ 1771 1772The AP Firmware Updater Configuration, BL2U, is an optional part of the FWU 1773process and is executed only by the primary CPU. BL1 passes control to BL2U at 1774``BL2U_BASE``. BL2U executes in Secure-EL1 and is responsible for: 1775 1776#. (Optional) Transfering the optional SCP\_BL2U binary image from AP secure 1777 memory to SCP RAM. BL2U uses the SCP\_BL2U ``image_info`` passed by BL1. 1778 ``SCP_BL2U_BASE`` defines the address in AP secure memory where SCP\_BL2U 1779 should be copied from. Subsequent handling of the SCP\_BL2U image is 1780 implemented by the platform specific ``bl2u_plat_handle_scp_bl2u()`` function. 1781 If ``SCP_BL2U_BASE`` is not defined then this step is not performed. 1782 1783#. Any platform specific setup required to perform the FWU process. For 1784 example, Arm standard platforms initialize the TZC controller so that the 1785 normal world can access DDR memory. 1786 1787The following functions must be implemented by the platform port to enable 1788BL2U to perform the tasks mentioned above. 1789 1790Function : bl2u\_early\_platform\_setup() [mandatory] 1791~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1792 1793:: 1794 1795 Argument : meminfo *mem_info, void *plat_info 1796 Return : void 1797 1798This function executes with the MMU and data caches disabled. It is only 1799called by the primary CPU. The arguments to this function is the address 1800of the ``meminfo`` structure and platform specific info provided by BL1. 1801 1802The platform may copy the contents of the ``mem_info`` and ``plat_info`` into 1803private storage as the original memory may be subsequently overwritten by BL2U. 1804 1805On Arm CSS platforms ``plat_info`` is interpreted as an ``image_info_t`` structure, 1806to extract SCP\_BL2U image information, which is then copied into a private 1807variable. 1808 1809Function : bl2u\_plat\_arch\_setup() [mandatory] 1810~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1811 1812:: 1813 1814 Argument : void 1815 Return : void 1816 1817This function executes with the MMU and data caches disabled. It is only 1818called by the primary CPU. 1819 1820The purpose of this function is to perform any architectural initialization 1821that varies across platforms, for example enabling the MMU (since the memory 1822map differs across platforms). 1823 1824Function : bl2u\_platform\_setup() [mandatory] 1825~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1826 1827:: 1828 1829 Argument : void 1830 Return : void 1831 1832This function may execute with the MMU and data caches enabled if the platform 1833port does the necessary initialization in ``bl2u_plat_arch_setup()``. It is only 1834called by the primary CPU. 1835 1836The purpose of this function is to perform any platform initialization 1837specific to BL2U. 1838 1839In Arm standard platforms, this function performs security setup, including 1840configuration of the TrustZone controller to allow non-secure masters access 1841to most of DRAM. Part of DRAM is reserved for secure world use. 1842 1843Function : bl2u\_plat\_handle\_scp\_bl2u() [optional] 1844~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1845 1846:: 1847 1848 Argument : void 1849 Return : int 1850 1851This function is used to perform any platform-specific actions required to 1852handle the SCP firmware. Typically it transfers the image into SCP memory using 1853a platform-specific protocol and waits until SCP executes it and signals to the 1854Application Processor (AP) for BL2U execution to continue. 1855 1856This function returns 0 on success, a negative error code otherwise. 1857This function is included if SCP\_BL2U\_BASE is defined. 1858 1859Boot Loader Stage 3-1 (BL31) 1860---------------------------- 1861 1862During cold boot, the BL31 stage is executed only by the primary CPU. This is 1863determined in BL1 using the ``platform_is_primary_cpu()`` function. BL1 passes 1864control to BL31 at ``BL31_BASE``. During warm boot, BL31 is executed by all 1865CPUs. BL31 executes at EL3 and is responsible for: 1866 1867#. Re-initializing all architectural and platform state. Although BL1 performs 1868 some of this initialization, BL31 remains resident in EL3 and must ensure 1869 that EL3 architectural and platform state is completely initialized. It 1870 should make no assumptions about the system state when it receives control. 1871 1872#. Passing control to a normal world BL image, pre-loaded at a platform- 1873 specific address by BL2. BL31 uses the ``entry_point_info`` structure that BL2 1874 populated in memory to do this. 1875 1876#. Providing runtime firmware services. Currently, BL31 only implements a 1877 subset of the Power State Coordination Interface (PSCI) API as a runtime 1878 service. See Section 3.3 below for details of porting the PSCI 1879 implementation. 1880 1881#. Optionally passing control to the BL32 image, pre-loaded at a platform- 1882 specific address by BL2. BL31 exports a set of apis that allow runtime 1883 services to specify the security state in which the next image should be 1884 executed and run the corresponding image. BL31 uses the ``entry_point_info`` 1885 structure populated by BL2 to do this. 1886 1887If BL31 is a reset vector, It also needs to handle the reset as specified in 1888section 2.2 before the tasks described above. 1889 1890The following functions must be implemented by the platform port to enable BL31 1891to perform the above tasks. 1892 1893Function : bl31\_early\_platform\_setup() [mandatory] 1894~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1895 1896:: 1897 1898 Argument : bl31_params *, void * 1899 Return : void 1900 1901This function executes with the MMU and data caches disabled. It is only called 1902by the primary CPU. The arguments to this function are: 1903 1904- The address of the ``bl31_params`` structure populated by BL2. 1905- An opaque pointer that the platform may use as needed. 1906 1907The platform can copy the contents of the ``bl31_params`` structure and its 1908sub-structures into private variables if the original memory may be 1909subsequently overwritten by BL31 and similarly the ``void *`` pointing 1910to the platform data also needs to be saved. 1911 1912In Arm standard platforms, BL2 passes a pointer to a ``bl31_params`` structure 1913in BL2 memory. BL31 copies the information in this pointer to internal data 1914structures. It also performs the following: 1915 1916- Initialize a UART (PL011 console), which enables access to the ``printf`` 1917 family of functions in BL31. 1918 1919- Enable issuing of snoop and DVM (Distributed Virtual Memory) requests to the 1920 CCI slave interface corresponding to the cluster that includes the primary 1921 CPU. 1922 1923Function : bl31\_plat\_arch\_setup() [mandatory] 1924~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1925 1926:: 1927 1928 Argument : void 1929 Return : void 1930 1931This function executes with the MMU and data caches disabled. It is only called 1932by the primary CPU. 1933 1934The purpose of this function is to perform any architectural initialization 1935that varies across platforms. 1936 1937On Arm standard platforms, this function enables the MMU. 1938 1939Function : bl31\_platform\_setup() [mandatory] 1940~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1941 1942:: 1943 1944 Argument : void 1945 Return : void 1946 1947This function may execute with the MMU and data caches enabled if the platform 1948port does the necessary initialization in ``bl31_plat_arch_setup()``. It is only 1949called by the primary CPU. 1950 1951The purpose of this function is to complete platform initialization so that both 1952BL31 runtime services and normal world software can function correctly. 1953 1954On Arm standard platforms, this function does the following: 1955 1956- Initialize the generic interrupt controller. 1957 1958 Depending on the GIC driver selected by the platform, the appropriate GICv2 1959 or GICv3 initialization will be done, which mainly consists of: 1960 1961 - Enable secure interrupts in the GIC CPU interface. 1962 - Disable the legacy interrupt bypass mechanism. 1963 - Configure the priority mask register to allow interrupts of all priorities 1964 to be signaled to the CPU interface. 1965 - Mark SGIs 8-15 and the other secure interrupts on the platform as secure. 1966 - Target all secure SPIs to CPU0. 1967 - Enable these secure interrupts in the GIC distributor. 1968 - Configure all other interrupts as non-secure. 1969 - Enable signaling of secure interrupts in the GIC distributor. 1970 1971- Enable system-level implementation of the generic timer counter through the 1972 memory mapped interface. 1973 1974- Grant access to the system counter timer module 1975 1976- Initialize the power controller device. 1977 1978 In particular, initialise the locks that prevent concurrent accesses to the 1979 power controller device. 1980 1981Function : bl31\_plat\_runtime\_setup() [optional] 1982~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1983 1984:: 1985 1986 Argument : void 1987 Return : void 1988 1989The purpose of this function is allow the platform to perform any BL31 runtime 1990setup just prior to BL31 exit during cold boot. The default weak 1991implementation of this function will invoke ``console_switch_state()`` to switch 1992console output to consoles marked for use in the ``runtime`` state. 1993 1994Function : bl31\_plat\_get\_next\_image\_ep\_info() [mandatory] 1995~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1996 1997:: 1998 1999 Argument : uint32_t 2000 Return : entry_point_info * 2001 2002This function may execute with the MMU and data caches enabled if the platform 2003port does the necessary initializations in ``bl31_plat_arch_setup()``. 2004 2005This function is called by ``bl31_main()`` to retrieve information provided by 2006BL2 for the next image in the security state specified by the argument. BL31 2007uses this information to pass control to that image in the specified security 2008state. This function must return a pointer to the ``entry_point_info`` structure 2009(that was copied during ``bl31_early_platform_setup()``) if the image exists. It 2010should return NULL otherwise. 2011 2012Function : bl31_plat_enable_mmu [optional] 2013~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2014 2015:: 2016 2017 Argument : uint32_t 2018 Return : void 2019 2020This function enables the MMU. The boot code calls this function with MMU and 2021caches disabled. This function should program necessary registers to enable 2022translation, and upon return, the MMU on the calling PE must be enabled. 2023 2024The function must honor flags passed in the first argument. These flags are 2025defined by the translation library, and can be found in the file 2026``include/lib/xlat_tables/xlat_mmu_helpers.h``. 2027 2028On DynamIQ systems, this function must not use stack while enabling MMU, which 2029is how the function in xlat table library version 2 is implementated. 2030 2031Function : plat\_get\_syscnt\_freq2() [mandatory] 2032~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2033 2034:: 2035 2036 Argument : void 2037 Return : unsigned int 2038 2039This function is used by the architecture setup code to retrieve the counter 2040frequency for the CPU's generic timer. This value will be programmed into the 2041``CNTFRQ_EL0`` register. In Arm standard platforms, it returns the base frequency 2042of the system counter, which is retrieved from the first entry in the frequency 2043modes table. 2044 2045#define : PLAT\_PERCPU\_BAKERY\_LOCK\_SIZE [optional] 2046~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2047 2048When ``USE_COHERENT_MEM = 0``, this constant defines the total memory (in 2049bytes) aligned to the cache line boundary that should be allocated per-cpu to 2050accommodate all the bakery locks. 2051 2052If this constant is not defined when ``USE_COHERENT_MEM = 0``, the linker 2053calculates the size of the ``bakery_lock`` input section, aligns it to the 2054nearest ``CACHE_WRITEBACK_GRANULE``, multiplies it with ``PLATFORM_CORE_COUNT`` 2055and stores the result in a linker symbol. This constant prevents a platform 2056from relying on the linker and provide a more efficient mechanism for 2057accessing per-cpu bakery lock information. 2058 2059If this constant is defined and its value is not equal to the value 2060calculated by the linker then a link time assertion is raised. A compile time 2061assertion is raised if the value of the constant is not aligned to the cache 2062line boundary. 2063 2064SDEI porting requirements 2065~~~~~~~~~~~~~~~~~~~~~~~~~ 2066 2067The SDEI dispatcher requires the platform to provide the following macros 2068and functions, of which some are optional, and some others mandatory. 2069 2070Macros 2071...... 2072 2073Macro: PLAT_SDEI_NORMAL_PRI [mandatory] 2074^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2075 2076This macro must be defined to the EL3 exception priority level associated with 2077Normal SDEI events on the platform. This must have a higher value (therefore of 2078lower priority) than ``PLAT_SDEI_CRITICAL_PRI``. 2079 2080Macro: PLAT_SDEI_CRITICAL_PRI [mandatory] 2081^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2082 2083This macro must be defined to the EL3 exception priority level associated with 2084Critical SDEI events on the platform. This must have a lower value (therefore of 2085higher priority) than ``PLAT_SDEI_NORMAL_PRI``. 2086 2087**Note**: SDEI exception priorities must be the lowest among Secure priorities. 2088Among the SDEI exceptions, Critical SDEI priority must be higher than Normal 2089SDEI priority. 2090 2091Functions 2092......... 2093 2094Function: int plat_sdei_validate_entry_point(uintptr_t ep) [optional] 2095^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2096 2097:: 2098 2099 Argument: uintptr_t 2100 Return: int 2101 2102This function validates the address of client entry points provided for both 2103event registration and *Complete and Resume* SDEI calls. The function takes one 2104argument, which is the address of the handler the SDEI client requested to 2105register. The function must return ``0`` for successful validation, or ``-1`` 2106upon failure. 2107 2108The default implementation always returns ``0``. On Arm platforms, this function 2109is implemented to translate the entry point to physical address, and further to 2110ensure that the address is located in Non-secure DRAM. 2111 2112Function: void plat_sdei_handle_masked_trigger(uint64_t mpidr, unsigned int intr) [optional] 2113^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2114 2115:: 2116 2117 Argument: uint64_t 2118 Argument: unsigned int 2119 Return: void 2120 2121SDEI specification requires that a PE comes out of reset with the events masked. 2122The client therefore is expected to call ``PE_UNMASK`` to unmask SDEI events on 2123the PE. No SDEI events can be dispatched until such time. 2124 2125Should a PE receive an interrupt that was bound to an SDEI event while the 2126events are masked on the PE, the dispatcher implementation invokes the function 2127``plat_sdei_handle_masked_trigger``. The MPIDR of the PE that received the 2128interrupt and the interrupt ID are passed as parameters. 2129 2130The default implementation only prints out a warning message. 2131 2132Power State Coordination Interface (in BL31) 2133-------------------------------------------- 2134 2135The TF-A implementation of the PSCI API is based around the concept of a 2136*power domain*. A *power domain* is a CPU or a logical group of CPUs which 2137share some state on which power management operations can be performed as 2138specified by `PSCI`_. Each CPU in the system is assigned a cpu index which is 2139a unique number between ``0`` and ``PLATFORM_CORE_COUNT - 1``. The 2140*power domains* are arranged in a hierarchical tree structure and each 2141*power domain* can be identified in a system by the cpu index of any CPU that 2142is part of that domain and a *power domain level*. A processing element (for 2143example, a CPU) is at level 0. If the *power domain* node above a CPU is a 2144logical grouping of CPUs that share some state, then level 1 is that group of 2145CPUs (for example, a cluster), and level 2 is a group of clusters (for 2146example, the system). More details on the power domain topology and its 2147organization can be found in `Power Domain Topology Design`_. 2148 2149BL31's platform initialization code exports a pointer to the platform-specific 2150power management operations required for the PSCI implementation to function 2151correctly. This information is populated in the ``plat_psci_ops`` structure. The 2152PSCI implementation calls members of the ``plat_psci_ops`` structure for performing 2153power management operations on the power domains. For example, the target 2154CPU is specified by its ``MPIDR`` in a PSCI ``CPU_ON`` call. The ``pwr_domain_on()`` 2155handler (if present) is called for the CPU power domain. 2156 2157The ``power-state`` parameter of a PSCI ``CPU_SUSPEND`` call can be used to 2158describe composite power states specific to a platform. The PSCI implementation 2159defines a generic representation of the power-state parameter viz which is an 2160array of local power states where each index corresponds to a power domain 2161level. Each entry contains the local power state the power domain at that power 2162level could enter. It depends on the ``validate_power_state()`` handler to 2163convert the power-state parameter (possibly encoding a composite power state) 2164passed in a PSCI ``CPU_SUSPEND`` call to this representation. 2165 2166The following functions form part of platform port of PSCI functionality. 2167 2168Function : plat\_psci\_stat\_accounting\_start() [optional] 2169~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2170 2171:: 2172 2173 Argument : const psci_power_state_t * 2174 Return : void 2175 2176This is an optional hook that platforms can implement for residency statistics 2177accounting before entering a low power state. The ``pwr_domain_state`` field of 2178``state_info`` (first argument) can be inspected if stat accounting is done 2179differently at CPU level versus higher levels. As an example, if the element at 2180index 0 (CPU power level) in the ``pwr_domain_state`` array indicates a power down 2181state, special hardware logic may be programmed in order to keep track of the 2182residency statistics. For higher levels (array indices > 0), the residency 2183statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the 2184default implementation will use PMF to capture timestamps. 2185 2186Function : plat\_psci\_stat\_accounting\_stop() [optional] 2187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2188 2189:: 2190 2191 Argument : const psci_power_state_t * 2192 Return : void 2193 2194This is an optional hook that platforms can implement for residency statistics 2195accounting after exiting from a low power state. The ``pwr_domain_state`` field 2196of ``state_info`` (first argument) can be inspected if stat accounting is done 2197differently at CPU level versus higher levels. As an example, if the element at 2198index 0 (CPU power level) in the ``pwr_domain_state`` array indicates a power down 2199state, special hardware logic may be programmed in order to keep track of the 2200residency statistics. For higher levels (array indices > 0), the residency 2201statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the 2202default implementation will use PMF to capture timestamps. 2203 2204Function : plat\_psci\_stat\_get\_residency() [optional] 2205~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2206 2207:: 2208 2209 Argument : unsigned int, const psci_power_state_t *, int 2210 Return : u_register_t 2211 2212This is an optional interface that is is invoked after resuming from a low power 2213state and provides the time spent resident in that low power state by the power 2214domain at a particular power domain level. When a CPU wakes up from suspend, 2215all its parent power domain levels are also woken up. The generic PSCI code 2216invokes this function for each parent power domain that is resumed and it 2217identified by the ``lvl`` (first argument) parameter. The ``state_info`` (second 2218argument) describes the low power state that the power domain has resumed from. 2219The current CPU is the first CPU in the power domain to resume from the low 2220power state and the ``last_cpu_idx`` (third parameter) is the index of the last 2221CPU in the power domain to suspend and may be needed to calculate the residency 2222for that power domain. 2223 2224Function : plat\_get\_target\_pwr\_state() [optional] 2225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2226 2227:: 2228 2229 Argument : unsigned int, const plat_local_state_t *, unsigned int 2230 Return : plat_local_state_t 2231 2232The PSCI generic code uses this function to let the platform participate in 2233state coordination during a power management operation. The function is passed 2234a pointer to an array of platform specific local power state ``states`` (second 2235argument) which contains the requested power state for each CPU at a particular 2236power domain level ``lvl`` (first argument) within the power domain. The function 2237is expected to traverse this array of upto ``ncpus`` (third argument) and return 2238a coordinated target power state by the comparing all the requested power 2239states. The target power state should not be deeper than any of the requested 2240power states. 2241 2242A weak definition of this API is provided by default wherein it assumes 2243that the platform assigns a local state value in order of increasing depth 2244of the power state i.e. for two power states X & Y, if X < Y 2245then X represents a shallower power state than Y. As a result, the 2246coordinated target local power state for a power domain will be the minimum 2247of the requested local power state values. 2248 2249Function : plat\_get\_power\_domain\_tree\_desc() [mandatory] 2250~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2251 2252:: 2253 2254 Argument : void 2255 Return : const unsigned char * 2256 2257This function returns a pointer to the byte array containing the power domain 2258topology tree description. The format and method to construct this array are 2259described in `Power Domain Topology Design`_. The BL31 PSCI initilization code 2260requires this array to be described by the platform, either statically or 2261dynamically, to initialize the power domain topology tree. In case the array 2262is populated dynamically, then plat\_core\_pos\_by\_mpidr() and 2263plat\_my\_core\_pos() should also be implemented suitably so that the topology 2264tree description matches the CPU indices returned by these APIs. These APIs 2265together form the platform interface for the PSCI topology framework. 2266 2267Function : plat\_setup\_psci\_ops() [mandatory] 2268~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2269 2270:: 2271 2272 Argument : uintptr_t, const plat_psci_ops ** 2273 Return : int 2274 2275This function may execute with the MMU and data caches enabled if the platform 2276port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only 2277called by the primary CPU. 2278 2279This function is called by PSCI initialization code. Its purpose is to let 2280the platform layer know about the warm boot entrypoint through the 2281``sec_entrypoint`` (first argument) and to export handler routines for 2282platform-specific psci power management actions by populating the passed 2283pointer with a pointer to BL31's private ``plat_psci_ops`` structure. 2284 2285A description of each member of this structure is given below. Please refer to 2286the Arm FVP specific implementation of these handlers in 2287`plat/arm/board/fvp/fvp\_pm.c`_ as an example. For each PSCI function that the 2288platform wants to support, the associated operation or operations in this 2289structure must be provided and implemented (Refer section 4 of 2290`Firmware Design`_ for the PSCI API supported in TF-A). To disable a PSCI 2291function in a platform port, the operation should be removed from this 2292structure instead of providing an empty implementation. 2293 2294plat\_psci\_ops.cpu\_standby() 2295.............................. 2296 2297Perform the platform-specific actions to enter the standby state for a cpu 2298indicated by the passed argument. This provides a fast path for CPU standby 2299wherein overheads of PSCI state management and lock acquistion is avoided. 2300For this handler to be invoked by the PSCI ``CPU_SUSPEND`` API implementation, 2301the suspend state type specified in the ``power-state`` parameter should be 2302STANDBY and the target power domain level specified should be the CPU. The 2303handler should put the CPU into a low power retention state (usually by 2304issuing a wfi instruction) and ensure that it can be woken up from that 2305state by a normal interrupt. The generic code expects the handler to succeed. 2306 2307plat\_psci\_ops.pwr\_domain\_on() 2308................................. 2309 2310Perform the platform specific actions to power on a CPU, specified 2311by the ``MPIDR`` (first argument). The generic code expects the platform to 2312return PSCI\_E\_SUCCESS on success or PSCI\_E\_INTERN\_FAIL for any failure. 2313 2314plat\_psci\_ops.pwr\_domain\_off() 2315.................................. 2316 2317Perform the platform specific actions to prepare to power off the calling CPU 2318and its higher parent power domain levels as indicated by the ``target_state`` 2319(first argument). It is called by the PSCI ``CPU_OFF`` API implementation. 2320 2321The ``target_state`` encodes the platform coordinated target local power states 2322for the CPU power domain and its parent power domain levels. The handler 2323needs to perform power management operation corresponding to the local state 2324at each power level. 2325 2326For this handler, the local power state for the CPU power domain will be a 2327power down state where as it could be either power down, retention or run state 2328for the higher power domain levels depending on the result of state 2329coordination. The generic code expects the handler to succeed. 2330 2331plat\_psci\_ops.pwr\_domain\_suspend\_pwrdown\_early() [optional] 2332................................................................. 2333 2334This optional function may be used as a performance optimization to replace 2335or complement pwr_domain_suspend() on some platforms. Its calling semantics 2336are identical to pwr_domain_suspend(), except the PSCI implementation only 2337calls this function when suspending to a power down state, and it guarantees 2338that data caches are enabled. 2339 2340When HW_ASSISTED_COHERENCY = 0, the PSCI implementation disables data caches 2341before calling pwr_domain_suspend(). If the target_state corresponds to a 2342power down state and it is safe to perform some or all of the platform 2343specific actions in that function with data caches enabled, it may be more 2344efficient to move those actions to this function. When HW_ASSISTED_COHERENCY 2345= 1, data caches remain enabled throughout, and so there is no advantage to 2346moving platform specific actions to this function. 2347 2348plat\_psci\_ops.pwr\_domain\_suspend() 2349...................................... 2350 2351Perform the platform specific actions to prepare to suspend the calling 2352CPU and its higher parent power domain levels as indicated by the 2353``target_state`` (first argument). It is called by the PSCI ``CPU_SUSPEND`` 2354API implementation. 2355 2356The ``target_state`` has a similar meaning as described in 2357the ``pwr_domain_off()`` operation. It encodes the platform coordinated 2358target local power states for the CPU power domain and its parent 2359power domain levels. The handler needs to perform power management operation 2360corresponding to the local state at each power level. The generic code 2361expects the handler to succeed. 2362 2363The difference between turning a power domain off versus suspending it is that 2364in the former case, the power domain is expected to re-initialize its state 2365when it is next powered on (see ``pwr_domain_on_finish()``). In the latter 2366case, the power domain is expected to save enough state so that it can resume 2367execution by restoring this state when its powered on (see 2368``pwr_domain_suspend_finish()``). 2369 2370When suspending a core, the platform can also choose to power off the GICv3 2371Redistributor and ITS through an implementation-defined sequence. To achieve 2372this safely, the ITS context must be saved first. The architectural part is 2373implemented by the ``gicv3_its_save_disable()`` helper, but most of the needed 2374sequence is implementation defined and it is therefore the responsibility of 2375the platform code to implement the necessary sequence. Then the GIC 2376Redistributor context can be saved using the ``gicv3_rdistif_save()`` helper. 2377Powering off the Redistributor requires the implementation to support it and it 2378is the responsibility of the platform code to execute the right implementation 2379defined sequence. 2380 2381When a system suspend is requested, the platform can also make use of the 2382``gicv3_distif_save()`` helper to save the context of the GIC Distributor after 2383it has saved the context of the Redistributors and ITS of all the cores in the 2384system. The context of the Distributor can be large and may require it to be 2385allocated in a special area if it cannot fit in the platform's global static 2386data, for example in DRAM. The Distributor can then be powered down using an 2387implementation-defined sequence. 2388 2389plat\_psci\_ops.pwr\_domain\_pwr\_down\_wfi() 2390............................................. 2391 2392This is an optional function and, if implemented, is expected to perform 2393platform specific actions including the ``wfi`` invocation which allows the 2394CPU to powerdown. Since this function is invoked outside the PSCI locks, 2395the actions performed in this hook must be local to the CPU or the platform 2396must ensure that races between multiple CPUs cannot occur. 2397 2398The ``target_state`` has a similar meaning as described in the ``pwr_domain_off()`` 2399operation and it encodes the platform coordinated target local power states for 2400the CPU power domain and its parent power domain levels. This function must 2401not return back to the caller. 2402 2403If this function is not implemented by the platform, PSCI generic 2404implementation invokes ``psci_power_down_wfi()`` for power down. 2405 2406plat\_psci\_ops.pwr\_domain\_on\_finish() 2407......................................... 2408 2409This function is called by the PSCI implementation after the calling CPU is 2410powered on and released from reset in response to an earlier PSCI ``CPU_ON`` call. 2411It performs the platform-specific setup required to initialize enough state for 2412this CPU to enter the normal world and also provide secure runtime firmware 2413services. 2414 2415The ``target_state`` (first argument) is the prior state of the power domains 2416immediately before the CPU was turned on. It indicates which power domains 2417above the CPU might require initialization due to having previously been in 2418low power states. The generic code expects the handler to succeed. 2419 2420plat\_psci\_ops.pwr\_domain\_suspend\_finish() 2421.............................................. 2422 2423This function is called by the PSCI implementation after the calling CPU is 2424powered on and released from reset in response to an asynchronous wakeup 2425event, for example a timer interrupt that was programmed by the CPU during the 2426``CPU_SUSPEND`` call or ``SYSTEM_SUSPEND`` call. It performs the platform-specific 2427setup required to restore the saved state for this CPU to resume execution 2428in the normal world and also provide secure runtime firmware services. 2429 2430The ``target_state`` (first argument) has a similar meaning as described in 2431the ``pwr_domain_on_finish()`` operation. The generic code expects the platform 2432to succeed. 2433 2434If the Distributor, Redistributors or ITS have been powered off as part of a 2435suspend, their context must be restored in this function in the reverse order 2436to how they were saved during suspend sequence. 2437 2438plat\_psci\_ops.system\_off() 2439............................. 2440 2441This function is called by PSCI implementation in response to a ``SYSTEM_OFF`` 2442call. It performs the platform-specific system poweroff sequence after 2443notifying the Secure Payload Dispatcher. 2444 2445plat\_psci\_ops.system\_reset() 2446............................... 2447 2448This function is called by PSCI implementation in response to a ``SYSTEM_RESET`` 2449call. It performs the platform-specific system reset sequence after 2450notifying the Secure Payload Dispatcher. 2451 2452plat\_psci\_ops.validate\_power\_state() 2453........................................ 2454 2455This function is called by the PSCI implementation during the ``CPU_SUSPEND`` 2456call to validate the ``power_state`` parameter of the PSCI API and if valid, 2457populate it in ``req_state`` (second argument) array as power domain level 2458specific local states. If the ``power_state`` is invalid, the platform must 2459return PSCI\_E\_INVALID\_PARAMS as error, which is propagated back to the 2460normal world PSCI client. 2461 2462plat\_psci\_ops.validate\_ns\_entrypoint() 2463.......................................... 2464 2465This function is called by the PSCI implementation during the ``CPU_SUSPEND``, 2466``SYSTEM_SUSPEND`` and ``CPU_ON`` calls to validate the non-secure ``entry_point`` 2467parameter passed by the normal world. If the ``entry_point`` is invalid, 2468the platform must return PSCI\_E\_INVALID\_ADDRESS as error, which is 2469propagated back to the normal world PSCI client. 2470 2471plat\_psci\_ops.get\_sys\_suspend\_power\_state() 2472................................................. 2473 2474This function is called by the PSCI implementation during the ``SYSTEM_SUSPEND`` 2475call to get the ``req_state`` parameter from platform which encodes the power 2476domain level specific local states to suspend to system affinity level. The 2477``req_state`` will be utilized to do the PSCI state coordination and 2478``pwr_domain_suspend()`` will be invoked with the coordinated target state to 2479enter system suspend. 2480 2481plat\_psci\_ops.get\_pwr\_lvl\_state\_idx() 2482........................................... 2483 2484This is an optional function and, if implemented, is invoked by the PSCI 2485implementation to convert the ``local_state`` (first argument) at a specified 2486``pwr_lvl`` (second argument) to an index between 0 and 2487``PLAT_MAX_PWR_LVL_STATES`` - 1. This function is only needed if the platform 2488supports more than two local power states at each power domain level, that is 2489``PLAT_MAX_PWR_LVL_STATES`` is greater than 2, and needs to account for these 2490local power states. 2491 2492plat\_psci\_ops.translate\_power\_state\_by\_mpidr() 2493.................................................... 2494 2495This is an optional function and, if implemented, verifies the ``power_state`` 2496(second argument) parameter of the PSCI API corresponding to a target power 2497domain. The target power domain is identified by using both ``MPIDR`` (first 2498argument) and the power domain level encoded in ``power_state``. The power domain 2499level specific local states are to be extracted from ``power_state`` and be 2500populated in the ``output_state`` (third argument) array. The functionality 2501is similar to the ``validate_power_state`` function described above and is 2502envisaged to be used in case the validity of ``power_state`` depend on the 2503targeted power domain. If the ``power_state`` is invalid for the targeted power 2504domain, the platform must return PSCI\_E\_INVALID\_PARAMS as error. If this 2505function is not implemented, then the generic implementation relies on 2506``validate_power_state`` function to translate the ``power_state``. 2507 2508This function can also be used in case the platform wants to support local 2509power state encoding for ``power_state`` parameter of PSCI\_STAT\_COUNT/RESIDENCY 2510APIs as described in Section 5.18 of `PSCI`_. 2511 2512plat\_psci\_ops.get\_node\_hw\_state() 2513...................................... 2514 2515This is an optional function. If implemented this function is intended to return 2516the power state of a node (identified by the first parameter, the ``MPIDR``) in 2517the power domain topology (identified by the second parameter, ``power_level``), 2518as retrieved from a power controller or equivalent component on the platform. 2519Upon successful completion, the implementation must map and return the final 2520status among ``HW_ON``, ``HW_OFF`` or ``HW_STANDBY``. Upon encountering failures, it 2521must return either ``PSCI_E_INVALID_PARAMS`` or ``PSCI_E_NOT_SUPPORTED`` as 2522appropriate. 2523 2524Implementations are not expected to handle ``power_levels`` greater than 2525``PLAT_MAX_PWR_LVL``. 2526 2527plat\_psci\_ops.system\_reset2() 2528................................ 2529 2530This is an optional function. If implemented this function is 2531called during the ``SYSTEM_RESET2`` call to perform a reset 2532based on the first parameter ``reset_type`` as specified in 2533`PSCI`_. The parameter ``cookie`` can be used to pass additional 2534reset information. If the ``reset_type`` is not supported, the 2535function must return ``PSCI_E_NOT_SUPPORTED``. For architectural 2536resets, all failures must return ``PSCI_E_INVALID_PARAMETERS`` 2537and vendor reset can return other PSCI error codes as defined 2538in `PSCI`_. On success this function will not return. 2539 2540plat\_psci\_ops.write\_mem\_protect() 2541.................................... 2542 2543This is an optional function. If implemented it enables or disables the 2544``MEM_PROTECT`` functionality based on the value of ``val``. 2545A non-zero value enables ``MEM_PROTECT`` and a value of zero 2546disables it. Upon encountering failures it must return a negative value 2547and on success it must return 0. 2548 2549plat\_psci\_ops.read\_mem\_protect() 2550..................................... 2551 2552This is an optional function. If implemented it returns the current 2553state of ``MEM_PROTECT`` via the ``val`` parameter. Upon encountering 2554failures it must return a negative value and on success it must 2555return 0. 2556 2557plat\_psci\_ops.mem\_protect\_chk() 2558................................... 2559 2560This is an optional function. If implemented it checks if a memory 2561region defined by a base address ``base`` and with a size of ``length`` 2562bytes is protected by ``MEM_PROTECT``. If the region is protected 2563then it must return 0, otherwise it must return a negative number. 2564 2565Interrupt Management framework (in BL31) 2566---------------------------------------- 2567 2568BL31 implements an Interrupt Management Framework (IMF) to manage interrupts 2569generated in either security state and targeted to EL1 or EL2 in the non-secure 2570state or EL3/S-EL1 in the secure state. The design of this framework is 2571described in the `IMF Design Guide`_ 2572 2573A platform should export the following APIs to support the IMF. The following 2574text briefly describes each api and its implementation in Arm standard 2575platforms. The API implementation depends upon the type of interrupt controller 2576present in the platform. Arm standard platform layer supports both 2577`Arm Generic Interrupt Controller version 2.0 (GICv2)`_ 2578and `3.0 (GICv3)`_. Juno builds the Arm platform layer to use GICv2 and the 2579FVP can be configured to use either GICv2 or GICv3 depending on the build flag 2580``FVP_USE_GIC_DRIVER`` (See FVP platform specific build options in 2581`User Guide`_ for more details). 2582 2583See also: `Interrupt Controller Abstraction APIs`__. 2584 2585.. __: platform-interrupt-controller-API.rst 2586 2587Function : plat\_interrupt\_type\_to\_line() [mandatory] 2588~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2589 2590:: 2591 2592 Argument : uint32_t, uint32_t 2593 Return : uint32_t 2594 2595The Arm processor signals an interrupt exception either through the IRQ or FIQ 2596interrupt line. The specific line that is signaled depends on how the interrupt 2597controller (IC) reports different interrupt types from an execution context in 2598either security state. The IMF uses this API to determine which interrupt line 2599the platform IC uses to signal each type of interrupt supported by the framework 2600from a given security state. This API must be invoked at EL3. 2601 2602The first parameter will be one of the ``INTR_TYPE_*`` values (see 2603`IMF Design Guide`_) indicating the target type of the interrupt, the second parameter is the 2604security state of the originating execution context. The return result is the 2605bit position in the ``SCR_EL3`` register of the respective interrupt trap: IRQ=1, 2606FIQ=2. 2607 2608In the case of Arm standard platforms using GICv2, S-EL1 interrupts are 2609configured as FIQs and Non-secure interrupts as IRQs from either security 2610state. 2611 2612In the case of Arm standard platforms using GICv3, the interrupt line to be 2613configured depends on the security state of the execution context when the 2614interrupt is signalled and are as follows: 2615 2616- The S-EL1 interrupts are signaled as IRQ in S-EL0/1 context and as FIQ in 2617 NS-EL0/1/2 context. 2618- The Non secure interrupts are signaled as FIQ in S-EL0/1 context and as IRQ 2619 in the NS-EL0/1/2 context. 2620- The EL3 interrupts are signaled as FIQ in both S-EL0/1 and NS-EL0/1/2 2621 context. 2622 2623Function : plat\_ic\_get\_pending\_interrupt\_type() [mandatory] 2624~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2625 2626:: 2627 2628 Argument : void 2629 Return : uint32_t 2630 2631This API returns the type of the highest priority pending interrupt at the 2632platform IC. The IMF uses the interrupt type to retrieve the corresponding 2633handler function. ``INTR_TYPE_INVAL`` is returned when there is no interrupt 2634pending. The valid interrupt types that can be returned are ``INTR_TYPE_EL3``, 2635``INTR_TYPE_S_EL1`` and ``INTR_TYPE_NS``. This API must be invoked at EL3. 2636 2637In the case of Arm standard platforms using GICv2, the *Highest Priority 2638Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of 2639the pending interrupt. The type of interrupt depends upon the id value as 2640follows. 2641 2642#. id < 1022 is reported as a S-EL1 interrupt 2643#. id = 1022 is reported as a Non-secure interrupt. 2644#. id = 1023 is reported as an invalid interrupt type. 2645 2646In the case of Arm standard platforms using GICv3, the system register 2647``ICC_HPPIR0_EL1``, *Highest Priority Pending group 0 Interrupt Register*, 2648is read to determine the id of the pending interrupt. The type of interrupt 2649depends upon the id value as follows. 2650 2651#. id = ``PENDING_G1S_INTID`` (1020) is reported as a S-EL1 interrupt 2652#. id = ``PENDING_G1NS_INTID`` (1021) is reported as a Non-secure interrupt. 2653#. id = ``GIC_SPURIOUS_INTERRUPT`` (1023) is reported as an invalid interrupt type. 2654#. All other interrupt id's are reported as EL3 interrupt. 2655 2656Function : plat\_ic\_get\_pending\_interrupt\_id() [mandatory] 2657~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2658 2659:: 2660 2661 Argument : void 2662 Return : uint32_t 2663 2664This API returns the id of the highest priority pending interrupt at the 2665platform IC. ``INTR_ID_UNAVAILABLE`` is returned when there is no interrupt 2666pending. 2667 2668In the case of Arm standard platforms using GICv2, the *Highest Priority 2669Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of the 2670pending interrupt. The id that is returned by API depends upon the value of 2671the id read from the interrupt controller as follows. 2672 2673#. id < 1022. id is returned as is. 2674#. id = 1022. The *Aliased Highest Priority Pending Interrupt Register* 2675 (``GICC_AHPPIR``) is read to determine the id of the non-secure interrupt. 2676 This id is returned by the API. 2677#. id = 1023. ``INTR_ID_UNAVAILABLE`` is returned. 2678 2679In the case of Arm standard platforms using GICv3, if the API is invoked from 2680EL3, the system register ``ICC_HPPIR0_EL1``, *Highest Priority Pending Interrupt 2681group 0 Register*, is read to determine the id of the pending interrupt. The id 2682that is returned by API depends upon the value of the id read from the 2683interrupt controller as follows. 2684 2685#. id < ``PENDING_G1S_INTID`` (1020). id is returned as is. 2686#. id = ``PENDING_G1S_INTID`` (1020) or ``PENDING_G1NS_INTID`` (1021). The system 2687 register ``ICC_HPPIR1_EL1``, *Highest Priority Pending Interrupt group 1 2688 Register* is read to determine the id of the group 1 interrupt. This id 2689 is returned by the API as long as it is a valid interrupt id 2690#. If the id is any of the special interrupt identifiers, 2691 ``INTR_ID_UNAVAILABLE`` is returned. 2692 2693When the API invoked from S-EL1 for GICv3 systems, the id read from system 2694register ``ICC_HPPIR1_EL1``, *Highest Priority Pending group 1 Interrupt 2695Register*, is returned if is not equal to GIC\_SPURIOUS\_INTERRUPT (1023) else 2696``INTR_ID_UNAVAILABLE`` is returned. 2697 2698Function : plat\_ic\_acknowledge\_interrupt() [mandatory] 2699~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2700 2701:: 2702 2703 Argument : void 2704 Return : uint32_t 2705 2706This API is used by the CPU to indicate to the platform IC that processing of 2707the highest pending interrupt has begun. It should return the raw, unmodified 2708value obtained from the interrupt controller when acknowledging an interrupt. 2709The actual interrupt number shall be extracted from this raw value using the API 2710`plat_ic_get_interrupt_id()`__. 2711 2712.. __: platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional 2713 2714This function in Arm standard platforms using GICv2, reads the *Interrupt 2715Acknowledge Register* (``GICC_IAR``). This changes the state of the highest 2716priority pending interrupt from pending to active in the interrupt controller. 2717It returns the value read from the ``GICC_IAR``, unmodified. 2718 2719In the case of Arm standard platforms using GICv3, if the API is invoked 2720from EL3, the function reads the system register ``ICC_IAR0_EL1``, *Interrupt 2721Acknowledge Register group 0*. If the API is invoked from S-EL1, the function 2722reads the system register ``ICC_IAR1_EL1``, *Interrupt Acknowledge Register 2723group 1*. The read changes the state of the highest pending interrupt from 2724pending to active in the interrupt controller. The value read is returned 2725unmodified. 2726 2727The TSP uses this API to start processing of the secure physical timer 2728interrupt. 2729 2730Function : plat\_ic\_end\_of\_interrupt() [mandatory] 2731~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2732 2733:: 2734 2735 Argument : uint32_t 2736 Return : void 2737 2738This API is used by the CPU to indicate to the platform IC that processing of 2739the interrupt corresponding to the id (passed as the parameter) has 2740finished. The id should be the same as the id returned by the 2741``plat_ic_acknowledge_interrupt()`` API. 2742 2743Arm standard platforms write the id to the *End of Interrupt Register* 2744(``GICC_EOIR``) in case of GICv2, and to ``ICC_EOIR0_EL1`` or ``ICC_EOIR1_EL1`` 2745system register in case of GICv3 depending on where the API is invoked from, 2746EL3 or S-EL1. This deactivates the corresponding interrupt in the interrupt 2747controller. 2748 2749The TSP uses this API to finish processing of the secure physical timer 2750interrupt. 2751 2752Function : plat\_ic\_get\_interrupt\_type() [mandatory] 2753~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2754 2755:: 2756 2757 Argument : uint32_t 2758 Return : uint32_t 2759 2760This API returns the type of the interrupt id passed as the parameter. 2761``INTR_TYPE_INVAL`` is returned if the id is invalid. If the id is valid, a valid 2762interrupt type (one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1`` and ``INTR_TYPE_NS``) is 2763returned depending upon how the interrupt has been configured by the platform 2764IC. This API must be invoked at EL3. 2765 2766Arm standard platforms using GICv2 configures S-EL1 interrupts as Group0 interrupts 2767and Non-secure interrupts as Group1 interrupts. It reads the group value 2768corresponding to the interrupt id from the relevant *Interrupt Group Register* 2769(``GICD_IGROUPRn``). It uses the group value to determine the type of interrupt. 2770 2771In the case of Arm standard platforms using GICv3, both the *Interrupt Group 2772Register* (``GICD_IGROUPRn``) and *Interrupt Group Modifier Register* 2773(``GICD_IGRPMODRn``) is read to figure out whether the interrupt is configured 2774as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt. 2775 2776Crash Reporting mechanism (in BL31) 2777----------------------------------- 2778 2779NOTE: This section assumes that your platform is enabling the MULTI_CONSOLE_API 2780flag in its platform.mk. Not using this flag is deprecated for new platforms. 2781 2782BL31 implements a crash reporting mechanism which prints the various registers 2783of the CPU to enable quick crash analysis and debugging. By default, the 2784definitions in ``plat/common/aarch64/platform\_helpers.S`` will cause the crash 2785output to be routed over the normal console infrastructure and get printed on 2786consoles configured to output in crash state. ``console_set_scope()`` can be 2787used to control whether a console is used for crash output. 2788 2789In some cases (such as debugging very early crashes that happen before the 2790normal boot console can be set up), platforms may want to control crash output 2791more explicitly. For these, the following functions can be overridden by 2792platform code. They are executed outside of a C environment and without a stack. 2793 2794Function : plat\_crash\_console\_init 2795~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2796 2797:: 2798 2799 Argument : void 2800 Return : int 2801 2802This API is used by the crash reporting mechanism to initialize the crash 2803console. It must only use the general purpose registers x0 through x7 to do the 2804initialization and returns 1 on success. 2805 2806If you are trying to debug crashes before the console driver would normally get 2807registered, you can use this to register a driver from assembly with hardcoded 2808parameters. For example, you could register the 16550 driver like this: 2809 2810:: 2811 2812 .section .data.crash_console /* Reserve space for console structure */ 2813 crash_console: 2814 .zero 6 * 8 /* console_16550_t has 6 8-byte words */ 2815 func plat_crash_console_init 2816 ldr x0, =YOUR_16550_BASE_ADDR 2817 ldr x1, =YOUR_16550_SRCCLK_IN_HZ 2818 ldr x2, =YOUR_16550_TARGET_BAUD_RATE 2819 adrp x3, crash_console 2820 add x3, x3, :lo12:crash_console 2821 b console_16550_register /* tail call, returns 1 on success */ 2822 endfunc plat_crash_console_init 2823 2824If you're trying to debug crashes in BL1, you can call the console_xxx_core_init 2825function exported by some console drivers from here. 2826 2827Function : plat\_crash\_console\_putc 2828~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2829 2830:: 2831 2832 Argument : int 2833 Return : int 2834 2835This API is used by the crash reporting mechanism to print a character on the 2836designated crash console. It must only use general purpose registers x1 and 2837x2 to do its work. The parameter and the return value are in general purpose 2838register x0. 2839 2840If you have registered a normal console driver in ``plat_crash_console_init``, 2841you can keep the default implementation here (which calls ``console_putc()``). 2842 2843If you're trying to debug crashes in BL1, you can call the console_xxx_core_putc 2844function exported by some console drivers from here. 2845 2846Function : plat\_crash\_console\_flush 2847~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2848 2849:: 2850 2851 Argument : void 2852 Return : int 2853 2854This API is used by the crash reporting mechanism to force write of all buffered 2855data on the designated crash console. It should only use general purpose 2856registers x0 through x5 to do its work. The return value is 0 on successful 2857completion; otherwise the return value is -1. 2858 2859If you have registered a normal console driver in ``plat_crash_console_init``, 2860you can keep the default implementation here (which calls ``console_flush()``). 2861 2862If you're trying to debug crashes in BL1, you can call the console_xx_core_flush 2863function exported by some console drivers from here. 2864 2865Extternal Abort handling and RAS Support 2866---------------------------------------- 2867 2868Function : plat_ea_handler 2869~~~~~~~~~~~~~~~~~~~~~~~~~~ 2870 2871:: 2872 2873 Argument : int 2874 Argument : uint64_t 2875 Argument : void * 2876 Argument : void * 2877 Argument : uint64_t 2878 Return : void 2879 2880This function is invoked by the RAS framework for the platform to handle an 2881External Abort received at EL3. The intention of the function is to attempt to 2882resolve the cause of External Abort and return; if that's not possible, to 2883initiate orderly shutdown of the system. 2884 2885The first parameter (``int ea_reason``) indicates the reason for External Abort. 2886Its value is one of ``ERROR_EA_*`` constants defined in ``ea_handle.h``. 2887 2888The second parameter (``uint64_t syndrome``) is the respective syndrome 2889presented to EL3 after having received the External Abort. Depending on the 2890nature of the abort (as can be inferred from the ``ea_reason`` parameter), this 2891can be the content of either ``ESR_EL3`` or ``DISR_EL1``. 2892 2893The third parameter (``void *cookie``) is unused for now. The fourth parameter 2894(``void *handle``) is a pointer to the preempted context. The fifth parameter 2895(``uint64_t flags``) indicates the preempted security state. These parameters 2896are received from the top-level exception handler. 2897 2898If ``RAS_EXTENSION`` is set to ``1``, the default implementation of this 2899function iterates through RAS handlers registered by the platform. If any of the 2900RAS handlers resolve the External Abort, no further action is taken. 2901 2902If ``RAS_EXTENSION`` is set to ``0``, or if none of the platform RAS handlers 2903could resolve the External Abort, the default implementation prints an error 2904message, and panics. 2905 2906Function : plat_handle_uncontainable_ea 2907~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2908 2909:: 2910 2911 Argument : int 2912 Argument : uint64_t 2913 Return : void 2914 2915This function is invoked by the RAS framework when an External Abort of 2916Uncontainable type is received at EL3. Due to the critical nature of 2917Uncontainable errors, the intention of this function is to initiate orderly 2918shutdown of the system, and is not expected to return. 2919 2920This function must be implemented in assembly. 2921 2922The first and second parameters are the same as that of ``plat_ea_handler``. 2923 2924The default implementation of this function calls 2925``report_unhandled_exception``. 2926 2927Function : plat_handle_double_fault 2928~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2929 2930:: 2931 2932 Argument : int 2933 Argument : uint64_t 2934 Return : void 2935 2936This function is invoked by the RAS framework when another External Abort is 2937received at EL3 while one is already being handled. I.e., a call to 2938``plat_ea_handler`` is outstanding. Due to its critical nature, the intention of 2939this function is to initiate orderly shutdown of the system, and is not expected 2940recover or return. 2941 2942This function must be implemented in assembly. 2943 2944The first and second parameters are the same as that of ``plat_ea_handler``. 2945 2946The default implementation of this function calls 2947``report_unhandled_exception``. 2948 2949Function : plat_handle_el3_ea 2950~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2951 2952:: 2953 2954 Return : void 2955 2956This function is invoked when an External Abort is received while executing in 2957EL3. Due to its critical nature, the intention of this function is to initiate 2958orderly shutdown of the system, and is not expected recover or return. 2959 2960This function must be implemented in assembly. 2961 2962The default implementation of this function calls 2963``report_unhandled_exception``. 2964 2965Build flags 2966----------- 2967 2968There are some build flags which can be defined by the platform to control 2969inclusion or exclusion of certain BL stages from the FIP image. These flags 2970need to be defined in the platform makefile which will get included by the 2971build system. 2972 2973- **NEED\_BL33** 2974 By default, this flag is defined ``yes`` by the build system and ``BL33`` 2975 build option should be supplied as a build option. The platform has the 2976 option of excluding the BL33 image in the ``fip`` image by defining this flag 2977 to ``no``. If any of the options ``EL3_PAYLOAD_BASE`` or ``PRELOADED_BL33_BASE`` 2978 are used, this flag will be set to ``no`` automatically. 2979 2980C Library 2981--------- 2982 2983To avoid subtle toolchain behavioral dependencies, the header files provided 2984by the compiler are not used. The software is built with the ``-nostdinc`` flag 2985to ensure no headers are included from the toolchain inadvertently. Instead the 2986required headers are included in the TF-A source tree. The library only 2987contains those C library definitions required by the local implementation. If 2988more functionality is required, the needed library functions will need to be 2989added to the local implementation. 2990 2991Some C headers have been obtained from `FreeBSD`_ and `SCC`_, while others have 2992been written specifically for TF-A. Fome implementation files have been obtained 2993from `FreeBSD`_, others have been written specifically for TF-A as well. The 2994files can be found in ``include/lib/libc`` and ``lib/libc``. 2995 2996SCC can be found in `http://www.simple-cc.org/`_. A copy of the `FreeBSD`_ 2997sources can be obtained from `http://github.com/freebsd/freebsd`_. 2998 2999Storage abstraction layer 3000------------------------- 3001 3002In order to improve platform independence and portability an storage abstraction 3003layer is used to load data from non-volatile platform storage. 3004 3005Each platform should register devices and their drivers via the Storage layer. 3006These drivers then need to be initialized by bootloader phases as 3007required in their respective ``blx_platform_setup()`` functions. Currently 3008storage access is only required by BL1 and BL2 phases. The ``load_image()`` 3009function uses the storage layer to access non-volatile platform storage. 3010 3011It is mandatory to implement at least one storage driver. For the Arm 3012development platforms the Firmware Image Package (FIP) driver is provided as 3013the default means to load data from storage (see the "Firmware Image Package" 3014section in the `User Guide`_). The storage layer is described in the header file 3015``include/drivers/io/io_storage.h``. The implementation of the common library 3016is in ``drivers/io/io_storage.c`` and the driver files are located in 3017``drivers/io/``. 3018 3019Each IO driver must provide ``io_dev_*`` structures, as described in 3020``drivers/io/io_driver.h``. These are returned via a mandatory registration 3021function that is called on platform initialization. The semi-hosting driver 3022implementation in ``io_semihosting.c`` can be used as an example. 3023 3024The Storage layer provides mechanisms to initialize storage devices before 3025IO operations are called. The basic operations supported by the layer 3026include ``open()``, ``close()``, ``read()``, ``write()``, ``size()`` and ``seek()``. 3027Drivers do not have to implement all operations, but each platform must 3028provide at least one driver for a device capable of supporting generic 3029operations such as loading a bootloader image. 3030 3031The current implementation only allows for known images to be loaded by the 3032firmware. These images are specified by using their identifiers, as defined in 3033[include/plat/common/platform\_def.h] (or a separate header file included from 3034there). The platform layer (``plat_get_image_source()``) then returns a reference 3035to a device and a driver-specific ``spec`` which will be understood by the driver 3036to allow access to the image data. 3037 3038The layer is designed in such a way that is it possible to chain drivers with 3039other drivers. For example, file-system drivers may be implemented on top of 3040physical block devices, both represented by IO devices with corresponding 3041drivers. In such a case, the file-system "binding" with the block device may 3042be deferred until the file-system device is initialised. 3043 3044The abstraction currently depends on structures being statically allocated 3045by the drivers and callers, as the system does not yet provide a means of 3046dynamically allocating memory. This may also have the affect of limiting the 3047amount of open resources per driver. 3048 3049-------------- 3050 3051*Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.* 3052 3053.. _include/plat/common/platform.h: ../include/plat/common/platform.h 3054.. _include/plat/arm/common/plat\_arm.h: ../include/plat/arm/common/plat_arm.h%5D 3055.. _User Guide: user-guide.rst 3056.. _include/plat/common/common\_def.h: ../include/plat/common/common_def.h 3057.. _include/plat/arm/common/arm\_def.h: ../include/plat/arm/common/arm_def.h 3058.. _plat/common/aarch64/platform\_mp\_stack.S: ../plat/common/aarch64/platform_mp_stack.S 3059.. _plat/common/aarch64/platform\_up\_stack.S: ../plat/common/aarch64/platform_up_stack.S 3060.. _For example, define the build flag in platform.mk: PLAT_PL061_MAX_GPIOS%20:=%20160 3061.. _Power Domain Topology Design: psci-pd-tree.rst 3062.. _include/common/bl\_common.h: ../include/common/bl_common.h 3063.. _include/lib/aarch32/arch.h: ../include/lib/aarch32/arch.h 3064.. _Firmware Design: firmware-design.rst 3065.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf 3066.. _plat/arm/board/fvp/fvp\_pm.c: ../plat/arm/board/fvp/fvp_pm.c 3067.. _IMF Design Guide: interrupt-framework-design.rst 3068.. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html 3069.. _3.0 (GICv3): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html 3070.. _FreeBSD: http://www.freebsd.org 3071.. _SCC: http://www.simple-cc.org/ 3072