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
1 year ago · 48856003bf
2 changed files with 134 additions and 107 deletions
--- a/docs/about/features.rst
+++ b/docs/about/features.rst
@ -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
 -------------
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@ -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.*