Djam/arm-trusted-firmware
1
0
Fork 0
mirror of https://github.com/ARM-software/arm-trusted-firmware.git synced 2025-04-17 10:04:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Remove dashes from image names: 'BL3-x' --> 'BL3x'

Browse source 
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
This commit is contained in:
Juan Castillo 2015-12-14 09:35:25 +00:00
parent f59821d512
commit d178637d2b
37 changed files with 470 additions and 470 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
Makefile
View file

@ -309,7 +309,7 @@ ifeq (${DISABLE_PEDANTIC},0)
CFLAGS += -pedantic
endif
# Using the ARM Trusted Firmware BL2 implies that a BL3-3 image also need to be
# Using the ARM Trusted Firmware BL2 implies that a BL33 image also need to be
# supplied for the FIP and Certificate generation tools. This flag can be
# overridden by the platform.
ifdef BL2_SOURCES
@ -589,8 +589,8 @@ help:
@echo " bl1 Build the BL1 binary"
@echo " bl2 Build the BL2 binary"
@echo " bl2u Build the BL2U binary"
@echo " bl31 Build the BL3-1 binary"
@echo " bl32 Build the BL3-2 binary"
@echo " bl31 Build the BL31 binary"
@echo " bl32 Build the BL32 binary"
@echo " certificates Build the certificates (requires 'GENERATE_COT=1')"
@echo " fip Build the Firmware Image Package (FIP)"
@echo " fwu_fip Build the FWU Firmware Image Package (FIP)"

2
bl1/bl1_main.c
View file

@ -216,7 +216,7 @@ void bl1_load_bl2(void)
******************************************************************************/
void bl1_print_bl31_ep_info(const entry_point_info_t *bl31_ep_info)
{
NOTICE("BL1: Booting BL3-1\n");
NOTICE("BL1: Booting BL31\n");
print_entry_point_info(bl31_ep_info);
}

50
bl2/bl2_main.c
View file

