Kconfig Tool: Support input ENV. and config files loading
The Kconfig tool now supports loading config files and merging them
into one. The merging is basically done by the later loaded config files
overriding the first loaded config files with dependencies respected.
With this feature, the Kconfig system will be aware of the configs such
as platform settings and profile settings rather than having default
values for all configurations.
The environment variables are for the Kconfig files which refer to env.
variables, for example the PLATFORM_PATH.
Now the PLATFORM_PATH is no longer passed as one of the arguments, it's
done via the --env argument now. Of course, any other env. variables can
be appended at will.
Change-Id: Ib39e13b29def382a9546cd7680c62a4f4d321f99
Signed-off-by: Kevin Peng <kevin.peng@arm.com>
diff --git a/docs/configuration/kconfig_system.rst b/docs/configuration/kconfig_system.rst
index f4fa257..a4b2caf 100644
--- a/docs/configuration/kconfig_system.rst
+++ b/docs/configuration/kconfig_system.rst
@@ -3,30 +3,32 @@
##################
The Kconfig System
##################
-The Kconfig system is an additional tool for users to change configuration options of TF-M.
+The Kconfig system is an alternative tool to the CMake config system for users to change config
+options of TF-M.
.. figure:: kconfig_header_file_system.png
It handles dependencies and validations automatically when you change configurations so that the
generated configuration options are always valid.
-It consists of `The Kconfig tool`_ and the `The Kconfig files`_.
+To use the Kconfig system, enable ``USE_KCONFIG_TOOL`` in commande line.
+And enable ``MENUCONFIG`` to launch configuration GUI.
+
+The Kconfig system consists of `The Kconfig tool`_ and the `The Kconfig files`_.
****************
The Kconfig tool
****************
The Kconfig tool is a python script based on `Kconfiglib <https://github.com/ulfalizer/Kconfiglib>`__
-to launch the menuconfig interfaces and generate the following config files:
+to generate the following config files:
- CMake config file
Contains CMake cache variables of building options.
- This file should be passed to the build system via command line option ``TFM_EXTRA_CONFIG_PATH``.
- Header file
Contains component options in the header file system.
- This file should be passed to the build system via the command line option ``PROJECT_CONFIG_HEADER_FILE``.
Component options are gathered together in a seperate menu ``TF-M component configs`` in
`The Kconfig files`_.
@@ -38,59 +40,74 @@
The Kconfig tool will load it if it exists and ``.config.old`` will be created to
save the previous configurations.
-How To Use
-==========
-The script takes four arguments at maximum.
+The tool supports loading multiple pre-set configuration files merging into a single one.
+The first loaded options are overridden by later ones if the config files contain duplicated
+options.
+And dependencies between config options are taken care of.
+It then launchs a configuration GUI for users to change any config options if the ``MENUCONFIG`` is
+enabled in build command line.
-- '-k', '--kconfig-file'
+Integration with TF-M build system
+----------------------------------
+TF-M build system includes ``kconfig.cmake`` to integrate this tool.
+It prepares the parameters for the script and invokes it to load multiple configuration files basing
+on your build setup, including but not limited to
- Required. The root Kconfig file.
+ - Build type bound configurations, decided by ``CMAKE_BUILD_TYPE``
+ - Profile configurations, decided by ``TFM_PROFILE``
-- '-u', '--ui'
+**************************
+Customizing config options
+**************************
+By default, the Kconfig system only merges configuration files and generated the final config files.
+To customize the config options, there are several approaches.
- Optional. The menuconfig interface to launch, ``gui`` or ``tui``.
- Refer to `Menuconfig interfaces <https://github.com/ulfalizer/Kconfiglib#menuconfig-interfaces>`__
- for interface details. Only the first two are supported.
- If no UI is selected, the tool generates config files with default values.
+Menuconfig
+----------
+Menuconfig is the recommended approach to adjust the values of the config options because it has
+a graphic interface for you to easily change the options without worrying about dependencies.
-- '-o', '--output_path'
-
- Required. The output directory to hold the generated files.
-
-- '-p', '--platform-path'
-
- Optional. The platform specific Kconfig or defconfig files.
-
-Here is an example:
+To launch the menuconfig, you need to enable ``MENUCONFIG`` in addition to enabling
+``USE_KCONFIG_TOOL``.
.. code-block:: bash
- cd trusted-firmware-m
- python3 tools/kconfig/tfm_kconfig.py -k Kconfig -o <output_path> -u tui
-
- # If the platform path has defconfig or Kconfig, use '-p' to load them.
- python3 tools/kconfig/tfm_kconfig.py -k Kconfig -o <output_path> -p platform/ext/target/arm/mps2/an521
-
-The script can be used as a standalone tool. You can pass the config files to
-build system via command line option ``TFM_EXTRA_CONFIG_PATH`` and
-``PROJECT_CONFIG_HEADER_FILE`` respectively, as mentioned above.
-
-.. code-block:: bash
-
- # Pass the files generated by script.
- <cmake build command> -DTFM_EXTRA_CONFIG_PATH=<output_path>/project_config.cmake \
- -DPROJECT_CONFIG_HEADER_FILE=<output_path>/project_config.h
-
-The TF-M build system has also integrated the tool.
-You only need to set ``USE_KCONFIG_TOOL`` to ``ON/TRUE/1`` in commande line and CMake will launch
-the GUI menuconfig for users to adjust configurations and automatically load the generated config
-files.
+ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 \
+ -DUSE_KCONFIG_TOOL=ON \
+ -DMENUCONFIG=ON
.. note::
- - Only GUI menuconfig can be launched by CMake for the time being.
- - Due to the current limitation of the tool, you are not allowed to change the values of build
- options that of which platforms have customized values. And there is no prompt messages either.
+ Although the Kconfiglib provides three
+ `menuconfig interfaces <https://github.com/ulfalizer/Kconfiglib#menuconfig-interfaces>`__,
+ only GUI menuconfig can be launched by CMake for the time being.
+
+Command line options
+--------------------
+The support of passing configurations via command line is kept for the Kconfig system.
+
+.. code-block:: bash
+
+ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 \
+ -DUSE_KCONFIG_TOOL=ON \
+ -DTFM_ISOLATION_LEVEL=2
+
+Kconfig file
+------------
+You can also put the frequently used config options into a Kconfig file. When you need to apply the
+config options in that file, pass it via command line option ``-DKCONFIG_CONFIG_FILE``
+
+.. code-block:: bash
+
+ cmake -S . -B cmake_build -DTFM_PLATFORM=arm/mps2/an521 \
+ -DTFM_ISOLATION_LEVEL=2 \
+ -DUSE_KCONFIG_TOOL=ON \
+ -DKCONFIG_CONFIG_FILE=my_config.conf
+
+.. note::
+
+ The command line set options override the ones in the config file.
+ And you can always launch menuconfig to do the final adjustments.
*****************
The Kconfig files
@@ -103,4 +120,4 @@
--------------
-*Copyright (c) 2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*