Kconfig is a tool used in coreboot, Linux, and many other projects as the main configuration mechanism. In coreboot, it allows a developer both to select which platform to build and to modify various features within the platform. The Kconfig language was developed as a way to configure the Linux kernel, and is still maintained as a part of the Linux kernel tree. Starting in Linux 2.5.45, the ncurses based menuconfig was added, which is still used as the main configuration front end in coreboot today.
The official Kconfig source and documentation is kept at kernel.org:
The advantage to using Kconfig is that it allows users to easily select the high level features of the project to be enabled or disabled at build time. Ultimately the Kconfig tool generates a list of values which are used by the source code and Makefiles of the project. This allows the source files to select features, and allows the build to determine which files should be compiled and linked to the rom.
The Kconfig program in coreboot is built from source in util/kconfig. There are various targets in the makefile to build Kconfig in different ways. These give the user control over how to build the platform
These are the make targets that would be used to update the configuration of the platform.
These options are used to update the coreboot config files, typically .config. The target file can be changed with variables in the environment or on the make command line.
These variables are typically set in the makefiles or on the make command line.
These variables were added to Kconfig specifically for coreboot and are not included in the Linux version.
COREBOOT_BUILD_DIR=path for temporary files. This is used by coreboot’s abuild tool.
KCONFIG_STRICT=value. Define to enable warnings as errors. This is enabled in coreboot, and should not be changed.
KCONFIG_NEGATIVES=value. Define to show negative values in the autoconf.h file (build/config.h). This is enabled in coreboot, and should not be changed.
KBUILD_DEFCONFIG=inputname of the defconfig file. This defaults to ‘configs/defconfig’ and is used by the ‘defconfig’ target.
DEFCONFIG=output name of the defconfig file. This defaults to ‘defconfig’ and is used by ‘savedefconfig’ target as the output filename.
DOTCONFIG=name of the .config file. This defaults to '.config' and is used by most config type targets.
Kconfig=root Kconfig file. This is set to 'src/Kconfig' in the coreboot makefile.
KCONFIG_CONFIG=input config file. coreboot sets this to $(DOTCONFIG).
KCONFIG_AUTOHEADER=path and filename of autoconf.h file. coreboot sets this to $(obj)/config.h.
KCONFIG_DEPENDENCIES=”kbuild dependency file". This defaults to auto.conf.cmd and outputs the name of all of the Kconfig files used.
KCONFIG_SPLITCONFIG=”directory name for individual SYMBOL.h files”. coreboot sets this to $(obj)/config.
MENUCONFIG_MODE=single_menu. Set to "single_menu" to enable. All other values disable the option. This makes submenus appear below the menu option instead of opening a new screen.
MENUCONFIG_COLOR=<theme>. This sets the color theme for the menu from these options:
Submenus appear below the menu option instead of opening a new screen.
Although these variables are not used by coreboot, their values should be left at the default values. Other values may have unexpected effects on the codebase.
KCONFIG_SEED=randconfig seed value.
KCONFIG_PROBABILITY=randconfig percent to set to y.
KCONFIG_NOSILENTUPDATE=value. Define to prevent silent updates to .config file.
KCONFIG_OVERWRITECONFIG=value. Define to prevent breaking a .config symlink.
KCONFIG_TRISTATE=filename of tristate.conf file.
SRCTREE=path to src directory.
KCONFIG_AUTOCONFIG=path and filename of the auto.conf file.
coreboot sets this to $(obj)/auto.conf. Although this value is actually set by coreboot, the resulting file is not used.
CONFIG_=prefix for Kconfig output symbols.
coreboot expects this to NOT be set.
The Kconfig language has about 30 keywords, some overloaded, and some with the same meaning. Whitespace may have specific meaning, for example in the 'help' keyword. There are 8 logical operators for use in expressions, which allow values to be set based on other values.
Symbols - There are two types of symbols, "constant" and “non-constant”.
Expressions - An expression is a logical evaluation. It can be as simple as a static 'y' or 'n', or can be a symbol. Alternatively, expressions can be complex evaluations of multiple symbols using the various logical operators. The Kconfig language allows these logical evaluations in several places. The most common use for complex expressions is following 'if' or ‘depends on’ keywords, but they can also be used to set the value for a prompt or default values.
Types - Each Kconfig symbol is one of the following types: bool, hex, int, string, or tristate. The tristate type is not used for coreboot, leaving just four types. As noted in the keyword summaries, a symbol must have a consistent type anywhere it is defined. Also, Kconfig will simply not display a symbol that has no type defined. A warning will be displayed in the terminal where menuconfig was run if this happens: src/Kconfig:25:warning: config symbol defined without type.
Prompts - Input prompts are the text associated with the symbols which shown to the user. The Kconfig language definition does not require surrounding the prompt’s text with quotes, however it is recommended that quotes be used for maximum compatibility.
Menu Entries - These keyword blocks create the symbols and questions that are visible in the front end.
The 'bool' keyword assigns a boolean type to a symbol. The allowable values for a boolean type are 'n' or 'y'. The keyword can be followed by an optional prompt string which makes the symbol editable in one of the configuration front ends.
bool [prompt] [if <expr>]
config ANY_TOOLCHAIN bool "Allow building with any toolchain" default n depends on COMPILER_GCC
This creates a selection list of one or more boolean symbols. For bools, only one of the symbols can be selected, and one will be be forced to be selected, either by a ‘default’ statement, or by selecting the first config option if there is no default value listed.
choice TESTCHOICE prompt "Test choice" default TESTCHOICE2 if TESTCHOICE_DEFAULT_2 default TESTCHOICE3 config TESTCHOICE1 bool "Choice 1" config TESTCHOICE2 bool "Choice 2" config TESTCHOICE3 bool "Choice 3" config TESTCHOICE4 bool "Choice 4" if TESTCHOICE_SHOW_4 endchoice config TESTCHOICE_DEFAULT_2 def_bool y config TESTCHOICE_SHOW_4 def_bool n config TESTSTRING string default “String #1” if TESTCHOICE1 default “String #2” if TESTCHOICE2 default “String #4” if TESTCHOICE3 default “String #4” if TESTCHOICE4 default “”
This keyword defines a line of text that is displayed to the user in the configuration frontend and is additionally written to the output files.
if CONSOLE_SERIAL comment "I/O mapped, 8250-compatible" depends on DRIVERS_UART_8250IO endif
This is the keyword that starts a block defining a Kconfig symbol. The symbol modifiers follow the 'config' statement.
config SEABIOS_PS2_TIMEOUT prompt "PS/2 keyboard timeout" if PAYLOAD_SEABIOS default 0 depends on PAYLOAD_SEABIOS int help Some PS/2 keyboard controllers don't respond to commands immediately after powering on. This specifies how long SeaBIOS will wait for the keyboard controller to become ready before giving up.
Non-coreboot projects also use the 'tristate' and 'def_tristate' types.
Ends at the next Kconfig keyword that is not valid inside the config block:
menu | endmenu | if | endif | choice | config | source | comment
The ‘default’ keyword assigns a value to a symbol in the case where no preset value exists, i.e. the symbol is not present and assigned in .config. If there is no preset value, and no ‘default’ keyword, the user will be asked to enter a valid value when building coreboot.
default <expr> [if <expr>]
config GENERATE_MP_TABLE prompt "Generate an MP table" if HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC bool default HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC help Generate an MP table (conforming to the Intel MultiProcessor specification 1.4) for this board.
‘def_bool’ is similar to the 'bool' keyword in that it sets a symbol’s type to boolean. It lets you set the type and default value at the same time, instead of setting the type and the prompt at the same time. It's typically used for symbols that don't have prompts.
def_bool <expr> [if <expr>]
config EC_GOOGLE_CHROMEEC_LPC depends on EC_GOOGLE_CHROMEEC && ARCH_X86 def_bool y select SERIRQ_CONTINUOUS_MODE help Google Chrome EC via LPC bus.
This defines a dependency for a menu entry, including symbols and comments. It behaves the same as surrounding the menu entry with an if/endif block. If the ‘depends on’ expression evaluates to false, the 'prompt' value will not be printed, and defaults will not be set based on this block.
depends on <expr>
config COMMON_CBFS_SPI_WRAPPER bool default n depends on SPI_FLASH depends on !ARCH_X86 help Use common wrapper to interface CBFS to SPI bootrom.
This ends a choice block. See the 'choice' keyword for more information and an example.
This ends a block started by the 'if' keyword. See the 'if' keyword for more information and an example.
This ends a menu block. See the 'menu' keyword for more information and an example.
The 'help' keyword defines the subsequent block of text as help for a config or choice block. The help block is started by the 'help' keyword on a line by itself, and the indentation level of the next line controls the end of the help block. The help ends on the next non-blank line that has an indentation level less than the indentation level of the first line following the 'help' keyword.
help <help text>
config COMPILER_GCC bool "GCC" help Use the GNU Compiler Collection (GCC) to build coreboot. For details see http://gcc.gnu.org.
This is another symbol type specifier, specifying an unsigned integer value formatted as hexadecimal.
hex <expr> [if <expr>]
config INTEL_PCH_UART_CONSOLE_NUMBER hex "Serial IO UART number to use for console" default 0x0 depends on INTEL_PCH_UART_CONSOLE
The 'if' keyword is overloaded, used in two different ways. The first definition enables and disables various other keywords, and follows the other keyword definition. This usage is shown in each of the other keywords' usage listings.
The second usage of the 'if' keyword is part of an if/endif block. Most items within an if/endif block are not evaluated, while others, such as the 'source' keyword, ignore the existence of the if/endif block completely. Symbols defined within an if/endif block are still created, although their default values are ignored - all values are set to 'n'.
if ARCH_X86 config SMP bool default y if MAX_CPUS != 1 default n help This option is used to enable certain functions to make coreboot work correctly on symmetric multi processor (SMP) systems. endif
A type setting keyword, defines a symbol as an integer, accepting only signed numeric values. The values can be further restricted with the ‘range’ keyword.
int <expr> [if <expr>]
config PRE_GRAPHICS_DELAY int "Graphics initialization delay in ms" default 0 help On some systems, coreboot boots so fast that connected monitors (mostly TVs) won't be able to wake up fast enough to talk to the VBIOS. On those systems we need to wait for a bit before executing the VBIOS.
The 'mainmenu' keyword sets the title or title bar of the configuration front end, depending on how the configuration program decides to use it. It can only be specified once and at the very beginning of the top level Kconfig file, before any other statements.
mainmenu "coreboot configuration"
The 'menu' and 'endmenu' keywords tell the configuration front end that the enclosed statements are part of a group of related pieces.
menu "On-Chip Device Power Down Control" config TEMP_POWERDOWN bool "Temperature sensor power-down" config SATA_POWERDOWN bool "SATA power-down" config ADC_POWERDOWN bool "ADC power-down" config PCIE0_POWERDOWN bool "PCIE0 power-down" config MAC_POWERDOWN bool "MAC power-down" config USB1_POWERDOWN bool "USB2.0 Host Controller 1 power-down" config IDE_POWERDOWN bool "IDE power-down" endmenu
The 'prompt' keyword sets the text displayed for a config symbol or choice in configuration front end.
prompt <prompt> [if <expr>]
config REALMODE_DEBUG prompt "Enable debug messages for option ROM execution" bool default n depends on PCI_OPTION_ROM_RUN_REALMODE depends on DEFAULT_CONSOLE_LOGLEVEL_7 || DEFAULT_CONSOLE_LOGLEVEL_8 help This option enables additional x86emu related debug messages. Note: This option will increase the time to emulate a ROM. If unsure, say N.
The same rules apply for menu entries defined by the 'prompt' keyword and other prompt types such as those defined by the 'int' or 'string' keywords.
Redefining the prompt text in multiple instances of config symbols is allowed. Only the current prompt statement for a particular entry will be displayed by the front end in any given location. This means that multiple mainboards can set different prompt values for a symbol, and it would appear differently in each mainboard’s menu. The symbol can even have multiple entries in the same menu with different prompts if desired. For example, both of these would get printed, and changing either entry would change the other.
config PROMPT_TEST string "Prompt value 1" config PROMPT_TEST prompt "Prompt value 2"
Although not required, it's recommended that you use quotes around prompt statements.
If the prompt is redefined inside the SAME config entry, you will get a warning: warning: prompt redefined. For example, this is not allowed:
config PROMPT_TEST string "Prompt value 1" prompt "Prompt value 2"
This sets the allowable minimum and maximum entries for hex or int type config symbols.
range <symbol> <symbol> [if <expr>]
config TEST1 hex "test 1" range 0x0 0x10
The ‘select’ keyword is used within a bool type config block. In coreboot (and other projects that don't use modules), the 'select' keyword can force an unassociated bool type symbol to 'y'. When the symbol for the config block is ‘y’, the ‘select’ action is taken. Otherwise the bool is unaffected.
select <symbol> [if <expr>]
config TPM bool default n select LPC_TPM if ARCH_X86 select I2C_TPM if ARCH_ARM select I2C_TPM if ARCH_ARM64 help Enable this option to enable TPM support in coreboot. If unsure, say N.
Using the 'select' keyword can create logical contradictions in Kconfig, which will create warnings and fail to save the .config. Following is an example of an obviously invalid configuration, where selecting BOOLTEST violates the ‘depends on’ of BOOLTEST2:
config BOOLTEST bool "bool Test" select BOOLTEST2 config BOOLTEST2 bool "Bool Test 2" depends on !BOOLTEST
The 'source' keyword functions much the same as an 'include' statement in c. This pulls one or more files into Kconfig at the location of the 'source' command. This statement is always parsed - there is no way to conditionally source a file. coreboot has modified the source statement slightly to handle directory globbing. The '*' character will match with any directory.
choice prompt "Mainboard vendor" default VENDOR_EMULATION source "src/mainboard/*/Kconfig.name" endchoice source "src/mainboard/*/Kconfig"
The coreboot Kconfig structure uses this along with globbing to build up the mainboard directory. Each mainboard’s Kconfig.name file contains just two statements that generate a list of all the platform names:
config BOARD_AMD_NORWICH bool "Norwich"
The last of the symbol type assignment keywords. 'string' allows a text value to be entered.
string <expr> [if <expr>]
config BOOTBLOCK_SOUTHBRIDGE_INIT string default "southbridge/amd/pi/hudson/bootblock.c" config HUDSON_GEC_FWM_FILE string "GEC firmware path and filename" depends on HUDSON_GEC_FWM
The config.h file is a very basic header file made up of a list of #define statements:
#define SYMBOL NAME XXX
The config.h file uses 0 and 1 to represent Kconfig's 'n' and 'y' values respectively. String values are placed inside double quotes.
The name of the file is controlled by the $KCONFIG_AUTOHEADER environment variable, which is set to $(obj)/config.h by the coreboot makefiles.
The prefix used for the symbols is controlled by the $CONFIG_ environment variable. This is not set in coreboot, which uses the default CONFIG_ prefix for all of its symbols.
The coreboot makefile forces the config.h file to be included into all coreboot C files. This is done in Makefile.inc on the compiler command line using the “-include $(obj)/config.h” command line option.
Example of various symbol types in the config.h file:
#define CONFIG_BOOTBLOCK_SOURCE "bootblock_simple.c" # String #define CONFIG_CBFS_SIZE 0x00300000 # Hex #define CONFIG_TTYS0_BAUD 115200 # Int #define CONFIG_HAVE_ACPI_TABLES 1 # Bool enabled #define CONFIG_EXPERT 0 # Bool disabled #define CONFIG_NORTHBRIDGE_INTEL_I440LX 0 # Bool excluded
The .config file in the root directory is used as the input file, but also by the makefiles to set variable values. The main difference is that it does not contain all of the symbols. It excludes symbols defined in an if/endif block whose expression evaluated as false. Note that the symbol CONFIG_NORTHBRIDGE_INTEL_I440LX shown in the config.h example above is not present in the .config file.
In addition, the .config file below contains the 'comment' prompt text from the Kconfig, separating the blocks.
## General setup ## CONFIG_BOOTBLOCK_SOURCE="bootblock_simple.c" # String CONFIG_CBFS_SIZE=0x00300000 # Hex CONFIG_TTYS0_BAUD=115200 # Int CONFIG_HAVE_ACPI_TABLES=y # Bool enabled # CONFIG_EXPERT is not set # Bool disabled
This file is included directly by the makefile, and sets the CONFIG symbols so that they are available during the build process.
Although the controlling variable for the auto.conf filename, KCONFIG_AUTOCONFIG, is set in the coreboot makefiles, the auto.conf file itself is not used by coreboot. This file has the same syntax and structure as the .config file, but contains all symbols in the Kconfig tree, including those that are not enabled, or are excluded by if/endif blocks, or the 'depends on' keyword. The kconfig tool could be updated to not generate this file, but since it's not hurting anything, it's still being generated.
Miniconfig files are the standard .config files with all of the symbols which are set to their default values stripped out. These files are very useful for debugging your config, as well as being the best way to store your .config file. If you store your config as a full config file, it will be much harder to maintain. Any Kconfig symbols with updated default values will retain their old values, and any symbols which have been removed will still remain in the file. Storing full config files just generally leads to a lot more maintenance than storing miniconfig files.
The easiest way to generate the miniconfig file is by running
make savedefconfig DOTCONFIG=.config DEFCONFIG=[output file]
DEFCONFIG defaults to ‘defconfig’, DOTCONFIG defaults to ‘.config’.
To turn the miniconfig back into a full config file, use one of the two targets:
make olddefconfig DOTCONFIG=[input/output file]
make defconfig KBUILD_DEFCONFIG=[input file] DOTCONFIG=[output file]
In both of these cases, DOTCONFIG defaults to .config.
Save miniconfig files, as mentioned in the previous section.
A common mistake when trying to disable a value is to edit the .config file and change it from ‘CONFIG_SYMBOL=y’ to ‘CONFIG_SYMBOL=n’, but this doesn’t correctly disable the symbol. If the default value for the symbol is ‘n’ to begin with, this isn’t an issue - the symbol just gets ignored, and the default value is used. The problem is where the default for the symbol is ‘y’. When the bad entry in the .config file gets ignored, the value is set back to ‘y’, leading to much frustration.
Always disable the Kconfig symbols in the .config file with the syntax:
# CONFIG_SYMBOL is not set
When reading a saved .config file, Kconfig uses the LAST instance of a symbol that it comes across, and ignores any previous instances. This can be used to override symbols in a saved .config file by appending the new value to a config file.
A .config file that contains these two lines:
# CONFIG_BOOLTEST is not set CONFIG_BOOLTEST=y
After running ‘make olddefconfig’, ends up with the value:
A case where this can be used is by a making a script to create two versions of a coreboot rom for a single platform. The first ROM could be built with serial console disabled, and the second ROM, built as a debug version, could have serial console enabled by overriding the "CONFIG_CONSOLE_SERIAL" symbol, and setting it to enabled.
The FIRST valid default that the Kconfig parser comes across will be used for each symbol. This means that the organization of the tree is very important. The structure should go from most specific at the top of the Kconfig tree to the most general later in the tree. In coreboot, the mainboard directories get loaded first, as they are sourced very early in the src/Kconfig file. Chipset Kconfig files get sourced later, and the architecture specific Kconfig files get sourced even later. This allows the mainboards to set their defaults early, overriding the default values set in chipset or architecture.
Due to this mechanism, a default defined early cannot be changed by a default set in a later Kconfig file. There are ways around this, involving 'depends on' statements, but they add additional variables which are generally just used internal to Kconfig.
The 'select' keyword forces the value of a symbol with a bool type to 'y'. It overrides any dependencies of the symbol, so using it carelessly can lead to unpredictable results.
All bool, int, and hex Kconfig symbols are ALWAYS defined in the C code if they are in a sourced Kconfig - do NOT use #ifdef CONFIG_SYMBOL
String symbols are the exception. All others (int, hex, etc.) are always defined in config.h. Never use an #ifdef statement for a Kconfig symbol other than strings in C to determine whether the symbol is enabled or disabled. So long as the symbol is in ANY sourced Kconfig file, it will be defined. Even if the symbol is only inside of an if/endif block where the if expression evaluates as false, the symbol STILL gets defined in the config.h file (though not in the .config file).
Use #if IS_ENABLED(CONFIG_*) to be sure (it returns false for undefined symbols and defined-to-0 symbols alike).
Symbols with a prompt which may be user-modified are NOT updated to default values when changing between platforms or modifying other symbols. There are only two times the default values are used:
Because of this, starting with a saved .config for one platform and updating it for another platform can lead to very different results than creating a platform from scratch.
Symbols that do not have a prompt will always use the first valid default value specified in Kconfig. They cannot be updated, even if they are modified in a saved .config file. As always, a 'select' statement overrides any specified 'default' or 'depends on' statement.
vim has syntax highlighting for Kconfig built in (or at least as a part of vim-common), but most editors do not.
The Kconfig utility does some basic syntax checking on the Kconfig tree. Running "make silentoldconfig" will show any errors that the Kconfig utility sees.
Because the Kconfig utility is relatively forgiving, and ignores issues that a developer might be interested in, kconfig_lint, another Kconfig checker has been written.
The file kconfig_lint and its associated readme can be found in the coreboot utils/lint directory. It is useful for parsing the Kconfig tree, and for showing warnings, errors, and notes about coreboot’s Kconfig files.
kconfig_lint <options> -o|--output=file Set output filename -p|--print Print full output -e|--errors_off Don't print warnings or errors -w|--warnings_off Don't print warnings -n|--notes Show minor notes --path=dir Path to top level kconfig -c|--config=file Filename of config file to load -G|--no_git_grep Use standard grep tools instead of git grep
The -p option is very useful for debugging Kconfig issues, because it reads all of the Kconfig files in the order that the Kconfig tools would read them, and prints it out, along with where each line came from and which menu it appears in.
This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
Code examples snippets are licensed under GPLv2, and are used here under fair use laws.