build: restrict usage of CTX_INCLUDE_EL2_REGS
CTX_INCLUDE_EL2_REGS is used to save/restore EL2 registers and
it should be only used when there is SPMD or RME enabled.
Make CTX_INCLUDE_EL2_REGS an internal macro and remove
from documentation.
Signed-off-by: Govindraj Raja <govindraj.raja@arm.com>
Change-Id: I6a70edfd88163423ff0482de094601cf794246d6
diff --git a/docs/components/secure-partition-manager.rst b/docs/components/secure-partition-manager.rst
index cd439ad..f0caf89 100644
--- a/docs/components/secure-partition-manager.rst
+++ b/docs/components/secure-partition-manager.rst
@@ -150,9 +150,6 @@
at EL3.
- If neither ``SPMD_SPM_AT_SEL2`` or ``SPMC_AT_EL3`` are enabled the SPMC
exception level is set to S-EL1.
-- **CTX_INCLUDE_EL2_REGS**: this option permits saving (resp.
- restoring) the EL2 system register context before entering (resp.
- after leaving) the SPMC. It is mandatorily enabled when
``SPMD_SPM_AT_SEL2`` is enabled. The context save/restore routine
and exhaustive list of registers is visible at `[4]`_.
- **SP_LAYOUT_FILE**: this option specifies a text description file
@@ -161,16 +158,16 @@
is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple
secure partitions are to be loaded by BL2 on behalf of the SPMC.
-+---------------+----------------------+------------------+-------------+
-| | CTX_INCLUDE_EL2_REGS | SPMD_SPM_AT_SEL2 | SPMC_AT_EL3 |
-+---------------+----------------------+------------------+-------------+
-| SPMC at S-EL1 | 0 | 0 | 0 |
-+---------------+----------------------+------------------+-------------+
-| SPMC at S-EL2 | 1 | 1 (default when | 0 |
-| | | SPD=spmd) | |
-+---------------+----------------------+------------------+-------------+
-| SPMC at EL3 | 0 | 0 | 1 |
-+---------------+----------------------+------------------+-------------+
++---------------+------------------+-------------+-------------------------+
+| | SPMD_SPM_AT_SEL2 | SPMC_AT_EL3 | CTX_INCLUDE_EL2_REGS(*) |
++---------------+------------------+-------------+-------------------------+
+| SPMC at S-EL1 | 0 | 0 | 0 |
++---------------+------------------+-------------+-------------------------+
+| SPMC at S-EL2 | 1 (default when | 0 | 1 |
+| | SPD=spmd) | | |
++---------------+------------------+-------------+-------------------------+
+| SPMC at EL3 | 0 | 1 | 0 |
++---------------+------------------+-------------+-------------------------+
Other combinations of such build options either break the build or are not
supported.
@@ -181,9 +178,9 @@
stack.
- When ``SPMD_SPM_AT_SEL2=1``, the reference software stack assumes enablement
of FEAT_PAuth, FEAT_BTI and FEAT_MTE architecture extensions.
-- The ``CTX_INCLUDE_EL2_REGS`` option provides the generic support for
- barely saving/restoring EL2 registers from an Arm arch perspective. As such
- it is decoupled from the ``SPD=spmd`` option.
+- ``(*) CTX_INCLUDE_EL2_REGS``, this flag is |TF-A| internal and informational
+ in this table. When set, it provides the generic support for saving/restoring
+ EL2 registers required when S-EL2 firmware is present.
- BL32 option is re-purposed to specify the SPMC image. It can specify either
the Hafnium binary path (built for the secure world) or the path to a TEE
binary implementing FF-A interfaces.
@@ -212,7 +209,6 @@
CROSS_COMPILE=aarch64-none-elf- \
PLAT=fvp \
SPD=spmd \
- CTX_INCLUDE_EL2_REGS=1 \
ARM_ARCH_MINOR=5 \
BRANCH_PROTECTION=1 \
CTX_INCLUDE_PAUTH_REGS=1 \
@@ -230,7 +226,6 @@
CROSS_COMPILE=aarch64-none-elf- \
PLAT=fvp \
SPD=spmd \
- CTX_INCLUDE_EL2_REGS=1 \
ARM_ARCH_MINOR=5 \
BRANCH_PROTECTION=1 \
CTX_INCLUDE_PAUTH_REGS=1 \
diff --git a/docs/getting_started/build-internals.rst b/docs/getting_started/build-internals.rst
new file mode 100644
index 0000000..a015d71
--- /dev/null
+++ b/docs/getting_started/build-internals.rst
@@ -0,0 +1,14 @@
+Internal Build Options
+======================
+
+|TF-A| internally uses certain options that are not exposed directly through
+:ref:`build-options <build options>` but enabled or disabled indirectly and
+depends on certain options to be enabled or disabled.
+
+.. _build_options_internal:
+
+- ``CTX_INCLUDE_EL2_REGS``: This boolean option provides context save/restore
+ operations when entering/exiting an EL2 execution context. This is of primary
+ interest when Armv8.4-SecEL2 or RME extension is implemented.
+ Default is 0 (disabled). This option will be set to 1 (enabled) when ``SPD=spmd``
+ and ``SPMD_SPM_AT_SEL2`` is set or when ``ENABLE_RME`` is set to 1 (enabled).
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index 402de13..7cd9b2b 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -164,12 +164,6 @@
is on hardware that does not implement AArch32, or at least not at EL1 and
higher ELs). Default value is 1.
-- ``CTX_INCLUDE_EL2_REGS`` : This boolean option provides context save/restore
- operations when entering/exiting an EL2 execution context. This is of primary
- interest when Armv8.4-SecEL2 extension is implemented. Default is 0 (disabled).
- This option must be equal to 1 (enabled) when ``SPD=spmd`` and
- ``SPMD_SPM_AT_SEL2`` is set.
-
- ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP
registers to be included when saving and restoring the CPU context. Default
is 0.
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index 3fbf48d..5ebabea 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -10,6 +10,7 @@
initial-build
tools-build
build-options
+ build-internals
image-terminology
porting-guide
psci-lib-integration-guide