Docs: Add document for header file and Kconfig system
Change-Id: I3dfb9b271e10a5b9ee999ce9aa59979d1581a276
Signed-off-by: Kevin Peng <kevin.peng@arm.com>
diff --git a/docs/configuration/header_file_system.png b/docs/configuration/header_file_system.png
new file mode 100755
index 0000000..0c2151a
--- /dev/null
+++ b/docs/configuration/header_file_system.png
Binary files differ
diff --git a/docs/configuration/header_file_system.rst b/docs/configuration/header_file_system.rst
new file mode 100644
index 0000000..e87f64e
--- /dev/null
+++ b/docs/configuration/header_file_system.rst
@@ -0,0 +1,223 @@
+.. _Header_configuration:
+
+#############################
+The Header File Config System
+#############################
+
+The header file configurations system is used to fine-tune component options.
+
+The following diagram shows how the system works.
+
+.. figure:: header_file_system.png
+
+A ``config_tfm.h`` file collects customized configurations, including platform customized and
+project specific settings.
+Each component has a ``config_<comp_name>.h`` which includes the ``config_tfm.h`` first and then
+provides default values for each config option of the component as well as necessary validations
+on config dependencies.
+Source files then include component header files when necessary.
+
+The ``config_tfm.h`` includes a customized project config file provided via compile definition
+``PROJECT_CONFIG_HEADER_FILE``.
+Users set the corresponding CMake variable ``PROJECT_CONFIG_HEADER_FILE`` with the full path of the
+configuration header file.
+A platform can adjust or place restriction on config options by providing a ``config_tfm_target.h``
+under the root folder of their platforms.
+If the build system finds the file, it sets the ``TARGET_CONFIG_HEADER_FILE`` compile definition.
+
+.. code-block:: c
+
+ #ifdef PROJECT_CONFIG_HEADER_FILE
+ #include PROJECT_CONFIG_HEADER_FILE
+ #endif
+
+ #ifdef TARGET_CONFIG_HEADER_FILE
+ #include TARGET_CONFIG_HEADER_FILE
+ #endif
+
+The project config header file can be
+
+- Generated by the TF-M Kconfig system <kconfig_system>
+- One of the header files of Profiles <tf-m_profiles>, set via the ``TFM_PROFILE`` build option.
+- Manually customized profile based on pre-set profiles.
+
+It is expected that all Component options are included in the header file to explicitly set values
+for each option.
+Refer to `Base Config Options`_ for details the base configurations.
+
+*******************
+Base Config Options
+*******************
+This section lists the config option categorizations of the SPM and Secure Partitions.
+
+Crypto
+======
++-------------------------------------+-----------+------------+
+| Options | Type | Base Value |
++=====================================+===========+============+
+|TFM_PARTITION_CRYPTO | Build | OFF |
++-------------------------------------+-----------+------------+
+|CRYPTO_TFM_BUILTIN_KEYS_DRIVER | Build | ON |
++-------------------------------------+-----------+------------+
+|CRYPTO_NV_SEED | Component | ON |
++-------------------------------------+-----------+------------+
+|CRYPTO_ENGINE_BUF_SIZE | Component | 0x2080 |
++-------------------------------------+-----------+------------+
+|CRYPTO_IOVEC_BUFFER_SIZE | Component | 5120 |
++-------------------------------------+-----------+------------+
+|CRYPTO_STACK_SIZE | Component | 0x1B00 |
++-------------------------------------+-----------+------------+
+|CRYPTO_CONC_OPER_NUM | Component | 8 |
++-------------------------------------+-----------+------------+
+|CRYPTO_RNG_MODULE_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+|CRYPTO_KEY_MODULE_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+|CRYPTO_AEAD_MODULE_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+|CRYPTO_MAC_MODULE_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+|CRYPTO_HASH_MODULE_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+|CRYPTO_CIPHER_MODULE_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+|CRYPTO_ASYM_SIGN_MODULE_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+|CRYPTO_ASYM_ENCRYPT_MODULE_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+|CRYPTO_KEY_DERIVATION_MODULE_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+|CRYPTO_SINGLE_PART_FUNCS_ENABLED | Component | 1 |
++-------------------------------------+-----------+------------+
+
+Initial Attestation
+===================
++-------------------------------------+-----------+-------------+
+| Options | Type | Base Value |
++=====================================+===========+=============+
+|TFM_PARTITION_INITIAL_ATTESTATION | Build | OFF |
++-------------------------------------+-----------+-------------+
+|SYMMETRIC_INITIAL_ATTESTATION | Build | OFF |
++-------------------------------------+-----------+-------------+
+|ATTEST_INCLUDE_TEST_CODE | Build | OFF |
++-------------------------------------+-----------+-------------+
+|ATTEST_KEY_BITS | Build | 256 |
++-------------------------------------+-----------+-------------+
+|ATTEST_TOKEN_PROFILE | Component | "PSA_IOT_1" |
++-------------------------------------+-----------+-------------+
+|ATTEST_INCLUDE_OPTIONAL_CLAIMS | Component | 1 |
++-------------------------------------+-----------+-------------+
+|ATTEST_INCLUDE_COSE_KEY_ID | Component | 0 |
++-------------------------------------+-----------+-------------+
+|ATTEST_STACK_SIZE | Component | 0x700 |
++-------------------------------------+-----------+-------------+
+
+Internal Trusted Storage
+========================
++---------------------------------------+-----------+------------------------+
+| Options | Type | Base Value |
++=======================================+===========+========================+
+|TFM_PARTITION_INTERNAL_TRUSTED_STORAGE | Build | OFF |
++---------------------------------------+-----------+------------------------+
+|ITS_CREATE_FLASH_LAYOUT | Component | 1 |
++---------------------------------------+-----------+------------------------+
+|ITS_RAM_FS | Component | 0 |
++---------------------------------------+-----------+------------------------+
+|ITS_VALIDATE_METADATA_FROM_FLASH | Component | 1 |
++---------------------------------------+-----------+------------------------+
+|ITS_MAX_ASSET_SIZE | Component | 512 |
++---------------------------------------+-----------+------------------------+
+|ITS_NUM_ASSETS | Component | 10 |
++---------------------------------------+-----------+------------------------+
+|ITS_BUF_SIZE | Component | ITS_MAX_ASSET_SIZE |
++---------------------------------------+-----------+------------------------+
+|ITS_STACK_SIZE | Component | 0x720 |
++---------------------------------------+-----------+------------------------+
+
+Protected Storage
+=================
++---------------------------------------+-----------+-----------------+
+| Options | Type | Base Value |
++=======================================+===========+=================+
+|TFM_PARTITION_PROTECTED_STORAGE | Build | OFF |
++---------------------------------------+-----------+-----------------+
+|PS_ENCRYPTION | Build | ON |
++---------------------------------------+-----------+-----------------+
+|PS_CRYPTO_AEAD_ALG | Build | PSA_ALG_GCM |
++---------------------------------------+-----------+-----------------+
+|PS_CREATE_FLASH_LAYOUT | Component | 1 |
++---------------------------------------+-----------+-----------------+
+|PS_RAM_FS | Component | 0 |
++---------------------------------------+-----------+-----------------+
+|PS_VALIDATE_METADATA_FROM_FLASH | Component | 1 |
++---------------------------------------+-----------+-----------------+
+|PS_MAX_ASSET_SIZE | Component | 2048 |
++---------------------------------------+-----------+-----------------+
+|PS_NUM_ASSETS | Component | 10 |
++---------------------------------------+-----------+-----------------+
+|PS_ROLLBACK_PROTECTION | Component | 1 |
++---------------------------------------+-----------+-----------------+
+|PS_STACK_SIZE | Component | 0x700 |
++---------------------------------------+-----------+-----------------+
+
+Firmware Update
+===============
++-------------------------------------+-----------+-------------------------------------+
+| Options | Type | Base Value |
++=====================================+===========+=====================================+
+|PLATFORM_HAS_FIRMWARE_UPDATE_SUPPORT | Build | OFF |
++-------------------------------------+-----------+-------------------------------------+
+|TFM_PARTITION_FIRMWARE_UPDATE | Build | OFF |
++-------------------------------------+-----------+-------------------------------------+
+|TFM_CONFIG_FWU_MAX_WRITE_SIZE | Build | 1024 |
++-------------------------------------+-----------+-------------------------------------+
+|TFM_CONFIG_FWU_MAX_MANIFEST_SIZE | Build | 0 |
++-------------------------------------+-----------+-------------------------------------+
+|FWU_DEVICE_CONFIG_FILE | Build | "" |
++-------------------------------------+-----------+-------------------------------------+
+|FWU_SUPPORT_TRIAL_STATE | Build | Depends on MCUBOOT_UPGRADE_STRATEGY |
++-------------------------------------+-----------+-------------------------------------+
+|TFM_FWU_BOOTLOADER_LIB | Build | "mcuboot" |
++-------------------------------------+-----------+-------------------------------------+
+|TFM_FWU_BUF_SIZE | Component | PSA_FWU_MAX_BLOCK_SIZE |
++-------------------------------------+-----------+-------------------------------------+
+|FWU_STACK_SIZE | Component | 0x600 |
++-------------------------------------+-----------+-------------------------------------+
+
+Platform Secure Partition
+=========================
++-------------------------------------+-----------+------------+
+| Options | Type | Base Value |
++=====================================+===========+============+
+|TFM_PARTITION_PLATFORM | Build | OFF |
++-------------------------------------+-----------+------------+
+|PLATFORM_SERVICE_INPUT_BUFFER_SIZE | Component | 64 |
++-------------------------------------+-----------+------------+
+|PLATFORM_SERVICE_OUTPUT_BUFFER_SIZE | Component | 64 |
++-------------------------------------+-----------+------------+
+|PLATFORM_SP_STACK_SIZE | Component | 0x500 |
++-------------------------------------+-----------+------------+
+|PLATFORM_NV_COUNTER_MODULE_DISABLED | Component | 0 |
++-------------------------------------+-----------+------------+
+
+Secure Partition Manager
+========================
++-------------------------------------+-----------+-------------+
+| Options | Type | Base Values |
++=====================================+===========+=============+
+|TFM_ISOLATION_LEVEL | Build | 1 |
++-------------------------------------+-----------+-------------+
+|PSA_FRAMEWORK_HAS_MM_IOVEC | Build | OFF |
++-------------------------------------+-----------+-------------+
+|CONFIG_TFM_SPM_BACKEND | Build | "SFN" |
++-------------------------------------+-----------+-------------+
+|TFM_SPM_LOG_LEVEL | Build | 1 |
++-------------------------------------+-----------+-------------+
+|CONFIG_TFM_CONN_HANDLE_MAX_NUM | Component | 8 |
++-------------------------------------+-----------+-------------+
+|CONFIG_TFM_DOORBELL_API | Component | 0 |
++-------------------------------------+-----------+-------------+
+
+--------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst
index 29db514..391620c 100644
--- a/docs/configuration/index.rst
+++ b/docs/configuration/index.rst
@@ -15,6 +15,8 @@
:glob:
build_configuration.rst
+ Component configuration <header_file_system>
+ Kconfig <kconfig_system>
Profiles <profiles/index>
test_configuration.rst
@@ -23,25 +25,23 @@
them to their requirements. There are two types of configuration options
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.
+ 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. Please check the corresponded section :ref:`tfm_cmake_configuration`
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.
+ Options are in C header file. The :ref:`Header_configuration` has more
+ details about it.
.. 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 configuration and moved component options into a dedicated
+ :ref:`Header_configuration` and moved component options into a dedicated
config headers.
****************
@@ -52,8 +52,8 @@
SPM and platform code only. Starting from the base, users can enable required
services and features using several independent methods to configure TF-M.
-Use <Profiles>.
- There are 4 sets of predefined configurations for a selected
+Use :ref:`tf-m_profiles`.
+ There are 4 sets of predefined configurations for a elected
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
@@ -64,11 +64,11 @@
options manually editing CMake and config header files. This is for users
familiar with TF-M.
-Use <Kconfig_system>.
+Use :ref:`Kconfig_system`.
This method is recommended for beginners. Starting from the
- <base configuration> a user can enable necessary services and options.
+ *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
+ This is new in v1.7.0 and it covers only SPM and PSA services. As an output
KConfig produces a pair of configuration files, similar to a profile.
.. Note::
@@ -83,7 +83,7 @@
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
+:ref:`tfm_cmake_configuration` or :ref:`Header_configuration` please
check the corresponded document.
#. The base configuration with default values is used as a starting point
diff --git a/docs/configuration/kconfig_header_file_system.png b/docs/configuration/kconfig_header_file_system.png
new file mode 100755
index 0000000..80d2ed2
--- /dev/null
+++ b/docs/configuration/kconfig_header_file_system.png
Binary files differ
diff --git a/docs/configuration/kconfig_system.rst b/docs/configuration/kconfig_system.rst
new file mode 100644
index 0000000..41a3d4f
--- /dev/null
+++ b/docs/configuration/kconfig_system.rst
@@ -0,0 +1,84 @@
+.. _Kconfig_system:
+
+##################
+The Kconfig System
+##################
+The Kconfig system is an additional tool for users to change configuration options of TF-M.
+
+.. figure:: kconfig_header_file_system.png
+
+It handles dependencies and validations automatically when you change configurations so that the
+generated configuration options are always valid.
+
+It consists of `The Kconfig tool`_ and the `The Kconfig files`_.
+
+****************
+The Kconfig tool
+****************
+The Kconfig tool is a python script based on `Kconfiglib <https://github.com/ulfalizer/Kconfiglib>`__
+to launch the menuconfig interfaces and generate the following config files:
+
+- CMake config file
+
+ Contains CMake cache variables of building options.
+ This file should be passed to the build system via command line option ``TFM_EXTRA_CONFIG_PATH``.
+
+- Header file
+
+ Contains component options in the header file system.
+ This file should be passed to the build system via the command line option ``PROJECT_CONFIG_HEADER_FILE``.
+
+- The .config file
+
+ The ``.config`` file which contains all the above configurations in the Kconfig format.
+ It is only used to allow users to make adjustments basing on the previous settings.
+ The Kconfig tool will load it if it exists.
+
+How To Use
+==========
+The script takes three arguments at maximum.
+
+- '-k', '--kconfig-file'
+
+ Required. The root Kconfig file.
+
+- '-u', '--ui'
+
+ Optional. The menuconfig interface to launch, ``gui`` or ``tui``.
+ Refer to `Menuconfig interfaces <https://github.com/ulfalizer/Kconfiglib#menuconfig-interfaces>`__
+ for interface details. Only the first two are supported.
+ If no UI is selected, the tool generates config files with default values.
+
+- '-o', '--output_path'
+
+ Required. The output directory to hold the generated files.
+
+The script can be used as a standalone tool.
+You can pass the config files to build system via command line option ``TFM_EXTRA_CONFIG_PATH`` and
+``PROJECT_CONFIG_HEADER_FILE`` respectively, as mentioned above.
+
+The TF-M build system has also integrated the tool.
+You only need to set ``USE_KCONFIG_TOOL`` to ``ON/TRUE/1`` and CMake will launch the GUI menuconfig
+for users to adjust configurations and automatically load the generated config files.
+
+.. note::
+
+ - Only GUI menuconfig can be launched by CMake for the time being.
+ - Due to the current limitation of the tool, you are not allowed to change the values of build
+ options that of which platforms have customized values. And there is no prompt messages either.
+
+*****************
+The Kconfig files
+*****************
+The Kconfig files are the files written in the
+`Kconfig language <https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html#kconfig-language>`__
+to describe config options.
+They also uses some Kconfiglib extensions such as ``osource`` and ``rsource`` so they can only work
+with the Kconfiglib.
+
+Component options are gathered together in a seperate menu ``TF-M component configs`` because these
+options are changed less frequently.
+
+--------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
diff --git a/docs/introduction/readme.rst b/docs/introduction/readme.rst
index d33e1ee..56e77bc 100644
--- a/docs/introduction/readme.rst
+++ b/docs/introduction/readme.rst
@@ -28,7 +28,7 @@
‘TF-M base’ build with just TF-M core and platform drivers and 4 predefined
configurations known as :ref:`tf-m_profiles`. TF-M Profiles or TF-M base can
be configured to include required services and features as described in the
-'Configuration' section.
+:ref:`tf-m_configuration` section.
.. figure:: readme_tfm_v8.png
:scale: 65 %
