Consolidate design and porting documentation
Consolidate firmware-design.md and porting-guide.pm so
that recently added sections fit better with
pre-existing sections. Make the documentation more
consistent in use of terminology.
Change-Id: Id87050b096122fbd845189dc2fe1cd17c3003468
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index 4e7890e..11d6f1d 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -44,12 +44,13 @@
CPU has performed enough initialization to boot them.
The cold boot path in this implementation of the ARM Trusted Firmware is divided
-into three stages (in order of execution):
+into five steps (in order of execution):
-* Boot Loader stage 1 (BL1)
-* Boot Loader stage 2 (BL2)
-* Boot Loader stage 3 (BL3-1). The '1' distinguishes this from other 3rd level
- boot loader stages.
+* Boot Loader stage 1 (BL1) _AP Trusted ROM_
+* Boot Loader stage 2 (BL2) _Trusted Boot Firmware_
+* Boot Loader stage 3-1 (BL3-1) _EL3 Runtime Firmware_
+* Boot Loader stage 3-2 (BL3-2) _Secure-EL1 Payload_ (optional)
+* Boot Loader stage 3-3 (BL3-3) _Non-trusted Firmware_
The ARM Fixed Virtual Platforms (FVPs) provide trusted ROM, trusted SRAM and
trusted DRAM regions. Each boot loader stage uses one or more of these
@@ -171,9 +172,9 @@
1. 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. The filename of the BL2 raw binary image
- must be `bl2.bin`. If the BL2 image file is not present or if there is not
- enough free trusted SRAM the following error message is printed:
+ platform-specific base address. If the BL2 image file is not present or if
+ there is not enough free trusted SRAM the following error message is
+ printed:
"Failed to load boot loader stage 2 (BL2) firmware."
@@ -198,7 +199,7 @@
### BL2
-BL1 loads and passes control to BL2 at Secure EL1. BL2 is linked against and
+BL1 loads and passes control to BL2 at Secure-EL1. BL2 is linked against and
loaded at a platform-specific base address (more information can be found later
in this document). The functionality implemented by BL2 is as follows.
@@ -217,60 +218,55 @@
stages of the ARM Trusted Firmware or normal world software. It copies the
information regarding the trusted SRAM populated by BL1 using a
platform-specific mechanism. It calculates the limits of DRAM (main memory)
-to determine whether there is enough space to load the normal world software
-images. A platform defined base address is used to specify the load address for
-the BL3-1 image. It also defines the extents of memory available for use by the
-BL3-2 image.
+to determine whether there is enough space to load the BL3-3 image. A platform
+defined base address is used to specify the load address for the BL3-1 image.
+It also defines the extents of memory available for use by the BL3-2 image.
-#### Normal world image load
+#### BL3-1 (EL3 Runtime Firmware) image load
-BL2 loads the normal world firmware image (e.g. UEFI). BL2 relies on BL3-1 to
-pass control to the normal world software image it loads. Hence, BL2 populates
-a platform-specific area of memory with the entrypoint and Current Program
-Status Register (`CPSR`) of the normal world software image. The entrypoint is
-the load address of the normal world software image. The `CPSR` is determined as
-specified in Section 5.13 of the [PSCI PDD] [PSCI]. This information is passed
-to BL3-1.
+BL2 loads the BL3-1 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 the BL3-1 image loads successfully,
+BL2 updates the amount of trusted SRAM used and available for use by BL3-1.
+This information is populated at a platform-specific memory address.
-#### BL3-2 (Secure Payload) image load
+#### BL3-2 (Secure-EL1 Payload) image load
-BL2 loads the optional BL3-2 image. The image executes in the secure world. BL2
+BL2 loads the optional BL3-2 image from platform storage into a platform-
+specific region of secure memory. The image executes in the secure world. BL2
relies on BL3-1 to pass control to the BL3-2 image, if present. Hence, BL2
-populates a platform- specific area of memory with the entrypoint and Current
-Program Status Register (`CPSR`) of the BL3-2 image. The entrypoint is the load
-address of the BL3-2 image. The `CPSR` is initialized with Secure EL1 and Stack
-pointer set to SP_EL1 (EL1h) as the mode, exception bits disabled (DAIF bits)
-and AArch64 execution state. This information is passed to BL3-1.
+populates a platform-specific area of memory with the entrypoint/load-address
+of the BL3-2 image. The value of the Saved Processor Status Register (`SPSR`)
+for entry into BL3-2 is not determined by BL2, it is initialized by the
+Secure-EL1 Payload Dispatcher (see later) within BL3-1, which is responsible for
+managing interaction with BL3-2. This information is passed to BL3-1.
-##### UEFI firmware load
+#### BL3-3 (Non-trusted Firmware) image load
-BL2 loads the BL3-3 (UEFI) image into non-secure memory as defined by the
-platform (`0x88000000` for FVPs), and arranges for BL3-1 to pass control to that
-location. As mentioned earlier, BL2 populates platform-specific memory with the
-entrypoint and `CPSR` of the BL3-3 image.
+BL2 loads the BL3-3 image (e.g. UEFI or other test or boot software) from
+platform storage into non-secure memory as defined by the platform
+(`0x88000000` for FVPs).
-#### BL3-1 image load and execution
+BL2 relies on BL3-1 to pass control to BL3-3 once secure state initialization is
+complete. Hence, BL2 populates a platform-specific area of memory with the
+entrypoint and Saved Program Status Register (`SPSR`) of the normal world
+software image. The entrypoint is the load address of the BL3-3 image. The
+`SPSR` is determined as specified in Section 5.13 of the [PSCI PDD] [PSCI]. This
+information is passed to BL3-1.
-BL2 execution continues as follows:
+#### BL3-1 (EL3 Runtime Firmware) execution
-1. BL2 loads the BL3-1 image into a platform-specific address in trusted SRAM
- and the BL3-3 image into a platform specific address in non-secure DRAM.
- The images are identified by the files `bl31.bin` and `bl33.bin` in
- platform storage. If there is not enough memory to load the images or the
- images are missing it leads to an assertion failure. If the BL3-1 image
- loads successfully, BL1 updates the amount of trusted SRAM used and
- available for use by BL3-1. This information is populated at a
- platform-specific memory address.
+BL2 execution continues as follows:
-2. BL2 passes control back to BL1 by raising an SMC, providing BL1 with the
+1. BL2 passes control back to BL1 by raising an SMC, providing BL1 with the
BL3-1 entrypoint. The exception is handled by the SMC exception handler
installed by BL1.
-3. BL1 turns off the MMU and flushes the caches. It clears the
+2. BL1 turns off the MMU and flushes the caches. It clears the
`SCTLR_EL3.M/I/C` bits, flushes the data cache to the point of coherency
and invalidates the TLBs.
-4. BL1 passes control to BL3-1 at the specified entrypoint at EL3.
+3. BL1 passes control to BL3-1 at the specified entrypoint at EL3.
### BL3-1
@@ -299,8 +295,8 @@
BL3-1 performs detailed platform initialization, which enables normal world
software to function correctly. It also retrieves entrypoint information for
-the normal world software image loaded by BL2 from the platform defined
-memory address populated by BL2.
+the BL3-3 image loaded by BL2 from the platform defined memory address populated
+by BL2.
* GICv2 initialization:
@@ -1000,17 +996,15 @@
### Loading from a Firmware Image Package (FIP)
The Firmware Image Package (FIP) driver can load images from a binary package on
-non-volatile platform storage. For the FVPs this currently NOR FLASH. For
-information on how to load a FIP into FVP NOR FLASH see the "Running the
-software" section.
+non-volatile platform storage. For the FVPs this is currently NOR FLASH.
Bootloader images are loaded according to the platform policy as specified in
`plat/<platform>/plat_io_storage.c`. For the FVPs this means the platform will
attempt to load images from a Firmware Image Package located at the start of NOR
FLASH0.
-Currently the FVPs policy only allows for loading of known images. The platform
-policy can be modified to add additional images.
+Currently the FVP's policy only allows loading of a known set of images. The
+platform policy can be modified to allow additional images.
8. Code Structure
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index c9e4a50..56467fb 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -616,7 +616,8 @@
The ARM FVP port also populates the `bl32_meminfo` field in the `bl31_args`
structure pointed to by `bl2_to_bl31_args` with the extents of memory available
for use by the BL3-2 image. The memory is allocated in the Secure DRAM from the
-address defined by the constant `BL32_BASE`.
+address defined by the constant `BL32_BASE`. The ARM FVP port currently loads
+the BL3-2 image at the Secure DRAM address `0x6002000`.
The non-secure memory extents used for loading BL3-3 are also initialized in
this function. This information is accessible in the `bl33_meminfo` field in