]>
Commit | Line | Data |
---|---|---|
5c72c0e0 SG |
1 | .. SPDX-License-Identifier: GPL-2.0+ |
2 | ||
65d7fcec SG |
3 | moveconfig - Migrating and querying CONFIG options |
4 | ================================================== | |
5c72c0e0 SG |
5 | |
6 | Since Kconfig was introduced to U-Boot, we have worked on moving | |
7 | config options from headers to Kconfig (defconfig). | |
8 | ||
9 | This tool intends to help this tremendous work. | |
10 | ||
11 | Installing | |
12 | ---------- | |
13 | ||
14 | You may need to install 'python3-asteval' for the 'asteval' module. | |
15 | ||
16 | Usage | |
17 | ----- | |
18 | ||
19 | First, you must edit the Kconfig to add the menu entries for the configs | |
20 | you are moving. | |
21 | ||
22 | Then run this tool giving CONFIG names you want to move. | |
98463903 | 23 | For example, if you want to move CONFIG_CMD_USB and CONFIG_TEXT_BASE, |
5c72c0e0 SG |
24 | simply type as follows:: |
25 | ||
98463903 | 26 | $ tools/moveconfig.py CONFIG_CMD_USB CONFIG_TEXT_BASE |
5c72c0e0 SG |
27 | |
28 | The tool walks through all the defconfig files and move the given CONFIGs. | |
29 | ||
30 | The log is also displayed on the terminal. | |
31 | ||
32 | The 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. | |
43 | It 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 | ||
77 | Finally, you will be asked, Clean up headers? [y/n]: | |
78 | ||
79 | If you say 'y' here, the unnecessary config defines are removed | |
80 | from the config headers (include/configs/\*.h). | |
81 | It just uses the regex method, so you should not rely on it. | |
82 | Just in case, please do 'git diff' to see what happened. | |
83 | ||
84 | ||
85 | How does it work? | |
86 | ----------------- | |
87 | ||
88 | This tool runs configuration and builds include/autoconf.mk for every | |
89 | defconfig. The config options defined in Kconfig appear in the .config | |
90 | file (unless they are hidden because of unmet dependency.) | |
91 | On the other hand, the config options defined by board headers are seen | |
92 | in include/autoconf.mk. The tool looks for the specified options in both | |
93 | of them to decide the appropriate action for the options. If the given | |
94 | config option is found in the .config, but its value does not match the | |
95 | one from the board header, the config option in the .config is replaced | |
96 | with the define in the board header. Then, the .config is synced by | |
97 | "make savedefconfig" and the defconfig is updated with it. | |
98 | ||
99 | For faster processing, this tool handles multi-threading. It creates | |
100 | separate build directories where the out-of-tree build is run. The | |
101 | temporary build directories are automatically created and deleted as | |
102 | needed. The number of threads are chosen based on the number of the CPU | |
103 | cores of your system although you can change it via -j (--jobs) option. | |
104 | ||
105 | ||
106 | Toolchains | |
107 | ---------- | |
108 | ||
109 | Appropriate toolchain are necessary to generate include/autoconf.mk | |
110 | for all the architectures supported by U-Boot. Most of them are available | |
111 | at the kernel.org site, some are not provided by kernel.org. This tool uses | |
112 | the same tools as buildman, so see that tool for setup (e.g. --fetch-arch). | |
113 | ||
114 | ||
115 | Tips and trips | |
116 | -------------- | |
117 | ||
118 | To sync only X86 defconfigs:: | |
119 | ||
120 | ./tools/moveconfig.py -s -d <(grep -l X86 configs/*) | |
121 | ||
122 | or:: | |
123 | ||
124 | grep -l X86 configs/* | ./tools/moveconfig.py -s -d - | |
125 | ||
126 | To 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 | ||
65d7fcec SG |
132 | Finding boards with particular CONFIG combinations |
133 | -------------------------------------------------- | |
134 | ||
135 | You can use `moveconfig.py` to figure out which boards have a CONFIG enabled, or | |
136 | which do not. To use it, first build a database:: | |
137 | ||
138 | ./tools/moveconfig.py -b | |
139 | ||
140 | Then you can run queries using the `-f` flag followed by a list of CONFIG terms. | |
141 | Each term is CONFIG name, with or without a tilde (~) prefix. The tool searches | |
142 | for boards which match the CONFIG name, or do not match if tilde is used. For | |
143 | example, 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 | ||
5c72c0e0 SG |
150 | Finding implied CONFIGs |
151 | ----------------------- | |
152 | ||
153 | Some CONFIG options can be implied by others and this can help to reduce | |
154 | the size of the defconfig files. For example, CONFIG_X86 implies | |
155 | CONFIG_CMD_IRQ, so we can put 'imply CMD_IRQ' under 'config X86' and | |
156 | all x86 boards will have that option, avoiding adding CONFIG_CMD_IRQ to | |
157 | each of the x86 defconfig files. | |
158 | ||
159 | This tool can help find such configs. To use it, first build a database:: | |
160 | ||
161 | ./tools/moveconfig.py -b | |
162 | ||
163 | Then try to query it:: | |
164 | ||
a8ba35bf SG |
165 | ./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 | ... | |
178 | ||
179 | This shows a list of config options which might imply CONFIG_I8042_KEYB along | |
5c72c0e0 | 180 | with how many defconfigs they cover. From this you can see that CONFIG_X86 |
a8ba35bf SG |
181 | generally implies CONFIG_I8042_KEYB but not always (28 out of 35). Therefore, |
182 | instead of adding CONFIG_I8042_KEYB to | |
5c72c0e0 | 183 | the defconfig of every x86 board, you could add a single imply line to the |
a8ba35bf | 184 | Kconfig file:: |
5c72c0e0 SG |
185 | |
186 | config X86 | |
187 | bool "x86 architecture" | |
188 | ... | |
189 | imply CMD_EEPROM | |
190 | ||
a8ba35bf SG |
191 | That will cover 28 defconfigs and you can perhaps find another condition that |
192 | indicates that CONFIG_I8042_KEYB is not needed for the remaining 5 boards. Many | |
193 | of the options listed are not suitable as they are not related. E.g. it would be | |
194 | odd for CONFIG_RAMBASE to imply CONFIG_I8042_KEYB. | |
5c72c0e0 SG |
195 | |
196 | Using this search you can reduce the size of moveconfig patches. | |
197 | ||
198 | You can automatically add 'imply' statements in the Kconfig with the -a | |
199 | option:: | |
200 | ||
201 | ./tools/moveconfig.py -s -i CONFIG_SCSI \ | |
202 | -a CONFIG_ARCH_LS1021A,CONFIG_ARCH_LS1043A | |
203 | ||
204 | This will add 'imply SCSI' to the two CONFIG options mentioned, assuming that | |
205 | the database indicates that they do actually imply CONFIG_SCSI and do not | |
206 | already have an 'imply SCSI'. | |
207 | ||
208 | The 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 | ||
214 | The first number is the number of boards which can avoid having a special | |
215 | CONFIG_SCSI option in their defconfig file if this 'imply' is added. | |
216 | The location at the right is the Kconfig file and line number where the config | |
217 | appears. For example, adding 'imply CONFIG_SCSI' to the 'config ARCH_LS1021A' | |
218 | in arch/arm/cpu/armv7/ls102xa/Kconfig at line 1 will help 18 boards to reduce | |
219 | the size of their defconfig files. | |
220 | ||
221 | If 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 | ||
225 | To control which ones are displayed, use -I <list> where list is a list of | |
226 | options (use '-I help' to see possible options and their meaning). | |
227 | ||
228 | To skip showing you options that already have an 'imply' attached, use -A. | |
229 | ||
230 | When you have finished adding 'imply' options you can regenerate the | |
231 | defconfig files for affected boards with something like:: | |
232 | ||
233 | git show --stat | ./tools/moveconfig.py -s -d - | |
234 | ||
235 | This will regenerate only those defconfigs changed in the current commit. | |
236 | If you start with (say) 100 defconfigs being changed in the commit, and add | |
237 | a few 'imply' options as above, then regenerate, hopefully you can reduce the | |
238 | number of defconfigs changed in the commit. | |
239 | ||
240 | ||
241 | Available 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 | ||
65d7fcec SG |
256 | -f, --find |
257 | Find boards with a given config combination | |
258 | ||
5c72c0e0 SG |
259 | -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 | |
5579ce74 | 298 | includes cleaning up headers, the config whitelist and the README. |
5c72c0e0 SG |
299 | |
300 | To see the complete list of supported options, run:: | |
301 | ||
302 | tools/moveconfig.py -h |