RIOT/doc/doxygen/src/kconfig/kconfig.md

Kconfig in RIOT

[TOC]

The objective of using Kconfig in RIOT is to configure software modules at compile-time. This means having a standard way of:

• Exposing configurable parameters
• Assigning application and user-specific configurations
• Verifying these parameters
  • Check possible values
  • Check valid configuration considering inter-dependencies
• Applying the selected configuration

Overview

Exposure

Modules in RIOT expose their configurable parameters via Kconfig files (for more information on Kconfig syntax check the specification). In these files documentation, restrictions, default values and dependencies can be expressed.

Kconfig files are structured through the file system mirroring the current module distribution. In time, all modules will have Kconfig files to make themselves configurable through this system.

Assignment

The user can assign values to the exposed parameters, either by manually writing '.config' files or using an interface such as Menuconfig. Parameters with no assigned values will take the default ones. For a detailed distinction between Kconfig and '.config' files see Appendix B.

Verification and application

Using '.config' and Kconfig files the build system takes care of doing the necessary checks on the values according to the parameter definition. After that, the autoconf.h header file is generated, it contains all the configurations in the form of (CONFIG_ prefixed) macros.

---

User's guide to configure with Kconfig

Configure using menuconfig

In order to use the graphical interface menuconfig to configure the application, run make menuconfig in the application's folder. All available configurations (based on the used modules) for the particular platform will be presented. By default, the configuration of a module via Kconfig is not enabled. In order to activate the configuration via Kconfig the corresponding option should be selected. That will enable the configuration of all inner options, if available.

Once the desired configuration is achieved save the configuration to the default proposed path and exit. The saved configuration will be applied when the code is compiled (make all).

If the current configuration will be used in the future it can be saved in the application's folder as user.config, using the 'Save' option in menuconfig. This way it will be persistent after cleaning the application directory (make clean).

Configure using '.config' files

The second way to configure the application is by directly writing '.config' files. Two files will be sources of configuration during the generation of the final header file: app.config and user.config, which should be placed inside the application's folder. app.config sets default configuration values for the particular application, the user can override them by setting them in user.config.

Let's say that the SOCK_UTIL_SCHEME_MAXLEN symbol in sock_util module needs to be configured. The user.config file could look like:

# activate configuration of sock_util using Kconfig
CONFIG_KCONFIG_MODULE_SOCK_UTIL=y
# change scheme part length
CONFIG_SOCK_UTIL_SCHEME_MAXLEN=24

In this case, there is no need for using menuconfig. It's enough just to call make all in the application folder, as this configuration will be read and applied. Note that if any dependency issue occurs, warnings will be generated (e.g. not enabling the configuration of a module via Kconfig).

Application configuration with Kconfig

To expose application-specific configuration options a Kconfig file can be placed in the application's folder. For an example of this you can check the tests/kconfig application.

A note on the usage of CFLAGS

When a certain module is being configured via Kconfig the configuration macro will not longer be overridable by means of CFLAGS (e.g. set on the compilation command or on a Makefile). Consider this if you are getting a 'redefined warning'.

A note on the usage of the 'clean' command

When using Kconfig as the configurator for RIOT, configuration symbols may be used in Makefiles through the build system. For this to work properly make sure that when cleaning an application you call make clean && make all, instead of make clean all.

---

Integration into the build system

The integration of Kconfig into the build system is mainly done in makefiles/kconfig.mk.

Steps during the build process

0. Module dependency resolution

Currently, the resolution of module dependencies is performed by the build system where all the used modules and packages end up listed in the USEMODULE make variables. In the next phases of integration we plan to resolve dependencies using Kconfig.

Input

• Makefiles.

Output

• USEMODULE and USEPKG variables.

1. Module listing

The list of modules needed for the particular build is dumped into the $ (GENERATED_DIR)/Kconfig.dep file, where each module is translated into a Kconfig symbol as documented in Appendix A.

Input

• USEMODULE and USEPKG variables

Output

• $ (GENERATED_DIR)/Kconfig.dep file

2. Merging all configuration sources

In this step configuration values are taken from multiple sources and merged into a single merged.config configuration file. This file is temporary and is removed on clean. If the user needs to save a particular configuration set, a backup has to be saved (this can be done using the menuconfig interface) so it can be loaded later in this step.

To accomplish merging of multiple input files, the mergeconfig script is used. Note that the order matters: existing configuration values are merged in the order expressed in the input section, where the last value assigned to a parameter has the highest priority. If no configuration files are available all default values will be applied.

merged.config is the only configuration input for the autoconf.h in the generation step.

Input

• Optional:
  • $ (APPDIR)/app.config: Application specific default configurations.
  • $ (APPDIR)/user.config: Configurations saved by user.

Output

• $ (GENERATED_DIR)/merged.config file.

3. Menuconfig execution (optional)

Menuconfig is a graphical interface for software configuration. It is used for the configuration of the Linux kernel. This section explains the process that occurs when RIOT is being configured using the menuconfig interface.

The main Kconfig file is used in this step to show the configurable parameters of the system. Kconfig will filter innaplicable parameters (i.e. parameters exposed by modules that are not being used) based on the file $ (GENERATED_DIR)/Kconfig.dep generated in step 1.

During the transition phase, the user needs to enable Kconfig explicitly per module, by setting the corresponding option. If using menuconfig a checkbox with a submenu has to be selected, if using .config files a CONFIG_KCONFIG_MODULE_ prefixed option has to be set to y. For more information see Making configuration via Kconfig optional.

Note that if Kconfig is not used to configure a module, the corresponding header files default values will be used.

merged.config is one of the inputs for menuconfig. This means that any configuration that the application defines in the app.config or a backup configuration from the user in user.config are taken into account on the first run (see Appendix C).

