diff options
Diffstat (limited to 'Documentation/getting_started/kconfig.md')
| -rw-r--r-- | Documentation/getting_started/kconfig.md | 1235 |
1 files changed, 1235 insertions, 0 deletions
diff --git a/Documentation/getting_started/kconfig.md b/Documentation/getting_started/kconfig.md new file mode 100644 index 0000000000..7b436ce80a --- /dev/null +++ b/Documentation/getting_started/kconfig.md @@ -0,0 +1,1235 @@ +# Kconfig in coreboot + +## Overview +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: + +- [Kconfig source](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kconfig) +- [Kconfig Language Documentation](https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt) + +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. + + +## Kconfig targets in Make +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 + + +### Front end configuration targets +These are the make targets that would be used to update the configuration of +the platform. +- config - Text mode configuration tool, asks each configuration option in turn. + This does actually run in coreboot, but it is recommended that this not be + used as there is no way to save a partial config. +- gconfig - Graphical configuration tool based on GTK+ 2.0. +- menuconfig - Text mode, menu driven configuration tool. +- nconfig - Text mode, menu driven configuration tool. +- xconfig - Graphical front end based on QT. + + +### Targets that update config files +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. + +- defconfig - This generates a config based on another config file. Use the + environment variable KBUILD_DEFCONFIG to specify the base config file. +- oldconfig - Displays the answers to all configuration questions as it + generates the config.h file. If an interactive question is found that does + not have an answer yet, it stops and queries the user for the desired value. +- olddefconfig - Generates a config, using the default value for any symbols not + listed in the .config file. +- savedefconfig - Creates a ‘mini-config’ file, stripping out all of the symbols + that were left as default values. This is very useful for debugging, and is + how config files should be saved. +- silentoldconfig - This evaluates the .config file the same way that the + oldconfig target does, but does not print out each question as it is + evaluated. It still stops to query the user if an option with no answer in + the .config file is found. + + +### Targets not typically used in coreboot +- localmodconfig, localnoconfig, randconfig, allyesconfig, allnoconfig - These + are all used to generate various Kconfig files for testing. + + +### Environment Variables that affect Kconfig +These variables are typically set in the makefiles or on the make command line. + +#### Variables added to the coreboot Kconfig source +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. + + +#### Variables used to control the input and output config files +- 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. + + +#### Variables used by the makefiles for controlling Kconfig +- 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. + +#### Used only for ‘make menuconfig’ +- 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: + + - mono => selects colors suitable for monochrome displays. + - blackbg => selects a color scheme with black background. + - classic => theme with blue background. The classic look. + - bluetitle => an LCD friendly version of classic. (default). + + +#### Used only for ‘make nconfig’ + +- NCONFIG_MODE=single_menu + + Submenus appear below the menu option instead of opening a new screen. + + +#### Unused in coreboot + +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. + + + +## Kconfig Language + +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. + + +### Terminology + +- Symbols - There are two types of symbols, "constant" and “non-constant”. + - Constant symbols are alphanumeric values used in expressions for + comparison. The Kconfig language specification says that these must be + surrounded by single or double quotes. + - Non-constant symbols are the 'config' values that are output into the + saved .config, auto.conf and config.h files. Non-constant symbols are + typically defined with the 'config' keyword, although they can also be + defined with the 'choice' keyword. These symbols may be used in a file's + expressions before they are defined. Valid characters for non-constant + symbols are any combination of alphanumeric characters, underscore. + Although “1234” is accepted as a symbol name, as is “o_o”, convention is + to use all uppercase words that are descriptive of the symbol's use so + they make sense when turned into CONFIG_NAME #defines. + +- 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. + + +## Keywords + +### bool + +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. + + +##### Usage: +bool \[prompt\] \[if <expr>\] + + +##### Example: + config ANY_TOOLCHAIN + bool "Allow building with any toolchain" + default n + depends on COMPILER_GCC + + +##### Notes: +- Putting the prompt after the 'bool' keyword is the same as using a 'prompt' + keyword later. See the 'prompt' keyword for more notes. +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. +- Boolean symbols do not need a default and will default to ‘n’. + + +##### Restrictions: + +- This keyword must be within a symbol definition block, started by the + 'config' keyword. + +-------------------------------------------------------------------------------- + +### choice + +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. + +##### Usage: +choice \[symbol\] +- \[prompt\] +- \[default\] + + +##### Example: + 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 “” + + +##### Notes: +- If no symbol is associated with a choice, then you can not have multiple + definitions of that choice. If a symbol is associated to the choice, then + you may define the same choice (ie. with the same entries) in another place. + Any selection in either location will update both choice menu selections. In + coreboot, the value of the symbol is always 1. +- As shown in the example above, the choice between bools can be used to set + the default for a non-bool type. This works best when the non-bool type + does not have an input prompt. + + +##### Restrictions: +- Symbols used for 'choice' entries must have input prompts defined using the + 'prompt' keyword. +- Symbols used in 'choice' entries may not be enabled with a 'select' + statement, they can be defaulted using a second Kconfig symbol however. + +-------------------------------------------------------------------------------- + +### comment + +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. + + +##### Usage: +comment <prompt> +- \[depends on\] + + +##### Example: + + if CONSOLE_SERIAL + comment "I/O mapped, 8250-compatible" + depends on DRIVERS_UART_8250IO + endif + + +##### Notes: +- Comments are only valid outside of config blocks, but can be within menu and + if blocks. + +-------------------------------------------------------------------------------- + +### config + +This is the keyword that starts a block defining a Kconfig symbol. The symbol +modifiers follow the 'config' statement. + +##### Usage: +config <symbol> + +- \[bool | def_bool | int | hex | string\] +- \[depends on\] +- \[prompt\] +- \[help\] +- \[range\] +- \[select\] + + +##### Example: + 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. + + +##### Notes: +- 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 + +-------------------------------------------------------------------------------- + +### default + +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. + + +##### Usage: +default <expr> \[if <expr>\] + + +##### Example: + 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. + + +##### Notes: +- Kconfig defaults for symbols without a prompt *NEVER* affect existing legal + symbol definitions in a .config file. The default only affects the symbol if + there is no valid definition in a config file. This is a frequent source of + confusion. It’s covered again in the Tips section below. +- The first valid 'default' entry for a symbol is always used. Any further + 'default' statements for a symbol are ignored. This means that the order of + Kconfig files is very important as the earlier files get to set the defaults + first. They should be sourced in the order from most specific (mainboard + Kconfig files) to the most generic (architecture-specific Kconfig files). +- If there is no 'default' entry for a symbol, it gets set to 'n', 0, 0x0, or + “” depending on the type, however the 'bool' type is the only type that + should be left without a default value. + +-------------------------------------------------------------------------------- + +### def_bool + +‘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. + + +##### Usage: +def_bool <expr> \[if <expr>\] + + +##### Example: + 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. + + +##### Notes: +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the + 'config' keyword. + +-------------------------------------------------------------------------------- + +### depends on + +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. + + +##### Usage: +depends on <expr> + + +##### Example: + 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. + + +##### Notes: +- Symbols that have multiple ‘depends on’ sections as above are equivalent to a + single ‘depends on’ statement with sections joined by &&. So the above is + the same as “depends on SPI_FLASH && ! ARCH_X86”. + +-------------------------------------------------------------------------------- + +### endchoice + +This ends a choice block. See the 'choice' keyword for more information and an +example. + +-------------------------------------------------------------------------------- + +### endif + +This ends a block started by the 'if' keyword. See the 'if' keyword for more +information and an example. + +-------------------------------------------------------------------------------- + +### endmenu + +This ends a menu block. See the 'menu' keyword for more information and an +example. + +-------------------------------------------------------------------------------- + +### help + +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. + +##### Usage: +help <help text> + + +##### Example: + config COMPILER_GCC + bool "GCC" + help + Use the GNU Compiler Collection (GCC) to build coreboot. For details + see http://gcc.gnu.org. + + +##### Notes: +- Identical to the '---help---' keyword which isn’t used in coreboot. +- Other keywords are allowed inside the help block, and are not recognized as + keywords so long as the indentation rules are followed, even if they start a + line. + + +##### Restrictions: +- Only used for 'config' and 'choice' keywords. + +-------------------------------------------------------------------------------- + +### hex + +This is another symbol type specifier, specifying an unsigned integer value +formatted as hexadecimal. + +##### Usage: +hex <expr> \[if <expr>\] + + +##### Example: + config INTEL_PCH_UART_CONSOLE_NUMBER + hex "Serial IO UART number to use for console" + default 0x0 + depends on INTEL_PCH_UART_CONSOLE + + +##### Notes: +- Kconfig doesn’t complain if you don’t start the default value for a hex + symbol with ‘0x’, but not doing so will lead to issues. It will update 10 + to 0x10 without warning the user. +- Putting the prompt text after the 'hex' keyword is the same as using a + 'prompt' keyword later. See the 'prompt' keyword for more notes. +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. + + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the + 'config' keyword. +- 'hex' type symbols must have a 'default' entry set. + +-------------------------------------------------------------------------------- + +### if + +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'. + + +##### Usage: +if <expr> + +- \[config\] +- \[choice\] +- \[comment\] +- \[menu\] + +endif + + +##### Example: + 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 + +##### Restrictions: +- Corresponding ‘if’ and ‘endif’ statements must exist in the same file. + +-------------------------------------------------------------------------------- + +### int + +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. + + +##### Usage: +int <expr> \[if <expr>\] + + +##### Example: + 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. + + +##### Notes: +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. + + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the 'config' + keyword. +- 'int' type symbols must have a default value set. + +-------------------------------------------------------------------------------- + +### mainmenu + +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. + + +##### Usage: +mainmenu <prompt> + +##### Example: +mainmenu "coreboot configuration" + +##### Restrictions: +- Must be the first statement in the top level Kconfig. +- Must only be used once in the entire Kconfig tree. + +-------------------------------------------------------------------------------- + +### menu + +The 'menu' and 'endmenu' keywords tell the configuration front end that the +enclosed statements are part of a group of related pieces. + + +##### Usage: +menu <prompt> + +- \[choice\] +- \[config\] +- \[menu\] +- \[if/endif\] + +endmenu + + +##### Example: + 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 + +##### Restrictions: +- Must be closed by a corresponding ‘endmenu’ keyword in the same file. + +-------------------------------------------------------------------------------- + +### prompt + +The 'prompt' keyword sets the text displayed for a config symbol or choice in +configuration front end. + + +##### Usage: +prompt <prompt> \[if <expr>\] + + +##### Example: + 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. + + +##### Notes: +- 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" +-------------------------------------------------------------------------------- + +### range + +This sets the allowable minimum and maximum entries for hex or int type config +symbols. + + +##### Usage: +range <symbol> <symbol> \[if <expr>\] + + +##### Example: + config TEST1 + hex "test 1" + range 0x0 0x10 + + +##### Notes: +- Only the first definition of a range is used for any symbol. Further + definitions will be ignored without warning. + +-------------------------------------------------------------------------------- + +### select + +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. + + +##### Usage: +select <symbol> \[if <expr>\] + + +##### Example: + 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. + +##### Notes: +- 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 + +##### Restrictions: +- The ‘select’ keyword only works on bool type symbols. +- Symbols created inside of choice blocks cannot be selected, and should be + enabled by using default values instead. + +-------------------------------------------------------------------------------- + +### source + +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. + + +##### Usage: +source <prompt> + + +##### Example: + + choice + prompt "Mainboard vendor" + default VENDOR_EMULATION + + source "src/mainboard/*/Kconfig.name" + + endchoice + + source "src/mainboard/*/Kconfig" + + +##### Notes: +- As with all prompt values, the 'source' prompt may be enclosed in single or + double quotes, or left without any quotes. Using quotes is highly recommended + however. +- The 'source' keyword loads files relative to the working directory where the + Kconfig command was run. For coreboot, this is the root coreboot directory, so + all source commands in the src directory need to start with ‘src/’. +- In coreboot's Kconfig, if a sourced file does not exist, the statement is + simply ignored. This is different than other versions of Kconfig. +- 'source' pulls a file into the Kconfig tree at the location of the keyword. + This allows for files containing small bits of the Kconfig tree to be pulled + into a larger construct. A restriction on this is that the starting/ending + keyword pairs must be within the same file - ‘endif’ cannot appear in a + different file than the ‘if’ statement that it ends. The same is true of + menu/endmenu and choice/endchoice pairs. + +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" + + +##### Restrictions: +- 'source' keywords always load in the specified file or files. There is no way + to optionally pull in a file. Putting an if/endif block around a source + command does not affect the source command, although it does affect the + content. To avoid confusion, use if/endif blocks inside sourced files to + remove their content if necessary. + +-------------------------------------------------------------------------------- + +### string + +The last of the symbol type assignment keywords. 'string' allows a text value to +be entered. + + +##### Usage: +string <expr> \[if <expr>\] + + +##### Example: + 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 + + +##### Notes: +- Putting the prompt after the 'string' keyword is the same as using a 'prompt' +keyword later. See the prompt keyword for more notes. +- Only the first type definition for each symbol is valid. Further matching + definitions are fine, although unnecessary. Conflicting type definitions will + be ignored, and a warning will be presented on the console where the + configuration front end was run: + _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'string'_. +- Some characters may not get interpreted correctly when inside a string entry + depending on how they are used - inside a C file, inside a Makefile, passed + through a Makefile to a C file, or something else. It may be necessary to + escape the characters at times. Because this is very dependent upon how the + symbol is actually used, a definitive guide cannot be given here. +- 'string' type variables do NOT need a default, and will default to the + value “”. + + +##### Restrictions: +- This keyword must be within a symbol definition block, started by the 'config' + keyword. + +-------------------------------------------------------------------------------- + + + + +## Keywords not used in coreboot at the time of writing: + +- allnoconfig_y: +- defconfig_list +- def_tristate +- env +- ---help--- +- menuconfig +- modules +- optional +- option +- tristate +- visible if + + +## Build files generated by Kconfig + +### build/config.h + +The config.h file is a very basic header file made up of a list of #define +statements: + + #define SYMBOL NAME XXX + + +##### Symbol types: +- bool, int, and hex types - Every symbol of one of these types created in the + Kconfig tree is defined. It doesn’t matter whether they’re in an if/endif + block, or have a ‘depends on’ statement - they ALL end up being defined in + this file. +- String - Only string types that actually have a value associated with them + are defined. + +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 + + +### .config + +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. + + +### build/auto.conf + +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. + + + +## Defconfig or Miniconfig files + +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] + +or + + make defconfig KBUILD_DEFCONFIG=[input file] DOTCONFIG=[output file] + +In both of these cases, DOTCONFIG defaults to .config. + + + +## Editing and updating saved .config files + + +### Don’t save full config files + +Save miniconfig files, as mentioned in the previous section. + + +### Disable values with ‘# CONFIG_SYMBOL is not set’ + +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 + +### Only the LAST instance of a symbol is used + +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. + +For example: + +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: + + CONFIG_BOOLTEST=y + +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. + +## General Kconfig Tips and Notes + +### Default values for config options + +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. + + +### Select statement usage + +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 + +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 prompts use defaults *ONLY* when initially created or enabled. + +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: +1. When a config is initially created. +2. When a dependency which had previously kept the symbol from being active + changes to allowing it to be active. + +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 with no prompt will be the default value (unless 'select' is used). + +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. + + +## Differences between coreboot's Kconfig and other Kconfig implementations. + +- coreboot has added the glob operator '*' for the 'source' keyword. +- coreboot’s Kconfig always defines variables except for strings. In other + Kconfig implementations, bools set to false/0/no are not defined. +- IS_ENABLED() is ‘false’ for undefined variables and ‘0’ variables. In Linux + (where the macro comes from) it’s ‘true’ as soon as the variable is defined. +- coreboot’s version of Kconfig adds the KCONFIG_STRICT environment variable to + error out if there are any issues in the Kconfig files. In the Linux kernel, + Kconfig will generate a warning, but will still output an updated .config or + config.h file. + + +## Kconfig Editor Highlighting + +#### vim: + +vim has syntax highlighting for Kconfig built in (or at least as a part of +vim-common), but most editors do not. + + +#### ultraedit: + +https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew + + + +#### atom: + +https://github.com/martinlroth/language-kconfig + + +## Syntax Checking: + +The Kconfig utility does some basic syntax checking on the Kconfig tree. +Running "make silentoldconfig" will show any errors that the Kconfig utility +sees. + +### util/kconfig_lint + +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. + +## License: +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. |