Kconfig System

Kconfig Overview

Organization Structure

The configuration system uses Kconfig to organize. Top Kconfig file under amebaxxx_gcc_project references sub-Kconfig under each component, generating files for CMake. As following figure show:

Mutual references between Kconfig files can use following syntax:
source :

The source statement can reference a path relative to the top-level Kconfig. For example, a top-level Kconfig loacated at ${top_kconfig_path} can use the following statement:
source "subdir/Kconfig"
This will incorporate {top_kconfig_path}/subdir/Kconfig file into the top-level Kconfig. If {top_kconfig_path}/subdir/Kconfig file does not exist, a Kconfig error will pop.
Note

You cannot use an if statement to avoid referencing non-existent files. In the example below, even if DEP is not selected, Kconfig will still attempt to read the contents of Kconfig.other, and an error will occur if Kconfig.other does not exist.
if DEP
   source "Kconfig.other"
endif
osource :

The file path referenced after osource will not cause an error even if it does not exist.

rsource :

The path referenced by rsource is relative to the Kconfig file using the rsource statement, rather than the top-level Kconfig.

orsource :

This statement is based on rsource, allowing the referenced file path to not exist.

Below are some common usages and notice of Kconfig. For more detailed information about Kconfig, please refer to: https://docs.kernel.org/kbuild/kconfig-language.html

Defining Kconfig Symbols

Defining a Kconfig symbol follows the below format:
config FOO
   bool "choose FOO"
   default n
The above Kconfig structure defines a bool type config symbol, which appears in the visualization interface as:
[ ]  choose FOO
"choose FOO" is the prompt text, which will be displayed in the visualization configuration interface. If "choose FOO" is removed, the configuration item will not appear in the visualization interface. Besides bool type, other types such as string, hex, int, etc., can also be defined.

default n indicates “no”, meaning this item will not be selected by default. default n can be omitted. Note that the default value defined by default only takes effect if the user has never touched this config item.

If multiple default values are defined within the same config, then the first valid default value encountered will be used.
Further, conditional expressions can expand Kconfig functionality. For example, the following writing means that when BAR is selected, the FOO item will be displayed in the menu, and when both BAR and TIZ are selected, the default value of FOO will be y.
config FOO
   bool "choose FOO" if BAR
   default y if BAR && TIZ

Dependencies in Kconfig

Adding dependencies with depends on

Through depends on, all entries under this config item can be added with dependencies. The following two writings are equivalent:
config FOO
   depends on BAR
   bool "choose FOO"
   default y

## equal to

config FOO
   bool "choose FOO" if BAR
   default y if BAR
Adding reverse dependencies with select

select forces another config to be selected when a config is chosen, regardless of whether this config has other dependency relationships. For example, in the following example, when BUZZ is selected, FOO will definitely be selected regardless of the value of BAR, and it cannot be deselected through the visualization interface.
config BUZZ
   bool "choose BUZZ"
   select FOO

config FOO
   depends on BAR
   bool "choose FOO"
Note

select can only select bool-type configs.

select is commonly used for invisible configs or those without dependencies.

Invisible Config Items

When no prompt text is defined under a config, this config item is invisible, meaning it cannot be manually selected or deselected by the user. Its value is generally selected through dependency items or defined by default values. For example:
config BAR
   bool "BAR"
   select FOO

config FOO
   bool
   default n

##equal to

config FOO
   bool
   default y if BAR

##also equal to

config FOO
   depends on BAR
   bool
   default y
If it is not a bool type:
config NUM
   int
   default 255 if BAR
   default 65535 if !BAR

Multiple Definitions of config Items

In Kconfig syntax, it is allowed to define the same-named config items in multiple locations. These definitions will be parsed and merged into a single config value and output to .config file. Two examples are provided to illustrate this usage:

Example 1:

config FOO
   bool "FOO"
   select BAR
...

config FOO
   bool # This line can be deleted
   select TIZ

In Example 1, both instances of FOO refer to the same config item. When FOO is selected, both BAR and TIZ will also be selected. The second bool keyword can also be omitted.

Example 2:

config FOO
   bool
   depends on BAR
   default n

...

