From 641571c7287bcb72c10f722416b6514c87dbab54 Mon Sep 17 00:00:00 2001
From: Andre Przywara <andre.przywara@arm.com>
Date: Thu, 23 Nov 2023 16:40:13 +0000
Subject: [PATCH] docs(cpufeat): clarify description of FEATURE_DETECTION macro
The current documentation of the FEATURE_DETECTION build option seems
to suggest that this macro enables the dynamic runtime checking of
features, although this is done regardless of this debug feature.
FEATURE_DETECTION just adds the detect_arch_features() function to the
build and calls it early on, plus it enables the CPU errata order
checking.
Simplify the description of the FEATURE_DETECTION macro to make this
clear, and move the dynamic feature detection description into a
separate section, before all the specific ENABLE_FEAT_xxx explanations.
This also renames all mentioning of:
"... to align with the FEATURE_DETECTIION mechanism ..."
with:
"... to align with the ENABLE_FEAT mechanism ..."
in the description of each feature.
Change-Id: I5f4dd2d1e43bd440687b7cee551d02ec853d4e23
Signed-off-by: Andre Przywara <andre.przywara@arm.com>
---
docs/getting_started/build-options.rst | 137 +++++++++++++------------
1 file changed, 69 insertions(+), 68 deletions(-)
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index b85992402..077f59885 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -188,12 +188,12 @@ Common build options
- ``CTX_INCLUDE_NEVE_REGS``: Numeric value, when set will cause the Armv8.4-NV
registers to be saved/restored when entering/exiting an EL2 execution
context. This flag can take values 0 to 2, to align with the
- ``FEATURE_DETECTION`` mechanism. Default value is 0.
+ ``ENABLE_FEAT`` mechanism. Default value is 0.
- ``CTX_INCLUDE_PAUTH_REGS``: Numeric value to enable the Pointer
Authentication for Secure world. This will cause the ARMv8.3-PAuth registers
to be included when saving and restoring the CPU context as part of world
- switch. This flag can take values 0 to 2, to align with ``FEATURE_DETECTION``
+ switch. This flag can take values 0 to 2, to align with ``ENABLE_FEAT``
mechanism. Default value is 0.
Note that Pointer Authentication is enabled for Non-secure world irrespective
@@ -214,7 +214,7 @@ Common build options
- ``DISABLE_MTPMU``: Numeric option to disable ``FEAT_MTPMU`` (Multi Threaded
PMU). ``FEAT_MTPMU`` is an optional feature available on Armv8.6 onwards.
- This flag can take values 0 to 2, to align with the ``FEATURE_DETECTION``
+ This flag can take values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default is ``0``.
- ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted
@@ -261,9 +261,35 @@ Common build options
builds, but this behaviour can be overridden in each platform's Makefile or
in the build command line.
+- ``ENABLE_FEAT``
+ The Arm architecture defines several architecture extension features,
+ named FEAT_xxx in the architecure manual. Some of those features require
+ setup code in higher exception levels, other features might be used by TF-A
+ code itself.
+ Most of the feature flags defined in the TF-A build system permit to take
+ the values 0, 1 or 2, with the following meaning:
+
+ ::
+
+ ENABLE_FEAT_* = 0: Feature is disabled statically at compile time.
+ ENABLE_FEAT_* = 1: Feature is enabled unconditionally at compile time.
+ ENABLE_FEAT_* = 2: Feature is enabled, but checked at runtime.
+
+ When setting the flag to 0, the feature is disabled during compilation,
+ and the compiler's optimisation stage and the linker will try to remove
+ as much of this code as possible.
+ If it is defined to 1, the code will use the feature unconditionally, so the
+ CPU is expected to support that feature. The FEATURE_DETECTION debug
+ feature, if enabled, will verify this.
+ If the feature flag is set to 2, support for the feature will be compiled
+ in, but its existence will be checked at runtime, so it works on CPUs with
+ or without the feature. This is mostly useful for platforms which either
+ support multiple different CPUs, or where the CPU is configured at runtime,
+ like in emulators.
+
- ``ENABLE_FEAT_AMU``: Numeric value to enable Activity Monitor Unit
extensions. This flag can take the values 0 to 2, to align with the
- ``FEATURE_DETECTION`` mechanism. This is an optional architectural feature
+ ``ENABLE_FEAT`` mechanism. This is an optional architectural feature
available on v8.4 onwards. Some v8.2 implementations also implement an AMU
and this option can be used to enable this feature on those systems as well.
This flag can take the values 0 to 2, the default is 0.
@@ -271,52 +297,52 @@ Common build options
- ``ENABLE_FEAT_AMUv1p1``: Numeric value to enable the ``FEAT_AMUv1p1``
extension. ``FEAT_AMUv1p1`` is an optional feature available on Arm v8.6
onwards. This flag can take the values 0 to 2, to align with the
- ``FEATURE_DETECTION`` mechanism. Default value is ``0``.
+ ``ENABLE_FEAT`` mechanism. Default value is ``0``.
- ``ENABLE_FEAT_CSV2_2``: Numeric value to enable the ``FEAT_CSV2_2``
extension. It allows access to the SCXTNUM_EL2 (Software Context Number)
register during EL2 context save/restore operations. ``FEAT_CSV2_2`` is an
optional feature available on Arm v8.0 onwards. This flag can take values
- 0 to 2, to align with the ``FEATURE_DETECTION`` mechanism.
+ 0 to 2, to align with the ``ENABLE_FEAT`` mechanism.
Default value is ``0``.
- ``ENABLE_FEAT_DIT``: Numeric value to enable ``FEAT_DIT`` (Data Independent
Timing) extension. It allows setting the ``DIT`` bit of PSTATE in EL3.
``FEAT_DIT`` is a mandatory architectural feature and is enabled from v8.4
and upwards. This flag can take the values 0 to 2, to align with the
- ``FEATURE_DETECTION`` mechanism. Default value is ``0``.
+ ``ENABLE_FEAT`` mechanism. Default value is ``0``.
- ``ENABLE_FEAT_ECV``: Numeric value to enable support for the Enhanced Counter
Virtualization feature, allowing for access to the CNTPOFF_EL2 (Counter-timer
Physical Offset register) during EL2 to EL3 context save/restore operations.
Its a mandatory architectural feature and is enabled from v8.6 and upwards.
- This flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_FGT``: Numeric value to enable support for FGT (Fine Grain Traps)
feature allowing for access to the HDFGRTR_EL2 (Hypervisor Debug Fine-Grained
Read Trap Register) during EL2 to EL3 context save/restore operations.
Its a mandatory architectural feature and is enabled from v8.6 and upwards.
- This flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_HCX``: Numeric value to set the bit SCR_EL3.HXEn in EL3 to
allow access to HCRX_EL2 (extended hypervisor control register) from EL2 as
well as adding HCRX_EL2 to the EL2 context save/restore operations. Its a
mandatory architectural feature and is enabled from v8.7 and upwards. This
- flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ flag can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_MTE``: Numeric value to enable Memory Tagging Extension
if the platform wants to use this feature in the Secure world and MTE is
enabled at ELX. This flag can take values 0 to 2, to align with the
- ``FEATURE_DETECTION`` mechanism. Default value is ``0``.
+ ``ENABLE_FEAT`` mechanism. Default value is ``0``.
- ``ENABLE_FEAT_MTE_PERM``: Numeric value to enable support for
``FEAT_MTE_PERM``, which introduces Allocation tag access permission to
memory region attributes. ``FEAT_MTE_PERM`` is a optional architectural
feature available from v8.9 and upwards. This flag can take the values 0 to
- 2, to align with the ``FEATURE_DETECTION`` mechanism. Default value is
+ 2, to align with the ``ENABLE_FEAT`` mechanism. Default value is
``0``.
- ``ENABLE_FEAT_PAN``: Numeric value to enable the ``FEAT_PAN`` (Privileged
@@ -324,17 +350,17 @@ Common build options
permission fault for any privileged data access from EL1/EL2 to virtual
memory address, accessible at EL0, provided (HCR_EL2.E2H=1). It is a
mandatory architectural feature and is enabled from v8.1 and upwards. This
- flag can take values 0 to 2, to align with the ``FEATURE_DETECTION``
+ flag can take values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_RNG``: Numeric value to enable the ``FEAT_RNG`` extension.
``FEAT_RNG`` is an optional feature available on Arm v8.5 onwards. This
- flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ flag can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_RNG_TRAP``: Numeric value to enable the ``FEAT_RNG_TRAP``
extension. This feature is only supported in AArch64 state. This flag can
- take values 0 to 2, to align with the ``FEATURE_DETECTION`` mechanism.
+ take values 0 to 2, to align with the ``ENABLE_FEAT`` mechanism.
Default value is ``0``. ``FEAT_RNG_TRAP`` is an optional feature from
Armv8.5 onwards.
@@ -346,13 +372,13 @@ Common build options
- ``ENABLE_FEAT_SEL2``: Numeric value to enable the ``FEAT_SEL2`` (Secure EL2)
extension. ``FEAT_SEL2`` is a mandatory feature available on Arm v8.4.
- This flag can take values 0 to 2, to align with the ``FEATURE_DETECTION``
+ This flag can take values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default is ``0``.
- ``ENABLE_FEAT_TWED``: Numeric value to enable the ``FEAT_TWED`` (Delayed
trapping of WFE Instruction) extension. ``FEAT_TWED`` is a optional feature
available on Arm v8.6. This flag can take values 0 to 2, to align with the
- ``FEATURE_DETECTION`` mechanism. Default is ``0``.
+ ``ENABLE_FEAT`` mechanism. Default is ``0``.
When ``ENABLE_FEAT_TWED`` is set to ``1``, WFE instruction trapping gets
delayed by the amount of value in ``TWED_DELAY``.
@@ -361,40 +387,40 @@ Common build options
Host Extensions) extension. It allows access to CONTEXTIDR_EL2 register
during EL2 context save/restore operations.``FEAT_VHE`` is a mandatory
architectural feature and is enabled from v8.1 and upwards. It can take
- values 0 to 2, to align with the ``FEATURE_DETECTION`` mechanism.
+ values 0 to 2, to align with the ``ENABLE_FEAT`` mechanism.
Default value is ``0``.
- ``ENABLE_FEAT_TCR2``: Numeric value to set the bit SCR_EL3.ENTCR2 in EL3 to
allow access to TCR2_EL2 (extended translation control) from EL2 as
well as adding TCR2_EL2 to the EL2 context save/restore operations. Its a
mandatory architectural feature and is enabled from v8.9 and upwards. This
- flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ flag can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_S2PIE``: Numeric value to enable support for FEAT_S2PIE
at EL2 and below, and context switch relevant registers. This flag
- can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_S1PIE``: Numeric value to enable support for FEAT_S1PIE
at EL2 and below, and context switch relevant registers. This flag
- can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_S2POE``: Numeric value to enable support for FEAT_S2POE
at EL2 and below, and context switch relevant registers. This flag
- can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_S1POE``: Numeric value to enable support for FEAT_S1POE
at EL2 and below, and context switch relevant registers. This flag
- can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default value is ``0``.
- ``ENABLE_FEAT_GCS``: Numeric value to set the bit SCR_EL3.GCSEn in EL3 to
allow use of Guarded Control Stack from EL2 as well as adding the GCS
registers to the EL2 context save/restore operations. This flag can take
- the values 0 to 2, to align with the ``FEATURE_DETECTION`` mechanism.
+ the values 0 to 2, to align with the ``ENABLE_FEAT`` mechanism.
Default value is ``0``.
- ``ENABLE_LTO``: Boolean option to enable Link Time Optimization (LTO)
@@ -407,7 +433,7 @@ Common build options
various ELs can assign themselves to desired partition to control their
performance aspects.
- This flag can take values 0 to 2, to align with the ``FEATURE_DETECTION``
+ This flag can take values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. When this option is set to ``1`` or ``2``, EL3 allows lower ELs to
access their own MPAM registers without trapping into EL3. This option
doesn't make use of partitioning in EL3, however. Platform initialisation
@@ -448,7 +474,7 @@ Common build options
- ``ENABLE_SPE_FOR_NS`` : Numeric value to enable Statistical Profiling
extensions. This is an optional architectural feature for AArch64.
- This flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. The default is 2 but is automatically disabled when the target
architecture is AArch32.
@@ -462,7 +488,7 @@ Common build options
compatible with the ``CTX_INCLUDE_FPREGS`` build option, and will raise an
assert on platforms where SVE is implemented and ``ENABLE_SVE_FOR_NS``
enabled. This flag can take the values 0 to 2, to align with the
- ``FEATURE_DETECTION`` mechanism. At this time, this build option cannot be
+ ``ENABLE_FEAT`` mechanism. At this time, this build option cannot be
used on systems that have SPM_MM enabled. The default is 1.
- ``ENABLE_SVE_FOR_SWD``: Boolean option to enable SVE for the Secure world.
@@ -1078,26 +1104,26 @@ Common build options
- ``ENABLE_BRBE_FOR_NS``: Numeric value to enable access to the branch record
buffer registers from NS ELs when FEAT_BRBE is implemented. BRBE is an
optional architectural feature for AArch64. This flag can take the values
- 0 to 2, to align with the ``FEATURE_DETECTION`` mechanism. The default is 0
+ 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. The default is 0
and it is automatically disabled when the target architecture is AArch32.
- ``ENABLE_TRBE_FOR_NS``: Numeric value to enable access of trace buffer
control registers from NS ELs, NS-EL2 or NS-EL1(when NS-EL2 is implemented
but unused) when FEAT_TRBE is implemented. TRBE is an optional architectural
feature for AArch64. This flag can take the values 0 to 2, to align with the
- ``FEATURE_DETECTION`` mechanism. The default is 0 and it is automatically
+ ``ENABLE_FEAT`` mechanism. The default is 0 and it is automatically
disabled when the target architecture is AArch32.
- ``ENABLE_SYS_REG_TRACE_FOR_NS``: Numeric value to enable trace system
registers access from NS ELs, NS-EL2 or NS-EL1 (when NS-EL2 is implemented
but unused). This feature is available if trace unit such as ETMv4.x, and
ETE(extending ETM feature) is implemented. This flag can take the values
- 0 to 2, to align with the ``FEATURE_DETECTION`` mechanism. The default is 0.
+ 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. The default is 0.
- ``ENABLE_TRF_FOR_NS``: Numeric value to enable trace filter control registers
access from NS ELs, NS-EL2 or NS-EL1 (when NS-EL2 is implemented but unused),
if FEAT_TRF is implemented. This flag can take the values 0 to 2, to align
- with the ``FEATURE_DETECTION`` mechanism. This flag is disabled by default.
+ with the ``ENABLE_FEAT`` mechanism. This flag is disabled by default.
- ``CONDITIONAL_CMO``: Boolean option to enable call to platform-defined routine
``plat_can_cmo`` which will return zero if cache management operations should
@@ -1225,7 +1251,7 @@ Common build options
- ``ENABLE_RME``: Numeric value to enable support for the ARMv9 Realm
Management Extension. This flag can take the values 0 to 2, to align with
- the ``FEATURE_DETECTION`` mechanism. Default value is 0.
+ the ``ENABLE_FEAT`` mechanism. Default value is 0.
- ``ENABLE_SME_FOR_NS``: Numeric value to enable Scalable Matrix Extension
(SME), SVE, and FPU/SIMD for the non-secure world only. These features share
@@ -1235,7 +1261,7 @@ Common build options
superset of SVE. SME is an optional architectural feature for AArch64.
At this time, this build option cannot be used on systems that have
SPD=spmd/SPM_MM and atempting to build with this option will fail.
- This flag can take the values 0 to 2, to align with the ``FEATURE_DETECTION``
+ This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT``
mechanism. Default is 0.
- ``ENABLE_SME2_FOR_NS``: Numeric value to enable Scalable Matrix Extension
@@ -1243,7 +1269,7 @@ Common build options
architectural feature for AArch64.
This should be set along with ENABLE_SME_FOR_NS=1, if not, the default SME
accesses will still be trapped. This flag can take the values 0 to 2, to
- align with the ``FEATURE_DETECTION`` mechanism. Default is 0.
+ align with the ``ENABLE_FEAT`` mechanism. Default is 0.
- ``ENABLE_SME_FOR_SWD``: Boolean option to enable the Scalable Matrix
Extension for secure world. Used along with SVE and FPU/SIMD.
@@ -1257,41 +1283,16 @@ Common build options
must not be used if ``SPMC_AT_EL3`` is enabled.
- ``FEATURE_DETECTION``: Boolean option to enable the architectural features
- detection mechanism. It detects whether the Architectural features enabled
- through feature specific build flags are supported by the PE or not by
- validating them either at boot phase or at runtime based on the value
- possessed by the feature flag (0 to 2) and report error messages at an early
- stage. This flag will also enable errata ordering checking for ``DEBUG``
- builds.
+ verification mechanism. This is a debug feature that compares the
+ architectural features enabled through the feature specific build flags
+ (ENABLE_FEAT_xxx) with the features actually available on the CPU running,
+ and reports any discrepancies.
+ This flag will also enable errata ordering checking for ``DEBUG`` builds.
- This prevents and benefits us from EL3 runtime exceptions during context save
- and restore routines guarded by these build flags. Henceforth validating them
- before their usage provides more control on the actions taken under them.
-
- The mechanism permits the build flags to take values 0, 1 or 2 and
- evaluates them accordingly.
-
- Lets consider ``ENABLE_FEAT_HCX``, build flag for ``FEAT_HCX`` as an example:
-
- ::
-
- ENABLE_FEAT_HCX = 0: Feature disabled statically at compile time.
- ENABLE_FEAT_HCX = 1: Feature Enabled and the flag is validated at boottime.
- ENABLE_FEAT_HCX = 2: Feature Enabled and the flag is validated at runtime.
-
- In the above example, if the feature build flag, ``ENABLE_FEAT_HCX`` set to
- 0, feature is disabled statically during compilation. If it is defined as 1,
- feature is validated, wherein FEAT_HCX is detected at boot time. In case not
- implemented by the PE, a hard panic is generated. Finally, if the flag is set
- to 2, feature is validated at runtime.
-
- Note that the entire implementation is divided into two phases, wherein as
- as part of phase-1 we are supporting the values 0,1. Value 2 is currently not
- supported and is planned to be handled explicilty in phase-2 implementation.
-
- ``FEATURE_DETECTION`` macro is disabled by default. Platforms can explicitly
- make use of this by mechanism, by enabling it to validate whether they have
- set their build flags properly at an early phase.
+ It is expected that this feature is only used for flexible platforms like
+ software emulators, or for hardware platforms at bringup time, to verify
+ that the configured feature set matches the CPU.
+ The ``FEATURE_DETECTION`` macro is disabled by default.
- ``PSA_CRYPTO``: Boolean option for enabling MbedTLS PSA crypto APIs support.
The platform will use PSA compliant Crypto APIs during authentication and