doc/develop/moveconfig.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 moveconfig
   4 ==========
   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.
  23 For example, if you want to move CONFIG_CMD_USB and CONFIG_SYS_TEXT_BASE,
  24 simply type as follows::
  25
  26   $ tools/moveconfig.py CONFIG_CMD_USB CONFIG_SYS_TEXT_BASE
  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
 132 Finding implied CONFIGs
 133 -----------------------
 134
 135 Some CONFIG options can be implied by others and this can help to reduce
 136 the size of the defconfig files. For example, CONFIG_X86 implies
 137 CONFIG_CMD_IRQ, so we can put 'imply CMD_IRQ' under 'config X86' and
 138 all x86 boards will have that option, avoiding adding CONFIG_CMD_IRQ to
 139 each of the x86 defconfig files.
 140
 141 This tool can help find such configs. To use it, first build a database::
 142
 143     ./tools/moveconfig.py -b
 144
 145 Then try to query it::
 146
 147     ./tools/moveconfig.py -i CONFIG_CMD_IRQ
 148     CONFIG_CMD_IRQ found in 311/2384 defconfigs
 149     44 : CONFIG_SYS_FSL_ERRATUM_IFC_A002769
 150     41 : CONFIG_SYS_FSL_ERRATUM_A007075
 151     31 : CONFIG_SYS_FSL_DDR_VER_44
 152     28 : CONFIG_ARCH_P1010
 153     28 : CONFIG_SYS_FSL_ERRATUM_P1010_A003549
 154     28 : CONFIG_SYS_FSL_ERRATUM_SEC_A003571
 155     28 : CONFIG_SYS_FSL_ERRATUM_IFC_A003399
 156     25 : CONFIG_SYS_FSL_ERRATUM_A008044
 157     22 : CONFIG_ARCH_P1020
 158     21 : CONFIG_SYS_FSL_DDR_VER_46
 159     20 : CONFIG_MAX_PIRQ_LINKS
 160     20 : CONFIG_HPET_ADDRESS
 161     20 : CONFIG_X86
 162     20 : CONFIG_PCIE_ECAM_SIZE
 163     20 : CONFIG_IRQ_SLOT_COUNT
 164     20 : CONFIG_I8259_PIC
 165     20 : CONFIG_CPU_ADDR_BITS
 166     20 : CONFIG_RAMBASE
 167     20 : CONFIG_SYS_FSL_ERRATUM_A005871
 168     20 : CONFIG_PCIE_ECAM_BASE
 169     20 : CONFIG_X86_TSC_TIMER
 170     20 : CONFIG_I8254_TIMER
 171     20 : CONFIG_CMD_GETTIME
 172     19 : CONFIG_SYS_FSL_ERRATUM_A005812
 173     18 : CONFIG_X86_RUN_32BIT
 174     17 : CONFIG_CMD_CHIP_CONFIG
 175     ...
 176
 177 This shows a list of config options which might imply CONFIG_CMD_EEPROM along
 178 with how many defconfigs they cover. From this you can see that CONFIG_X86
 179 implies CONFIG_CMD_EEPROM. Therefore, instead of adding CONFIG_CMD_EEPROM to
 180 the defconfig of every x86 board, you could add a single imply line to the
 181 Kconfig file:
 182
 183     config X86
 184         bool "x86 architecture"
 185         ...
 186         imply CMD_EEPROM
 187
 188 That will cover 20 defconfigs. Many of the options listed are not suitable as
 189 they are not related. E.g. it would be odd for CONFIG_CMD_GETTIME to imply
 190 CMD_EEPROM.
 191
 192 Using this search you can reduce the size of moveconfig patches.
 193
 194 You can automatically add 'imply' statements in the Kconfig with the -a
 195 option::
 196
 197     ./tools/moveconfig.py -s -i CONFIG_SCSI \
 198             -a CONFIG_ARCH_LS1021A,CONFIG_ARCH_LS1043A
 199
 200 This will add 'imply SCSI' to the two CONFIG options mentioned, assuming that
 201 the database indicates that they do actually imply CONFIG_SCSI and do not
 202 already have an 'imply SCSI'.
 203
 204 The output shows where the imply is added::
 205
 206    18 : CONFIG_ARCH_LS1021A       arch/arm/cpu/armv7/ls102xa/Kconfig:1
 207    13 : CONFIG_ARCH_LS1043A       arch/arm/cpu/armv8/fsl-layerscape/Kconfig:11
 208    12 : CONFIG_ARCH_LS1046A       arch/arm/cpu/armv8/fsl-layerscape/Kconfig:31
 209
 210 The first number is the number of boards which can avoid having a special
 211 CONFIG_SCSI option in their defconfig file if this 'imply' is added.
 212 The location at the right is the Kconfig file and line number where the config
 213 appears. For example, adding 'imply CONFIG_SCSI' to the 'config ARCH_LS1021A'
 214 in arch/arm/cpu/armv7/ls102xa/Kconfig at line 1 will help 18 boards to reduce
 215 the size of their defconfig files.
 216
 217 If you want to add an 'imply' to every imply config in the list, you can use::
 218
 219     ./tools/moveconfig.py -s -i CONFIG_SCSI -a all
 220
 221 To control which ones are displayed, use -I <list> where list is a list of
 222 options (use '-I help' to see possible options and their meaning).
 223
 224 To skip showing you options that already have an 'imply' attached, use -A.
 225
 226 When you have finished adding 'imply' options you can regenerate the
 227 defconfig files for affected boards with something like::
 228
 229     git show --stat | ./tools/moveconfig.py -s -d -
 230
 231 This will regenerate only those defconfigs changed in the current commit.
 232 If you start with (say) 100 defconfigs being changed in the commit, and add
 233 a few 'imply' options as above, then regenerate, hopefully you can reduce the
 234 number of defconfigs changed in the commit.
 235
 236
 237 Available options
 238 -----------------
 239
 240  -c, --color
 241    Surround each portion of the log with escape sequences to display it
 242    in color on the terminal.
 243
 244  -C, --commit
 245    Create a git commit with the changes when the operation is complete. A
 246    standard commit message is used which may need to be edited.
 247
 248  -d, --defconfigs
 249   Specify a file containing a list of defconfigs to move.  The defconfig
 250   files can be given with shell-style wildcards. Use '-' to read from stdin.
 251
 252  -n, --dry-run
 253    Perform a trial run that does not make any changes.  It is useful to
 254    see what is going to happen before one actually runs it.
 255
 256  -e, --exit-on-error
 257    Exit immediately if Make exits with a non-zero status while processing
 258    a defconfig file.
 259
 260  -s, --force-sync
 261    Do "make savedefconfig" forcibly for all the defconfig files.
 262    If not specified, "make savedefconfig" only occurs for cases
 263    where at least one CONFIG was moved.
 264
 265  -S, --spl
 266    Look for moved config options in spl/include/autoconf.mk instead of
 267    include/autoconf.mk.  This is useful for moving options for SPL build
 268    because SPL related options (mostly prefixed with CONFIG_SPL\_) are
 269    sometimes blocked by CONFIG_SPL_BUILD ifdef conditionals.
 270
 271  -H, --headers-only
 272    Only cleanup the headers; skip the defconfig processing
 273
 274  -j, --jobs
 275    Specify the number of threads to run simultaneously.  If not specified,
 276    the number of threads is the same as the number of CPU cores.
 277
 278  -r, --git-ref
 279    Specify the git ref to clone for building the autoconf.mk. If unspecified
 280    use the CWD. This is useful for when changes to the Kconfig affect the
 281    default values and you want to capture the state of the defconfig from
 282    before that change was in effect. If in doubt, specify a ref pre-Kconfig
 283    changes (use HEAD if Kconfig changes are not committed). Worst case it will
 284    take a bit longer to run, but will always do the right thing.
 285
 286  -v, --verbose
 287    Show any build errors as boards are built
 288
 289  -y, --yes
 290    Instead of prompting, automatically go ahead with all operations. This
 291    includes cleaning up headers, CONFIG_SYS_EXTRA_OPTIONS, the config whitelist
 292    and the README.
 293
 294 To see the complete list of supported options, run::
 295
 296   tools/moveconfig.py -h