6.3.1.File : platform_def.h [mandatory]

Each platform must ensure that a header file of this name is in the systeminclude path with the following constants defined. This will require updatingthe list ofPLAT_INCLUDES in theplatform.mk file.

Platform ports may optionally use the fileinclude/plat/common/common_def.h,which provides typical values for some of the constants below. These values arelikely to be suitable for all platform ports.

• #define : PLATFORM_LINKER_FORMAT

  Defines the linker format used by the platform, for exampleelf64-littleaarch64.

• #define : PLATFORM_LINKER_ARCH

  Defines the processor architecture for the linker by the platform, forexampleaarch64.

• #define : PLATFORM_STACK_SIZE

  Defines the normal stack memory available to each CPU. This constant is usedbyplat/common/aarch64/platform_mp_stack.S andplat/common/aarch64/platform_up_stack.S.

• #define : CACHE_WRITEBACK_GRANULE

  Defines the size in bytes of the largest cache line across all the cachelevels in the platform.

• #define : FIRMWARE_WELCOME_STR

  Defines the character string printed by BL1 upon entry into thebl1_main()function.

• #define : PLATFORM_CORE_COUNT

  Defines the total number of CPUs implemented by the platform across allclusters in the system.

• #define : PLAT_NUM_PWR_DOMAINS

  Defines the total number of nodes in the power domain topologytree at all the power domain levels used by the platform.This macro is used by the PSCI implementation to allocatedata structures to represent power domain topology.

• #define : PLAT_MAX_PWR_LVL

  Defines the maximum power domain level that the power management operationsshould apply to. More often, but not always, the power domain levelcorresponds to affinity level. This macro allows the PSCI implementationto know the highest power domain level that it should consider for powermanagement operations in the system that the platform implements. Forexample, the Base AEM FVP implements two clusters with a configurablenumber of CPUs and it reports the maximum power domain level as 1.

• #define : PLAT_MAX_OFF_STATE

  Defines the local power state corresponding to the deepest power downpossible at every power domain level in the platform. The local powerstates for each level may be sparsely allocated between 0 and this valuewith 0 being reserved for the RUN state. The PSCI implementation uses thisvalue to initialize the local power states of the power domain nodes andto specify the requested power state for a PSCI_CPU_OFF call.

• #define : PLAT_MAX_RET_STATE

  Defines the local power state corresponding to the deepest retention statepossible at every power domain level in the platform. This macro should bea value less than PLAT_MAX_OFF_STATE and greater than 0. It is used by thePSCI implementation to distinguish between retention and power down localpower states within PSCI_CPU_SUSPEND call.

• #define : PLAT_MAX_PWR_LVL_STATES

  Defines the maximum number of local power states per power domain levelthat the platform supports. The default value of this macro is 2 sincemost platforms just support a maximum of two local power states at eachpower domain level (power-down and retention). If the platform needs toaccount for more local power states, then it must redefine this macro.

  Currently, this macro is used by the Generic PSCI implementation to sizethe array used for PSCI_STAT_COUNT/RESIDENCY accounting.

• #define : BL1_RO_BASE

  Defines the base address in secure ROM where BL1 originally lives. Must bealigned on a page-size boundary.

• #define : BL1_RO_LIMIT

  Defines the maximum address in secure ROM that BL1’s actual content (i.e.excluding any data section allocated at runtime) can occupy.

• #define : BL1_RW_BASE

  Defines the base address in secure RAM where BL1’s read-write data will liveat runtime. Must be aligned on a page-size boundary.

• #define : BL1_RW_LIMIT

  Defines the maximum address in secure RAM that BL1’s read-write data canoccupy at runtime.

• #define : BL2_BASE

  Defines the base address in secure RAM where BL1 loads the BL2 binary image.Must be aligned on a page-size boundary. This constant is not applicablewhen BL2_IN_XIP_MEM is set to ‘1’.

• #define : BL2_LIMIT

  Defines the maximum address in secure RAM that the BL2 image can occupy.This constant is not applicable when BL2_IN_XIP_MEM is set to ‘1’.

• #define : BL2_RO_BASE

  Defines the base address in secure XIP memory where BL2 RO section originallylives. Must be aligned on a page-size boundary. This constant is only neededwhen BL2_IN_XIP_MEM is set to ‘1’.

• #define : BL2_RO_LIMIT

  Defines the maximum address in secure XIP memory that BL2’s actual content(i.e. excluding any data section allocated at runtime) can occupy. Thisconstant is only needed when BL2_IN_XIP_MEM is set to ‘1’.

• #define : BL2_RW_BASE

  Defines the base address in secure RAM where BL2’s read-write data will liveat runtime. Must be aligned on a page-size boundary. This constant is onlyneeded when BL2_IN_XIP_MEM is set to ‘1’.

• #define : BL2_RW_LIMIT

  Defines the maximum address in secure RAM that BL2’s read-write data canoccupy at runtime. This constant is only needed when BL2_IN_XIP_MEM is setto ‘1’.

• #define : BL31_BASE

  Defines the base address in secure RAM where BL2 loads the BL31 binaryimage. Must be aligned on a page-size boundary.

• #define : BL31_LIMIT

  Defines the maximum address in secure RAM that the BL31 image can occupy.

• #define : PLAT_RSE_COMMS_PAYLOAD_MAX_SIZE

  Defines the maximum message size between AP and RSE. Need to define ifplatform supports RSE.

For every image, the platform must define individual identifiers that will beused by BL1 or BL2 to load the corresponding image into memory from non-volatilestorage. For the sake of performance, integer numbers will be used asidentifiers. The platform will use those identifiers to return the relevantinformation about the image to be loaded (file handler, load address,authentication information, etc.). The following image identifiers aremandatory:

• #define : BL2_IMAGE_ID

  BL2 image identifier, used by BL1 to load BL2.

• #define : BL31_IMAGE_ID

  BL31 image identifier, used by BL2 to load BL31.

• #define : BL33_IMAGE_ID

  BL33 image identifier, used by BL2 to load BL33.

If Trusted Board Boot is enabled, the following certificate identifiers mustalso be defined:

• #define : TRUSTED_BOOT_FW_CERT_ID

  BL2 content certificate identifier, used by BL1 to load the BL2 contentcertificate.

• #define : TRUSTED_KEY_CERT_ID

  Trusted key certificate identifier, used by BL2 to load the trusted keycertificate.

• #define : SOC_FW_KEY_CERT_ID

  BL31 key certificate identifier, used by BL2 to load the BL31 keycertificate.

• #define : SOC_FW_CONTENT_CERT_ID

  BL31 content certificate identifier, used by BL2 to load the BL31 contentcertificate.

• #define : NON_TRUSTED_FW_KEY_CERT_ID

  BL33 key certificate identifier, used by BL2 to load the BL33 keycertificate.

• #define : NON_TRUSTED_FW_CONTENT_CERT_ID

  BL33 content certificate identifier, used by BL2 to load the BL33 contentcertificate.

• #define : FWU_CERT_ID

  Firmware Update (FWU) certificate identifier, used by NS_BL1U to load theFWU content certificate.

If the AP Firmware Updater Configuration image, BL2U is used, the followingmust also be defined:

• #define : BL2U_BASE

  Defines the base address in secure memory where BL1 copies the BL2U binaryimage. Must be aligned on a page-size boundary.

• #define : BL2U_LIMIT

  Defines the maximum address in secure memory that the BL2U image can occupy.

• #define : BL2U_IMAGE_ID

  BL2U image identifier, used by BL1 to fetch an image descriptorcorresponding to BL2U.

If the SCP Firmware Update Configuration Image, SCP_BL2U is used, the followingmust also be defined:

• #define : SCP_BL2U_IMAGE_ID

  SCP_BL2U image identifier, used by BL1 to fetch an image descriptorcorresponding to SCP_BL2U.

  Note

  TF-A does not provide source code for this image.

If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following mustalso be defined:

• #define : NS_BL1U_BASE

  Defines the base address in non-secure ROM where NS_BL1U executes.Must be aligned on a page-size boundary.

  Note

  TF-A does not provide source code for this image.

• #define : NS_BL1U_IMAGE_ID

  NS_BL1U image identifier, used by BL1 to fetch an image descriptorcorresponding to NS_BL1U.

If the Non-Secure Firmware Updater, NS_BL2U is used, the following must alsobe defined:

• #define : NS_BL2U_BASE

  Defines the base address in non-secure memory where NS_BL2U executes.Must be aligned on a page-size boundary.

  Note

  TF-A does not provide source code for this image.

• #define : NS_BL2U_IMAGE_ID

  NS_BL2U image identifier, used by BL1 to fetch an image descriptorcorresponding to NS_BL2U.

For the the Firmware update capability of TRUSTED BOARD BOOT, the followingmacros may also be defined:

• #define : PLAT_FWU_MAX_SIMULTANEOUS_IMAGES

  Total number of images that can be loaded simultaneously. If the platformdoesn’t specify any value, it defaults to 10.

If a SCP_BL2 image is supported by the platform, the following constants mustalso be defined:

• #define : SCP_BL2_IMAGE_ID

  SCP_BL2 image identifier, used by BL2 to load SCP_BL2 into secure memoryfrom platform storage before being transferred to the SCP.

• #define : SCP_FW_KEY_CERT_ID

  SCP_BL2 key certificate identifier, used by BL2 to load the SCP_BL2 keycertificate (mandatory when Trusted Board Boot is enabled).

• #define : SCP_FW_CONTENT_CERT_ID

  SCP_BL2 content certificate identifier, used by BL2 to load the SCP_BL2content certificate (mandatory when Trusted Board Boot is enabled).

If a BL32 image is supported by the platform, the following constants mustalso be defined:

• #define : BL32_IMAGE_ID

  BL32 image identifier, used by BL2 to load BL32.

• #define : TRUSTED_OS_FW_KEY_CERT_ID

  BL32 key certificate identifier, used by BL2 to load the BL32 keycertificate (mandatory when Trusted Board Boot is enabled).

• #define : TRUSTED_OS_FW_CONTENT_CERT_ID

  BL32 content certificate identifier, used by BL2 to load the BL32 contentcertificate (mandatory when Trusted Board Boot is enabled).

• #define : BL32_BASE

  Defines the base address in secure memory where BL2 loads the BL32 binaryimage. Must be aligned on a page-size boundary.

• #define : BL32_LIMIT

  Defines the maximum address that the BL32 image can occupy.

If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by theplatform, the following constants must also be defined:

• #define : TSP_SEC_MEM_BASE

  Defines the base address of the secure memory used by the TSP image on theplatform. This must be at the same address or belowBL32_BASE.

• #define : TSP_SEC_MEM_SIZE

  Defines the size of the secure memory used by the BL32 image on theplatform.TSP_SEC_MEM_BASE andTSP_SEC_MEM_SIZE must fullyaccommodate the memory required by the BL32 image, defined byBL32_BASEandBL32_LIMIT.

• #define : TSP_IRQ_SEC_PHY_TIMER

  Defines the ID of the secure physical generic timer interrupt used by theTSP’s interrupt handling code.

If the platform port uses the translation table library code, the followingconstants must also be defined:

• #define : PLAT_XLAT_TABLES_DYNAMIC

  Optional flag that can be set per-image to enable the dynamic allocation ofregions even when the MMU is enabled. If not defined, only staticfunctionality will be available, if defined and set to 1 it will alsoinclude the dynamic functionality.

