1# Kconfig in coreboot 2 3## Overview 4Kconfig is a tool used in coreboot, Linux, and many other projects as the main 5configuration mechanism. In coreboot, it allows a developer both to select 6which platform to build and to modify various features within the platform. The 7Kconfig language was developed as a way to configure the Linux kernel, and is 8still maintained as a part of the Linux kernel tree. Starting in Linux 2.5.45, 9the ncurses based menuconfig was added, which is still used as the main 10configuration front end in coreboot today. 11 12The official Kconfig source and documentation is kept at kernel.org: 13 14```{toctree} 15:maxdepth: 1 16 17Kconfig source <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kconfig> 18Kconfig Language Documentation <https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt> 19``` 20 21The advantage to using Kconfig is that it allows users to easily select the 22high level features of the project to be enabled or disabled at build time. 23Ultimately the Kconfig tool generates a list of values which are used by the 24source code and Makefiles of the project. This allows the source files to 25select features, and allows the build to determine which files should be 26compiled and linked to the rom. 27 28 29## Kconfig targets in Make 30The Kconfig program in coreboot is built from source in util/kconfig. There are 31various targets in the makefile to build Kconfig in different ways. These give 32the user control over how to build the platform 33 34 35### Front end configuration targets 36These are the make targets that would be used to update the configuration of 37the platform. 38- config - Text mode configuration tool, asks each configuration option in turn. 39 This does actually run in coreboot, but it is recommended that this not be 40 used as there is no way to save a partial config. 41- gconfig - Graphical configuration tool based on GTK+ 2.0. 42- menuconfig - Text mode, menu driven configuration tool. 43- nconfig - Text mode, menu driven configuration tool. 44- xconfig - Graphical front end based on QT. 45 46 47### Targets that update config files 48These options are used to update the coreboot config files, typically .config. 49The target file can be changed with variables in the environment or on the make 50command line. 51 52- defconfig - This generates a config based on another config file. Use the 53 environment variable KBUILD_DEFCONFIG to specify the base config file. 54- oldconfig - Displays the answers to all configuration questions as it 55 generates the config.h file. If an interactive question is found that does 56 not have an answer yet, it stops and queries the user for the desired value. 57- olddefconfig - Generates a config, using the default value for any symbols not 58 listed in the .config file. 59- savedefconfig - Creates a ‘defconfig’ file, stripping out all of the symbols 60 that were left as default values. This is very useful for debugging, and is 61 how config files should be saved. 62 63 64### Targets not typically used in coreboot 65- localmodconfig, localnoconfig, randconfig, allyesconfig, allnoconfig - These 66 are all used to generate various Kconfig files for testing. 67 68 69### Environment Variables that affect Kconfig 70These variables are typically set in the makefiles or on the make command line. 71 72#### Variables added to the coreboot Kconfig source 73These variables were added to Kconfig specifically for coreboot and are not 74included in the Linux version. 75 76- KCONFIG_NEGATIVES=value. Define to show negative values in the autoconf.h file 77 (build/config.h). This is enabled in coreboot, and should not be changed. 78 79 80#### Variables used to control the input and output config files 81- KBUILD_DEFCONFIG=inputname of the defconfig file. This defaults to 82 ‘configs/defconfig’ and is used by the ‘defconfig’ target. 83 84- DEFCONFIG=output name of the defconfig file. This defaults to ‘defconfig’ 85 and is used by ‘savedefconfig’ target as the output filename. 86 87- DOTCONFIG=name of the .config file. This defaults to '.config' and is used 88 by most config type targets. 89 90 91#### Variables used by the makefiles for controlling Kconfig 92- Kconfig=root Kconfig file. This is set to 'src/Kconfig' in the coreboot 93 makefile. 94 95- KCONFIG_CONFIG=input config file. coreboot sets this to $(DOTCONFIG). 96 97- KCONFIG_AUTOHEADER=path and filename of autoconf.h file. coreboot sets this 98 to $(obj)/config.h. 99 100- KCONFIG_DEPENDENCIES=”kbuild dependency file". This defaults to 101 auto.conf.cmd and outputs the name of all of the Kconfig files used. 102 103- KCONFIG_SPLITCONFIG=”directory name for individual SYMBOL.h files”. 104 coreboot sets this to $(obj)/config. 105 106- KCONFIG_WERROR=value. Define to enable warnings as errors. This is enabled 107 in coreboot, and should not be changed. 108 109#### Used only for ‘make menuconfig’ 110- MENUCONFIG_MODE=single_menu. Set to "single_menu" to enable. All other 111 values disable the option. This makes submenus appear below the menu option 112 instead of opening a new screen. 113 114- MENUCONFIG_COLOR=<theme>. This sets the color theme for the menu from 115 these options: 116 117 - mono => selects colors suitable for monochrome displays. 118 - blackbg => selects a color scheme with black background. 119 - classic => theme with blue background. The classic look. 120 - bluetitle => an LCD friendly version of classic. (default). 121 122 123#### Used only for ‘make nconfig’ 124 125- NCONFIG_MODE=single_menu 126 127 Submenus appear below the menu option instead of opening a new screen. 128 129 130#### Unused in coreboot 131 132Although these variables are not used by coreboot, their values should be left 133at the default values. Other values may have unexpected effects on the 134codebase. 135 136- KCONFIG_SEED=randconfig seed value. 137- KCONFIG_PROBABILITY=randconfig percent to set to y. 138- KCONFIG_NOSILENTUPDATE=value. Define to prevent silent updates to .config 139 file. 140- KCONFIG_OVERWRITECONFIG=value. Define to prevent breaking a .config symlink. 141- KCONFIG_TRISTATE=filename of tristate.conf file. 142- SRCTREE=path to src directory. 143- KCONFIG_AUTOCONFIG=path and filename of the auto.conf file. 144 145 coreboot sets this to $(obj)/auto.conf. Although this value is actually 146 set by coreboot, the resulting file is not used. 147 148- CONFIG_=prefix for Kconfig output symbols. 149 150 coreboot expects this to *NOT* be set. 151 152 153 154## Kconfig Language 155 156The Kconfig language has about 30 keywords, some overloaded, and some with the 157same meaning. Whitespace may have specific meaning, for example in the 'help' 158keyword. There are 8 logical operators for use in expressions, which allow 159values to be set based on other values. 160 161 162### Terminology 163 164- Symbols - There are two types of symbols, "constant" and “non-constant”. 165 - Constant symbols are alphanumeric values used in expressions for 166 comparison. The Kconfig language specification says that these must be 167 surrounded by single or double quotes. 168 - Non-constant symbols are the 'config' values that are output into the 169 saved .config, auto.conf and config.h files. Non-constant symbols are 170 typically defined with the 'config' keyword, although they can also be 171 defined with the 'choice' keyword. These symbols may be used in a file's 172 expressions before they are defined. Valid characters for non-constant 173 symbols are any combination of alphanumeric characters, underscore. 174 Although “1234” is accepted as a symbol name, as is “o_o”, convention is 175 to use all uppercase words that are descriptive of the symbol's use so 176 they make sense when turned into CONFIG_NAME #defines. 177 178- Expressions - An expression is a logical evaluation. It can be as simple as 179 a static 'y' or 'n', or can be a symbol. Alternatively, expressions can be 180 complex evaluations of multiple symbols using the various logical operators. 181 The Kconfig language allows these logical evaluations in several places. The 182 most common use for complex expressions is following 'if' or ‘depends on’ 183 keywords, but they can also be used to set the value for a prompt or default 184 values. 185 186- Types - Each Kconfig symbol is one of the following types: bool, hex, int, 187 string, or tristate. The tristate type is not used for coreboot, leaving just 188 four types. As noted in the keyword summaries, a symbol must have a consistent 189 type anywhere it is defined. Also, Kconfig will simply not display a symbol 190 that has no type defined. A warning will be displayed in the terminal where 191 menuconfig was run if this happens: 192 _src/Kconfig:25:warning: config symbol defined without type_. 193 194- Prompts - Input prompts are the text associated with the symbols which shown 195 to the user. The Kconfig language definition does not require surrounding the 196 prompt’s text with quotes, however it is recommended that quotes be used for 197 maximum compatibility. 198 199- Menu Entries - These keyword blocks create the symbols and questions that are 200 visible in the front end. 201 202 203### Keywords 204 205#### bool 206 207The 'bool' keyword assigns a boolean type to a symbol. The allowable values for 208a boolean type are 'n' or 'y'. The keyword can be followed by an optional prompt 209string which makes the symbol editable in one of the configuration front ends. 210 211 212##### Usage: 213bool \[prompt\] \[if <expr>\] 214 215 216##### Example: 217 config ANY_TOOLCHAIN 218 bool "Allow building with any toolchain" 219 default n 220 depends on COMPILER_GCC 221 222 223##### Notes: 224- Putting the prompt after the 'bool' keyword is the same as using a 'prompt' 225 keyword later. See the 'prompt' keyword for more notes. 226- Only the first type definition for each symbol is valid. Further matching 227 definitions are fine, although unnecessary. Conflicting type definitions will 228 be ignored, and a warning will be presented on the console where the 229 configuration front end was run: 230 _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. 231- Boolean symbols do not need a default and will default to ‘n’. 232 233 234##### Restrictions: 235 236- This keyword must be within a symbol definition block, started by the 237 'config' keyword. 238 239-------------------------------------------------------------------------------- 240 241#### choice 242 243This creates a selection list of one or more boolean symbols. For bools, only 244one of the symbols can be selected, and one will be be forced to be selected, 245either by a ‘default’ statement, or by selecting the first config option if 246there is no default value listed. 247 248##### Usage: 249choice \[symbol\] 250- \[prompt\] 251- \[default\] 252 253 254##### Example: 255 choice TESTCHOICE 256 prompt "Test choice" 257 default TESTCHOICE2 if TESTCHOICE_DEFAULT_2 258 default TESTCHOICE3 259 260 config TESTCHOICE1 261 bool "Choice 1" 262 config TESTCHOICE2 263 bool "Choice 2" 264 config TESTCHOICE3 265 bool "Choice 3" 266 config TESTCHOICE4 267 bool "Choice 4" if TESTCHOICE_SHOW_4 268 endchoice 269 270 config TESTCHOICE_DEFAULT_2 271 def_bool y 272 273 config TESTCHOICE_SHOW_4 274 def_bool n 275 276 config TESTSTRING 277 string 278 default “String #1” if TESTCHOICE1 279 default “String #2” if TESTCHOICE2 280 default “String #4” if TESTCHOICE3 281 default “String #4” if TESTCHOICE4 282 default “” 283 284 285##### Notes: 286- If no symbol is associated with a choice, then you can not have multiple 287 definitions of that choice. If a symbol is associated to the choice, then 288 you may define the same choice (ie. with the same entries) in another place. 289 Any selection in either location will update both choice menu selections. In 290 coreboot, the value of the symbol is always 1. 291- As shown in the example above, the choice between bools can be used to set 292 the default for a non-bool type. This works best when the non-bool type 293 does not have an input prompt. 294 295 296##### Restrictions: 297- Symbols used for 'choice' entries must have input prompts defined using the 298 'prompt' keyword. 299- Symbols used in 'choice' entries may not be enabled with a 'select' 300 statement, they can be defaulted using a second Kconfig symbol however. 301 302-------------------------------------------------------------------------------- 303 304#### comment 305 306This keyword defines a line of text that is displayed to the user in the 307configuration frontend and is additionally written to the output files. 308 309 310##### Usage: 311comment <prompt> 312- \[depends on\] 313 314 315##### Example: 316 317 if CONSOLE_SERIAL 318 comment "I/O mapped, 8250-compatible" 319 depends on DRIVERS_UART_8250IO 320 endif 321 322 323##### Notes: 324- Comments are only valid outside of config blocks, but can be within menu and 325 if blocks. 326 327-------------------------------------------------------------------------------- 328 329#### config 330 331This is the keyword that starts a block defining a Kconfig symbol. The symbol 332modifiers follow the 'config' statement. 333 334##### Usage: 335config <symbol> 336 337- \[bool | def_bool | int | hex | string\] 338- \[depends on\] 339- \[prompt\] 340- \[help\] 341- \[range\] 342- \[select\] 343 344 345##### Example: 346 config SEABIOS_PS2_TIMEOUT 347 prompt "PS/2 keyboard timeout" if PAYLOAD_SEABIOS 348 default 0 349 depends on PAYLOAD_SEABIOS 350 int 351 help 352 Some PS/2 keyboard controllers don't respond to commands 353 immediately after powering on. This specifies how long 354 SeaBIOS will wait for the keyboard controller to become 355 ready before giving up. 356 357 358##### Notes: 359- Non-coreboot projects also use the 'tristate' and 'def_tristate' types. 360- Ends at the next Kconfig keyword that is not valid inside the config block: 361 362 menu | endmenu | if | endif | choice | config | source | comment 363 364-------------------------------------------------------------------------------- 365 366#### default 367 368The ‘default’ keyword assigns a value to a symbol in the case where no preset 369value exists, i.e. the symbol is not present and assigned in .config. If there 370is no preset value, and no ‘default’ keyword, the user will be asked to enter a 371valid value when building coreboot. 372 373 374##### Usage: 375default <expr> \[if <expr>\] 376 377 378##### Example: 379 config GENERATE_MP_TABLE 380 prompt "Generate an MP table" if HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC 381 bool 382 default HAVE_MP_TABLE || DRIVERS_GENERIC_IOAPIC 383 help 384 Generate an MP table (conforming to the Intel 385 MultiProcessor specification 1.4) for this board. 386 387 388##### Notes: 389- Kconfig defaults for symbols without a prompt *NEVER* affect existing legal 390 symbol definitions in a .config file. The default only affects the symbol if 391 there is no valid definition in a config file. This is a frequent source of 392 confusion. It’s covered again in the Tips section below. 393- The first valid 'default' entry for a symbol is always used. Any further 394 'default' statements for a symbol are ignored. This means that the order of 395 Kconfig files is very important as the earlier files get to set the defaults 396 first. They should be sourced in the order from most specific (mainboard 397 Kconfig files) to the most generic (architecture-specific Kconfig files). 398- If there is no 'default' entry for a symbol, it gets set to 'n', 0, 0x0, or 399 “” depending on the type, however the 'bool' type is the only type that 400 should be left without a default value. 401- If possible, the declaration should happen before all default entries to make 402 it visible in Kconfig tools like menuconfig. 403 404-------------------------------------------------------------------------------- 405 406#### def_bool 407 408‘def_bool’ is similar to the 'bool' keyword in that it sets a symbol’s type to 409boolean. It lets you set the type and default value at the same time, instead 410of setting the type and the prompt at the same time. It's typically used for 411symbols that don't have prompts. 412 413 414##### Usage: 415def_bool <expr> \[if <expr>\] 416 417 418##### Example: 419 config EC_GOOGLE_CHROMEEC_LPC 420 depends on EC_GOOGLE_CHROMEEC && ARCH_X86 421 def_bool y 422 select SERIRQ_CONTINUOUS_MODE 423 help 424 Google Chrome EC via LPC bus. 425 426 427##### Notes: 428- Only the first type definition for each symbol is valid. Further matching 429 definitions are fine, although unnecessary. Conflicting type definitions will 430 be ignored, and a warning will be presented on the console where the 431 configuration front end was run: 432 _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. 433 434##### Restrictions: 435- This keyword must be within a symbol definition block, started by the 436 'config' keyword. 437 438-------------------------------------------------------------------------------- 439 440#### depends on 441 442This defines a dependency for a menu entry, including symbols and comments. It 443behaves the same as surrounding the menu entry with an if/endif block. If the 444‘depends on’ expression evaluates to false, the 'prompt' value will not be 445printed, and defaults will not be set based on this block. 446 447 448##### Usage: 449depends on <expr> 450 451 452##### Example: 453 config COMMON_CBFS_SPI_WRAPPER 454 bool 455 default n 456 depends on SPI_FLASH 457 depends on !ARCH_X86 458 help 459 Use common wrapper to interface CBFS to SPI bootrom. 460 461 462##### Notes: 463- Symbols that have multiple ‘depends on’ sections as above are equivalent to a 464 single ‘depends on’ statement with sections joined by &&. So the above is 465 the same as “depends on SPI_FLASH && ! ARCH_X86”. 466 467-------------------------------------------------------------------------------- 468 469#### endchoice 470 471This ends a choice block. See the 'choice' keyword for more information and an 472example. 473 474-------------------------------------------------------------------------------- 475 476#### endif 477 478This ends a block started by the 'if' keyword. See the 'if' keyword for more 479information and an example. 480 481-------------------------------------------------------------------------------- 482 483#### endmenu 484 485This ends a menu block. See the 'menu' keyword for more information and an 486example. 487 488-------------------------------------------------------------------------------- 489 490#### help 491 492The 'help' keyword defines the subsequent block of text as help for a config or 493choice block. The help block is started by the 'help' keyword on a line by 494itself, and the indentation level of the next line controls the end of the help 495block. The help ends on the next non-blank line that has an indentation level 496less than the indentation level of the first line following the 'help' keyword. 497 498##### Usage: 499help <help text> 500 501 502##### Example: 503 config COMPILER_GCC 504 bool "GCC" 505 help 506 Use the GNU Compiler Collection (GCC) to build coreboot. For details 507 see http://gcc.gnu.org. 508 509 510##### Notes: 511- Identical to the '---help---' keyword which isn’t used in coreboot. 512- Other keywords are allowed inside the help block, and are not recognized as 513 keywords so long as the indentation rules are followed, even if they start a 514 line. 515 516 517##### Restrictions: 518- Only used for 'config' and 'choice' keywords. 519 520-------------------------------------------------------------------------------- 521 522#### hex 523 524This is another symbol type specifier, specifying an unsigned integer value 525formatted as hexadecimal. 526 527##### Usage: 528hex <expr> \[if <expr>\] 529 530 531##### Example: 532 config INTEL_PCH_UART_CONSOLE_NUMBER 533 hex "Serial IO UART number to use for console" 534 default 0x0 535 depends on INTEL_PCH_UART_CONSOLE 536 537 538##### Notes: 539- Kconfig doesn’t complain if you don’t start the default value for a hex 540 symbol with ‘0x’, but not doing so will lead to issues. It will update 10 541 to 0x10 without warning the user. 542- Putting the prompt text after the 'hex' keyword is the same as using a 543 'prompt' keyword later. See the 'prompt' keyword for more notes. 544- Only the first type definition for each symbol is valid. Further matching 545 definitions are fine, although unnecessary. Conflicting type definitions will 546 be ignored, and a warning will be presented on the console where the 547 configuration front end was run: 548 _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. 549 550 551##### Restrictions: 552- This keyword must be within a symbol definition block, started by the 553 'config' keyword. 554- 'hex' type symbols must have a 'default' entry set. 555 556-------------------------------------------------------------------------------- 557 558#### if 559 560The 'if' keyword is overloaded, used in two different ways. The first definition 561enables and disables various other keywords, and follows the other keyword 562definition. This usage is shown in each of the other keywords' usage listings. 563 564The second usage of the 'if' keyword is part of an if/endif block. Most items 565within an if/endif block are not evaluated, while others, such as the 'source' 566keyword, ignore the existence of the if/endif block completely. Symbols defined 567within an if/endif block are still created, although their default values are 568ignored - all values are set to 'n'. 569 570 571##### Usage: 572if <expr> 573 574- \[config\] 575- \[choice\] 576- \[comment\] 577- \[menu\] 578 579endif 580 581 582##### Example: 583 if ARCH_X86 584 585 config SMP 586 bool 587 default y if MAX_CPUS != 1 588 default n 589 help 590 This option is used to enable certain functions to make 591 coreboot work correctly on symmetric multi processor (SMP) systems. 592 endif 593 594##### Restrictions: 595- Corresponding ‘if’ and ‘endif’ statements must exist in the same file. 596 597-------------------------------------------------------------------------------- 598 599#### int 600 601A type setting keyword, defines a symbol as an integer, accepting only signed 602numeric values. The values can be further restricted with the ‘range’ keyword. 603 604 605##### Usage: 606int <expr> \[if <expr>\] 607 608 609##### Example: 610 config PRE_GRAPHICS_DELAY_MS 611 int "Graphics initialization delay in ms" 612 default 0 613 help 614 On some systems, coreboot boots so fast that connected 615 monitors (mostly TVs) won't be able to wake up fast enough 616 to talk to the VBIOS. On those systems we need to wait for a 617 bit before executing the VBIOS. 618 619 620##### Notes: 621- Only the first type definition for each symbol is valid. Further matching 622 definitions are fine, although unnecessary. Conflicting type definitions will 623 be ignored, and a warning will be presented on the console where the 624 configuration front end was run: 625 _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'integer'_. 626 627 628##### Restrictions: 629- This keyword must be within a symbol definition block, started by the 'config' 630 keyword. 631- 'int' type symbols must have a default value set. 632 633-------------------------------------------------------------------------------- 634 635#### mainmenu 636 637The 'mainmenu' keyword sets the title or title bar of the configuration front 638 end, depending on how the configuration program decides to use it. It can only 639 be specified once and at the very beginning of the top level Kconfig file, 640 before any other statements. 641 642 643##### Usage: 644mainmenu <prompt> 645 646##### Example: 647mainmenu "coreboot configuration" 648 649##### Restrictions: 650- Must be the first statement in the top level Kconfig. 651- Must only be used once in the entire Kconfig tree. 652 653-------------------------------------------------------------------------------- 654 655#### menu 656 657The 'menu' and 'endmenu' keywords tell the configuration front end that the 658enclosed statements are part of a group of related pieces. 659 660 661##### Usage: 662menu <prompt> 663 664- \[choice\] 665- \[config\] 666- \[menu\] 667- \[if/endif\] 668 669endmenu 670 671 672##### Example: 673 menu "On-Chip Device Power Down Control" 674 config TEMP_POWERDOWN 675 bool "Temperature sensor power-down" 676 677 config SATA_POWERDOWN 678 bool "SATA power-down" 679 680 config ADC_POWERDOWN 681 bool "ADC power-down" 682 683 config PCIE0_POWERDOWN 684 bool "PCIE0 power-down" 685 686 config MAC_POWERDOWN 687 bool "MAC power-down" 688 689 config USB1_POWERDOWN 690 bool "USB2.0 Host Controller 1 power-down" 691 692 config IDE_POWERDOWN 693 bool "IDE power-down" 694 695 endmenu 696 697##### Restrictions: 698- Must be closed by a corresponding ‘endmenu’ keyword in the same file. 699 700-------------------------------------------------------------------------------- 701 702#### prompt 703 704The 'prompt' keyword sets the text displayed for a config symbol or choice in 705configuration front end. 706 707 708##### Usage: 709prompt <prompt> \[if <expr>\] 710 711 712##### Example: 713 config REALMODE_DEBUG 714 prompt "Enable debug messages for option ROM execution" 715 bool 716 default n 717 depends on PCI_OPTION_ROM_RUN_REALMODE 718 depends on DEFAULT_CONSOLE_LOGLEVEL_7 || DEFAULT_CONSOLE_LOGLEVEL_8 719 help 720 This option enables additional x86emu related debug 721 messages. Note: This option will increase the time to emulate a ROM. 722 723 If unsure, say N. 724 725 726##### Notes: 727- The same rules apply for menu entries defined by the 'prompt' keyword and 728 other prompt types such as those defined by the 'int' or 'string' keywords. 729- Redefining the prompt text in multiple instances of config symbols is allowed. 730 Only the current prompt statement for a particular entry will be displayed by 731 the front end in any given location. This means that multiple mainboards can 732 set different prompt values for a symbol, and it would appear differently in 733 each mainboard’s menu. The symbol can even have multiple entries in the same 734 menu with different prompts if desired. For example, both of these would get 735 printed, and changing either entry would change the other. 736 737 config PROMPT_TEST 738 string "Prompt value 1" 739 740 config PROMPT_TEST 741 prompt "Prompt value 2" 742 743- Although not required, it's recommended that you use quotes around prompt 744 statements. 745* If the prompt is redefined inside the SAME config entry, you will get a 746 warning: 747 _warning: prompt redefined_. 748 For example, this is not allowed: 749 750 config PROMPT_TEST 751 string "Prompt value 1" 752 prompt "Prompt value 2" 753-------------------------------------------------------------------------------- 754 755#### range 756 757This sets the allowable minimum and maximum entries for hex or int type config 758symbols. 759 760 761##### Usage: 762range <symbol> <symbol> \[if <expr>\] 763 764 765##### Example: 766 config TEST1 767 hex "test 1" 768 range 0x0 0x10 769 770 771##### Notes: 772- Only the first definition of a range is used for any symbol. Further 773 definitions will be ignored without warning. 774 775-------------------------------------------------------------------------------- 776 777#### select 778 779The ‘select’ keyword is used within a bool type config block. In coreboot (and 780other projects that don't use modules), the 'select' keyword can force an 781unassociated bool type symbol to 'y'. When the symbol for the config block is 782‘y’, the ‘select’ action is taken. Otherwise the bool is unaffected. 783 784 785##### Usage: 786select <symbol> \[if <expr>\] 787 788 789##### Example: 790 config TPM 791 bool 792 default n 793 select MEMORY_MAPPED_TPM if ARCH_X86 794 select I2C_TPM if ARCH_ARM 795 select I2C_TPM if ARCH_ARM64 796 help 797 Enable this option to enable TPM support in coreboot. 798 If unsure, say N. 799 800##### Notes: 801- Using the 'select' keyword can create logical contradictions in Kconfig, which 802 will create warnings and fail to save the .config. Following is an example of 803 an obviously invalid configuration, where selecting BOOLTEST violates the 804 ‘depends on’ of BOOLTEST2: 805 806 config BOOLTEST 807 bool "bool Test" 808 select BOOLTEST2 809 810 config BOOLTEST2 811 bool "Bool Test 2" 812 depends on !BOOLTEST 813 814##### Restrictions: 815- The ‘select’ keyword only works on bool type symbols. 816- Symbols created inside of choice blocks cannot be selected, and should be 817 enabled by using default values instead. 818 819-------------------------------------------------------------------------------- 820 821#### source 822 823The 'source' keyword functions much the same as an 'include' statement in c. 824This pulls one or more files into Kconfig at the location of the 'source' 825command. This statement is always parsed - there is no way to conditionally 826source a file. coreboot has modified the source statement slightly to handle 827directory globbing. The '*' character will match with any directory. 828 829 830##### Usage: 831source <prompt> 832 833 834##### Example: 835 836 choice 837 prompt "Mainboard vendor" 838 default VENDOR_EMULATION 839 840 source "src/mainboard/*/Kconfig.name" 841 842 endchoice 843 844 source "src/mainboard/*/Kconfig" 845 846 847##### Notes: 848- As with all prompt values, the 'source' prompt may be enclosed in single or 849 double quotes, or left without any quotes. Using quotes is highly recommended 850 however. 851- The 'source' keyword loads files relative to the working directory where the 852 Kconfig command was run. For coreboot, this is the root coreboot directory, so 853 all source commands in the src directory need to start with ‘src/’. 854- In coreboot's Kconfig, if a sourced file does not exist, the statement is 855 simply ignored. This is different than other versions of Kconfig. 856- 'source' pulls a file into the Kconfig tree at the location of the keyword. 857 This allows for files containing small bits of the Kconfig tree to be pulled 858 into a larger construct. A restriction on this is that the starting/ending 859 keyword pairs must be within the same file - ‘endif’ cannot appear in a 860 different file than the ‘if’ statement that it ends. The same is true of 861 menu/endmenu and choice/endchoice pairs. 862 863The coreboot Kconfig structure uses this along with globbing to build up the 864mainboard directory. Each mainboard’s Kconfig.name file contains just two 865statements that generate a list of all the platform names: 866 867 config BOARD_AMD_NORWICH 868 bool "Norwich" 869 870 871##### Restrictions: 872- 'source' keywords always load in the specified file or files. There is no way 873 to optionally pull in a file. Putting an if/endif block around a source 874 command does not affect the source command, although it does affect the 875 content. To avoid confusion, use if/endif blocks inside sourced files to 876 remove their content if necessary. 877 878-------------------------------------------------------------------------------- 879 880#### string 881 882The last of the symbol type assignment keywords. 'string' allows a text value to 883be entered. 884 885 886##### Usage: 887string <expr> \[if <expr>\] 888 889 890##### Example: 891 config BOOTBLOCK_SOUTHBRIDGE_INIT 892 string 893 default "southbridge/amd/pi/hudson/bootblock.c" 894 895 config HUDSON_GEC_FWM_FILE 896 string "GEC firmware path and filename" 897 depends on HUDSON_GEC_FWM 898 899 900##### Notes: 901- Putting the prompt after the 'string' keyword is the same as using a 'prompt' 902keyword later. See the prompt keyword for more notes. 903- Only the first type definition for each symbol is valid. Further matching 904 definitions are fine, although unnecessary. Conflicting type definitions will 905 be ignored, and a warning will be presented on the console where the 906 configuration front end was run: 907 _warning: ignoring type redefinition of 'SYMBOL' from 'hex' to 'string'_. 908- Some characters may not get interpreted correctly when inside a string entry 909 depending on how they are used - inside a C file, inside a Makefile, passed 910 through a Makefile to a C file, or something else. It may be necessary to 911 escape the characters at times. Because this is very dependent upon how the 912 symbol is actually used, a definitive guide cannot be given here. 913- 'string' type variables do NOT need a default, and will default to the 914 value “”. 915 916 917##### Restrictions: 918- This keyword must be within a symbol definition block, started by the 'config' 919 keyword. 920 921-------------------------------------------------------------------------------- 922 923 924 925 926### Keywords not used in coreboot at the time of writing: 927 928- allnoconfig_y: 929- defconfig_list 930- def_tristate 931- env 932- ---help--- 933- menuconfig 934- modules 935- optional 936- option 937- tristate 938- visible if 939 940 941## Build files generated by Kconfig 942 943### build/config.h 944 945The config.h file is a very basic header file made up of a list of #define 946statements: 947 948 #define SYMBOL NAME XXX 949 950 951#### Symbol types: 952- bool, int, and hex types - Every symbol of one of these types created in the 953 Kconfig tree is defined. It doesn’t matter whether they’re in an if/endif 954 block, or have a ‘depends on’ statement - they ALL end up being defined in 955 this file. 956- String - Only string types that actually have a value associated with them 957 are defined. 958 959The config.h file uses 0 and 1 to represent Kconfig's 'n' and 'y' values 960respectively. String values are placed inside double quotes. 961 962The name of the file is controlled by the $KCONFIG_AUTOHEADER environment 963variable, which is set to $(obj)/config.h by the coreboot makefiles. 964 965The prefix used for the symbols is controlled by the $CONFIG_ environment 966variable. This is not set in coreboot, which uses the default CONFIG_ prefix 967for all of its symbols. 968 969The coreboot makefile forces the config.h file to be included into all coreboot 970C files. This is done in Makefile.mk on the compiler command line using the 971“-include $(obj)/config.h” command line option. 972 973Example of various symbol types in the config.h file: 974 975 #define CONFIG_BOOTBLOCK_SOURCE "bootblock_simple.c" # String 976 #define CONFIG_CBFS_SIZE 0x00300000 # Hex 977 #define CONFIG_TTYS0_BAUD 115200 # Int 978 #define CONFIG_HAVE_ACPI_TABLES 1 # Bool enabled 979 #define CONFIG_EXPERT 0 # Bool disabled 980 #define CONFIG_NORTHBRIDGE_INTEL_I440LX 0 # Bool excluded 981 982 983### .config 984 985The .config file in the root directory is used as the input file, but also by 986the makefiles to set variable values. The main difference is that it does not 987contain all of the symbols. It excludes symbols defined in an if/endif block 988whose expression evaluated as false. Note that the symbol 989CONFIG_NORTHBRIDGE_INTEL_I440LX shown in the config.h example above is not 990present in the .config file. 991 992In addition, the .config file below contains the 'comment' prompt text from the 993Kconfig, separating the blocks. 994 995 ## General setup ## 996 CONFIG_BOOTBLOCK_SOURCE="bootblock_simple.c" # String 997 CONFIG_CBFS_SIZE=0x00300000 # Hex 998 CONFIG_TTYS0_BAUD=115200 # Int 999 CONFIG_HAVE_ACPI_TABLES=y # Bool enabled 1000 # CONFIG_EXPERT is not set # Bool disabled 1001 1002This file is included directly by the makefile, and sets the CONFIG symbols so 1003that they are available during the build process. 1004 1005 1006### build/auto.conf 1007 1008Although the controlling variable for the auto.conf filename, 1009KCONFIG_AUTOCONFIG, is set in the coreboot makefiles, the auto.conf file itself 1010is not used by coreboot. This file has the same syntax and structure as the 1011.config file, but contains all symbols in the Kconfig tree, including those that 1012are not enabled, or are excluded by if/endif blocks, or the 'depends on' 1013keyword. The kconfig tool could be updated to not generate this file, but since 1014it's not hurting anything, it's still being generated. 1015 1016 1017 1018## Defconfig or Miniconfig files 1019 1020Miniconfig files are the standard .config files with all of the symbols which 1021are set to their default values stripped out. These files are very useful for 1022debugging your config, as well as being the best way to store your .config file. 1023If you store your config as a full config file, it will be much harder to 1024maintain. Any Kconfig symbols with updated default values will retain their old 1025values, and any symbols which have been removed will still remain in the file. 1026Storing full config files just generally leads to a lot more maintenance than 1027storing miniconfig files. 1028 1029The easiest way to generate the miniconfig file is by running 1030 1031 make savedefconfig DOTCONFIG=.config DEFCONFIG=[output file] 1032 1033DEFCONFIG defaults to ‘defconfig’, DOTCONFIG defaults to ‘.config’. 1034 1035 1036To turn the miniconfig back into a full config file, use one of the two targets: 1037 1038 make olddefconfig DOTCONFIG=[input/output file] 1039 1040or 1041 1042 make defconfig KBUILD_DEFCONFIG=[input file] DOTCONFIG=[output file] 1043 1044In both of these cases, DOTCONFIG defaults to .config. 1045 1046 1047 1048## Editing and updating saved .config files 1049 1050 1051### Don’t save full config files 1052 1053Save miniconfig files, as mentioned in the previous section. 1054 1055 1056### Disable values with ‘# CONFIG_SYMBOL is not set’ 1057 1058A common mistake when trying to disable a value is to edit the .config file and 1059change it from ‘CONFIG_SYMBOL=y’ to ‘CONFIG_SYMBOL=n’, but this doesn’t 1060correctly disable the symbol. If the default value for the symbol is ‘n’ to 1061begin with, this isn’t an issue - the symbol just gets ignored, and the default 1062value is used. The problem is where the default for the symbol is ‘y’. When 1063the bad entry in the .config file gets ignored, the value is set back to ‘y’, 1064leading to much frustration. 1065 1066Always disable the Kconfig symbols in the .config file with the syntax: 1067 1068 # CONFIG_SYMBOL is not set 1069 1070### Only the LAST instance of a symbol is used 1071 1072When reading a saved .config file, Kconfig uses the LAST instance of a symbol 1073that it comes across, and ignores any previous instances. This can be used to 1074override symbols in a saved .config file by appending the new value to a config 1075file. 1076 1077For example: 1078 1079A .config file that contains these two lines: 1080 1081 # CONFIG_BOOLTEST is not set 1082 CONFIG_BOOLTEST=y 1083 1084After running ‘make olddefconfig’, ends up with the value: 1085 1086 CONFIG_BOOLTEST=y 1087 1088A case where this can be used is by a making a script to create two versions of 1089a coreboot rom for a single platform. The first ROM could be built with serial 1090console disabled, and the second ROM, built as a debug version, could have 1091serial console enabled by overriding the "CONFIG_CONSOLE_SERIAL" symbol, and 1092setting it to enabled. 1093 1094## General Kconfig Tips and Notes 1095 1096### Default values for config options 1097 1098The FIRST valid default that the Kconfig parser comes across will be used for 1099each symbol. This means that the organization of the tree is very important. 1100The structure should go from most specific at the top of the Kconfig tree to the 1101most general later in the tree. In coreboot, the mainboard directories get 1102loaded first, as they are sourced very early in the src/Kconfig file. Chipset 1103Kconfig files get sourced later, and the architecture specific Kconfig files get 1104sourced even later. This allows the mainboards to set their defaults early, 1105overriding the default values set in chipset or architecture. 1106 1107Due to this mechanism, a default defined early cannot be changed by a default 1108set in a later Kconfig file. There are ways around this, involving 'depends on' 1109statements, but they add additional variables which are generally just used 1110internal to Kconfig. 1111 1112 1113### Select statement usage 1114 1115The 'select' keyword forces the value of a symbol with a bool type to 'y'. It 1116overrides any dependencies of the symbol, so using it carelessly can lead to 1117unpredictable results. 1118 1119 1120 1121### All bool, int, and hex Kconfig symbols are ALWAYS defined in the C code 1122 1123All bool, int, and hex Kconfig symbols are ALWAYS defined in the C code if they 1124are in a sourced Kconfig - do NOT use #ifdef CONFIG_SYMBOL 1125 1126String symbols are the exception. All others (int, hex, etc.) are always 1127defined in config.h. Never use an #ifdef statement for a Kconfig symbol other 1128than strings in C to determine whether the symbol is enabled or disabled. So 1129long as the symbol is in ANY sourced Kconfig file, it will be defined. Even if 1130the symbol is only inside of an if/endif block where the if expression evaluates 1131as false, the symbol STILL gets defined in the config.h file (though not in the 1132.config file). 1133 1134Use \#if CONFIG(SYMBOL) to be sure (it returns false for undefined symbols 1135and defined-to-0 symbols alike). 1136 1137 1138 1139### Symbols with prompts use defaults *ONLY* when initially created or enabled. 1140 1141Symbols with a prompt which may be user-modified are NOT updated to default 1142values when changing between platforms or modifying other symbols. There are 1143only two times the default values are used: 11441. When a config is initially created. 11452. When a dependency which had previously kept the symbol from being active 1146 changes to allowing it to be active. 1147 1148Because of this, starting with a saved .config for one platform and updating it 1149for another platform can lead to very different results than creating a platform 1150from scratch. 1151 1152 1153 1154### Symbols with no prompt will be the default value (unless 'select' is used). 1155 1156Symbols that do not have a prompt will always use the first valid default value 1157specified in Kconfig. They cannot be updated, even if they are modified in a 1158saved .config file. As always, a 'select' statement overrides any specified 1159'default' or 'depends on' statement. 1160 1161 1162## Differences between coreboot's Kconfig and other Kconfig implementations. 1163 1164- coreboot has added the glob operator '*' for the 'source' keyword. 1165- coreboot’s Kconfig always defines variables except for strings. In other 1166 Kconfig implementations, bools set to false/0/no are not defined. 1167 1168 1169## Kconfig Editor Highlighting 1170 1171### vim: 1172 1173vim has syntax highlighting for Kconfig built in (or at least as a part of 1174vim-common), but most editors do not. 1175 1176 1177### ultraedit: 1178 1179https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew 1180 1181 1182 1183### atom: 1184 1185https://github.com/martinlroth/language-kconfig 1186 1187 1188## Syntax Checking: 1189 1190The Kconfig utility does some basic syntax checking on the Kconfig tree. 1191Running "make oldconfig" will show any errors that the Kconfig utility 1192sees. 1193 1194### util/kconfig_lint 1195 1196Because the Kconfig utility is relatively forgiving, and ignores issues that a 1197developer might be interested in, kconfig_lint, another Kconfig checker has been 1198written. 1199 1200The file kconfig_lint and its associated readme can be found in the coreboot 1201utils/lint directory. It is useful for parsing the Kconfig tree, and for 1202showing warnings, errors, and notes about coreboot’s Kconfig files. 1203 1204 1205 kconfig_lint <options> 1206 -o|--output=file Set output filename 1207 -p|--print Print full output 1208 -e|--errors_off Don't print warnings or errors 1209 -w|--warnings_off Don't print warnings 1210 -n|--notes Show minor notes 1211 --path=dir Path to top level kconfig 1212 -c|--config=file Filename of config file to load 1213 -G|--no_git_grep Use standard grep tools instead of git grep 1214 1215 1216The -p option is very useful for debugging Kconfig issues, because it reads all 1217of the Kconfig files in the order that the Kconfig tools would read them, and 1218prints it out, along with where each line came from and which menu it appears 1219in. 1220 1221## License: 1222This work is licensed under the Creative Commons Attribution 4.0 International 1223License. To view a copy of this license, visit 1224https://creativecommons.org/licenses/by/4.0/ or send a letter to Creative 1225Commons, PO Box 1866, Mountain View, CA 94042, USA. 1226 1227Code examples snippets are licensed under GPLv2, and are used here under fair 1228use laws. 1229