Merge pull request #1308 from soby-mathew/sm/doc_dyn_cfg
Docs: Update design guide for dynamic config
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
~~~~~~~~~~~~~~~~~