• #define : MAX_XLAT_TABLES

  Defines the maximum number of translation tables that are allocated by thetranslation table library code. To minimize the amount of runtime memoryused, choose the smallest value needed to map the required virtual addressesfor each BL stage. IfPLAT_XLAT_TABLES_DYNAMIC flag is enabled for a BLimage,MAX_XLAT_TABLES must be defined to accommodate the dynamic regionsas well.

• #define : MAX_MMAP_REGIONS

  Defines the maximum number of regions that are allocated by the translationtable library code. A region consists of physical base address, virtual baseaddress, size and attributes (Device/Memory, RO/RW, Secure/Non-Secure), asdefined in themmap_region_t structure. The platform defines the regionsthat should be mapped. Then, the translation table library will create thecorresponding tables and descriptors at runtime. To minimize the amount ofruntime memory used, choose the smallest value needed to register therequired regions for each BL stage. IfPLAT_XLAT_TABLES_DYNAMIC flag isenabled for a BL image,MAX_MMAP_REGIONS must be defined to accommodatethe dynamic regions as well.

• #define : PLAT_VIRT_ADDR_SPACE_SIZE

  Defines the total size of the virtual address space in bytes. For example,for a 32 bit virtual address space, this value should be(1ULL<<32).

• #define : PLAT_PHY_ADDR_SPACE_SIZE

  Defines the total size of the physical address space in bytes. For example,for a 32 bit physical address space, this value should be(1ULL<<32).

If the platform port uses the IO storage framework, the following constantsmust also be defined:

• #define : MAX_IO_DEVICES

  Defines the maximum number of registered IO devices. Attempting to registermore devices than this value usingio_register_device() will fail with-ENOMEM.

• #define : MAX_IO_HANDLES

  Defines the maximum number of open IO handles. Attempting to open more IOentities than this value usingio_open() will fail with -ENOMEM.

• #define : MAX_IO_BLOCK_DEVICES

  Defines the maximum number of registered IO block devices. Attempting toregister more devices this value usingio_dev_open() will failwith -ENOMEM. MAX_IO_BLOCK_DEVICES should be less than MAX_IO_DEVICES.With this macro, multiple block devices could be supported at the sametime.

If the platform needs to allocate data within the per-cpu data framework inBL31, it should define the following macro. Currently this is only required ifthe platform decides not to use the coherent memory section by undefining theUSE_COHERENT_MEM build flag. In this case, the framework allocates therequired memory within the the per-cpu data to minimize wastage.

• #define : PLAT_PCPU_DATA_SIZE

  Defines the memory (in bytes) to be reserved within the per-cpu datastructure for use by the platform layer.

The following constants are optional. They should be defined when the platformmemory layout implies some image overlaying like in Arm standard platforms.

• #define : BL31_PROGBITS_LIMIT

  Defines the maximum address in secure RAM that the BL31’s progbits sectionscan occupy.

• #define : TSP_PROGBITS_LIMIT

  Defines the maximum address that the TSP’s progbits sections can occupy.

If the platform supports OS-initiated mode, i.e. the build optionPSCI_OS_INIT_MODE is enabled, and if the platform’s maximum power domainlevel for PSCI_CPU_SUSPEND differs fromPLAT_MAX_PWR_LVL, the followingconstant must be defined.

• #define : PLAT_MAX_CPU_SUSPEND_PWR_LVL

  Defines the maximum power domain level that PSCI_CPU_SUSPEND should apply to.

If the platform port uses the PL061 GPIO driver, the following constant mayoptionally be defined:

• PLAT_PL061_MAX_GPIOSMaximum number of GPIOs required by the platform. This allows control howmuch memory is allocated for PL061 GPIO controllers. The default value is

  1. $(eval $(call add_define,PLAT_PL061_MAX_GPIOS))

If the platform port uses the partition driver, the following constant mayoptionally be defined:

• PLAT_PARTITION_MAX_ENTRIESMaximum number of partition entries required by the platform. This allowscontrol how much memory is allocated for partition entries. The defaultvalue is 128.For example, define the build flag inplatform.mk:PLAT_PARTITION_MAX_ENTRIES := 12$(eval $(call add_define,PLAT_PARTITION_MAX_ENTRIES))

• PLAT_PARTITION_BLOCK_SIZEThe size of partition block. It could be either 512 bytes or 4096 bytes.The default value is 512.For example, define the build flag inplatform.mk:PLAT_PARTITION_BLOCK_SIZE := 4096$(eval $(call add_define,PLAT_PARTITION_BLOCK_SIZE))

If the platform port uses the Arm® Ethos™-N NPU driver, the followingconfiguration must be performed:

• The NPU SiP service handler must be hooked up. This consists of both theinitial setup (ethosn_smc_setup) and the handler itself(ethosn_smc_handler)

If the platform port uses the Arm® Ethos™-N NPU driver with TZMP1 supportenabled, the following constants and configuration must also be defined:

• ETHOSN_NPU_PROT_FW_NSAID

  Defines the Non-secure Access IDentity (NSAID) that the NPU shall use toaccess the protected memory that contains the NPU’s firmware.

• ETHOSN_NPU_PROT_DATA_RW_NSAID

  Defines the Non-secure Access IDentity (NSAID) that the NPU shall use forread/write access to the protected memory that contains inference data.

• ETHOSN_NPU_PROT_DATA_RO_NSAID

  Defines the Non-secure Access IDentity (NSAID) that the NPU shall use forread-only access to the protected memory that contains inference data.

• ETHOSN_NPU_NS_RW_DATA_NSAID

  Defines the Non-secure Access IDentity (NSAID) that the NPU shall use forread/write access to the non-protected memory.

• ETHOSN_NPU_NS_RO_DATA_NSAID

  Defines the Non-secure Access IDentity (NSAID) that the NPU shall use forread-only access to the non-protected memory.

• ETHOSN_NPU_FW_IMAGE_BASE andETHOSN_NPU_FW_IMAGE_LIMIT

  Defines the physical address range that the NPU’s firmware will be loadedinto and executed from.

• Configure the platforms TrustZone Controller (TZC) with appropriate regionsof protected memory. At minimum this must include a region for the NPU’sfirmware code and a region for protected inference data, and these must beaccessible using the NSAIDs defined above.

• Include the NPU firmware and certificates in the FIP.

• Provide FCONF entries to configure the image source for the NPU firmwareand certificates.

• Add MMU mappings such that:

• BL2 can write the NPU firmware into the region defined byETHOSN_NPU_FW_IMAGE_BASE andETHOSN_NPU_FW_IMAGE_LIMIT

• BL31 (SiP service) can read the NPU firmware from the same region

• Add the firmware image IDETHOSN_NPU_FW_IMAGE_ID to the list of imagesloaded by BL2.

Please see the reference implementation code for the Juno platform as an example.

The following constant is optional. It should be defined to override the defaultbehaviour of theassert() function (for example, to save memory).

• PLAT_LOG_LEVEL_ASSERTIfPLAT_LOG_LEVEL_ASSERT is higher or equal thanLOG_LEVEL_VERBOSE,assert() prints the name of the file, the line number and the assertedexpression. Else if it is higher thanLOG_LEVEL_INFO, it prints the filename and the line number. Else if it is lower thanLOG_LEVEL_INFO, itdoesn’t print anything to the console. IfPLAT_LOG_LEVEL_ASSERT isn’tdefined, it defaults toLOG_LEVEL.

If the platform port uses the DRTM feature, the following constants must bedefined:

• #define : PLAT_DRTM_EVENT_LOG_MAX_SIZE

  Maximum Event Log size used by the platform. Platform can decide the maximumsize of the Event Log buffer, depending upon the highest hash algorithmchosen and the number of components selected to measure during the DRTMexecution flow.

• #define : PLAT_DRTM_MMAP_ENTRIES

  Number of the MMAP entries used by the DRTM implementation to calculate thesize of address map region of the platform.

6.3.2.File : plat_macros.S [mandatory]

Each platform must ensure a file of this name is in the system include path withthe following macro defined. In the Arm development platforms, this file isfound inplat/arm/board/<plat_name>/include/plat_macros.S.

• Macro : plat_crash_print_regs

  This macro allows the crash reporting routine to print relevant platformregisters in case of an unhandled exception in BL31. This aids in debuggingand this macro can be defined to be empty in case register reporting is notdesired.

  For instance, GIC or interconnect registers may be helpful fortroubleshooting.

6.4.1.Function : plat_get_my_entrypoint() [mandatory when PROGRAMMABLE_RESET_ADDRESS == 0]

Argument:voidReturn:uintptr_t

This function is called with the MMU and caches disabled(SCTLR_EL3.M = 0 andSCTLR_EL3.C = 0). The function is responsible fordistinguishing between a warm and cold reset for the current CPU usingplatform-specific means. If it’s a warm reset, then it returns the warmreset entrypoint point provided toplat_setup_psci_ops() duringBL31 initialization. If it’s a cold reset then this function must return zero.

This function does not follow the Procedure Call Standard used by theApplication Binary Interface for the Arm 64-bit architecture. The caller shouldnot assume that callee saved registers are preserved across a call to thisfunction.

This function fulfills requirement 1 and 3 listed above.

Note that for platforms that support programming the reset address, it isexpected that a CPU will start executing code directly at the right address,both on a cold and warm reset. In this case, there is no need to identify thetype of reset nor to query the warm reset entrypoint. Therefore, implementingthis function is not required on such platforms.

6.4.2.Function : plat_secondary_cold_boot_setup() [mandatory when COLD_BOOT_SINGLE_CPU == 0]

Argument:void

This function is called with the MMU and data caches disabled. It is responsiblefor placing the executing secondary CPU in a platform-specific state until theprimary CPU performs the necessary actions to bring it out of that state andallow entry into the OS. This function must not return.

In the Arm FVP port, when using the normal boot flow, each secondary CPU powersitself off. The primary CPU is responsible for powering up the secondary CPUswhen normal world software requires them. When booting an EL3 payload instead,they stay powered on and are put in a holding pen until their mailbox getspopulated.

This function fulfills requirement 2 above.

Note that for platforms that can’t release secondary CPUs out of reset, only theprimary CPU will execute the cold boot code. Therefore, implementing thisfunction is not required on such platforms.

6.4.3.Function : plat_is_my_cpu_primary() [mandatory when COLD_BOOT_SINGLE_CPU == 0]

Argument:voidReturn:unsignedint

This function identifies whether the current CPU is the primary CPU or asecondary CPU. A return value of zero indicates that the CPU is not theprimary CPU, while a non-zero return value indicates that the CPU is theprimary CPU.

Note that for platforms that can’t release secondary CPUs out of reset, only theprimary CPU will execute the cold boot code. Therefore, there is no need todistinguish between primary and secondary CPUs and implementing this function isnot required.

6.4.4.Function : platform_mem_init() [mandatory]

Argument:voidReturn:void

This function is called before any access to data is made by the firmware, inorder to carry out any essential memory initialization.

6.4.5.Function: plat_get_rotpk_info()

Argument:void*,void**,unsignedint*,unsignedint*Return:int

This function is mandatory when Trusted Board Boot is enabled. It returns apointer to the ROTPK stored in the platform (or a hash of it) and its length.The ROTPK must be encoded in DER format according to the following ASN.1structure:

