1Kconfig in U-Boot 2================= 3 4This document describes the configuration infrastructure of U-Boot. 5 6The conventional configuration was replaced by Kconfig at v2014.10-rc1 release. 7 8 9Language Specification 10---------------------- 11 12Kconfig originates in Linux Kernel. 13See the file "Documentation/kbuild/kconfig*.txt" in your Linux Kernel 14source directory for a basic specification of Kconfig. 15 16 17Difference from Linux's Kconfig 18------------------------------- 19 20The biggest difference between Linux Kernel and U-Boot in terms of the 21configuration is that U-Boot has to configure multiple boot images per board: 22Normal, SPL, TPL. 23Kconfig functions need to be expanded for U-Boot to handle multiple images. 24The files scripts/kconfig/* were imported from Linux Kernel and adjusted 25for that purpose. 26 27See below for how each configuration target works in U-Boot: 28 29- config, nconfig, menuconfig, xconfig, gconfig 30 31 These targets are used to configure Normal and create (or modify) the 32 .config file. For SPL configuration, the configutation targets are prefixed 33 with "spl/", for example "make spl/config", "make spl/menuconfig", etc. 34 Those targets create or modify the spl/.config file. Likewise, run 35 "make tpl/config", "make tpl/menuconfig", etc. for TPL. 36 37- silentoldconfig 38 39 This target updates .config, include/generated/autoconf.h and 40 include/configs/*. In U-Boot, the same thing is done for SPL, TPL, 41 if supported by the target board. Depending on whether CONFIG_SPL and 42 CONFIG_TPL are defined, "make silentoldconfig" iterates three times at most 43 changing the work directory. 44 45 To sum up, "make silentoldconfig" possibly updates: 46 - .config, include/generated/autoconf.h, include/config/* 47 - spl/.config, spl/include/generated/autoconf.h, spl/include/config/* 48 (in case CONFIG_SPL=y) 49 - tpl/.config, tpl/include/generated/autoconf.h, tpl/include/config/* 50 (in case CONFIG_TPL=y) 51 52- defconfig, <board>_defconfig 53 54 The target "<board>_defconfig" is used to create the .config based on the 55 file configs/<board>_defconfig. The "defconfig" target is the same 56 except it checks for a file specified with KBUILD_DEFCONFIG environment. 57 58 Note: 59 The defconfig files are placed under the "configs" directory, 60 not "arch/$(ARCH)/configs". This is because "ARCH" is not necessarily 61 given from the command line for the U-Boot configuration and build. 62 63 The defconfig file format in U-Boot has the special syntax; each line has 64 "<condition>:" prefix to show which image(s) the line is valid for. 65 For example, 66 67 CONFIG_FOO=100 68 S:CONFIG_FOO=200 69 T:CONFIG_FOO=300 70 ST:CONFIG_BAR=y 71 +S:CONFIG_BAZ=y 72 +T:CONFIG_QUX=y 73 +ST:CONFIG_QUUX=y 74 75 Here, the "<condition>:" prefix is one of: 76 None - the line is valid only for Normal image 77 S: - the line is valid only for SPL image 78 T: - the line is valid only for TPL image 79 ST: - the line is valid for SPL and TPL images 80 +S: - the line is valid for Normal and SPL images 81 +T: - the line is valid for Normal and TPL images 82 +ST: - the line is valid for Normal, SPL and TPL images 83 84 So, if neither CONFIG_SPL nor CONFIG_TPL is defined, the defconfig file 85 has no "<condition>:" part and therefore has the same form as in Linux. 86 From the example defconfig shown above, three separete configuration sets 87 are generated and used for creating .config, spl/.config and tpl/.config. 88 89 - Input for the default configuration of Normal 90 CONFIG_FOO=100 91 CONFIG_BAZ=y 92 CONFIG_QUX=y 93 CONFIG_QUUX=y 94 95 - Input for the default configuration of SPL 96 CONFIG_FOO=200 97 CONFIG_BAR=y 98 CONFIG_BAZ=y 99 CONFIG_QUUX=y 100 101 - Input for the default configuration of TPL 102 CONFIG_FOO=300 103 CONFIG_BAR=y 104 CONFIG_QUX=y 105 CONFIG_QUUX=y 106 107- savedefconfig 108 109 This is the reverse operation of "make defconfig". If neither CONFIG_SPL 110 nor CONFIG_TPL is defined in the .config file, it works like "savedefconfig" 111 in Linux Kernel: creates the minimal set of config based on the .config 112 and saves it into the "defconfig" file. If CONFIG_SPL (and CONFIG_TPL) is 113 defined, the common lines among .config, spl/.config (and tpl/.config) are 114 coalesced together with "<condition:>" prefix for each line as shown above. 115 This file can be used as an input of "defconfig" target. 116 117- <board>_config 118 119 This does not exist in Linux's Kconfig. 120 Prior to Kconfig, in U-Boot, "make <board>_config" was used for the 121 configuration. It is still supported for backward compatibility and 122 its behavior is the same as "make <board>_defconfig". 123 124 125Migration steps to Kconfig 126-------------------------- 127 128Prior to Kconfig, the C preprocessor based board configuration had been used 129in U-Boot. 130 131Although Kconfig was introduced and some configs have been moved to Kconfig, 132many of configs are still defined in C header files. It will take a very 133long term to move all of them to Kconfig. In the interim, the two different 134configuration infrastructures should coexist. 135The configuration files are generated by both Kconfig and the old preprocessor 136based configuration as follows: 137 138Configuration files for use in C sources 139 - include/generated/autoconf.h (generated by Kconfig for Normal) 140 - spl/include/generated/autoconf.h (generated by Kconfig for SPL) 141 - tpl/include/generated/autoconf.h (generated by Kconfig for TPL) 142 - include/configs/<board>.h (exists for all boards) 143 144Configuration file for use in makefiles 145 - include/config/auto.conf (generated by Kconfig for Normal) 146 - spl/include/config/auto.conf (generated by Kconfig for SPL) 147 - tpl/include/config/auto.conf (generated by Kconfig for TPL) 148 - include/autoconf.mk (generated by the old config for Normal) 149 - spl/include/autoconfig.mk (generated by the old config for SPL) 150 - tpl/include/autoconfig.mk (generated by the old config for TPL) 151 152When adding a new CONFIG macro, it is highly recommended to add it to Kconfig 153rather than to a header file. 154 155 156Conversion from boards.cfg to Kconfig 157------------------------------------- 158 159Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU, 160SoC, etc. of all the supported boards. It was deleted when switching to 161Kconfig. Each field of boards.cfg was converted as follows: 162 163 Status -> "S:" entry of MAINTAINERS 164 Arch -> CONFIG_SYS_ARCH defined by Kconfig 165 CPU -> CONFIG_SYS_CPU defined by Kconfig 166 SoC -> CONFIG_SYS_SOC defined by Kconfig 167 Vendor -> CONFIG_SYS_VENDOR defined by Kconfig 168 Board -> CONFIG_SYS_BOARD defined by Kconfig 169 Target -> File name of defconfig (configs/<target>_defconfig) 170 Options -> CONFIG_SYS_EXTRA_OPTIONS defined by Kconfig 171 Maintainers -> "M:" entry of MAINTAINERS 172 173 174Tips to add/remove boards 175------------------------- 176 177When adding a new board, the following steps are generally needed: 178 179 [1] Add a header file include/configs/<target>.h 180 [2] Make sure to define necessary CONFIG_SYS_* in Kconfig: 181 Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu> 182 Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc> 183 Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/* 184 and board/<vendor>/<board>/* 185 Define CONFIG_SYS_BOARD="board" to compile board/<board>/* 186 (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined) 187 Define CONFIG_SYS_CONFIG_NAME="target" to include 188 include/configs/<target>.h 189 [3] Add a new entry to the board select menu in Kconfig. 190 The board select menu is located in arch/<arch>/Kconfig or 191 arch/<arch>/*/Kconfig. 192 [4] Add a MAINTAINERS file 193 It is generally placed at board/<board>/MAINTAINERS or 194 board/<vendor>/<board>/MAINTAINERS 195 [5] Add configs/<target>_defconfig 196 197When removing an obsolete board, the following steps are generally needed: 198 199 [1] Remove configs/<target>_defconfig 200 [2] Remove include/configs/<target>.h if it is not used by any other boards 201 [3] Remove board/<vendor>/<board>/* or board/<board>/* if it is not used 202 by any other boards 203 [4] Update MAINTAINERS if necessary 204 [5] Remove the unused entry from the board select menu in Kconfig 205 [6] Add an entry to doc/README.scrapyard 206 207 208TODO 209---- 210 211- The option field of boards.cfg, which was used for the pre-Kconfig 212 configuration, moved to CONFIG_SYS_EXTRA_OPTIONS verbatim now. 213 Board maintainers are expected to implement proper Kconfig options 214 and switch over to them. Eventually CONFIG_SYS_EXTRA_OPTIONS will go away. 215 CONFIG_SYS_EXTRA_OPTIONS should not be used for new boards. 216 217- In the pre-Kconfig, a single board had multiple entries in the boards.cfg 218 file with differences in the option fields. The correspoing defconfig files 219 were auto-generated when switching to Kconfig. Now we have too many 220 defconfig files compared with the number of the supported boards. It is 221 recommended to have only one defconfig per board and allow users to select 222 the config options. 223 224- Move the config macros in header files to Kconfig. When we move at least 225 macros used in makefiles, we can drop include/autoconfig.mk, which makes 226 the build scripts much simpler. 227