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