AlgorithmIdentifier::=SEQUENCE{algorithmOBJECTIDENTIFIER,parametersANYDEFINEDBYalgorithmOPTIONAL}SubjectPublicKeyInfo::=SEQUENCE{algorithmAlgorithmIdentifier,subjectPublicKeyBITSTRING}

In case the function returns a hash of the key:

DigestInfo::=SEQUENCE{digestAlgorithmAlgorithmIdentifier,digestOCTETSTRING}

The function returns 0 on success. Any other value is treated as error by theTrusted Board Boot. The function also reports extra information relatedto the ROTPK in the flags parameter:

ROTPK_IS_HASH:IndicatesthattheROTPKreturnedbytheplatformisahash.ROTPK_NOT_DEPLOYED:ThisallowstheplatformtoskipcertificateROTPKverificationwhiletheplatformROTPKisnotdeployed.Whenthisflagisset,thefunctiondoesnotneedtoreturnaplatformROTPK,andtheauthenticationframeworkusestheROTPKinthecertificatewithoutverifyingitagainsttheplatformvalue.Thisflagmustnotbeusedinadeployedproductionenvironment.

6.4.6.Function: plat_get_nv_ctr()

Argument:void*,unsignedint*Return:int

This function is mandatory when Trusted Board Boot is enabled. It returns thenon-volatile counter value stored in the platform in the second argument. Thecookie in the first argument may be used to select the counter in case theplatform provides more than one (for example, on platforms that use the defaultTBBR CoT, the cookie will correspond to the OID values defined inTRUSTED_FW_NVCOUNTER_OID or NON_TRUSTED_FW_NVCOUNTER_OID).

The function returns 0 on success. Any other value means the counter value couldnot be retrieved from the platform.

6.4.7.Function: plat_set_nv_ctr()

Argument:void*,unsignedintReturn:int

This function is mandatory when Trusted Board Boot is enabled. It sets a newcounter value in the platform. The cookie in the first argument may be used toselect the counter (as explained in plat_get_nv_ctr()). The second argument isthe updated counter value to be written to the NV counter.

The function returns 0 on success. Any other value means the counter value couldnot be updated.

6.4.8.Function: plat_set_nv_ctr2()

Argument:void*,constauth_img_desc_t*,unsignedintReturn:int

This function is optional when Trusted Board Boot is enabled. If thisinterface is defined, thenplat_set_nv_ctr() need not be defined. Thefirst argument passed is a cookie and is typically used todifferentiate between a Non Trusted NV Counter and a Trusted NVCounter. The second argument is a pointer to an authentication imagedescriptor and may be used to decide if the counter is allowed to beupdated or not. The third argument is the updated counter value tobe written to the NV counter.

The function returns 0 on success. Any other value means the counter valueeither could not be updated or the authentication image descriptor indicatesthat it is not allowed to be updated.

6.5.1.Function : plat_get_addr_mmap()

Argument:voidReturn:constmmap_region_t*

This function is used to return the address of the platformaddress-map table,which describes the regions of normal memory, memory mapped I/Oand non-volatile memory.

6.5.2.Function : plat_has_non_host_platforms()

Argument:voidReturn:bool

This function returnstrue if the platform has any trusted devices capable ofDMA, otherwise returnsfalse.

6.5.3.Function : plat_has_unmanaged_dma_peripherals()

Argument:voidReturn:bool

This function returnstrue if platform uses peripherals whose DMA is notmanaged by an SMMU, otherwise returnsfalse.

Note -If the platform has peripherals that are not managed by the SMMU, then theplatform should investigate such peripherals to determine whether they canbe trusted, and such peripherals should be moved under “Non-host platforms”if they can be trusted.

6.5.4.Function : plat_get_total_num_smmus()

Argument:voidReturn:unsignedint

This function returns the total number of SMMUs in the platform.

6.5.5.Function : plat_enumerate_smmus()

Argument:voidReturn:constuintptr_t*,size_t

This function returns an array of SMMU addresses and the actual number of SMMUsreported by the platform.

6.5.6.Function : plat_drtm_get_dma_prot_features()

Argument:voidReturn:constplat_drtm_dma_prot_features_t*

This function returns the address of plat_drtm_dma_prot_features_t structurecontaining the maximum number of protected regions and bitmap with the typesof DMA protection supported by the platform.For more details see section 3.3 Table 6 ofDRTM specification.

6.5.7.Function : plat_drtm_dma_prot_get_max_table_bytes()

Argument:voidReturn:uint64_t

This function returns the maximum size of DMA protected regions table inbytes.

6.5.8.Function : plat_drtm_get_tpm_features()

Argument:voidReturn:constplat_drtm_tpm_features_t*

This function returns the address ofplat_drtm_tpm_features_t structurecontaining PCR usage schema, TPM-based hash, and firmware hash algorithmsupported by the platform.

6.5.9.Function : plat_drtm_get_min_size_normal_world_dce()

Argument:voidReturn:uint64_t

This function returns the size normal-world DCE of the platform.

6.5.10.Function : plat_drtm_get_imp_def_dlme_region_size()

Argument:voidReturn:uint64_t

This function returns the size of implementation defined DLME regionof the platform.

6.5.11.Function : plat_drtm_get_tcb_hash_table_size()

Argument:voidReturn:uint64_t

This function returns the size of TCB hash table of the platform.

6.5.12.Function : plat_drtm_get_acpi_tables_region_size()

Argument:voidReturn:uint64_t

This function returns the size of ACPI tables region of the platform.

6.5.13.Function : plat_drtm_get_tcb_hash_features()

Argument:voidReturn:uint64_t

This function returns the Maximum number of TCB hashes recorded by theplatform.For more details see section 3.3 Table 6 ofDRTM specification.

6.5.14.Function : plat_drtm_get_dlme_img_auth_features()

Argument:voidReturn:uint64_t

This function returns the DLME image authentication features.For more details see section 3.3 Table 6 ofDRTM specification.

6.5.15.Function : plat_drtm_validate_ns_region()

Argument:uintptr_t,uintptr_tReturn:int

This function validates that given region is within the Non-Secure regionof DRAM. This function takes a region start address and size an inputarguments, and returns 0 on success and -1 on failure.

6.5.16.Function : plat_set_drtm_error()

Argument:uint64_tReturn:int

This function writes a 64 bit error code received as input intonon-volatile storage and returns 0 on success and -1 on failure.

6.5.17.Function : plat_get_drtm_error()

Argument:uint64_t*Return:int

This function reads a 64 bit error code from the non-volatile storageinto the received address, and returns 0 on success and -1 on failure.

6.6.1.Function : plat_my_core_pos()

Argument:voidReturn:unsignedint

This function returns the index of the calling CPU which is used as aCPU-specific linear index into blocks of memory (for example while allocatingper-CPU stacks). This function will be invoked very early in theinitialization sequence which mandates that this function should beimplemented in assembly and should not rely on the availability of a Cruntime environment. This function can clobber x0 - x8 and must preservex9 - x29.

This function plays a crucial role in the power domain topology framework inPSCI and details of this can be found inPSCI Power Domain Tree Structure.

6.6.2.Function : plat_core_pos_by_mpidr()

Argument:u_register_tReturn:int

This function validates theMPIDR of a CPU and converts it to an index,which can be used as a CPU-specific linear index into blocks of memory. Incase theMPIDR is invalid, this function returns -1. This function will onlybe invoked by BL31 after the power domain topology is initialized and canutilize the C runtime environment. For further details about how TF-Arepresents the power domain topology and how this relates to the linear CPUindex, please referPSCI Power Domain Tree Structure.

6.6.3.Function : plat_get_mbedtls_heap() [when TRUSTED_BOARD_BOOT == 1]

Arguments:void**heap_addr,size_t*heap_sizeReturn:int

This function is invoked during Mbed TLS library initialisation to get a heap,by means of a starting address and a size. This heap will then be usedinternally by the Mbed TLS library. Hence, each BL stage that utilises Mbed TLSmust be able to provide a heap to it.

A helper function can be found indrivers/auth/mbedtls/mbedtls_common.c inwhich a heap is statically reserved during compile time inside every image(i.e. every BL stage) that utilises Mbed TLS. In this default implementation,the function simply returns the address and size of this “pre-allocated” heap.For a platform to use this default implementation, only a call to the helperfrom inside plat_get_mbedtls_heap() body is enough and nothing else is needed.

However, by writting their own implementation, platforms have the potential tooptimise memory usage. For example, on some Arm platforms, the Mbed TLS heap isshared between BL1 and BL2 stages and, thus, the necessary space is not reservedtwice.

On success the function should return 0 and a negative error code otherwise.

6.6.4.Function : plat_get_enc_key_info() [when FW_ENC_STATUS == 0 or 1]

Arguments:enumfw_enc_status_tfw_enc_status,uint8_t*key,size_t*key_len,unsignedint*flags,constuint8_t*img_id,size_timg_id_lenReturn:int

This function provides a symmetric key (either SSK or BSSK depending onfw_enc_status) which is invoked during runtime decryption of encryptedfirmware images.plat/common/plat_bl_common.c provides a dummy weakimplementation for testing purposes which must be overridden by the platformtrying to implement a real world firmware encryption use-case.

It also allows the platform to pass symmetric key identifier rather thanactual symmetric key which is useful in cases where the crypto backend providessecure storage for the symmetric key. So in this caseENC_KEY_IS_IDENTIFIERflag must be set inflags.

In addition to above a platform may also choose to provide an image specificsymmetric key/identifier using img_id.

On success the function should return 0 and a negative error code otherwise.

Note that this API depends onDECRYPTION_SUPPORT build flag.

6.6.5.Function : plat_fwu_set_images_source() [when PSA_FWU_SUPPORT == 1]

Argument:conststructfwu_metadata*metadataReturn:void

This function is mandatory when PSA_FWU_SUPPORT is enabled.It provides a means to retrieve image specification (offset innon-volatile storage and length) of active/updated images using the passedFWU metadata, and update I/O policies of active/updated images using retrievedimage specification information.Further I/O layer operations such as I/O open, I/O read, etc. on theseimages rely on this function call.

In Arm platforms, this function is used to set an I/O policy of the FIP image,container of all active/updated secure and non-secure images.

6.6.6.Function : plat_fwu_set_metadata_image_source() [when PSA_FWU_SUPPORT == 1]

Argument:unsignedintimage_id,uintptr_t*dev_handle,uintptr_t*image_specReturn:int

This function is mandatory when PSA_FWU_SUPPORT is enabled. It isresponsible for setting up the platform I/O policy of the requested metadataimage (either FWU_METADATA_IMAGE_ID or BKUP_FWU_METADATA_IMAGE_ID) that willbe used to load this image from the platform’s non-volatile storage.

FWU metadata can not be always stored as a raw image in non-volatile storageto define its image specification (offset in non-volatile storage and length)statically in I/O policy.For example, the FWU metadata image is stored as a partition inside the GUIDpartition table image. Its specification is defined in the partition tablethat needs to be parsed dynamically.This function provides a means to retrieve such dynamic information to setthe I/O policy of the FWU metadata image.Further I/O layer operations such as I/O open, I/O read, etc. on FWU metadataimage relies on this function call.

