docs/getting_started/porting-guide.rst

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