rk3399_ARM-atf/docs/porting-guide.rst

7 Porting Trusted Firmware-A (TF-A) to a new platform involves making some
11 -  Implementing a platform-specific function or variable,
15 The platform-specific functions and variables are declared in
16 ``include/plat/common/platform.h``. The firmware provides a default
18 in order to ease the porting effort. Each platform port can use them as is or
23       TF-A historically provided default implementations of platform interfaces
24       as *weak* functions. This practice is now discouraged and new platform
30 effort. Some platform interfaces play a key role in mitigating against some of
32 guarantees offered by TF-A. These platform responsibilities are highlighted in
54 This section covers the modifications that should be made by the platform for
61 A platform port must enable the Memory Management Unit (MMU) as well as the
63 tables is the responsibility of the platform port because memory maps differ
77 platform-specific architecture setup function, ``blX_plat_arch_setup()``, and uses
80 If the build option ``USE_COHERENT_MEM`` is enabled, each platform can allocate a
103 The following variables, functions and constants must be defined by the platform
111 Each platform must ensure that a header file of this name is in the system
113 the list of ``PLAT_INCLUDES`` in the ``platform.mk`` file.
117 likely to be suitable for all platform ports.
121    Defines the linker format used by the platform, for example
126    Defines the processor architecture for the linker by the platform, for
138    levels in the platform.
147    Defines the total number of CPUs implemented by the platform across all
153    tree at all the power domain levels used by the platform.
163    management operations in the system that the platform implements. For
170    possible at every power domain level in the platform. The local power
179    possible at every power domain level in the platform. This macro should be
187    that the platform supports. The default value of this macro is 2 since
189    power domain level (power-down and retention). If the platform needs to
262    platform supports RSE.
264 For every image, the platform must define individual identifiers that will be
267 identifiers. The platform will use those identifiers to return the relevant
387    Total number of images that can be loaded simultaneously. If the platform
390 If a SCP_BL2 image is supported by the platform, the following constants must
396    from platform storage before being transferred to the SCP.
408 If a BL32 image is supported by the platform, the following constants must
435 platform, the following constants must also be defined:
440    platform. This must be at the same address or below ``BL32_BASE``.
445    platform. ``TSP_SEC_MEM_BASE`` and ``TSP_SEC_MEM_SIZE`` must fully
454 If the platform port uses the translation table library code, the following
478    defined in the ``mmap_region_t`` structure. The platform defines the regions
496 If the platform port uses the IO storage framework, the following constants
518 If the platform needs to allocate data within the per-cpu data framework in
520 the platform decides not to use the coherent memory section by undefining the
527    structure for use by the platform layer.
529 The following constants are optional. They should be defined when the platform
541 If the platform supports OS-initiated mode, i.e. the build option
542 ``PSCI_OS_INIT_MODE`` is enabled, and if the platform's maximum power domain
550 If the platform port uses the PL061 GPIO driver, the following constant may
554    Maximum number of GPIOs required by the platform. This allows control how
559 If the platform port uses the partition driver, the following constant may
563    Maximum number of partition entries required by the platform. This allows
566    For example, define the build flag in ``platform.mk``:
573    For example, define the build flag in ``platform.mk``:
577 If the platform port uses the Arm® Ethos™-N NPU driver, the following
584 If the platform port uses the Arm® Ethos™-N NPU driver with TZMP1 support
636 Please see the reference implementation code for the Juno platform as an example.
650 If the platform port uses the DRTM feature, the following constants must be
655    Maximum Event Log size used by the platform. Platform can decide the maximum
663    size of address map region of the platform.
668 Each platform must ensure a file of this name is in the system include path with
674    This macro allows the crash reporting routine to print relevant platform
694    the CPU is placed in a platform-specific state until the primary CPU
697 #. In the case of a warm boot, ensuring that the CPU jumps to a platform-
701 The following functions need to be implemented by the platform port to enable
715 platform-specific means. If it's a warm reset, then it returns the warm
740 for placing the executing secondary CPU in a platform-specific state until the
794 pointer to the ROTPK stored in the platform (or a hash of it) and its length.
825     ROTPK_IS_HASH      : Indicates that the ROTPK returned by the platform is a
827     ROTPK_NOT_DEPLOYED : This allows the platform to skip certificate ROTPK
828                          verification while the platform ROTPK is not deployed.
830                          return a platform ROTPK, and the authentication
832                          verifying it against the platform value. This flag
844 non-volatile counter value stored in the platform in the second argument. The
846 platform provides more than one (for example, on platforms that use the default
851 not be retrieved from the platform.
862 counter value in the platform. The cookie in the first argument may be used to
893 The functions mentioned in this section are mandatory, when platform enables
904 This function is used to return the address of the platform *address-map* table,
916 This function returns *true* if the platform has any trusted devices capable of
927 This function returns *true* if platform uses peripherals whose DMA is not
931 If the platform has peripherals that are not managed by the SMMU, then the
932 platform should investigate such peripherals to determine whether they can
944 This function returns the total number of SMMUs in the platform.
955 reported by the platform.
967 of DMA protection supported by the platform.
991 supported by the platform.
1001 This function returns the size normal-world DCE of the platform.
1012 of the platform.
1022 This function returns the size of TCB hash table of the platform.
1032 This function returns the size of ACPI tables region of the platform.
1043 platform.
1095 by the platform port.
1150 For a platform to use this default implementation, only a call to the helper
1173 implementation for testing purposes which must be overridden by the platform
1176 It also allows the platform to pass symmetric key identifier rather than
1181 In addition to above a platform may also choose to provide an image specific
1217 responsible for setting up the platform I/O policy of the requested metadata
1219 be used to load this image from the platform's non-volatile storage.
1245 means to retrieve the boot index value from the platform. The boot index is the
1246 bank from which the platform has booted the firmware images.
1248 By default, the platform will read the metadata structure and try to boot from
1249 the active bank. If the platform fails to boot from the active bank due to
1251 resets while booting from the active bank, the platform can then switch to boot
1252 from a different bank. This function then returns the bank that the platform
1259 common platform-specific tasks. A platform may choose to override these
1273 of the stack allocated to each CPU is specified by the platform defined
1291 of the stack allocated to each CPU is specified by the platform defined
1306 A platform may need to report various information about its status when an
1315 about the way the platform displays its status information.
1334 A platform may need to do additional initialization after reset. This function
1335 allows the platform to do the platform specific initializations. Platform
1339 The default implementation doesn't do anything. If a platform needs to override
1351 This API allows a platform to disable the Accelerator Coherency Port (if
1367 which it cannot continue. It allows the platform to perform error reporting or
1407 This function returns pointer to the list of images that the platform has
1419 This function returns a pointer to the shared memory that the platform has
1465 correspond to one of the standard log levels defined in debug.h. The platform
1508 The plat_get_soc_name() function allows a platform to expose the SoC name to
1513 success, the function returns SMC_ARCH_CALL_SUCCESS. If the platform does not
1525 This function returns SMC_ARCH_CALL_SUCCESS if the platform supports
1548 This optional structure holds platform hooks for alternative images load.
1549 It has to be defined in platform code and registered by calling
1561 This optional function is called to register platform try images ops, given
1587 This optional function is called to register platform log GPT corrupted functions,
1632    address specified by the platform defined constant ``BL2_BASE``.
1645    It is possible for the platform to decide where it wants to place the
1650 The following functions need to be implemented by the platform port to enable
1683 This function performs any platform-specific and architectural setup that the
1684 platform requires. Platform-specific setup might include configuration of
1700 for performing any remaining platform-specific setup that can occur after the
1742 platform specific clean up or bookkeeping operations before transferring
1768 BL1 calls this function after platform setup to identify the next image to be
1769 loaded and executed. If the platform returns ``BL2_IMAGE_ID`` then BL1 proceeds
1770 with the normal boot sequence, which loads and executes BL2. If the platform
1786 for the provided ``image_id`` from the platform.
1845 The platform may override this function to take platform specific action, for
1882 This function inquiry the platform if the non-volatile counter is shared
1897 The following functions must be implemented by the platform port to enable BL2
1910 are platform specific.
1916     arg1 - ``meminfo`` structure populated by BL1. The platform copies
1952 This function may execute with the MMU and data caches enabled if the platform
1956 The purpose of this function is to perform any platform initialization
1995 This optional function performs any BL2 platform initialization
2002 When the platform has a non-TF-A Boot ROM it is desirable to jump
2024 by the platform to pass any needed information from the Boot ROM to BL2.
2062 It should be used to perform platform specific clean up or bookkeeping
2077    implemented by the platform specific ``bl2u_plat_handle_scp_bl2u()`` function.
2080 #. Any platform specific setup required to perform the FWU process. For
2084 The following functions must be implemented by the platform port to enable
2097 of the ``meminfo`` structure and platform specific info provided by BL1.
2099 The platform may copy the contents of the ``mem_info`` and ``plat_info`` into
2129 This function may execute with the MMU and data caches enabled if the platform
2133 The purpose of this function is to perform any platform initialization
2148 This function is used to perform any platform-specific actions required to
2150 a platform-specific protocol and waits until SCP executes it and signals to the
2164 #. Re-initializing all architectural and platform state. Although BL1 performs
2166    that EL3 architectural and platform state is completely initialized. It
2169 #. Passing control to a normal world BL image, pre-loaded at a platform-
2178 #. Optionally passing control to the BL32 image, pre-loaded at a platform-
2187 The following functions must be implemented by the platform port to enable BL31
2200 platform specific.
2208            except in case of Arm FVP and Juno platform.
2210            In case of Arm FVP and Juno platform, points to load address
2215     arg3 - A special value to verify platform parameters from BL2 to BL31. Not
2252 This function may execute with the MMU and data caches enabled if the platform
2256 The purpose of this function is to complete platform initialization so that both
2263    Depending on the GIC driver selected by the platform, the appropriate GICv2
2270    -  Mark SGIs 8-15 and the other secure interrupts on the platform as secure.
2294 The purpose of this function is to allow the platform to perform any BL31 runtime
2296 of this function is empty. Any platform that needs to perform additional runtime
2307 This function may execute with the MMU and data caches enabled if the platform
2333            this function. If the platform token does not completely fit in the
2338            of the platform token length hunk copied to the buffer.
2350 resource associated with the platform token retrieval is busy.
2420 This function needs to be implemented by a platform if it enables RME.
2436 This function needs to be implemented if a platform enables RME and the RMM requires the memory
2510 in a platform specific manner such that the private key is not exposed. In such cases,
2541 and for each substream corresponding to a single keyset. The platform should validate
2546 The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.
2547 Depending on the expected latency for IDE-KM interface, the platform should choose blocking
2582 programmed. The platform should validate the arguments `Ecam address` and `Rootport ID`
2586 The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.
2587 Depending on the expected latency for IDE-KM interface, the platform should choose blocking
2620 The platform should validate the arguments `Ecam address` and `Rootport ID` before acting
2624 The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.
2625 Depending on the expected latency for IDE-KM interface, the platform should choose blocking
2661 The platform needs to ensure proper exclusives are in place when accessed from multiple CPUs.
2662 Depending on the expected latency for IDE-KM interface, the platform should choose blocking
2719 called each time a core powers up and it is the platform's responsibility to
2749 and stores the result in a linker symbol. This constant prevents a platform
2763 The |SDEI| dispatcher requires the platform to provide the following macros
2773 Normal |SDEI| events on the platform. This must have a higher value
2780 Critical |SDEI| events on the platform. This must have a lower value
2838 The |TRNG| backend requires the platform to provide the following values
2864 This function is expected to do platform-specific initialization of any TRNG
2899 BL31's platform initialization code exports a pointer to the platform-specific
2908 describe composite power states specific to a platform. The PSCI implementation
2916 The following functions form part of platform port of PSCI functionality.
2982 The PSCI generic code uses this function to let the platform participate in
2984 a pointer to an array of platform specific local power state ``states`` (second
2993 that the platform assigns a local state value in order of increasing depth
3010 initialization code requires this array to be described by the platform, either
3015 form the platform interface for the PSCI topology framework.
3025 This function may execute with the MMU and data caches enabled if the platform
3030 the platform layer know about the warm boot entrypoint through the
3032 platform-specific psci power management actions by populating the passed
3038 platform wants to support, the associated operation or operations in this
3041 function in a platform port, the operation should be removed from this
3047 Perform the platform-specific actions to enter the standby state for a cpu
3060 Perform the platform specific actions to power on a CPU, specified
3061 by the ``MPIDR`` (first argument). The generic code expects the platform to
3067 This optional function performs the platform specific actions to check if
3071 The ``target_state`` encodes the platform coordinated target local power states
3078 platform thinks that CPU_OFF should not proceed on the calling CPU.
3083 Perform the platform specific actions to prepare to power off the calling CPU
3087 The ``target_state`` encodes the platform coordinated target local power states
3103 If implemented, this function allows the platform to perform platform specific
3119 power down state and it is safe to perform some or all of the platform
3123 moving platform specific actions to this function.
3128 Perform the platform specific actions to prepare to suspend the calling
3134 the ``pwr_domain_off()`` operation. It encodes the platform coordinated
3147 When suspending a core, the platform can also choose to power off the GICv3
3152 the platform code to implement the necessary sequence. Then the GIC
3155 is the responsibility of the platform code to execute the right implementation
3158 When a system suspend is requested, the platform can also make use of the
3162 allocated in a special area if it cannot fit in the platform's global static
3170 platform specific actions before the CPU is powered down. Since this function is
3172 to the CPU or the platform must ensure that races between multiple CPUs cannot
3176 operation and it encodes the platform coordinated target local power states for
3194 It performs the platform-specific setup required to initialize enough state for
3209 function gives the flexibility to perform any platform-specific actions safely,
3222 ``CPU_SUSPEND`` call or ``SYSTEM_SUSPEND`` call. It performs the platform-specific
3227 the ``pwr_domain_on_finish()`` operation. The generic code expects the platform
3238 call. It performs the platform-specific system poweroff sequence after
3246 call. It performs the platform-specific system reset sequence after
3256 specific local states. If the ``power_state`` is invalid, the platform must
3266 the platform must return PSCI_E_INVALID_ADDRESS as error, which is
3273 call to get the ``req_state`` parameter from platform which encodes the power
3285 ``PLAT_MAX_PWR_LVL_STATES`` - 1. This function is only needed if the platform
3302 domain, the platform must return PSCI_E_INVALID_PARAMS as error. If this
3306 This function can also be used in case the platform wants to support local
3316 as retrieved from a power controller or equivalent component on the platform.
3447 A platform should export the following APIs to support the IMF. The following
3450 present in the platform. Arm standard platform layer supports both
3452 and `3.0 (GICv3)`_. Juno builds the Arm platform layer to use GICv2 and the
3471 the platform IC uses to signal each type of interrupt supported by the framework
3504 platform IC. The IMF uses the interrupt type to retrieve the corresponding
3537 platform IC. ``INTR_ID_UNAVAILABLE`` is returned when there is no interrupt
3578 This API is used by the CPU to indicate to the platform IC that processing of
3608 This API is used by the CPU to indicate to the platform IC that processing of
3633 returned depending upon how the interrupt has been configured by the platform
3704 on the platform implementing ``plat_crash_console_init``,
3781 If any cores on the platform support powerdown abandon (check the "Core powerup
3806 platform to handle an External Abort received at EL3. The intention of the
3823 This function must be implemented if a platform expects Firmware First handling
3916 This function needs to be implemented by a platform if it enables FEAT_RNG_TRAP.
3950 This function needs to be implemented by a platform if it enables
3956 There are some build flags which can be defined by the platform to control
3958 need to be defined in the platform makefile which will get included by the
3963    build option should be supplied as a build option. The platform has the
3970    if the platform makefile/build defines or uses the correct ARM_ARCH_MAJOR and
3973    the Architecture and available in TF-A can be enabled from platform specific
4012 In order to improve platform independence and portability a storage abstraction
4013 layer is used to load data from non-volatile platform storage. Currently
4031 function that is called on platform initialization. The semi-hosting driver
4034 Each platform should register devices and their drivers via the storage
4047 Drivers do not have to implement all operations, but each platform must
4054 there). The platform layer (``plat_get_image_source()``) then returns a reference
4072 Enabling the MEASURED_BOOT flag adds extra platform requirements. Please refer
4086 This platform API provides the list of LFA components available for activation.
4099 This platform API checks if the specified LFA component, identified
4111 This platform API allows the platform to cancel an ongoing update or activation
4123 The platform uses this API to load, authenticate and measure the component
4138 This API is invoked by the platform to notify its security engine to initiate