It returns ‘0’ on success, otherwise a negative error value on error.Alongside, returns device handle and image specification from the I/O policyof the requested FWU metadata image.

6.6.7.Function : plat_fwu_get_boot_idx() [when PSA_FWU_SUPPORT == 1]

Argument:voidReturn:uint32_t

This function is mandatory when PSA_FWU_SUPPORT is enabled. It provides themeans to retrieve the boot index value from the platform. The boot index is thebank from which the platform has booted the firmware images.

By default, the platform will read the metadata structure and try to boot fromthe active bank. If the platform fails to boot from the active bank due toreasons like an Authentication failure, or on crossing a set number of watchdogresets while booting from the active bank, the platform can then switch to bootfrom a different bank. This function then returns the bank that the platformshould boot its images from.

6.7.1.Function : plat_set_my_stack()

Argument:voidReturn:void

This function sets the current stack pointer to the normal memory stack thathas been allocated for the current CPU. For BL images that only require astack for the primary CPU, the UP version of the function is used. The sizeof the stack allocated to each CPU is specified by the platform definedconstantPLATFORM_STACK_SIZE.

Common implementations of this function for the UP and MP BL images areprovided inplat/common/aarch64/platform_up_stack.S andplat/common/aarch64/platform_mp_stack.S

6.7.2.Function : plat_get_my_stack()

Argument:voidReturn:uintptr_t

This function returns the base address of the normal memory stack thathas been allocated for the current CPU. For BL images that only require astack for the primary CPU, the UP version of the function is used. The sizeof the stack allocated to each CPU is specified by the platform definedconstantPLATFORM_STACK_SIZE.

Common implementations of this function for the UP and MP BL images areprovided inplat/common/aarch64/platform_up_stack.S andplat/common/aarch64/platform_mp_stack.S

6.7.3.Function : plat_report_exception()

Argument:unsignedintReturn:void

A platform may need to report various information about its status when anexception is taken, for example the current exception level, the CPU securitystate (secure/non-secure), the exception type, and so on. This function iscalled in the following circumstances:

• In BL1, whenever an exception is taken.

• In BL2, whenever an exception is taken.

The default implementation doesn’t do anything, to avoid making assumptionsabout the way the platform displays its status information.

For AArch64, this function receives the exception type as its argument.Possible values for exceptions types are listed in theinclude/common/bl_common.h header file. Note that these constants are notrelated to any architectural exception code; they are just a TF-A convention.

For AArch32, this function receives the exception mode as its argument.Possible values for exception modes are listed in theinclude/lib/aarch32/arch.h header file.

6.7.4.Function : plat_reset_handler()

Argument:voidReturn:void

A platform may need to do additional initialization after reset. This functionallows the platform to do the platform specific initializations. Platformspecific errata workarounds could also be implemented here. The API shouldpreserve the values of callee saved registers x19 to x29.

The default implementation doesn’t do anything. If a platform needs to overridethe default implementation, refer to theFirmware Design for generalguidelines.

6.7.5.Function : plat_disable_acp()

Argument:voidReturn:void

This API allows a platform to disable the Accelerator Coherency Port (ifpresent) during a cluster power down sequence. The default weak implementationdoesn’t do anything. Since this API is called during the power down sequence,it has restrictions for stack usage and it can use the registers x0 - x17 asscratch registers. It should preserve the value in x18 register as it is usedby the caller to store the return address.

6.7.6.Function : plat_error_handler()

Argument:intReturn:void

This API is called when the generic code encounters an error situation fromwhich it cannot continue. It allows the platform to perform error reporting orrecovery actions (for example, reset the system). This function must not return.

The parameter indicates the type of error using standard codes fromerrno.h.Possible errors reported by the generic code are:

• -EAUTH: a certificate or image could not be authenticated (when TrustedBoard Boot is enabled)

• -ENOENT: the requested image or certificate could not be found or an IOerror was detected

• -ENOMEM: resources exhausted. TF-A does not use dynamic memory, so thiserror is usually an indication of an incorrect array size

The default implementation simply spins.

6.7.7.Function : plat_panic_handler()

Argument:voidReturn:void

This API is called when the generic code encounters an unexpected errorsituation from which it cannot recover. This function must not return,and must be implemented in assembly because it may be called before the Cenvironment is initialized.

6.7.8.Function : plat_system_reset()

Argument:voidReturn:void

This function is used by the platform to resets the system. It can be usedin any specific use-case where system needs to be resetted. For example,in case of DRTM implementation this function reset the system afterwriting the DRTM error code in the non-volatile storage. This functionnever returns. Failure in reset results in panic.

6.7.9.Function : plat_get_bl_image_load_info()

Argument:voidReturn:bl_load_info_t*

This function returns pointer to the list of images that the platform haspopulated to load. This function is invoked in BL2 to load theBL3xx images.

6.7.10.Function : plat_get_next_bl_params()

Argument:voidReturn:bl_params_t*

This function returns a pointer to the shared memory that the platform haskept aside to pass TF-A related information that next BL image needs. Thisfunction is invoked in BL2 to pass this information to the next BLimage.

6.7.11.Function : plat_get_stack_protector_canary()

Argument:voidReturn:u_register_t

This function returns a random value that is used to initialize the canary usedwhen the stack protector is enabled with ENABLE_STACK_PROTECTOR. A predictablevalue will weaken the protection as the attacker could easily write the rightvalue as part of the attack most of the time. Therefore, it should return atrue random number.

6.7.12.Function : plat_flush_next_bl_params()

Argument:voidReturn:void

This function flushes to main memory all the image params that are passed tonext image. This function is invoked in BL2 to flush this informationto the next BL image.

6.7.13.Function : plat_log_get_prefix()

Argument:unsignedintReturn:constchar*

This function defines the prefix string corresponding to thelog_level to beprepended to all the log output from TF-A. Thelog_level (argument) willcorrespond to one of the standard log levels defined in debug.h. The platformcan override the common implementation to define a different prefix string forthe log output. The implementation should be robust to future changes thatincrease the number of log levels.

6.7.14.Function : plat_get_soc_version()

Argument:voidReturn:int32_t

This function returns soc version which mainly consist of below fields

soc_version[30:24]=JEP-106continuationcodefortheSiPsoc_version[23:16]=JEP-106identificationcodewithparitybitfortheSiPsoc_version[15:0]=ImplementationdefinedSoCID

6.7.15.Function : plat_get_soc_revision()

Argument:voidReturn:int32_t

This function returns soc revision in below format

soc_revision[0:30]=SOCrevisionofspecificSOC

6.7.16.Function : plat_is_smccc_feature_available()

Argument:u_register_tReturn:int32_t

This function returns SMC_ARCH_CALL_SUCCESS if the platform supportsthe SMCCC function specified in the argument; otherwise returnsSMC_ARCH_CALL_NOT_SUPPORTED.

6.7.17.Function : plat_can_cmo()

Argument:voidReturn:uint64_t

When CONDITIONAL_CMO flag is enabled:

• This function indicates whether cache management operations should beperformed. It returns 0 if CMOs should be skipped and non-zerootherwise.

• The function must not clobber x1, x2 and x3. It’s also not safe to rely onstack. Otherwise obey AAPCS.

6.7.18.Struct: plat_try_images_ops [optional]

This optional structure holds platform hooks for alternative images load.It has to be defined in platform code and registered by callingplat_setup_try_img_ops() function, passing it the address of theplat_try_images_ops struct.

Argument:conststructplat_try_images_ops*Return:void

Argument:unsignedintimage_idReturn:int

6.9.1.Function : bl1_early_platform_setup() [mandatory]

Argument:voidReturn:void

This function executes with the MMU and data caches disabled. It is only calledby the primary CPU.

On Arm standard platforms, this function:

• Enables a secure instance of SP805 to act as the Trusted Watchdog.

• Initializes a UART (PL011 console), which enables access to theprintffamily of functions in BL1.

• Enables issuing of snoop and DVM (Distributed Virtual Memory) requests tothe CCI slave interface corresponding to the cluster that includes theprimary CPU.

6.9.2.Function : bl1_plat_arch_setup() [mandatory]

Argument:voidReturn:void

This function performs any platform-specific and architectural setup that theplatform requires. Platform-specific setup might include configuration ofmemory controllers and the interconnect.

In Arm standard platforms, this function enables the MMU.

This function helps fulfill requirement 2 above.

6.9.3.Function : bl1_platform_setup() [mandatory]

Argument:voidReturn:void

This function executes with the MMU and data caches enabled. It is responsiblefor performing any remaining platform-specific setup that can occur after theMMU and data cache have been enabled.

In Arm standard platforms, this function initializes the storage abstractionlayer used to load the next bootloader image.

This function helps fulfill requirement 4 above.

6.9.4.Function : bl1_plat_sec_mem_layout() [mandatory]

Argument:voidReturn:meminfo*

This function should only be called on the cold boot path. It executes with theMMU and data caches enabled. The pointer returned by this function must point toameminfo structure containing the extents and availability of secure RAM forthe BL1 stage.

meminfo.total_base=BaseaddressofsecureRAMvisibletoBL1meminfo.total_size=SizeofsecureRAMvisibletoBL1

This information is used by BL1 to load the BL2 image in secure RAM. BL1 alsopopulates a similar structure to tell BL2 the extents of memory available forits own use.

This function helps fulfill requirements 4 and 5 above.

6.9.5.Function : bl1_plat_prepare_exit() [optional]

Argument:entry_point_info_t*Return:void

This function is called prior to exiting BL1 in response to theBL1_SMC_RUN_IMAGE SMC request raised by BL2. It should be used to performplatform specific clean up or bookkeeping operations before transferringcontrol to the next image. It receives the address of theentry_point_info_tstructure passed from BL2. This function runs with MMU disabled.

6.9.6.Function : bl1_plat_set_ep_info() [optional]

Argument:unsignedintimage_id,entry_point_info_t*ep_infoReturn:void

This function allows platforms to overrideep_info for the givenimage_id.

The default implementation just returns.

6.9.7.Function : bl1_plat_get_next_image_id() [optional]

Argument:voidReturn:unsignedint

This and the following function must be overridden to enable the FWU feature.

BL1 calls this function after platform setup to identify the next image to beloaded and executed. If the platform returnsBL2_IMAGE_ID then BL1 proceedswith the normal boot sequence, which loads and executes BL2. If the platformreturns a different image id, BL1 assumes that Firmware Update is required.

The default implementation always returnsBL2_IMAGE_ID. The Arm developmentplatforms override this function to detect if firmware update is required, andif so, return the first image in the firmware update process.

6.9.8.Function : bl1_plat_get_image_desc() [optional]

Argument:unsignedintimage_idReturn:image_desc_t*

BL1 calls this function to get the image descriptor informationimage_desc_tfor the providedimage_id from the platform.

The default implementation always returns a common BL2 image descriptor. Armstandard platforms return an image descriptor corresponding to BL2 or one ofthe firmware update images defined in the Trusted Board Boot Requirementsspecification.

6.9.9.Function : bl1_plat_handle_pre_image_load() [optional]

Argument:unsignedintimage_idReturn:int

This function can be used by the platforms to update/use image informationcorresponding toimage_id. This function is invoked in BL1, both in coldboot and FWU code path, before loading the image.

6.9.10.Function : bl1_plat_calc_bl2_layout() [optional]

