Docs: Gather configuration options in a section
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: Ia59485647cb34694c7b7274022825af3b8eef526
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.
--------------