Docs: Gather configuration options in a section
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: Ia59485647cb34694c7b7274022825af3b8eef526
diff --git a/docs/configuration/build_configuration.rst b/docs/configuration/build_configuration.rst
new file mode 100644
index 0000000..f82d6d7
--- /dev/null
+++ b/docs/configuration/build_configuration.rst
@@ -0,0 +1,39 @@
+.. _tfm_cmake_configuration:
+
+###################
+Build configuration
+###################
+
+All configuration options are provided by cmake variables, and their default
+values, with docstrings, can be found in ``config/config_base.cmake``.
+
+Configuration is provided in multiple stages. Each stage will not override any
+config that has already been set at any of the prior stages.
+
+ 1. Command-line variable settings are applied.
+ 2. If the ``TFM_EXTRA_CONFIG_PATH`` variable has been set, that file is
+ loaded.
+ 3. If TEST_PSA_TEST is set, then PSA API test related config is applied from
+ ``config/tests/config_test_psa_api.cmake``.
+ 4. If it exists, CMAKE_BUILD_TYPE specific config is applied from
+ ``config/build_type/<build_type>.cmake``.
+ 5. Target specific config from ``platform/ext/target/<target_platform>/config.cmake``
+ is applied.
+ 6. If CRYPTO_HW_ACCELERATOR is set, then a config specific to the
+ accelerator type is applied if it exists.
+ 7. If it exists, TFM Profile specific config is applied from
+ ``config/profile/<tfm_profile>.cmake``.
+ 8. ``config/config_default.cmake`` is loaded.
+ 9. If ``TEST_S`` or ``TEST_NS`` or other single test suite config like
+ ``TEST_NS_ATTESTATION`` (see :ref:`test_configuration`) is set, then
+ config from ``${TFM_TEST_REPO_PATH}/test/config/set_config.cmake`` and
+ ``${TFM_TEST_REPO_PATH}/test/config/default_ns_test_config.cmake`` or
+ ``${TFM_TEST_REPO_PATH}/test/config/default_s_test_config.cmake`` or
+ ``${TFM_TEST_REPO_PATH}/test/config/default_test_config.cmake`` is
+ applied.
+
+.. Warning::
+ This means that command-line settings are not applied when they conflict
+ with required platform settings. If it is required to override platform
+ settings (this is not usually a good idea) then TFM_EXTRA_CONFIG_PATH should be
+ used.
diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst
index 7c2cc2d..29db514 100644
--- a/docs/configuration/index.rst
+++ b/docs/configuration/index.rst
@@ -1,3 +1,5 @@
+.. _tf-m_configuration:
+
#############
Configuration
#############
@@ -12,53 +14,61 @@
:maxdepth: 1
:glob:
- profiles/index
+ build_configuration.rst
+ Profiles <profiles/index>
+ test_configuration.rst
-TF-M is a complex project having many configuration options to adjust project
-for a user needs. A user can select the desired set of services and fine-tune
-them to user's requirements. There are 2 types of configuration options:
+TF-M is highly configurable project with many configuration options to meet
+a user needs. A user can select the desired set of services and fine-tune
+them to their requirements. There are two types of configuration options
-1. Building : to select which file or component to include into compilation.
+Building configuration
+ Specifies which file or component to include into compilation and build.
These are options, usually used by a build system to enable/disable
modules, specify location of external dependency or other selection,
global to a project. These options shall be considered while adopting TF-M
to other build systems.
In the Base configuration table theses options have *Build* type.
-2. Component tuning : to adjust a particular parameter to a desired value.
- Those options are local to a component or externally referenced when
- components are coupled. Usually, such options are located in C header
- file. The Header File Config System has more details about it.
+Component tuning
+ To adjust a particular parameter to a desired value. Those options are
+ local to a component or externally referenced when components are coupled.
+ Options are in C header file. The <Header_configuration> has more details about it.
In the Base configuration table theses options have *Component* type.
.. Note::
- Originally, TF-M used CMake variables for both building and component tuning
- purposes. It was convenient to have a single system for both building and
- component's configurations. To simplify and improve configurability and
- better support build systems other than a CMake, TF-M introduced a header
- file configuration and moved component options into a dedicated config headers.
+ Originally, TF-M used CMake variables for both building and component tuning
+ purposes. It was convenient to have a single system for both building and
+ component's configurations. To simplify and improve configurability and
+ better support build systems other than a CMake, TF-M introduced a
+ Header configuration and moved component options into a dedicated
+ config headers.
****************
How to configure
****************
-The default TF-M build includes the minimum set of components required in any
-project: SPM and a selected platform. This is not very useful for any product
-and desired services shall be enabled by a user. There are several independent
-ways to configure TF-M.
+TF-M Project provides a base build, defined in config_base.cmake. It includes
+SPM and platform code only. Starting from the base, users can enable required
+services and features using several independent methods to configure TF-M.
-1. Use profiles. There are 4 sets of predefined configurations for a elected
+Use <Profiles>.
+ There are 4 sets of predefined configurations for a selected
use cases, called profiles. A user can select a profile by providing
-DTFM_PROFILE=<profile file name>.
Each profiles represented by a pair of configuration files for
Building (CMake) options and Component options (.h file)
-2. A custom profile. Another method is to take a profile as a base and manually
- modify desired options.
+Use a custom profile.
+ Another method is to take existing TF-M profile and adjust the desired
+ options manually editing CMake and config header files. This is for users
+ familiar with TF-M.
-3. Use KConfig system. This is recommended method especially for beginners.
- KConfig ensurers that all selected options are consistent and valid. This
- is new in v1.7.0 and it covers only SPM and PSA ervices. As an output
+Use <Kconfig_system>.
+ This method is recommended for beginners. Starting from the
+ <base configuration> a user can enable necessary services and options.
+ KConfig ensurers that all selected options are consistent and valid.
+ This is new in v1.7.0 and it covers only SPM and PSA ervices. As an output
KConfig produces a pair of configuration files, similar to a profile.
.. Note::
@@ -70,10 +80,21 @@
**********
Priorities
**********
-Note::
- TODO: Need a secion on configuration Priorities
+A project configueration performed in multiple steps with priorities.
+The list below explains the process but for the details specific to
+:ref:`tfm_cmake_configuration` or <Header_configuration> please
+check the corresponded document.
+#. The base configuration with default values is used as a starting point
+#. A profile options applied on top of the base
+#. A platform can check the selected configuration and apply restrictions
+#. Finally, command line options can modify the composed set
+
+.. Note::
+ To ensure a clear intention and conscious choice, all options must be
+ providede explicitly via a project configuration file. Default values
+ on step 1 will generate warnings which expected to break a build.
--------------
diff --git a/docs/configuration/profiles/index.rst b/docs/configuration/profiles/index.rst
index 1b3e69b..1000aa5 100644
--- a/docs/configuration/profiles/index.rst
+++ b/docs/configuration/profiles/index.rst
@@ -1,5 +1,8 @@
+.. _tf-m_profiles:
+
+#############
TF-M Profiles
-=============
+#############
The capabilities and resources may dramatically vary on different IoT devices.
Some IoT devices may have very limited memory resource. The program on those devices should keep
@@ -83,4 +86,4 @@
--------------
-Copyright (c) 2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/configuration/test_configuration.rst b/docs/configuration/test_configuration.rst
new file mode 100644
index 0000000..8f2825d
--- /dev/null
+++ b/docs/configuration/test_configuration.rst
@@ -0,0 +1,121 @@
+.. _test_configuration:
+
+###################
+Tests configuration
+###################
+
+Regression tests
+================
+
+Regression test configuration is controlled entirely by ``TEST_NS`` or
+``TEST_S`` or single test suite configuration. The group test
+configurations and single test suite configurations are listed below, all of
+them are disabled by default.
+
++---------------------+--------------------------------------------------------------------+
+| Parameter | Description |
++=====================+====================================================================+
+| TEST_NS_ATTESTATION | Build non-secure regression Attestation tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_T_COSE | Build non-secure regression t_cose tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_QCBOR | Build non-secure regression QCBOR tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_CRYPTO | Build non-secure regression Crypto tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_ITS | Build non-secure regression ITS tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_PS | Build non-secure regression PS tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_PLATFORM | Build non-secure regression Platform tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_FWU | Build non-secure regression FWU tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_IPC | Build non-secure regression IPC tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_SLIH_IRQ | Build non-secure regression Second-Level Interrupt Handling tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_FLIH_IRQ | Build non-secure regression First-Level Interrupt Handling tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_NS_MULTI_CORE | Build non-secure regression multi-core tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_S_ATTESTATION | Build secure regression Attestation tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_S_CRYPTO | Build secure regression Crypto tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_S_ITS | Build secure regression ITS tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_S_PS | Build secure regression PS tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_S_PLATFORM | Build secure regression Platform tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_S_FWU | Build secure regression FWU tests. |
++---------------------+--------------------------------------------------------------------+
+| TEST_S_IPC | Build secure regression IPC tests. |
++---------------------+--------------------------------------------------------------------+
+
+Individual test suites can be enabled when their dependencies like partitions or
+other specific configurations are set. On the one hand, some test suites depend
+on other test suites. On the other hand, some test suites conflict with
+other test suites. Test configurations and dependencies will be
+checked in ``${TFM_TEST_REPO_PATH}/test/config/check_config.cmake``.
+
+If regression testing is enabled by ``TEST_NS`` or ``TEST_S``, individual
+test suites will be enabled or disabled as appropriate for the TF-M
+configuration (i.e. all enabled secure partitions will be tested).
+
+Some cryptographic tests can be enabled and disabled. This is done to prevent
+false failures from being reported when a smaller Mbed Crypto config is being
+used which does not support all features.
+
++---------------------------------------+---------------------------------------+---------------+
+| Parameter | Description | Default value |
++=======================================+=======================================+===============+
+| TFM_CRYPTO_TEST_ALG_CBC | Test CBC cryptography mode | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CCM | Test CCM cryptography mode | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CFB | Test CFB cryptography mode | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_ECB | Test ECB cryptography mode | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CTR | Test CTR cryptography mode | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_OFB | Test OFB cryptography mode | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_GCM | Test GCM cryptography mode | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_SHA_384 | Test SHA-384 cryptography algorithm | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_SHA_512 | Test SHA-512 cryptography algorithm | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_HKDF | Test HKDF key derivation algorithm | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ECDH | Test ECDH key agreement algorithm | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_CHACHA20 | Test ChaCha20 stream cipher | ON |
++---------------------------------------+---------------------------------------+---------------+
+| TFM_CRYPTO_TEST_ALG_CHACHA20_POLY1305 | Test ChaCha20-Poly1305 AEAD algorithm | ON |
++---------------------------------------+---------------------------------------+---------------+
+
+PSA tests
+=========
+
+PSA tests are configured by using the ``TEST_PSA_API`` cmake variable. The
+variable should be set to the name of the test suite that is desired. It is
+_not_ supported to set both ``TEST_PSA_API`` and ``TEST_S`` or ``TEST_NS``.
+
+The Functional API tests are:
+ - ``CRYPTO``
+ - ``INITIAL_ATTESTATION``
+ - ``STORAGE`` (INTERNAL_TRUSTED_STORAGE and PROTECTED_STORAGE)
+ - ``INTERNAL_TRUSTED_STORAGE``
+ - ``PROTECTED_STORAGE``
+
+The Firmware Framework test suites are:
+ - ``IPC``
+ - ``SFN``
+ - ``Interrupt``
+
+Note that these map directly to the ``SUITE`` cmake variable used in the
+psa-arch-tests documentation.