github
/
arm-trusted-firmware
mirror of https://github.com/ARM-software/arm-trusted-firmware.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Merge pull request #1308 from soby-mathew/sm/doc_dyn_cfg 

Docs: Update design guide for dynamic config
pull/1309/merge
davidcunado-arm 7 years ago
committed by GitHub
parent
1d060675d2 b2a68f88c1
commit
c3e34a9e01
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 132 additions and 51 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 142
      docs/firmware-design.rst
  2. 28
      docs/porting-guide.rst
  3. 13
      docs/user-guide.rst

142
docs/firmware-design.rst
View File

@ -77,11 +77,57 @@ one or more of these memory regions.
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 @@ On ARM platforms, BL1 performs the following platform initializations:
- 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 @@ In the normal boot flow, BL1 execution continues as follows:
"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 @@ In the normal boot flow, BL1 execution continues as follows:
"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 @@ On ARM platforms, BL2 performs the following platform initializations:
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 @@ 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.
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 @@ layout of the other images in Trusted SRAM.
| 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 +----------+
Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL31 PROGBITS |
|----------| ------------------
| BL2 |
|----------|
| |
0x04001000 +----------+
| Shared |
0x04000000 +----------+
Trusted ROM
0x04000000 +----------+
| BL1 (ro) |
0x00000000 +----------+
DRAM
0xffffffff +--------------+
: :
|--------------|
| HW_CONFIG |
0x83000000 |--------------| (non-secure)
| |
0x80000000 +--------------+
Trusted DRAM
0x08000000 +--------------+
| BL32 |
0x06000000 +--------------+
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 @@ layout of the other images in Trusted SRAM.
DRAM
0xffffffff +----------+
| BL32 | (secure)
| BL32 | (secure)
0xff000000 +----------+
| |
: : (non-secure)
@ -1881,7 +1947,7 @@ layout of the other images in Trusted SRAM.
DRAM
0xFFE00000 +----------+
| BL32 | (secure)
| BL32 | (secure)
0xFF000000 |----------|
| |
: : (non-secure)
@ -2663,7 +2729,7 @@ References
--------------
*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

28
docs/porting-guide.rst
View File

@ -1076,20 +1076,16 @@ warm boot. For each CPU, BL1 is responsible for the following tasks:
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 @@ This function can be used by the platforms to update/use image information
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]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

13
docs/user-guide.rst
View File

@ -776,6 +776,19 @@ ARM FVP platform specific build options
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
~~~~~~~~~~~~~~~~~

Write Preview
Loading…
Cancel
Save