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 SPL 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 118Migration steps to Kconfig 119-------------------------- 120 121Prior to Kconfig, the C preprocessor based board configuration had been used 122in U-Boot. 123 124Although Kconfig was introduced and some configs have been moved to Kconfig, 125many of configs are still defined in C header files. It will take a very 126long term to move all of them to Kconfig. In the interim, the two different 127configuration infrastructures should coexist. 128The configuration files are generated by both Kconfig and the old preprocessor 129based configuration as follows: 130 131Configuration files for use in C sources 132 - include/generated/autoconf.h (generated by Kconfig for Normal) 133 - spl/include/generated/autoconf.h (generated by Kconfig for SPL) 134 - tpl/include/generated/autoconf.h (generated by Kconfig for TPL) 135 - include/configs/<board>.h (exists for all boards) 136 137Configuration file for use in makefiles 138 - include/config/auto.conf (generated by Kconfig for Normal) 139 - spl/include/config/auto.conf (generated by Kconfig for SPL) 140 - tpl/include/config/auto.conf (generated by Kconfig for TPL) 141 - include/autoconf.mk (generated by the old config for Normal) 142 - spl/include/autoconfig.mk (generated by the old config for SPL) 143 - tpl/include/autoconfig.mk (generated by the old config for TPL) 144 145When adding a new CONFIG macro, it is highly recommended to add it to Kconfig 146rather than to a header file. 147 148 149Conversion from boards.cfg to Kconfig 150------------------------------------- 151 152Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU, 153SoC, etc. of all the supported boards. It was deleted when switching to 154Kconfig. Each field of boards.cfg was converted as follows: 155 156 Status -> "S:" entry of MAINTAINERS 157 Arch -> CONFIG_SYS_ARCH defined by Kconfig 158 CPU -> CONFIG_SYS_CPU defined by Kconfig 159 SoC -> CONFIG_SYS_SOC defined by Kconfig 160 Vendor -> CONFIG_SYS_VENDOR defined by Kconfig 161 Board -> CONFIG_SYS_BOARD defined by Kconfig 162 Target -> File name of defconfig (configs/<target>_defconfig) 163 Options -> CONFIG_SYS_EXTRA_OPTIONS defined by Kconfig 164 Maintainers -> "M:" entry of MAINTAINERS 165 166 167Tips to add/remove boards 168------------------------- 169 170When adding a new board, the following steps are generally needed: 171 172 [1] Add a header file include/configs/<target>.h 173 [2] Make sure to define necessary CONFIG_SYS_* in Kconfig: 174 Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu> 175 Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc> 176 Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/* 177 and board/<vendor>/<board>/* 178 Define CONFIG_SYS_BOARD="board" to compile board/<board>/* 179 (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined) 180 Define CONFIG_SYS_CONFIG_NAME="target" to include 181 include/configs/<target>.h 182 [3] Add a new entry to the board select menu in Kconfig. 183 The board select menu is located in arch/<arch>/Kconfig or 184 arch/<arch>/*/Kconfig. 185 [4] Add a MAINTAINERS file 186 It is generally placed at board/<board>/MAINTAINERS or 187 board/<vendor>/<board>/MAINTAINERS 188 [5] Add configs/<target>_defconfig 189 190When removing an obsolete board, the following steps are generally needed: 191 192 [1] Remove configs/<target>_defconfig 193 [2] Remove include/configs/<target>.h if it is not used by any other boards 194 [3] Remove board/<vendor>/<board>/* or board/<board>/* if it is not used 195 by any other boards 196 [4] Update MAINTAINERS if necessary 197 [5] Remove the unused entry from the board select menu in Kconfig 198 [6] Add an entry to doc/README.scrapyard 199 200 201TODO 202---- 203 204- The option field of boards.cfg, which was used for the pre-Kconfig 205 configuration, moved to CONFIG_SYS_EXTRA_OPTIONS verbatim now. 206 Board maintainers are expected to implement proper Kconfig options 207 and switch over to them. Eventually CONFIG_SYS_EXTRA_OPTIONS will go away. 208 CONFIG_SYS_EXTRA_OPTIONS should not be used for new boards. 209 210- In the pre-Kconfig, a single board had multiple entries in the boards.cfg 211 file with differences in the option fields. The correspoing defconfig files 212 were auto-generated when switching to Kconfig. Now we have too many 213 defconfig files compared with the number of the supported boards. It is 214 recommended to have only one defconfig per board and allow users to select 215 the config options. 216 217- Move the config macros in header files to Kconfig. When we move at least 218 macros used in makefiles, we can drop include/autoconfig.mk, which makes 219 the build scripts much simpler. 220