diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst index c383c5d..5b99d54 100644 --- a/docs/firmware-design.rst +++ b/docs/firmware-design.rst @@ -77,11 +77,57 @@ The sections below provide the following details: +- dynamic configuration of Boot Loader stages - initialization and execution of the first three stages during cold boot - specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for AArch32) entrypoint requirements for use by alternative Trusted Boot Firmware in place of the provided BL1 and BL2 +Dynamic Configuration during cold boot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each of the Boot Loader stages may be dynamically configured if required by the +platform. The Boot Loader stage may optionally specify a firmware +configuration file and/or hardware configuration file as listed below: + +- HW_CONFIG - The hardware configuration file. Can be shared by all Boot Loader + stages and also by the Normal World Rich OS. +- TB_FW_CONFIG - Trusted Boot Firmware configuration file. Shared between BL1 + and BL2. +- SOC_FW_CONFIG - SoC Firmware configuration file. Used by BL31. +- TOS_FW_CONFIG - Trusted OS Firmware configuration file. Used by Trusted OS + (BL32). +- NT_FW_CONFIG - Non Trusted Firmware configuration file. Used by Non-trusted + firmware (BL33). + +The Arm development platforms use the Flattened Device Tree format for the +dynamic configuration files. + +Each Boot Loader stage can pass up to 4 arguments via registers to the next +stage. BL2 passes the list of the next images to execute to the *EL3 Runtime +Software* (BL31 for AArch64 and BL32 for AArch32) via `arg0`. All the other +arguments are platform defined. The Arm development platforms use the following +convention: + +- BL1 passes the address of a meminfo_t structure to BL2 via ``arg1``. This + structure contains the memory layout available to BL2. +- When dynamic configuration files are present, the firmware configuration for + the next Boot Loader stage is populated in the first available argument and + the generic hardware configuration is passed the next available argument. + For example, + + - If TB_FW_CONFIG is loaded by BL1, then its address is passed in ``arg0`` + to BL2. + - If HW_CONFIG is loaded by BL1, then its address is passed in ``arg2`` to + BL2. Note, ``arg1`` is already used for meminfo_t. + - If SOC_FW_CONFIG is loaded by BL2, then its address is passed in ``arg1`` + to BL31. Note, ``arg0`` is used to pass the list of executable images. + - Similarly, if HW_CONFIG is loaded by BL1 or BL2, then its address is + passed in ``arg2`` to BL31. + - For other BL3x images, if the firmware configuration file is loaded by + BL2, then its address is passed in ``arg0`` and if HW_CONFIG is loaded + then its address is passed in ``arg1``. + BL1 ~~~ @@ -261,6 +307,9 @@ - Enable the MMU and map the memory it needs to access. - Configure any required platform storage to load the next bootloader image (BL2). +- If the BL1 dynamic configuration file, ``TB_FW_CONFIG``, is available, then + load it to the platform defined address and make it available to BL2 via + ``arg0``. Firmware Update detection and execution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -287,10 +336,10 @@ "Booting Trusted Firmware" -#. BL1 determines the amount of free trusted SRAM memory available by - calculating the extent of its own data section, which also resides in - trusted SRAM. BL1 loads a BL2 raw binary image from platform storage, at a - platform-specific base address. If the BL2 image file is not present or if +#. BL1 loads a BL2 raw binary image from platform storage, at a + platform-specific base address. Prior to the load, BL1 invokes + ``bl1_plat_handle_pre_image_load()`` which allows the platform to update or + use the image information. If the BL2 image file is not present or if there is not enough free trusted SRAM the following error message is printed: @@ -298,18 +347,15 @@ "Failed to load BL2 firmware." - BL1 calculates the amount of Trusted SRAM that can be used by the BL2 - image. The exact load location of the image is provided as a base address - in the platform header. Further description of the memory layout can be - found later in this document. +#. BL1 invokes ``bl1_plat_handle_post_image_load()`` which again is intended + for platforms to take further action after image load. This function must + populate the necessary arguments for BL2, which may also include the memory + layout. Further description of the memory layout can be found later + in this document. #. BL1 passes control to the BL2 image at Secure EL1 (for AArch64) or at Secure SVC mode (for AArch32), starting from its load address. -#. BL1 also passes information about the amount of trusted SRAM used and - available for use. This information is populated at a platform-specific - memory address. - BL2 ~~~ @@ -344,6 +390,8 @@ EL3 Runtime Software and populate it. - Define the extents of memory available for loading each subsequent bootloader image. +- If BL1 has passed TB_FW_CONFIG dynamic configuration file in ``arg0``, + then parse it. Image loading in BL2 ^^^^^^^^^^^^^^^^^^^^ @@ -356,6 +404,12 @@ 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. +The list of loadable images provided by the platform may also contain +dynamic configuration files. The files are loaded and can be parsed as +needed in the ``bl2_plat_handle_post_image_load()`` function. These +configuration files can be passed to next Boot Loader stages as arguments +by updating the corresponding entrypoint information in this function. + SCP\_BL2 (System Control Processor Firmware) image load ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1791,32 +1845,44 @@ | BL1 (ro) | 0x00000000 +----------+ -**FVP with TSP in Trusted DRAM:** +**FVP with TSP in Trusted DRAM with TB_FW_CONFIG and HW_CONFIG :** :: - Trusted DRAM - 0x08000000 +----------+ - | BL32 | - 0x06000000 +----------+ + DRAM + 0xffffffff +--------------+ + : : + |--------------| + | HW_CONFIG | + 0x83000000 |--------------| (non-secure) + | | + 0x80000000 +--------------+ - Trusted SRAM - 0x04040000 +----------+ loaded by BL2 ------------------ - | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | - |----------| <<<<<<<<<<<<< |----------------| - | | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| ------------------ - | BL2 | - |----------| - | | - 0x04001000 +----------+ - | Shared | - 0x04000000 +----------+ + Trusted DRAM + 0x08000000 +--------------+ + | BL32 | + 0x06000000 +--------------+ - Trusted ROM - 0x04000000 +----------+ - | BL1 (ro) | - 0x00000000 +----------+ + Trusted SRAM + 0x04040000 +--------------+ loaded by BL2 ------------------ + | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS | + |--------------| <<<<<<<<<<<<< |----------------| + | | <<<<<<<<<<<<< | BL31 PROGBITS | + |--------------| ------------------ + | BL2 | + |--------------| + | | + |--------------| + | TB_FW_CONFIG | + |--------------| + 0x04001000 +--------------+ + | Shared | + 0x04000000 +--------------+ + + Trusted ROM + 0x04000000 +--------------+ + | BL1 (ro) | + 0x00000000 +--------------+ **FVP with TSP in TZC-Secured DRAM:** @@ -1824,7 +1890,7 @@ DRAM 0xffffffff +----------+ - | BL32 | (secure) + | BL32 | (secure) 0xff000000 +----------+ | | : : (non-secure) @@ -1881,7 +1947,7 @@ DRAM 0xFFE00000 +----------+ - | BL32 | (secure) + | BL32 | (secure) 0xFF000000 |----------| | | : : (non-secure) @@ -2663,7 +2729,7 @@ -------------- -*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.* +*Copyright (c) 2013-2018, ARM Limited and Contributors. All rights reserved.* .. _Reset Design: ./reset-design.rst .. _Porting Guide: ./porting-guide.rst diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index 21db86b..c35c526 100644 --- a/docs/porting-guide.rst +++ b/docs/porting-guide.rst @@ -1076,20 +1076,16 @@ allocation to BL2 meminfo.free_size = Size of secure RAM available for allocation to BL2 - 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 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). - In future releases of the ARM Trusted Firmware it will be possible for - the platform to decide where it wants to place the ``meminfo`` structure for - BL2. - - BL1 implements the ``bl1_init_bl2_mem_layout()`` function to populate the - BL2 ``meminfo`` structure. The platform may override this implementation, for - example if the platform wants to restrict the amount of memory visible to - BL2. Details of how to do this are given below. + 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 + BL2 by overriding the weak default implementation of + ``bl1_plat_handle_post_image_load`` API. The following functions need to be implemented by the platform port to enable BL1 to perform the above tasks. @@ -1264,6 +1260,12 @@ corresponding to ``image_id``. This function is invoked in BL1, both in cold boot and FWU code path, after loading and authenticating the image. +The default weak implementation of this function calculates the amount of +Trusted SRAM that can be used by BL2 and allocates a ``meminfo_t`` +structure at the beginning of this free memory and populates it. The address +of ``meminfo_t`` structure is updated in ``arg1`` of the entrypoint +information to BL2. + Function : bl1\_plat\_fwu\_done() [optional] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 9e23711..ebca4ec 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -776,6 +776,19 @@ for functions that wait for an arbitrary time length (udelay and mdelay). The default value is 0. +- ``FVP_HW_CONFIG_DTS`` : Specify the path to the DTS file to be compiled + to DTB and packaged in FIP as the HW_CONFIG. See `Firmware Design`_ for + details on HW_CONFIG. By default, this is initialized to a sensible DTS + file in ``fdts/`` folder depending on other build options. But some cases, + like shifted affinity format for MPIDR, cannot be detected at build time + and this option is needed to specify the appropriate DTS file. + +- ``FVP_HW_CONFIG`` : Specify the path to the HW_CONFIG blob to be packaged in + FIP. See `Firmware Design`_ for details on HW_CONFIG. This option is + similar to the ``FVP_HW_CONFIG_DTS`` option, but it directly specifies the + HW_CONFIG blob instead of the DTS file. This option is useful to override + the default HW_CONFIG selected by the build system. + Debugging options ~~~~~~~~~~~~~~~~~