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