Lines Matching refs:the

8 mandatory and optional modifications for both the cold and warm boot paths.
12 -  Setting up the execution context in a certain way, or
17 implementation of variables and functions to fulfill the optional requirements
18 in order to ease the porting effort. Each platform port can use them as is or
19 provide their own implementation if the default implementation is inadequate.
25       interfaces as they get introduced in the code base should be *strongly*
29 Please review the :ref:`Threat Model` documents as part of the porting
31 the threats. Failing to fulfill these expectations could undermine the security
33 the threat assessment section, under the "`Mitigations implemented?`" box for
37 discusses these in detail. The subsequent sections discuss the remaining
40 Please refer to the :ref:`Platform Ports Policy` for the policy regarding
43 Only Arm development platforms (such as FVP and Juno) may use the
44 functions/definitions in ``include/plat/arm/common/`` and the corresponding
47 want to use any of the functionality present in ``plat/arm`` files, please
48 propose a patch that moves the code to ``plat/common`` so that it can be
54 This section covers the modifications that should be made by the platform for
55 each BL stage to correctly port the firmware stack. They are categorized as
61 A platform port must enable the Memory Management Unit (MMU) as well as the
62 instruction and data caches for each BL stage. Setting up the translation
63 tables is the responsibility of the platform port because memory maps differ
72 Also, the only translation granule size supported in TF-A is 4KB, as various
73 parts of the code assume that is the case. It is not possible to switch to
74 16 KB or 64 KB granule sizes at the moment.
76 In Arm standard platforms, each BL stage configures the MMU in the
80 If the build option ``USE_COHERENT_MEM`` is enabled, each platform can allocate a
85 possible for the firmware to place variables in it using the following C code
92 Or alternatively the following assembler code directive:
103 The following variables, functions and constants must be defined by the platform
104 for the firmware to work correctly.
111 Each platform must ensure that a header file of this name is in the system
112 include path with the following constants defined. This will require updating
113 the list of ``PLAT_INCLUDES`` in the ``platform.mk`` file.
115 Platform ports may optionally use the file ``include/plat/common/common_def.h``,
116 which provides typical values for some of the constants below. These values are
121    Defines the linker format used by the platform, for example
126    Defines the processor architecture for the linker by the platform, for
131    Defines the normal stack memory available to each CPU. This constant is used
137    Defines the size in bytes of the largest cache line across all the cache
138    levels in the platform.
142    Defines the character string printed by BL1 upon entry into the ``bl1_main()``
147    Defines the total number of CPUs implemented by the platform across all
148    clusters in the system.
152    Defines the total number of nodes in the power domain topology
153    tree at all the power domain levels used by the platform.
154    This macro is used by the PSCI implementation to allocate
159    Defines the maximum power domain level that the power management operations
160    should apply to. More often, but not always, the power domain level
161    corresponds to affinity level. This macro allows the PSCI implementation
162    to know the highest power domain level that it should consider for power
163    management operations in the system that the platform implements. For
164    example, the Base AEM FVP implements two clusters with a configurable
165    number of CPUs and it reports the maximum power domain level as 1.
169    Defines the local power state corresponding to the deepest power down
170    possible at every power domain level in the platform. The local power
172    with 0 being reserved for the RUN state. The PSCI implementation uses this
173    value to initialize the local power states of the power domain nodes and
174    to specify the requested power state for a PSCI_CPU_OFF call.
178    Defines the local power state corresponding to the deepest retention state
179    possible at every power domain level in the platform. This macro should be
180    a value less than PLAT_MAX_OFF_STATE and greater than 0. It is used by the
186    Defines the maximum number of local power states per power domain level
187    that the platform supports. The default value of this macro is 2 since
189    power domain level (power-down and retention). If the platform needs to
192    Currently, this macro is used by the Generic PSCI implementation to size
193    the array used for PSCI_STAT_COUNT/RESIDENCY accounting.
197    Defines the base address in secure ROM where BL1 originally lives. Must be
202    Defines the maximum address in secure ROM that BL1's actual content (i.e.
207    Defines the base address in secure RAM where BL1's read-write data will live
212    Defines the maximum address in secure RAM that BL1's read-write data can
217    Defines the base address in secure RAM where BL1 loads the BL2 binary image.
223    Defines the maximum address in secure RAM that the BL2 image can occupy.
228    Defines the base address in secure XIP memory where BL2 RO section originally
234    Defines the maximum address in secure XIP memory that BL2's actual content
240    Defines the base address in secure RAM where BL2's read-write data will live
246    Defines the maximum address in secure RAM that BL2's read-write data can
252    Defines the base address in secure RAM where BL2 loads the BL31 binary
257    Defines the maximum address in secure RAM that the BL31 image can occupy.
261    Defines the maximum message size between AP and RSE. Need to define if
264 For every image, the platform must define individual identifiers that will be
265 used by BL1 or BL2 to load the corresponding image into memory from non-volatile
266 storage. For the sake of performance, integer numbers will be used as
267 identifiers. The platform will use those identifiers to return the relevant
268 information about the image to be loaded (file handler, load address,
284 If Trusted Board Boot is enabled, the following certificate identifiers must
289    BL2 content certificate identifier, used by BL1 to load the BL2 content
294    Trusted key certificate identifier, used by BL2 to load the trusted key
299    BL31 key certificate identifier, used by BL2 to load the BL31 key
304    BL31 content certificate identifier, used by BL2 to load the BL31 content
309    BL33 key certificate identifier, used by BL2 to load the BL33 key
314    BL33 content certificate identifier, used by BL2 to load the BL33 content
319    Firmware Update (FWU) certificate identifier, used by NS_BL1U to load the
322 If the AP Firmware Updater Configuration image, BL2U is used, the following
327    Defines the base address in secure memory where BL1 copies the BL2U binary
332    Defines the maximum address in secure memory that the BL2U image can occupy.
339 If the SCP Firmware Update Configuration Image, SCP_BL2U is used, the following
350 If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following must
355    Defines the base address in non-secure ROM where NS_BL1U executes.
366 If the Non-Secure Firmware Updater, NS_BL2U is used, the following must also
371    Defines the base address in non-secure memory where NS_BL2U executes.
382 For the the Firmware update capability of TRUSTED BOARD BOOT, the following
387    Total number of images that can be loaded simultaneously. If the platform
390 If a SCP_BL2 image is supported by the platform, the following constants must
396    from platform storage before being transferred to the SCP.
400    SCP_BL2 key certificate identifier, used by BL2 to load the SCP_BL2 key
405    SCP_BL2 content certificate identifier, used by BL2 to load the SCP_BL2
408 If a BL32 image is supported by the platform, the following constants must
417    BL32 key certificate identifier, used by BL2 to load the BL32 key
422    BL32 content certificate identifier, used by BL2 to load the BL32 content
427    Defines the base address in secure memory where BL2 loads the BL32 binary
432    Defines the maximum address that the BL32 image can occupy.
434 If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the
435 platform, the following constants must also be defined:
439    Defines the base address of the secure memory used by the TSP image on the
440    platform. This must be at the same address or below ``BL32_BASE``.
444    Defines the size of the secure memory used by the BL32 image on the
446    accommodate the memory required by the BL32 image, defined by ``BL32_BASE``
451    Defines the ID of the secure physical generic timer interrupt used by the
454 If the platform port uses the translation table library code, the following
459    Optional flag that can be set per-image to enable the dynamic allocation of
460    regions even when the MMU is enabled. If not defined, only static
462    include the dynamic functionality.
466    Defines the maximum number of translation tables that are allocated by the
467    translation table library code. To minimize the amount of runtime memory
468    used, choose the smallest value needed to map the required virtual addresses
470    image, ``MAX_XLAT_TABLES`` must be defined to accommodate the dynamic regions
475    Defines the maximum number of regions that are allocated by the translation
478    defined in the ``mmap_region_t`` structure. The platform defines the regions
479    that should be mapped. Then, the translation table library will create the
480    corresponding tables and descriptors at runtime. To minimize the amount of
481    runtime memory used, choose the smallest value needed to register the
484    the dynamic regions as well.
488    Defines the total size of the virtual address space in bytes. For example,
493    Defines the total size of the physical address space in bytes. For example,
496 If the platform port uses the IO storage framework, the following constants
501    Defines the maximum number of registered IO devices. Attempting to register
507    Defines the maximum number of open IO handles. Attempting to open more IO
512    Defines the maximum number of registered IO block devices. Attempting to
515    With this macro, multiple block devices could be supported at the same
518 If the platform needs to allocate data within the per-cpu data framework in
519 BL31, it should define the following macro. Currently this is only required if
520 the platform decides not to use the coherent memory section by undefining the
521 ``USE_COHERENT_MEM`` build flag. In this case, the framework allocates the
522 required memory within the the per-cpu data to minimize wastage.
526    Defines the memory (in bytes) to be reserved within the per-cpu data
527    structure for use by the platform layer.
529 The following constants are optional. They should be defined when the platform
534    Defines the maximum address in secure RAM that the BL31's progbits sections
539    Defines the maximum address that the TSP's progbits sections can occupy.
541 If the platform supports OS-initiated mode, i.e. the build option
542 ``PSCI_OS_INIT_MODE`` is enabled, and if the platform's maximum power domain
543 level for PSCI_CPU_SUSPEND differs from ``PLAT_MAX_PWR_LVL``, the following
548    Defines the maximum power domain level that PSCI_CPU_SUSPEND should apply to.
550 If the platform port uses the PL061 GPIO driver, the following constant may
554    Maximum number of GPIOs required by the platform. This allows control how
559 If the platform port uses the partition driver, the following constant may
563    Maximum number of partition entries required by the platform. This allows
566    For example, define the build flag in ``platform.mk``:
573    For example, define the build flag in ``platform.mk``:
577 If the platform port uses the Arm® Ethos™-N NPU driver, the following
580 - The NPU SiP service handler must be hooked up. This consists of both the
581   initial setup (``ethosn_smc_setup``) and the handler itself
584 If the platform port uses the Arm® Ethos™-N NPU driver with TZMP1 support
585 enabled, the following constants and configuration must also be defined:
589   Defines the Non-secure Access IDentity (NSAID) that the NPU shall use to
590   access the protected memory that contains the NPU's firmware.
594   Defines the Non-secure Access IDentity (NSAID) that the NPU shall use for
595   read/write access to the protected memory that contains inference data.
599   Defines the Non-secure Access IDentity (NSAID) that the NPU shall use for
600   read-only access to the protected memory that contains inference data.
604   Defines the Non-secure Access IDentity (NSAID) that the NPU shall use for
605   read/write access to the non-protected memory.
609   Defines the Non-secure Access IDentity (NSAID) that the NPU shall use for
610   read-only access to the non-protected memory.
614   Defines the physical address range that the NPU's firmware will be loaded
617 - Configure the platforms TrustZone Controller (TZC) with appropriate regions
618   of protected memory. At minimum this must include a region for the NPU's
620   accessible using the NSAIDs defined above.
622 - Include the NPU firmware and certificates in the FIP.
624 - Provide FCONF entries to configure the image source for the NPU firmware
629  - BL2 can write the NPU firmware into the region defined by
631  - BL31 (SiP service) can read the NPU firmware from the same region
633 - Add the firmware image ID ``ETHOSN_NPU_FW_IMAGE_ID`` to the list of images
636 Please see the reference implementation code for the Juno platform as an example.
639 The following constant is optional. It should be defined to override the default
640 behaviour of the ``assert()`` function (for example, to save memory).
644    ``assert()`` prints the name of the file, the line number and the asserted
645    expression. Else if it is higher than ``LOG_LEVEL_INFO``, it prints the file
646    name and the line number. Else if it is lower than ``LOG_LEVEL_INFO``, it
647    doesn't print anything to the console. If ``PLAT_LOG_LEVEL_ASSERT`` isn't
650 If the platform port uses the DRTM feature, the following constants must be
655    Maximum Event Log size used by the platform. Platform can decide the maximum
656    size of the Event Log buffer, depending upon the highest hash algorithm
657    chosen and the number of components selected to measure during the DRTM
662    Number of the MMAP entries used by the DRTM implementation to calculate the
663    size of address map region of the platform.
668 Each platform must ensure a file of this name is in the system include path with
669 the following macro defined. In the Arm development platforms, this file is
674    This macro allows the crash reporting routine to print relevant platform
685 BL1 by default implements the reset vector where execution starts from a cold
686 or warm boot. BL31 can be optionally set as a reset vector using the
689 For each CPU, the reset vector code is responsible for the following tasks:
693 #. In the case of a cold boot and the CPU being a secondary CPU, ensuring that
694    the CPU is placed in a platform-specific state until the primary CPU
695    performs the necessary steps to remove it from this state.
697 #. In the case of a warm boot, ensuring that the CPU jumps to a platform-
698    specific address in the BL31 image in the same processor mode as it was
701 The following functions need to be implemented by the platform port to enable
702 reset vector code to perform the above tasks.
712 This function is called with the MMU and caches disabled
714 distinguishing between a warm and cold reset for the current CPU using
715 platform-specific means. If it's a warm reset, then it returns the warm
719 This function does not follow the Procedure Call Standard used by the
720 Application Binary Interface for the Arm 64-bit architecture. The caller should
726 Note that for platforms that support programming the reset address, it is
727 expected that a CPU will start executing code directly at the right address,
728 both on a cold and warm reset. In this case, there is no need to identify the
729 type of reset nor to query the warm reset entrypoint. Therefore, implementing
739 This function is called with the MMU and data caches disabled. It is responsible
740 for placing the executing secondary CPU in a platform-specific state until the
741 primary CPU performs the necessary actions to bring it out of that state and
742 allow entry into the OS. This function must not return.
744 In the Arm FVP port, when using the normal boot flow, each secondary CPU powers
745 itself off. The primary CPU is responsible for powering up the secondary CPUs
752 Note that for platforms that can't release secondary CPUs out of reset, only the
753 primary CPU will execute the cold boot code. Therefore, implementing this
764 This function identifies whether the current CPU is the primary CPU or a
765 secondary CPU. A return value of zero indicates that the CPU is not the
766 primary CPU, while a non-zero return value indicates that the CPU is the
769 Note that for platforms that can't release secondary CPUs out of reset, only the
770 primary CPU will execute the cold boot code. Therefore, there is no need to
782 This function is called before any access to data is made by the firmware, in
794 pointer to the ROTPK stored in the platform (or a hash of it) and its length.
795 The ROTPK must be encoded in DER format according to the following ASN.1
810 In case the function returns a hash of the key:
819 The function returns 0 on success. Any other value is treated as error by the
821 to the ROTPK in the flags parameter:
825     ROTPK_IS_HASH      : Indicates that the ROTPK returned by the platform is a
827     ROTPK_NOT_DEPLOYED : This allows the platform to skip certificate ROTPK
828                          verification while the platform ROTPK is not deployed.
829                          When this flag is set, the function does not need to
830                          return a platform ROTPK, and the authentication
831                          framework uses the ROTPK in the certificate without
832                          verifying it against the platform value. This flag
843 This function is mandatory when Trusted Board Boot is enabled. It returns the
844 non-volatile counter value stored in the platform in the second argument. The
845 cookie in the first argument may be used to select the counter in case the
846 platform provides more than one (for example, on platforms that use the default
847 TBBR CoT, the cookie will correspond to the OID values defined in
850 The function returns 0 on success. Any other value means the counter value could
851 not be retrieved from the platform.
862 counter value in the platform. The cookie in the first argument may be used to
863 select the counter (as explained in plat_get_nv_ctr()). The second argument is
864 the updated counter value to be written to the NV counter.
866 The function returns 0 on success. Any other value means the counter value could
882 descriptor and may be used to decide if the counter is allowed to be
883 updated or not. The third argument is the updated counter value to
884 be written to the NV counter.
886 The function returns 0 on success. Any other value means the counter value
887 either could not be updated or the authentication image descriptor indicates
904 This function is used to return the address of the platform *address-map* table,
905 which describes the regions of normal memory, memory mapped I/O
916 This function returns *true* if the platform has any trusted devices capable of
931 If the platform has peripherals that are not managed by the SMMU, then the
944 This function returns the total number of SMMUs in the platform.
954 This function returns an array of SMMU addresses and the actual number of SMMUs
955 reported by the platform.
965 This function returns the address of plat_drtm_dma_prot_features_t structure
966 containing the maximum number of protected regions and bitmap with the types
967 of DMA protection supported by the platform.
978 This function returns the maximum size of DMA protected regions table in
989 This function returns the address of *plat_drtm_tpm_features_t* structure
991 supported by the platform.
1001 This function returns the size normal-world DCE of the platform.
1011 This function returns the size of implementation defined DLME region
1012 of the platform.
1022 This function returns the size of TCB hash table of the platform.
1032 This function returns the size of ACPI tables region of the platform.
1042 This function returns the Maximum number of TCB hashes recorded by the
1054 This function returns the DLME image authentication features.
1065 This function validates that given region is within the Non-Secure region
1088 This function reads a 64 bit error code from the non-volatile storage
1089 into the received address, and returns 0 on success and -1 on failure.
1095 by the platform port.
1105 This function returns the index of the calling CPU which is used as a
1107 per-CPU stacks). This function will be invoked very early in the
1109 implemented in assembly and should not rely on the availability of a C
1113 This function plays a crucial role in the power domain topology framework in
1125 This function validates the ``MPIDR`` of a CPU and converts it to an index,
1127 case the ``MPIDR`` is invalid, this function returns -1. This function will only
1128 be invoked by BL31 after the power domain topology is initialized and can
1129 utilize the C runtime environment. For further details about how TF-A
1130 represents the power domain topology and how this relates to the linear CPU
1143 internally by the Mbed TLS library. Hence, each BL stage that utilises Mbed TLS
1149 the function simply returns the address and size of this "pre-allocated" heap.
1150 For a platform to use this default implementation, only a call to the helper
1153 However, by writting their own implementation, platforms have the potential to
1154 optimise memory usage. For example, on some Arm platforms, the Mbed TLS heap is
1155 shared between BL1 and BL2 stages and, thus, the necessary space is not reserved
1158 On success the function should return 0 and a negative error code otherwise.
1173 implementation for testing purposes which must be overridden by the platform
1176 It also allows the platform to pass symmetric key identifier rather than
1177 actual symmetric key which is useful in cases where the crypto backend provides
1178 secure storage for the symmetric key. So in this case ``ENC_KEY_IS_IDENTIFIER``
1184 On success the function should return 0 and a negative error code otherwise.
1198 non-volatile storage and length) of active/updated images using the passed
1204 In Arm platforms, this function is used to set an I/O policy of the FIP image,
1217 responsible for setting up the platform I/O policy of the requested metadata
1219 be used to load this image from the platform's non-volatile storage.
1224 For example, the FWU metadata image is stored as a partition inside the GUID
1225 partition table image. Its specification is defined in the partition table
1228 the I/O policy of the FWU metadata image.
1233 Alongside, returns device handle and image specification from the I/O policy
1234 of the requested FWU metadata image.
1244 This function is mandatory when PSA_FWU_SUPPORT is enabled. It provides the
1245 means to retrieve the boot index value from the platform. The boot index is the
1246 bank from which the platform has booted the firmware images.
1248 By default, the platform will read the metadata structure and try to boot from
1249 the active bank. If the platform fails to boot from the active bank due to
1251 resets while booting from the active bank, the platform can then switch to boot
1252 from a different bank. This function then returns the bank that the platform
1258 The following are helper functions implemented by the firmware that perform
1270 This function sets the current stack pointer to the normal memory stack that
1271 has been allocated for the current CPU. For BL images that only require a
1272 stack for the primary CPU, the UP version of the function is used. The size
1273 of the stack allocated to each CPU is specified by the platform defined
1276 Common implementations of this function for the UP and MP BL images are
1288 This function returns the base address of the normal memory stack that
1289 has been allocated for the current CPU. For BL images that only require a
1290 stack for the primary CPU, the UP version of the function is used. The size
1291 of the stack allocated to each CPU is specified by the platform defined
1294 Common implementations of this function for the UP and MP BL images are
1307 exception is taken, for example the current exception level, the CPU security
1308 state (secure/non-secure), the exception type, and so on. This function is
1309 called in the following circumstances:
1315 about the way the platform displays its status information.
1317 For AArch64, this function receives the exception type as its argument.
1318 Possible values for exceptions types are listed in the
1322 For AArch32, this function receives the exception mode as its argument.
1323 Possible values for exception modes are listed in the
1335 allows the platform to do the platform specific initializations. Platform
1337 preserve the values of callee saved registers x19 to x29.
1340 the default implementation, refer to the :ref:`Firmware Design` for general
1351 This API allows a platform to disable the Accelerator Coherency Port (if
1353 doesn't do anything. Since this API is called during the power down sequence,
1354 it has restrictions for stack usage and it can use the registers x0 - x17 as
1355 scratch registers. It should preserve the value in x18 register as it is used
1356 by the caller to store the return address.
1366 This API is called when the generic code encounters an error situation from
1367 which it cannot continue. It allows the platform to perform error reporting or
1368 recovery actions (for example, reset the system). This function must not return.
1370 The parameter indicates the type of error using standard codes from ``errno.h``.
1371 Possible errors reported by the generic code are:
1375 -  ``-ENOENT``: the requested image or certificate could not be found or an IO
1390 This API is called when the generic code encounters an unexpected error
1392 and must be implemented in assembly because it may be called before the C
1407 This function returns pointer to the list of images that the platform has
1408 populated to load. This function is invoked in BL2 to load the
1419 This function returns a pointer to the shared memory that the platform has
1421 function is invoked in BL2 to pass this information to the next BL
1432 This function returns a random value that is used to initialize the canary used
1433 when the stack protector is enabled with ENABLE_STACK_PROTECTOR. A predictable
1434 value will weaken the protection as the attacker could easily write the right
1435 value as part of the attack most of the time. Therefore, it should return a
1439    For the protection to be effective, the global data need to be placed at
1440    a lower address than the stack bases. Failure to do so would allow an
1441    attacker to overwrite the canary as part of the stack buffer overflow attack.
1451 This function flushes to main memory all the image params that are passed to
1453 to the next BL image.
1463 This function defines the prefix string corresponding to the `log_level` to be
1464 prepended to all the log output from TF-A. The `log_level` (argument) will
1465 correspond to one of the standard log levels defined in debug.h. The platform
1466 can override the common implementation to define a different prefix string for
1467 the log output. The implementation should be robust to future changes that
1468 increase the number of log levels.
1482     soc_version[30:24] = JEP-106 continuation code for the SiP
1483     soc_version[23:16] = JEP-106 identification code with parity bit for the SiP
1508 The plat_get_soc_name() function allows a platform to expose the SoC name to
1509 the firmware. It takes a pointer to a character pointer as an argument, which
1512 compatibility. It must not exceed 136 bytes, including the null terminator. On
1513 success, the function returns SMC_ARCH_CALL_SUCCESS. If the platform does not
1525 This function returns SMC_ARCH_CALL_SUCCESS if the platform supports
1526 the SMCCC function specified in the argument; otherwise returns
1550 plat_setup_try_img_ops() function, passing it the address of the
1574 used, it is mandatory that the backup image is on the same media.
1576 The argument is the ID of the image for which we are looking for an alternative
1598 This optional function will log error information if the GPT is corrupted, by
1599 setting the address passed by gpt_corrupted_info_ptr to flags value, currently
1611 This optional function will log if the primary GPT is corrupted, by writing
1612 the value of gpt_corrupted_info to the address passed by log_address.
1620 BL1 implements the reset vector where execution starts from after a cold or
1621 warm boot. For each CPU, BL1 is responsible for the following tasks:
1623 #. Handling the reset as described in section 2.2
1625 #. In the case of a cold boot and the CPU being the primary CPU, ensuring that
1626    only this CPU executes the remaining BL1 code, including loading and passing
1627    control to the BL2 stage.
1629 #. Identifying and starting the Firmware Update process (if required).
1631 #. Loading the BL2 image from non-volatile storage into secure memory at the
1632    address specified by the platform defined constant ``BL2_BASE``.
1634 #. Populating a ``meminfo`` structure with the following information in memory,
1642    By default, BL1 places this ``meminfo`` structure at the end of secure
1645    It is possible for the platform to decide where it wants to place the
1646    ``meminfo`` structure for BL2 or restrict the amount of memory visible to
1647    BL2 by overriding the weak default implementation of
1650 The following functions need to be implemented by the platform port to enable
1651 BL1 to perform the above tasks.
1661 This function executes with the MMU and data caches disabled. It is only called
1662 by the primary CPU.
1666 -  Enables a secure instance of SP805 to act as the Trusted Watchdog.
1668 -  Initializes a UART (PL011 console), which enables access to the ``printf``
1672    the CCI slave interface corresponding to the cluster that includes the
1683 This function performs any platform-specific and architectural setup that the
1685 memory controllers and the interconnect.
1687 In Arm standard platforms, this function enables the MMU.
1699 This function executes with the MMU and data caches enabled. It is responsible
1700 for performing any remaining platform-specific setup that can occur after the
1703 In Arm standard platforms, this function initializes the storage abstraction
1704 layer used to load the next bootloader image.
1716 This function should only be called on the cold boot path. It executes with the
1718 a ``meminfo`` structure containing the extents and availability of secure RAM for
1719 the BL1 stage.
1726 This information is used by BL1 to load the BL2 image in secure RAM. BL1 also
1727 populates a similar structure to tell BL2 the extents of memory available for
1740 This function is called prior to exiting BL1 in response to the
1743 control to the next image. It receives the address of the ``entry_point_info_t``
1754 This function allows platforms to override ``ep_info`` for the given ``image_id``.
1766 This and the following function must be overridden to enable the FWU feature.
1768 BL1 calls this function after platform setup to identify the next image to be
1769 loaded and executed. If the platform returns ``BL2_IMAGE_ID`` then BL1 proceeds
1770 with the normal boot sequence, which loads and executes BL2. If the platform
1775 if so, return the first image in the firmware update process.
1785 BL1 calls this function to get the image descriptor information ``image_desc_t``
1786 for the provided ``image_id`` from the platform.
1790 the firmware update images defined in the Trusted Board Boot Requirements
1801 This function can be used by the platforms to update/use image information
1803 boot and FWU code path, before loading the image.
1813 This utility function calculates the memory layout of BL2, representing it in a
1814 `meminfo_t` structure. The default implementation derives this layout from the
1815 positioning of BL1’s RW data at the top of the memory layout.
1825 This function can be used by the platforms to update/use image information
1827 boot and FWU code path, after loading and authenticating the image.
1829 The default weak implementation of this function calculates the amount of
1831 structure at the beginning of this free memory and populates it. The address
1832 of ``meminfo_t`` structure is updated in ``arg1`` of the entrypoint
1844 BL1 calls this function when the FWU process is complete. It must not return.
1846 example to initiate the normal boot flow.
1860 copying or authenticating an image. Its responsibility is to ensure that the
1863 indicated by the security state of the ``flags`` argument.
1865 This function can safely assume that the value resulting from the addition of
1872 override it when using the FWU feature.
1882 This function inquiry the platform if the non-volatile counter is shared
1889 The BL2 stage is executed only by the primary CPU, which is determined in BL1
1890 using the ``platform_is_primary_cpu()`` function. BL1 passed control to BL2 at
1892 ``plat_get_bl_image_load_info()`` to retrieve the list of images to load from
1893 non-volatile storage to secure/non-secure RAM. After all the images are loaded
1894 then BL2 invokes ``plat_get_next_bl_params()`` to get the list of executable
1895 images to be passed to the next BL image.
1897 The following functions must be implemented by the platform port to enable BL2
1898 to perform the above tasks.
1908 This function executes with the MMU and data caches disabled. It is only called
1909 by the primary CPU. The 4 arguments are passed by BL1 to BL2 and these arguments
1912 On Arm standard platforms, the arguments received are :
1917     the contents of ``meminfo`` as it may be subsequently overwritten by BL2.
1921 -  Initializes a UART (PL011 console), which enables access to the ``printf``
1924 -  Initializes the storage abstraction layer used to load further bootloader
1926    since the later ``bl2_platform_setup`` must be done after SCP_BL2 is loaded.
1936 This function executes with the MMU and data caches disabled. It is only called
1937 by the primary CPU.
1942 On Arm standard platforms, this function enables the MMU.
1952 This function may execute with the MMU and data caches enabled if the platform
1953 port does the necessary initialization in ``bl2_plat_arch_setup()``. It is only
1954 called by the primary CPU.
1960 configuration of the TrustZone controller to allow non-secure masters access
1971 This function can be used by the platforms to update/use image information
1983 This function can be used by the platforms to update/use image information
2002 When the platform has a non-TF-A Boot ROM it is desirable to jump
2004 execute at EL3 instead of executing at EL1. Refer to the :ref:`Firmware Design`
2007 All mandatory functions of BL2 must be implemented, except the functions
2011 the bl1_plat_xxx() and bl2_plat_xxx() functionality combined.
2022 This function executes with the MMU and data caches disabled. It is only called
2023 by the primary CPU. This function receives four parameters which can be used
2024 by the platform to pass any needed information from the Boot ROM to BL2.
2026 On Arm standard platforms, this function does the following:
2028 -  Initializes a UART (PL011 console), which enables access to the ``printf``
2031 -  Initializes the storage abstraction layer used to load further bootloader
2033    since the later ``bl2_platform_setup`` must be done after SCP_BL2 is loaded.
2035 - Initializes the private variables that define the memory layout used.
2045 This function executes with the MMU and data caches disabled. It is only called
2046 by the primary CPU.
2051 On Arm standard platforms, this function enables the MMU.
2061 This function is called prior to exiting BL2 and run the next image.
2063 operations before transferring control to the next image. This function
2069 The AP Firmware Updater Configuration, BL2U, is an optional part of the FWU
2070 process and is executed only by the primary CPU. BL1 passes control to BL2U at
2073 #. (Optional) Transferring the optional SCP_BL2U binary image from AP secure
2074    memory to SCP RAM. BL2U uses the SCP_BL2U ``image_info`` passed by BL1.
2075    ``SCP_BL2U_BASE`` defines the address in AP secure memory where SCP_BL2U
2076    should be copied from. Subsequent handling of the SCP_BL2U image is
2077    implemented by the platform specific ``bl2u_plat_handle_scp_bl2u()`` function.
2080 #. Any platform specific setup required to perform the FWU process. For
2081    example, Arm standard platforms initialize the TZC controller so that the
2084 The following functions must be implemented by the platform port to enable
2085 BL2U to perform the tasks mentioned above.
2095 This function executes with the MMU and data caches disabled. It is only
2096 called by the primary CPU. The arguments to this function is the address
2097 of the ``meminfo`` structure and platform specific info provided by BL1.
2099 The platform may copy the contents of the ``mem_info`` and ``plat_info`` into
2100 private storage as the original memory may be subsequently overwritten by BL2U.
2114 This function executes with the MMU and data caches disabled. It is only
2115 called by the primary CPU.
2118 that varies across platforms, for example enabling the MMU (since the memory
2129 This function may execute with the MMU and data caches enabled if the platform
2130 port does the necessary initialization in ``bl2u_plat_arch_setup()``. It is only
2131 called by the primary CPU.
2137 configuration of the TrustZone controller to allow non-secure masters access
2149 handle the SCP firmware. Typically it transfers the image into SCP memory using
2150 a platform-specific protocol and waits until SCP executes it and signals to the
2159 During cold boot, the BL31 stage is executed only by the primary CPU. This is
2160 determined in BL1 using the ``platform_is_primary_cpu()`` function. BL1 passes
2167    should make no assumptions about the system state when it receives control.
2170    specific address by BL2. On ARM platforms, BL31 uses the ``bl_params`` list
2174    subset of the Power State Coordination Interface (PSCI) API as a runtime
2175    service. See :ref:`psci_in_bl31` below for details of porting the PSCI
2178 #. Optionally passing control to the BL32 image, pre-loaded at a platform-
2180    services to specify the security state in which the next image should be
2181    executed and run the corresponding image. On ARM platforms, BL31 uses the
2184 If BL31 is a reset vector, It also needs to handle the reset as specified in
2185 section 2.2 before the tasks described above.
2187 The following functions must be implemented by the platform port to enable BL31
2188 to perform the above tasks.
2198 This function executes with the MMU and data caches disabled. It is only called
2199 by the primary CPU. BL2 can pass 4 arguments to BL31 and these arguments are
2202 In Arm standard platforms, the arguments received are :
2204     arg0 - The pointer to the head of `bl_params_t` list
2218 The function runs through the `bl_param_t` list and extracts the entry point
2219 information for BL32 and BL33. It also performs the following:
2221 -  Initialize a UART (PL011 console), which enables access to the ``printf``
2224 -  Enable issuing of snoop and DVM (Distributed Virtual Memory) requests to the
2225    CCI slave interface corresponding to the cluster that includes the primary
2236 This function executes with the MMU and data caches disabled. It is only called
2237 by the primary CPU.
2242 On Arm standard platforms, this function enables the MMU.
2252 This function may execute with the MMU and data caches enabled if the platform
2253 port does the necessary initialization in ``bl31_plat_arch_setup()``. It is only
2254 called by the primary CPU.
2259 On Arm standard platforms, this function does the following:
2261 -  Initialize the generic interrupt controller.
2263    Depending on the GIC driver selected by the platform, the appropriate GICv2
2266    -  Enable secure interrupts in the GIC CPU interface.
2267    -  Disable the legacy interrupt bypass mechanism.
2268    -  Configure the priority mask register to allow interrupts of all priorities
2269       to be signaled to the CPU interface.
2270    -  Mark SGIs 8-15 and the other secure interrupts on the platform as secure.
2272    -  Enable these secure interrupts in the GIC distributor.
2274    -  Enable signaling of secure interrupts in the GIC distributor.
2276 -  Enable system-level implementation of the generic timer counter through the
2279 -  Grant access to the system counter timer module
2281 -  Initialize the power controller device.
2283    In particular, initialise the locks that prevent concurrent accesses to the
2294 The purpose of this function is to allow the platform to perform any BL31 runtime
2307 This function may execute with the MMU and data caches enabled if the platform
2308 port does the necessary initializations in ``bl31_plat_arch_setup()``.
2311 BL2 for the next image in the security state specified by the argument. BL31
2312 uses this information to pass control to that image in the specified security
2313 state. This function must return a pointer to the ``entry_point_info`` structure
2314 (that was copied during ``bl31_early_platform_setup()``) if the image exists. It
2325 This function returns the Platform attestation token. If the full token does
2326 not fit in the buffer, the function will return a hunk of the token and
2328 to this function may be needed to retrieve the entire token.
2330 The parameters of the function are:
2332     arg0 - A pointer to the buffer where the Platform token should be copied by
2333            this function. If the platform token does not completely fit in the
2334            buffer, the function may return a piece of the token only.
2336     arg1 - Contains the size (in bytes) of the buffer passed in arg0. In
2337            addition, this parameter is used by the function to return the size
2338            of the platform token length hunk copied to the buffer.
2340     arg2 - A pointer to the buffer where the challenge object is stored.
2342     arg3 - The length of the challenge object in bytes. Possible values are 32,
2344            retrieve the remaining hunks of the token.
2346     arg4 - Returns the remaining length of the token (in bytes) that is yet to
2349 The function returns 0 on success, -EINVAL on failure and -EAGAIN if the
2350 resource associated with the platform token retrieval is busy.
2360 This function returns the delegated realm attestation key which will be used to
2364 The parameters of the function are:
2366     arg0 - A pointer to the buffer where the attestation key should be copied
2367            by this function. The buffer must be big enough to hold the
2370     arg1 - Contains the size (in bytes) of the buffer passed in arg0. The
2371            function returns the attestation key length in this parameter.
2373     arg2 - The type of the elliptic curve to which the requested attestation key
2386 This function returns the size of the shared area between EL3 and RMM (or 0 on
2387 failure). A pointer to the shared area (or a NULL pointer on failure) is stored
2388 in the pointer passed as argument.
2398 When ENABLE_RME is enabled, this function populates a boot manifest for the
2399 RMM image and stores it in the area specified by manifest.
2411 This function is invoked by BL31's RMMD when there is a request from the RMM
2412 monitor to update the tweak for the encryption key associated to a MECID.
2414 The first parameter (``uint16_t mecid``) contains the MECID for which the
2415 encryption key is to be updated. The second argument specifies the reason
2430 Reserve memory to be used by the RMM. This could be memory simply taken from a pool of reserved
2433 Return value is the physical address of a memory region of at least ``size`` bytes, which needs
2436 This function needs to be implemented if a platform enables RME and the RMM requires the memory
2447 Queue realm attestation token signing request from the RMM in EL3. The interface between
2448 the RMM and EL3 is modeled as a queue but the underlying implementation may be different,
2449 so long as the semantics of queuing and the error codes are used as defined below.
2451 See :ref:`el3_token_sign_request_struct` for definition of the request structure.
2453 Optional interface from the RMM-EL3 interface v0.4 onwards.
2455 The parameters of the functions are:
2456       arg0: Pointer to the token sign request to be pushed to EL3.
2457       The structure must be located in the RMM-EL3 shared
2462         - E_RMM_INVAL   If the arguments are invalid.
2463         - E_RMM_AGAIN   Indicates that the request was not queued since the
2465 	  or situation in the system, that prevents accepting the request
2466 	  from the RMM.
2467         - E_RMM_UNK     If the SMC is not implemented or if interface
2478 Populate the attestation signing response in the ``resp`` parameter. The interface between
2479 the RMM and EL3 is modeled as a queue for responses but the underlying implementation may
2480 be different, so long as the semantics of queuing and the error codes are used as defined
2483 See :ref:`el3_token_sign_response_struct` for definition of the response structure.
2485 Optional interface from the RMM-EL3 interface v0.4 onwards.
2487 The parameters of the functions are:
2488           resp: Pointer to the token sign response to get from EL3.
2489 	  The structure must be located in the RMM-EL3 shared
2494         - E_RMM_INVAL   If the arguments are invalid.
2496         - E_RMM_UNK     If the SMC is not implemented or if interface
2507 This function returns the public portion of the realm attestation key which will be used to
2508 sign Realm attestation token. Typically, with delegated attestation, the private key is
2509 returned, however, there may be platforms where the private key bits are better protected
2510 in a platform specific manner such that the private key is not exposed. In such cases,
2511 the RMM will only cache the public key and forward any requests such as signing, that
2512 uses the private key to EL3. The API currently only supports P-384 ECC curve key.
2514 This is an optional interface from the RMM-EL3 interface v0.4 onwards.
2516 The parameters of the function are:
2518     arg0 - A pointer to the buffer where the public key should be copied
2519     by this function. The buffer must be big enough to hold the
2522     arg1 - Contains the size (in bytes) of the buffer passed in arg0. The
2523     function returns the attestation key length in this parameter.
2525     arg2 - The type of the elliptic curve to which the requested attestation key
2529 E_RMM_UNK if the SMC is not implemented or if interface version is < 0.4.
2539 This function sets the key/IV info for an IDE stream at the Root port. The key is 256 bits
2540 and IV is 96 bits. The caller calls this SMC to program this key to the Rx and Tx ports
2542 the arguments `Ecam address` and `Rootport ID` before acting on it. The arguments `request ID`
2543 and `cookie` are to be ignored for blocking mode and are pass-through to the response for
2547 Depending on the expected latency for IDE-KM interface, the platform should choose blocking
2551 The parameters of the function are:
2555     arg1 - The rootport ID used to identify the PCIe rootport of a connected device.
2557     arg2 - The IDE stream info associated with a physical device, this parameter packs the
2558     the keyset, direction, substream and stream ID info.
2568 if the key programming is unsuccesful, E_RMM_UNK for an unknown error, E_RMM_AGAIN returned
2569 only for non-blocking mode if the IDE-KM interface is busy or the request queue is full.
2570 E_RMM_INPROGRESS returned if the request is queued successfully and used only in non-blocking
2581 This function activates the IDE stream at the Root Port once all the keys have been
2582 programmed. The platform should validate the arguments `Ecam address` and `Rootport ID`
2584 mode and are pass-through to the response for non-blocking mode.
2587 Depending on the expected latency for IDE-KM interface, the platform should choose blocking
2591 The parameters of the function are:
2595     arg1 - The rootport ID used to identify the PCIe rootport of a connected device.
2597     arg2 - The IDE stream info associated with a physical device, this parameter packs the
2598     the keyset, direction, substream and stream ID info.
2606 if the key programming is unsuccesful, E_RMM_UNK for an unknown error, E_RMM_AGAIN returned
2607 only for non-blocking mode if the IDE-KM interface is busy or the request queue is full.
2608 E_RMM_INPROGRESS returned if the request is queued successfully and used only in non-blocking
2619 This function stops the IDE stream and is used to tear down the IDE stream at Root Port.
2620 The platform should validate the arguments `Ecam address` and `Rootport ID` before acting
2622 mode and are pass-through to the response for non-blocking mode.
2625 Depending on the expected latency for IDE-KM interface, the platform should choose blocking
2629 The parameters of the function are:
2633     arg1 - The rootport ID used to identify the PCIe rootport of a connected device.
2635     arg2 - The IDE stream info associated with a physical device, this parameter packs the
2636     the keyset, direction, substream and stream ID info.
2644 if the key programming is unsuccesful, E_RMM_UNK for an unknown error, E_RMM_AGAIN returned
2645 only for non-blocking mode if the IDE-KM interface is busy or the request queue is full.
2646 E_RMM_INPROGRESS returned if the request is queued successfully and used only in non-blocking
2657 This function retrieves a reponse for any of the prior non-blocking IDE-KM requests. The
2658 caller has to identify the request and populate the accurate response. For blocking calls,
2662 Depending on the expected latency for IDE-KM interface, the platform should choose blocking
2666 The parameters of the function are:
2670     arg1 - The rootport ID used to identify the PCIe rootport of a connected device.
2672     arg2 - Retrieved response corresponding to the previous IDE_KM request.
2674     arg3 - returns the passthrough request ID of the retrieved response.
2676     arg4 - returns the passthrough cookie of the retrieved response.
2680 IDE-KM interface is having blocking semantics, E_RMM_AGAIN if the response queue is empty.
2682 The `arg2` return parameter can return the following values:
2696 This function enables the MMU. The boot code calls this function with MMU and
2698 translation, and upon return, the MMU on the calling PE must be enabled.
2700 The function must honor flags passed in the first argument. These flags are
2701 defined by the translation library, and can be found in the file
2705 is how the function in xlat table library version 2 is implemented.
2715 This function returns the 128-bit value which can be used to program ARMv8.3
2719 called each time a core powers up and it is the platform's responsibility to
2720 decide when to regenerate the keys if generating them is an expensive operation.
2722 This function is only needed if ARMv8.3 pointer authentication is used in the
2733 This function is used by the architecture setup code to retrieve the counter
2734 frequency for the CPU's generic timer. This value will be programmed into the
2735 ``CNTFRQ_EL0`` register. In Arm standard platforms, it returns the base frequency
2736 of the system counter, which is retrieved from the first entry in the frequency
2742 When ``USE_COHERENT_MEM = 0``, this constant defines the total memory (in
2743 bytes) aligned to the cache line boundary that should be allocated per-cpu to
2744 accommodate all the bakery locks.
2746 If this constant is not defined when ``USE_COHERENT_MEM = 0``, the linker
2747 calculates the size of the ``.bakery_lock`` input section, aligns it to the
2749 and stores the result in a linker symbol. This constant prevents a platform
2750 from relying on the linker and provide a more efficient mechanism for
2753 If this constant is defined and its value is not equal to the value
2754 calculated by the linker then a link time assertion is raised. A compile time
2755 assertion is raised if the value of the constant is not aligned to the cache
2763 The |SDEI| dispatcher requires the platform to provide the following macros
2772 This macro must be defined to the EL3 exception priority level associated with
2773 Normal |SDEI| events on the platform. This must have a higher value
2779 This macro must be defined to the EL3 exception priority level associated with
2780 Critical |SDEI| events on the platform. This must have a lower value
2783 **Note**: |SDEI| exception priorities must be the lowest among Secure
2784 priorities. Among the |SDEI| exceptions, Critical |SDEI| priority must
2798 This function validates the entry point address of the event handler provided by
2799 the client for both event registration and *Complete and Resume* |SDEI| calls.
2800 The function ensures that the address is valid in the client translation regime.
2802 The second argument is the exception level that the client is executing in. It
2808 translates the entry point address within the client translation regime and
2809 further ensures that the resulting physical address is located in Non-secure
2821 |SDEI| specification requires that a PE comes out of reset with the events
2823 |SDEI| events on the PE. No |SDEI| events can be dispatched until such
2826 Should a PE receive an interrupt that was bound to an |SDEI| event while the
2827 events are masked on the PE, the dispatcher implementation invokes the function
2828 ``plat_sdei_handle_masked_trigger``. The MPIDR of the PE that received the
2829 interrupt and the interrupt ID are passed as parameters.
2838 The |TRNG| backend requires the platform to provide the following values
2847 This value must be defined to the UUID of the TRNG backend that is specific to
2848 the hardware after ``plat_entropy_setup`` function is called. This value must
2849 conform to the SMCCC calling convention; The most significant 32 bits of the
2850 UUID must not equal ``0xffffffff`` or the signed integer ``-1`` as this value in
2874   Out : when the return value is true, the entropy has been written into the
2877 This function writes entropy into storage provided by the caller. If no entropy
2878 is available, it must return false and the storage must not be written.
2885 The TF-A implementation of the PSCI API is based around the concept of a
2888 specified by `PSCI`_. Each CPU in the system is assigned a cpu index which is
2891 *power domain* can be identified in a system by the cpu index of any CPU that
2893 example, a CPU) is at level 0. If the *power domain* node above a CPU is a
2896 example, the system). More details on the power domain topology and its
2899 BL31's platform initialization code exports a pointer to the platform-specific
2900 power management operations required for the PSCI implementation to function
2901 correctly. This information is populated in the ``plat_psci_ops`` structure. The
2902 PSCI implementation calls members of the ``plat_psci_ops`` structure for performing
2903 power management operations on the power domains. For example, the target
2905 handler (if present) is called for the CPU power domain.
2909 defines a generic representation of the power-state parameter, which is an
2911 level. Each entry contains the local power state the power domain at that power
2912 level could enter. It depends on the ``validate_power_state()`` handler to
2913 convert the power-state parameter (possibly encoding a composite power state)
2929 differently at CPU level versus higher levels. As an example, if the element at
2930 index 0 (CPU power level) in the ``pwr_domain_state`` array indicates a power down
2931 state, special hardware logic may be programmed in order to keep track of the
2932 residency statistics. For higher levels (array indices > 0), the residency
2933 statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the
2947 differently at CPU level versus higher levels. As an example, if the element at
2948 index 0 (CPU power level) in the ``pwr_domain_state`` array indicates a power down
2949 state, special hardware logic may be programmed in order to keep track of the
2950 residency statistics. For higher levels (array indices > 0), the residency
2951 statistics could be tracked in software using PMF. If ``ENABLE_PMF`` is set, the
2963 state and provides the time spent resident in that low power state by the power
2967 identified by the ``lvl`` (first argument) parameter. The ``state_info`` (second
2968 argument) describes the low power state that the power domain has resumed from.
2969 The current CPU is the first CPU in the power domain to resume from the low
2970 power state and the ``last_cpu_idx`` (third parameter) is the index of the last
2971 CPU in the power domain to suspend and may be needed to calculate the residency
2982 The PSCI generic code uses this function to let the platform participate in
2985 argument) which contains the requested power state for each CPU at a particular
2986 power domain level ``lvl`` (first argument) within the power domain. The function
2988 a coordinated target power state by the comparing all the requested power
2989 states. The target power state should not be deeper than any of the requested
2993 that the platform assigns a local state value in order of increasing depth
2994 of the power state i.e. for two power states X & Y, if X < Y
2995 then X represents a shallower power state than Y. As a result, the
2996 coordinated target local power state for a power domain will be the minimum
2997 of the requested local power state values.
3007 This function returns a pointer to the byte array containing the power domain
3010 initialization code requires this array to be described by the platform, either
3011 statically or dynamically, to initialize the power domain topology tree. In case
3012 the array is populated dynamically, then plat_core_pos_by_mpidr() and
3013 plat_my_core_pos() should also be implemented suitably so that the topology tree
3014 description matches the CPU indices returned by these APIs. These APIs together
3015 form the platform interface for the PSCI topology framework.
3025 This function may execute with the MMU and data caches enabled if the platform
3026 port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only
3027 called by the primary CPU.
3030 the platform layer know about the warm boot entrypoint through the
3032 platform-specific psci power management actions by populating the passed
3036 the Arm FVP specific implementation of these handlers in
3037 ``plat/arm/board/fvp/fvp_pm.c`` as an example. For each PSCI function that the
3038 platform wants to support, the associated operation or operations in this
3040 :ref:`Firmware Design` for the PSCI API supported in TF-A). To disable a PSCI
3041 function in a platform port, the operation should be removed from this
3047 Perform the platform-specific actions to enter the standby state for a cpu
3048 indicated by the passed argument. This provides a fast path for CPU standby
3050 For this handler to be invoked by the PSCI ``CPU_SUSPEND`` API implementation,
3051 the suspend state type specified in the ``power-state`` parameter should be
3052 STANDBY and the target power domain level specified should be the CPU. The
3053 handler should put the CPU into a low power retention state (usually by
3055 state by a normal interrupt. The generic code expects the handler to succeed.
3060 Perform the platform specific actions to power on a CPU, specified
3061 by the ``MPIDR`` (first argument). The generic code expects the platform to
3067 This optional function performs the platform specific actions to check if
3068 powering off the calling CPU and its higher parent power domain levels as
3069 indicated by the ``target_state`` (first argument) is possible or allowed.
3071 The ``target_state`` encodes the platform coordinated target local power states
3072 for the CPU power domain and its parent power domain levels.
3074 For this handler, the local power state for the CPU power domain will be a
3076 for the higher power domain levels depending on the result of state
3077 coordination. The generic code expects PSCI_E_DENIED return code if the
3078 platform thinks that CPU_OFF should not proceed on the calling CPU.
3083 Perform the platform specific actions to prepare to power off the calling CPU
3084 and its higher parent power domain levels as indicated by the ``target_state``
3085 (first argument). It is called by the PSCI ``CPU_OFF`` API implementation.
3087 The ``target_state`` encodes the platform coordinated target local power states
3088 for the CPU power domain and its parent power domain levels. The handler
3089 needs to perform power management operation corresponding to the local state
3092 For this handler, the local power state for the CPU power domain will be a
3094 for the higher power domain levels depending on the result of state
3095 coordination. The generic code expects the handler to succeed.
3100 This is an optional function that is only compiled into the build if the build
3103 If implemented, this function allows the platform to perform platform specific
3113 are identical to pwr_domain_suspend(), except the PSCI implementation only
3117 When HW_ASSISTED_COHERENCY = 0, the PSCI implementation disables data caches
3118 before calling pwr_domain_suspend(). If the target_state corresponds to a
3119 power down state and it is safe to perform some or all of the platform
3128 Perform the platform specific actions to prepare to suspend the calling
3129 CPU and its higher parent power domain levels as indicated by the
3130 ``target_state`` (first argument). It is called by the PSCI ``CPU_SUSPEND``
3134 the ``pwr_domain_off()`` operation. It encodes the platform coordinated
3135 target local power states for the CPU power domain and its parent
3137 corresponding to the local state at each power level. The generic code
3138 expects the handler to succeed.
3141 in the former case, the power domain is expected to re-initialize its state
3142 when it is next powered on (see ``pwr_domain_on_finish()``). In the latter
3143 case, the power domain is expected to save enough state so that it can resume
3147 When suspending a core, the platform can also choose to power off the GICv3
3149 this safely, the ITS context must be saved first. The architectural part is
3150 implemented by the ``gicv3_its_save_disable()`` helper, but most of the needed
3151 sequence is implementation defined and it is therefore the responsibility of
3152 the platform code to implement the necessary sequence. Then the GIC
3153 Redistributor context can be saved using the ``gicv3_rdistif_save()`` helper.
3154 Powering off the Redistributor requires the implementation to support it and it
3155 is the responsibility of the platform code to execute the right implementation
3158 When a system suspend is requested, the platform can also make use of the
3159 ``gicv3_distif_save()`` helper to save the context of the GIC Distributor after
3160 it has saved the context of the Redistributors and ITS of all the cores in the
3161 system. The context of the Distributor can be large and may require it to be
3162 allocated in a special area if it cannot fit in the platform's global static
3170 platform specific actions before the CPU is powered down. Since this function is
3171 invoked outside the PSCI locks, the actions performed in this hook must be local
3172 to the CPU or the platform must ensure that races between multiple CPUs cannot
3175 The ``target_state`` has a similar meaning as described in the ``pwr_domain_off()``
3176 operation and it encodes the platform coordinated target local power states for
3177 the CPU power domain and its parent power domain levels.
3180 ``wfi()`` to powerdown the CPU, mitigate any powerdown errata,
3192 This function is called by the PSCI implementation after the calling CPU is
3194 It performs the platform-specific setup required to initialize enough state for
3195 this CPU to enter the normal world and also provide secure runtime firmware
3198 The ``target_state`` (first argument) is the prior state of the power domains
3199 immediately before the CPU was turned on. It indicates which power domains
3200 above the CPU might require initialization due to having previously been in
3201 low power states. The generic code expects the handler to succeed.
3206 This optional function is called by the PSCI implementation after the calling
3208 the associated cluster are guaranteed to be participating in coherency. This
3209 function gives the flexibility to perform any platform-specific actions safely,
3210 such as initialization or modification of shared data structures, without the
3213 The ``target_state`` has a similar meaning as described in the ``pwr_domain_on_finish()``
3214 operation. The generic code expects the handler to succeed.
3219 This function is called by the PSCI implementation after the calling CPU is
3221 event, for example a timer interrupt that was programmed by the CPU during the
3222 ``CPU_SUSPEND`` call or ``SYSTEM_SUSPEND`` call. It performs the platform-specific
3223 setup required to restore the saved state for this CPU to resume execution
3224 in the normal world and also provide secure runtime firmware services.
3227 the ``pwr_domain_on_finish()`` operation. The generic code expects the platform
3230 If the Distributor, Redistributors or ITS have been powered off as part of a
3231 suspend, their context must be restored in this function in the reverse order
3238 call. It performs the platform-specific system poweroff sequence after
3239 notifying the Secure Payload Dispatcher. The caller will call ``wfi`` if this
3246 call. It performs the platform-specific system reset sequence after
3247 notifying the Secure Payload Dispatcher. The caller will call ``wfi`` if this
3253 This function is called by the PSCI implementation during the ``CPU_SUSPEND``
3254 call to validate the ``power_state`` parameter of the PSCI API and if valid,
3256 specific local states. If the ``power_state`` is invalid, the platform must
3257 return PSCI_E_INVALID_PARAMS as error, which is propagated back to the
3263 This function is called by the PSCI implementation during the ``CPU_SUSPEND``,
3264 ``SYSTEM_SUSPEND`` and ``CPU_ON`` calls to validate the non-secure ``entry_point``
3265 parameter passed by the normal world. If the ``entry_point`` is invalid,
3266 the platform must return PSCI_E_INVALID_ADDRESS as error, which is
3267 propagated back to the normal world PSCI client.
3272 This function is called by the PSCI implementation during the ``SYSTEM_SUSPEND``
3273 call to get the ``req_state`` parameter from platform which encodes the power
3275 ``req_state`` will be utilized to do the PSCI state coordination and
3276 ``pwr_domain_suspend()`` will be invoked with the coordinated target state to
3282 This is an optional function and, if implemented, is invoked by the PSCI
3283 implementation to convert the ``local_state`` (first argument) at a specified
3285 ``PLAT_MAX_PWR_LVL_STATES`` - 1. This function is only needed if the platform
3293 This is an optional function and, if implemented, verifies the ``power_state``
3294 (second argument) parameter of the PSCI API corresponding to a target power
3296 argument) and the power domain level encoded in ``power_state``. The power domain
3298 populated in the ``output_state`` (third argument) array. The functionality
3299 is similar to the ``validate_power_state`` function described above and is
3300 envisaged to be used in case the validity of ``power_state`` depend on the
3301 targeted power domain. If the ``power_state`` is invalid for the targeted power
3302 domain, the platform must return PSCI_E_INVALID_PARAMS as error. If this
3303 function is not implemented, then the generic implementation relies on
3304 ``validate_power_state`` function to translate the ``power_state``.
3306 This function can also be used in case the platform wants to support local
3314 the power state of a node (identified by the first parameter, the ``MPIDR``) in
3315 the power domain topology (identified by the second parameter, ``power_level``),
3316 as retrieved from a power controller or equivalent component on the platform.
3317 Upon successful completion, the implementation must map and return the final
3329 called during the ``SYSTEM_RESET2`` call to perform a reset
3330 based on the first parameter ``reset_type`` as specified in
3332 reset information. If the ``reset_type`` is not supported, the
3336 in `PSCI`_. If this function returns success, the caller will call
3342 This is an optional function. If implemented it enables or disables the
3343 ``MEM_PROTECT`` functionality based on the value of ``val``.
3351 This is an optional function. If implemented it returns the current
3352 state of ``MEM_PROTECT`` via the ``val`` parameter.  Upon encountering
3361 bytes is protected by ``MEM_PROTECT``.  If the region is protected
3369 During PSCI power management operations, the EL3 Runtime Software may
3376 of the EL3 Runtime Software context. Also if the EL3 Runtime Software makes
3379 to the current CPU must be disabled or re-targeted to other running CPU prior
3380 to power down of the current CPU. During power up, these interrupt can be
3381 enabled/re-targeted back to the current CPU.
3402    PSCI_CPU_OFF APIs respectively. The ``svc_on_finish`` is called when the
3403    target CPU of PSCI_CPU_ON API powers up and executes the
3410    called when the CPU wakes up from suspend and executes the
3412    (first parameter) denotes the highest power domain level being powered down
3424    correspond to the return value of PSCI_MIGRATE_INFO_TYPE API as described
3425    in `PSCI`_. If the secure payload is a Uniprocessor (UP)
3426    implementation, then it must update the mpidr of the CPU it is resident in
3428    ignored if the secure payload is a multiprocessor (MP) implementation.
3432    This callback is only relevant if the secure payload in EL3 Runtime
3434    the current CPU ``from_cpu`` (first argument) to another CPU ``to_cpu``
3436    API. This callback is never called if the secure payload is a
3443 generated in either security state and targeted to EL1 or EL2 in the non-secure
3444 state or EL3/S-EL1 in the secure state. The design of this framework is
3445 described in the :ref:`Interrupt Management Framework`
3447 A platform should export the following APIs to support the IMF. The following
3449 platforms. The API implementation depends upon the type of interrupt controller
3450 present in the platform. Arm standard platform layer supports both
3452 and `3.0 (GICv3)`_. Juno builds the Arm platform layer to use GICv2 and the
3453 FVP can be configured to use either GICv2 or GICv3 depending on the build flag
3467 The Arm processor signals an interrupt exception either through the IRQ or FIQ
3468 interrupt line. The specific line that is signaled depends on how the interrupt
3471 the platform IC uses to signal each type of interrupt supported by the framework
3474 The first parameter will be one of the ``INTR_TYPE_*`` values (see
3475 :ref:`Interrupt Management Framework`) indicating the target type of the
3476 interrupt, the second parameter is the security state of the originating
3477 execution context. The return result is the bit position in the ``SCR_EL3``
3478 register of the respective interrupt trap: IRQ=1, FIQ=2.
3480 In the case of Arm standard platforms using GICv2, S-EL1 interrupts are
3484 In the case of Arm standard platforms using GICv3, the interrupt line to be
3485 configured depends on the security state of the execution context when the
3491    in the NS-EL0/1/2 context.
3503 This API returns the type of the highest priority pending interrupt at the
3504 platform IC. The IMF uses the interrupt type to retrieve the corresponding
3509 In the case of Arm standard platforms using GICv2, the *Highest Priority
3510 Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of
3511 the pending interrupt. The type of interrupt depends upon the id value as
3518 In the case of Arm standard platforms using GICv3, the system register
3520 is read to determine the id of the pending interrupt. The type of interrupt
3521 depends upon the id value as follows.
3536 This API returns the id of the highest priority pending interrupt at the
3540 In the case of Arm standard platforms using GICv2, the *Highest Priority
3541 Pending Interrupt Register* (``GICC_HPPIR``) is read to determine the id of the
3542 pending interrupt. The id that is returned by API depends upon the value of
3543 the id read from the interrupt controller as follows.
3547    (``GICC_AHPPIR``) is read to determine the id of the non-secure interrupt.
3548    This id is returned by the API.
3551 In the case of Arm standard platforms using GICv3, if the API is invoked from
3552 EL3, the system register ``ICC_HPPIR0_EL1``, *Highest Priority Pending Interrupt
3553 group 0 Register*, is read to determine the id of the pending interrupt. The id
3554 that is returned by API depends upon the value of the id read from the
3560    Register* is read to determine the id of the group 1 interrupt. This id
3561    is returned by the API as long as it is a valid interrupt id
3562 #. If the id is any of the special interrupt identifiers,
3565 When the API invoked from S-EL1 for GICv3 systems, the id read from system
3578 This API is used by the CPU to indicate to the platform IC that processing of
3579 the highest pending interrupt has begun. It should return the raw, unmodified
3580 value obtained from the interrupt controller when acknowledging an interrupt.
3581 The actual interrupt number shall be extracted from this raw value using the API
3584 This function in Arm standard platforms using GICv2, reads the *Interrupt
3585 Acknowledge Register* (``GICC_IAR``). This changes the state of the highest
3586 priority pending interrupt from pending to active in the interrupt controller.
3587 It returns the value read from the ``GICC_IAR``, unmodified.
3589 In the case of Arm standard platforms using GICv3, if the API is invoked
3590 from EL3, the function reads the system register ``ICC_IAR0_EL1``, *Interrupt
3591 Acknowledge Register group 0*. If the API is invoked from S-EL1, the function
3592 reads the system register ``ICC_IAR1_EL1``, *Interrupt Acknowledge Register
3593 group 1*. The read changes the state of the highest pending interrupt from
3594 pending to active in the interrupt controller. The value read is returned
3597 The TSP uses this API to start processing of the secure physical timer
3608 This API is used by the CPU to indicate to the platform IC that processing of
3609 the interrupt corresponding to the id (passed as the parameter) has
3610 finished. The id should be the same as the id returned by the
3613 Arm standard platforms write the id to the *End of Interrupt Register*
3615 system register in case of GICv3 depending on where the API is invoked from,
3616 EL3 or S-EL1. This deactivates the corresponding interrupt in the interrupt
3619 The TSP uses this API to finish processing of the secure physical timer
3630 This API returns the type of the interrupt id passed as the parameter.
3631 ``INTR_TYPE_INVAL`` is returned if the id is invalid. If the id is valid, a valid
3633 returned depending upon how the interrupt has been configured by the platform
3637 and Non-secure interrupts as Group1 interrupts. It reads the group value
3638 corresponding to the interrupt id from the relevant *Interrupt Group Register*
3639 (``GICD_IGROUPRn``). It uses the group value to determine the type of interrupt.
3641 In the case of Arm standard platforms using GICv3, both the *Interrupt Group
3643 (``GICD_IGRPMODRn``) is read to figure out whether the interrupt is configured
3649 Platforms will need to implement the TF-A console framework to register and use
3651 the different stages of the firmware boot process and also for debugging purposes.
3654 TF-A supported UARTs. Multiple consoles can be registered at the same time with
3658 Information for registering a console can be found in the :ref:`Console Framework` section
3659 of the :ref:`System Design` documentation.
3702 BL31 implements a crash reporting mechanism which prints the various registers
3703 of the CPU to enable quick crash analysis and debugging. This mechanism relies
3704 on the platform implementing ``plat_crash_console_init``,
3709 makefiles in order to benefit from them. By default, they will cause the crash
3710 output to be routed over the normal console infrastructure and get printed on
3716    use in the crash scope that are able to support this, i.e. that are written
3717    in assembly and conform with the register clobber rules for putc()
3720 In some cases (such as debugging very early crashes that happen before the
3736 This API is used by the crash reporting mechanism to initialize the crash
3737 console. It must only use the general purpose registers x0 through x7 to do the
3748 This API is used by the crash reporting mechanism to print a character on the
3750 x2 to do its work. The parameter and the return value are in general purpose
3761 This API is used by the crash reporting mechanism to force write of all buffered
3762 data on the designated crash console. It should only use general purpose
3773 This API is used to setup the early console, it is required only if the flag
3781 If any cores on the platform support powerdown abandon (check the "Core powerup
3784 after the powerdown ``wfi``. In other words it may run after a call to
3790 powerdown hooks to prevent deadlocks due to a RAS error after the point of no
3791 return. See the core's TRM for further information.
3805 This function is invoked by the runtime exception handling framework for the
3806 platform to handle an External Abort received at EL3. The intention of the
3807 function is to attempt to resolve the cause of External Abort and return;
3808 if that's not possible then an orderly shutdown of the system is initiated.
3810 The first parameter (``int ea_reason``) indicates the reason for External Abort.
3813 The second parameter (``uint64_t syndrome``) is the respective syndrome
3814 presented to EL3 after having received the External Abort. Depending on the
3815 nature of the abort (as can be inferred from the ``ea_reason`` parameter), this
3816 can be the content of either ``ESR_EL3`` or ``DISR_EL1``.
3819 (``void *handle``) is a pointer to the preempted context. The fifth parameter
3820 (``uint64_t flags``) indicates the preempted security state. These parameters
3821 are received from the top-level exception handler.
3835 This function is invoked by the RAS framework when an External Abort of
3836 Uncontainable type is received at EL3. Due to the critical nature of
3837 Uncontainable errors, the intention of this function is to initiate orderly
3838 shutdown of the system, and is not expected to return.
3842 The first and second parameters are the same as that of ``plat_ea_handler``.
3856 This function is invoked by the RAS framework when another External Abort is
3858 ``plat_ea_handler`` is outstanding. Due to its critical nature, the intention of
3859 this function is to initiate orderly shutdown of the system, and is not expected
3864 The first and second parameters are the same as that of ``plat_ea_handler``.
3877 EL3. Due to its critical nature, the intention of this function is to initiate
3878 orderly shutdown of the system, and is not expected recover or return.
3895 system register trap caused by access to the RNDR or RNDRRS registers. It allows
3897 emulate those system registers by returing back some entropy to the lower EL.
3899 The first parameter (``uint64_t esr_el3``) contains the content of the ESR_EL3
3900 syndrome register, which encodes the instruction that was trapped. The interesting
3901 information in there is the target register (``get_sysreg_iss_rt()``).
3903 The second parameter (``cpu_context_t *ctx``) represents the CPU state in the
3904 lower exception level, at the time when the execution of the ``mrs`` instruction
3905 was trapped. Its content can be changed, to put the entropy into the target
3910 -  When returning ``TRAP_RET_UNHANDLED`` (-1), the machine will panic.
3911 -  When returning ``TRAP_RET_REPEAT`` (0), the exception handler will return
3912    to the same instruction, so its execution will be repeated.
3913 -  When returning ``TRAP_RET_CONTINUE`` (1), the exception handler will return
3914    to the next instruction.
3928 system register trap caused by access to the implementation defined registers.
3931 ``ARCH_FEATURE_AVAILABILITY``, the macros
3935 The first parameter (``uint64_t esr_el3``) contains the content of the ESR_EL3
3936 syndrome register, which encodes the instruction that was trapped.
3938 The second parameter (``cpu_context_t *ctx``) represents the CPU state in the
3939 lower exception level, at the time when the execution of the ``mrs`` instruction
3944 -  When returning ``TRAP_RET_UNHANDLED`` (-1), the machine will panic.
3945 -  When returning ``TRAP_RET_REPEAT`` (0), the exception handler will return
3946    to the same instruction, so its execution will be repeated.
3947 -  When returning ``TRAP_RET_CONTINUE`` (1), the exception handler will return
3948    to the next instruction.
3956 There are some build flags which can be defined by the platform to control
3957 inclusion or exclusion of certain BL stages from the FIP image. These flags
3958 need to be defined in the platform makefile which will get included by the
3962    By default, this flag is defined ``yes`` by the build system and ``BL33``
3963    build option should be supplied as a build option. The platform has the
3964    option of excluding the BL33 image in the ``fip`` image by defining this flag
3965    to ``no``. If any of the options ``EL3_PAYLOAD_BASE`` or ``PRELOADED_BL33_BASE``
3970    if the platform makefile/build defines or uses the correct ARM_ARCH_MAJOR and
3973    the Architecture and available in TF-A can be enabled from platform specific
3980 Platforms are allowed to add more include paths to be passed to the compiler.
3982 particular for the file ``platform_def.h``.
3993 To avoid subtle toolchain behavioral dependencies, the header files provided
3994 by the compiler are not used. The software is built with the ``-nostdinc`` flag
3995 to ensure no headers are included from the toolchain inadvertently. Instead the
3996 required headers are included in the TF-A source tree. The library only
3997 contains those C library definitions required by the local implementation. If
3998 more functionality is required, the needed library functions will need to be
3999 added to the local implementation.
4006 SCC can be found in http://www.simple-cc.org/. A copy of the `FreeBSD`_ sources
4014 storage access is only required by BL1 and BL2 phases and performed inside the
4019 It is mandatory to implement at least one storage driver. For the Arm
4020 development platforms the Firmware Image Package (FIP) driver is provided as
4021 the default means to load data from storage (see :ref:`firmware_design_fip`).
4022 The storage layer is described in the header file
4023 ``include/drivers/io/io_storage.h``. The implementation of the common library is
4024 in ``drivers/io/io_storage.c`` and the driver files are located in
4034 Each platform should register devices and their drivers via the storage
4045 The basic operations supported by the layer
4051 The current implementation only allows for known images to be loaded by the
4055 to a device and a driver-specific ``spec`` which will be understood by the driver
4056 to allow access to the image data.
4061 drivers. In such a case, the file-system "binding" with the block device may
4062 be deferred until the file-system device is initialised.
4065 by the drivers and callers, as the system does not yet provide a means of
4066 dynamically allocating memory. This may also have the affect of limiting the
4072 Enabling the MEASURED_BOOT flag adds extra platform requirements. Please refer
4086 This platform API provides the list of LFA components available for activation.
4099 This platform API checks if the specified LFA component, identified
4111 This platform API allows the platform to cancel an ongoing update or activation
4112 process for the specified ``lfa_component_id``. It returns 0 on success or
4123 The platform uses this API to load, authenticate and measure the component
4127 NOTE: The error code -EAGAIN is not treated as an error, it means the operation
4128 is incomplete and the function should be called again by the caller.
4138 This API is invoked by the platform to notify its security engine to initiate
4139 the required steps for component activation. The function takes the component