In this step the user chooses configuration values (or selects the minimal configuration) and saves it to the merged.config file. Here the user can choose to save a backup configuration file for later at a different location (e.g. a user.config file in the application folder).

Input

• /Kconfig file.
• Optional:
  • $ (APPDIR)/app.config
  • $ (APPDIR)/user.config
  • $ (GENERATED_DIR)/merged.config

Output

• Updated $ (GENERATED_DIR)/merged.config file.
• $ (GENERATED_DIR)/merged.config.old backup file.

4. Generation of the autoconf.h header

With the addition of Kconfig a dependency has been added to the build process: the $ (GENERATED_DIR)/autoconf.h header file. This header file is the main output from the Kconfig configuration system. It holds all the macros that should be used to configure modules in RIOT: CONFIG_<module>_<parameter>.

In order to generate the autoconf.h file the genconfig script is used. Inputs for this script are the main Kconfig file and merged.config configuration file, which holds the selected values for the exposed parameters.

Input:

• $ (GENERATED_DIR)/merged.config file.
• Main Kconfig file exposing configuration of modules.

Output:

• $ (GENERATED_DIR)/autoconf.h configuration header file.

Summary of files

These files are defined in kconfig.mk.

File	Description
Kconfig	Defines configuration options of modules.
Kconfig.dep	Holds a list of the modules that are being compiled.
app.config	Holds default application configuration values.
user.config	Holds configuration values applied by the user.
merged.config	Holds configuration from multiple sources. Used to generate header.
autoconf.h	Header file containing the macros that applied the selected configuration.

Kconfig symbols in Makefiles

As '.config' files have Makefile syntax they can be included when building, which allows to access the applied configuration from the build system and, in the future, to check for enabled modules.

During migration this is also useful, as it gives the ability to check if a parameter is being configured via Kconfig or a default value via CFLAGS could be injected. For example:

ifndef CONFIG_USB_VID
  CFLAGS += -DCONFIG_USB_VID=0x1209
endif

Symbols will have the same name as the configuration macros (thus will always have the CONFIG_ prefix). As the configuration file is loaded in Makefile.include care should be taken when performing checks in the application's Makefile. The symbols will not be defined until after including Makefile.include.

---

Transition phase

Making configuration via Kconfig optional

During transition to the usage of Kconfig as the main configurator for RIOT, the default behavior will be the traditional one: expose configuration options in header files and use CFLAGS as inputs. To allow optional configuration via Kconfig, a convention will be used when writing Kconfig files.

Modules should be contained in their own menuconfig entries, this way the user can choose to enable the configuration via Kconfig for an specific module. These entries should define a dependency on the module they configure (see Appendix A to see how to check if a module is being used).

The module configuration then can be enabled either via the menuconfig interface:

or by means of a '.config' file:

CONFIG_KCONFIG_MODULE_GCOAP=y

---

Appendixes

Appendix A: Check if a module or package is used

In order to show only the relevant configuration parameters to the user with respect to a given application and board selection, Kconfig needs knowledge about all modules and packages to be used for a compilation. Currently dependency handling among modules is performed by the build system (via Makefile.dep files). The interface defined to declared the used modules and packages is the $ (GENERATED_DIR)/Kconfig.dep file.

Kconfig.dep is a Kconfig file that will define symbols of the form:

config MODULE_SOCK_UTIL
    bool
    default y

There will be a symbol for every used module (i.e. every module in USEMODULE make variable) and package. The names in the symbols will be uppercase and separated by _. Based on these symbols configurability is decided. Modules and packages symbols will have MODULE_ and PKG_ prefixes respectively.

The following is an example of how to use these symbols in Kconfig files to enable/disable a configuration menu:

menuconfig KCONFIG_MODULE_SOCK_UTIL
    bool "Configure Sock Utilities"
    depends on MODULE_SOCK_UTIL
    help
        "Configure Sock Utilities using Kconfig."

Then, every configuration option for the previous module would be modeled like:

if KCONFIG_MODULE_SOCK_UTIL

config SOCK_UTIL_SCHEME_MAXLEN
    int "Maximum length of the scheme part for sock_urlsplit"
    default 16

endif # KCONFIG_MODULE_SOCK_UTIL

Appendix B: Difference between 'Kconfig' and '.config' files

Kconfig files describe a configuration database, which is a collection of configuration options organized in a tree structure. Configuration options may have dependencies (among other attributes), which are used to determine their visibility.

Kconfig files are written in Kconfig language defined in the Linux kernel. Configuration options have attributes such as types, prompts and default values.

Kconfig file

menu "Buffer Sizes"

config GCOAP_PDU_BUF_SIZE
    int "Request or response buffer size"
    default 128

endmenu

On the other hand configuration files contain assignment of values to configuration options and use Makefile syntax. They can also be used to save a set of configuration values as backup.

'.config' file

# enable Kconfig configuration for gcoap
CONFIG_KCONFIG_MODULE_GCOAP=y
# set the value
CONFIG_GCOAP_PDU_BUF_SIZE=12345

In other words: Kconfig files describe configuration options and '.config' files assign their values.

Appendix C: Pitfall when using different configuration interfaces

In the current configuration flow the user can choose to configure RIOT using the menuconfig graphical interface or writing '.config' files by hand.

As explained in the 'Configuration sources merging step' of the configuration process, configuration from multiple sources are loaded to create a single merged.config file, and the order of merging matters: last file has priority.

While editing values directly via '.config' files merged.config will be re-built. Once the user decides to edit merged.config directly using menuconfig, the file will not be re-built anymore, and any changes by manually editing the source files will have no effect. To go back to manual edition a make clean has to be issued in the application directory.

Useful references

• Kconfig language specification
• Kconfig macro language specification
• Kconfig - Tips and Best Practices