diff --git a/Makefile b/Makefile index 97fa0ac..b035301 100644 --- a/Makefile +++ b/Makefile @@ -309,7 +309,7 @@ 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 @@ @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)" diff --git a/bl1/bl1_main.c b/bl1/bl1_main.c index 84d5611..3cca176 100644 --- a/bl1/bl1_main.c +++ b/bl1/bl1_main.c @@ -216,7 +216,7 @@ ******************************************************************************/ 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); } diff --git a/bl2/bl2_main.c b/bl2/bl2_main.c index d74d426..9ff75d2 100644 --- a/bl2/bl2_main.c +++ b/bl2/bl2_main.c @@ -93,9 +93,9 @@ #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 @@ 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 @@ } /******************************************************************************* - * 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 @@ #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 @@ } /******************************************************************************* - * 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 @@ 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 @@ /******************************************************************************* * 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 @@ /* * 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 @@ * 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 @@ #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 @@ 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); } diff --git a/bl31/aarch64/bl31_entrypoint.S b/bl31/aarch64/bl31_entrypoint.S index 45aa85d..1c8eed9 100644 --- a/bl31/aarch64/bl31_entrypoint.S +++ b/bl31/aarch64/bl31_entrypoint.S @@ -91,7 +91,7 @@ _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. * --------------------------------------------------------------------- diff --git a/bl31/bl31.ld.S b/bl31/bl31.ld.S index e572f9b..dc6e7a4 100644 --- a/bl31/bl31.ld.S +++ b/bl31/bl31.ld.S @@ -94,7 +94,7 @@ } >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 @@ __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.") } diff --git a/bl31/bl31.mk b/bl31/bl31.mk index 0c2b631..8951159 100644 --- a/bl31/bl31.mk +++ b/bl31/bl31.mk @@ -62,7 +62,7 @@ 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 diff --git a/bl31/bl31_main.c b/bl31/bl31_main.c index f22e612..835d41e 100644 --- a/bl31/bl31_main.c +++ b/bl31/bl31_main.c @@ -71,8 +71,8 @@ ******************************************************************************/ 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 @@ 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 @@ * 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 @@ 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); diff --git a/bl32/tsp/tsp.ld.S b/bl32/tsp/tsp.ld.S index 41c4b4a..9c7ed38 100644 --- a/bl32/tsp/tsp.ld.S +++ b/bl32/tsp/tsp.ld.S @@ -138,5 +138,5 @@ __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.") } diff --git a/bl32/tsp/tsp.mk b/bl32/tsp/tsp.mk index aeda31a..9919fe4 100644 --- a/bl32/tsp/tsp.mk +++ b/bl32/tsp/tsp.mk @@ -41,8 +41,8 @@ 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 diff --git a/common/aarch64/early_exceptions.S b/common/aarch64/early_exceptions.S index 780a38f..64bfcd0 100644 --- a/common/aarch64/early_exceptions.S +++ b/common/aarch64/early_exceptions.S @@ -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. * ----------------------------------------------------- */ diff --git a/docs/auth-framework.md b/docs/auth-framework.md index f6455b9..531505b 100644 --- a/docs/auth-framework.md +++ b/docs/auth-framework.md @@ -83,7 +83,7 @@ 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. ``` @@ -97,8 +97,8 @@ / | / | L v - +------------------+ +-------------------+ - | Trusted World |------>| BL3-1 Key | + +------------------+ +-------------------+ + | Trusted World |------>| BL31 Key | | Public Key | | Certificate | +------------------+ | (Auth Image) | +-------------------+ @@ -108,7 +108,7 @@ / | / v +------------------+ L +-------------------+ - | BL3-1 Content |------>| BL3-1 Content | + | BL31 Content |------>| BL31 Content | | Certificate PK | | Certificate | +------------------+ | (Auth Image) | +-------------------+ @@ -118,7 +118,7 @@ / | / v +------------------+ L +-------------------+ - | BL3-1 Hash |------>| BL3-1 Image | + | BL31 Hash |------>| BL31 Image | | | | (Data Image) | +------------------+ | | +-------------------+ @@ -211,15 +211,15 @@ 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 @@ `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 @@ * `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 @@ 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 @@ 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`. diff --git a/docs/firmware-design.md b/docs/firmware-design.md index 51084f4..d066fc3 100644 --- a/docs/firmware-design.md +++ b/docs/firmware-design.md @@ -8,7 +8,7 @@ 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 @@ * 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ * 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 @@ 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 @@ 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 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 @@ 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 @@ 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 @@ 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 @@ ### 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 @@ --------------------------------------- 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 @@ * 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 @@ 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 @@ ### 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 @@ ### 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 @@ * `__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 @@ 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 @@ 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 @@ 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 @@ DRAM 0xffffffff +----------+ - | BL3-2 | (secure) + | BL32 | (secure) 0xff000000 +----------+ | | : : (non-secure) @@ -1329,9 +1329,9 @@ 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 @@ 0x00000000 +----------+ -**Juno with BL3-2 in Trusted SRAM (default option):** +**Juno with BL32 in Trusted SRAM (default option):** Flash0 0x0C000000 +----------+ @@ -1355,27 +1355,27 @@ | 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 @@ | 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 @@ 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 diff --git a/docs/platform-migration-guide.md b/docs/platform-migration-guide.md index f6790ef..27cd067 100644 --- a/docs/platform-migration-guide.md +++ b/docs/platform-migration-guide.md @@ -314,7 +314,7 @@ 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 @@ [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 @@ 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 diff --git a/docs/porting-guide.md b/docs/porting-guide.md index 5e80a7f..3dc60cc 100644 --- a/docs/porting-guide.md +++ b/docs/porting-guide.md @@ -13,10 +13,10 @@ 3. [Boot Loader stage specific modifications](#3--modifications-specific-to-a-boot-loader-stage) * [Boot Loader stage 1 (BL1)](#31-boot-loader-stage-1-bl1) * [Boot Loader stage 2 (BL2)](#32-boot-loader-stage-2-bl2) - * [Boot Loader stage 3-1 (BL3-1)](#32-boot-loader-stage-3-1-bl3-1) - * [PSCI implementation (in BL3-1)](#33-power-state-coordination-interface-in-bl3-1) - * [Interrupt Management framework (in BL3-1)](#34--interrupt-management-framework-in-bl3-1) - * [Crash Reporting mechanism (in BL3-1)](#35--crash-reporting-mechanism-in-bl3-1) + * [Boot Loader stage 3-1 (BL31)](#32-boot-loader-stage-3-1-bl3-1) + * [PSCI implementation (in BL31)](#33-power-state-coordination-interface-in-bl3-1) + * [Interrupt Management framework (in BL31)](#34--interrupt-management-framework-in-bl3-1) + * [Crash Reporting mechanism (in BL31)](#35--crash-reporting-mechanism-in-bl3-1) 4. [Build flags](#4--build-flags) 5. [C Library](#5--c-library) 6. [Storage abstraction layer](#6--storage-abstraction-layer) @@ -212,16 +212,16 @@ * **#define : BL31_BASE** - Defines the base address in secure RAM where BL2 loads the BL3-1 binary + Defines the base address in secure RAM where BL2 loads the BL31 binary image. Must be aligned on a page-size boundary. * **#define : BL31_LIMIT** - Defines the maximum address in secure RAM that the BL3-1 image can occupy. + Defines the maximum address in secure RAM that the BL31 image can occupy. * **#define : NS_IMAGE_OFFSET** - Defines the base address in non-secure DRAM where BL2 loads the BL3-3 binary + Defines the base address in non-secure DRAM where BL2 loads the BL33 binary image. Must be aligned on a page-size boundary. For every image, the platform must define individual identifiers that will be @@ -238,11 +238,11 @@ * **#define : BL31_IMAGE_ID** - BL3-1 image identifier, used by BL2 to load BL3-1. + BL31 image identifier, used by BL2 to load BL31. * **#define : BL33_IMAGE_ID** - BL3-3 image identifier, used by BL2 to load BL3-3. + BL33 image identifier, used by BL2 to load BL33. If Trusted Board Boot is enabled, the following certificate identifiers must also be defined: @@ -259,22 +259,22 @@ * **#define : SOC_FW_KEY_CERT_ID** - BL3-1 key certificate identifier, used by BL2 to load the BL3-1 key + BL31 key certificate identifier, used by BL2 to load the BL31 key certificate. * **#define : SOC_FW_CONTENT_CERT_ID** - BL3-1 content certificate identifier, used by BL2 to load the BL3-1 content + BL31 content certificate identifier, used by BL2 to load the BL31 content certificate. * **#define : NON_TRUSTED_FW_KEY_CERT_ID** - BL3-3 key certificate identifier, used by BL2 to load the BL3-3 key + BL33 key certificate identifier, used by BL2 to load the BL33 key certificate. * **#define : NON_TRUSTED_FW_CONTENT_CERT_ID** - BL3-3 content certificate identifier, used by BL2 to load the BL3-3 content + BL33 content certificate identifier, used by BL2 to load the BL33 content certificate. If a SCP_BL2 image is supported by the platform, the following constants must @@ -295,33 +295,33 @@ SCP_BL2 content certificate identifier, used by BL2 to load the SCP_BL2 content certificate (mandatory when Trusted Board Boot is enabled). -If a BL3-2 image is supported by the platform, the following constants must +If a BL32 image is supported by the platform, the following constants must also be defined: * **#define : BL32_IMAGE_ID** - BL3-2 image identifier, used by BL2 to load BL3-2. + BL32 image identifier, used by BL2 to load BL32. * **#define : TRUSTED_OS_FW_KEY_CERT_ID** - BL3-2 key certificate identifier, used by BL2 to load the BL3-2 key + BL32 key certificate identifier, used by BL2 to load the BL32 key certificate (mandatory when Trusted Board Boot is enabled). * **#define : TRUSTED_OS_FW_CONTENT_CERT_ID** - BL3-2 content certificate identifier, used by BL2 to load the BL3-2 content + BL32 content certificate identifier, used by BL2 to load the BL32 content certificate (mandatory when Trusted Board Boot is enabled). * **#define : BL32_BASE** - Defines the base address in secure memory where BL2 loads the BL3-2 binary + Defines the base address in secure memory where BL2 loads the BL32 binary image. Must be aligned on a page-size boundary. * **#define : BL32_LIMIT** - Defines the maximum address that the BL3-2 image can occupy. + Defines the maximum address that the BL32 image can occupy. -If the Test Secure-EL1 Payload (TSP) instantiation of BL3-2 is supported by the +If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the platform, the following constants must also be defined: * **#define : TSP_SEC_MEM_BASE** @@ -331,9 +331,9 @@ * **#define : TSP_SEC_MEM_SIZE** - Defines the size of the secure memory used by the BL3-2 image on the + Defines the size of the secure memory used by the BL32 image on the platform. `TSP_SEC_MEM_BASE` and `TSP_SEC_MEM_SIZE` must fully accomodate - the memory required by the BL3-2 image, defined by `BL32_BASE` and + the memory required by the BL32 image, defined by `BL32_BASE` and `BL32_LIMIT`. * **#define : TSP_IRQ_SEC_PHY_TIMER** @@ -366,7 +366,7 @@ entities than this value using `io_open()` will fail with -ENOMEM. If the platform needs to allocate data within the per-cpu data framework in -BL3-1, it should define the following macro. Currently this is only required if +BL31, it should define the following macro. Currently this is only required if the platform decides not to use the coherent memory section by undefining the USE_COHERENT_MEM build flag. In this case, the framework allocates the required memory within the the per-cpu data to minimize wastage. @@ -381,7 +381,7 @@ * **#define : BL31_PROGBITS_LIMIT** - Defines the maximum address in secure RAM that the BL3-1's progbits sections + Defines the maximum address in secure RAM that the BL31's progbits sections can occupy. * **#define : TSP_PROGBITS_LIMIT** @@ -397,14 +397,14 @@ * **Macro : plat_print_gic_regs** This macro allows the crash reporting routine to print GIC registers - in case of an unhandled exception in BL3-1. This aids in debugging and + in case of an unhandled exception in BL31. This aids in debugging and this macro can be defined to be empty in case GIC register reporting is not desired. * **Macro : plat_print_interconnect_regs** This macro allows the crash reporting routine to print interconnect - registers in case of an unhandled exception in BL3-1. This aids in debugging + registers in case of an unhandled exception in BL31. This aids in debugging and this macro can be defined to be empty in case interconnect register reporting is not desired. In ARM standard platforms, the CCI snoop control registers are reported. @@ -414,7 +414,7 @@ ------------------ BL1 by default implements the reset vector where execution starts from a cold -or warm boot. BL3-1 can be optionally set as a reset vector using the +or warm boot. BL31 can be optionally set as a reset vector using the RESET_TO_BL31 make variable. For each CPU, the reset vector code is responsible for the following tasks: @@ -426,7 +426,7 @@ performs the necessary steps to remove it from this state. 3. In the case of a warm boot, ensuring that the CPU jumps to a platform- - specific address in the BL3-1 image in the same processor mode as it was + specific address in the BL31 image in the same processor mode as it was when released from reset. The following functions need to be implemented by the platform port to enable @@ -443,7 +443,7 @@ distinguishing between a warm and cold reset for the current CPU using platform-specific means. If it's a warm reset, then it returns the warm reset entrypoint point provided to `plat_setup_psci_ops()` during -BL3-1 initialization. If it's a cold reset then this function must return zero. +BL31 initialization. If it's a cold reset then this function must return zero. This function does not follow the Procedure Call Standard used by the Application Binary Interface for the ARM 64-bit architecture. The caller should @@ -567,7 +567,7 @@ This function validates the `MPIDR` of a CPU and converts it to an index, which can be used as a CPU-specific linear index into blocks of memory. In case the `MPIDR` is invalid, this function returns -1. This function will only -be invoked by BL3-1 after the power domain topology is initialized and can +be invoked by BL31 after the power domain topology is initialized and can utilize the C runtime environment. For further details about how ARM Trusted Firmware represents the power domain topology and how this relates to the linear CPU index, please refer [Power Domain Topology Design]. @@ -848,33 +848,33 @@ implemented in the `bl2_plat_handle_scp_bl2()` function. If `SCP_BL2_BASE` is not defined then this step is not performed. -2. Loading the BL3-1 binary image into secure RAM from non-volatile storage. To - load the BL3-1 image, BL2 makes use of the `meminfo` structure passed to it +2. Loading the BL31 binary image into secure RAM from non-volatile storage. To + load the BL31 image, BL2 makes use of the `meminfo` structure passed to it by BL1. This structure allows BL2 to calculate how much secure RAM is available for its use. The platform also defines the address in secure RAM - where BL3-1 is loaded through the constant `BL31_BASE`. BL2 uses this - information to determine if there is enough memory to load the BL3-1 image. + where BL31 is loaded through the constant `BL31_BASE`. BL2 uses this + information to determine if there is enough memory to load the BL31 image. -3. (Optional) Loading the BL3-2 binary image (if present) from platform - provided non-volatile storage. To load the BL3-2 image, BL2 makes use of +3. (Optional) Loading the BL32 binary image (if present) from platform + provided non-volatile storage. To load the BL32 image, BL2 makes use of the `meminfo` returned by the `bl2_plat_get_bl32_meminfo()` function. - The platform also defines the address in memory where BL3-2 is loaded + The platform also defines the address in memory where BL32 is loaded through the optional constant `BL32_BASE`. BL2 uses this information - to determine if there is enough memory to load the BL3-2 image. + to determine if there is enough memory to load the BL32 image. If `BL32_BASE` is not defined then this and the next step is not performed. -4. (Optional) Arranging to pass control to the BL3-2 image (if present) that +4. (Optional) Arranging to pass control to the BL32 image (if present) that has been pre-loaded at `BL32_BASE`. BL2 populates an `entry_point_info` structure in memory provided by the platform with information about how - BL3-1 should pass control to the BL3-2 image. + BL31 should pass control to the BL32 image. -5. Loading the normal world BL3-3 binary image into non-secure DRAM from - platform storage and arranging for BL3-1 to pass control to this image. This +5. Loading the normal world BL33 binary image into non-secure DRAM from + platform storage and arranging for BL31 to pass control to this image. This address is determined using the `plat_get_ns_image_entrypoint()` function described below. 6. BL2 populates an `entry_point_info` structure in memory provided by the - platform with information about how BL3-1 should pass control to the + platform with information about how BL31 should pass control to the other BL images. The following functions must be implemented by the platform port to enable BL2 @@ -976,22 +976,22 @@ Return : bl31_params * BL2 platform code needs to return a pointer to a `bl31_params` structure it -will use for passing information to BL3-1. The `bl31_params` structure carries +will use for passing information to BL31. The `bl31_params` structure carries the following information. - Header describing the version information for interpreting the bl31_param structure - - Information about executing the BL3-3 image in the `bl33_ep_info` field - - Information about executing the BL3-2 image in the `bl32_ep_info` field - - Information about the type and extents of BL3-1 image in the + - Information about executing the BL33 image in the `bl33_ep_info` field + - Information about executing the BL32 image in the `bl32_ep_info` field + - Information about the type and extents of BL31 image in the `bl31_image_info` field - - Information about the type and extents of BL3-2 image in the + - Information about the type and extents of BL32 image in the `bl32_image_info` field - - Information about the type and extents of BL3-3 image in the + - Information about the type and extents of BL33 image in the `bl33_image_info` field The memory pointed by this structure and its sub-structures should be -accessible from BL3-1 initialisation code. BL3-1 might choose to copy the -necessary content, or maintain the structures until BL3-3 is initialised. +accessible from BL31 initialisation code. BL31 might choose to copy the +necessary content, or maintain the structures until BL33 is initialised. ### Funtion : bl2_plat_get_bl31_ep_info() [mandatory] @@ -1000,8 +1000,8 @@ Return : entry_point_info * BL2 platform code returns a pointer which is used to populate the entry point -information for BL3-1 entry point. The location pointed by it should be -accessible from BL1 while processing the synchronous exception to run to BL3-1. +information for BL31 entry point. The location pointed by it should be +accessible from BL1 while processing the synchronous exception to run to BL31. In ARM standard platforms this is allocated inside a bl2_to_bl31_params_mem structure in BL2 memory. @@ -1012,9 +1012,9 @@ Argument : image_info *, entry_point_info * Return : void -In the normal boot flow, this function is called after loading BL3-1 image and +In the normal boot flow, this function is called after loading BL31 image and it can be used to overwrite the entry point set by loader and also set the -security state and SPSR which represents the entry point system state for BL3-1. +security state and SPSR which represents the entry point system state for BL31. When booting an EL3 payload instead, this function is called after populating its entry point address and can be used for the same purpose for the payload @@ -1025,9 +1025,9 @@ Argument : image_info *, entry_point_info * Return : void -This function is called after loading BL3-2 image and it can be used to +This function is called after loading BL32 image and it can be used to overwrite the entry point set by loader and also set the security state -and SPSR which represents the entry point system state for BL3-2. +and SPSR which represents the entry point system state for BL32. ### Function : bl2_plat_set_bl33_ep_info() [mandatory] @@ -1035,9 +1035,9 @@ Argument : image_info *, entry_point_info * Return : void -This function is called after loading BL3-3 image and it can be used to +This function is called after loading BL33 image and it can be used to overwrite the entry point set by loader and also set the security state -and SPSR which represents the entry point system state for BL3-3. +and SPSR which represents the entry point system state for BL33. ### Function : bl2_plat_get_bl32_meminfo() [mandatory] @@ -1046,8 +1046,8 @@ Return : void This function is used to get the memory limits where BL2 can load the -BL3-2 image. The meminfo provided by this is used by load_image() to -validate whether the BL3-2 image can be loaded with in the given +BL32 image. The meminfo provided by this is used by load_image() to +validate whether the BL32 image can be loaded with in the given memory from the given base. ### Function : bl2_plat_get_bl33_meminfo() [mandatory] @@ -1056,8 +1056,8 @@ Return : void This function is used to get the memory limits where BL2 can load the -BL3-3 image. The meminfo provided by this is used by load_image() to -validate whether the BL3-3 image can be loaded with in the given +BL33 image. The meminfo provided by this is used by load_image() to +validate whether the BL33 image can be loaded with in the given memory from the given base. ### Function : bl2_plat_flush_bl31_params() [mandatory] @@ -1066,7 +1066,7 @@ Return : void Once BL2 has populated all the structures that needs to be read by BL1 -and BL3-1 including the bl31_params structures and its sub-structures, +and BL31 including the bl31_params structures and its sub-structures, the bl31_ep_info structure and any platform specific data. It flushes all these data to the main memory so that it is available when we jump to later Bootloader stages with MMU off @@ -1077,44 +1077,44 @@ Return : unsigned long As previously described, BL2 is responsible for arranging for control to be -passed to a normal world BL image through BL3-1. This function returns the -entrypoint of that image, which BL3-1 uses to jump to it. +passed to a normal world BL image through BL31. This function returns the +entrypoint of that image, which BL31 uses to jump to it. -BL2 is responsible for loading the normal world BL3-3 image (e.g. UEFI). +BL2 is responsible for loading the normal world BL33 image (e.g. UEFI). -3.2 Boot Loader Stage 3-1 (BL3-1) +3.2 Boot Loader Stage 3-1 (BL31) --------------------------------- -During cold boot, the BL3-1 stage is executed only by the primary CPU. This is +During cold boot, the BL31 stage is executed only by the primary CPU. This is determined in BL1 using the `platform_is_primary_cpu()` function. BL1 passes -control to BL3-1 at `BL31_BASE`. During warm boot, BL3-1 is executed by all -CPUs. BL3-1 executes at EL3 and is responsible for: +control to BL31 at `BL31_BASE`. During warm boot, BL31 is executed by all +CPUs. BL31 executes at EL3 and is responsible for: 1. Re-initializing all architectural and platform state. Although BL1 performs - some of this initialization, BL3-1 remains resident in EL3 and must ensure + some of this initialization, BL31 remains resident in EL3 and must ensure that EL3 architectural and platform state is completely initialized. It should make no assumptions about the system state when it receives control. 2. Passing control to a normal world BL image, pre-loaded at a platform- - specific address by BL2. BL3-1 uses the `entry_point_info` structure that BL2 + specific address by BL2. BL31 uses the `entry_point_info` structure that BL2 populated in memory to do this. -3. Providing runtime firmware services. Currently, BL3-1 only implements a +3. Providing runtime firmware services. Currently, BL31 only implements a subset of the Power State Coordination Interface (PSCI) API as a runtime service. See Section 3.3 below for details of porting the PSCI implementation. -4. Optionally passing control to the BL3-2 image, pre-loaded at a platform- - specific address by BL2. BL3-1 exports a set of apis that allow runtime +4. Optionally passing control to the BL32 image, pre-loaded at a platform- + specific address by BL2. BL31 exports a set of apis that allow runtime services to specify the security state in which the next image should be - executed and run the corresponding image. BL3-1 uses the `entry_point_info` + executed and run the corresponding image. BL31 uses the `entry_point_info` structure populated by BL2 to do this. -If BL3-1 is a reset vector, It also needs to handle the reset as specified in +If BL31 is a reset vector, It also needs to handle the reset as specified in section 2.2 before the tasks described above. -The following functions must be implemented by the platform port to enable BL3-1 +The following functions must be implemented by the platform port to enable BL31 to perform the above tasks. @@ -1131,11 +1131,11 @@ The platform can copy the contents of the `bl31_params` structure and its sub-structures into private variables if the original memory may be -subsequently overwritten by BL3-1 and similarly the `void *` pointing +subsequently overwritten by BL31 and similarly the `void *` pointing to the platform data also needs to be saved. In ARM standard platforms, BL2 passes a pointer to a `bl31_params` structure -in BL2 memory. BL3-1 copies the information in this pointer to internal data +in BL2 memory. BL31 copies the information in this pointer to internal data structures. @@ -1162,7 +1162,7 @@ called by the primary CPU. The purpose of this function is to complete platform initialization so that both -BL3-1 runtime services and normal world software can function correctly. +BL31 runtime services and normal world software can function correctly. In ARM standard platforms, this function does the following: * Initializes the generic interrupt controller. @@ -1196,7 +1196,7 @@ port does the necessary initializations in `bl31_plat_arch_setup()`. This function is called by `bl31_main()` to retrieve information provided by -BL2 for the next image in the security state specified by the argument. BL3-1 +BL2 for the next image in the security state specified by the argument. BL31 uses this information to pass control to that image in the specified security state. This function must return a pointer to the `entry_point_info` structure (that was copied during `bl31_early_platform_setup()`) if the image exists. It @@ -1232,7 +1232,7 @@ assertion is raised if the value of the constant is not aligned to the cache line boundary. -3.3 Power State Coordination Interface (in BL3-1) +3.3 Power State Coordination Interface (in BL31) ------------------------------------------------ The ARM Trusted Firmware's implementation of the PSCI API is based around the @@ -1249,7 +1249,7 @@ (for example, the system). More details on the power domain topology and its organization can be found in [Power Domain Topology Design]. -BL3-1's platform initialization code exports a pointer to the platform-specific +BL31's platform initialization code exports a pointer to the platform-specific power management operations required for the PSCI implementation to function correctly. This information is populated in the `plat_psci_ops` structure. The PSCI implementation calls members of the `plat_psci_ops` structure for performing @@ -1300,7 +1300,7 @@ This function returns a pointer to the byte array containing the power domain topology tree description. The format and method to construct this array are -described in [Power Domain Topology Design]. The BL3-1 PSCI initilization code +described in [Power Domain Topology Design]. The BL31 PSCI initilization code requires this array to be described by the platform, either statically or dynamically, to initialize the power domain topology tree. In case the array is populated dynamically, then plat_core_pos_by_mpidr() and @@ -1322,7 +1322,7 @@ the platform layer know about the warm boot entrypoint through the `sec_entrypoint` (first argument) and to export handler routines for platform-specific psci power management actions by populating the passed -pointer with a pointer to BL3-1's private `plat_psci_ops` structure. +pointer with a pointer to BL31's private `plat_psci_ops` structure. A description of each member of this structure is given below. Please refer to the ARM FVP specific implementation of these handlers in @@ -1441,9 +1441,9 @@ enter system suspend. -3.4 Interrupt Management framework (in BL3-1) +3.4 Interrupt Management framework (in BL31) ---------------------------------------------- -BL3-1 implements an Interrupt Management Framework (IMF) to manage interrupts +BL31 implements an Interrupt Management Framework (IMF) to manage interrupts generated in either security state and targeted to EL1 or EL2 in the non-secure state or EL3/S-EL1 in the secure state. The design of this framework is described in the [IMF Design Guide] @@ -1573,15 +1573,15 @@ type of interrupt. -3.5 Crash Reporting mechanism (in BL3-1) +3.5 Crash Reporting mechanism (in BL31) ---------------------------------------------- -BL3-1 implements a crash reporting mechanism which prints the various registers +BL31 implements a crash reporting mechanism which prints the various registers of the CPU to enable quick crash analysis and debugging. It requires that a console is designated as the crash console by the platform which will be used to print the register dump. The following functions must be implemented by the platform if it wants crash -reporting mechanism in BL3-1. The functions are implemented in assembly so that +reporting mechanism in BL31. The functions are implemented in assembly so that they can be invoked without a C Runtime stack. ### Function : plat_crash_console_init @@ -1620,7 +1620,7 @@ * **NEED_BL33** By default, this flag is defined `yes` by the build system and `BL33` build option should be supplied as a build option. The platform has the option - of excluding the BL3-3 image in the `fip` image by defining this flag to + of excluding the BL33 image in the `fip` image by defining this flag to `no`. 5. C Library diff --git a/docs/rt-svc-writers-guide.md b/docs/rt-svc-writers-guide.md index 13f5310..947f4a5 100644 --- a/docs/rt-svc-writers-guide.md +++ b/docs/rt-svc-writers-guide.md @@ -19,7 +19,7 @@ ---------------- 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 @@ 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 @@ 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.... diff --git a/docs/trusted-board-boot.md b/docs/trusted-board-boot.md index cd999e5..40b1e10 100644 --- a/docs/trusted-board-boot.md +++ b/docs/trusted-board-boot.md @@ -66,18 +66,18 @@ * **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 @@ * 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 @@ 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 @@ 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. diff --git a/docs/user-guide.md b/docs/user-guide.md index b4ef37c..1cab61f 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -99,7 +99,7 @@ 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=/bin/aarch64-linux-gnu- \ @@ -109,11 +109,11 @@ 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 @@ 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=/ 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=/ in the build option, will @@ -184,7 +184,7 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 [--dump to show result] @@ -470,7 +470,7 @@ --------------------------- - Trusted Boot Firmware BL2: offset=0x88, size=0x81E8 file: 'build//debug/bl2.bin' - - EL3 Runtime Firmware BL3-1: offset=0x8270, size=0xC218 + - EL3 Runtime Firmware BL31: offset=0x8270, size=0xC218 file: 'build//debug/bl31.bin' --------------------------- Creating "fip.bin" @@ -482,7 +482,7 @@ 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 @@ --------------------------- - Trusted Boot Firmware BL2: offset=0x88, size=0x7240 file: 'build//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 @@ ### 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=/bin/aarch64-linux-gnu- \ BL33=/ \ @@ -566,19 +566,19 @@ * `build///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 @@ --data cluster0.cpu0="/"@0x80080000 \ -C bp.virtioblockdevice.image_path="/" -### 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 @@ --data cluster0.cpu0="/"@0x80080000 \ -C bp.virtioblockdevice.image_path="/" -### 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 @@ 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 diff --git a/include/common/bl_common.h b/include/common/bl_common.h index b7cb95a..0ec7a8d 100644 --- a/include/common/bl_common.h +++ b/include/common/bl_common.h @@ -245,14 +245,14 @@ * 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 { diff --git a/include/common/el3_common_macros.S b/include/common/el3_common_macros.S index 0514e2a..6f7136f 100644 --- a/include/common/el3_common_macros.S +++ b/include/common/el3_common_macros.S @@ -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 diff --git a/include/lib/cpus/aarch64/cpu_macros.S b/include/lib/cpus/aarch64/cpu_macros.S index 72c35fb..f34f078 100644 --- a/include/lib/cpus/aarch64/cpu_macros.S +++ b/include/lib/cpus/aarch64/cpu_macros.S @@ -46,7 +46,7 @@ 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 */ diff --git a/include/plat/arm/common/aarch64/arm_macros.S b/include/plat/arm/common/aarch64/arm_macros.S index eaaa62f..384bb51 100644 --- a/include/plat/arm/common/aarch64/arm_macros.S +++ b/include/plat/arm/common/aarch64/arm_macros.S @@ -57,7 +57,7 @@ /* --------------------------------------------- * 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 @@ /* ------------------------------------------------ * 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 * ------------------------------------------------ */ diff --git a/include/plat/arm/common/arm_def.h b/include/plat/arm/common/arm_def.h index 4a50c1c..b2db616 100644 --- a/include/plat/arm/common/arm_def.h +++ b/include/plat/arm/common/arm_def.h @@ -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, diff --git a/include/plat/arm/common/plat_arm.h b/include/plat/arm/common/plat_arm.h index 32c062d..3b6a04b 100644 --- a/include/plat/arm/common/plat_arm.h +++ b/include/plat/arm/common/plat_arm.h @@ -87,7 +87,7 @@ #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_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); diff --git a/include/plat/arm/css/common/aarch64/css_macros.S b/include/plat/arm/css/common/aarch64/css_macros.S index 9f18e09..9124fdc 100644 --- a/include/plat/arm/css/common/aarch64/css_macros.S +++ b/include/plat/arm/css/common/aarch64/css_macros.S @@ -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 * --------------------------------------------- */ diff --git a/include/plat/arm/css/common/css_def.h b/include/plat/arm/css/common/css_def.h index dcc7790..c900278 100644 --- a/include/plat/arm/css/common/css_def.h +++ b/include/plat/arm/css/common/css_def.h @@ -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 diff --git a/include/plat/common/common_def.h b/include/plat/common/common_def.h index 4175b14..744c22e 100644 --- a/include/plat/common/common_def.h +++ b/include/plat/common/common_def.h @@ -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 diff --git a/include/plat/common/platform.h b/include/plat/common/platform.h index b6a037f..c21f9ee 100644 --- a/include/plat/common/platform.h +++ b/include/plat/common/platform.h @@ -134,7 +134,7 @@ /* * 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 @@ /* * 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_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 @@ 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 @@ 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 @@ 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 @@ 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 **); diff --git a/make_helpers/tbbr/tbbr_tools.mk b/make_helpers/tbbr/tbbr_tools.mk index 9b47886..e934d72 100644 --- a/make_helpers/tbbr/tbbr_tools.mk +++ b/make_helpers/tbbr/tbbr_tools.mk @@ -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) diff --git a/plat/arm/board/fvp/include/plat_macros.S b/plat/arm/board/fvp/include/plat_macros.S index 2ed0d85..2117843 100644 --- a/plat/arm/board/fvp/include/plat_macros.S +++ b/plat/arm/board/fvp/include/plat_macros.S @@ -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 * --------------------------------------------- */ diff --git a/plat/arm/board/fvp/include/platform_def.h b/plat/arm/board/fvp/include/platform_def.h index e93418d..0d671dc 100644 --- a/plat/arm/board/fvp/include/platform_def.h +++ b/plat/arm/board/fvp/include/platform_def.h @@ -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) diff --git a/plat/arm/common/aarch64/arm_common.c b/plat/arm/common/aarch64/arm_common.c index 4264183..d42009d 100644 --- a/plat/arm/common/aarch64/arm_common.c +++ b/plat/arm/common/aarch64/arm_common.c @@ -109,7 +109,7 @@ { /* * 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; } diff --git a/plat/arm/common/arm_bl2_setup.c b/plat/arm/common/arm_bl2_setup.c index 0ee1b0d..97c2bca 100644 --- a/plat/arm/common/arm_bl2_setup.c +++ b/plat/arm/common/arm_bl2_setup.c @@ -64,7 +64,7 @@ /******************************************************************************* * 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 @@ /* * 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 @@ 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 @@ 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 @@ } /******************************************************************************* - * 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 @@ /******************************************************************************* - * 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 @@ } /******************************************************************************* - * 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, diff --git a/plat/arm/common/arm_bl31_setup.c b/plat/arm/common/arm_bl31_setup.c index a7c2f7d..6c58ff1 100644 --- a/plat/arm/common/arm_bl31_setup.c +++ b/plat/arm/common/arm_bl31_setup.c @@ -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 @@ /******************************************************************************* * 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 @@ } /******************************************************************************* - * 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 @@ 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 @@ 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 @@ 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 @@ } /******************************************************************************* - * 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 @@ } /******************************************************************************* - * 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) diff --git a/plat/arm/common/tsp/arm_tsp_setup.c b/plat/arm/common/tsp/arm_tsp_setup.c index 3631c03..2a67fd1 100644 --- a/plat/arm/common/tsp/arm_tsp_setup.c +++ b/plat/arm/common/tsp/arm_tsp_setup.c @@ -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. diff --git a/plat/arm/css/common/css_common.mk b/plat/arm/css/common/css_common.mk index 8fcfbe5..aabcb46 100644 --- a/plat/arm/css/common/css_common.mk +++ b/plat/arm/css/common/css_common.mk @@ -56,7 +56,7 @@ 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 diff --git a/services/std_svc/psci/psci_entry.S b/services/std_svc/psci/psci_entry.S index 73c3377..5f4f91c 100644 --- a/services/std_svc/psci/psci_entry.S +++ b/services/std_svc/psci/psci_entry.S @@ -48,7 +48,7 @@ * 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. diff --git a/tools/fip_create/fip_create.c b/tools/fip_create/fip_create.c index 5bb716e..f0d0791 100644 --- a/tools/fip_create/fip_create.c +++ b/tools/fip_create/fip_create.c @@ -67,11 +67,11 @@ "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,