config FOO
   bool
   depends on TIZ
   default y

In Example 2, both instances of FOO depend on BAR and TIZ, respectively. These dependency conditions only apply to the expressions at their respective positions, which is equivalent to:

config FOO
   bool
   default n if BAR

...

config FOO
   bool
   default y if TIZ

Only when BAR is selected, the value of FOO is n; only when TIZ is selected, the value of FOO is y. When both BAR and TIZ are selected, according to the rule that the first valid default value takes precedence, the value of FOO is n.

Introduction to conf Files

conf File Format

Conf files replace the UI-based menuconfig approach by writing user-defined configuration items into them. Conf files consist of multiple configuration items, each following this format:
CONFIG_<name1>=<value>

CONFIG_<name2>=<value>

...
There should be no spaces around the = sign.

Writing conf Files

The writing style of conf files is similar to .config files, but note that .config files contain all config items, whether they are visible to the user or not. However, conf files can only set config items visible to the user.

Similar to UI menuconfig, this direct configuration method essentially selects/deselects some items defined in Kconfig files, replacing interactive input with parameter input.

For example, consider the following Kconfig:
config SUPPORT_ATCMD
   bool "Enable ATCMD"
   default n
if SUPPORT_ATCMD
   choice
      default ATCMD_MANUAL_TEST
      prompt "ATCMD Mode"
      config ATCMD_MANUAL_TEST
            bool "Manual Test Mode"
      config ATCMD_HOST_CONTROL
            bool "Host Control Mode"
   endchoice
   config ATCMD_NETWORK
      bool "Enable Network"
      default n
   config ATCMD_SOCKET
      bool "Enable Socket"
endif
[*] Enable ATCMD
   ATCMD Mode (Manual Test Mode)  --->
[ ]     Enable Longer CMD
[*]     Enable Network
[ ]     Enable Socket
The corresponding conf file should be written as:
CONFIG_SUPPORT_ATCMD=y

CONFIG_ATCMD_NETWORK=y
Since ATCMD_MANUAL_TEST is the default choice value, it can be omitted in the conf file as CONFIG_ATCMD_MANUAL_TEST=y.

In the {SDK}/amebaxxx_gcc_project/utils/confs_daily_build directory, various common configuration collection files are provided, which users can refer to for creating their own conf files.

Note

Users can save the current configurations as a conf file using menuconfig.py -s.

default.conf

In {SDK}/amebaxxx_gcc_project directory, there is a configuration file named default.conf, defining the initial configuration for building this SOC project.

Specifically, menuconfig.py -f implicitly includes the rule of menuconfig.py -f default.conf, so when users write conf files, they can omit config items already configured in the default.conf file, meaning they only need to write incremental configurations compared to default.conf. If certain options in default.conf need to be disabled, set the corresponding config items to n.

Default values in Kconfig only take effect if a specific config item is not touched, while default.conf files act as a series of default inputs, thus having higher priority than default values in Kconfig.

prj.conf

prj.conf is located under example or the user-created project path, recording the configuration items needed for this example or external project. Users can configure the project using menuconfig.py -f /.../prj.conf. Additionally, when users have not configured through the UI or specified other conf files, prj.conf will be used as the initial configuration.

The priority of prj.conf is higher than that of default.conf.

Kconfig Automatic Update Check

When the Kconfig file or default.conf file is updated (e.g., pulled from a remote repository), but the files in the menuconfig folder are still based on the previous Kconfig, running build.py directly can lead to unexpected behavior. To prevent this, a check for Kconfig updates is performed before each compilation.

The anchor file for this check is menuconfig/.config_default, which is generated based on default.conf before each compilation. It contains the default configuration values for the SOC. If the newly generated menuconfig/.config_default differs from an existing file in the menuconfig folder, the console will display the differences and prompt the user to decide:

If user determines that the Kconfig update can be ignored, press Enter to continue using the current .config configuration.
If user believes ignoring the Kconfig update may affect the compilation results, press Ctrl+C to exit. After exiting, the user can reconfigure using the visualization interface or via menuconfig.py -f, or clean the menuconfig folder using menuconfig.py -c or build.py -p, and then compile using the default configuration.