1.. _Kconfig_system:
2
3##################
4The Kconfig System
5##################
6The Kconfig system is an alternative tool to the CMake config system for users to change config
7options of TF-M.
8
9.. figure:: kconfig_header_file_system.svg
10
11It handles dependencies and validations automatically when you change configurations so that the
12generated configuration options are always valid.
13
14To use the Kconfig system, enable ``USE_KCONFIG_TOOL`` in command line.
15And enable ``MENUCONFIG`` to launch configuration GUI.
16
17The Kconfig system consists of `The Kconfig tool`_ and the `The Kconfig files`_.
18
19****************
20The Kconfig tool
21****************
22The Kconfig tool is a python script based on `Kconfiglib <https://github.com/ulfalizer/Kconfiglib>`__
23to generate the following config files:
24
25- CMake config file
26
27  Contains CMake cache variables of building options.
28
29- Header file
30
31  Contains component options in the header file system.
32  Component options are gathered together in a separate menu ``TF-M component configs`` in
33  `The Kconfig files`_.
34
35- The .config and .config.old files
36
37  The ``.config`` file which contains all the above configurations in the Kconfig format.
38  It will be created after the first execution of the script. It is only used to allow
39  users to make adjustments basing on the previous settings.
40  The Kconfig tool will load it if it exists and ``.config.old`` will be created to
41  save the previous configurations.
42
43The tool supports loading multiple pre-set configuration files merging into a single one.
44The first loaded options are overridden by later ones if the config files contain duplicated
45options.
46And dependencies between config options are taken care of.
47It then launches a configuration GUI for users to change any config options if the ``MENUCONFIG`` is
48enabled in build command line.
49
50Integration with TF-M build system
51----------------------------------
52TF-M build system includes ``kconfig.cmake`` to integrate this tool.
53It prepares the parameters for the script and invokes it to load multiple configuration files basing
54on your build setup, including but not limited to
55
56  - Build type bound configurations, decided by ``CMAKE_BUILD_TYPE``
57  - Profile configurations, decided by ``TFM_PROFILE``
58
59**************************
60Customizing config options
61**************************
62By default, the Kconfig system only merges configuration files and generated the final config files.
63To customize the config options, there are several approaches.
64
65Menuconfig
66----------
67Menuconfig is the recommended approach to adjust the values of the config options because it has
68a graphic interface for you to easily change the options without worrying about dependencies.
69
70To launch the menuconfig, you need to enable ``MENUCONFIG`` in addition to enabling
71``USE_KCONFIG_TOOL``.
72
73.. code-block:: bash
74
75  cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 \
76                            -DUSE_KCONFIG_TOOL=ON \
77                            -DMENUCONFIG=ON
78
79.. note::
80
81  Although the Kconfiglib provides three
82  `menuconfig interfaces <https://github.com/ulfalizer/Kconfiglib#menuconfig-interfaces>`__,
83  only GUI menuconfig can be launched by CMake for the time being.
84
85Command line options
86--------------------
87The support of passing configurations via command line is kept for the Kconfig system.
88
89.. code-block:: bash
90
91  cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 \
92                            -DUSE_KCONFIG_TOOL=ON \
93                            -DTFM_ISOLATION_LEVEL=2
94
95Kconfig file
96------------
97You can also put the frequently used config options into a Kconfig file. When you need to apply the
98config options in that file, pass it via command line option ``-DKCONFIG_CONFIG_FILE``
99
100.. code-block:: bash
101
102  cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 \
103                            -DTFM_ISOLATION_LEVEL=2 \
104                            -DUSE_KCONFIG_TOOL=ON \
105                            -DKCONFIG_CONFIG_FILE=my_config.conf
106
107.. note::
108
109  The command line set options override the ones in the config file.
110  And you can always launch menuconfig to do the final adjustments.
111
112*****************
113The Kconfig files
114*****************
115The Kconfig files are the files written by the
116`Kconfig language <https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html#kconfig-language>`__
117to describe config options.
118They also uses some Kconfiglib extensions such as optional source ``osource`` and relative source ``rsource``
119so they can only work with the Kconfiglib.
120
121--------------
122
123*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*
124