@ -93,9 +93,9 @@ static int load_scp_bl2(void)
#ifndef EL3_PAYLOAD_BASE
/*******************************************************************************
* Load the BL3-1 image.
* Load the BL31 image.
* The bl2_to_bl31_params and bl31_ep_info params will be updated with the
* relevant BL3-1 information.
* relevant BL31 information.
* Return 0 on success, a negative error code otherwise.
******************************************************************************/
static int load_bl31(bl31_params_t *bl2_to_bl31_params,
@ -104,17 +104,17 @@ static int load_bl31(bl31_params_t *bl2_to_bl31_params,
meminfo_t *bl2_tzram_layout;
int e;
INFO("BL2: Loading BL3-1\n");
INFO("BL2: Loading BL31\n");
assert(bl2_to_bl31_params != NULL);
assert(bl31_ep_info != NULL);
/* Find out how much free trusted ram remains after BL2 load */
bl2_tzram_layout = bl2_plat_sec_mem_layout();
/* Set the X0 parameter to BL3-1 */
/* Set the X0 parameter to BL31 */
bl31_ep_info->args.arg0 = (unsigned long)bl2_to_bl31_params;
/* Load the BL3-1 image */
/* Load the BL31 image */
e = load_auth_image(bl2_tzram_layout,
BL31_IMAGE_ID,
BL31_BASE,
@ -130,12 +130,12 @@ static int load_bl31(bl31_params_t *bl2_to_bl31_params,
}
/*******************************************************************************
* Load the BL3-2 image if there's one.
* The bl2_to_bl31_params param will be updated with the relevant BL3-2
* Load the BL32 image if there's one.
* The bl2_to_bl31_params param will be updated with the relevant BL32
* information.
* If a platform does not want to attempt to load BL3-2 image it must leave
* If a platform does not want to attempt to load BL32 image it must leave
* BL32_BASE undefined.
* Return 0 on success or if there's no BL3-2 image to load, a negative error
* Return 0 on success or if there's no BL32 image to load, a negative error
* code otherwise.
******************************************************************************/
static int load_bl32(bl31_params_t *bl2_to_bl31_params)
@ -144,11 +144,11 @@ static int load_bl32(bl31_params_t *bl2_to_bl31_params)
#ifdef BL32_BASE
meminfo_t bl32_mem_info;
INFO("BL2: Loading BL3-2\n");
INFO("BL2: Loading BL32\n");
assert(bl2_to_bl31_params != NULL);
/*
* It is up to the platform to specify where BL3-2 should be loaded if
* It is up to the platform to specify where BL32 should be loaded if
* it exists. It could create space in the secure sram or point to a
* completely different memory.
*/
@ -170,8 +170,8 @@ static int load_bl32(bl31_params_t *bl2_to_bl31_params)
}
/*******************************************************************************
* Load the BL3-3 image.
* The bl2_to_bl31_params param will be updated with the relevant BL3-3
* Load the BL33 image.
* The bl2_to_bl31_params param will be updated with the relevant BL33
* information.
* Return 0 on success, a negative error code otherwise.
******************************************************************************/
@ -180,12 +180,12 @@ static int load_bl33(bl31_params_t *bl2_to_bl31_params)
meminfo_t bl33_mem_info;
int e;
INFO("BL2: Loading BL3-3\n");
INFO("BL2: Loading BL33\n");
assert(bl2_to_bl31_params != NULL);
bl2_plat_get_bl33_meminfo(&bl33_mem_info);
/* Load the BL3-3 image in non-secure memory provided by the platform */
/* Load the BL33 image in non-secure memory provided by the platform */
e = load_auth_image(&bl33_mem_info,
BL33_IMAGE_ID,
plat_get_ns_image_entrypoint(),
@ -203,7 +203,7 @@ static int load_bl33(bl31_params_t *bl2_to_bl31_params)
/*******************************************************************************
* The only thing to do in BL2 is to load further images and pass control to
* BL3-1. The memory occupied by BL2 will be reclaimed by BL3-x stages. BL2 runs
* BL31. The memory occupied by BL2 will be reclaimed by BL3x stages. BL2 runs
* entirely in S-EL1.
******************************************************************************/
void bl2_main(void)
@ -237,7 +237,7 @@ void bl2_main(void)
/*
* Get a pointer to the memory the platform has set aside to pass
* information to BL3-1.
* information to BL31.
*/
bl2_to_bl31_params = bl2_plat_get_bl31_params();
bl31_ep_info = bl2_plat_get_bl31_ep_info();
@ -248,7 +248,7 @@ void bl2_main(void)
* images. Just update the BL31 entrypoint info structure to make BL1
* jump to the EL3 payload.
* The pointer to the memory the platform has set aside to pass
* information to BL3-1 in the normal boot flow is reused here, even
* information to BL31 in the normal boot flow is reused here, even
* though only a fraction of the information contained in the
* bl31_params_t structure makes sense in the context of EL3 payloads.
* This will be refined in the future.
@ -260,23 +260,23 @@ void bl2_main(void)
#else
e = load_bl31(bl2_to_bl31_params, bl31_ep_info);
if (e) {
ERROR("Failed to load BL3-1 (%i)\n", e);
ERROR("Failed to load BL31 (%i)\n", e);
plat_error_handler(e);
}
e = load_bl32(bl2_to_bl31_params);
if (e) {
if (e == -EAUTH) {
ERROR("Failed to authenticate BL3-2\n");
ERROR("Failed to authenticate BL32\n");
plat_error_handler(e);
} else {
WARN("Failed to load BL3-2 (%i)\n", e);
WARN("Failed to load BL32 (%i)\n", e);
}
}
e = load_bl33(bl2_to_bl31_params);
if (e) {
ERROR("Failed to load BL3-3 (%i)\n", e);
ERROR("Failed to load BL33 (%i)\n", e);
plat_error_handler(e);
}
#endif /* EL3_PAYLOAD_BASE */
@ -285,9 +285,9 @@ void bl2_main(void)
bl2_plat_flush_bl31_params();
/*
* Run BL3-1 via an SMC to BL1. Information on how to pass control to
* the BL3-2 (if present) and BL3-3 software images will be passed to
* BL3-1 as an argument.
* Run BL31 via an SMC to BL1. Information on how to pass control to
* the BL32 (if present) and BL33 software images will be passed to
* BL31 as an argument.
*/
smc(BL1_SMC_RUN_IMAGE, (unsigned long)bl31_ep_info, 0, 0, 0, 0, 0, 0);
}

2
bl31/aarch64/bl31_entrypoint.S
View file

@ -91,7 +91,7 @@ func bl31_entrypoint
_exception_vectors=runtime_exceptions
/* ---------------------------------------------------------------------
* For RESET_TO_BL31 systems, BL3-1 is the first bootloader to run so
* For RESET_TO_BL31 systems, BL31 is the first bootloader to run so
* there's no argument to relay from a previous bootloader. Zero the
* arguments passed to the platform layer to reflect that.
* ---------------------------------------------------------------------

4
bl31/bl31.ld.S
View file

@ -94,7 +94,7 @@ SECTIONS
} >RAM
#ifdef BL31_PROGBITS_LIMIT
ASSERT(. <= BL31_PROGBITS_LIMIT, "BL3-1 progbits has exceeded its limit.")
ASSERT(. <= BL31_PROGBITS_LIMIT, "BL31 progbits has exceeded its limit.")
#endif
stacks (NOLOAD) : {
@ -184,5 +184,5 @@ SECTIONS
__COHERENT_RAM_END_UNALIGNED__ - __COHERENT_RAM_START__;
#endif
ASSERT(. <= BL31_LIMIT, "BL3-1 image has exceeded its limit.")
ASSERT(. <= BL31_LIMIT, "BL31 image has exceeded its limit.")
}

2
bl31/bl31.mk
View file

@ -62,7 +62,7 @@ endif
BL31_LINKERFILE := bl31/bl31.ld.S
# Flag used to inidicate if Crash reporting via console should be included
# in BL3-1. This defaults to being present in DEBUG builds only
# in BL31. This defaults to being present in DEBUG builds only
ifndef CRASH_REPORTING
CRASH_REPORTING := $(DEBUG)
endif

10
bl31/bl31_main.c
View file

@ -71,8 +71,8 @@ void bl31_lib_init(void)
******************************************************************************/
void bl31_main(void)
{
NOTICE("BL3-1: %s\n", version_string);
NOTICE("BL3-1: %s\n", build_message);
NOTICE("BL31: %s\n", version_string);
NOTICE("BL31: %s\n", build_message);
/* Perform remaining generic architectural setup from EL3 */
bl31_arch_setup();
@ -84,7 +84,7 @@ void bl31_main(void)
bl31_lib_init();
/* Initialize the runtime services e.g. psci */
INFO("BL3-1: Initializing runtime services\n");
INFO("BL31: Initializing runtime services\n");
runtime_svc_init();
/*
@ -101,7 +101,7 @@ void bl31_main(void)
* If SPD had registerd an init hook, invoke it.
*/
if (bl32_init) {
INFO("BL3-1: Initializing BL3-2\n");
INFO("BL31: Initializing BL32\n");
(*bl32_init)();
}
/*
@ -153,7 +153,7 @@ void bl31_prepare_next_image_entry(void)
assert(next_image_info);
assert(image_type == GET_SECURITY_STATE(next_image_info->h.attr));
INFO("BL3-1: Preparing for EL3 exit to %s world\n",
INFO("BL31: Preparing for EL3 exit to %s world\n",
(image_type == SECURE) ? "secure" : "normal");
print_entry_point_info(next_image_info);
cm_init_my_context(next_image_info);

2
bl32/tsp/tsp.ld.S
View file

@ -138,5 +138,5 @@ SECTIONS
__COHERENT_RAM_END_UNALIGNED__ - __COHERENT_RAM_START__;
#endif
ASSERT(. <= BL32_LIMIT, "BL3-2 image has exceeded its limit.")
ASSERT(. <= BL32_LIMIT, "BL32 image has exceeded its limit.")
}

4
bl32/tsp/tsp.mk
View file

@ -41,8 +41,8 @@ BL32_SOURCES += bl32/tsp/tsp_main.c \
BL32_LINKERFILE := bl32/tsp/tsp.ld.S
# This flag determines if the TSPD initializes BL3-2 in tspd_init() (synchronous
# method) or configures BL3-1 to pass control to BL3-2 instead of BL3-3
# This flag determines if the TSPD initializes BL32 in tspd_init() (synchronous
# method) or configures BL31 to pass control to BL32 instead of BL33
# (asynchronous method).
TSP_INIT_ASYNC := 0

2
common/aarch64/early_exceptions.S
View file

@ -37,7 +37,7 @@
/* -----------------------------------------------------
* Very simple stackless exception handlers used by BL2
* and BL3-1 bootloader stages. BL3-1 uses them before
* and BL31 bootloader stages. BL31 uses them before
* stacks are setup. BL2 uses them throughout.
* -----------------------------------------------------
*/

44
docs/auth-framework.md
View file

@ -83,7 +83,7 @@ behind them. These aspects are key to verify a Chain of Trust.
A CoT is basically a sequence of authentication images which usually starts with
a root of trust and culminates in a single data image. The following diagram
illustrates how this maps to a CoT for the BL3-1 image described in the
illustrates how this maps to a CoT for the BL31 image described in the
TBBR-Client specification.
```
@ -98,7 +98,7 @@ TBBR-Client specification.
/ |
L v
+------------------+ +-------------------+
| Trusted World |------>| BL3-1 Key |
| Trusted World |------>| BL31 Key |
| Public Key | | Certificate |
+------------------+ | (Auth Image) |
+-------------------+
@ -108,7 +108,7 @@ TBBR-Client specification.
/ |
/ v
+------------------+ L +-------------------+
| BL3-1 Content |------>| BL3-1 Content |
| BL31 Content |------>| BL31 Content |
| Certificate PK | | Certificate |
+------------------+ | (Auth Image) |
+-------------------+
@ -118,7 +118,7 @@ TBBR-Client specification.
/ |
/ v
+------------------+ L +-------------------+
| BL3-1 Hash |------>| BL3-1 Image |
| BL31 Hash |------>| BL31 Image |
| | | (Data Image) |
+------------------+ | |
+-------------------+
@ -211,15 +211,15 @@ It is responsible for:
3. Tracking which images have been verified. In case an image is a part of
multiple CoTs then it should be verified only once e.g. the Trusted World
Key Certificate in the TBBR-Client spec. contains information to verify
SCP_BL2, BL3-1, BL3-2 each of which have a separate CoT. (This
SCP_BL2, BL31, BL32 each of which have a separate CoT. (This
responsibility has not been described in this document but should be
trivial to implement).
4. Reusing memory meant for a data image to verify authentication images e.g.
in the CoT described in Diagram 2, each certificate can be loaded and
verified in the memory reserved by the platform for the BL3-1 image. By the
time BL3-1 (the data image) is loaded, all information to authenticate it
will have been extracted from the parent image i.e. BL3-1 content
verified in the memory reserved by the platform for the BL31 image. By the
time BL31 (the data image) is loaded, all information to authenticate it
will have been extracted from the parent image i.e. BL31 content
certificate. It is assumed that the size of an authentication image will
never exceed the size of a data image. It should be possible to verify this
at build time using asserts.
@ -492,7 +492,7 @@ typedef struct auth_param_type_desc_s {
`cookie` is used by the platform to specify additional information to the IPM
which enables it to uniquely identify the parameter that should be extracted
from an image. For example, the hash of a BL3-x image in its corresponding
from an image. For example, the hash of a BL3x image in its corresponding
content certificate is stored in an X509v3 custom extension field. An extension
field can only be identified using an OID. In this case, the `cookie` could
contain the pointer to the OID defined by the platform for the hash extension
@ -634,9 +634,9 @@ and thus all CoTs must present:
* `BL2`
* `SCP_BL2` (platform specific)
* `BL3-1`
* `BL3-2` (optional)
* `BL3-3`
* `BL31`
* `BL32` (optional)
* `BL33`
The TBBR specifies the additional certificates that must accompany these images
for a proper authentication. Details about the TBBR CoT may be found in the
@ -705,9 +705,9 @@ process, some of the buffers may be reused at different stages during the boot.
Next in that file, the parameter descriptors are defined. These descriptors will
be used to extract the parameter data from the corresponding image.
#### 4.1.1 Example: the BL3-1 Chain of Trust
#### 4.1.1 Example: the BL31 Chain of Trust
Four image descriptors form the BL3-1 Chain of Trust:
Four image descriptors form the BL31 Chain of Trust:
```
[TRUSTED_KEY_CERT_ID] = {
@ -836,27 +836,27 @@ is created in the `authenticated_data` array for that purpose. In that entry,
the corresponding parameter descriptor must be specified along with the buffer
address to store the parameter value. In this case, the `tz_world_pk` descriptor
is used to extract the public key from an x509v3 extension with OID
`TRUSTED_WORLD_PK_OID`. The BL3-1 key certificate will use this descriptor as
`TRUSTED_WORLD_PK_OID`. The BL31 key certificate will use this descriptor as
parameter in the signature authentication method. The key is stored in the
`plat_tz_world_pk_buf` buffer.
The **BL3-1 Key certificate** is authenticated by checking its digital signature
The **BL31 Key certificate** is authenticated by checking its digital signature
using the Trusted World public key obtained previously from the Trusted Key
certificate. In the image descriptor, we specify a single authentication method
by signature whose public key is the `tz_world_pk`. Once this certificate has
been authenticated, we have to extract the BL3-1 public key, stored in the
been authenticated, we have to extract the BL31 public key, stored in the
extension specified by `bl31_content_pk`. This key will be copied to the
`plat_content_pk` buffer.
The **BL3-1 certificate** is authenticated by checking its digital signature
using the BL3-1 public key obtained previously from the BL3-1 Key certificate.
The **BL31 certificate** is authenticated by checking its digital signature
using the BL31 public key obtained previously from the BL31 Key certificate.
We specify the authentication method using `bl31_content_pk` as public key.
After authentication, we need to extract the BL3-1 hash, stored in the extension
After authentication, we need to extract the BL31 hash, stored in the extension
specified by `bl31_hash`. This hash will be copied to the `plat_bl31_hash_buf`
buffer.
The **BL3-1 image** is authenticated by calculating its hash and matching it
with the hash obtained from the BL3-1 certificate. The image descriptor contains
The **BL31 image** is authenticated by calculating its hash and matching it
with the hash obtained from the BL31 certificate. The image descriptor contains
a single authentication method by hash. The parameters to the hash method are
the reference hash, `bl31_hash`, and the data to be hashed. In this case, it is
the whole image, so we specify `raw_data`.

338
docs/firmware-design.md
View file

@ -8,7 +8,7 @@ Contents :
3. [EL3 runtime services framework](#3--el3-runtime-services-framework)
4. [Power State Coordination Interface](#4--power-state-coordination-interface)
5. [Secure-EL1 Payloads and Dispatchers](#5--secure-el1-payloads-and-dispatchers)
6. [Crash Reporting in BL3-1](#6--crash-reporting-in-bl3-1)
6. [Crash Reporting in BL31](#6--crash-reporting-in-bl3-1)
7. [Guidelines for Reset Handlers](#7--guidelines-for-reset-handlers)
8. [CPU specific operations framework](#8--cpu-specific-operations-framework)
9. [Memory layout of BL images](#9-memory-layout-of-bl-images)
@ -56,9 +56,9 @@ into five steps (in order of execution):
* 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_
* Boot Loader stage 3-1 (BL31) _EL3 Runtime Firmware_
* Boot Loader stage 3-2 (BL32) _Secure-EL1 Payload_ (optional)
* Boot Loader stage 3-3 (BL33) _Non-trusted Firmware_
ARM development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a
combination of the following types of memory regions. Each bootloader stage uses
@ -76,10 +76,10 @@ one or more of these memory regions.
The sections below provide the following details:
* initialization and execution of the first three stages during cold boot
* specification of the BL3-1 entrypoint requirements for use by alternative
* specification of the BL31 entrypoint requirements for use by alternative
Trusted Boot Firmware in place of the provided BL1 and BL2
* changes in BL3-1 behavior when using the `RESET_TO_BL31` option which
allows BL3-1 to run without BL1 and BL2
* changes in BL31 behavior when using the `RESET_TO_BL31` option which
allows BL31 to run without BL1 and BL2
### BL1
@ -150,7 +150,7 @@ BL1 performs minimal architectural initialization as follows.
For the latter, BL1 installs a simple stub. The stub expects to receive
only a single type of SMC (determined by its function ID in the general
purpose register `X0`). This SMC is raised by BL2 to make BL1 pass control
to BL3-1 (loaded by BL2) at EL3. Any other SMC leads to an assertion
to BL31 (loaded by BL2) at EL3. Any other SMC leads to an assertion
failure.
* CPU initialization
@ -240,9 +240,9 @@ bits.
BL2 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 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.
to determine whether there is enough space to load the BL33 image. A platform
defined base address is used to specify the load address for the BL31 image.
It also defines the extents of memory available for use by the BL32 image.
BL2 also initializes a UART (PL011 console), which enables access to the
`printf` family of functions in BL2. Platform security is initialized to allow
access to controlled components. The storage abstraction layer is initialized
@ -259,85 +259,85 @@ using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM
memory. The SCP executes SCP_BL2 and signals to the Application Processor (AP)
for BL2 execution to continue.
#### BL3-1 (EL3 Runtime Firmware) image load
#### BL31 (EL3 Runtime Firmware) image load
BL2 loads the BL3-1 image from platform storage into a platform-specific address
BL2 loads the BL31 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.
missing it leads to an assertion failure. If the BL31 image loads successfully,
BL2 updates the amount of trusted SRAM used and available for use by BL31.
This information is populated at a platform-specific memory address.
#### BL3-2 (Secure-EL1 Payload) image load
#### BL32 (Secure-EL1 Payload) image load
BL2 loads the optional BL3-2 image from platform storage into a platform-
BL2 loads the optional BL32 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
relies on BL31 to pass control to the BL32 image, if present. Hence, BL2
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.
of the BL32 image. The value of the Saved Processor Status Register (`SPSR`)
for entry into BL32 is not determined by BL2, it is initialized by the
Secure-EL1 Payload Dispatcher (see later) within BL31, which is responsible for
managing interaction with BL32. This information is passed to BL31.
#### BL3-3 (Non-trusted Firmware) image load
#### BL33 (Non-trusted Firmware) image load
BL2 loads the BL3-3 image (e.g. UEFI or other test or boot software) from
BL2 loads the BL33 image (e.g. UEFI or other test or boot software) from
platform storage into non-secure memory as defined by the platform.
BL2 relies on BL3-1 to pass control to BL3-3 once secure state initialization is
BL2 relies on BL31 to pass control to BL33 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
software image. The entrypoint is the load address of the BL33 image. The
`SPSR` is determined as specified in Section 5.13 of the [PSCI PDD] [PSCI]. This
information is passed to BL3-1.
information is passed to BL31.
#### BL3-1 (EL3 Runtime Firmware) execution
#### BL31 (EL3 Runtime Firmware) execution
BL2 execution continues as follows:
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
BL31 entrypoint. The exception is handled by the SMC exception handler
installed by BL1.
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.
3. BL1 passes control to BL3-1 at the specified entrypoint at EL3.
3. BL1 passes control to BL31 at the specified entrypoint at EL3.
### BL3-1
### BL31
The image for this stage is loaded by BL2 and BL1 passes control to BL3-1 at
EL3. BL3-1 executes solely in trusted SRAM. BL3-1 is linked against and
The image for this stage is loaded by BL2 and BL1 passes control to BL31 at
EL3. BL31 executes solely in trusted SRAM. BL31 is linked against and
loaded at a platform-specific base address (more information can be found later
in this document). The functionality implemented by BL3-1 is as follows.
in this document). The functionality implemented by BL31 is as follows.
#### Architectural initialization
Currently, BL3-1 performs a similar architectural initialization to BL1 as
Currently, BL31 performs a similar architectural initialization to BL1 as
far as system register settings are concerned. Since BL1 code resides in ROM,
architectural initialization in BL3-1 allows override of any previous
initialization done by BL1. BL3-1 creates page tables to address the first
architectural initialization in BL31 allows override of any previous
initialization done by BL1. BL31 creates page tables to address the first
4GB of physical address space and initializes the MMU accordingly. It initializes
a buffer of frequently used pointers, called per-CPU pointer cache, in memory for
faster access. Currently the per-CPU pointer cache contains only the pointer
to crash stack. It then replaces the exception vectors populated by BL1 with its
own. BL3-1 exception vectors implement more elaborate support for
own. BL31 exception vectors implement more elaborate support for
handling SMCs since this is the only mechanism to access the runtime services
implemented by BL3-1 (PSCI for example). BL3-1 checks each SMC for validity as
implemented by BL31 (PSCI for example). BL31 checks each SMC for validity as
specified by the [SMC calling convention PDD][SMCCC] before passing control to
the required SMC handler routine. BL3-1 programs the `CNTFRQ_EL0` register with
the required SMC handler routine. BL31 programs the `CNTFRQ_EL0` register with
the clock frequency of the system counter, which is provided by the platform.
#### Platform initialization
BL3-1 performs detailed platform initialization, which enables normal world
BL31 performs detailed platform initialization, which enables normal world
software to function correctly. It also retrieves entrypoint information for
the BL3-3 image loaded by BL2 from the platform defined memory address populated
the BL33 image loaded by BL2 from the platform defined memory address populated
by BL2. It enables issuing of snoop and DVM (Distributed Virtual Memory)
requests to the CCI slave interface corresponding to the cluster that includes
the primary CPU. BL3-1 also initializes a UART (PL011 console), which enables
access to the `printf` family of functions in BL3-1. It enables the system
the primary CPU. BL31 also initializes a UART (PL011 console), which enables
access to the `printf` family of functions in BL31. It enables the system
level implementation of the generic timer through the memory mapped interface.
* GICv2 initialization:
@ -356,21 +356,21 @@ level implementation of the generic timer through the memory mapped interface.
* GICv3 initialization:
If a GICv3 implementation is available in the platform, BL3-1 initializes
If a GICv3 implementation is available in the platform, BL31 initializes
the GICv3 in GICv2 emulation mode with settings as described for GICv2
above.
* Power management initialization:
BL3-1 implements a state machine to track CPU and cluster state. The state
BL31 implements a state machine to track CPU and cluster state. The state
can be one of `OFF`, `ON_PENDING`, `SUSPEND` or `ON`. All secondary CPUs are
initially in the `OFF` state. The cluster that the primary CPU belongs to is
`ON`; any other cluster is `OFF`. BL3-1 initializes the data structures that
implement the state machine, including the locks that protect them. BL3-1
`ON`; any other cluster is `OFF`. BL31 initializes the data structures that
implement the state machine, including the locks that protect them. BL31
accesses the state of a CPU or cluster immediately after reset and before
the data cache is enabled in the warm boot path. It is not currently
possible to use 'exclusive' based spinlocks, therefore BL3-1 uses locks
based on Lamport's Bakery algorithm instead. BL3-1 allocates these locks in
possible to use 'exclusive' based spinlocks, therefore BL31 uses locks
based on Lamport's Bakery algorithm instead. BL31 allocates these locks in
device memory by default.
* Runtime services initialization:
@ -381,34 +381,34 @@ level implementation of the generic timer through the memory mapped interface.
Details about the PSCI service are provided in the "Power State Coordination
Interface" section below.
* BL3-2 (Secure-EL1 Payload) image initialization
* BL32 (Secure-EL1 Payload) image initialization
If a BL3-2 image is present then there must be a matching Secure-EL1 Payload
If a BL32 image is present then there must be a matching Secure-EL1 Payload
Dispatcher (SPD) service (see later for details). During initialization
that service must register a function to carry out initialization of BL3-2
once the runtime services are fully initialized. BL3-1 invokes such a
registered function to initialize BL3-2 before running BL3-3.
that service must register a function to carry out initialization of BL32
once the runtime services are fully initialized. BL31 invokes such a
registered function to initialize BL32 before running BL33.
Details on BL3-2 initialization and the SPD's role are described in the
Details on BL32 initialization and the SPD's role are described in the
"Secure-EL1 Payloads and Dispatchers" section below.
* BL3-3 (Non-trusted Firmware) execution
* BL33 (Non-trusted Firmware) execution
BL3-1 initializes the EL2 or EL1 processor context for normal-world cold
BL31 initializes the EL2 or EL1 processor context for normal-world cold
boot, ensuring that no secure state information finds its way into the
non-secure execution state. BL3-1 uses the entrypoint information provided
by BL2 to jump to the Non-trusted firmware image (BL3-3) at the highest
non-secure execution state. BL31 uses the entrypoint information provided
by BL2 to jump to the Non-trusted firmware image (BL33) at the highest
available Exception Level (EL2 if available, otherwise EL1).
### Using alternative Trusted Boot Firmware in place of BL1 and BL2
Some platforms have existing implementations of Trusted Boot Firmware that
would like to use ARM Trusted Firmware BL3-1 for the EL3 Runtime Firmware. To
would like to use ARM Trusted Firmware BL31 for the EL3 Runtime Firmware. To
enable this firmware architecture it is important to provide a fully documented
and stable interface between the Trusted Boot Firmware and BL3-1.
and stable interface between the Trusted Boot Firmware and BL31.
Future changes to the BL3-1 interface will be done in a backwards compatible
Future changes to the BL31 interface will be done in a backwards compatible
way, and this enables these firmware components to be independently enhanced/
updated to develop and exploit new functionality.
@ -425,58 +425,58 @@ EL3, little-endian data access, and all interrupt sources masked:
SCTLR_EL3.EE = 0
X0 and X1 can be used to pass information from the Trusted Boot Firmware to the
platform code in BL3-1:
platform code in BL31:
X0 : Reserved for common Trusted Firmware information
X1 : Platform specific information
BL3-1 zero-init sections (e.g. `.bss`) should not contain valid data on entry,
BL31 zero-init sections (e.g. `.bss`) should not contain valid data on entry,
these will be zero filled prior to invoking platform setup code.
##### Use of the X0 and X1 parameters
The parameters are platform specific and passed from `bl31_entrypoint()` to
`bl31_early_platform_setup()`. The value of these parameters is never directly
used by the common BL3-1 code.
used by the common BL31 code.
The convention is that `X0` conveys information regarding the BL3-1, BL3-2 and
BL3-3 images from the Trusted Boot firmware and `X1` can be used for other
The convention is that `X0` conveys information regarding the BL31, BL32 and
BL33 images from the Trusted Boot firmware and `X1` can be used for other
platform specific purpose. This convention allows platforms which use ARM
Trusted Firmware's BL1 and BL2 images to transfer additional platform specific
information from Secure Boot without conflicting with future evolution of the
Trusted Firmware using `X0` to pass a `bl31_params` structure.
BL3-1 common and SPD initialization code depends on image and entrypoint
information about BL3-3 and BL3-2, which is provided via BL3-1 platform APIs.
This information is required until the start of execution of BL3-3. This
BL31 common and SPD initialization code depends on image and entrypoint
information about BL33 and BL32, which is provided via BL31 platform APIs.
This information is required until the start of execution of BL33. This
information can be provided in a platform defined manner, e.g. compiled into
the platform code in BL3-1, or provided in a platform defined memory location
the platform code in BL31, or provided in a platform defined memory location
by the Trusted Boot firmware, or passed from the Trusted Boot Firmware via the
Cold boot Initialization parameters. This data may need to be cleaned out of
the CPU caches if it is provided by an earlier boot stage and then accessed by
BL3-1 platform code before the caches are enabled.
BL31 platform code before the caches are enabled.
ARM Trusted Firmware's BL2 implementation passes a `bl31_params` structure in
`X0` and the ARM development platforms interpret this in the BL3-1 platform
`X0` and the ARM development platforms interpret this in the BL31 platform
code.
##### MMU, Data caches & Coherency
BL3-1 does not depend on the enabled state of the MMU, data caches or
BL31 does not depend on the enabled state of the MMU, data caches or
interconnect coherency on entry to `bl31_entrypoint()`. If these are disabled
on entry, these should be enabled during `bl31_plat_arch_setup()`.
##### Data structures used in the BL3-1 cold boot interface
##### Data structures used in the BL31 cold boot interface
These structures are designed to support compatibility and independent
evolution of the structures and the firmware images. For example, a version of
BL3-1 that can interpret the BL3-x image information from different versions of
BL31 that can interpret the BL3x image information from different versions of
BL2, a platform that uses an extended entry_point_info structure to convey
additional register information to BL3-1, or a ELF image loader that can convey
additional register information to BL31, or a ELF image loader that can convey
more details about the firmware images.
To support these scenarios the structures are versioned and sized, which enables
BL3-1 to detect which information is present and respond appropriately. The
BL31 to detect which information is present and respond appropriately. The
`param_header` is defined to capture this information:
typedef struct param_header {
@ -491,7 +491,7 @@ The structures using this format are `entry_point_info`, `image_info` and
the header fields appropriately, and the `SET_PARAM_HEAD()` a macro is defined
to simplify this action.
#### Required CPU state for BL3-1 Warm boot initialization
#### Required CPU state for BL31 Warm boot initialization
When requesting a CPU power-on, or suspending a running CPU, ARM Trusted
Firmware provides the platform power management code with a Warm boot
@ -510,49 +510,49 @@ platform power management code is then invoked as required to initialize all
necessary system, cluster and CPU resources.
### Using BL3-1 as the CPU reset vector
### Using BL31 as the CPU reset vector
On some platforms the runtime firmware (BL3-x images) for the application
On some platforms the runtime firmware (BL3x images) for the application
processors are loaded by trusted firmware running on a secure system processor
on the SoC, rather than by BL1 and BL2 running on the primary application
processor. For this type of SoC it is desirable for the application processor
to always reset to BL3-1 which eliminates the need for BL1 and BL2.
to always reset to BL31 which eliminates the need for BL1 and BL2.
ARM Trusted Firmware provides a build-time option `RESET_TO_BL31` that includes
some additional logic in the BL3-1 entrypoint to support this use case.
some additional logic in the BL31 entrypoint to support this use case.
In this configuration, the platform's Trusted Boot Firmware must ensure that
BL3-1 is loaded to its runtime address, which must match the CPU's RVBAR reset
BL31 is loaded to its runtime address, which must match the CPU's RVBAR reset
vector address, before the application processor is powered on. Additionally,
platform software is responsible for loading the other BL3-x images required and
providing entry point information for them to BL3-1. Loading these images might
be done by the Trusted Boot Firmware or by platform code in BL3-1.
platform software is responsible for loading the other BL3x images required and
providing entry point information for them to BL31. Loading these images might
be done by the Trusted Boot Firmware or by platform code in BL31.
The ARM FVP port supports the `RESET_TO_BL31` configuration, in which case the
`bl31.bin` image must be loaded to its run address in Trusted SRAM and all CPU
reset vectors be changed from the default `0x0` to this run address. See the
[User Guide] for details of running the FVP models in this way.
This configuration requires some additions and changes in the BL3-1
This configuration requires some additions and changes in the BL31
functionality:
#### Determination of boot path
In this configuration, BL3-1 uses the same reset framework and code as the one
In this configuration, BL31 uses the same reset framework and code as the one
described for BL1 above. On a warm boot a CPU is directed to the PSCI
implementation via a platform defined mechanism. On a cold boot, the platform
must place any secondary CPUs into a safe state while the primary CPU executes
a modified BL3-1 initialization, as described below.
a modified BL31 initialization, as described below.
#### Platform initialization
In this configuration, when the CPU resets to BL3-1 there are no parameters
In this configuration, when the CPU resets to BL31 there are no parameters
that can be passed in registers by previous boot stages. Instead, the platform
code in BL3-1 needs to know, or be able to determine, the location of the BL3-2
(if required) and BL3-3 images and provide this information in response to the
code in BL31 needs to know, or be able to determine, the location of the BL32
(if required) and BL33 images and provide this information in response to the
`bl31_plat_get_next_image_ep_info()` function.
As the first image to execute in this configuration BL3-1 must also ensure that
As the first image to execute in this configuration BL31 must also ensure that
any security initialisation, for example programming a TrustZone address space
controller, is carried out during early platform initialisation.
@ -571,7 +571,7 @@ The EL3 runtime services framework enables the development of services by
different providers that can be easily integrated into final product firmware.
The following sections describe the framework which facilitates the
registration, initialization and use of runtime services in EL3 Runtime
Firmware (BL3-1).
Firmware (BL31).
The design of the runtime services depends heavily on the concepts and
definitions described in the [SMCCC], in particular SMC Function IDs, Owning
@ -628,7 +628,7 @@ the name of the service, the range of OENs covered, the type of service and
initialization and call handler functions. This macro instantiates a `const
struct rt_svc_desc` for the service with these details (see `runtime_svc.h`).
This structure is allocated in a special ELF section `rt_svc_descs`, enabling
the framework to find all service descriptors included into BL3-1.
the framework to find all service descriptors included into BL31.
The specific service for a SMC Function is selected based on the OEN and call
type of the Function ID, and the framework uses that information in the service
@ -650,14 +650,14 @@ call handling functions are provided in the following sections.
### Initialization
`runtime_svc_init()` in `runtime_svc.c` initializes the runtime services
framework running on the primary CPU during cold boot as part of the BL3-1
framework running on the primary CPU during cold boot as part of the BL31
initialization. This happens prior to initializing a Trusted OS and running
Normal world boot firmware that might in turn use these services.
Initialization involves validating each of the declared runtime service
descriptors, calling the service initialization function and populating the
index used for runtime lookup of the service.
The BL3-1 linker script collects all of the declared service descriptors into a
The BL31 linker script collects all of the declared service descriptors into a
single array and defines symbols that allow the framework to locate and traverse
the array, and determine its size.
@ -771,22 +771,22 @@ hooks to be registered with the generic PSCI code to be supported.
---------------------------------------
On a production system that includes a Trusted OS running in Secure-EL1/EL0,
the Trusted OS is coupled with a companion runtime service in the BL3-1
the Trusted OS is coupled with a companion runtime service in the BL31
firmware. This service is responsible for the initialisation of the Trusted
OS and all communications with it. The Trusted OS is the BL3-2 stage of the
OS and all communications with it. The Trusted OS is the BL32 stage of the
boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load
and execute a BL3-2 image.
and execute a BL32 image.
ARM Trusted Firmware uses a more general term for the BL3-2 software that runs
ARM Trusted Firmware uses a more general term for the BL32 software that runs
at Secure-EL1 - the _Secure-EL1 Payload_ - as it is not always a Trusted OS.
The ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and a Test
Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS
is supported on a production system using the Runtime Services Framework. On
such a system, the Test BL3-2 image and service are replaced by the Trusted OS
such a system, the Test BL32 image and service are replaced by the Trusted OS
and its dispatcher service. The ARM Trusted Firmware build system expects that
the dispatcher will define the build flag `NEED_BL32` to enable it to include
the BL3-2 in the build either as a binary or to compile from source depending
the BL32 in the build either as a binary or to compile from source depending
on whether the `BL32` build option is specified or not.
The TSP runs in Secure-EL1. It is designed to demonstrate synchronous
@ -806,69 +806,69 @@ The TSPD service is responsible for.
* Routing requests and responses between the secure and the non-secure
states during the two types of communications just described
### Initializing a BL3-2 Image
### Initializing a BL32 Image
The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing
the BL3-2 image. It needs access to the information passed by BL2 to BL3-1 to do
the BL32 image. It needs access to the information passed by BL2 to BL31 to do
so. This is provided by:
entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t);
which returns a reference to the `entry_point_info` structure corresponding to
the image which will be run in the specified security state. The SPD uses this
API to get entry point information for the SECURE image, BL3-2.
API to get entry point information for the SECURE image, BL32.
In the absence of a BL3-2 image, BL3-1 passes control to the normal world
bootloader image (BL3-3). When the BL3-2 image is present, it is typical
that the SPD wants control to be passed to BL3-2 first and then later to BL3-3.
In the absence of a BL32 image, BL31 passes control to the normal world
bootloader image (BL33). When the BL32 image is present, it is typical
that the SPD wants control to be passed to BL32 first and then later to BL33.
To do this the SPD has to register a BL3-2 initialization function during
initialization of the SPD service. The BL3-2 initialization function has this
To do this the SPD has to register a BL32 initialization function during
initialization of the SPD service. The BL32 initialization function has this
prototype:
int32_t init();
and is registered using the `bl31_register_bl32_init()` function.
Trusted Firmware supports two approaches for the SPD to pass control to BL3-2
before returning through EL3 and running the non-trusted firmware (BL3-3):
Trusted Firmware supports two approaches for the SPD to pass control to BL32
before returning through EL3 and running the non-trusted firmware (BL33):
1. In the BL3-2 setup function, use `bl31_set_next_image_type()` to
request that the exit from `bl31_main()` is to the BL3-2 entrypoint in
Secure-EL1. BL3-1 will exit to BL3-2 using the asynchronous method by
1. In the BL32 setup function, use `bl31_set_next_image_type()` to
request that the exit from `bl31_main()` is to the BL32 entrypoint in
Secure-EL1. BL31 will exit to BL32 using the asynchronous method by
calling bl31_prepare_next_image_entry() and el3_exit().
When the BL3-2 has completed initialization at Secure-EL1, it returns to
BL3-1 by issuing an SMC, using a Function ID allocated to the SPD. On
When the BL32 has completed initialization at Secure-EL1, it returns to
BL31 by issuing an SMC, using a Function ID allocated to the SPD. On
receipt of this SMC, the SPD service handler should switch the CPU context
from trusted to normal world and use the `bl31_set_next_image_type()` and
`bl31_prepare_next_image_entry()` functions to set up the initial return to
the normal world firmware BL3-3. On return from the handler the framework
will exit to EL2 and run BL3-3.
the normal world firmware BL33. On return from the handler the framework
will exit to EL2 and run BL33.
2. The BL3-2 setup function registers a initialization function using
2. The BL32 setup function registers a initialization function using
`bl31_register_bl32_init()` which provides a SPD-defined mechanism to
invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL3-2
invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
entrypoint.
NOTE: The Test SPD service included with the Trusted Firmware provides one
implementation of such a mechanism.
On completion BL3-2 returns control to BL3-1 via a SMC, and on receipt the
On completion BL32 returns control to BL31 via a SMC, and on receipt the
SPD service handler invokes the synchronous call return mechanism to return
to the BL3-2 initialization function. On return from this function,
`bl31_main()` will set up the return to the normal world firmware BL3-3 and
to the BL32 initialization function. On return from this function,
`bl31_main()` will set up the return to the normal world firmware BL33 and
continue the boot process in the normal world.
6. Crash Reporting in BL3-1
6. Crash Reporting in BL31
----------------------------
BL3-1 implements a scheme for reporting the processor state when an unhandled
BL31 implements a scheme for reporting the processor state when an unhandled
exception is encountered. The reporting mechanism attempts to preserve all the
register contents and report it via a dedicated UART (PL011 console). BL3-1
register contents and report it via a dedicated UART (PL011 console). BL31
reports the general purpose, EL3, Secure EL1 and some EL2 state registers.
A dedicated per-CPU crash stack is maintained by BL3-1 and this is retrieved via
A dedicated per-CPU crash stack is maintained by BL31 and this is retrieved via
the per-CPU pointer cache. The implementation attempts to minimise the memory
required for this feature. The file `crash_reporting.S` contains the
implementation for crash reporting.
@ -960,7 +960,7 @@ The sample crash output is shown below.
Trusted Firmware implements a framework that allows CPU and platform ports to
perform actions very early after a CPU is released from reset in both the cold
and warm boot paths. This is done by calling the `reset_handler()` function in
both the BL1 and BL3-1 images. It in turn calls the platform and CPU specific
both the BL1 and BL31 images. It in turn calls the platform and CPU specific
reset handling functions.
Details for implementing a CPU specific reset handler can be found in
@ -1045,7 +1045,7 @@ regarding placement of code in a reset handler.
### CPU specific power down sequence
During the BL3-1 initialization sequence, the pointer to the matching `cpu_ops`
During the BL31 initialization sequence, the pointer to the matching `cpu_ops`
entry is stored in per-CPU data by `init_cpu_ops()` so that it can be quickly
retrieved during power down sequences.
@ -1065,7 +1065,7 @@ turning off CCI coherency during a cluster power down.
### CPU specific register reporting during crash
If the crash reporting is enabled in BL3-1, when a crash occurs, the crash
If the crash reporting is enabled in BL31, when a crash occurs, the crash
reporting framework calls `do_cpu_reg_dump` which retrieves the matching
`cpu_ops` using `get_cpu_ops_ptr()` function. The `cpu_reg_dump()` in
`cpu_ops` is invoked, which then returns the CPU specific register values to
@ -1182,9 +1182,9 @@ for this purpose:
* `__BL1_RAM_START__` This is the start address of BL1 RW data.
* `__BL1_RAM_END__` This is the end address of BL1 RW data.
#### BL2's, BL3-1's and TSP's linker symbols
#### BL2's, BL31's and TSP's linker symbols
BL2, BL3-1 and TSP need to know the extents of their read-only section to set
BL2, BL31 and TSP need to know the extents of their read-only section to set
the right memory attributes for this memory region in their MMU setup code. The
following linker symbols are defined for this purpose:
@ -1221,7 +1221,7 @@ happens, the linker will issue a message similar to the following:
aarch64-none-elf-ld: BLx has exceeded its limit.
Additionally, if the platform memory layout implies some image overlaying like
on FVP, BL3-1 and TSP need to know the limit address that their PROGBITS
on FVP, BL31 and TSP need to know the limit address that their PROGBITS
sections must not overstep. The platform code must provide those.
@ -1242,45 +1242,45 @@ The following list describes the memory layout on the ARM development platforms:
Juno, BL1 resides in flash memory at address `0x0BEC0000`. BL1 read-write
data are relocated to the top of Trusted SRAM at runtime.
* BL3-1 is loaded at the top of the Trusted SRAM, such that its NOBITS
* BL31 is loaded at the top of the Trusted SRAM, such that its NOBITS
sections will overwrite BL1 R/W data. This implies that BL1 global variables
remain valid only until execution reaches the BL3-1 entry point during
remain valid only until execution reaches the BL31 entry point during
a cold boot.
* BL2 is loaded below BL3-1.
* BL2 is loaded below BL31.
* On Juno, SCP_BL2 is loaded temporarily into the BL3-1 memory region and
transfered to the SCP before being overwritten by BL3-1.
* On Juno, SCP_BL2 is loaded temporarily into the BL31 memory region and
transfered to the SCP before being overwritten by BL31.
* BL3-2 can be loaded in one of the following locations:
* BL32 can be loaded in one of the following locations:
* Trusted SRAM
* Trusted DRAM (FVP only)
* Secure region of DRAM (top 16MB of DRAM configured by the TrustZone
controller)
When BL3-2 is loaded into Trusted SRAM, its NOBITS sections are allowed to
overlay BL2. This memory layout is designed to give the BL3-2 image as much
When BL32 is loaded into Trusted SRAM, its NOBITS sections are allowed to
overlay BL2. This memory layout is designed to give the BL32 image as much
memory as possible when it is loaded into Trusted SRAM.
The location of the BL3-2 image will result in different memory maps. This is
The location of the BL32 image will result in different memory maps. This is
illustrated for both FVP and Juno in the following diagrams, using the TSP as
an example.
Note: Loading the BL3-2 image in TZC secured DRAM doesn't change the memory
Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory
layout of the other images in Trusted SRAM.
**FVP with TSP in Trusted SRAM (default option):**
Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
| BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-1 PROGBITS |
| | <<<<<<<<<<<<< | BL31 PROGBITS |
|----------| ------------------
| BL2 | <<<<<<<<<<<<< | BL3-2 NOBITS |
| BL2 | <<<<<<<<<<<<< | BL32 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-2 PROGBITS |
| | <<<<<<<<<<<<< | BL32 PROGBITS |
0x04001000 +----------+ ------------------
| Shared |
0x04000000 +----------+
@ -1295,14 +1295,14 @@ layout of the other images in Trusted SRAM.
Trusted DRAM
0x08000000 +----------+
| BL3-2 |
| BL32 |
0x06000000 +----------+
Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
| BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-1 PROGBITS |
| | <<<<<<<<<<<<< | BL31 PROGBITS |
|----------| ------------------
| BL2 |
|----------|
@ -1320,7 +1320,7 @@ layout of the other images in Trusted SRAM.
DRAM
0xffffffff +----------+
| BL3-2 | (secure)
| BL32 | (secure)
0xff000000 +----------+
| |
: : (non-secure)
@ -1329,9 +1329,9 @@ layout of the other images in Trusted SRAM.
Trusted SRAM
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
| BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-1 PROGBITS |
| | <<<<<<<<<<<<< | BL31 PROGBITS |
|----------| ------------------
| BL2 |
|----------|
@ -1346,7 +1346,7 @@ layout of the other images in Trusted SRAM.
0x00000000 +----------+
**Juno with BL3-2 in Trusted SRAM (default option):**
**Juno with BL32 in Trusted SRAM (default option):**
Flash0
0x0C000000 +----------+
@ -1355,27 +1355,27 @@ layout of the other images in Trusted SRAM.
| BL1 (ro) |
0x0BEC0000 |----------|
: :
0x08000000 +----------+ BL3-1 is loaded
0x08000000 +----------+ BL31 is loaded
after SCP_BL2 has
Trusted SRAM been sent to SCP
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
| BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| SCP_BL2 | <<<<<<<<<<<<< | BL3-1 PROGBITS |
| SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS |
|----------| ------------------
| BL2 | <<<<<<<<<<<<< | BL3-2 NOBITS |
| BL2 | <<<<<<<<<<<<< | BL32 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| | <<<<<<<<<<<<< | BL3-2 PROGBITS |
| | <<<<<<<<<<<<< | BL32 PROGBITS |
0x04001000 +----------+ ------------------
| MHU |
0x04000000 +----------+
**Juno with BL3-2 in TZC-secured DRAM:**
**Juno with BL32 in TZC-secured DRAM:**
DRAM
0xFFE00000 +----------+
| BL3-2 | (secure)
| BL32 | (secure)
0xFF000000 |----------|
| |
: : (non-secure)
@ -1389,13 +1389,13 @@ layout of the other images in Trusted SRAM.
| BL1 (ro) |
0x0BEC0000 |----------|
: :
0x08000000 +----------+ BL3-1 is loaded
0x08000000 +----------+ BL31 is loaded
after SCP_BL2 has
Trusted SRAM been sent to SCP
0x04040000 +----------+ loaded by BL2 ------------------
| BL1 (rw) | <<<<<<<<<<<<< | BL3-1 NOBITS |
| BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
|----------| <<<<<<<<<<<<< |----------------|
| SCP_BL2 | <<<<<<<<<<<<< | BL3-1 PROGBITS |
| SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS |
|----------| ------------------
| BL2 |
|----------|
@ -1722,7 +1722,7 @@ following categories (present as directories in the source code):
Each boot loader stage uses code from one or more of the above mentioned
categories. Based upon the above, the code layout looks like this:
Directory Used by BL1? Used by BL2? Used by BL3-1?
Directory Used by BL1? Used by BL2? Used by BL31?
bl1 Yes No No
bl2 No Yes No
bl31 No No Yes

6
docs/platform-migration-guide.md
View file

@ -314,7 +314,7 @@ This function is called with the `SCTLR.M` and `SCTLR.C` bits disabled. The core
is identified by its `MPIDR`, which is passed as the argument. The function is
responsible for distinguishing between a warm and cold reset using platform-
specific means. If it is a warm reset, it returns the entrypoint into the
BL3-1 image that the core must jump to. If it is a cold reset, this function
BL31 image that the core must jump to. If it is a cold reset, this function
must return zero.
This function is also responsible for implementing a platform-specific mechanism
@ -387,7 +387,7 @@ provided in [plat/common/aarch64/platform_up_stack.S] and
[plat/common/aarch64/platform_mp_stack.S]
## Modifications for Power State Coordination Interface (in BL3-1)
## Modifications for Power State Coordination Interface (in BL31)
The following functions must be implemented to initialize PSCI functionality in
the ARM Trusted Firmware.
@ -448,7 +448,7 @@ called by the primary core.
This function is called by PSCI initialization code. Its purpose is to export
handler routines for platform-specific power management actions by populating
the passed pointer with a pointer to the private `plat_pm_ops` structure of
BL3-1.
BL31.
A description of each member of this structure is given below. A platform port
is expected to implement these handlers if the corresponding PSCI operation

186
docs/porting-guide.md
View file

@ -13,10 +13,10 @@ Contents
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 @@ platform port to define additional platform porting constants in
* **#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 @@ mandatory:
* **#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 @@ also be defined:
* **#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 @@ also be defined:
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 @@ platform, the following constants must also be defined:
* **#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 @@ must also be defined:
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 @@ memory layout implies some image overlaying like in ARM standard platforms.
* **#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 @@ found in `plat/arm/board/<plat_name>/include/plat_macros.S`.
* **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 @@ found in `plat/arm/board/<plat_name>/include/plat_macros.S`.
------------------
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 @@ For each CPU, the reset vector code is responsible for the following tasks:
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 @@ This function is called with the called with the MMU and caches disabled
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 @@ PSCI and details of this can be found in [Power Domain Topology Design].
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 @@ using the `platform_is_primary_cpu()` function. BL1 passed control to BL2 at
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 @@ This function returns 0 on success, a negative error code otherwise.
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 @@ necessary content, or maintain the structures until BL3-3 is initialised.
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 @@ structure in BL2 memory.
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 @@ image. It receives a null pointer as its first argument in this case.
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 @@ and SPSR which represents the entry point system state for BL3-2.
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 @@ and SPSR which represents the entry point system state for BL3-3.
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 @@ memory from the given base.
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 @@ memory from the given base.
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 @@ later Bootloader stages with MMU off
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 @@ by the primary CPU. The arguments to this function are:
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 @@ port does the necessary initialization in `bl31_plat_arch_setup()`. It is only
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 @@ This function may execute with the MMU and data caches enabled if the platform
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 @@ modes table.
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 @@ of CPUs (for example, a cluster), and level 2 is a group of clusters
(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 @@ of the requested local power state values.
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 @@ This function is called by PSCI initialization code. Its purpose is to let
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 @@ domain level specific local states to suspend to system affinity level. The
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 @@ Group Register_ (`GICD_IGROUPRn`). It uses the group value to determine the
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 @@ build system.
* **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

8
docs/rt-svc-writers-guide.md
View file

@ -19,7 +19,7 @@ Contents
----------------
This document describes how to add a runtime service to the EL3 Runtime
Firmware component of ARM Trusted Firmware (BL3-1).
Firmware component of ARM Trusted Firmware (BL31).
Software executing in the normal world and in the trusted world at exception
levels lower than EL3 will request runtime services using the Secure Monitor
@ -30,9 +30,9 @@ results are returned.
SMC Functions are grouped together based on the implementor of the service, for
example a subset of the Function IDs are designated as "OEM Calls" (see [SMCCC]
for full details). The EL3 runtime services framework in BL3-1 enables the
for full details). The EL3 runtime services framework in BL31 enables the
independent implementation of services for each group, which are then compiled
into the BL3-1 image. This simplifies the integration of common software from
into the BL31 image. This simplifies the integration of common software from
ARM to support [PSCI], Secure Monitor for a Trusted OS and SoC specific
software. The common runtime services framework ensures that SMC Functions are
dispatched to their respective service implementation - the [Firmware Design]
@ -290,7 +290,7 @@ between the normal and secure worlds, deliver SMC Calls through to Secure-EL1
and generally manage the Secure-EL1 Payload through CPU power-state transitions.
TODO: Provide details of the additional work required to implement a SPD and
the BL3-1 support for these services. Or a reference to the document that will
the BL31 support for these services. Or a reference to the document that will
provide this information....

64
docs/trusted-board-boot.md
View file

@ -66,18 +66,18 @@ The keys used to establish the CoT are:
* **Trusted world key**
The private part is used to sign the key certificates corresponding to the
secure world images (SCP_BL2, BL3-1 and BL3-2). The public part is stored in
secure world images (SCP_BL2, BL31 and BL32). The public part is stored in
one of the extension fields in the trusted world certificate.
* **Non-trusted world key**
The private part is used to sign the key certificate corresponding to the
non secure world image (BL3-3). The public part is stored in one of the
non secure world image (BL33). The public part is stored in one of the
extension fields in the trusted world certificate.
* **BL3-X keys**
For each of SCP_BL2, BL3-1, BL3-2 and BL3-3, the private part is used to
For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to
sign the content certificate for the BL3-X image. The public part is stored
in one of the extension fields in the corresponding key certificate.
@ -86,9 +86,9 @@ The following images are included in the CoT:
* BL1
* BL2
* SCP_BL2 (optional)
* BL3-1
* BL3-3
* BL3-2 (optional)
* BL31
* BL33
* BL32 (optional)
The following certificates are used to authenticate the images.
@ -113,35 +113,35 @@ The following certificates are used to authenticate the images.
It is self-signed with the SCP_BL2 key. It contains a hash of the SCP_BL2
image.
* **BL3-1 key certificate**
* **BL31 key certificate**
It is self-signed with the trusted world key. It contains the public part of
the BL3-1 key.
the BL31 key.
* **BL3-1 content certificate**
* **BL31 content certificate**
It is self-signed with the BL3-1 key. It contains a hash of the BL3-1 image.
It is self-signed with the BL31 key. It contains a hash of the BL31 image.
* **BL3-2 key certificate**
* **BL32 key certificate**
It is self-signed with the trusted world key. It contains the public part of
the BL3-2 key.
the BL32 key.
* **BL3-2 content certificate**
* **BL32 content certificate**
It is self-signed with the BL3-2 key. It contains a hash of the BL3-2 image.
It is self-signed with the BL32 key. It contains a hash of the BL32 image.
* **BL3-3 key certificate**
* **BL33 key certificate**
It is self-signed with the non-trusted world key. It contains the public
part of the BL3-3 key.
part of the BL33 key.
* **BL3-3 content certificate**
* **BL33 content certificate**
It is self-signed with the BL3-3 key. It contains a hash of the BL3-3 image.
It is self-signed with the BL33 key. It contains a hash of the BL33 image.
The SCP_BL2 and BL3-2 certificates are optional, but they must be present if the
corresponding SCP_BL2 or BL3-2 images are present.
The SCP_BL2 and BL32 certificates are optional, but they must be present if the
corresponding SCP_BL2 or BL32 images are present.
3. Trusted Board Boot Sequence
@ -168,27 +168,27 @@ if any of the steps fail.
registers. If the comparison succeeds, BL2 reads and saves the trusted and
non-trusted world public keys from the verified certificate.
The next two steps are executed for each of the SCP_BL2, BL3-1 & BL3-2 images.
The steps for the optional SCP_BL2 and BL3-2 images are skipped if these images
The next two steps are executed for each of the SCP_BL2, BL31 & BL32 images.
The steps for the optional SCP_BL2 and BL32 images are skipped if these images
are not present.
* BL2 loads and verifies the BL3-x key certificate. The certificate signature
* BL2 loads and verifies the BL3x key certificate. The certificate signature
is verified using the trusted world public key. If the signature
verification succeeds, BL2 reads and saves the BL3-x public key from the
verification succeeds, BL2 reads and saves the BL3x public key from the
certificate.
* BL2 loads and verifies the BL3-x content certificate. The signature is
verified using the BL3-x public key. If the signature verification succeeds,
BL2 reads and saves the BL3-x image hash from the certificate.
* BL2 loads and verifies the BL3x content certificate. The signature is
verified using the BL3x public key. If the signature verification succeeds,
BL2 reads and saves the BL3x image hash from the certificate.
The next two steps are executed only for the BL3-3 image.
The next two steps are executed only for the BL33 image.
* BL2 loads and verifies the BL3-3 key certificate. If the signature
verification succeeds, BL2 reads and saves the BL3-3 public key from the
* BL2 loads and verifies the BL33 key certificate. If the signature
verification succeeds, BL2 reads and saves the BL33 public key from the
certificate.
* BL2 loads and verifies the BL3-3 content certificate. If the signature
verification succeeds, BL2 reads and saves the BL3-3 image hash from the
* BL2 loads and verifies the BL33 content certificate. If the signature
verification succeeds, BL2 reads and saves the BL33 image hash from the
certificate.
The next step is executed for all the boot loader images.

70
docs/user-guide.md
View file

@ -99,7 +99,7 @@ as part of the Linaro release.
To build the Trusted Firmware images, change to the root directory of the
Trusted Firmware source tree and follow these steps:
1. Set the compiler path, specify a Non-trusted Firmware image (BL3-3) and
1. Set the compiler path, specify a Non-trusted Firmware image (BL33) and
a valid platform, and then build:
CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- \
@ -109,11 +109,11 @@ Trusted Firmware source tree and follow these steps:
If `PLAT` is not specified, `fvp` is assumed by default. See the "Summary of
build options" for more information on available build options.
The BL3-3 image corresponds to the software that is executed after switching
to the non-secure world. UEFI can be used as the BL3-3 image. Refer to the
The BL33 image corresponds to the software that is executed after switching
to the non-secure world. UEFI can be used as the BL33 image. Refer to the
"Building the rest of the software stack" section below.
The TSP (Test Secure Payload), corresponding to the BL3-2 image, is not
The TSP (Test Secure Payload), corresponding to the BL32 image, is not
compiled in by default. Refer to the "Building the Test Secure Payload"
section below.
@ -159,10 +159,10 @@ Trusted Firmware source tree and follow these steps:
make realclean
5. (Optional) Path to binary for certain BL stages (BL2, BL3-1 and BL3-2) can be
5. (Optional) Path to binary for certain BL stages (BL2, BL31 and BL32) can be
provided by specifying the BLx=<path-to>/<blx_image> where BLx is the BL stage.
This will bypass the build of the BL component from source, but will include
the specified binary in the final FIP image. Please note that BL3-2 will be
the specified binary in the final FIP image. Please note that BL32 will be
included in the build, only if the `SPD` build option is specified.
For example, specifying BL2=<path-to>/<bl2_image> in the build option, will
@ -184,7 +184,7 @@ performed.
If a SCP_BL2 image is present then this option must be passed for the `fip`
target.
* `BL33`: Path to BL3-3 image in the host file system. This is mandatory for
* `BL33`: Path to BL33 image in the host file system. This is mandatory for
`fip` target in case the BL2 from ARM Trusted Firmware is used.
* `BL2`: This is an optional build option which specifies the path to BL2
@ -192,11 +192,11 @@ performed.
Firmware will not be built.
* `BL31`: This is an optional build option which specifies the path to
BL3-1 image for the `fip` target. In this case, the BL3-1 in the ARM
BL31 image for the `fip` target. In this case, the BL31 in the ARM
Trusted Firmware will not be built.
* `BL32`: This is an optional build option which specifies the path to
BL3-2 image for the `fip` target. In this case, the BL3-2 in the ARM
BL32 image for the `fip` target. In this case, the BL32 in the ARM
Trusted Firmware will not be built.
* `FIP_NAME`: This is an optional build option which specifies the FIP
@ -246,14 +246,14 @@ performed.
is used to determine the number of valid slave interfaces available in the
ARM CCI driver. Default is 400 (that is, CCI-400).
* `RESET_TO_BL31`: Enable BL3-1 entrypoint as the CPU reset vector instead
* `RESET_TO_BL31`: Enable BL31 entrypoint as the CPU reset vector instead
of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
entrypoint) or 1 (CPU reset to BL3-1 entrypoint).
entrypoint) or 1 (CPU reset to BL31 entrypoint).
The default value is 0.
* `CRASH_REPORTING`: A non-zero value enables a console dump of processor
register state when an unexpected exception occurs during execution of
BL3-1. This option defaults to the value of `DEBUG` - i.e. by default
BL31. This option defaults to the value of `DEBUG` - i.e. by default
this is only enabled for a debug build of the firmware.
* `ASM_ASSERTION`: This flag determines whether the assertion checks within
@ -261,10 +261,10 @@ performed.
value of `DEBUG` - that is, by default this is only enabled for a debug
build of the firmware.
* `TSP_INIT_ASYNC`: Choose BL3-2 initialization method as asynchronous or
synchronous, (see "Initializing a BL3-2 Image" section in [Firmware
Design]). It can take the value 0 (BL3-2 is initialized using
synchronous method) or 1 (BL3-2 is initialized using asynchronous method).
* `TSP_INIT_ASYNC`: Choose BL32 initialization method as asynchronous or
synchronous, (see "Initializing a BL32 Image" section in [Firmware
Design]). It can take the value 0 (BL32 is initialized using
synchronous method) or 1 (BL32 is initialized using asynchronous method).
Default is 0.
* `USE_COHERENT_MEM`: This flag determines whether to include the coherent
@ -332,15 +332,15 @@ performed.
this file name will be used to save the key.
* `BL31_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
file that contains the BL3-1 private key in PEM format. If `SAVE_KEYS=1`,
file that contains the BL31 private key in PEM format. If `SAVE_KEYS=1`,
this file name will be used to save the key.
* `BL32_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
file that contains the BL3-2 private key in PEM format. If `SAVE_KEYS=1`,
file that contains the BL32 private key in PEM format. If `SAVE_KEYS=1`,
this file name will be used to save the key.
* `BL33_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
file that contains the BL3-3 private key in PEM format. If `SAVE_KEYS=1`,
file that contains the BL33 private key in PEM format. If `SAVE_KEYS=1`,
this file name will be used to save the key.
* `PROGRAMMABLE_RESET_ADDRESS`: This option indicates whether the reset
@ -459,7 +459,7 @@ It is recommended to remove the build artifacts before rebuilding:
make -C tools/fip_create clean
Create a Firmware package that contains existing BL2 and BL3-1 images:
Create a Firmware package that contains existing BL2 and BL31 images:
# fip_create --help to print usage information
# fip_create <fip_name> <images to add> [--dump to show result]
@ -470,7 +470,7 @@ Create a Firmware package that contains existing BL2 and BL3-1 images:
---------------------------
- Trusted Boot Firmware BL2: offset=0x88, size=0x81E8
file: 'build/<platform>/debug/bl2.bin'
- EL3 Runtime Firmware BL3-1: offset=0x8270, size=0xC218
- EL3 Runtime Firmware BL31: offset=0x8270, size=0xC218
file: 'build/<platform>/debug/bl31.bin'
---------------------------
Creating "fip.bin"
@ -482,7 +482,7 @@ View the contents of an existing Firmware package:
Firmware Image Package ToC:
---------------------------
- Trusted Boot Firmware BL2: offset=0x88, size=0x81E8
- EL3 Runtime Firmware BL3-1: offset=0x8270, size=0xC218
- EL3 Runtime Firmware BL31: offset=0x8270, size=0xC218
---------------------------
Existing package entries can be individially updated:
@ -495,7 +495,7 @@ Existing package entries can be individially updated:
---------------------------
- Trusted Boot Firmware BL2: offset=0x88, size=0x7240
file: 'build/<platform>/release/bl2.bin'
- EL3 Runtime Firmware BL3-1: offset=0x72C8, size=0xC218
- EL3 Runtime Firmware BL31: offset=0x72C8, size=0xC218
---------------------------
Updating "fip.bin"
@ -550,13 +550,13 @@ commands can be used:
### Building the Test Secure Payload
The TSP is coupled with a companion runtime service in the BL3-1 firmware,
called the TSPD. Therefore, if you intend to use the TSP, the BL3-1 image
The TSP is coupled with a companion runtime service in the BL31 firmware,
called the TSPD. Therefore, if you intend to use the TSP, the BL31 image
must be recompiled as well. For more information on SPs and SPDs, see the
"Secure-EL1 Payloads and Dispatchers" section in the [Firmware Design].
First clean the Trusted Firmware build directory to get rid of any previous
BL3-1 binary. Then to build the TSP image and include it into the FIP use:
BL31 binary. Then to build the TSP image and include it into the FIP use:
CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- \
BL33=<path-to>/<bl33_image> \
@ -566,19 +566,19 @@ An additional boot loader binary file is created in the `build` directory:
* `build/<platform>/<build-type>/bl32.bin`
The FIP will now contain the additional BL3-2 image. Here is an example
output from an FVP build in release mode including BL3-2 and using
FVP_AARCH64_EFI.fd as BL3-3 image:
The FIP will now contain the additional BL32 image. Here is an example
output from an FVP build in release mode including BL32 and using
FVP_AARCH64_EFI.fd as BL33 image:
Firmware Image Package ToC:
---------------------------
- Trusted Boot Firmware BL2: offset=0xD8, size=0x6000
file: './build/fvp/release/bl2.bin'
- EL3 Runtime Firmware BL3-1: offset=0x60D8, size=0x9000
- EL3 Runtime Firmware BL31: offset=0x60D8, size=0x9000
file: './build/fvp/release/bl31.bin'
- Secure Payload BL3-2 (Trusted OS): offset=0xF0D8, size=0x3000
- Secure Payload BL32 (Trusted OS): offset=0xF0D8, size=0x3000
file: './build/fvp/release/bl32.bin'
- Non-Trusted Firmware BL3-3: offset=0x120D8, size=0x280000
- Non-Trusted Firmware BL33: offset=0x120D8, size=0x280000
file: '../FVP_AARCH64_EFI.fd'
---------------------------
Creating "build/fvp/release/fip.bin"
@ -1002,7 +1002,7 @@ boot Linux with 8 CPUs using the ARM Trusted Firmware.
--data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
### Running on the AEMv8 Base FVP with reset to BL3-1 entrypoint
### Running on the AEMv8 Base FVP with reset to BL31 entrypoint
Please read "Notes regarding Base FVP configuration options" section above for
information about some of the options to run the software.
@ -1032,7 +1032,7 @@ with 8 CPUs using the ARM Trusted Firmware.
--data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>"
### Running on the Cortex-A57-A53 Base FVP with reset to BL3-1 entrypoint
### Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
Please read "Notes regarding Base FVP configuration options" section above for
information about some of the options to run the software.
@ -1097,7 +1097,7 @@ registers memory map (`0x1c010000`).
This register can be configured as described in the following sections.
NOTE: If the legacy VE GIC memory map is used, then the corresponding FDT and
BL3-3 images should be used.
BL33 images should be used.
#### Configuring AEMv8 Foundation FVP GIC for legacy VE memory map

10
include/common/bl_common.h
View file

@ -245,14 +245,14 @@ typedef struct image_desc {
* This structure represents the superset of information that can be passed to
* BL31 e.g. while passing control to it from BL2. The BL32 parameters will be
* populated only if BL2 detects its presence. A pointer to a structure of this
* type should be passed in X0 to BL3-1's cold boot entrypoint.
* type should be passed in X0 to BL31's cold boot entrypoint.
*
* Use of this structure and the X0 parameter is not mandatory: the BL3-1
* Use of this structure and the X0 parameter is not mandatory: the BL31
* platform code can use other mechanisms to provide the necessary information
* about BL3-2 and BL3-3 to the common and SPD code.
* about BL32 and BL33 to the common and SPD code.
*
* BL3-1 image information is mandatory if this structure is used. If either of
* the optional BL3-2 and BL3-3 image information is not provided, this is
* BL31 image information is mandatory if this structure is used. If either of
* the optional BL32 and BL33 image information is not provided, this is
* indicated by the respective image_info pointers being zero.
******************************************************************************/
typedef struct bl31_params {

2
include/common/el3_common_macros.S
View file

@ -104,7 +104,7 @@
/* -----------------------------------------------------------------------------
* This is the super set of actions that need to be performed during a cold boot
* or a warm boot in EL3. This code is shared by BL1 and BL3-1.
* or a warm boot in EL3. This code is shared by BL1 and BL31.
*
* This macro will always perform reset handling, architectural initialisations
* and stack setup. The rest of the actions are optional because they might not

2
include/lib/cpus/aarch64/cpu_macros.S
View file

@ -46,7 +46,7 @@ CPU_MIDR: /* cpu_ops midr */
CPU_RESET_FUNC: /* cpu_ops reset_func */
.space 8
#endif
#if IMAGE_BL31 /* The power down core and cluster is needed only in BL3-1 */
#if IMAGE_BL31 /* The power down core and cluster is needed only in BL31 */
CPU_PWR_DWN_CORE: /* cpu_ops core_pwr_dwn */
.space 8
CPU_PWR_DWN_CLUSTER: /* cpu_ops cluster_pwr_dwn */

4
include/plat/arm/common/aarch64/arm_macros.S
View file

@ -57,7 +57,7 @@ spacer:
/* ---------------------------------------------
* The below utility macro prints out relevant GIC
* registers whenever an unhandled exception is
* taken in BL3-1 on ARM standard platforms.
* taken in BL31 on ARM standard platforms.
* Expects: GICD base in x16, GICC base in x17
* Clobbers: x0 - x10, sp
* ---------------------------------------------
@ -125,7 +125,7 @@ cci_iface_regs:
/* ------------------------------------------------
* The below required platform porting macro prints
* out relevant interconnect registers whenever an
* unhandled exception is taken in BL3-1.
* unhandled exception is taken in BL31.
* Clobbers: x0 - x9, sp
* ------------------------------------------------
*/

12
include/plat/arm/common/arm_def.h
View file

@ -41,7 +41,7 @@
* Definitions common to all ARM standard platforms
*****************************************************************************/
/* Special value used to verify platform parameters from BL2 to BL3-1 */
/* Special value used to verify platform parameters from BL2 to BL31 */
#define ARM_BL31_PLAT_PARAM_VAL 0x0f1e2d3c4b5a6978ULL
#define ARM_CLUSTER_COUNT 2
@ -257,7 +257,7 @@
* BL2 specific defines.
******************************************************************************/
/*
* Put BL2 just below BL3-1. BL2_BASE is calculated using the current BL2 debug
* Put BL2 just below BL31. BL2_BASE is calculated using the current BL2 debug
* size plus a little space for growth.
*/
#if TRUSTED_BOARD_BOOT
@ -268,11 +268,11 @@
#define BL2_LIMIT BL31_BASE
/*******************************************************************************
* BL3-1 specific defines.
* BL31 specific defines.
******************************************************************************/
/*
* Put BL3-1 at the top of the Trusted SRAM. BL31_BASE is calculated using the
* current BL3-1 debug size plus a little space for growth.
* Put BL31 at the top of the Trusted SRAM. BL31_BASE is calculated using the
* current BL31 debug size plus a little space for growth.
*/
#define BL31_BASE (ARM_BL_RAM_BASE + \
ARM_BL_RAM_SIZE - \
@ -281,7 +281,7 @@
#define BL31_LIMIT (ARM_BL_RAM_BASE + ARM_BL_RAM_SIZE)
/*******************************************************************************
* BL3-2 specific defines.
* BL32 specific defines.
******************************************************************************/
/*
* On ARM standard platforms, the TSP can execute from Trusted SRAM,

4
include/plat/arm/common/plat_arm.h
View file

@ -87,7 +87,7 @@ void arm_configure_mmu_el3(unsigned long total_base,
#else
/*
* Empty macros for all other BL stages other than BL3-1
* Empty macros for all other BL stages other than BL31
*/
#define ARM_INSTANTIATE_LOCK
#define arm_lock_init()
@ -171,7 +171,7 @@ void arm_bl2u_early_platform_setup(struct meminfo *mem_layout,
void arm_bl2u_platform_setup(void);
void arm_bl2u_plat_arch_setup(void);
/* BL3-1 utility functions */
/* BL31 utility functions */
void arm_bl31_early_platform_setup(bl31_params_t *from_bl2,
void *plat_params_from_bl2);
void arm_bl31_platform_setup(void);

2
include/plat/arm/css/common/aarch64/css_macros.S
View file

@ -36,7 +36,7 @@
/* ---------------------------------------------
* The below required platform porting macro
* prints out relevant GIC registers whenever an
* unhandled exception is taken in BL3-1.
* unhandled exception is taken in BL31.
* Clobbers: x0 - x10, x16, x17, sp
* ---------------------------------------------
*/

4
include/plat/arm/css/common/css_def.h
View file

@ -111,8 +111,8 @@
/*
* Load address of SCP_BL2 in CSS platform ports
* SCP_BL2 is loaded to the same place as BL3-1. Once SCP_BL2 is transferred to the
* SCP, it is discarded and BL3-1 is loaded over the top.
* SCP_BL2 is loaded to the same place as BL31. Once SCP_BL2 is transferred to the
* SCP, it is discarded and BL31 is loaded over the top.
*/
#define SCP_BL2_BASE BL31_BASE

2
include/plat/common/common_def.h
View file

@ -55,7 +55,7 @@
* avoid subtle integer overflow errors due to implicit integer type promotion
* when working with 32-bit values.
*
* The TSP linker script includes some of these definitions to define the BL3-2
* The TSP linker script includes some of these definitions to define the BL32
* memory map, but the GNU LD does not support the 'ull' suffix, causing the
* build process to fail. To solve this problem, the auxiliary macro MAKE_ULL(x)
* will add the 'ull' suffix only when the macro __LINKER__ is not defined

26
include/plat/common/platform.h
View file

@ -134,7 +134,7 @@ struct meminfo *bl2_plat_sec_mem_layout(void);
/*
* This function returns a pointer to the shared memory that the platform has
* kept aside to pass trusted firmware related information that BL3-1
* kept aside to pass trusted firmware related information that BL31
* could need
*/
struct bl31_params *bl2_plat_get_bl31_params(void);
@ -147,14 +147,14 @@ struct entry_point_info *bl2_plat_get_bl31_ep_info(void);
/*
* This function flushes to main memory all the params that are
* passed to BL3-1
* passed to BL31
*/
void bl2_plat_flush_bl31_params(void);
/*
* The next 2 functions allow the platform to change the entrypoint information
* for the mandatory 3rd level BL images, BL3-1 and BL3-3. This is done after
* BL2 has loaded those images into memory but before BL3-1 is executed.
* for the mandatory 3rd level BL images, BL31 and BL33. This is done after
* BL2 has loaded those images into memory but before BL31 is executed.
*/
void bl2_plat_set_bl31_ep_info(struct image_info *image,
struct entry_point_info *ep);
@ -162,7 +162,7 @@ void bl2_plat_set_bl31_ep_info(struct image_info *image,
void bl2_plat_set_bl33_ep_info(struct image_info *image,
struct entry_point_info *ep);
/* Gets the memory layout for BL3-3 */
/* Gets the memory layout for BL33 */
void bl2_plat_get_bl33_meminfo(struct meminfo *mem_info);
/*******************************************************************************
@ -179,13 +179,13 @@ void bl2_plat_get_scp_bl2_meminfo(struct meminfo *mem_info);
int bl2_plat_handle_scp_bl2(struct image_info *scp_bl2_image_info);
/*******************************************************************************
* Conditionally mandatory BL2 functions: must be implemented if BL3-2 image
* Conditionally mandatory BL2 functions: must be implemented if BL32 image
* is supported
******************************************************************************/
void bl2_plat_set_bl32_ep_info(struct image_info *image,
struct entry_point_info *ep);
/* Gets the memory layout for BL3-2 */
/* Gets the memory layout for BL32 */
void bl2_plat_get_bl32_meminfo(struct meminfo *mem_info);
/*******************************************************************************
@ -210,7 +210,7 @@ void bl2u_platform_setup(void);
int bl2u_plat_handle_scp_bl2u(void);
/*******************************************************************************
* Mandatory BL3-1 functions
* Mandatory BL31 functions
******************************************************************************/
void bl31_early_platform_setup(struct bl31_params *from_bl2,
void *plat_params_from_bl2);
@ -220,26 +220,26 @@ void bl31_plat_runtime_setup(void);
struct entry_point_info *bl31_plat_get_next_image_ep_info(uint32_t type);
/*******************************************************************************
* Mandatory PSCI functions (BL3-1)
* Mandatory PSCI functions (BL31)
******************************************************************************/
int plat_setup_psci_ops(uintptr_t sec_entrypoint,
const struct plat_psci_ops **);
const unsigned char *plat_get_power_domain_tree_desc(void);
/*******************************************************************************
* Optional PSCI functions (BL3-1).
* Optional PSCI functions (BL31).
******************************************************************************/
plat_local_state_t plat_get_target_pwr_state(unsigned int lvl,
const plat_local_state_t *states,
unsigned int ncpu);
/*******************************************************************************
* Optional BL3-1 functions (may be overridden)
* Optional BL31 functions (may be overridden)
******************************************************************************/
void bl31_plat_enable_mmu(uint32_t flags);
/*******************************************************************************
* Optional BL3-2 functions (may be overridden)
* Optional BL32 functions (may be overridden)
******************************************************************************/
void bl32_plat_enable_mmu(uint32_t flags);
@ -261,7 +261,7 @@ int plat_get_rotpk_info(void *cookie, void **key_ptr, unsigned int *key_len,
unsigned int platform_get_core_pos(unsigned long mpidr);
/*******************************************************************************
* Mandatory PSCI Compatibility functions (BL3-1)
* Mandatory PSCI Compatibility functions (BL31)
******************************************************************************/
int platform_setup_pm(const plat_pm_ops_t **);

2
make_helpers/tbbr/tbbr_tools.mk
View file

@ -35,7 +35,7 @@
# Expected environment:
#
# BUILD_PLAT: output directory
# NEED_BL32: indicates whether BL3-2 is needed by the platform
# NEED_BL32: indicates whether BL32 is needed by the platform
# BL2: image filename (optional). Default is IMG_BIN(2) (see macro IMG_BIN)
# SCP_BL2: image filename (optional). Default is IMG_BIN(30)
# BL31: image filename (optional). Default is IMG_BIN(31)

2
plat/arm/board/fvp/include/plat_macros.S
View file

@ -37,7 +37,7 @@
/* ---------------------------------------------
* The below required platform porting macro
* prints out relevant GIC registers whenever an
* unhandled exception is taken in BL3-1.
* unhandled exception is taken in BL31.
* Clobbers: x0 - x10, x16, x17, sp
* ---------------------------------------------
*/

2
plat/arm/board/fvp/include/platform_def.h
View file

@ -67,7 +67,7 @@
#define PLAT_ARM_SHARED_RAM_CACHED 1
/*
* Load address of BL3-3 for this platform port
* Load address of BL33 for this platform port
*/
#define PLAT_ARM_NS_IMAGE_OFFSET (ARM_DRAM1_BASE + 0x8000000)

2
plat/arm/common/aarch64/arm_common.c
View file

@ -109,7 +109,7 @@ uint32_t arm_get_spsr_for_bl32_entry(void)
{
/*
* The Secure Payload Dispatcher service is responsible for
* setting the SPSR prior to entry into the BL3-2 image.
* setting the SPSR prior to entry into the BL32 image.
*/
return 0;
}

24
plat/arm/common/arm_bl2_setup.c
View file

@ -64,7 +64,7 @@ static meminfo_t bl2_tzram_layout __aligned(CACHE_WRITEBACK_GRANULE);
/*******************************************************************************
* This structure represents the superset of information that is passed to
* BL3-1, e.g. while passing control to it from BL2, bl31_params
* BL31, e.g. while passing control to it from BL2, bl31_params
* and other platform specific params
******************************************************************************/
typedef struct bl2_to_bl31_params_mem {
@ -117,7 +117,7 @@ bl31_params_t *bl2_plat_get_bl31_params(void)
/*
* Initialise the memory for all the arguments that needs to
* be passed to BL3-1
* be passed to BL31
*/
memset(&bl31_params_mem, 0, sizeof(bl2_to_bl31_params_mem_t));
@ -125,12 +125,12 @@ bl31_params_t *bl2_plat_get_bl31_params(void)
bl2_to_bl31_params = &bl31_params_mem.bl31_params;
SET_PARAM_HEAD(bl2_to_bl31_params, PARAM_BL31, VERSION_1, 0);
/* Fill BL3-1 related information */
/* Fill BL31 related information */
bl2_to_bl31_params->bl31_image_info = &bl31_params_mem.bl31_image_info;
SET_PARAM_HEAD(bl2_to_bl31_params->bl31_image_info, PARAM_IMAGE_BINARY,
VERSION_1, 0);
/* Fill BL3-2 related information if it exists */
/* Fill BL32 related information if it exists */
#if BL32_BASE
bl2_to_bl31_params->bl32_ep_info = &bl31_params_mem.bl32_ep_info;
SET_PARAM_HEAD(bl2_to_bl31_params->bl32_ep_info, PARAM_EP,
@ -140,12 +140,12 @@ bl31_params_t *bl2_plat_get_bl31_params(void)
VERSION_1, 0);
#endif
/* Fill BL3-3 related information */
/* Fill BL33 related information */
bl2_to_bl31_params->bl33_ep_info = &bl31_params_mem.bl33_ep_info;
SET_PARAM_HEAD(bl2_to_bl31_params->bl33_ep_info,
PARAM_EP, VERSION_1, 0);
/* BL3-3 expects to receive the primary CPU MPID (through x0) */
/* BL33 expects to receive the primary CPU MPID (through x0) */
bl2_to_bl31_params->bl33_ep_info->args.arg0 = 0xffff & read_mpidr();
bl2_to_bl31_params->bl33_image_info = &bl31_params_mem.bl33_image_info;
@ -244,9 +244,9 @@ void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)
}
/*******************************************************************************
* Before calling this function BL3-1 is loaded in memory and its entrypoint
* Before calling this function BL31 is loaded in memory and its entrypoint
* is set by load_image. This is a placeholder for the platform to change
* the entrypoint of BL3-1 and set SPSR and security state.
* the entrypoint of BL31 and set SPSR and security state.
* On ARM standard platforms we only set the security state of the entrypoint
******************************************************************************/
void bl2_plat_set_bl31_ep_info(image_info_t *bl31_image_info,
@ -259,9 +259,9 @@ void bl2_plat_set_bl31_ep_info(image_info_t *bl31_image_info,
/*******************************************************************************
* Before calling this function BL3-2 is loaded in memory and its entrypoint
* Before calling this function BL32 is loaded in memory and its entrypoint
* is set by load_image. This is a placeholder for the platform to change
* the entrypoint of BL3-2 and set SPSR and security state.
* the entrypoint of BL32 and set SPSR and security state.
* On ARM standard platforms we only set the security state of the entrypoint
******************************************************************************/
void bl2_plat_set_bl32_ep_info(image_info_t *bl32_image_info,
@ -272,9 +272,9 @@ void bl2_plat_set_bl32_ep_info(image_info_t *bl32_image_info,
}
/*******************************************************************************
* Before calling this function BL3-3 is loaded in memory and its entrypoint
* Before calling this function BL33 is loaded in memory and its entrypoint
* is set by load_image. This is a placeholder for the platform to change
* the entrypoint of BL3-3 and set SPSR and security state.
* the entrypoint of BL33 and set SPSR and security state.
* On ARM standard platforms we only set the security state of the entrypoint
******************************************************************************/
void bl2_plat_set_bl33_ep_info(image_info_t *image,

26
plat/arm/common/arm_bl31_setup.c
View file

@ -43,7 +43,7 @@
/*
* The next 3 constants identify the extents of the code, RO data region and the
* limit of the BL3-1 image. These addresses are used by the MMU setup code and
* limit of the BL31 image. These addresses are used by the MMU setup code and
* therefore they must be page-aligned. It is the responsibility of the linker
* script to ensure that __RO_START__, __RO_END__ & __BL31_END__ linker symbols
* refer to page-aligned addresses.
@ -66,7 +66,7 @@
/*
* Placeholder variables for copying the arguments that have been passed to
* BL3-1 from BL2.
* BL31 from BL2.
*/
static entry_point_info_t bl32_image_ep_info;
static entry_point_info_t bl33_image_ep_info;
@ -82,8 +82,8 @@ static entry_point_info_t bl33_image_ep_info;
/*******************************************************************************
* Return a pointer to the 'entry_point_info' structure of the next image for the
* security state specified. BL3-3 corresponds to the non-secure image type
* while BL3-2 corresponds to the secure image type. A NULL pointer is returned
* security state specified. BL33 corresponds to the non-secure image type
* while BL32 corresponds to the secure image type. A NULL pointer is returned
* if the image does not exist.
******************************************************************************/
entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t type)
@ -104,7 +104,7 @@ entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t type)
}
/*******************************************************************************
* Perform any BL3-1 early platform setup common to ARM standard platforms.
* Perform any BL31 early platform setup common to ARM standard platforms.
* Here is an opportunity to copy parameters passed by the calling EL (S-EL1
* in BL2 & S-EL3 in BL1) before they are lost (potentially). This needs to be
* done before the MMU is initialized so that the memory layout can be used
@ -119,12 +119,12 @@ void arm_bl31_early_platform_setup(bl31_params_t *from_bl2,
ARM_CONSOLE_BAUDRATE);
#if RESET_TO_BL31
/* There are no parameters from BL2 if BL3-1 is a reset vector */
/* There are no parameters from BL2 if BL31 is a reset vector */
assert(from_bl2 == NULL);
assert(plat_params_from_bl2 == NULL);
#ifdef BL32_BASE
/* Populate entry point information for BL3-2 */
/* Populate entry point information for BL32 */
SET_PARAM_HEAD(&bl32_image_ep_info,
PARAM_EP,
VERSION_1,
@ -134,13 +134,13 @@ void arm_bl31_early_platform_setup(bl31_params_t *from_bl2,
bl32_image_ep_info.spsr = arm_get_spsr_for_bl32_entry();
#endif /* BL32_BASE */
/* Populate entry point information for BL3-3 */
/* Populate entry point information for BL33 */
SET_PARAM_HEAD(&bl33_image_ep_info,
PARAM_EP,
VERSION_1,
0);
/*
* Tell BL3-1 where the non-trusted software image
* Tell BL31 where the non-trusted software image
* is located and the entry state information
*/
bl33_image_ep_info.pc = plat_get_ns_image_entrypoint();
@ -156,14 +156,14 @@ void arm_bl31_early_platform_setup(bl31_params_t *from_bl2,
assert(from_bl2->h.version >= VERSION_1);
/*
* In debug builds, we pass a special value in 'plat_params_from_bl2'
* to verify platform parameters from BL2 to BL3-1.
* to verify platform parameters from BL2 to BL31.
* In release builds, it's not used.
*/
assert(((unsigned long long)plat_params_from_bl2) ==
ARM_BL31_PLAT_PARAM_VAL);
/*
* Copy BL3-2 (if populated by BL2) and BL3-3 entry point information.
* Copy BL32 (if populated by BL2) and BL33 entry point information.
* They are stored in Secure RAM, in BL2's address space.
*/
if (from_bl2->bl32_ep_info)
@ -195,7 +195,7 @@ void bl31_early_platform_setup(bl31_params_t *from_bl2,
}
/*******************************************************************************
* Perform any BL3-1 platform setup common to ARM standard platforms
* Perform any BL31 platform setup common to ARM standard platforms
******************************************************************************/
void arm_bl31_platform_setup(void)
{
@ -224,7 +224,7 @@ void arm_bl31_platform_setup(void)
}
/*******************************************************************************
* Perform any BL3-1 platform runtime setup prior to BL3-1 exit common to ARM
* Perform any BL31 platform runtime setup prior to BL31 exit common to ARM
* standard platforms
******************************************************************************/
void arm_bl31_plat_runtime_setup(void)

2
plat/arm/common/tsp/arm_tsp_setup.c
View file

@ -38,7 +38,7 @@
/*
* The next 3 constants identify the extents of the code & RO data region and
* the limit of the BL3-2 image. These addresses are used by the MMU setup code
* the limit of the BL32 image. These addresses are used by the MMU setup code
* and therefore they must be page-aligned. It is the responsibility of the
* linker script to ensure that __RO_START__, __RO_END__ & & __BL32_END__
* linker symbols refer to page-aligned addresses.

2
plat/arm/css/common/css_common.mk
View file

@ -56,7 +56,7 @@ $(eval $(call FWU_FIP_ADD_IMG,SCP_BL2U,--scp_bl2u))
endif
ifneq (${RESET_TO_BL31},0)
$(error "Using BL3-1 as the reset vector is not supported on CSS platforms. \
$(error "Using BL31 as the reset vector is not supported on CSS platforms. \
Please set RESET_TO_BL31 to 0.")
endif

2
services/std_svc/psci/psci_entry.S
View file

@ -48,7 +48,7 @@ func psci_entrypoint
* On the warm boot path, most of the EL3 initialisations performed by
* 'el3_entrypoint_common' must be skipped:
*
* - Only when the platform bypasses the BL1/BL3-1 entrypoint by
* - Only when the platform bypasses the BL1/BL31 entrypoint by
* programming the reset address do we need to set the CPU endianness.
* In other cases, we assume this has been taken care by the
* entrypoint code.

6
tools/fip_create/fip_create.c
View file

@ -67,11 +67,11 @@ static entry_lookup_list_t toc_entry_lookup_list[] = {
"bl2", NULL, FLAG_FILENAME },
{ "SCP Firmware SCP_BL2", UUID_SCP_FIRMWARE_SCP_BL2,
"scp_bl2", NULL, FLAG_FILENAME},
{ "EL3 Runtime Firmware BL3-1", UUID_EL3_RUNTIME_FIRMWARE_BL31,
{ "EL3 Runtime Firmware BL31", UUID_EL3_RUNTIME_FIRMWARE_BL31,
"bl31", NULL, FLAG_FILENAME},
{ "Secure Payload BL3-2 (Trusted OS)", UUID_SECURE_PAYLOAD_BL32,
{ "Secure Payload BL32 (Trusted OS)", UUID_SECURE_PAYLOAD_BL32,
"bl32", NULL, FLAG_FILENAME},
{ "Non-Trusted Firmware BL3-3", UUID_NON_TRUSTED_FIRMWARE_BL33,
{ "Non-Trusted Firmware BL33", UUID_NON_TRUSTED_FIRMWARE_BL33,
"bl33", NULL, FLAG_FILENAME},
/* Key Certificates */
{ "Root Of Trust key certificate", UUID_ROT_KEY_CERT,