mirror of
https://github.com/ARM-software/arm-trusted-firmware.git
synced 2025-04-16 01:24:27 +00:00
docs: add a section for experimental build options
A number of features are marked experimental in the build system through makefiles but there wasn't an explicit document to list them. Added a dedicated experimental build options section and moved existing experimental build option descriptions in this section. Restoring the change from [1] removing the experimental flag on the EL3 SPMC (this has been lost in rebasing a later change). [1] https://review.trustedfirmware.org/c/TF-A/trusted-firmware-a/+/24713 Signed-off-by: Olivier Deprez <olivier.deprez@arm.com> Change-Id: I2c458c6857c347114b265404e8b9ede9ac588463
This commit is contained in:
Olivier Deprez
parent
f15f360cfc
commit
48856003bf
2 changed files with 134 additions and 107 deletions
|
|
@ -108,6 +108,28 @@ Current features
|
|||
|
||||
- Position-Independent Executable (PIE) support.
|
||||
|
||||
Experimental features
|
||||
---------------------
|
||||
|
||||
A feature is considered experimental when still in development or isn't known
|
||||
to the TF-A team as widely deployed or proven on end products. It is generally
|
||||
advised such options aren't pulled into real deployments, or done with the
|
||||
appropriate level of supplementary integration testing.
|
||||
|
||||
A feature is no longer considered experimental when it is generally agreed
|
||||
the said feature has reached a level of maturity and quality comparable to
|
||||
other features that have been integrated into products.
|
||||
|
||||
Experimental build options are found in following section
|
||||
:ref:`build_options_experimental`. Their use through the build emits a warning
|
||||
message.
|
||||
|
||||
Additionally the following libraries are marked experimental when included
|
||||
in a platform:
|
||||
|
||||
- MPU translation library ``lib/xlat_mpu``
|
||||
- RSS comms driver ``drivers/arm/rss``
|
||||
|
||||
Still to come
|
||||
-------------
|
||||
|
||||
|
|
|
|||
|
|
@ -436,40 +436,12 @@ Common build options
|
|||
be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in
|
||||
software.
|
||||
|
||||
- ``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. This is currently
|
||||
an experimental feature.
|
||||
|
||||
- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime
|
||||
instrumentation which injects timestamp collection points into TF-A to
|
||||
allow runtime performance to be measured. Currently, only PSCI is
|
||||
instrumented. Enabling this option enables the ``ENABLE_PMF`` build option
|
||||
as well. Default 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
|
||||
registers so are enabled together. Using this option without
|
||||
ENABLE_SME_FOR_SWD=1 will cause SME, SVE, and FPU/SIMD instructions in secure
|
||||
world to trap to EL3. Requires ``ENABLE_SVE_FOR_NS`` to be set as SME is a
|
||||
superset of SVE. SME is an optional architectural feature for AArch64
|
||||
and TF-A support is experimental. 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`` mechanism. Default is 0.
|
||||
|
||||
- ``ENABLE_SME2_FOR_NS``: Numeric value to enable Scalable Matrix Extension
|
||||
version 2 (SME2) for the non-secure world only. SME2 is an optional
|
||||
architectural feature for AArch64 and TF-A support is experimental.
|
||||
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.
|
||||
|
||||
- ``ENABLE_SME_FOR_SWD``: Boolean option to enable the Scalable Matrix
|
||||
Extension for secure world. Used along with SVE and FPU/SIMD.
|
||||
ENABLE_SME_FOR_NS and ENABLE_SVE_FOR_SWD must also be set to use this.
|
||||
This is experimental. Default is 0.
|
||||
|
||||
- ``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``
|
||||
|
|
@ -555,44 +527,6 @@ Common build options
|
|||
This feature is intended for testing purposes only, and is advisable to keep
|
||||
disabled for production images.
|
||||
|
||||
- ``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.
|
||||
|
||||
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, and is currently an
|
||||
experimental procedure. 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.
|
||||
|
||||
- ``FIP_NAME``: This is an optional build option which specifies the FIP
|
||||
filename for the ``fip`` target. Default is ``fip.bin``.
|
||||
|
||||
|
|
@ -730,15 +664,6 @@ Common build options
|
|||
|
||||
This option defaults to 0.
|
||||
|
||||
- ``DRTM_SUPPORT``: Boolean flag to enable support for Dynamic Root of Trust
|
||||
for Measurement (DRTM). This feature has trust dependency on BL31 for taking
|
||||
the measurements and recording them as per `PSA DRTM specification`_. For
|
||||
platforms which use BL2 to load/authenticate BL31 ``TRUSTED_BOARD_BOOT`` can
|
||||
be used and for the platforms which use ``RESET_TO_BL31`` platform owners
|
||||
should have mechanism to authenticate BL31. This is an experimental feature.
|
||||
|
||||
This option defaults to 0.
|
||||
|
||||
- ``MARCH_DIRECTIVE``: used to pass a -march option from the platform build
|
||||
options to the compiler. An example usage:
|
||||
|
||||
|
|
@ -894,7 +819,7 @@ Common build options
|
|||
Dispatcher option (``SPD=spmd``). When enabled (1) it indicates the SPMC
|
||||
component runs at the EL3 exception level. The default value is ``0`` (
|
||||
disabled). This configuration supports pre-Armv8.4 platforms (aka not
|
||||
implementing the ``FEAT_SEL2`` extension). This is an experimental feature.
|
||||
implementing the ``FEAT_SEL2`` extension).
|
||||
|
||||
- ``SPMC_AT_EL3_SEL0_SP`` : Boolean option to enable SEL0 SP load support when
|
||||
``SPMC_AT_EL3`` is enabled. The default value if ``0`` (disabled). This
|
||||
|
|
@ -914,12 +839,6 @@ Common build options
|
|||
support pre-Armv8.4 platforms (aka not implementing the ``FEAT_SEL2``
|
||||
extension).
|
||||
|
||||
- ``ENABLE_SPMD_LP`` : This boolean option is used jointly with the SPM
|
||||
Dispatcher option (``SPD=spmd``). When enabled (1) it indicates support
|
||||
for logical partitions in EL3, managed by the SPMD as defined in the FF-A
|
||||
1.2 specification. This flag is disabled by default. This flag must not be
|
||||
used if ``SPMC_AT_EL3`` is enabled. This is an experimental feature.
|
||||
|
||||
- ``SPM_MM`` : Boolean option to enable the Management Mode (MM)-based Secure
|
||||
Partition Manager (SPM) implementation. The default value is ``0``
|
||||
(disabled). This option cannot be enabled (``1``) when SPM Dispatcher is
|
||||
|
|
@ -945,11 +864,6 @@ Common build options
|
|||
hardware will limit the effective VL to the maximum physically supported
|
||||
VL.
|
||||
|
||||
- ``TRANSFER_LIST``: Setting this to ``1`` enables support for Firmware
|
||||
Handoff using Transfer List defined in `Firmware Handoff specification`_.
|
||||
This defaults to ``0``. Please note that this is an experimental feature
|
||||
based on Firmware Handoff specification v0.9.
|
||||
|
||||
- ``TRNG_SUPPORT``: Setting this to ``1`` enables support for True
|
||||
Random Number Generator Interface to BL31 image. This defaults to ``0``.
|
||||
|
||||
|
|
@ -1008,10 +922,6 @@ Common build options
|
|||
(Coherent memory region is included) or 0 (Coherent memory region is
|
||||
excluded). Default is 1.
|
||||
|
||||
- ``USE_DEBUGFS``: When set to 1 this option activates an EXPERIMENTAL feature
|
||||
exposing a virtual filesystem interface through BL31 as a SiP SMC function.
|
||||
Default is 0.
|
||||
|
||||
- ``ARM_IO_IN_DTB``: This flag determines whether to use IO based on the
|
||||
firmware configuration framework. This will move the io_policies into a
|
||||
configuration device tree, instead of static structure in the code base.
|
||||
|
|
@ -1185,13 +1095,6 @@ Common build options
|
|||
errata mitigation for platforms with a non-arm interconnect using the errata
|
||||
ABI. By default its disabled (``0``).
|
||||
|
||||
- ``PSA_CRYPTO``: Boolean option for enabling MbedTLS PSA crypto APIs support.
|
||||
The platform will use PSA compliant Crypto APIs during authentication and
|
||||
image measurement process by enabling this option. It uses APIs defined as
|
||||
per the `PSA Crypto API specification`_. This feature is only supported if
|
||||
using MbedTLS 3.x version. By default it is disabled (``0``), and this is an
|
||||
experimental feature.
|
||||
|
||||
- ``ENABLE_CONSOLE_GETC``: Boolean option to enable `getc()` feature in console
|
||||
driver(s). By default it is disabled (``0``) because it constitutes an attack
|
||||
vector into TF-A by potentially allowing an attacker to inject arbitrary data.
|
||||
|
|
@ -1288,8 +1191,118 @@ commands can be used:
|
|||
# Resume execution
|
||||
continue
|
||||
|
||||
.. _build_options_experimental:
|
||||
|
||||
Experimental build options
|
||||
---------------------------
|
||||
|
||||
Common build options
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- ``DRTM_SUPPORT``: Boolean flag to enable support for Dynamic Root of Trust
|
||||
for Measurement (DRTM). This feature has trust dependency on BL31 for taking
|
||||
the measurements and recording them as per `PSA DRTM specification`_. For
|
||||
platforms which use BL2 to load/authenticate BL31 ``TRUSTED_BOARD_BOOT`` can
|
||||
be used and for the platforms which use ``RESET_TO_BL31`` platform owners
|
||||
should have mechanism to authenticate BL31. This option defaults to 0.
|
||||
|
||||
- ``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.
|
||||
|
||||
- ``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
|
||||
registers so are enabled together. Using this option without
|
||||
ENABLE_SME_FOR_SWD=1 will cause SME, SVE, and FPU/SIMD instructions in secure
|
||||
world to trap to EL3. Requires ``ENABLE_SVE_FOR_NS`` to be set as SME is a
|
||||
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``
|
||||
mechanism. Default is 0.
|
||||
|
||||
- ``ENABLE_SME2_FOR_NS``: Numeric value to enable Scalable Matrix Extension
|
||||
version 2 (SME2) for the non-secure world only. SME2 is an optional
|
||||
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.
|
||||
|
||||
- ``ENABLE_SME_FOR_SWD``: Boolean option to enable the Scalable Matrix
|
||||
Extension for secure world. Used along with SVE and FPU/SIMD.
|
||||
ENABLE_SME_FOR_NS and ENABLE_SVE_FOR_SWD must also be set to use this.
|
||||
Default is 0.
|
||||
|
||||
- ``ENABLE_SPMD_LP`` : This boolean option is used jointly with the SPM
|
||||
Dispatcher option (``SPD=spmd``). When enabled (1) it indicates support
|
||||
for logical partitions in EL3, managed by the SPMD as defined in the
|
||||
FF-A v1.2 specification. This flag is disabled by default. This flag
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
- ``PSA_CRYPTO``: Boolean option for enabling MbedTLS PSA crypto APIs support.
|
||||
The platform will use PSA compliant Crypto APIs during authentication and
|
||||
image measurement process by enabling this option. It uses APIs defined as
|
||||
per the `PSA Crypto API specification`_. This feature is only supported if
|
||||
using MbedTLS 3.x version. It is disabled (``0``) by default.
|
||||
|
||||
- ``TRANSFER_LIST``: Setting this to ``1`` enables support for Firmware
|
||||
Handoff using Transfer List defined in `Firmware Handoff specification`_.
|
||||
This defaults to ``0``. Current implementation follows the Firmware Handoff
|
||||
specification v0.9.
|
||||
|
||||
- ``USE_DEBUGFS``: When set to 1 this option exposes a virtual filesystem
|
||||
interface through BL31 as a SiP SMC function.
|
||||
Default is disabled (0).
|
||||
|
||||
Firmware update options
|
||||
-----------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- ``PSA_FWU_SUPPORT``: Enable the firmware update mechanism as per the
|
||||
`PSA FW update specification`_. The default value is 0.
|
||||
PSA firmware update implementation has few limitations, such as:
|
||||
|
||||
- BL2 is not part of the protocol-updatable images. If BL2 needs to
|
||||
be updated, then it should be done through another platform-defined
|
||||
mechanism.
|
||||
|
||||
- It assumes the platform's hardware supports CRC32 instructions.
|
||||
|
||||
- ``NR_OF_FW_BANKS``: Define the number of firmware banks. This flag is used
|
||||
in defining the firmware update metadata structure. This flag is by default
|
||||
|
|
@ -1301,14 +1314,6 @@ Firmware update options
|
|||
This flag is used in defining the firmware update metadata structure. This
|
||||
flag is by default set to '1'.
|
||||
|
||||
- ``PSA_FWU_SUPPORT``: Enable the firmware update mechanism as per the
|
||||
`PSA FW update specification`_. The default value is 0, and this is an
|
||||
experimental feature.
|
||||
PSA firmware update implementation has some limitations, such as BL2 is
|
||||
not part of the protocol-updatable images, if BL2 needs to be updated, then
|
||||
it should be done through another platform-defined mechanism, and it assumes
|
||||
that the platform's hardware supports CRC32 instructions.
|
||||
|
||||
--------------
|
||||
|
||||
*Copyright (c) 2019-2023, Arm Limited. All rights reserved.*
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue