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's 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 these 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 an 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 configuration 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   provided explicitly via a project configuration file. Default values
95   on step 1 will generate warnings which are 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, provided defaults
104are defined 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_KEY_BITS                      | Build     |   256       |
160+-------------------------------------+-----------+-------------+
161|ATTEST_TOKEN_PROFILE                 | Component | "PSA_IOT_1" |
162+-------------------------------------+-----------+-------------+
163|ATTEST_INCLUDE_OPTIONAL_CLAIMS       | Component |   1         |
164+-------------------------------------+-----------+-------------+
165|ATTEST_INCLUDE_COSE_KEY_ID           | Component |   0         |
166+-------------------------------------+-----------+-------------+
167|ATTEST_STACK_SIZE                    | Component |   0x800     |
168+-------------------------------------+-----------+-------------+
169
170Internal Trusted Storage
171========================
172+---------------------------------------+-----------+------------------------+
173| Options                               | Type      | Base Value             |
174+=======================================+===========+========================+
175|TFM_PARTITION_INTERNAL_TRUSTED_STORAGE | Build     |   OFF                  |
176+---------------------------------------+-----------+------------------------+
177|ITS_CREATE_FLASH_LAYOUT                | Component |   1                    |
178+---------------------------------------+-----------+------------------------+
179|ITS_RAM_FS                             | Component |   0                    |
180+---------------------------------------+-----------+------------------------+
181|ITS_VALIDATE_METADATA_FROM_FLASH       | Component |   1                    |
182+---------------------------------------+-----------+------------------------+
183|ITS_MAX_ASSET_SIZE                     | Component |   512                  |
184+---------------------------------------+-----------+------------------------+
185|ITS_NUM_ASSETS                         | Component |   10                   |
186+---------------------------------------+-----------+------------------------+
187|ITS_BUF_SIZE                           | Component |   ITS_MAX_ASSET_SIZE   |
188+---------------------------------------+-----------+------------------------+
189|ITS_STACK_SIZE                         | Component |   0x720                |
190+---------------------------------------+-----------+------------------------+
191
192Protected Storage
193=================
194+---------------------------------------+-----------+-----------------+
195| Options                               | Type      | Base Value      |
196+=======================================+===========+=================+
197|TFM_PARTITION_PROTECTED_STORAGE        | Build     |   OFF           |
198+---------------------------------------+-----------+-----------------+
199|PS_ENCRYPTION                          | Build     |   ON            |
200+---------------------------------------+-----------+-----------------+
201|PS_SUPPORT_FORMAT_TRANSITION           | Build     |   OFF           |
202+---------------------------------------+-----------+-----------------+
203|PS_CRYPTO_AEAD_ALG                     | Build     |   PSA_ALG_GCM   |
204+---------------------------------------+-----------+-----------------+
205|PS_AES_KEY_USAGE_LIMIT                 | Build     |   0             |
206+---------------------------------------+-----------+-----------------+
207|PS_CREATE_FLASH_LAYOUT                 | Component |   1             |
208+---------------------------------------+-----------+-----------------+
209|PS_RAM_FS                              | Component |   0             |
210+---------------------------------------+-----------+-----------------+
211|PS_VALIDATE_METADATA_FROM_FLASH        | Component |   1             |
212+---------------------------------------+-----------+-----------------+
213|PS_MAX_ASSET_SIZE                      | Component |   2048          |
214+---------------------------------------+-----------+-----------------+
215|PS_NUM_ASSETS                          | Component |   10            |
216+---------------------------------------+-----------+-----------------+
217|PS_ROLLBACK_PROTECTION                 | Component |   1             |
218+---------------------------------------+-----------+-----------------+
219|PS_STACK_SIZE                          | Component |   0x700         |
220+---------------------------------------+-----------+-----------------+
221
222Firmware Update
223===============
224+-------------------------------------+-----------+-------------------------------------+
225| Options                             | Type      | Base Value                          |
226+=====================================+===========+=====================================+
227|PLATFORM_HAS_FIRMWARE_UPDATE_SUPPORT | Build     |   OFF                               |
228+-------------------------------------+-----------+-------------------------------------+
229|TFM_PARTITION_FIRMWARE_UPDATE        | Build     |   OFF                               |
230+-------------------------------------+-----------+-------------------------------------+
231|TFM_CONFIG_FWU_MAX_WRITE_SIZE        | Build     |   1024                              |
232+-------------------------------------+-----------+-------------------------------------+
233|TFM_CONFIG_FWU_MAX_MANIFEST_SIZE     | Build     |   0                                 |
234+-------------------------------------+-----------+-------------------------------------+
235|FWU_DEVICE_CONFIG_FILE               | Build     |   ""                                |
236+-------------------------------------+-----------+-------------------------------------+
237|FWU_SUPPORT_TRIAL_STATE              | Build     | Depends on MCUBOOT_UPGRADE_STRATEGY |
238+-------------------------------------+-----------+-------------------------------------+
239|TFM_FWU_BOOTLOADER_LIB               | Build     |   "mcuboot"                         |
240+-------------------------------------+-----------+-------------------------------------+
241|TFM_FWU_BUF_SIZE                     | Component |   PSA_FWU_MAX_BLOCK_SIZE            |
242+-------------------------------------+-----------+-------------------------------------+
243|FWU_STACK_SIZE                       | Component |   0x600                             |
244+-------------------------------------+-----------+-------------------------------------+
245
246Platform Secure Partition
247=========================
248+-------------------------------------+-----------+------------+
249| Options                             | Type      | Base Value |
250+=====================================+===========+============+
251|TFM_PARTITION_PLATFORM               | Build     |   OFF      |
252+-------------------------------------+-----------+------------+
253|PLATFORM_SERVICE_INPUT_BUFFER_SIZE   | Component |   64       |
254+-------------------------------------+-----------+------------+
255|PLATFORM_SERVICE_OUTPUT_BUFFER_SIZE  | Component |   64       |
256+-------------------------------------+-----------+------------+
257|PLATFORM_SP_STACK_SIZE               | Component |   0x500    |
258+-------------------------------------+-----------+------------+
259|PLATFORM_NV_COUNTER_MODULE_DISABLED  | Component |   0        |
260+-------------------------------------+-----------+------------+
261
262NS Agent Mailbox Secure Partition
263=================================
264+-------------------------------------+-----------+------------+
265| Options                             | Type      | Base Value |
266+=====================================+===========+============+
267|NS_AGENT_MAILBOX_STACK_SIZE          | Component |   0x800    |
268+-------------------------------------+-----------+------------+
269|MAILBOX_IS_UNCACHED_S                | Component |   1        |
270+-------------------------------------+-----------+------------+
271|MAILBOX_IS_UNCACHED_NS               | Component |   1        |
272+-------------------------------------+-----------+------------+
273
274
275Secure Partition Manager
276========================
277+----------------------------------------+-----------+-------------+
278| Options                                | Type      | Base Values |
279+========================================+===========+=============+
280|TFM_ISOLATION_LEVEL                     | Build     |   1         |
281+----------------------------------------+-----------+-------------+
282|PSA_FRAMEWORK_HAS_MM_IOVEC              | Build     |   OFF       |
283+----------------------------------------+-----------+-------------+
284|CONFIG_TFM_SPM_BACKEND                  | Build     |   "SFN"     |
285+----------------------------------------+-----------+-------------+
286|TFM_SPM_LOG_LEVEL                       | Build     |   1         |
287+----------------------------------------+-----------+-------------+
288|CONFIG_TFM_STACK_WATERMARKS             | Build     |   OFF       |
289+----------------------------------------+-----------+-------------+
290|CONFIG_TFM_CONN_HANDLE_MAX_NUM          | Component |   8         |
291+----------------------------------------+-----------+-------------+
292|CONFIG_TFM_DOORBELL_API                 | Component |   0         |
293+----------------------------------------+-----------+-------------+
294|CONFIG_TFM_SCHEDULE_WHEN_NS_INTERRUPTED | Component |   0         |
295+----------------------------------------+-----------+-------------+
296|CONFIG_TFM_HYBRID_PLAT_SCHED_TYPE       | Component |   0         |
297+----------------------------------------+-----------+-------------+
298
299--------------
300
301*SPDX-FileCopyrightText: Copyright The TrustedFirmware-M Contributors*
302
303*Copyright (c) 2023-2024 Cypress Semiconductor Corporation (an Infineon company)
304or an affiliate of Cypress Semiconductor Corporation. All rights reserved.*
305
306*SPDX-License-Identifier: BSD-3-Clause*
307