rk3399_ARM-atf/docs/porting-guide.rst

27       then, you will find references to *weak* functions in this document.
65 provided to help in this setup.
67 Note that although this library supports non-identity mappings, this is intended
111 Each platform must ensure that a header file of this name is in the system
171    states for each level may be sparsely allocated between 0 and this value
172    with 0 being reserved for the RUN state. The PSCI implementation uses this
187    that the platform supports. The default value of this macro is 2 since
190    account for more local power states, then it must redefine this macro.
192    Currently, this macro is used by the Generic PSCI implementation to size
348       TF-A does not provide source code for this image.
359       TF-A does not provide source code for this image.
375       TF-A does not provide source code for this image.
489    for a 32 bit virtual address space, this value should be ``(1ULL << 32)``.
494    for a 32 bit physical address space, this value should be ``(1ULL << 32)``.
502    more devices than this value using ``io_register_device()`` will fail with
508    entities than this value using ``io_open()`` will fail with -ENOMEM.
513    register more devices this value using ``io_dev_open()`` will fail
515    With this macro, multiple block devices could be supported at the same
519 BL31, it should define the following macro. Currently this is only required if
521 ``USE_COHERENT_MEM`` build flag. In this case, the framework allocates the
618   of protected memory. At minimum this must include a region for the NPU's
668 Each platform must ensure a file of this name is in the system include path with
669 the following macro defined. In the Arm development platforms, this file is
676    and this macro can be defined to be empty in case register reporting is not
695    performs the necessary steps to remove it from this state.
717 BL31 initialization. If it's a cold reset then this function must return zero.
721 not assume that callee saved registers are preserved across a call to this
728 both on a cold and warm reset. In this case, there is no need to identify the
730 this function is not required on such platforms.
753 primary CPU will execute the cold boot code. Therefore, implementing this
771 distinguish between primary and secondary CPUs and implementing this function is
829                          When this flag is set, the function does not need to
877 This function is optional when Trusted Board Boot is enabled. If this
893 The functions mentioned in this section are mandatory, when platform enables
1108 initialization sequence which mandates that this function should be
1114 PSCI and details of this can be found in
1127 case the ``MPIDR`` is invalid, this function returns -1. This function will only
1130 represents the power domain topology and how this relates to the linear CPU
1148 (i.e. every BL stage) that utilises Mbed TLS. In this default implementation,
1149 the function simply returns the address and size of this "pre-allocated" heap.
1150 For a platform to use this default implementation, only a call to the helper
1178 secure storage for the symmetric key. So in this case ``ENC_KEY_IS_IDENTIFIER``
1186 Note that this API depends on ``DECRYPTION_SUPPORT`` build flag.
1202 images rely on this function call.
1204 In Arm platforms, this function is used to set an I/O policy of the FIP image,
1219 be used to load this image from the platform's non-volatile storage.
1230 image relies on this function call.
1276 Common implementations of this function for the UP and MP BL images are
1294 Common implementations of this function for the UP and MP BL images are
1317 For AArch64, this function receives the exception type as its argument.
1322 For AArch32, this function receives the exception mode as its argument.
1353 doesn't do anything. Since this API is called during the power down sequence,
1377 -  ``-ENOMEM``: resources exhausted. TF-A does not use dynamic memory, so this
1421 function is invoked in BL2 to pass this information to the next BL
1452 next image. This function is invoked in BL2 to flush this information
1626    only this CPU executes the remaining BL1 code, including loading and passing
1642    By default, BL1 places this ``meminfo`` structure at the end of secure
1664 On Arm standard platforms, this function:
1687 In Arm standard platforms, this function enables the MMU.
1703 In Arm standard platforms, this function initializes the storage abstraction
1717 MMU and data caches enabled. The pointer returned by this function must point to
1768 BL1 calls this function after platform setup to identify the next image to be
1774 platforms override this function to detect if firmware update is required, and
1785 BL1 calls this function to get the image descriptor information ``image_desc_t``
1814 `meminfo_t` structure. The default implementation derives this layout from the
1829 The default weak implementation of this function calculates the amount of
1831 structure at the beginning of this free memory and populates it. The address
1844 BL1 calls this function when the FWU process is complete. It must not return.
1845 The platform may override this function to take platform specific action, for
1859 BL1 calls this function while handling FWU related SMCs, more specifically when
1862 that this memory corresponds to either a secure or non-secure memory region as
1871 The default implementation of this function asserts therefore platforms must
1919 On Arm standard platforms, this function also:
1925    images. It is necessary to do this early on platforms with a SCP_BL2 image,
1939 The purpose of this function is to perform any architectural initialization
1942 On Arm standard platforms, this function enables the MMU.
1956 The purpose of this function is to perform any platform initialization
1959 In Arm standard platforms, this function performs security setup, including
2003 directly to BL2 instead of TF-A BL1. In this case BL2 is expected to
2026 On Arm standard platforms, this function does the following:
2032    images. It is necessary to do this early on platforms with a SCP_BL2 image,
2048 The purpose of this function is to perform any architectural initialization
2051 On Arm standard platforms, this function enables the MMU.
2078    If ``SCP_BL2U_BASE`` is not defined then this step is not performed.
2096 called by the primary CPU. The arguments to this function is the address
2117 The purpose of this function is to perform any architectural initialization
2133 The purpose of this function is to perform any platform initialization
2136 In Arm standard platforms, this function performs security setup, including
2165    some of this initialization, BL31 remains resident in EL3 and must ensure
2171    populated by BL2 in memory to do this.
2182    ``bl_params`` list populated by BL2 in memory to do this.
2239 The purpose of this function is to perform any architectural initialization
2242 On Arm standard platforms, this function enables the MMU.
2256 The purpose of this function is to complete platform initialization so that both
2259 On Arm standard platforms, this function does the following:
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
2297 setup, before BL31 exits, will need to override this function.
2312 uses this information to pass control to that image in the specified security
2328 to this function may be needed to retrieve the entire token.
2333            this function. If the platform token does not completely fit in the
2337            addition, this parameter is used by the function to return the size
2367            by this function. The buffer must be big enough to hold the
2371            function returns the attestation key length in this parameter.
2398 When ENABLE_RME is enabled, this function populates a boot manifest for the
2401 When ENABLE_RME is disabled, this function is not used.
2519     by this function. The buffer must be big enough to hold the
2523     function returns the attestation key length in this parameter.
2540 and IV is 96 bits. The caller calls this SMC to program this key to the Rx and Tx ports
2549 in this `RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_.
2557     arg2 - The IDE stream info associated with a physical device, this parameter packs the
2589 in this `RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_.
2597     arg2 - The IDE stream info associated with a physical device, this parameter packs the
2627 in this `RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_.
2635     arg2 - The IDE stream info associated with a physical device, this parameter packs the
2659 this function always returns E_RMM_UNK.
2664 in this `RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_.
2679 to this function are invalid, E_RMM_UNK if response retrieval failed for an unknown error or
2696 This function enables the MMU. The boot code calls this function with MMU and
2704 On DynamIQ systems, this function must not use stack while enabling MMU, which
2742 When ``USE_COHERENT_MEM = 0``, this constant defines the total memory (in
2746 If this constant is not defined when ``USE_COHERENT_MEM = 0``, the linker
2753 If this constant is defined and its value is not equal to the value
2807 The default implementation always returns ``0``. On Arm platforms, this function
2850 UUID must not equal ``0xffffffff`` or the signed integer ``-1`` as this value in
2914 passed in a PSCI ``CPU_SUSPEND`` call to this representation.
2966 invokes this function for each parent power domain that is resumed and it
2982 The PSCI generic code uses this function to let the platform participate in
2987 is expected to traverse this array of upto ``ncpus`` (third argument) and return
2992 A weak definition of this API is provided by default wherein it assumes
3008 topology tree description. The format and method to construct this array are
3010 initialization code requires this array to be described by the platform, either
3035 A description of each member of this structure is given below. Please refer to
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
3050 For this handler to be invoked by the PSCI ``CPU_SUSPEND`` API implementation,
3074 For this handler, the local power state for the CPU power domain will be a
3092 For this handler, the local power state for the CPU power domain will be a
3103 If implemented, this function allows the platform to perform platform specific
3104 validations based on hardware states. The generic code expects this function to
3114 calls this function when suspending to a power down state, and it guarantees
3121 efficient to move those actions to this function. When HW_ASSISTED_COHERENCY
3123 moving platform specific actions to this function.
3144 execution by restoring this state when its powered on (see
3149 this safely, the ITS context must be saved first. The architectural part is
3170 platform specific actions before the CPU is powered down. Since this function is
3171 invoked outside the PSCI locks, the actions performed in this hook must be local
3179 It is preferred that this function returns. The caller will invoke
3181 and handle any wakeups that may arise. Previously, this function did not return
3183 possible on platforms where this is guaranteed to be terminal, however, it is
3186 Previously this function was called ``pwr_domain_pwr_down_wfi()`` and invoked
3195 this CPU to enter the normal world and also provide secure runtime firmware
3223 setup required to restore the saved state for this CPU to resume execution
3231 suspend, their context must be restored in this function in the reverse order
3239 notifying the Secure Payload Dispatcher. The caller will call ``wfi`` if this
3247 notifying the Secure Payload Dispatcher. The caller will call ``wfi`` if this
3302 domain, the platform must return PSCI_E_INVALID_PARAMS as error. If this
3313 This is an optional function. If implemented this function is intended to return
3328 This is an optional function. If implemented this function is
3336 in `PSCI`_. If this function returns success, the caller will call
3371 ``spd_pm_ops_t`` callbacks for this purpose. These hooks must be
3423    PSCI_MIGRATE_INFO_UP_CPU APIs. The return value of this callback must
3444 state or EL3/S-EL1 in the secure state. The design of this framework is
3470 either security state. The IMF uses this API to determine which interrupt line
3581 The actual interrupt number shall be extracted from this raw value using the API
3597 The TSP uses this API to start processing of the secure physical timer
3619 The TSP uses this API to finish processing of the secure physical timer
3708 implementation of all of them. Platforms may include this file to their
3716    use in the crash scope that are able to support this, i.e. that are written
3726 for an example of this.
3788 Should this not be desirable, or if there is no powerdown abandon support, then
3815 nature of the abort (as can be inferred from the ``ea_reason`` parameter), this
3837 Uncontainable errors, the intention of this function is to initiate orderly
3844 The default implementation of this function calls
3859 this function is to initiate orderly shutdown of the system, and is not expected
3866 The default implementation of this function calls
3877 EL3. Due to its critical nature, the intention of this function is to initiate
3882 The default implementation of this function calls
3962    By default, this flag is defined ``yes`` by the build system and ``BL33``
3964    option of excluding the BL33 image in the ``fip`` image by defining this flag
3966    are used, this flag will be set to ``no`` automatically.
3981 The ``PLAT_INCLUDES`` variable is used for this purpose. This is needed in
4123 The platform uses this API to load, authenticate and measure the component