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