1.. _tf-m_configuration:
2
3#############
4Configuration
5#############
6
7.. toctree::
8    :maxdepth: 1
9    :glob:
10
11    build_configuration.rst
12    Component configuration <header_file_system>
13    Kconfig <kconfig_system>
14    Profiles <profiles/index>
15    test_configuration.rst
16
17TF-M is highly configurable project with many configuration options to meet
18a user needs. A user can select the desired set of services and fine-tune
19them to their requirements. There are two types of configuration options
20
21Build configuration
22   Specifies which file or component to include into compilation and build.
23   These are options, usually used by a build system to enable/disable
24   modules, specify location of external dependency or other selection,
25   global to a project. These option set shall be considered while adopting TF-M
26   to other build systems.
27   In the :ref:`Base_configuration` table these options have *Build* type.
28
29Component configuration
30   To adjust a particular parameter to a desired value. Those options are
31   local to a component or externally referenced when components are coupled.
32   Options are in C header file. The :ref:`Header_configuration` has more
33   details about it.
34   In the :ref:`Base_configuration` table theses options have *Component* type.
35
36.. Note::
37   Originally, TF-M used CMake variables for both building and component tuning
38   purposes. It was convenient to have a single system for both building and
39   component's configurations. To simplify and improve configurability and
40   better support build systems other than a CMake, TF-M introduced a
41   :ref:`Header_configuration` and moved component options into a dedicated
42   config headers.
43
44****************
45How to configure
46****************
47
48TF-M Project provides a base build, defined in ``/config/config_base.cmake``
49and ``/config/config_base.h``.
50Starting from the base, users can enable required services and features using several
51independent methods to configure TF-M.
52
53Use :ref:`tf-m_profiles`.
54   There are 4 sets of predefined configurations for a elected
55   use cases, called profiles. A user can select a profile by providing
56   -DTFM_PROFILE=<profile file name>.
57   Each profiles represented by a pair of configuration files for
58   Building (CMake) options and Component options (.h file)
59
60Use a custom profile.
61   Another method is to take existing TF-M profile and adjust the desired
62   options manually editing CMake and config header files. This is for users
63   familiar with TF-M.
64
65Use :ref:`Kconfig_system`.
66   This method is recommended for beginners. Starting from the
67   *base configuration* a user can enable necessary services and options.
68   KConfig ensurers that all selected options are consistent and valid.
69   This is new in v1.7.0 and it covers only SPM and PSA services. As an output
70   KConfig produces a pair of configuration files, similar to a profile.
71
72.. Note::
73   In contrast, before TF-M v1.7.0, the default build includes all possible
74   features. With growing functionality, such rich default build became
75   unpractical by not fitting into every platform and confusing of big
76   memory requirements.
77
78**********
79Priorities
80**********
81
82A project configueration performed in multiple steps with priorities.
83The list below explains the process but for the details specific to
84:ref:`tfm_cmake_configuration` or :ref:`Header_configuration` please
85check the corresponded document.
86
87#. The base configuration with default values is used as a starting point
88#. A profile options applied on top of the base
89#. A platform can check the selected configuration and apply restrictions
90#. Finally, command line options can modify the composed set
91
92.. Note::
93   To ensure a clear intention and conscious choice, all options must be
94   providede explicitly via a project configuration file. Default values
95   on step 1 will generate warnings which expected to break a build.
96
97.. _Base_configuration:
98
99******************
100Base Configuration
101******************
102
103The base configuration is the ground for configuring TF-M providing default
104defined in ``/config/config_base.cmake`` and ``/config/config_base.h``.
105The base build includes SPM and platform code only.
106
107This table lists the config option categorizations of the SPM and Secure
108Partitions.
109
110Crypto
111======
112+-------------------------------------+-----------+------------+
113| Options                             | Type      | Base Value |
114+=====================================+===========+============+
115|TFM_PARTITION_CRYPTO                 | Build     |   OFF      |
116+-------------------------------------+-----------+------------+
117|CRYPTO_TFM_BUILTIN_KEYS_DRIVER       | Build     |   ON       |
118+-------------------------------------+-----------+------------+
119|CRYPTO_NV_SEED                       | Component |   ON       |
120+-------------------------------------+-----------+------------+
121|CRYPTO_ENGINE_BUF_SIZE               | Component |   0x2080   |
122+-------------------------------------+-----------+------------+
123|CRYPTO_IOVEC_BUFFER_SIZE             | Component |   5120     |
124+-------------------------------------+-----------+------------+
125|CRYPTO_STACK_SIZE                    | Component |   0x1B00   |
126+-------------------------------------+-----------+------------+
127|CRYPTO_CONC_OPER_NUM                 | Component |   8        |
128+-------------------------------------+-----------+------------+
129|CRYPTO_RNG_MODULE_ENABLED            | Component |   1        |
130+-------------------------------------+-----------+------------+
131|CRYPTO_KEY_MODULE_ENABLED            | Component |   1        |
132+-------------------------------------+-----------+------------+
133|CRYPTO_AEAD_MODULE_ENABLED           | Component |   1        |
134+-------------------------------------+-----------+------------+
135|CRYPTO_MAC_MODULE_ENABLED            | Component |   1        |
136+-------------------------------------+-----------+------------+
137|CRYPTO_HASH_MODULE_ENABLED           | Component |   1        |
138+-------------------------------------+-----------+------------+
139|CRYPTO_CIPHER_MODULE_ENABLED         | Component |   1        |
140+-------------------------------------+-----------+------------+
141|CRYPTO_ASYM_SIGN_MODULE_ENABLED      | Component |   1        |
142+-------------------------------------+-----------+------------+
143|CRYPTO_ASYM_ENCRYPT_MODULE_ENABLED   | Component |   1        |
144+-------------------------------------+-----------+------------+
145|CRYPTO_KEY_DERIVATION_MODULE_ENABLED | Component |   1        |
146+-------------------------------------+-----------+------------+
147|CRYPTO_SINGLE_PART_FUNCS_ENABLED     | Component |   1        |
148+-------------------------------------+-----------+------------+
149
150Initial Attestation
151===================
152+-------------------------------------+-----------+-------------+
153| Options                             | Type      | Base Value  |
154+=====================================+===========+=============+
155|TFM_PARTITION_INITIAL_ATTESTATION    | Build     |   OFF       |
156+-------------------------------------+-----------+-------------+
157|SYMMETRIC_INITIAL_ATTESTATION        | Build     |   OFF       |
158+-------------------------------------+-----------+-------------+
159|ATTEST_INCLUDE_TEST_CODE             | Build     |   OFF       |
160+-------------------------------------+-----------+-------------+
161|ATTEST_KEY_BITS                      | Build     |   256       |
162+-------------------------------------+-----------+-------------+
163|ATTEST_TOKEN_PROFILE                 | Component | "PSA_IOT_1" |
164+-------------------------------------+-----------+-------------+
165|ATTEST_INCLUDE_OPTIONAL_CLAIMS       | Component |   1         |
166+-------------------------------------+-----------+-------------+
167|ATTEST_INCLUDE_COSE_KEY_ID           | Component |   0         |
168+-------------------------------------+-----------+-------------+
169|ATTEST_STACK_SIZE                    | Component |   0x700     |
170+-------------------------------------+-----------+-------------+
171
172Internal Trusted Storage
173========================
174+---------------------------------------+-----------+------------------------+
175| Options                               | Type      | Base Value             |
176+=======================================+===========+========================+
177|TFM_PARTITION_INTERNAL_TRUSTED_STORAGE | Build     |   OFF                  |
178+---------------------------------------+-----------+------------------------+
179|ITS_CREATE_FLASH_LAYOUT                | Component |   1                    |
180+---------------------------------------+-----------+------------------------+
181|ITS_RAM_FS                             | Component |   0                    |
182+---------------------------------------+-----------+------------------------+
183|ITS_VALIDATE_METADATA_FROM_FLASH       | Component |   1                    |
184+---------------------------------------+-----------+------------------------+
185|ITS_MAX_ASSET_SIZE                     | Component |   512                  |
186+---------------------------------------+-----------+------------------------+
187|ITS_NUM_ASSETS                         | Component |   10                   |
188+---------------------------------------+-----------+------------------------+
189|ITS_BUF_SIZE                           | Component |   ITS_MAX_ASSET_SIZE   |
190+---------------------------------------+-----------+------------------------+
191|ITS_STACK_SIZE                         | Component |   0x720                |
192+---------------------------------------+-----------+------------------------+
193
194Protected Storage
195=================
196+---------------------------------------+-----------+-----------------+
197| Options                               | Type      | Base Value      |
198+=======================================+===========+=================+
199|TFM_PARTITION_PROTECTED_STORAGE        | Build     |   OFF           |
200+---------------------------------------+-----------+-----------------+
201|PS_ENCRYPTION                          | Build     |   ON            |
202+---------------------------------------+-----------+-----------------+
203|PS_CRYPTO_AEAD_ALG                     | Build     |   PSA_ALG_GCM   |
204+---------------------------------------+-----------+-----------------+
205|PS_CREATE_FLASH_LAYOUT                 | Component |   1             |
206+---------------------------------------+-----------+-----------------+
207|PS_RAM_FS                              | Component |   0             |
208+---------------------------------------+-----------+-----------------+
209|PS_VALIDATE_METADATA_FROM_FLASH        | Component |   1             |
210+---------------------------------------+-----------+-----------------+
211|PS_MAX_ASSET_SIZE                      | Component |   2048          |
212+---------------------------------------+-----------+-----------------+
213|PS_NUM_ASSETS                          | Component |   10            |
214+---------------------------------------+-----------+-----------------+
215|PS_ROLLBACK_PROTECTION                 | Component |   1             |
216+---------------------------------------+-----------+-----------------+
217|PS_STACK_SIZE                          | Component |   0x700         |
218+---------------------------------------+-----------+-----------------+
219
220Firmware Update
221===============
222+-------------------------------------+-----------+-------------------------------------+
223| Options                             | Type      | Base Value                          |
224+=====================================+===========+=====================================+
225|PLATFORM_HAS_FIRMWARE_UPDATE_SUPPORT | Build     |   OFF                               |
226+-------------------------------------+-----------+-------------------------------------+
227|TFM_PARTITION_FIRMWARE_UPDATE        | Build     |   OFF                               |
228+-------------------------------------+-----------+-------------------------------------+
229|TFM_CONFIG_FWU_MAX_WRITE_SIZE        | Build     |   1024                              |
230+-------------------------------------+-----------+-------------------------------------+
231|TFM_CONFIG_FWU_MAX_MANIFEST_SIZE     | Build     |   0                                 |
232+-------------------------------------+-----------+-------------------------------------+
233|FWU_DEVICE_CONFIG_FILE               | Build     |   ""                                |
234+-------------------------------------+-----------+-------------------------------------+
235|FWU_SUPPORT_TRIAL_STATE              | Build     | Depends on MCUBOOT_UPGRADE_STRATEGY |
236+-------------------------------------+-----------+-------------------------------------+
237|TFM_FWU_BOOTLOADER_LIB               | Build     |   "mcuboot"                         |
238+-------------------------------------+-----------+-------------------------------------+
239|TFM_FWU_BUF_SIZE                     | Component |   PSA_FWU_MAX_BLOCK_SIZE            |
240+-------------------------------------+-----------+-------------------------------------+
241|FWU_STACK_SIZE                       | Component |   0x600                             |
242+-------------------------------------+-----------+-------------------------------------+
243
244Platform Secure Partition
245=========================
246+-------------------------------------+-----------+------------+
247| Options                             | Type      | Base Value |
248+=====================================+===========+============+
249|TFM_PARTITION_PLATFORM               | Build     |   OFF      |
250+-------------------------------------+-----------+------------+
251|PLATFORM_SERVICE_INPUT_BUFFER_SIZE   | Component |   64       |
252+-------------------------------------+-----------+------------+
253|PLATFORM_SERVICE_OUTPUT_BUFFER_SIZE  | Component |   64       |
254+-------------------------------------+-----------+------------+
255|PLATFORM_SP_STACK_SIZE               | Component |   0x500    |
256+-------------------------------------+-----------+------------+
257|PLATFORM_NV_COUNTER_MODULE_DISABLED  | Component |   0        |
258+-------------------------------------+-----------+------------+
259
260Secure Partition Manager
261========================
262+----------------------------------------+-----------+-------------+
263| Options                                | Type      | Base Values |
264+========================================+===========+=============+
265|TFM_ISOLATION_LEVEL                     | Build     |   1         |
266+----------------------------------------+-----------+-------------+
267|PSA_FRAMEWORK_HAS_MM_IOVEC              | Build     |   OFF       |
268+----------------------------------------+-----------+-------------+
269|CONFIG_TFM_SPM_BACKEND                  | Build     |   "SFN"     |
270+----------------------------------------+-----------+-------------+
271|TFM_SPM_LOG_LEVEL                       | Build     |   1         |
272+----------------------------------------+-----------+-------------+
273|CONFIG_TFM_CONN_HANDLE_MAX_NUM          | Component |   8         |
274+----------------------------------------+-----------+-------------+
275|CONFIG_TFM_DOORBELL_API                 | Component |   0         |
276+----------------------------------------+-----------+-------------+
277|CONFIG_TFM_SCHEDULE_WHEN_NS_INTERRUPTED | Component |   0         |
278+----------------------------------------+-----------+-------------+
279
280--------------
281
282*Copyright (c) 2022, Arm Limited. All rights reserved.*
283*Copyright (c) 2023 Cypress Semiconductor Corporation (an Infineon company)
284or an affiliate of Cypress Semiconductor Corporation. All rights reserved.*
285