diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/firmware-design.rst | 179 | ||||
| -rw-r--r-- | docs/plat/xilinx-zynqmp.rst | 4 | ||||
| -rw-r--r-- | docs/platform-migration-guide.rst | 608 | ||||
| -rw-r--r-- | docs/porting-guide.rst | 337 | ||||
| -rw-r--r-- | docs/user-guide.rst | 38 |
5 files changed, 73 insertions, 1093 deletions
diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst index 8aa762278..79bdec98f 100644 --- a/docs/firmware-design.rst +++ b/docs/firmware-design.rst @@ -394,13 +394,9 @@ On Arm platforms, BL2 performs the following platform initializations: Image loading in BL2 ^^^^^^^^^^^^^^^^^^^^ -Image loading scheme in BL2 depends on ``LOAD_IMAGE_V2`` build option. If the -flag is disabled, the BLxx images are loaded, by calling the respective -load\_blxx() function from BL2 generic code. If the flag is enabled, the BL2 -generic code loads the images based on the list of loadable images provided -by the platform. BL2 passes the list of executable images provided by the -platform to the next handover BL image. By default, this flag is disabled for -AArch64 and the AArch32 build is supported only if this flag is enabled. +BL2 generic code loads the images based on the list of loadable images +provided by the platform. BL2 passes the list of executable images +provided by the platform to the next handover BL image. The list of loadable images provided by the platform may also contain dynamic configuration files. The files are loaded and can be parsed as @@ -425,10 +421,7 @@ EL3 Runtime Software image load BL2 loads the EL3 Runtime Software image from platform storage into a platform- specific address in trusted SRAM. If there is not enough memory to load the -image or image is missing it leads to an assertion failure. If ``LOAD_IMAGE_V2`` -is disabled and if image loads successfully, BL2 updates the amount of trusted -SRAM used and available for use by EL3 Runtime Software. This information is -populated at a platform-specific memory address. +image or image is missing it leads to an assertion failure. AArch64 BL32 (Secure-EL1 Payload) image load ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1281,47 +1274,22 @@ interrupts on the platform. To this end, the platform is expected to provide the GIC driver (either GICv2 or GICv3, as selected by the platform) with the interrupt configuration during the driver initialisation. -There are two ways to specify secure interrupt configuration: +Secure interrupt configuration are specified in an array of secure interrupt +properties. In this scheme, in both GICv2 and GICv3 driver data structures, the +``interrupt_props`` member points to an array of interrupt properties. Each +element of the array specifies the interrupt number and its configuration, viz. +priority, group, configuration. Each element of the array shall be populated by +the macro ``INTR_PROP_DESC()``. The macro takes the following arguments: -#. Array of secure interrupt properties: In this scheme, in both GICv2 and GICv3 - driver data structures, the ``interrupt_props`` member points to an array of - interrupt properties. Each element of the array specifies the interrupt - number and its configuration, viz. priority, group, configuration. Each - element of the array shall be populated by the macro ``INTR_PROP_DESC()``. - The macro takes the following arguments: +- 10-bit interrupt number, - - 10-bit interrupt number, +- 8-bit interrupt priority, - - 8-bit interrupt priority, +- Interrupt type (one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``, + ``INTR_TYPE_NS``), - - Interrupt type (one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``, - ``INTR_TYPE_NS``), - - - Interrupt configuration (either ``GIC_INTR_CFG_LEVEL`` or - ``GIC_INTR_CFG_EDGE``). - -#. Array of secure interrupts: In this scheme, the GIC driver is provided an - array of secure interrupt numbers. The GIC driver, at the time of - initialisation, iterates through the array and assigns each interrupt - the appropriate group. - - - For the GICv2 driver, in ``gicv2_driver_data`` structure, the - ``g0_interrupt_array`` member of the should point to the array of - interrupts to be assigned to *Group 0*, and the ``g0_interrupt_num`` - member of the should be set to the number of interrupts in the array. - - - For the GICv3 driver, in ``gicv3_driver_data`` structure: - - - The ``g0_interrupt_array`` member of the should point to the array of - interrupts to be assigned to *Group 0*, and the ``g0_interrupt_num`` - member of the should be set to the number of interrupts in the array. - - - The ``g1s_interrupt_array`` member of the should point to the array of - interrupts to be assigned to *Group 1 Secure*, and the - ``g1s_interrupt_num`` member of the should be set to the number of - interrupts in the array. - - **Note that this scheme is deprecated.** +- Interrupt configuration (either ``GIC_INTR_CFG_LEVEL`` or + ``GIC_INTR_CFG_EDGE``). CPU specific operations framework --------------------------------- @@ -1650,80 +1618,10 @@ Additionally, if the platform memory layout implies some image overlaying like on FVP, BL31 and TSP need to know the limit address that their PROGBITS sections must not overstep. The platform code must provide those. -When LOAD\_IMAGE\_V2 is disabled, TF-A provides a mechanism to verify at boot -time that the memory to load a new image is free to prevent overwriting a -previously loaded image. For this mechanism to work, the platform must specify -the memory available in the system as regions, where each region consists of -base address, total size and the free area within it (as defined in the -``meminfo_t`` structure). TF-A retrieves these memory regions by calling the -corresponding platform API: - -- ``meminfo_t *bl1_plat_sec_mem_layout(void)`` -- ``meminfo_t *bl2_plat_sec_mem_layout(void)`` -- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)`` -- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)`` -- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)`` - -For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will -return the region defined by the platform where BL1 intends to load BL2. The -``load_image()`` function will check that the memory where BL2 will be loaded is -within the specified region and marked as free. - -The actual number of regions and their base addresses and sizes is platform -specific. The platform may return the same region or define a different one for -each API. However, the overlap verification mechanism applies only to a single -region. Hence, it is the platform responsibility to guarantee that different -regions do not overlap, or that if they do, the overlapping images are not -accessed at the same time. This could be used, for example, to load temporary -images (e.g. certificates) or firmware images prior to being transfered to its -corresponding processor (e.g. the SCP BL2 image). - -To reduce fragmentation and simplify the tracking of free memory, all the free -memory within a region is always located in one single buffer defined by its -base address and size. TF-A implements a top/bottom load approach: -after a new image is loaded, it checks how much memory remains free above and -below the image. The smallest area is marked as unavailable, while the larger -area becomes the new free memory buffer. Platforms should take this behaviour -into account when defining the base address for each of the images. For example, -if an image is loaded near the middle of the region, small changes in image size -could cause a flip between a top load and a bottom load, which may result in an -unexpected memory layout. - -The following diagram is an example of an image loaded in the bottom part of -the memory region. The region is initially free (nothing has been loaded yet): - -:: - - Memory region - +----------+ - | | - | | <<<<<<<<<<<<< Free - | | - |----------| +------------+ - | image | <<<<<<<<<<<<< | image | - |----------| +------------+ - | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable - +----------+ - -And the following diagram is an example of an image loaded in the top part: - -:: - - Memory region - +----------+ - | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable - |----------| +------------+ - | image | <<<<<<<<<<<<< | image | - |----------| +------------+ - | | - | | <<<<<<<<<<<<< Free - | | - +----------+ - -When LOAD\_IMAGE\_V2 is enabled, TF-A does not provide any mechanism to verify -at boot time that the memory to load a new image is free to prevent overwriting -a previously loaded image. The platform must specify the memory available in -the system for all the relevant BL images to be loaded. +TF-A does not provide any mechanism to verify at boot time that the memory +to load a new image is free to prevent overwriting a previously loaded image. +The platform must specify the memory available in the system for all the +relevant BL images to be loaded. For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will return the region defined by the platform where BL1 intends to load BL2. The @@ -1774,43 +1672,6 @@ The following list describes the memory layout on the Arm development platforms: When BL32 (for AArch64) is loaded into Trusted SRAM, it is loaded below BL31. -When LOAD\_IMAGE\_V2 is disabled the memory regions for the overlap detection -mechanism at boot time are defined as follows (shown per API): - -- ``meminfo_t *bl1_plat_sec_mem_layout(void)`` - - This region corresponds to the whole Trusted SRAM except for the shared - memory at the base. This region is initially free. At boot time, BL1 will - mark the BL1(rw) section within this region as occupied. The BL1(rw) section - is placed at the top of Trusted SRAM. - -- ``meminfo_t *bl2_plat_sec_mem_layout(void)`` - - This region corresponds to the whole Trusted SRAM as defined by - ``bl1_plat_sec_mem_layout()``, but with the BL1(rw) section marked as - occupied. This memory region is used to check that BL2 and BL31 do not - overlap with each other. BL2\_BASE and BL1\_RW\_BASE are carefully chosen so - that the memory for BL31 is top loaded above BL2. - -- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)`` - - This region is an exact copy of the region defined by - ``bl2_plat_sec_mem_layout()``. Being a disconnected copy means that all the - changes made to this region by the TF-A will not be propagated. This - approach is valid because the SCP BL2 image is loaded temporarily while it - is being transferred to the SCP, so this memory is reused afterwards. - -- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)`` - - This region depends on the location of the BL32 image. Currently, Arm - platforms support three different locations (detailed below): Trusted SRAM, - Trusted DRAM and the TZC-Secured DRAM. - -- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)`` - - This region corresponds to the Non-Secure DDR-DRAM, excluding the - TZC-Secured area. - The location of the BL32 image will result in different memory maps. This is illustrated for both FVP and Juno in the following diagrams, using the TSP as an example. diff --git a/docs/plat/xilinx-zynqmp.rst b/docs/plat/xilinx-zynqmp.rst index 428024148..2b48ba92d 100644 --- a/docs/plat/xilinx-zynqmp.rst +++ b/docs/plat/xilinx-zynqmp.rst @@ -14,13 +14,13 @@ To build: .. code:: bash - make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp bl31 + make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp bl31 To build bl32 TSP you have to rebuild bl31 too: .. code:: bash - make ERROR_DEPRECATED=1 CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd bl31 bl32 + make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd bl31 bl32 ZynqMP platform specific build options ====================================== diff --git a/docs/platform-migration-guide.rst b/docs/platform-migration-guide.rst deleted file mode 100644 index 87d35f4f8..000000000 --- a/docs/platform-migration-guide.rst +++ /dev/null @@ -1,608 +0,0 @@ -Guide to migrate to new Platform porting interface -================================================== - - -.. section-numbering:: - :suffix: . - -.. contents:: - --------------- - -Introduction ------------- - -The PSCI implementation in TF-A has undergone a redesign because of three -requirements that the PSCI 1.0 specification introduced : - -- Removing the framework assumption about the structure of the MPIDR, and - its relation to the power topology enables support for deeper and more - complex hierarchies. - -- Reworking the power state coordination implementation in the framework - to support the more detailed PSCI 1.0 requirements and reduce platform - port complexity - -- Enable the use of the extended power\_state parameter and the larger StateID - field - -The PSCI 1.0 implementation introduces new frameworks to fulfill the above -requirements. These framework changes mean that the platform porting API must -also be modified. This document is a guide to assist migration of the existing -platform ports to the new platform API. - -This document describes the new platform API and compares it with the -deprecated API. It also describes the compatibility layer that enables the -existing platform ports to work with the PSCI 1.0 implementation. The -deprecated platform API is documented for reference. - -Platform API modification due to PSCI framework changes -------------------------------------------------------- - -This section describes changes to the platform APIs. - -Power domain topology framework platform API modifications ----------------------------------------------------------- - -This removes the assumption in the PSCI implementation that MPIDR -based affinity instances map directly to power domains. A power domain, as -described in section 4.2 of `PSCI`_, could contain a core or a logical group -of cores (a cluster) which share some state on which power management -operations can be performed. The existing affinity instance based APIs -``plat_get_aff_count()`` and ``plat_get_aff_state()`` are deprecated. The new -platform interfaces that are introduced for this framework are: - -- ``plat_core_pos_by_mpidr()`` -- ``plat_my_core_pos()`` -- ``plat_get_power_domain_tree_desc()`` - -``plat_my_core_pos()`` and ``plat_core_pos_by_mpidr()`` are mandatory -and are meant to replace the existing ``platform_get_core_pos()`` API. -The description of these APIs can be found in the `Porting Guide`_. -These are used by the power domain topology framework such that: - -#. The generic PSCI code does not generate MPIDRs or use them to query the - platform about the number of power domains at a particular power level. The - ``plat_get_power_domain_tree_desc()`` provides a description of the power - domain tree on the SoC through a pointer to the byte array containing the - power domain topology tree description data structure. - -#. The linear indices returned by ``plat_core_pos_by_mpidr()`` and - ``plat_my_core_pos()`` are used to retrieve core power domain nodes from - the power domain tree. These core indices are unique for a core and it is a - number between ``0`` and ``PLATFORM_CORE_COUNT - 1``. The platform can choose - to implement a static mapping between ``MPIDR`` and core index or implement - a dynamic mapping, choosing to skip the unavailable/unused cores to compact - the core indices. - -In addition, the platforms must define the macros ``PLAT_NUM_PWR_DOMAINS`` and -``PLAT_MAX_PWR_LVL`` which replace the macros ``PLAT_NUM_AFFS`` and -``PLATFORM_MAX_AFFLVL`` respectively. On platforms where the affinity instances -correspond to power domains, the values of new macros remain the same as the -old ones. - -More details on the power domain topology description and its platform -interface can be found in `psci pd tree`_. - -Composite power state framework platform API modifications ----------------------------------------------------------- - -The state-ID field in the power-state parameter of a CPU\_SUSPEND call can be -used to describe the composite power states specific to a platform. The existing -PSCI state coordination had the limitation that it operates on a run/off -granularity of power states and it did not interpret the state-ID field. This -was acceptable as the specification requirement in PSCI 0.2 and the framework's -approach to coordination only required maintaining a reference -count of the number of cores that have requested the cluster to remain powered. - -In the PSCI 1.0 specification, this approach is non optimal. If composite -power states are used, the PSCI implementation cannot make global -decisions about state coordination required because it does not understand the -platform specific states. - -The PSCI 1.0 implementation now defines a generic representation of the -power-state parameter : - -.. code:: c - - typedef struct psci_power_state { - plat_local_state_t pwr_domain_state[PLAT_MAX_PWR_LVL + 1]; - } psci_power_state_t; - -``pwr_domain_state`` is an array where each index corresponds to a power level. -Each entry in the array contains the local power state the power domain at -that power level could enter. The meaning of the local power state value is -platform defined, and can vary between levels in a single platform. The PSCI -implementation constraints the values only so that it can classify the state -as RUN, RETENTION or OFF as required by the specification: - -#. Zero means RUN - -#. All OFF state values at all levels must be higher than all - RETENTION state values at all levels - -The platform is required to define the macros ``PLAT_MAX_RET_STATE`` and -``PLAT_MAX_OFF_STATE`` to the framework. The requirement for these macros can -be found in the `Porting Guide <porting-guide.rst>`__. - -The PSCI 1.0 implementation adds support to involve the platform in state -coordination. This enables the platform to decide the final target state. -During a request to place a power domain in a low power state, the platform -is passed an array of requested ``plat_local_state_t`` for that power domain by -each core within it through the ``plat_get_target_pwr_state()`` API. This API -coordinates amongst these requested states to determine a target -``plat_local_state_t`` for that power domain. A default weak implementation of -this API is provided in the platform layer which returns the minimum of the -requested local states back to the PSCI state coordination. More details -of ``plat_get_target_pwr_state()`` API can be found in the -`Porting Guide <porting-guide.rst#user-content-function--plat_get_target_pwr_state-optional>`__. - -The PSCI Generic implementation expects platform ports to populate the handlers -for the ``plat_psci_ops`` structure which is declared as : - -.. code:: c - - typedef struct plat_psci_ops { - void (*cpu_standby)(plat_local_state_t cpu_state); - int (*pwr_domain_on)(u_register_t mpidr); - void (*pwr_domain_off)(const psci_power_state_t *target_state); - void (*pwr_domain_suspend_early)(const psci_power_state_t *target_state); - void (*pwr_domain_suspend)(const psci_power_state_t *target_state); - void (*pwr_domain_on_finish)(const psci_power_state_t *target_state); - void (*pwr_domain_suspend_finish)( - const psci_power_state_t *target_state); - void (*system_off)(void) __dead2; - void (*system_reset)(void) __dead2; - int (*validate_power_state)(unsigned int power_state, - psci_power_state_t *req_state); - int (*validate_ns_entrypoint)(unsigned long ns_entrypoint); - void (*get_sys_suspend_power_state)( - psci_power_state_t *req_state); - int (*get_pwr_lvl_state_idx)(plat_local_state_t pwr_domain_state, - int pwrlvl); - int (*translate_power_state_by_mpidr)(u_register_t mpidr, - unsigned int power_state, - psci_power_state_t *output_state); - int (*get_node_hw_state)(u_register_t mpidr, unsigned int power_level); - int (*mem_protect_chk)(uintptr_t base, u_register_t length); - int (*read_mem_protect)(int *val); - int (*write_mem_protect)(int val); - int (*system_reset2)(int is_vendor, - int reset_type, u_register_t cookie); - } plat_psci_ops_t; - -The description of these handlers can be found in the `Porting Guide <porting-guide.rst#user-content-function--plat_setup_psci_ops-mandatory>`__. -The previous ``plat_pm_ops`` structure is deprecated. Compared with the previous -handlers, the major differences are: - -- Difference in parameters - -The PSCI 1.0 implementation depends on the ``validate_power_state`` handler to -convert the power-state parameter (possibly encoding a composite power state) -passed in a PSCI ``CPU_SUSPEND`` to the ``psci_power_state`` format. This handler -is now mandatory for PSCI ``CPU_SUSPEND`` support. - -The ``plat_psci_ops`` handlers, ``pwr_domain_off``, ``pwr_domain_suspend_early`` -and ``pwr_domain_suspend``, are passed the target local state for each affected -power domain. The platform must execute operations specific to these target -states. Similarly, ``pwr_domain_on_finish`` and ``pwr_domain_suspend_finish`` -are passed the local states of the affected power domains before wakeup. The -platform must execute actions to restore these power domains from these specific -local states. - -- Difference in invocation - -Whereas the power management handlers in ``plat_pm_ops`` used to be invoked -for each affinity level till the target affinity level, the new handlers -are only invoked once. The ``target_state`` encodes the target low power -state or the low power state woken up from for each affected power domain. - -- Difference in semantics - -Although the previous ``suspend`` handlers could be used for power down as well -as retention at different affinity levels, the new handlers make this support -explicit. The ``pwr_domain_suspend`` can be used to specify powerdown and -retention at various power domain levels subject to the conditions mentioned -in section 4.2.1 of `PSCI`_ - -Unlike the previous ``standby`` handler, the ``cpu_standby()`` handler is only used -as a fast path for placing a core power domain into a standby or retention -state. - -The below diagram shows the sequence of a PSCI SUSPEND call and the interaction -with the platform layer depicting the exchange of data between PSCI Generic -layer and the platform layer. - -|Image 1| - -Refer `plat/arm/board/fvp/fvp\_pm.c`_ for the implementation details of -these handlers for the FVP. The commit `38dce70f51fb83b27958ba3e2ad15f5635cb1061`_ -demonstrates the migration of Arm reference platforms to the new platform API. - -Miscellaneous modifications ---------------------------- - -In addition to the framework changes, unification of warm reset entry points on -wakeup from low power modes has led to a change in the platform API. In the -earlier implementation, the warm reset entry used to be programmed into the -mailboxes by the 'ON' and 'SUSPEND' power management hooks. In the PSCI 1.0 -implementation, this information is not required, because it can figure that -out by querying affinity info state whether to execute the 'suspend\_finisher\` -or 'on\_finisher'. - -As a result, the warm reset entry point must be programmed only once. The -``plat_setup_psci_ops()`` API takes the secure entry point as an -additional parameter to enable the platforms to configure their mailbox. The -plat\_psci\_ops handlers ``pwr_domain_on`` and ``pwr_domain_suspend`` no longer take -the warm reset entry point as a parameter. - -Also, some platform APIs which took ``MPIDR`` as an argument were only ever -invoked to perform actions specific to the caller core which makes the argument -redundant. Therefore the platform APIs ``plat_get_my_entrypoint()``, -``plat_is_my_cpu_primary()``, ``plat_set_my_stack()`` and -``plat_get_my_stack()`` are defined which are meant to be invoked only for -operations on the current caller core instead of ``platform_get_entrypoint()``, -``platform_is_primary_cpu()``, ``platform_set_stack()`` and ``platform_get_stack()``. - -Compatibility layer -------------------- - -To ease the migration of the platform ports to the new porting interface, -a compatibility layer is introduced that essentially implements a glue layer -between the old platform API and the new API. The build flag -``ENABLE_PLAT_COMPAT`` (enabled by default), specifies whether to enable this -layer or not. A platform port which has migrated to the new API can disable -this flag within the platform specific makefile. - -The compatibility layer works on the assumption that the onus of -state coordination, in case multiple low power states are supported, -is with the platform. The generic PSCI implementation only takes into -account whether the suspend request is power down or not. This corresponds -with the behavior of the PSCI implementation before the introduction of -new frameworks. Also, it assumes that the affinity levels of the platform -correspond directly to the power domain levels. - -The compatibility layer dynamically constructs the new topology -description array by querying the platform using ``plat_get_aff_count()`` -and ``plat_get_aff_state()`` APIs. The linear index returned by -``platform_get_core_pos()`` is used as the core index for the cores. The -higher level (non-core) power domain nodes must know the cores contained -within its domain. It does so by storing the core index of first core -within it and number of core indexes following it. This means that core -indices returned by ``platform_get_core_pos()`` for cores within a particular -power domain must be consecutive. We expect that this is the case for most -platform ports including Arm reference platforms. - -The old PSCI helpers like ``psci_get_suspend_powerstate()``, -``psci_get_suspend_stateid()``, ``psci_get_suspend_stateid_by_mpidr()``, -``psci_get_max_phys_off_afflvl()`` and ``psci_get_suspend_afflvl()`` are also -implemented for the compatibility layer. This allows the existing -platform ports to work with the new PSCI frameworks without significant -rework. - -Deprecated Platform API ------------------------ - -This section documents the deprecated platform porting API. - -Common mandatory modifications ------------------------------- - -The mandatory macros to be defined by the platform port in ``platform_def.h`` - -- **#define : PLATFORM\_NUM\_AFFS** - - Defines the total number of nodes in the affinity hierarchy at all affinity - levels used by the platform. - -- **#define : PLATFORM\_MAX\_AFFLVL** - - Defines the maximum affinity level that the power management operations - should apply to. Armv8-A has support for four affinity levels. It is likely - that hardware will implement fewer affinity levels. This macro allows the - PSCI implementation to consider only those affinity levels in the system - that the platform implements. For example, the Base AEM FVP implements two - clusters with a configurable number of cores. It reports the maximum - affinity level as 1, resulting in PSCI power control up to the cluster - level. - -The following functions must be implemented by the platform port to enable -the reset vector code to perform the required tasks. - -Function : platform\_get\_entrypoint() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : unsigned long - Return : unsigned long - -This function is called with the ``SCTLR.M`` and ``SCTLR.C`` bits disabled. The core -is identified by its ``MPIDR``, which is passed as the argument. The function is -responsible for distinguishing between a warm and cold reset using platform- -specific means. If it is a warm reset, it returns the entrypoint into the -BL31 image that the core must jump to. If it is a cold reset, this function -must return zero. - -This function is also responsible for implementing a platform-specific mechanism -to handle the condition where the core has been warm reset but there is no -entrypoint to jump to. - -This function does not follow the Procedure Call Standard used by the -Application Binary Interface for the Arm 64-bit architecture. The caller should -not assume that callee saved registers are preserved across a call to this -function. - -Function : platform\_is\_primary\_cpu() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : unsigned long - Return : unsigned int - -This function identifies a core by its ``MPIDR``, which is passed as the argument, -to determine whether this core is the primary core or a secondary core. A return -value of zero indicates that the core is not the primary core, while a non-zero -return value indicates that the core is the primary core. - -Common optional modifications ------------------------------ - -Function : platform\_get\_core\_pos() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : unsigned long - Return : int - -A platform may need to convert the ``MPIDR`` of a core to an absolute number, which -can be used as a core-specific linear index into blocks of memory (for example -while allocating per-core stacks). This routine contains a simple mechanism -to perform this conversion, using the assumption that each cluster contains a -maximum of four cores: - -:: - - linear index = cpu_id + (cluster_id * 4) - - cpu_id = 8-bit value in MPIDR at affinity level 0 - cluster_id = 8-bit value in MPIDR at affinity level 1 - -Function : platform\_set\_stack() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : unsigned long - Return : void - -This function sets the current stack pointer to the normal memory stack that -has been allocated for the core specified by MPIDR. For BL images that only -require a stack for the primary core the parameter is ignored. The size of -the stack allocated to each core is specified by the platform defined constant -``PLATFORM_STACK_SIZE``. - -Common implementations of this function for the UP and MP BL images are -provided in `plat/common/aarch64/platform\_up\_stack.S`_ and -`plat/common/aarch64/platform\_mp\_stack.S`_ - -Function : platform\_get\_stack() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : unsigned long - Return : unsigned long - -This function returns the base address of the normal memory stack that -has been allocated for the core specificed by MPIDR. For BL images that only -require a stack for the primary core the parameter is ignored. The size of -the stack allocated to each core is specified by the platform defined constant -``PLATFORM_STACK_SIZE``. - -Common implementations of this function for the UP and MP BL images are -provided in `plat/common/aarch64/platform\_up\_stack.S`_ and -`plat/common/aarch64/platform\_mp\_stack.S`_ - -Modifications for Power State Coordination Interface (in BL31) --------------------------------------------------------------- - -The following functions must be implemented to initialize PSCI functionality in -TF-A. - -Function : plat\_get\_aff\_count() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : unsigned int, unsigned long - Return : unsigned int - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only -called by the primary core. - -This function is called by the PSCI initialization code to detect the system -topology. Its purpose is to return the number of affinity instances implemented -at a given ``affinity level`` (specified by the first argument) and a given -``MPIDR`` (specified by the second argument). For example, on a dual-cluster -system where first cluster implements two cores and the second cluster -implements four cores, a call to this function with an ``MPIDR`` corresponding -to the first cluster (``0x0``) and affinity level 0, would return 2. A call -to this function with an ``MPIDR`` corresponding to the second cluster (``0x100``) -and affinity level 0, would return 4. - -Function : plat\_get\_aff\_state() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : unsigned int, unsigned long - Return : unsigned int - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only -called by the primary core. - -This function is called by the PSCI initialization code. Its purpose is to -return the state of an affinity instance. The affinity instance is determined by -the affinity ID at a given ``affinity level`` (specified by the first argument) -and an ``MPIDR`` (specified by the second argument). The state can be one of -``PSCI_AFF_PRESENT`` or ``PSCI_AFF_ABSENT``. The latter state is used to cater for -system topologies where certain affinity instances are unimplemented. For -example, consider a platform that implements a single cluster with four cores and -another core implemented directly on the interconnect with the cluster. The -``MPIDR``\ s of the cluster would range from ``0x0-0x3``. The ``MPIDR`` of the single -core is 0x100 to indicate that it does not belong to cluster 0. Cluster 1 -is missing but needs to be accounted for to reach this single core in the -topology tree. Therefore it is marked as ``PSCI_AFF_ABSENT``. - -Function : platform\_setup\_pm() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : const plat_pm_ops ** - Return : int - -This function may execute with the MMU and data caches enabled if the platform -port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only -called by the primary core. - -This function is called by PSCI initialization code. Its purpose is to export -handler routines for platform-specific power management actions by populating -the passed pointer with a pointer to the private ``plat_pm_ops`` structure of -BL31. - -A description of each member of this structure is given below. A platform port -is expected to implement these handlers if the corresponding PSCI operation -is to be supported and these handlers are expected to succeed if the return -type is ``void``. - -plat\_pm\_ops.affinst\_standby() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Perform the platform-specific setup to enter the standby state indicated by the -passed argument. The generic code expects the handler to succeed. - -plat\_pm\_ops.affinst\_on() -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Perform the platform specific setup to power on an affinity instance, specified -by the ``MPIDR`` (first argument) and ``affinity level`` (third argument). The -``state`` (fourth argument) contains the current state of that affinity instance -(ON or OFF). This is useful to determine whether any action must be taken. For -example, while powering on a core, the cluster that contains this core might -already be in the ON state. The platform decides what actions must be taken to -transition from the current state to the target state (indicated by the power -management operation). The generic code expects the platform to return -E\_SUCCESS on success or E\_INTERN\_FAIL for any failure. - -plat\_pm\_ops.affinst\_off() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Perform the platform specific setup to power off an affinity instance of the -calling core. It is called by the PSCI ``CPU_OFF`` API implementation. - -The ``affinity level`` (first argument) and ``state`` (second argument) have -a similar meaning as described in the ``affinst_on()`` operation. They -identify the affinity instance on which the call is made and its -current state. This gives the platform port an indication of the -state transition it must make to perform the requested action. For example, if -the calling core is the last powered on core in the cluster, after powering down -affinity level 0 (the core), the platform port should power down affinity -level 1 (the cluster) as well. The generic code expects the handler to succeed. - -plat\_pm\_ops.affinst\_suspend() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Perform the platform specific setup to power off an affinity instance of the -calling core. It is called by the PSCI ``CPU_SUSPEND`` API and ``SYSTEM_SUSPEND`` -API implementation - -The ``affinity level`` (second argument) and ``state`` (third argument) have a -similar meaning as described in the ``affinst_on()`` operation. They are used to -identify the affinity instance on which the call is made and its current state. -This gives the platform port an indication of the state transition it must -make to perform the requested action. For example, if the calling core is the -last powered on core in the cluster, after powering down affinity level 0 -(the core), the platform port should power down affinity level 1 (the cluster) -as well. - -The difference between turning an affinity instance off and suspending it -is that in the former case, the affinity instance is expected to re-initialize -its state when it is next powered on (see ``affinst_on_finish()``). In the latter -case, the affinity instance is expected to save enough state so that it can -resume execution by restoring this state when it is powered on (see -``affinst_suspend_finish()``).The generic code expects the handler to succeed. - -plat\_pm\_ops.affinst\_on\_finish() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function is called by the PSCI implementation after the calling core is -powered on and released from reset in response to an earlier PSCI ``CPU_ON`` call. -It performs the platform-specific setup required to initialize enough state for -this core to enter the Normal world and also provide secure runtime firmware -services. - -The ``affinity level`` (first argument) and ``state`` (second argument) have a -similar meaning as described in the previous operations. The generic code -expects the handler to succeed. - -plat\_pm\_ops.affinst\_suspend\_finish() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function is called by the PSCI implementation after the calling core is -powered on and released from reset in response to an asynchronous wakeup -event, for example a timer interrupt that was programmed by the core during the -``CPU_SUSPEND`` call or ``SYSTEM_SUSPEND`` call. It performs the platform-specific -setup required to restore the saved state for this core to resume execution -in the Normal world and also provide secure runtime firmware services. - -The ``affinity level`` (first argument) and ``state`` (second argument) have a -similar meaning as described in the previous operations. The generic code -expects the platform to succeed. - -plat\_pm\_ops.validate\_power\_state() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function is called by the PSCI implementation during the ``CPU_SUSPEND`` -call to validate the ``power_state`` parameter of the PSCI API. If the -``power_state`` is known to be invalid, the platform must return -PSCI\_E\_INVALID\_PARAMS as an error, which is propagated back to the Normal -world PSCI client. - -plat\_pm\_ops.validate\_ns\_entrypoint() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function is called by the PSCI implementation during the ``CPU_SUSPEND``, -``SYSTEM_SUSPEND`` and ``CPU_ON`` calls to validate the Non-secure ``entry_point`` -parameter passed by the Normal world. If the ``entry_point`` is known to be -invalid, the platform must return PSCI\_E\_INVALID\_PARAMS as an error, which is -propagated back to the Normal world PSCI client. - -plat\_pm\_ops.get\_sys\_suspend\_power\_state() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function is called by the PSCI implementation during the ``SYSTEM_SUSPEND`` -call to return the ``power_state`` parameter. This allows the platform to encode -the appropriate State-ID field within the ``power_state`` parameter which can be -utilized in ``affinst_suspend()`` to suspend to system affinity level. The -``power_state`` parameter should be in the same format as specified by the -PSCI specification for the CPU\_SUSPEND API. - --------------- - -*Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.* - -.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf -.. _Porting Guide: porting-guide.rst#user-content-function--plat_my_core_pos -.. _psci pd tree: psci-pd-tree.rst -.. _plat/arm/board/fvp/fvp\_pm.c: ../plat/arm/board/fvp/fvp_pm.c -.. _38dce70f51fb83b27958ba3e2ad15f5635cb1061: https://github.com/ARM-software/arm-trusted-firmware/commit/38dce70f51fb83b27958ba3e2ad15f5635cb1061 -.. _plat/common/aarch64/platform\_up\_stack.S: ../plat/common/aarch64/platform_up_stack.S -.. _plat/common/aarch64/platform\_mp\_stack.S: ../plat/common/aarch64/platform_mp_stack.S - -.. |Image 1| image:: diagrams/psci-suspend-sequence.png?raw=true diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index 71051ca66..414b0fc12 100644 --- a/docs/porting-guide.rst +++ b/docs/porting-guide.rst @@ -12,10 +12,6 @@ Trusted Firmware-A Porting Guide Introduction ------------ -Please note that this document has been updated for the new platform API -as required by the PSCI v1.0 implementation. Please refer to the -`Migration Guide`_ for the previous platform API. - Porting Trusted Firmware-A (TF-A) to a new platform involves making some mandatory and optional modifications for both the cold and warm boot paths. Modifications consist of: @@ -484,13 +480,6 @@ constants must also be defined: enabled for a BL image, ``MAX_MMAP_REGIONS`` must be defined to accommodate the dynamic regions as well. -- **#define : ADDR\_SPACE\_SIZE** - - Defines the total size of the address space in bytes. For example, for a 32 - bit address space, this value should be ``(1ULL << 32)``. This definition is - now deprecated, platforms should use ``PLAT_PHY_ADDR_SPACE_SIZE`` and - ``PLAT_VIRT_ADDR_SPACE_SIZE`` instead. - - **#define : PLAT\_VIRT\_ADDR\_SPACE\_SIZE** Defines the total size of the virtual address space in bytes. For example, @@ -1011,8 +1000,8 @@ Function : plat\_get\_bl\_image\_load\_info() Return : bl_load_info_t * This function returns pointer to the list of images that the platform has -populated to load. This function is currently invoked in BL2 to load the -BL3xx images, when LOAD\_IMAGE\_V2 is enabled. +populated to load. This function is invoked in BL2 to load the +BL3xx images. Function : plat\_get\_next\_bl\_params() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1024,8 +1013,8 @@ Function : plat\_get\_next\_bl\_params() This function returns a pointer to the shared memory that the platform has kept aside to pass TF-A related information that next BL image needs. This -function is currently invoked in BL2 to pass this information to the next BL -image, when LOAD\_IMAGE\_V2 is enabled. +function is invoked in BL2 to pass this information to the next BL +image. Function : plat\_get\_stack\_protector\_canary() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1054,8 +1043,8 @@ Function : plat\_flush\_next\_bl\_params() Return : void This function flushes to main memory all the image params that are passed to -next image. This function is currently invoked in BL2 to flush this information -to the next BL image, when LOAD\_IMAGE\_V2 is enabled. +next image. This function is invoked in BL2 to flush this information +to the next BL image. Function : plat\_log\_get\_prefix() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1122,15 +1111,9 @@ warm boot. For each CPU, BL1 is responsible for the following tasks: meminfo.total_base = Base address of secure RAM visible to BL2 meminfo.total_size = Size of secure RAM visible to BL2 - meminfo.free_base = Base address of secure RAM available for - allocation to BL2 - meminfo.free_size = Size of secure RAM available for allocation to BL2 - By default, BL1 places this ``meminfo`` structure at the beginning of the - free memory available for its use. Since BL1 cannot allocate memory - dynamically at the moment, its free memory will be available for BL2's use - as-is. However, this means that BL2 must read the ``meminfo`` structure - before it starts using its free memory (this is discussed in Section 3.2). + By default, BL1 places this ``meminfo`` structure at the end of secure + memory visible to BL2. It is possible for the platform to decide where it wants to place the ``meminfo`` structure for BL2 or restrict the amount of memory visible to @@ -1360,66 +1343,33 @@ Boot Loader Stage 2 (BL2) The BL2 stage is executed only by the primary CPU, which is determined in BL1 using the ``platform_is_primary_cpu()`` function. BL1 passed control to BL2 at -``BL2_BASE``. BL2 executes in Secure EL1 and is responsible for: - -#. (Optional) Loading the SCP\_BL2 binary image (if present) from platform - provided non-volatile storage. To load the SCP\_BL2 image, BL2 makes use of - the ``meminfo`` returned by the ``bl2_plat_get_scp_bl2_meminfo()`` function. - The platform also defines the address in memory where SCP\_BL2 is loaded - through the optional constant ``SCP_BL2_BASE``. BL2 uses this information - to determine if there is enough memory to load the SCP\_BL2 image. - Subsequent handling of the SCP\_BL2 image is platform-specific and is - implemented in the ``bl2_plat_handle_scp_bl2()`` function. - If ``SCP_BL2_BASE`` is not defined then this step is not performed. - -#. Loading the BL31 binary image into secure RAM from non-volatile storage. To - load the BL31 image, BL2 makes use of the ``meminfo`` structure passed to it - by BL1. This structure allows BL2 to calculate how much secure RAM is - available for its use. The platform also defines the address in secure RAM - where BL31 is loaded through the constant ``BL31_BASE``. BL2 uses this - information to determine if there is enough memory to load the BL31 image. - -#. (Optional) Loading the BL32 binary image (if present) from platform - provided non-volatile storage. To load the BL32 image, BL2 makes use of - the ``meminfo`` returned by the ``bl2_plat_get_bl32_meminfo()`` function. - The platform also defines the address in memory where BL32 is loaded - through the optional constant ``BL32_BASE``. BL2 uses this information - to determine if there is enough memory to load the BL32 image. - If ``BL32_BASE`` is not defined then this and the next step is not performed. - -#. (Optional) Arranging to pass control to the BL32 image (if present) that - has been pre-loaded at ``BL32_BASE``. BL2 populates an ``entry_point_info`` - structure in memory provided by the platform with information about how - BL31 should pass control to the BL32 image. - -#. (Optional) Loading the normal world BL33 binary image (if not loaded by - other means) into non-secure DRAM from platform storage and arranging for - BL31 to pass control to this image. This address is determined using the - ``plat_get_ns_image_entrypoint()`` function described below. - -#. BL2 populates an ``entry_point_info`` structure in memory provided by the - platform with information about how BL31 should pass control to the - other BL images. +``BL2_BASE``. BL2 executes in Secure EL1 and and invokes +``plat_get_bl_image_load_info()`` to retrieve the list of images to load from +non-volatile storage to secure/non-secure RAM. After all the images are loaded +then BL2 invokes ``plat_get_next_bl_params()`` to get the list of executable +images to be passed to the next BL image. The following functions must be implemented by the platform port to enable BL2 to perform the above tasks. -Function : bl2\_early\_platform\_setup() [mandatory] +Function : bl2\_early\_platform\_setup2() [mandatory] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: - Argument : meminfo * + Argument : u_register_t, u_register_t, u_register_t, u_register_t Return : void This function executes with the MMU and data caches disabled. It is only called -by the primary CPU. The arguments to this function is the address of the -``meminfo`` structure populated by BL1. +by the primary CPU. The 4 arguments are passed by BL1 to BL2 and these arguments +are platform specific. + +On Arm standard platforms, the arguments received are : -The platform may copy the contents of the ``meminfo`` structure into a private -variable as the original memory may be subsequently overwritten by BL2. The -copied structure is made available to all BL2 code through the -``bl2_plat_sec_mem_layout()`` function. + arg0 - Points to load address of HW_CONFIG if present + + arg1 - ``meminfo`` structure populated by BL1. The platform copies + the contents of ``meminfo`` as it may be subsequently overwritten by BL2. On Arm standard platforms, this function also: @@ -1465,24 +1415,6 @@ In Arm standard platforms, this function performs security setup, including configuration of the TrustZone controller to allow non-secure masters access to most of DRAM. Part of DRAM is reserved for secure world use. -Function : bl2\_plat\_sec\_mem\_layout() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : void - Return : meminfo * - -This function should only be called on the cold boot path. It may execute with -the MMU and data caches enabled if the platform port does the necessary -initialization in ``bl2_plat_arch_setup()``. It is only called by the primary CPU. - -The purpose of this function is to return a pointer to a ``meminfo`` structure -populated with the extents of secure RAM available for BL2 to use. See -``bl2_early_platform_setup()`` above. - -Following functions are optionally used only when LOAD\_IMAGE\_V2 is enabled. - Function : bl2\_plat\_handle\_pre\_image\_load() [optional] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1493,7 +1425,7 @@ Function : bl2\_plat\_handle\_pre\_image\_load() [optional] This function can be used by the platforms to update/use image information for given ``image_id``. This function is currently invoked in BL2 before -loading each image, when LOAD\_IMAGE\_V2 is enabled. +loading each image. Function : bl2\_plat\_handle\_post\_image\_load() [optional] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1505,183 +1437,7 @@ Function : bl2\_plat\_handle\_post\_image\_load() [optional] This function can be used by the platforms to update/use image information for given ``image_id``. This function is currently invoked in BL2 after -loading each image, when LOAD\_IMAGE\_V2 is enabled. - -Following functions are required only when LOAD\_IMAGE\_V2 is disabled. - -Function : bl2\_plat\_get\_scp\_bl2\_meminfo() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : meminfo * - Return : void - -This function is used to get the memory limits where BL2 can load the -SCP\_BL2 image. The meminfo provided by this is used by load\_image() to -validate whether the SCP\_BL2 image can be loaded within the given -memory from the given base. - -Function : bl2\_plat\_handle\_scp\_bl2() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : image_info * - Return : int - -This function is called after loading SCP\_BL2 image and it is used to perform -any platform-specific actions required to handle the SCP firmware. Typically it -transfers the image into SCP memory using a platform-specific protocol and waits -until SCP executes it and signals to the Application Processor (AP) for BL2 -execution to continue. - -This function returns 0 on success, a negative error code otherwise. - -Function : bl2\_plat\_get\_bl31\_params() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : void - Return : bl31_params * - -BL2 platform code needs to return a pointer to a ``bl31_params`` structure it -will use for passing information to BL31. The ``bl31_params`` structure carries -the following information. -- Header describing the version information for interpreting the bl31\_param -structure -- Information about executing the BL33 image in the ``bl33_ep_info`` field -- Information about executing the BL32 image in the ``bl32_ep_info`` field -- Information about the type and extents of BL31 image in the -``bl31_image_info`` field -- Information about the type and extents of BL32 image in the -``bl32_image_info`` field -- Information about the type and extents of BL33 image in the -``bl33_image_info`` field - -The memory pointed by this structure and its sub-structures should be -accessible from BL31 initialisation code. BL31 might choose to copy the -necessary content, or maintain the structures until BL33 is initialised. - -Funtion : bl2\_plat\_get\_bl31\_ep\_info() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : void - Return : entry_point_info * - -BL2 platform code returns a pointer which is used to populate the entry point -information for BL31 entry point. The location pointed by it should be -accessible from BL1 while processing the synchronous exception to run to BL31. - -In Arm standard platforms this is allocated inside a bl2\_to\_bl31\_params\_mem -structure in BL2 memory. - -Function : bl2\_plat\_set\_bl31\_ep\_info() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : image_info *, entry_point_info * - Return : void - -In the normal boot flow, this function is called after loading BL31 image and -it can be used to overwrite the entry point set by loader and also set the -security state and SPSR which represents the entry point system state for BL31. - -When booting an EL3 payload instead, this function is called after populating -its entry point address and can be used for the same purpose for the payload -image. It receives a null pointer as its first argument in this case. - -Function : bl2\_plat\_set\_bl32\_ep\_info() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : image_info *, entry_point_info * - Return : void - -This function is called after loading BL32 image and it can be used to -overwrite the entry point set by loader and also set the security state -and SPSR which represents the entry point system state for BL32. - -Function : bl2\_plat\_set\_bl33\_ep\_info() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : image_info *, entry_point_info * - Return : void - -This function is called after loading BL33 image and it can be used to -overwrite the entry point set by loader and also set the security state -and SPSR which represents the entry point system state for BL33. - -In the preloaded BL33 alternative boot flow, this function is called after -populating its entry point address. It is passed a null pointer as its first -argument in this case. - -Function : bl2\_plat\_get\_bl32\_meminfo() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : meminfo * - Return : void - -This function is used to get the memory limits where BL2 can load the -BL32 image. The meminfo provided by this is used by load\_image() to -validate whether the BL32 image can be loaded with in the given -memory from the given base. - -Function : bl2\_plat\_get\_bl33\_meminfo() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : meminfo * - Return : void - -This function is used to get the memory limits where BL2 can load the -BL33 image. The meminfo provided by this is used by load\_image() to -validate whether the BL33 image can be loaded with in the given -memory from the given base. - -This function isn't needed if either ``PRELOADED_BL33_BASE`` or ``EL3_PAYLOAD_BASE`` -build options are used. - -Function : bl2\_plat\_flush\_bl31\_params() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : void - Return : void - -Once BL2 has populated all the structures that needs to be read by BL1 -and BL31 including the bl31\_params structures and its sub-structures, -the bl31\_ep\_info structure and any platform specific data. It flushes -all these data to the main memory so that it is available when we jump to -later Bootloader stages with MMU off - -Function : plat\_get\_ns\_image\_entrypoint() [mandatory] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - Argument : void - Return : uintptr_t - -As previously described, BL2 is responsible for arranging for control to be -passed to a normal world BL image through BL31. This function returns the -entrypoint of that image, which BL31 uses to jump to it. - -BL2 is responsible for loading the normal world BL33 image (e.g. UEFI). - -This function isn't needed if either ``PRELOADED_BL33_BASE`` or ``EL3_PAYLOAD_BASE`` -build options are used. +loading each image. Function : bl2\_plat\_preload\_setup [optional] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1884,8 +1640,8 @@ CPUs. BL31 executes at EL3 and is responsible for: should make no assumptions about the system state when it receives control. #. Passing control to a normal world BL image, pre-loaded at a platform- - specific address by BL2. BL31 uses the ``entry_point_info`` structure that BL2 - populated in memory to do this. + specific address by BL2. On ARM platforms, BL31 uses the ``bl_params`` list + populated by BL2 in memory to do this. #. Providing runtime firmware services. Currently, BL31 only implements a subset of the Power State Coordination Interface (PSCI) API as a runtime @@ -1895,8 +1651,8 @@ CPUs. BL31 executes at EL3 and is responsible for: #. Optionally passing control to the BL32 image, pre-loaded at a platform- specific address by BL2. BL31 exports a set of apis that allow runtime services to specify the security state in which the next image should be - executed and run the corresponding image. BL31 uses the ``entry_point_info`` - structure populated by BL2 to do this. + executed and run the corresponding image. On ARM platforms, BL31 uses the + ``bl_params`` list populated by BL2 in memory to do this. If BL31 is a reset vector, It also needs to handle the reset as specified in section 2.2 before the tasks described above. @@ -1904,28 +1660,32 @@ section 2.2 before the tasks described above. The following functions must be implemented by the platform port to enable BL31 to perform the above tasks. -Function : bl31\_early\_platform\_setup() [mandatory] +Function : bl31\_early\_platform\_setup2() [mandatory] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: - Argument : bl31_params *, void * + Argument : u_register_t, u_register_t, u_register_t, u_register_t Return : void This function executes with the MMU and data caches disabled. It is only called -by the primary CPU. The arguments to this function are: +by the primary CPU. BL2 can pass 4 arguments to BL31 and these arguments are +platform specific. + +In Arm standard platforms, the arguments received are : -- The address of the ``bl31_params`` structure populated by BL2. -- An opaque pointer that the platform may use as needed. + arg0 - The pointer to the head of `bl_params_t` list + which is list of executable images following BL31, -The platform can copy the contents of the ``bl31_params`` structure and its -sub-structures into private variables if the original memory may be -subsequently overwritten by BL31 and similarly the ``void *`` pointing -to the platform data also needs to be saved. + arg1 - Points to load address of SOC_FW_CONFIG if present -In Arm standard platforms, BL2 passes a pointer to a ``bl31_params`` structure -in BL2 memory. BL31 copies the information in this pointer to internal data -structures. It also performs the following: + arg2 - Points to load address of HW_CONFIG if present + + arg3 - A special value to verify platform parameters from BL2 to BL31. Not + used in release builds. + +The function runs through the `bl_param_t` list and extracts the entry point +information for BL32 and BL33. It also performs the following: - Initialize a UART (PL011 console), which enables access to the ``printf`` family of functions in BL31. @@ -2979,12 +2739,6 @@ The default implementation of this function calls Build flags ----------- -- **ENABLE\_PLAT\_COMPAT** - All the platforms ports conforming to this API specification should define - the build flag ``ENABLE_PLAT_COMPAT`` to 0 as the compatibility layer should - be disabled. For more details on compatibility layer, refer - `Migration Guide`_. - There are some build flags which can be defined by the platform to control inclusion or exclusion of certain BL stages from the FIP image. These flags need to be defined in the platform makefile which will get included by the @@ -3070,7 +2824,6 @@ amount of open resources per driver. *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.* -.. _Migration Guide: platform-migration-guide.rst .. _include/plat/common/platform.h: ../include/plat/common/platform.h .. _include/plat/arm/common/plat\_arm.h: ../include/plat/arm/common/plat_arm.h%5D .. _User Guide: user-guide.rst diff --git a/docs/user-guide.rst b/docs/user-guide.rst index bffc062c6..47a04a315 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -234,11 +234,6 @@ Common build options compiling TF-A. Its value must be a numeric, and defaults to 0. See also, *Armv8 Architecture Extensions* in `Firmware Design`_. -- ``ARM_GIC_ARCH``: Choice of Arm GIC architecture version used by the Arm - Legacy GIC driver for implementing the platform GIC API. This API is used - by the interrupt management framework. Default is 2 (that is, version 2.0). - This build option is deprecated. - - ``ARM_PLAT_MT``: This flag determines whether the Arm platform layer has to cater for the multi-threading ``MT`` bit when accessing MPIDR. When this flag is set, the functions which deal with MPIDR assume that the ``MT`` bit in @@ -334,8 +329,8 @@ Common build options - ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted Board Boot authentication at runtime. This option is meant to be enabled only - for development platforms. Both TRUSTED_BOARD_BOOT and LOAD_IMAGE_V2 flags - must be set if this flag has to be enabled. 0 is the default. + for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this + flag has to be enabled. 0 is the default. - ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of the normal boot flow. It must specify the entry point address of the EL3 @@ -514,12 +509,6 @@ Common build options - ``LDFLAGS``: Extra user options appended to the linkers' command line in addition to the one set by the build system. -- ``LOAD_IMAGE_V2``: Boolean option to enable support for new version (v2) of - image loading, which provides more flexibility and scalability around what - images are loaded and executed during boot. Default is 0. - - Note: this flag must be enabled for AArch32 builds. - - ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log output compiled into the build. This should be one of the following: @@ -844,9 +833,6 @@ Arm FVP platform specific build options - ``FVP_GIC600`` : The GIC600 implementation of GICv3 is selected - ``FVP_GICV2`` : The GICv2 only driver is selected - ``FVP_GICV3`` : The GICv3 only driver is selected (default option) - - ``FVP_GICV3_LEGACY``: The Legacy GICv3 driver is selected (deprecated) - Note: If TF-A is compiled with this option on FVPs with GICv3 hardware, - then it configures the hardware to run in GICv2 emulation mode - ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer for functions that wait for an arbitrary time length (udelay and mdelay). @@ -1085,18 +1071,6 @@ destination. In that case, use -f or --force to continue. More information about FIP can be found in the `Firmware Design`_ document. -Migrating from fip\_create to fiptool -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The previous version of fiptool was called fip\_create. A compatibility script -that emulates the basic functionality of the previous fip\_create is provided. -However, users are strongly encouraged to migrate to fiptool. - -- To create a new FIP file, replace "fip\_create" with "fiptool create". -- To update a FIP file, replace "fip\_create" with "fiptool update". -- To dump the contents of a FIP file, replace "fip\_create --dump" - with "fiptool info". - Building FIP images with support for Trusted Board Boot ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1215,12 +1189,12 @@ command: make PLAT=<platform> [DEBUG=1] [V=1] certtool -For platforms that do not require their own IDs in certificate files, -the generic 'cert\_create' tool can be built with the following command: +For platforms that require their own IDs in certificate files, the generic +'cert\_create' tool can be built with the following command: :: - make USE_TBBR_DEFS=1 [DEBUG=1] [V=1] certtool + make USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool ``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more verbose. The following command should be used to obtain help about the tool: @@ -1338,7 +1312,7 @@ section for more info on selecting the right FDT to use. :: - make ARCH=aarch64 PLAT=juno LOAD_IMAGE_V2=1 JUNO_AARCH32_EL3_RUNTIME=1 \ + make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \ BL33=<path-to-juno32-oe-uboot>/SOFTWARE/bl33-uboot.bin \ SCP_BL2=<path-to-juno32-oe-uboot>/SOFTWARE/scp_bl2.bin \ BL32=<path-to-bl32>/bl32.bin all fip |