Remove dashes from image names: 'BL3-x' --> 'BL3x'
This patch removes the dash character from the image name, to
follow the image terminology in the Trusted Firmware Wiki page:
https://github.com/ARM-software/arm-trusted-firmware/wiki
Changes apply to output messages, comments and documentation.
non-ARM platform files have been left unmodified.
Change-Id: Ic2a99be4ed929d52afbeb27ac765ceffce46ed76
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index 5e80a7f..3dc60cc 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -13,10 +13,10 @@
3. [Boot Loader stage specific modifications](#3--modifications-specific-to-a-boot-loader-stage)
* [Boot Loader stage 1 (BL1)](#31-boot-loader-stage-1-bl1)
* [Boot Loader stage 2 (BL2)](#32-boot-loader-stage-2-bl2)
- * [Boot Loader stage 3-1 (BL3-1)](#32-boot-loader-stage-3-1-bl3-1)
- * [PSCI implementation (in BL3-1)](#33-power-state-coordination-interface-in-bl3-1)
- * [Interrupt Management framework (in BL3-1)](#34--interrupt-management-framework-in-bl3-1)
- * [Crash Reporting mechanism (in BL3-1)](#35--crash-reporting-mechanism-in-bl3-1)
+ * [Boot Loader stage 3-1 (BL31)](#32-boot-loader-stage-3-1-bl3-1)
+ * [PSCI implementation (in BL31)](#33-power-state-coordination-interface-in-bl3-1)
+ * [Interrupt Management framework (in BL31)](#34--interrupt-management-framework-in-bl3-1)
+ * [Crash Reporting mechanism (in BL31)](#35--crash-reporting-mechanism-in-bl3-1)
4. [Build flags](#4--build-flags)
5. [C Library](#5--c-library)
6. [Storage abstraction layer](#6--storage-abstraction-layer)
@@ -212,16 +212,16 @@
* **#define : BL31_BASE**
- Defines the base address in secure RAM where BL2 loads the BL3-1 binary
+ Defines the base address in secure RAM where BL2 loads the BL31 binary
image. Must be aligned on a page-size boundary.
* **#define : BL31_LIMIT**
- Defines the maximum address in secure RAM that the BL3-1 image can occupy.
+ Defines the maximum address in secure RAM that the BL31 image can occupy.
* **#define : NS_IMAGE_OFFSET**
- Defines the base address in non-secure DRAM where BL2 loads the BL3-3 binary
+ Defines the base address in non-secure DRAM where BL2 loads the BL33 binary
image. Must be aligned on a page-size boundary.
For every image, the platform must define individual identifiers that will be
@@ -238,11 +238,11 @@
* **#define : BL31_IMAGE_ID**
- BL3-1 image identifier, used by BL2 to load BL3-1.
+ BL31 image identifier, used by BL2 to load BL31.
* **#define : BL33_IMAGE_ID**
- BL3-3 image identifier, used by BL2 to load BL3-3.
+ BL33 image identifier, used by BL2 to load BL33.
If Trusted Board Boot is enabled, the following certificate identifiers must
also be defined:
@@ -259,22 +259,22 @@
* **#define : SOC_FW_KEY_CERT_ID**
- BL3-1 key certificate identifier, used by BL2 to load the BL3-1 key
+ BL31 key certificate identifier, used by BL2 to load the BL31 key
certificate.
* **#define : SOC_FW_CONTENT_CERT_ID**
- BL3-1 content certificate identifier, used by BL2 to load the BL3-1 content
+ BL31 content certificate identifier, used by BL2 to load the BL31 content
certificate.
* **#define : NON_TRUSTED_FW_KEY_CERT_ID**
- BL3-3 key certificate identifier, used by BL2 to load the BL3-3 key
+ BL33 key certificate identifier, used by BL2 to load the BL33 key
certificate.
* **#define : NON_TRUSTED_FW_CONTENT_CERT_ID**
- BL3-3 content certificate identifier, used by BL2 to load the BL3-3 content
+ BL33 content certificate identifier, used by BL2 to load the BL33 content
certificate.
If a SCP_BL2 image is supported by the platform, the following constants must
@@ -295,33 +295,33 @@
SCP_BL2 content certificate identifier, used by BL2 to load the SCP_BL2
content certificate (mandatory when Trusted Board Boot is enabled).
-If a BL3-2 image is supported by the platform, the following constants must
+If a BL32 image is supported by the platform, the following constants must
also be defined:
* **#define : BL32_IMAGE_ID**
- BL3-2 image identifier, used by BL2 to load BL3-2.
+ BL32 image identifier, used by BL2 to load BL32.
* **#define : TRUSTED_OS_FW_KEY_CERT_ID**
- BL3-2 key certificate identifier, used by BL2 to load the BL3-2 key
+ BL32 key certificate identifier, used by BL2 to load the BL32 key
certificate (mandatory when Trusted Board Boot is enabled).
* **#define : TRUSTED_OS_FW_CONTENT_CERT_ID**
- BL3-2 content certificate identifier, used by BL2 to load the BL3-2 content
+ BL32 content certificate identifier, used by BL2 to load the BL32 content
certificate (mandatory when Trusted Board Boot is enabled).
* **#define : BL32_BASE**
- Defines the base address in secure memory where BL2 loads the BL3-2 binary
+ Defines the base address in secure memory where BL2 loads the BL32 binary
image. Must be aligned on a page-size boundary.
* **#define : BL32_LIMIT**
- Defines the maximum address that the BL3-2 image can occupy.
+ Defines the maximum address that the BL32 image can occupy.
-If the Test Secure-EL1 Payload (TSP) instantiation of BL3-2 is supported by the
+If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the
platform, the following constants must also be defined:
* **#define : TSP_SEC_MEM_BASE**
@@ -331,9 +331,9 @@
* **#define : TSP_SEC_MEM_SIZE**
- Defines the size of the secure memory used by the BL3-2 image on the
+ Defines the size of the secure memory used by the BL32 image on the
platform. `TSP_SEC_MEM_BASE` and `TSP_SEC_MEM_SIZE` must fully accomodate
- the memory required by the BL3-2 image, defined by `BL32_BASE` and
+ the memory required by the BL32 image, defined by `BL32_BASE` and
`BL32_LIMIT`.
* **#define : TSP_IRQ_SEC_PHY_TIMER**
@@ -366,7 +366,7 @@
entities than this value using `io_open()` will fail with -ENOMEM.
If the platform needs to allocate data within the per-cpu data framework in
-BL3-1, it should define the following macro. Currently this is only required if
+BL31, it should define the following macro. Currently this is only required if
the platform decides not to use the coherent memory section by undefining the
USE_COHERENT_MEM build flag. In this case, the framework allocates the required
memory within the the per-cpu data to minimize wastage.
@@ -381,7 +381,7 @@
* **#define : BL31_PROGBITS_LIMIT**
- Defines the maximum address in secure RAM that the BL3-1's progbits sections
+ Defines the maximum address in secure RAM that the BL31's progbits sections
can occupy.
* **#define : TSP_PROGBITS_LIMIT**
@@ -397,14 +397,14 @@
* **Macro : plat_print_gic_regs**
This macro allows the crash reporting routine to print GIC registers
- in case of an unhandled exception in BL3-1. This aids in debugging and
+ in case of an unhandled exception in BL31. This aids in debugging and
this macro can be defined to be empty in case GIC register reporting is
not desired.
* **Macro : plat_print_interconnect_regs**
This macro allows the crash reporting routine to print interconnect
- registers in case of an unhandled exception in BL3-1. This aids in debugging
+ registers in case of an unhandled exception in BL31. This aids in debugging
and this macro can be defined to be empty in case interconnect register
reporting is not desired. In ARM standard platforms, the CCI snoop
control registers are reported.
@@ -414,7 +414,7 @@
------------------
BL1 by default implements the reset vector where execution starts from a cold
-or warm boot. BL3-1 can be optionally set as a reset vector using the
+or warm boot. BL31 can be optionally set as a reset vector using the
RESET_TO_BL31 make variable.
For each CPU, the reset vector code is responsible for the following tasks:
@@ -426,7 +426,7 @@
performs the necessary steps to remove it from this state.
3. In the case of a warm boot, ensuring that the CPU jumps to a platform-
- specific address in the BL3-1 image in the same processor mode as it was
+ specific address in the BL31 image in the same processor mode as it was
when released from reset.
The following functions need to be implemented by the platform port to enable
@@ -443,7 +443,7 @@
distinguishing between a warm and cold reset for the current CPU using
platform-specific means. If it's a warm reset, then it returns the warm
reset entrypoint point provided to `plat_setup_psci_ops()` during
-BL3-1 initialization. If it's a cold reset then this function must return zero.
+BL31 initialization. If it's a cold reset then this function must return zero.
This function does not follow the Procedure Call Standard used by the
Application Binary Interface for the ARM 64-bit architecture. The caller should
@@ -567,7 +567,7 @@
This function validates the `MPIDR` of a CPU and converts it to an index,
which can be used as a CPU-specific linear index into blocks of memory. In
case the `MPIDR` is invalid, this function returns -1. This function will only
-be invoked by BL3-1 after the power domain topology is initialized and can
+be invoked by BL31 after the power domain topology is initialized and can
utilize the C runtime environment. For further details about how ARM Trusted
Firmware represents the power domain topology and how this relates to the
linear CPU index, please refer [Power Domain Topology Design].
@@ -848,33 +848,33 @@
implemented in the `bl2_plat_handle_scp_bl2()` function.
If `SCP_BL2_BASE` is not defined then this step is not performed.
-2. Loading the BL3-1 binary image into secure RAM from non-volatile storage. To
- load the BL3-1 image, BL2 makes use of the `meminfo` structure passed to it
+2. 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 BL3-1 is loaded through the constant `BL31_BASE`. BL2 uses this
- information to determine if there is enough memory to load the BL3-1 image.
+ 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.
-3. (Optional) Loading the BL3-2 binary image (if present) from platform
- provided non-volatile storage. To load the BL3-2 image, BL2 makes use of
+3. (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 BL3-2 is loaded
+ 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 BL3-2 image.
+ 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.
-4. (Optional) Arranging to pass control to the BL3-2 image (if present) that
+4. (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
- BL3-1 should pass control to the BL3-2 image.
+ BL31 should pass control to the BL32 image.
-5. Loading the normal world BL3-3 binary image into non-secure DRAM from
- platform storage and arranging for BL3-1 to pass control to this image. This
+5. Loading the normal world BL33 binary image 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.
6. BL2 populates an `entry_point_info` structure in memory provided by the
- platform with information about how BL3-1 should pass control to the
+ platform with information about how BL31 should pass control to the
other BL images.
The following functions must be implemented by the platform port to enable BL2
@@ -976,22 +976,22 @@
Return : bl31_params *
BL2 platform code needs to return a pointer to a `bl31_params` structure it
-will use for passing information to BL3-1. The `bl31_params` structure carries
+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 BL3-3 image in the `bl33_ep_info` field
- - Information about executing the BL3-2 image in the `bl32_ep_info` field
- - Information about the type and extents of BL3-1 image in the
+ - 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 BL3-2 image in the
+ - Information about the type and extents of BL32 image in the
`bl32_image_info` field
- - Information about the type and extents of BL3-3 image in the
+ - 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 BL3-1 initialisation code. BL3-1 might choose to copy the
-necessary content, or maintain the structures until BL3-3 is initialised.
+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]
@@ -1000,8 +1000,8 @@
Return : entry_point_info *
BL2 platform code returns a pointer which is used to populate the entry point
-information for BL3-1 entry point. The location pointed by it should be
-accessible from BL1 while processing the synchronous exception to run to BL3-1.
+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.
@@ -1012,9 +1012,9 @@
Argument : image_info *, entry_point_info *
Return : void
-In the normal boot flow, this function is called after loading BL3-1 image and
+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 BL3-1.
+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
@@ -1025,9 +1025,9 @@
Argument : image_info *, entry_point_info *
Return : void
-This function is called after loading BL3-2 image and it can be used to
+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 BL3-2.
+and SPSR which represents the entry point system state for BL32.
### Function : bl2_plat_set_bl33_ep_info() [mandatory]
@@ -1035,9 +1035,9 @@
Argument : image_info *, entry_point_info *
Return : void
-This function is called after loading BL3-3 image and it can be used to
+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 BL3-3.
+and SPSR which represents the entry point system state for BL33.
### Function : bl2_plat_get_bl32_meminfo() [mandatory]
@@ -1046,8 +1046,8 @@
Return : void
This function is used to get the memory limits where BL2 can load the
-BL3-2 image. The meminfo provided by this is used by load_image() to
-validate whether the BL3-2 image can be loaded with in the given
+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]
@@ -1056,8 +1056,8 @@
Return : void
This function is used to get the memory limits where BL2 can load the
-BL3-3 image. The meminfo provided by this is used by load_image() to
-validate whether the BL3-3 image can be loaded with in the given
+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.
### Function : bl2_plat_flush_bl31_params() [mandatory]
@@ -1066,7 +1066,7 @@
Return : void
Once BL2 has populated all the structures that needs to be read by BL1
-and BL3-1 including the bl31_params structures and its sub-structures,
+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
@@ -1077,44 +1077,44 @@
Return : unsigned long
As previously described, BL2 is responsible for arranging for control to be
-passed to a normal world BL image through BL3-1. This function returns the
-entrypoint of that image, which BL3-1 uses to jump to it.
+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 BL3-3 image (e.g. UEFI).
+BL2 is responsible for loading the normal world BL33 image (e.g. UEFI).
-3.2 Boot Loader Stage 3-1 (BL3-1)
+3.2 Boot Loader Stage 3-1 (BL31)
---------------------------------
-During cold boot, the BL3-1 stage is executed only by the primary CPU. This is
+During cold boot, the BL31 stage is executed only by the primary CPU. This is
determined in BL1 using the `platform_is_primary_cpu()` function. BL1 passes
-control to BL3-1 at `BL31_BASE`. During warm boot, BL3-1 is executed by all
-CPUs. BL3-1 executes at EL3 and is responsible for:
+control to BL31 at `BL31_BASE`. During warm boot, BL31 is executed by all
+CPUs. BL31 executes at EL3 and is responsible for:
1. Re-initializing all architectural and platform state. Although BL1 performs
- some of this initialization, BL3-1 remains resident in EL3 and must ensure
+ some of this initialization, BL31 remains resident in EL3 and must ensure
that EL3 architectural and platform state is completely initialized. It
should make no assumptions about the system state when it receives control.
2. Passing control to a normal world BL image, pre-loaded at a platform-
- specific address by BL2. BL3-1 uses the `entry_point_info` structure that BL2
+ specific address by BL2. BL31 uses the `entry_point_info` structure that BL2
populated in memory to do this.
-3. Providing runtime firmware services. Currently, BL3-1 only implements a
+3. Providing runtime firmware services. Currently, BL31 only implements a
subset of the Power State Coordination Interface (PSCI) API as a runtime
service. See Section 3.3 below for details of porting the PSCI
implementation.
-4. Optionally passing control to the BL3-2 image, pre-loaded at a platform-
- specific address by BL2. BL3-1 exports a set of apis that allow runtime
+4. 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. BL3-1 uses the `entry_point_info`
+ executed and run the corresponding image. BL31 uses the `entry_point_info`
structure populated by BL2 to do this.
-If BL3-1 is a reset vector, It also needs to handle the reset as specified in
+If BL31 is a reset vector, It also needs to handle the reset as specified in
section 2.2 before the tasks described above.
-The following functions must be implemented by the platform port to enable BL3-1
+The following functions must be implemented by the platform port to enable BL31
to perform the above tasks.
@@ -1131,11 +1131,11 @@
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 BL3-1 and similarly the `void *` pointing
+subsequently overwritten by BL31 and similarly the `void *` pointing
to the platform data also needs to be saved.
In ARM standard platforms, BL2 passes a pointer to a `bl31_params` structure
-in BL2 memory. BL3-1 copies the information in this pointer to internal data
+in BL2 memory. BL31 copies the information in this pointer to internal data
structures.
@@ -1162,7 +1162,7 @@
called by the primary CPU.
The purpose of this function is to complete platform initialization so that both
-BL3-1 runtime services and normal world software can function correctly.
+BL31 runtime services and normal world software can function correctly.
In ARM standard platforms, this function does the following:
* Initializes the generic interrupt controller.
@@ -1196,7 +1196,7 @@
port does the necessary initializations in `bl31_plat_arch_setup()`.
This function is called by `bl31_main()` to retrieve information provided by
-BL2 for the next image in the security state specified by the argument. BL3-1
+BL2 for the next image in the security state specified by the argument. BL31
uses this information to pass control to that image in the specified security
state. This function must return a pointer to the `entry_point_info` structure
(that was copied during `bl31_early_platform_setup()`) if the image exists. It
@@ -1232,7 +1232,7 @@
assertion is raised if the value of the constant is not aligned to the cache
line boundary.
-3.3 Power State Coordination Interface (in BL3-1)
+3.3 Power State Coordination Interface (in BL31)
------------------------------------------------
The ARM Trusted Firmware's implementation of the PSCI API is based around the
@@ -1249,7 +1249,7 @@
(for example, the system). More details on the power domain topology and its
organization can be found in [Power Domain Topology Design].
-BL3-1's platform initialization code exports a pointer to the platform-specific
+BL31's platform initialization code exports a pointer to the platform-specific
power management operations required for the PSCI implementation to function
correctly. This information is populated in the `plat_psci_ops` structure. The
PSCI implementation calls members of the `plat_psci_ops` structure for performing
@@ -1300,7 +1300,7 @@
This function returns a pointer to the byte array containing the power domain
topology tree description. The format and method to construct this array are
-described in [Power Domain Topology Design]. The BL3-1 PSCI initilization code
+described in [Power Domain Topology Design]. The BL31 PSCI initilization code
requires this array to be described by the platform, either statically or
dynamically, to initialize the power domain topology tree. In case the array
is populated dynamically, then plat_core_pos_by_mpidr() and
@@ -1322,7 +1322,7 @@
the platform layer know about the warm boot entrypoint through the
`sec_entrypoint` (first argument) and to export handler routines for
platform-specific psci power management actions by populating the passed
-pointer with a pointer to BL3-1's private `plat_psci_ops` structure.
+pointer with a pointer to BL31's private `plat_psci_ops` structure.
A description of each member of this structure is given below. Please refer to
the ARM FVP specific implementation of these handlers in
@@ -1441,9 +1441,9 @@
enter system suspend.
-3.4 Interrupt Management framework (in BL3-1)
+3.4 Interrupt Management framework (in BL31)
----------------------------------------------
-BL3-1 implements an Interrupt Management Framework (IMF) to manage interrupts
+BL31 implements an Interrupt Management Framework (IMF) to manage interrupts
generated in either security state and targeted to EL1 or EL2 in the non-secure
state or EL3/S-EL1 in the secure state. The design of this framework is
described in the [IMF Design Guide]
@@ -1573,15 +1573,15 @@
type of interrupt.
-3.5 Crash Reporting mechanism (in BL3-1)
+3.5 Crash Reporting mechanism (in BL31)
----------------------------------------------
-BL3-1 implements a crash reporting mechanism which prints the various registers
+BL31 implements a crash reporting mechanism which prints the various registers
of the CPU to enable quick crash analysis and debugging. It requires that a
console is designated as the crash console by the platform which will be used to
print the register dump.
The following functions must be implemented by the platform if it wants crash
-reporting mechanism in BL3-1. The functions are implemented in assembly so that
+reporting mechanism in BL31. The functions are implemented in assembly so that
they can be invoked without a C Runtime stack.
### Function : plat_crash_console_init
@@ -1620,7 +1620,7 @@
* **NEED_BL33**
By default, this flag is defined `yes` by the build system and `BL33`
build option should be supplied as a build option. The platform has the option
- of excluding the BL3-3 image in the `fip` image by defining this flag to
+ of excluding the BL33 image in the `fip` image by defining this flag to
`no`.
5. C Library