blob: 69dc45970b8393edf238b68dc5ce27500dc06d90 [file] [log] [blame]
Masahiro Yamada6933b5c2014-08-16 00:50:30 +09001Kconfig 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
Igor Grinbergb265d0c2014-10-21 13:27:45 +030082 +ST: - the line is valid for Normal, SPL and TPL images
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090083
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
Masahiro Yamadad1b60d32014-08-28 10:56:55 +0900117- <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
Masahiro Yamada6933b5c2014-08-16 00:50:30 +0900124
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.