[coreboot-gerrit] Patch set updated for coreboot: Documentation: Add Kconfig document
Martin Roth (martinroth@google.com)
gerrit at coreboot.org
Mon Oct 10 22:21:08 CEST 2016
Martin Roth (martinroth at google.com) just uploaded a new patch set to gerrit, which you can find at https://review.coreboot.org/16947
-gerrit
commit e282e7af7fff6f91c89d5db2611522e45a66bbe0
Author: Martin Roth <martinroth at google.com>
Date: Sat Oct 8 22:40:52 2016 -0600
Documentation: Add Kconfig document
Change-Id: I99ca65343d52e99611644c0c65f4b7feb5c58436
Signed-off-by: Martin Roth <martinroth at google.com>
---
Documentation/Kconfig.md | 1003 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 1003 insertions(+)
diff --git a/Documentation/Kconfig.md b/Documentation/Kconfig.md
new file mode 100644
index 0000000..8f324ad
--- /dev/null
+++ b/Documentation/Kconfig.md
@@ -0,0 +1,1003 @@
+# Kconfig in coreboot
+
+
+## Document History
+- Initial Version: June 15, 2015
+- First public version: October 8, 2016
+
+
+## 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
+- 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.
+- nconfig - Text mode, menu driven configuration tool.
+- menuconfig - Text mode, menu driven configuration tool.
+- gconfig - Graphical configuration tool based on GTK+ 2.0.
+- 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 - Define to enable warnings as errors. This is enabled in coreboot, and should not be changed.
+
+- KCONFIG_NEGATIVES - Set 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.
+
+ Defaults to ‘configs/defconfig’
+ Used by the ‘defconfig’ target
+
+- DEFCONFIG=output name of the defconfig file.
+
+ Defaults to ‘defconfig’
+ Used by ‘savedefconfig’ target as the output filename
+
+- DOTCONFIG=name of the .config file.
+
+ Defaults to .config
+ Used by most config type targets
+
+
+#### Variables used by the makefiles for controlling Kconfig
+- Kconfig=root Kconfig file.
+
+ 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’ - defaults to auto.conf.cmd.
+
+ 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
+
+ Submenus appear below the menu option instead of opening a new screen.
+
+- MENUCONFIG_COLOR=<theme>.
+
+ Sets the 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
+
+- KCONFIG_SEED=randconfig seed value
+- KCONFIG_PROBABILITY=randconfig percent to set to y
+- KCONFIG_NOSILENTUPDATE - Prevent silent updates to .config file
+- KCONFIG_OVERWRITECONFIG - 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 of them overloaded, several with the same meaning, and uses significant whitespace (whitespace that has a meaning) 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 in to set the value for a prompt or default values.
+
+- Types - Each Kconfig symbol is one of 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 if it is created without a type. A warning will be displayed in the terminal where menuconfig was run if this happens: _src/Kconfig:25:warning: config symbol defined without type_. This actually doesn't mean that every instance of a symbol needs a type, although that's how it's usually done in coreboot, but at least one instance of the symbol needs a type.
+
+- Input 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 specifies the type for a symbol. The allowable values for a bool type are 'n' or 'y'. The bool 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 marching 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'_.
+
+- Bool type 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.
+- If \[symbol\] is associated with a choice, the symbol shows whether or not a selection was made. If ‘optional’ is specified, the symbol's value can be 0 or 1, depending on whether or not a selection was made. If ‘optional’ is not specified, 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.
+
+
+##### Restrictions:
+
+--------------------------------------------------------------------------------
+
+### 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 | tristate | def_tristate\]
+- \[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:
+- ends at the next Kconfig keyword that is not valid inside the config block:
+
+ menu / endmenu / if / endif / choice / config / source / comment
+
+
+##### Restrictions:
+
+--------------------------------------------------------------------------------
+
+### 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:
+- When make menuconfig is run with a .config file present, existing legal symbol definitions for symbols with prompts are maintained, and are not overridden by Kconfig defaults. This is something that frequently confuses people. It’s covered again in the Tips section below.
+- The first valid default 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 for a symbol, it gets set to 'n', 0, or “” depending on the type.
+
+
+##### Restrictions:
+
+--------------------------------------------------------------------------------
+
+### 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 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”.
+
+
+##### Restrictions:
+
+--------------------------------------------------------------------------------
+
+### 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 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 marching 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 types must have a default value 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 w ithin 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
+
+##### Notes:
+
+
+##### 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 marching 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 types 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"
+
+##### Notes:
+
+##### Restrictions:
+- Must be the first statement in the top level Kconfig.
+- Must only be used once in the entire Kconfig tree.
+
+--------------------------------------------------------------------------------
+
+### menu
+
+The 'menu'/'endmenu' pair of 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
+
+
+##### Notes:
+
+
+##### Restrictions:
+- Must be closed by a corresponding ‘endmenu’ keyword in the same file.
+
+--------------------------------------------------------------------------------
+
+### prompt
+
+The prompt 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:
+- Redefining the prompt in multiple instances of config symbols is allowed. Only the prompt statement for a particular entry will be displayed by the front end. This means that multiple mainboards can set the prompt 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.
+- Although not required, it's recommended that you use quotes around prompt statements.
+
+##### Restrictions:
+
+--------------------------------------------------------------------------------
+
+### 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.
+
+
+##### Restrictions:
+
+--------------------------------------------------------------------------------
+
+### 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 select can create logical contridictions 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 (verify directory vs file).
+
+
+##### 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’ keywords pull a file into the Kconfig tree at the point where they are located. 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 start/end type keywords must be within the same file - ‘endif’ cannot appear in a different file than the ‘if’ statement that it ends.
+
+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 it. 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 marching 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:
+
+- Sets the value of a symbol to y when using the Make target or Kconfig parameter “allnoconfig”. The Kconfig documentation states that this is used for symbols that hide other symbols. At the time of writing, allnoconfig_y is not currently used anywhere in the coreboot or SeaBIOS. Since the coreboot project doesn’t use the ‘allnoconfig’ makefile target, there’s no reason to use this keyword.
+
+### defconfig_list
+
+### def_tristate
+
+### env
+This keyword imports an environment variable into Kconfig as a symbol, with the value of the environment variable used as the default value of the symbol. The Kconfig documentation states that mixing 'env' type defaults with standard 'default' type defaults is an undefined behavior.
+
+### ---help---
+The ‘---help---’ keyword is simply an alias of the 'help' keyword. The rationale for using it is that it helps to visually separate the help text from the rest of the configuration logic.
+
+### menuconfig
+
+### modules
+
+### optional (deprecated in coreboot)
+The 'optional' keyword is used only for 'choice' blocks. This makes the selection of a value in the choice a two step process. The first step is to enable the choice itself, then select a value.
+
+
+##### Usage:
+ choice \[symbol\]
+ \[optional\]
+
+
+##### Example:
+ choice TESTCHOICE
+ prompt "Test choice"
+ optional
+
+ config TESTCHOICE1
+ bool "Choice 1"
+
+ config TESTCHOICE2
+ bool "Choice 2"
+
+ endchoice
+
+
+##### Notes:
+- When the 'optional' keyword is used, the choice block always defaults to unselected. There seems to be is no way to default the choice to be enabled.
+- The ‘optional’ keyword seems to be quirky, so it’s been removed from coreboot syntax.
+
+
+##### Restrictions:
+
+### 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 CONFIG_<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 “force” includes the config.h file into all c files built. This is done in Makefile.inc on the compiler command line using the “-include $(obj)/config.h” command line option.
+
+ #define CONFIG_BOOTBLOCK_SOURCE "bootblock_simple.c"
+ #define CONFIG_CBFS_SIZE 0x00300000
+ #define CONFIG_TTYS0_BAUD 115200
+ #define CONFIG_HAVE_ACPI_TABLES 1
+ #define CONFIG_EXPERT 0
+ #define CONFIG_NORTHBRIDGE_INTEL_I440LX 0
+
+### .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 above files is not present in the .config file.
+
+In addition, it contains the 'comment' prompt text from the Kconfig, separating the blocks.
+
+ ## General setup ##
+ CONFIG_BOOTBLOCK_SOURCE="bootblock_simple.c"
+ CONFIG_CBFS_SIZE=0x00300000
+ CONFIG_TTYS0_BAUD=115200
+ CONFIG_HAVE_ACPI_TABLES=y
+ # CONFIG_EXPERT is not set
+
+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
+
+This file has the same syntax and structure as the .config file, but includes all symbols in the Kconfig tree. Although the controlling variable KCONFIG_AUTOCONF is set in the coreboot makefiles, the auto.conf file itself is not used by coreboot.
+
+
+
+## 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 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 in 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 piping the new value into 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
+
+
+
+## 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 does not pay attention to 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 C 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 that can be user modified *ONLY* use default values when they are initially created or enabled.
+
+Symbols with a prompt which may be user modified are NOT not updated to default values when changing between platforms or modifying other symbols. The only time the defaults are used are when a dependency which had previously kept the symbol from being active changes to allowing it to be active, or when a config is initially created. 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 always be the default value (unless a 'select' is used).
+
+Symbols that do not have a prompt will always use the first valid default value specified in Kconfig. These will not be updated correctly even if they are set in a saved .config. 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 by default.
+- 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](https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew)
+
+
+
+#### atom:
+
+[https://github.com/martinlroth/language-kconfig](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=fileSet output filename
+ -p|--printPrint full output
+ -e|--errors_offDon't print warnings or errors
+ -w|--warnings_offDon't print warnings
+ -n|--notesShow minor notes
+ --path=dirPath to top level kconfig
+ -c|--config=fileFilename of config file to load
+ -G|--no_git_grepUse 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.
More information about the coreboot-gerrit
mailing list