refactor(build): distinguish BL2 as TF-A entry point and BL2 running at EL3
BL2_AT_EL3 is an overloaded macro which has two uses:
1. When BL2 is entry point into TF-A(no BL1)
2. When BL2 is running at EL3 exception level
These two scenarios are not exactly same even though first implicitly
means second to be true. To distinguish between these two use cases we
introduce new macros.
BL2_AT_EL3 is renamed to RESET_TO_BL2 to better convey both 1. and 2.
Additional macro BL2_RUNS_AT_EL3 is added to cover all scenarious where
BL2 runs at EL3 (including four world systems).
BREAKING CHANGE: BL2_AT_EL3 renamed to RESET_TO_BL2 across the
repository.
Change-Id: I477e1d0f843b44b799c216670e028fcb3509fb72
Signed-off-by: Arvind Ram Prakash <arvind.ramprakash@arm.com>
Signed-off-by: Maksims Svecovs <maksims.svecovs@arm.com>
diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst
index f08608c..97f3550 100644
--- a/docs/design/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -25,7 +25,6 @@
:ref:`Translation (XLAT) Tables Library`.
TF-A can be built to support either AArch64 or AArch32 execution state.
-
.. note::
The descriptions in this chapter are for the Arm TrustZone architecture.
@@ -484,8 +483,8 @@
as its only purpose is to ensure TF-A BL2 is entered at S-EL1. To avoid
this waste, a special mode enables BL2 to execute at EL3, which allows
a non-TF-A Boot ROM to load and jump directly to BL2. This mode is selected
-when the build flag BL2_AT_EL3 is enabled. The main differences in this
-mode are:
+when the build flag RESET_TO_BL2 is enabled.
+The main differences in this mode are:
#. BL2 includes the reset code and the mailbox mechanism to differentiate
cold boot and warm boot. It runs at EL3 doing the arch
@@ -2752,7 +2751,7 @@
--------------
-*Copyright (c) 2013-2022, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2013-2023, Arm Limited and Contributors. All rights reserved.*
.. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
.. _SMCCC: https://developer.arm.com/docs/den0028/latest
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index a285d31..0dc8b71 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -52,8 +52,14 @@
- ``BL2U``: This is an optional build option which specifies the path to
BL2U image. In this case, the BL2U in TF-A will not be built.
-- ``BL2_AT_EL3``: This is an optional build option that enables the use of
- BL2 at EL3 execution level.
+- ``RESET_TO_BL2``: Boolean option to enable BL2 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 BL2 entrypoint).
+ The default value is 0.
+
+- ``BL2_RUNS_AT_EL3``: This is an implicit flag to denote that BL2 runs at EL3.
+ While it is explicitly set to 1 when RESET_TO_BL2 is set to 1 it can also be
+ true in a 4-world system where RESET_TO_BL2 is 0.
- ``BL2_ENABLE_SP_LOAD``: Boolean option to enable loading SP packages from the
FIP. Automatically enabled if ``SP_LAYOUT_FILE`` is provided.
@@ -61,8 +67,8 @@
- ``BL2_IN_XIP_MEM``: In some use-cases BL2 will be stored in eXecute In Place
(XIP) memory, like BL1. In these use-cases, it is necessary to initialize
the RW sections in RAM, while leaving the RO sections in place. This option
- enable this use-case. For now, this option is only supported when BL2_AT_EL3
- is set to '1'.
+ enable this use-case. For now, this option is only supported
+ when RESET_TO_BL2 is set to '1'.
- ``BL31``: This is an optional build option which specifies the path to
BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not
@@ -377,8 +383,8 @@
- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE)
support within generic code in TF-A. This option is currently only supported
- in BL2_AT_EL3, BL31, and BL32 (TSP) for AARCH64 binaries, and in BL32
- (SP_min) for AARCH32. Default is 0.
+ in BL2, BL31, and BL32 (TSP) for AARCH64 binaries, and
+ in BL32 (SP_min) for AARCH32. Default is 0.
- ``ENABLE_PMF``: Boolean option to enable support for optional Performance
Measurement Framework(PMF). Default is 0.
@@ -1199,7 +1205,7 @@
--------------
-*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2023, Arm Limited. All rights reserved.*
.. _DEN0115: https://developer.arm.com/docs/den0115/latest
.. _PSA FW update specification: https://developer.arm.com/documentation/den0118/a/
diff --git a/docs/plat/arm/corstone1000/index.rst b/docs/plat/arm/corstone1000/index.rst
index b889b7f..dc626e1 100644
--- a/docs/plat/arm/corstone1000/index.rst
+++ b/docs/plat/arm/corstone1000/index.rst
@@ -47,7 +47,7 @@
ARCH=aarch64 \
TARGET_PLATFORM=<fpga or fvp> \
ENABLE_PIE=1 \
- BL2_AT_EL3=1 \
+ RESET_TO_BL2=1 \
CREATE_KEYS=1 \
GENERATE_COT=1 \
TRUSTED_BOARD_BOOT=1 \
@@ -58,4 +58,4 @@
BL33=<path to u-boot binary> \
bl2
-*Copyright (c) 2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2021-2023, Arm Limited. All rights reserved.*
diff --git a/docs/plat/stm32mp1.rst b/docs/plat/stm32mp1.rst
index 23ea25a..a983606 100644
--- a/docs/plat/stm32mp1.rst
+++ b/docs/plat/stm32mp1.rst
@@ -107,11 +107,11 @@
Boot sequence
~~~~~~~~~~~~~
-ROM code -> BL2 (compiled with BL2_AT_EL3) -> BL32 (SP_min) -> BL33 (U-Boot)
+ROM code -> BL2(compiled with RESET_TO_BL2) -> BL32(SP_min)-> BL33(U-Boot)
or if Op-TEE is used:
-ROM code -> BL2 (compiled with BL2_AT_EL3) -> OP-TEE -> BL33 (U-Boot)
+ROM code -> BL2 (compiled with RESET_TO_BL2) -> OP-TEE -> BL33 (U-Boot)
Build Instructions