Argument:constmeminfo_t*bl1_mem_layout,meminfo_t*bl2_mem_layoutReturn:void

This utility function calculates the memory layout of BL2, representing it in ameminfo_t structure. The default implementation derives this layout from thepositioning of BL1’s RW data at the top of the memory layout.

6.9.11.Function : bl1_plat_handle_post_image_load() [optional]

Argument:unsignedintimage_idReturn:int

This function can be used by the platforms to update/use image informationcorresponding toimage_id. This function is invoked in BL1, both in coldboot and FWU code path, after loading and authenticating the image.

The default weak implementation of this function calculates the amount ofTrusted SRAM that can be used by BL2 and allocates ameminfo_tstructure at the beginning of this free memory and populates it. The addressofmeminfo_t structure is updated inarg1 of the entrypointinformation to BL2.

6.9.12.Function : bl1_plat_fwu_done() [optional]

Argument:unsignedintimage_id,uintptr_timage_src,unsignedintimage_sizeReturn:void

BL1 calls this function when the FWU process is complete. It must not return.The platform may override this function to take platform specific action, forexample to initiate the normal boot flow.

The default implementation spins forever.

6.9.13.Function : bl1_plat_mem_check() [mandatory]

Argument:uintptr_tmem_base,unsignedintmem_size,unsignedintflagsReturn:int

BL1 calls this function while handling FWU related SMCs, more specifically whencopying or authenticating an image. Its responsibility is to ensure that theregion of memory identified bymem_base andmem_size is mapped in BL1, andthat this memory corresponds to either a secure or non-secure memory region asindicated by the security state of theflags argument.

This function can safely assume that the value resulting from the addition ofmem_base andmem_size fits into auintptr_t type variable and does notoverflow.

This function must return 0 on success, a non-null error code otherwise.

The default implementation of this function asserts therefore platforms mustoverride it when using the FWU feature.

6.10.1.Function : bl2_early_platform_setup2() [mandatory]

Argument:u_register_t,u_register_t,u_register_t,u_register_tReturn:void

This function executes with the MMU and data caches disabled. It is only calledby the primary CPU. The 4 arguments are passed by BL1 to BL2 and these argumentsare platform specific.

On Arm standard platforms, the arguments received are :

arg0 - Points to load address of FW_CONFIG

arg1 -meminfo structure populated by BL1. The platform copiesthe contents ofmeminfo as it may be subsequently overwritten by BL2.

On Arm standard platforms, this function also:

• Initializes a UART (PL011 console), which enables access to theprintffamily of functions in BL2.

• Initializes the storage abstraction layer used to load further bootloaderimages. It is necessary to do this early on platforms with a SCP_BL2 image,since the laterbl2_platform_setup must be done after SCP_BL2 is loaded.

6.10.2.Function : bl2_plat_arch_setup() [mandatory]

Argument:voidReturn:void

This function executes with the MMU and data caches disabled. It is only calledby the primary CPU.

The purpose of this function is to perform any architectural initializationthat varies across platforms.

On Arm standard platforms, this function enables the MMU.

6.10.3.Function : bl2_platform_setup() [mandatory]

Argument:voidReturn:void

This function may execute with the MMU and data caches enabled if the platformport does the necessary initialization inbl2_plat_arch_setup(). It is onlycalled by the primary CPU.

The purpose of this function is to perform any platform initializationspecific to BL2.

In Arm standard platforms, this function performs security setup, includingconfiguration of the TrustZone controller to allow non-secure masters accessto most of DRAM. Part of DRAM is reserved for secure world use.

6.10.4.Function : bl2_plat_handle_pre_image_load() [optional]

Argument:unsignedintReturn:int

This function can be used by the platforms to update/use image informationfor givenimage_id. This function is currently invoked in BL2 beforeloading each image.

6.10.5.Function : bl2_plat_handle_post_image_load() [optional]

Argument:unsignedintReturn:int

This function can be used by the platforms to update/use image informationfor givenimage_id. This function is currently invoked in BL2 afterloading each image.

6.10.6.Function : bl2_plat_preload_setup [optional]

Argument:voidReturn:void

This optional function performs any BL2 platform initializationrequired before image loading, that is not done later inbl2_platform_setup().

6.11.1.Function : bl2_el3_early_platform_setup() [mandatory]

Argument:u_register_t,u_register_t,u_register_t,u_register_tReturn:void

This function executes with the MMU and data caches disabled. It is only calledby the primary CPU. This function receives four parameters which can be usedby the platform to pass any needed information from the Boot ROM to BL2.

On Arm standard platforms, this function does the following:

• Initializes a UART (PL011 console), which enables access to theprintffamily of functions in BL2.

• Initializes the storage abstraction layer used to load further bootloaderimages. It is necessary to do this early on platforms with a SCP_BL2 image,since the laterbl2_platform_setup must be done after SCP_BL2 is loaded.

• Initializes the private variables that define the memory layout used.

6.11.2.Function : bl2_el3_plat_arch_setup() [mandatory]

Argument:voidReturn:void

This function executes with the MMU and data caches disabled. It is only calledby the primary CPU.

The purpose of this function is to perform any architectural initializationthat varies across platforms.

On Arm standard platforms, this function enables the MMU.

6.11.3.Function : bl2_el3_plat_prepare_exit() [optional]

Argument:voidReturn:void

This function is called prior to exiting BL2 and run the next image.It should be used to perform platform specific clean up or bookkeepingoperations before transferring control to the next image. This functionruns with MMU disabled.

6.12.1.Function : bl2u_early_platform_setup() [mandatory]

Argument:meminfo*mem_info,void*plat_infoReturn:void

This function executes with the MMU and data caches disabled. It is onlycalled by the primary CPU. The arguments to this function is the addressof thememinfo structure and platform specific info provided by BL1.

The platform may copy the contents of themem_info andplat_info intoprivate storage as the original memory may be subsequently overwritten by BL2U.

On Arm CSS platformsplat_info is interpreted as animage_info_t structure,to extract SCP_BL2U image information, which is then copied into a privatevariable.

6.12.2.Function : bl2u_plat_arch_setup() [mandatory]

Argument:voidReturn:void

This function executes with the MMU and data caches disabled. It is onlycalled by the primary CPU.

The purpose of this function is to perform any architectural initializationthat varies across platforms, for example enabling the MMU (since the memorymap differs across platforms).

6.12.3.Function : bl2u_platform_setup() [mandatory]

Argument:voidReturn:void

This function may execute with the MMU and data caches enabled if the platformport does the necessary initialization inbl2u_plat_arch_setup(). It is onlycalled by the primary CPU.

The purpose of this function is to perform any platform initializationspecific to BL2U.

In Arm standard platforms, this function performs security setup, includingconfiguration of the TrustZone controller to allow non-secure masters accessto most of DRAM. Part of DRAM is reserved for secure world use.

6.12.4.Function : bl2u_plat_handle_scp_bl2u() [optional]

Argument:voidReturn:int

This function is used to perform any platform-specific actions required tohandle the SCP firmware. Typically it transfers the image into SCP memory usinga platform-specific protocol and waits until SCP executes it and signals to theApplication Processor (AP) for BL2U execution to continue.

This function returns 0 on success, a negative error code otherwise.This function is included if SCP_BL2U_BASE is defined.

6.13.1.Function : bl31_early_platform_setup2() [mandatory]

Argument:u_register_t,u_register_t,u_register_t,u_register_tReturn:void

This function executes with the MMU and data caches disabled. It is only calledby the primary CPU. BL2 can pass 4 arguments to BL31 and these arguments areplatform specific.

In Arm standard platforms, the arguments received are :

arg0 - The pointer to the head ofbl_params_t listwhich is list of executable images following BL31,

arg1 - Points to load address of SOC_FW_CONFIG if present

except in case of Arm FVP and Juno platform.

In case of Arm FVP and Juno platform, points to load addressof FW_CONFIG.

arg2 - Points to load address of HW_CONFIG if present

arg3 - A special value to verify platform parameters from BL2 to BL31. Notused in release builds.

The function runs through thebl_param_t list and extracts the entry pointinformation for BL32 and BL33. It also performs the following:

• Initialize a UART (PL011 console), which enables access to theprintffamily of functions in BL31.

• Enable issuing of snoop and DVM (Distributed Virtual Memory) requests to theCCI slave interface corresponding to the cluster that includes the primaryCPU.

6.13.2.Function : bl31_plat_arch_setup() [mandatory]

Argument:voidReturn:void

This function executes with the MMU and data caches disabled. It is only calledby the primary CPU.

The purpose of this function is to perform any architectural initializationthat varies across platforms.

On Arm standard platforms, this function enables the MMU.

6.13.3.Function : bl31_platform_setup() [mandatory]

Argument:voidReturn:void

This function may execute with the MMU and data caches enabled if the platformport does the necessary initialization inbl31_plat_arch_setup(). It is onlycalled by the primary CPU.

The purpose of this function is to complete platform initialization so that bothBL31 runtime services and normal world software can function correctly.

On Arm standard platforms, this function does the following:

• Initialize the generic interrupt controller.

  Depending on the GIC driver selected by the platform, the appropriate GICv2or GICv3 initialization will be done, which mainly consists of:

  • Enable secure interrupts in the GIC CPU interface.

  • Disable the legacy interrupt bypass mechanism.

  • Configure the priority mask register to allow interrupts of all prioritiesto be signaled to the CPU interface.

  • Mark SGIs 8-15 and the other secure interrupts on the platform as secure.

  • Target all secure SPIs to CPU0.

  • Enable these secure interrupts in the GIC distributor.

  • Configure all other interrupts as non-secure.

  • Enable signaling of secure interrupts in the GIC distributor.

• Enable system-level implementation of the generic timer counter through thememory mapped interface.

• Grant access to the system counter timer module

• Initialize the power controller device.

  In particular, initialise the locks that prevent concurrent accesses to thepower controller device.

6.13.4.Function : bl31_plat_runtime_setup() [optional]

Argument:voidReturn:void

The purpose of this function is to allow the platform to perform any BL31 runtimesetup just prior to BL31 exit during cold boot. The default weak implementationof this function is empty. Any platform that needs to perform additional runtimesetup, before BL31 exits, will need to override this function.

6.13.5.Function : bl31_plat_get_next_image_ep_info() [mandatory]

Argument:uint32_tReturn:entry_point_info*

This function may execute with the MMU and data caches enabled if the platformport does the necessary initializations inbl31_plat_arch_setup().

This function is called bybl31_main() to retrieve information provided byBL2 for the next image in the security state specified by the argument. BL31uses this information to pass control to that image in the specified securitystate. This function must return a pointer to theentry_point_info structure(that was copied duringbl31_early_platform_setup()) if the image exists. Itshould return NULL otherwise.

6.13.6.Function : plat_rmmd_get_cca_attest_token() [mandatory when ENABLE_RME == 1]

Argument:uintptr_t,size_t*,uintptr_t,size_t,size_t*Return:int

This function returns the Platform attestation token. If the full token doesnot fit in the buffer, the function will return a hunk of the token andindicate how many bytes were copied and how many are pending. Multiple callsto this function may be needed to retrieve the entire token.

The parameters of the function are:

arg0 - A pointer to the buffer where the Platform token should be copied by

this function. If the platform token does not completely fit in thebuffer, the function may return a piece of the token only.

