moveconfig.rst 10 KB

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