blob: cd549a8a5441b932dd8275efddaf806473da930b [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
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.