blob: 2f53ea52b7101cbc886636b1ff7183bbc68b8b40 [file] [log] [blame]
Simon Glass5c72c0e2021-07-21 21:35:51 -06001.. SPDX-License-Identifier: GPL-2.0+
2
Simon Glass65d7fce2021-12-18 08:09:46 -07003moveconfig - Migrating and querying CONFIG options
4==================================================
Simon Glass5c72c0e2021-07-21 21:35:51 -06005
6Since Kconfig was introduced to U-Boot, we have worked on moving
7config options from headers to Kconfig (defconfig).
8
9This tool intends to help this tremendous work.
10
11Installing
12----------
13
14You may need to install 'python3-asteval' for the 'asteval' module.
15
16Usage
17-----
18
19First, you must edit the Kconfig to add the menu entries for the configs
20you are moving.
21
22Then run this tool giving CONFIG names you want to move.
23For example, if you want to move CONFIG_CMD_USB and CONFIG_SYS_TEXT_BASE,
24simply type as follows::
25
26 $ tools/moveconfig.py CONFIG_CMD_USB CONFIG_SYS_TEXT_BASE
27
28The tool walks through all the defconfig files and move the given CONFIGs.
29
30The log is also displayed on the terminal.
31
32The log is printed for each defconfig as follows::
33
34 <defconfig_name>
35 <action1>
36 <action2>
37 <action3>
38 ...
39
40`<defconfig_name>` is the name of the defconfig.
41
42`<action*>` shows what the tool did for that defconfig.
43It looks like one of the following:
44
45 - Move 'CONFIG\_... '
46 This config option was moved to the defconfig
47
48 - CONFIG\_... is not defined in Kconfig. Do nothing.
49 The entry for this CONFIG was not found in Kconfig. The option is not
50 defined in the config header, either. So, this case can be just skipped.
51
52 - CONFIG\_... is not defined in Kconfig (suspicious). Do nothing.
53 This option is defined in the config header, but its entry was not found
54 in Kconfig.
55 There are two common cases:
56
57 - You forgot to create an entry for the CONFIG before running
58 this tool, or made a typo in a CONFIG passed to this tool.
59 - The entry was hidden due to unmet 'depends on'.
60
61 The tool does not know if the result is reasonable, so please check it
62 manually.
63
64 - 'CONFIG\_...' is the same as the define in Kconfig. Do nothing.
65 The define in the config header matched the one in Kconfig.
66 We do not need to touch it.
67
68 - Compiler is missing. Do nothing.
69 The compiler specified for this architecture was not found
70 in your PATH environment.
71 (If -e option is passed, the tool exits immediately.)
72
73 - Failed to process.
74 An error occurred during processing this defconfig. Skipped.
75 (If -e option is passed, the tool exits immediately on error.)
76
77Finally, you will be asked, Clean up headers? [y/n]:
78
79If you say 'y' here, the unnecessary config defines are removed
80from the config headers (include/configs/\*.h).
81It just uses the regex method, so you should not rely on it.
82Just in case, please do 'git diff' to see what happened.
83
84
85How does it work?
86-----------------
87
88This tool runs configuration and builds include/autoconf.mk for every
89defconfig. The config options defined in Kconfig appear in the .config
90file (unless they are hidden because of unmet dependency.)
91On the other hand, the config options defined by board headers are seen
92in include/autoconf.mk. The tool looks for the specified options in both
93of them to decide the appropriate action for the options. If the given
94config option is found in the .config, but its value does not match the
95one from the board header, the config option in the .config is replaced
96with the define in the board header. Then, the .config is synced by
97"make savedefconfig" and the defconfig is updated with it.
98
99For faster processing, this tool handles multi-threading. It creates
100separate build directories where the out-of-tree build is run. The
101temporary build directories are automatically created and deleted as
102needed. The number of threads are chosen based on the number of the CPU
103cores of your system although you can change it via -j (--jobs) option.
104
105
106Toolchains
107----------
108
109Appropriate toolchain are necessary to generate include/autoconf.mk
110for all the architectures supported by U-Boot. Most of them are available
111at the kernel.org site, some are not provided by kernel.org. This tool uses
112the same tools as buildman, so see that tool for setup (e.g. --fetch-arch).
113
114
115Tips and trips
116--------------
117
118To sync only X86 defconfigs::
119
120 ./tools/moveconfig.py -s -d <(grep -l X86 configs/*)
121
122or::
123
124 grep -l X86 configs/* | ./tools/moveconfig.py -s -d -
125
126To process CONFIG_CMD_FPGAD only for a subset of configs based on path match::
127
128 ls configs/{hrcon*,iocon*,strider*} | \
129 ./tools/moveconfig.py -Cy CONFIG_CMD_FPGAD -d -
130
131
Simon Glass65d7fce2021-12-18 08:09:46 -0700132Finding boards with particular CONFIG combinations
133--------------------------------------------------
134
135You can use `moveconfig.py` to figure out which boards have a CONFIG enabled, or
136which do not. To use it, first build a database::
137
138 ./tools/moveconfig.py -b
139
140Then you can run queries using the `-f` flag followed by a list of CONFIG terms.
141Each term is CONFIG name, with or without a tilde (~) prefix. The tool searches
142for boards which match the CONFIG name, or do not match if tilde is used. For
143example, to find boards which enabled CONFIG_SCSI but not CONFIG_BLK::
144
145 tools/moveconfig.py -f SCSI ~BLK
146 3 matches
147 pg_wcom_seli8_defconfig highbank_defconfig pg_wcom_expu1_defconfig
148
149
Simon Glass5c72c0e2021-07-21 21:35:51 -0600150Finding implied CONFIGs
151-----------------------
152
153Some CONFIG options can be implied by others and this can help to reduce
154the size of the defconfig files. For example, CONFIG_X86 implies
155CONFIG_CMD_IRQ, so we can put 'imply CMD_IRQ' under 'config X86' and
156all x86 boards will have that option, avoiding adding CONFIG_CMD_IRQ to
157each of the x86 defconfig files.
158
159This tool can help find such configs. To use it, first build a database::
160
161 ./tools/moveconfig.py -b
162
163Then try to query it::
164
Simon Glassa8ba35b2021-07-21 21:35:52 -0600165 ./tools/moveconfig.py -i CONFIG_I8042_KEYB
166 CONFIG_I8042_KEYB found in 33/5155 defconfigs
167 28 : CONFIG_X86
168 28 : CONFIG_SA_PCIEX_LENGTH
169 28 : CONFIG_HPET_ADDRESS
170 28 : CONFIG_MAX_PIRQ_LINKS
171 28 : CONFIG_I8254_TIMER
172 28 : CONFIG_I8259_PIC
173 28 : CONFIG_RAMBASE
174 28 : CONFIG_IRQ_SLOT_COUNT
175 28 : CONFIG_PCIE_ECAM_SIZE
176 28 : CONFIG_APIC
177 ...
Simon Glass5c72c0e2021-07-21 21:35:51 -0600178
Simon Glassa8ba35b2021-07-21 21:35:52 -0600179This shows a list of config options which might imply CONFIG_I8042_KEYB along
Simon Glass5c72c0e2021-07-21 21:35:51 -0600180with how many defconfigs they cover. From this you can see that CONFIG_X86
Simon Glassa8ba35b2021-07-21 21:35:52 -0600181generally implies CONFIG_I8042_KEYB but not always (28 out of 35). Therefore,
182instead of adding CONFIG_I8042_KEYB to
Simon Glass5c72c0e2021-07-21 21:35:51 -0600183the defconfig of every x86 board, you could add a single imply line to the
Simon Glassa8ba35b2021-07-21 21:35:52 -0600184Kconfig file::
Simon Glass5c72c0e2021-07-21 21:35:51 -0600185
186 config X86
187 bool "x86 architecture"
188 ...
189 imply CMD_EEPROM
190
Simon Glassa8ba35b2021-07-21 21:35:52 -0600191That will cover 28 defconfigs and you can perhaps find another condition that
192indicates that CONFIG_I8042_KEYB is not needed for the remaining 5 boards. Many
193of the options listed are not suitable as they are not related. E.g. it would be
194odd for CONFIG_RAMBASE to imply CONFIG_I8042_KEYB.
Simon Glass5c72c0e2021-07-21 21:35:51 -0600195
196Using this search you can reduce the size of moveconfig patches.
197
198You can automatically add 'imply' statements in the Kconfig with the -a
199option::
200
201 ./tools/moveconfig.py -s -i CONFIG_SCSI \
202 -a CONFIG_ARCH_LS1021A,CONFIG_ARCH_LS1043A
203
204This will add 'imply SCSI' to the two CONFIG options mentioned, assuming that
205the database indicates that they do actually imply CONFIG_SCSI and do not
206already have an 'imply SCSI'.
207
208The output shows where the imply is added::
209
210 18 : CONFIG_ARCH_LS1021A arch/arm/cpu/armv7/ls102xa/Kconfig:1
211 13 : CONFIG_ARCH_LS1043A arch/arm/cpu/armv8/fsl-layerscape/Kconfig:11
212 12 : CONFIG_ARCH_LS1046A arch/arm/cpu/armv8/fsl-layerscape/Kconfig:31
213
214The first number is the number of boards which can avoid having a special
215CONFIG_SCSI option in their defconfig file if this 'imply' is added.
216The location at the right is the Kconfig file and line number where the config
217appears. For example, adding 'imply CONFIG_SCSI' to the 'config ARCH_LS1021A'
218in arch/arm/cpu/armv7/ls102xa/Kconfig at line 1 will help 18 boards to reduce
219the size of their defconfig files.
220
221If you want to add an 'imply' to every imply config in the list, you can use::
222
223 ./tools/moveconfig.py -s -i CONFIG_SCSI -a all
224
225To control which ones are displayed, use -I <list> where list is a list of
226options (use '-I help' to see possible options and their meaning).
227
228To skip showing you options that already have an 'imply' attached, use -A.
229
230When you have finished adding 'imply' options you can regenerate the
231defconfig files for affected boards with something like::
232
233 git show --stat | ./tools/moveconfig.py -s -d -
234
235This will regenerate only those defconfigs changed in the current commit.
236If you start with (say) 100 defconfigs being changed in the commit, and add
237a few 'imply' options as above, then regenerate, hopefully you can reduce the
238number of defconfigs changed in the commit.
239
240
241Available options
242-----------------
243
244 -c, --color
245 Surround each portion of the log with escape sequences to display it
246 in color on the terminal.
247
248 -C, --commit
249 Create a git commit with the changes when the operation is complete. A
250 standard commit message is used which may need to be edited.
251
252 -d, --defconfigs
253 Specify a file containing a list of defconfigs to move. The defconfig
254 files can be given with shell-style wildcards. Use '-' to read from stdin.
255
Simon Glass65d7fce2021-12-18 08:09:46 -0700256 -f, --find
257 Find boards with a given config combination
258
Simon Glass5c72c0e2021-07-21 21:35:51 -0600259 -n, --dry-run
260 Perform a trial run that does not make any changes. It is useful to
261 see what is going to happen before one actually runs it.
262
263 -e, --exit-on-error
264 Exit immediately if Make exits with a non-zero status while processing
265 a defconfig file.
266
267 -s, --force-sync
268 Do "make savedefconfig" forcibly for all the defconfig files.
269 If not specified, "make savedefconfig" only occurs for cases
270 where at least one CONFIG was moved.
271
272 -S, --spl
273 Look for moved config options in spl/include/autoconf.mk instead of
274 include/autoconf.mk. This is useful for moving options for SPL build
275 because SPL related options (mostly prefixed with CONFIG_SPL\_) are
276 sometimes blocked by CONFIG_SPL_BUILD ifdef conditionals.
277
278 -H, --headers-only
279 Only cleanup the headers; skip the defconfig processing
280
281 -j, --jobs
282 Specify the number of threads to run simultaneously. If not specified,
283 the number of threads is the same as the number of CPU cores.
284
285 -r, --git-ref
286 Specify the git ref to clone for building the autoconf.mk. If unspecified
287 use the CWD. This is useful for when changes to the Kconfig affect the
288 default values and you want to capture the state of the defconfig from
289 before that change was in effect. If in doubt, specify a ref pre-Kconfig
290 changes (use HEAD if Kconfig changes are not committed). Worst case it will
291 take a bit longer to run, but will always do the right thing.
292
293 -v, --verbose
294 Show any build errors as boards are built
295
296 -y, --yes
297 Instead of prompting, automatically go ahead with all operations. This
298 includes cleaning up headers, CONFIG_SYS_EXTRA_OPTIONS, the config whitelist
299 and the README.
300
301To see the complete list of supported options, run::
302
303 tools/moveconfig.py -h