docs/configuration/header_file_system.rst

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