arg1 - Contains the size (in bytes) of the buffer passed in arg0. In

addition, this parameter is used by the function to return the sizeof the platform token length hunk copied to the buffer.

arg2 - A pointer to the buffer where the challenge object is stored.

arg3 - The length of the challenge object in bytes. Possible values are 32,

48 and 64. This argument must be zero for subsequent calls toretrieve the remaining hunks of the token.

arg4 - Returns the remaining length of the token (in bytes) that is yet to

be returned in further calls.

The function returns 0 on success, -EINVAL on failure and -EAGAIN if theresource associated with the platform token retrieval is busy.

6.13.7.Function : plat_rmmd_get_cca_realm_attest_key() [mandatory when ENABLE_RME == 1]

Argument:uintptr_t,size_t*,unsignedintReturn:int

This function returns the delegated realm attestation key which will be used tosign Realm attestation token. The API currently only supports P-384 ECC curvekey.

The parameters of the function are:

arg0 - A pointer to the buffer where the attestation key should be copied

by this function. The buffer must be big enough to hold theattestation key.

arg1 - Contains the size (in bytes) of the buffer passed in arg0. The

function returns the attestation key length in this parameter.

arg2 - The type of the elliptic curve to which the requested attestation key

belongs.

The function returns 0 on success, -EINVAL on failure.

6.13.8.Function : plat_rmmd_get_el3_rmm_shared_mem() [when ENABLE_RME == 1]

Argument:uintptr_t*Return:size_t

This function returns the size of the shared area between EL3 and RMM (or 0 onfailure). A pointer to the shared area (or a NULL pointer on failure) is storedin the pointer passed as argument.

6.13.9.Function : plat_rmmd_load_manifest() [when ENABLE_RME == 1]

Arguments:rmm_manifest_t*manifestReturn:int

When ENABLE_RME is enabled, this function populates a boot manifest for theRMM image and stores it in the area specified by manifest.

When ENABLE_RME is disabled, this function is not used.

6.13.10.Function : plat_rmm_mecid_key_update() [when ENABLE_RME == 1]

Argument:uint16_tReturn:int

This function is invoked by BL31’s RMMD when there is a request from the RMMmonitor to update the tweak for the encryption key associated to a MECID.

The first parameter (uint16_tmecid) contains the MECID for which theencryption key is to be updated.

Return value is 0 upon success and -EFAULT otherwise.

This function needs to be implemented by a platform if it enables RME.

6.13.11.Function : plat_rmmd_el3_token_sign_push_req() [mandatory when RMMD_ENABLE_EL3_TOKEN_SIGN == 1]

Arguments:conststructel3_token_sign_request*reqReturn:int

Queue realm attestation token signing request from the RMM in EL3. The interface betweenthe RMM and EL3 is modeled as a queue but the underlying implementation may be different,so long as the semantics of queuing and the error codes are used as defined below.

SeeEL3 Token Sign Request structure for definition of the request structure.

Optional interface from the RMM-EL3 interface v0.4 onwards.

The parameters of the functions are:

arg0: Pointer to the token sign request to be pushed to EL3.The structure must be located in the RMM-EL3 sharedmemory buffer and must be locked before use.

Return codes:

• E_RMM_OK On Success.

• E_RMM_INVAL If the arguments are invalid.

• E_RMM_AGAIN Indicates that the request was not queued since thequeue in EL3 is full. This may also be returned for any reasonor situation in the system, that prevents accepting the requestfrom the RMM.

• E_RMM_UNK If the SMC is not implemented or if interfaceversion is < 0.4.

6.13.12.Function : plat_rmmd_el3_token_sign_pull_resp() [mandatory when RMMD_ENABLE_EL3_TOKEN_SIGN == 1]

Arguments:structel3_token_sign_response*respReturn:int

Populate the attestation signing response in theresp parameter. The interface betweenthe RMM and EL3 is modeled as a queue for responses but the underlying implementation maybe different, so long as the semantics of queuing and the error codes are used as definedbelow.

SeeEL3 Token Sign Response structure for definition of the response structure.

Optional interface from the RMM-EL3 interface v0.4 onwards.

The parameters of the functions are:

resp: Pointer to the token sign response to get from EL3.The structure must be located in the RMM-EL3 sharedmemory buffer and must be locked before use.

Return:

• E_RMM_OK On Success.

• E_RMM_INVAL If the arguments are invalid.

• E_RMM_AGAIN Indicates that a response is not ready yet.

• E_RMM_UNK If the SMC is not implemented or if interfaceversion is < 0.4.

6.13.13.Function : plat_rmmd_el3_token_sign_get_rak_pub() [mandatory when RMMD_ENABLE_EL3_TOKEN_SIGN == 1]

Argument:uintptr_t,size_t*,unsignedintReturn:int

This function returns the public portion of the realm attestation key which will be used tosign Realm attestation token. Typically, with delegated attestation, the private key isreturned, however, there may be platforms where the private key bits are better protectedin a platform specific manner such that the private key is not exposed. In such cases,the RMM will only cache the public key and forward any requests such as signing, thatuses the private key to EL3. The API currently only supports P-384 ECC curve key.

This is an optional interface from the RMM-EL3 interface v0.4 onwards.

The parameters of the function are:

arg0 - A pointer to the buffer where the public key should be copiedby this function. The buffer must be big enough to hold theattestation key.

arg1 - Contains the size (in bytes) of the buffer passed in arg0. Thefunction returns the attestation key length in this parameter.

arg2 - The type of the elliptic curve to which the requested attestation keybelongs.

The function returns E_RMM_OK on success, RMM_E_INVAL if arguments are invalid andE_RMM_UNK if the SMC is not implemented or if interface version is < 0.4.

6.13.14.Function : plat_rmmd_el3_ide_key_program() [mandatory when RMMD_ENABLE_IDE_KEY_PROG == 1]

Argument:uint64_t,uint64_t,uint64_t,structrp_ide_key_info_t*,uint64_t,uint64_tReturn:int

This function sets the key/IV info for an IDE stream at the Root port. The key is 256 bitsand IV is 96 bits. The caller calls this SMC to program this key to the Rx and Tx portsand for each substream corresponding to a single keyset. The platform should validatethe argumentsEcam address andRootport ID before acting on it. The argumentsrequest IDandcookie are to be ignored for blocking mode and are pass-through to the response fornon-blocking mode.

The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.Depending on the expected latency for IDE-KM interface, the platform should choose blockingor non-blocking semantics. More details about IDE Setup flow can be foundin thisRFC.

The parameters of the function are:

arg0 - The ecam address, to access and configure PCI devices in a system.

arg1 - The rootport ID used to identify the PCIe rootport of a connected device.

arg2 - The IDE stream info associated with a physical device, this parameter packs thethe keyset, direction, substream and stream ID info.

arg3 - Structure with key and IV info.

arg4 - The request ID, is used in non-blocking mode only and can be ignored in blocking mode.

arg5 - The cookie variable, is used in non-blocking mode only and can be ignored in blockingmode.

The function returns E_RMM_OK on success, E_RMM_INVAL if arguments are invalid, E_RMM_FAULTif the key programming is unsuccesful, E_RMM_UNK for an unknown error, E_RMM_AGAIN returnedonly for non-blocking mode if the IDE-KM interface is busy or the request queue is full.E_RMM_INPROGRESS returned if the request is queued successfully and used only in non-blockingmode.

6.13.15.Function : plat_rmmd_el3_ide_key_set_go() [mandatory when RMMD_ENABLE_IDE_KEY_PROG == 1]

Argument:uint64_t,uint64_t,uint64_t,uint64_t,uint64_tReturn:int

This function activates the IDE stream at the Root Port once all the keys have beenprogrammed. The platform should validate the argumentsEcam address andRootport IDbefore acting on it. The argumentsrequest ID andcookie are to be ignored for blockingmode and are pass-through to the response for non-blocking mode.

The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.Depending on the expected latency for IDE-KM interface, the platform should choose blockingor non-blocking semantics. More details about IDE Setup flow can be foundin thisRFC.

The parameters of the function are:

arg0 - The ecam address, to access and configure PCI devices in a system.

arg1 - The rootport ID used to identify the PCIe rootport of a connected device.

arg2 - The IDE stream info associated with a physical device, this parameter packs thethe keyset, direction, substream and stream ID info.

arg3 - The request ID, is used in non-blocking mode only and can be ignored in blocking mode.

arg4 - The cookie variable, is used in non-blocking mode only and can be ignored in blockingmode.

The function returns E_RMM_OK on success, E_RMM_INVAL if arguments are invalid, E_RMM_FAULTif the key programming is unsuccesful, E_RMM_UNK for an unknown error, E_RMM_AGAIN returnedonly for non-blocking mode if the IDE-KM interface is busy or the request queue is full.E_RMM_INPROGRESS returned if the request is queued successfully and used only in non-blockingmode.

6.13.16.Function : plat_rmmd_el3_ide_key_set_stop() [mandatory when RMMD_ENABLE_IDE_KEY_PROG == 1]

Argument:uint64_t,uint64_t,uint64_t,uint64_t,uint64_tReturn:int

This function stops the IDE stream and is used to tear down the IDE stream at Root Port.The platform should validate the argumentsEcam address andRootport ID before actingon it. The argumentsrequest ID andcookie are to be ignored for blockingmode and are pass-through to the response for non-blocking mode.

The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.Depending on the expected latency for IDE-KM interface, the platform should choose blockingor non-blocking semantics. More details about IDE Setup flow can be foundin thisRFC.

The parameters of the function are:

arg0 - The ecam address, to access and configure PCI devices in a system.

arg1 - The rootport ID used to identify the PCIe rootport of a connected device.

arg2 - The IDE stream info associated with a physical device, this parameter packs thethe keyset, direction, substream and stream ID info.

arg3 - The request ID, is used in non-blocking mode only and can be ignored in blocking mode.

arg4 - The cookie variable, is used in non-blocking mode only and can be ignored in blockingmode.

The function returns E_RMM_OK on success, E_RMM_INVAL if arguments are invalid, E_RMM_FAULTif the key programming is unsuccesful, E_RMM_UNK for an unknown error, E_RMM_AGAIN returnedonly for non-blocking mode if the IDE-KM interface is busy or the request queue is full.E_RMM_INPROGRESS returned if the request is queued successfully and used only in non-blockingmode.

6.13.17.Function : plat_rmmd_el3_ide_km_pull_response() [mandatory when RMMD_ENABLE_IDE_KEY_PROG == 1]

Argument:uint64_t,uint64_t,uint64_t*,uint64_t*,uint64_t*Return:int

This function retrieves a reponse for any of the prior non-blocking IDE-KM requests. Thecaller has to identify the request and populate the accurate response. For blocking calls,this function always returns E_RMM_UNK.

The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.Depending on the expected latency for IDE-KM interface, the platform should choose blockingor non-blocking semantics. More details about IDE Setup flow can be foundin thisRFC.

The parameters of the function are:

arg0 - The ecam address, to access and configure PCI devices in a system.

arg1 - The rootport ID used to identify the PCIe rootport of a connected device.

arg2 - Retrieved response corresponding to the previous IDE_KM request.

arg3 - returns the passthrough request ID of the retrieved response.

arg4 - returns the passthrough cookie of the retrieved response.

