github
/
arm-trusted-firmware
mirror of https://github.com/ARM-software/arm-trusted-firmware.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

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
pull/1993/merge
Olivier Deprez 1 year ago
parent
f15f360cfc
commit
48856003bf
2 changed files with 134 additions and 107 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 22
      docs/about/features.rst
  2. 219
      docs/getting_started/build-options.rst

22
docs/about/features.rst
View File

@ -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
-------------

219
docs/getting_started/build-options.rst
View File

@ -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.*

Write Preview
Loading…
Cancel
Save