The function returns E_RMM_OK if response is retrieved successfully, E_RMM_INVAL if argumentsto this function are invalid, E_RMM_UNK if response retrieval failed for an unknown error orIDE-KM interface is having blocking semantics, E_RMM_AGAIN if the response queue is empty.

Thearg2 return parameter can return the following values:E_RMM_OK - The previous request was successful.E_RMM_FAULT - The previous request was not successful.E_RMM_INVAL - Arguments to previous request were incorrect.E_RMM_UNK - Previous request returned Unknown error.

6.13.18.Function : bl31_plat_enable_mmu [optional]

Argument:uint32_tReturn:void

This function enables the MMU. The boot code calls this function with MMU andcaches disabled. This function should program necessary registers to enabletranslation, and upon return, the MMU on the calling PE must be enabled.

The function must honor flags passed in the first argument. These flags aredefined by the translation library, and can be found in the fileinclude/lib/xlat_tables/xlat_mmu_helpers.h.

On DynamIQ systems, this function must not use stack while enabling MMU, whichis how the function in xlat table library version 2 is implemented.

6.13.19.Function : plat_init_apkey [optional]

Argument:voidReturn:uint128_t

This function returns the 128-bit value which can be used to program ARMv8.3pointer authentication keys.

The value should be obtained from a reliable source of randomness.

This function is only needed if ARMv8.3 pointer authentication is used in theTrusted Firmware by building withBRANCH_PROTECTION option set to 1, 2 or 3.

6.13.20.Function : plat_get_syscnt_freq2() [mandatory]

Argument:voidReturn:unsignedint

This function is used by the architecture setup code to retrieve the counterfrequency for the CPU’s generic timer. This value will be programmed into theCNTFRQ_EL0 register. In Arm standard platforms, it returns the base frequencyof the system counter, which is retrieved from the first entry in the frequencymodes table.

6.13.21.#define : PLAT_PERCPU_BAKERY_LOCK_SIZE [optional]

WhenUSE_COHERENT_MEM=0, this constant defines the total memory (inbytes) aligned to the cache line boundary that should be allocated per-cpu toaccommodate all the bakery locks.

If this constant is not defined whenUSE_COHERENT_MEM=0, the linkercalculates the size of the.bakery_lock input section, aligns it to thenearestCACHE_WRITEBACK_GRANULE, multiplies it withPLATFORM_CORE_COUNTand stores the result in a linker symbol. This constant prevents a platformfrom relying on the linker and provide a more efficient mechanism foraccessing per-cpu bakery lock information.

If this constant is defined and its value is not equal to the valuecalculated by the linker then a link time assertion is raised. A compile timeassertion is raised if the value of the constant is not aligned to the cacheline boundary.

6.13.22.SDEI porting requirements

TheSDEI dispatcher requires the platform to provide the following macrosand functions, of which some are optional, and some others mandatory.

Argument:uintptr_tep,unsignedintclient_modeReturn:int

Argument:uint64_tArgument:unsignedintReturn:void

6.13.23.TRNG porting requirements

TheTRNG backend requires the platform to provide the following valuesand mandatory functions.

Argument:noneReturn:none

Argument:uint64_t*Return:boolOut:whenthereturnvalueistrue,theentropyhasbeenwrittenintothestoragepointedto

6.14.1.Function : plat_psci_stat_accounting_start() [optional]

Argument:constpsci_power_state_t*Return:void

This is an optional hook that platforms can implement for residency statisticsaccounting before entering a low power state. Thepwr_domain_state field ofstate_info (first argument) can be inspected if stat accounting is donedifferently at CPU level versus higher levels. As an example, if the element atindex 0 (CPU power level) in thepwr_domain_state array indicates a power downstate, special hardware logic may be programmed in order to keep track of theresidency statistics. For higher levels (array indices > 0), the residencystatistics could be tracked in software using PMF. IfENABLE_PMF is set, thedefault implementation will use PMF to capture timestamps.

6.14.2.Function : plat_psci_stat_accounting_stop() [optional]

Argument:constpsci_power_state_t*Return:void

This is an optional hook that platforms can implement for residency statisticsaccounting after exiting from a low power state. Thepwr_domain_state fieldofstate_info (first argument) can be inspected if stat accounting is donedifferently at CPU level versus higher levels. As an example, if the element atindex 0 (CPU power level) in thepwr_domain_state array indicates a power downstate, special hardware logic may be programmed in order to keep track of theresidency statistics. For higher levels (array indices > 0), the residencystatistics could be tracked in software using PMF. IfENABLE_PMF is set, thedefault implementation will use PMF to capture timestamps.

6.14.3.Function : plat_psci_stat_get_residency() [optional]

Argument:unsignedint,constpsci_power_state_t*,unsignedintReturn:u_register_t

This is an optional interface that is is invoked after resuming from a low powerstate and provides the time spent resident in that low power state by the powerdomain at a particular power domain level. When a CPU wakes up from suspend,all its parent power domain levels are also woken up. The generic PSCI codeinvokes this function for each parent power domain that is resumed and itidentified by thelvl (first argument) parameter. Thestate_info (secondargument) describes the low power state that the power domain has resumed from.The current CPU is the first CPU in the power domain to resume from the lowpower state and thelast_cpu_idx (third parameter) is the index of the lastCPU in the power domain to suspend and may be needed to calculate the residencyfor that power domain.

6.14.4.Function : plat_get_target_pwr_state() [optional]

Argument:unsignedint,constplat_local_state_t*,unsignedintReturn:plat_local_state_t

The PSCI generic code uses this function to let the platform participate instate coordination during a power management operation. The function is passeda pointer to an array of platform specific local power statestates (secondargument) which contains the requested power state for each CPU at a particularpower domain levellvl (first argument) within the power domain. The functionis expected to traverse this array of uptoncpus (third argument) and returna coordinated target power state by the comparing all the requested powerstates. The target power state should not be deeper than any of the requestedpower states.

A weak definition of this API is provided by default wherein it assumesthat the platform assigns a local state value in order of increasing depthof the power state i.e. for two power states X & Y, if X < Ythen X represents a shallower power state than Y. As a result, thecoordinated target local power state for a power domain will be the minimumof the requested local power state values.

6.14.5.Function : plat_get_power_domain_tree_desc() [mandatory]

Argument:voidReturn:constunsignedchar*

This function returns a pointer to the byte array containing the power domaintopology tree description. The format and method to construct this array aredescribed inPSCI Power Domain Tree Structure. The BL31 PSCIinitialization code requires this array to be described by the platform, eitherstatically or dynamically, to initialize the power domain topology tree. In casethe array is populated dynamically, then plat_core_pos_by_mpidr() andplat_my_core_pos() should also be implemented suitably so that the topology treedescription matches the CPU indices returned by these APIs. These APIs togetherform the platform interface for the PSCI topology framework.

6.14.6.Function : plat_setup_psci_ops() [mandatory]

Argument:uintptr_t,constplat_psci_ops**Return:int

This function may execute with the MMU and data caches enabled if the platformport does the necessary initializations inbl31_plat_arch_setup(). It is onlycalled by the primary CPU.

This function is called by PSCI initialization code. Its purpose is to letthe platform layer know about the warm boot entrypoint through thesec_entrypoint (first argument) and to export handler routines forplatform-specific psci power management actions by populating the passedpointer with a pointer to BL31’s privateplat_psci_ops structure.

A description of each member of this structure is given below. Please refer tothe Arm FVP specific implementation of these handlers inplat/arm/board/fvp/fvp_pm.c as an example. For each PSCI function that theplatform wants to support, the associated operation or operations in thisstructure must be provided and implemented (Refer section 4 ofFirmware Design for the PSCI API supported in TF-A). To disable a PSCIfunction in a platform port, the operation should be removed from thisstructure instead of providing an empty implementation.

6.15.1.Function : plat_interrupt_type_to_line() [mandatory]

Argument:uint32_t,uint32_tReturn:uint32_t

The Arm processor signals an interrupt exception either through the IRQ or FIQinterrupt line. The specific line that is signaled depends on how the interruptcontroller (IC) reports different interrupt types from an execution context ineither security state. The IMF uses this API to determine which interrupt linethe platform IC uses to signal each type of interrupt supported by the frameworkfrom a given security state. This API must be invoked at EL3.

The first parameter will be one of theINTR_TYPE_* values (seeInterrupt Management Framework) indicating the target type of theinterrupt, the second parameter is the security state of the originatingexecution context. The return result is the bit position in theSCR_EL3register of the respective interrupt trap: IRQ=1, FIQ=2.

In the case of Arm standard platforms using GICv2, S-EL1 interrupts areconfigured as FIQs and Non-secure interrupts as IRQs from either securitystate.

In the case of Arm standard platforms using GICv3, the interrupt line to beconfigured depends on the security state of the execution context when theinterrupt is signalled and are as follows:

• The S-EL1 interrupts are signaled as IRQ in S-EL0/1 context and as FIQ inNS-EL0/1/2 context.

• The Non secure interrupts are signaled as FIQ in S-EL0/1 context and as IRQin the NS-EL0/1/2 context.

• The EL3 interrupts are signaled as FIQ in both S-EL0/1 and NS-EL0/1/2context.

6.15.2.Function : plat_ic_get_pending_interrupt_type() [mandatory]

Argument:voidReturn:uint32_t

This API returns the type of the highest priority pending interrupt at theplatform IC. The IMF uses the interrupt type to retrieve the correspondinghandler function.INTR_TYPE_INVAL is returned when there is no interruptpending. The valid interrupt types that can be returned areINTR_TYPE_EL3,INTR_TYPE_S_EL1 andINTR_TYPE_NS. This API must be invoked at EL3.

In the case of Arm standard platforms using GICv2, theHighest PriorityPending Interrupt Register (GICC_HPPIR) is read to determine the id ofthe pending interrupt. The type of interrupt depends upon the id value asfollows.

1. id < 1022 is reported as a S-EL1 interrupt

2. id = 1022 is reported as a Non-secure interrupt.

3. id = 1023 is reported as an invalid interrupt type.

In the case of Arm standard platforms using GICv3, the system registerICC_HPPIR0_EL1,Highest Priority Pending group 0 Interrupt Register,is read to determine the id of the pending interrupt. The type of interruptdepends upon the id value as follows.

1. id =PENDING_G1S_INTID (1020) is reported as a S-EL1 interrupt

2. id =PENDING_G1NS_INTID (1021) is reported as a Non-secure interrupt.

3. id =GIC_SPURIOUS_INTERRUPT (1023) is reported as an invalid interrupt type.

4. All other interrupt id’s are reported as EL3 interrupt.

6.15.3.Function : plat_ic_get_pending_interrupt_id() [mandatory]

Argument:voidReturn:uint32_t

This API returns the id of the highest priority pending interrupt at theplatform IC.INTR_ID_UNAVAILABLE is returned when there is no interruptpending.

In the case of Arm standard platforms using GICv2, theHighest PriorityPending Interrupt Register (GICC_HPPIR) is read to determine the id of thepending interrupt. The id that is returned by API depends upon the value ofthe id read from the interrupt controller as follows.

1. id < 1022. id is returned as is.

2. id = 1022. TheAliased Highest Priority Pending Interrupt Register(GICC_AHPPIR) is read to determine the id of the non-secure interrupt.This id is returned by the API.

3. id = 1023.INTR_ID_UNAVAILABLE is returned.

In the case of Arm standard platforms using GICv3, if the API is invoked fromEL3, the system registerICC_HPPIR0_EL1,Highest Priority Pending Interruptgroup 0 Register, is read to determine the id of the pending interrupt. The idthat is returned by API depends upon the value of the id read from theinterrupt controller as follows.

1. id <PENDING_G1S_INTID (1020). id is returned as is.

2. id =PENDING_G1S_INTID (1020) orPENDING_G1NS_INTID (1021). The systemregisterICC_HPPIR1_EL1,Highest Priority Pending Interrupt group 1Register is read to determine the id of the group 1 interrupt. This idis returned by the API as long as it is a valid interrupt id

3. If the id is any of the special interrupt identifiers,INTR_ID_UNAVAILABLE is returned.

When the API invoked from S-EL1 for GICv3 systems, the id read from systemregisterICC_HPPIR1_EL1,Highest Priority Pending group 1 InterruptRegister, is returned if is not equal to GIC_SPURIOUS_INTERRUPT (1023) elseINTR_ID_UNAVAILABLE is returned.

6.15.4.Function : plat_ic_acknowledge_interrupt() [mandatory]

Argument:voidReturn:uint32_t

This API is used by the CPU to indicate to the platform IC that processing ofthe highest pending interrupt has begun. It should return the raw, unmodifiedvalue obtained from the interrupt controller when acknowledging an interrupt.The actual interrupt number shall be extracted from this raw value using the APIplat_ic_get_interrupt_id()<plat_ic_get_interrupt_id>.

This function in Arm standard platforms using GICv2, reads theInterruptAcknowledge Register (GICC_IAR). This changes the state of the highestpriority pending interrupt from pending to active in the interrupt controller.It returns the value read from theGICC_IAR, unmodified.

In the case of Arm standard platforms using GICv3, if the API is invokedfrom EL3, the function reads the system registerICC_IAR0_EL1,InterruptAcknowledge Register group 0. If the API is invoked from S-EL1, the functionreads the system registerICC_IAR1_EL1,Interrupt Acknowledge Registergroup 1. The read changes the state of the highest pending interrupt frompending to active in the interrupt controller. The value read is returnedunmodified.

The TSP uses this API to start processing of the secure physical timerinterrupt.

6.15.5.Function : plat_ic_end_of_interrupt() [mandatory]

Argument:uint32_tReturn:void

This API is used by the CPU to indicate to the platform IC that processing ofthe interrupt corresponding to the id (passed as the parameter) hasfinished. The id should be the same as the id returned by theplat_ic_acknowledge_interrupt() API.

Arm standard platforms write the id to theEnd of Interrupt Register(GICC_EOIR) in case of GICv2, and toICC_EOIR0_EL1 orICC_EOIR1_EL1system register in case of GICv3 depending on where the API is invoked from,EL3 or S-EL1. This deactivates the corresponding interrupt in the interruptcontroller.

The TSP uses this API to finish processing of the secure physical timerinterrupt.

6.15.6.Function : plat_ic_get_interrupt_type() [mandatory]

Argument:uint32_tReturn:uint32_t

This API returns the type of the interrupt id passed as the parameter.INTR_TYPE_INVAL is returned if the id is invalid. If the id is valid, a validinterrupt type (one ofINTR_TYPE_EL3,INTR_TYPE_S_EL1 andINTR_TYPE_NS) isreturned depending upon how the interrupt has been configured by the platformIC. This API must be invoked at EL3.

Arm standard platforms using GICv2 configures S-EL1 interrupts as Group0 interruptsand Non-secure interrupts as Group1 interrupts. It reads the group valuecorresponding to the interrupt id from the relevantInterrupt Group Register(GICD_IGROUPRn). It uses the group value to determine the type of interrupt.

In the case of Arm standard platforms using GICv3, both theInterrupt GroupRegister (GICD_IGROUPRn) andInterrupt Group Modifier Register(GICD_IGRPMODRn) is read to figure out whether the interrupt is configuredas Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt.

6.17.1.Function : elx_panic()

Argument:voidReturn:void

This API is called from assembly files when reporting a critical failurethat has occured in lower EL and is been trapped in EL3. This callmust not return.

6.17.2.Function : el3_panic()

Argument:voidReturn:void

This API is called from assembly files when encountering a critical failure thatcannot be recovered from. This function assumes that it is invoked from a Cruntime environment i.e. valid stack exists. This callmust not return.

6.17.3.Function : panic()

Argument:voidReturn:void

This API called from C files when encountering a critical failure that cannotbe recovered from. This function in turn prints backtrace (if enabled) and callsel3_panic(). This callmust not return.

6.18.1.Function : plat_crash_console_init [mandatory]

Argument:voidReturn:int

This API is used by the crash reporting mechanism to initialize the crashconsole. It must only use the general purpose registers x0 through x7 to do theinitialization and returns 1 on success.

6.18.2.Function : plat_crash_console_putc [mandatory]

Argument:intReturn:int

This API is used by the crash reporting mechanism to print a character on thedesignated crash console. It must only use general purpose registers x1 andx2 to do its work. The parameter and the return value are in general purposeregister x0.

6.18.3.Function : plat_crash_console_flush [mandatory]

Argument:voidReturn:void

This API is used by the crash reporting mechanism to force write of all buffereddata on the designated crash console. It should only use general purposeregisters x0 through x5 to do its work.

6.18.4.Function : plat_setup_early_console [optional]

Argument:voidReturn:void

This API is used to setup the early console, it is required only if the flagEARLY_CONSOLE is enabled.

6.19.1.Function : plat_ea_handler

Argument:intArgument:uint64_tArgument:void*Argument:void*Argument:uint64_tReturn:void

This function is invoked by the runtime exception handling framework for theplatform to handle an External Abort received at EL3. The intention of thefunction is to attempt to resolve the cause of External Abort and return;if that’s not possible then an orderly shutdown of the system is initiated.

The first parameter (intea_reason) indicates the reason for External Abort.Its value is one ofERROR_EA_* constants defined inea_handle.h.

The second parameter (uint64_tsyndrome) is the respective syndromepresented to EL3 after having received the External Abort. Depending on thenature of the abort (as can be inferred from theea_reason parameter), thiscan be the content of eitherESR_EL3 orDISR_EL1.

The third parameter (void*cookie) is unused for now. The fourth parameter(void*handle) is a pointer to the preempted context. The fifth parameter(uint64_tflags) indicates the preempted security state. These parametersare received from the top-level exception handler.

This function must be implemented if a platform expects Firmware First handlingof External Aborts.

6.19.2.Function : plat_handle_uncontainable_ea

Argument:intArgument:uint64_tReturn:void

This function is invoked by the RAS framework when an External Abort ofUncontainable type is received at EL3. Due to the critical nature ofUncontainable errors, the intention of this function is to initiate orderlyshutdown of the system, and is not expected to return.

This function must be implemented in assembly.

The first and second parameters are the same as that ofplat_ea_handler.

The default implementation of this function callsreport_unhandled_exception.

6.19.3.Function : plat_handle_double_fault

Argument:intArgument:uint64_tReturn:void

This function is invoked by the RAS framework when another External Abort isreceived at EL3 while one is already being handled. I.e., a call toplat_ea_handler is outstanding. Due to its critical nature, the intention ofthis function is to initiate orderly shutdown of the system, and is not expectedrecover or return.

This function must be implemented in assembly.

The first and second parameters are the same as that ofplat_ea_handler.

The default implementation of this function callsreport_unhandled_exception.

6.19.4.Function : plat_handle_el3_ea

Return:void

This function is invoked when an External Abort is received while executing inEL3. Due to its critical nature, the intention of this function is to initiateorderly shutdown of the system, and is not expected recover or return.

This function must be implemented in assembly.

The default implementation of this function callsreport_unhandled_exception.

6.19.5.Function : plat_handle_rng_trap

Argument:uint64_tArgument:cpu_context_t*Return:int

This function is invoked by BL31’s exception handler when there is a synchronoussystem register trap caused by access to the RNDR or RNDRRS registers. It allowsplatforms implementingFEAT_RNG_TRAP and enablingENABLE_FEAT_RNG_TRAP toemulate those system registers by returing back some entropy to the lower EL.

The first parameter (uint64_tesr_el3) contains the content of the ESR_EL3syndrome register, which encodes the instruction that was trapped. The interestinginformation in there is the target register (get_sysreg_iss_rt()).

The second parameter (cpu_context_t*ctx) represents the CPU state in thelower exception level, at the time when the execution of themrs instructionwas trapped. Its content can be changed, to put the entropy into the targetregister.

The return value indicates how to proceed:

• When returningTRAP_RET_UNHANDLED (-1), the machine will panic.

• When returningTRAP_RET_REPEAT (0), the exception handler will returnto the same instruction, so its execution will be repeated.

• When returningTRAP_RET_CONTINUE (1), the exception handler will returnto the next instruction.

This function needs to be implemented by a platform if it enables FEAT_RNG_TRAP.

6.19.6.Function : plat_handle_impdef_trap

Argument:uint64_tArgument:cpu_context_t*Return:int

This function is invoked by BL31’s exception handler when there is a synchronoussystem register trap caused by access to the implementation defined registers.It allows platforms enablingIMPDEF_SYSREG_TRAP to emulate those systemregisters choosing to program bits of their choice. If using in combination withARCH_FEATURE_AVAILABILITY, the macros{SCR,MDCR,CPTR}_PLAT_{BITS,IGNORED,FLIPPED} should be defined to report correctresults.

The first parameter (uint64_tesr_el3) contains the content of the ESR_EL3syndrome register, which encodes the instruction that was trapped.

The second parameter (cpu_context_t*ctx) represents the CPU state in thelower exception level, at the time when the execution of themrs instructionwas trapped.

The return value indicates how to proceed:

• When returningTRAP_RET_UNHANDLED (-1), the machine will panic.

• When returningTRAP_RET_REPEAT (0), the exception handler will returnto the same instruction, so its execution will be repeated.

• When returningTRAP_RET_CONTINUE (1), the exception handler will returnto the next instruction.

This function needs to be implemented by a platform if it enablesIMPDEF_SYSREG_TRAP.

6.25.1.Function : plat_lfa_get_components()

Argument:plat_lfa_component_info_t**Return:int

This platform API provides the list of LFA components available for activation.It populates a pointer to an array ofplat_lfa_component_info_t structures,which contain information about each component (like UUID, ID, etc.). It returns0 on success, or a standard error code on failure.

6.25.2.Function : is_plat_lfa_activation_pending()

Argument:uint32_tReturn:bool

This platform API checks if the specified LFA component, identifiedby itslfa_component_id, is available for activation. It returnstrue if available, otherwise false.

6.25.3.Function : plat_lfa_cancel()

Argument:uint32_tReturn:int

This platform API allows the platform to cancel an ongoing update or activationprocess for the specifiedlfa_component_id. It returns 0 on success ora standard error code on failure.

6.25.4.Function : plat_lfa_load_auth_image()

Argument:uint32_tReturn:int

The platform uses this API to load, authenticate and measure the componentspecified bylfa_component_id. It should return 0 on success or appropriateerror codes for load/authentication failures.

Copyright (c) 2013-2025, Arm Limited and Contributors. All rights reserved.