[PATCH 28/28] qconfig: Update the documentation
Simon Glass
sjg at chromium.org
Thu Aug 10 18:32:00 CEST 2023
Update qconfig's documentation to better reflect its new purpose in life.
Signed-off-by: Simon Glass <sjg at chromium.org>
---
doc/develop/index.rst | 2 +-
doc/develop/{moveconfig.rst => qconfig.rst} | 148 +++++---------------
2 files changed, 38 insertions(+), 112 deletions(-)
rename doc/develop/{moveconfig.rst => qconfig.rst} (60%)
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 5b230d0321f..8bd08fd17f9 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -87,7 +87,7 @@ Refactoring
checkpatch
coccinelle
- moveconfig
+ qconfig
Code quality
------------
diff --git a/doc/develop/moveconfig.rst b/doc/develop/qconfig.rst
similarity index 60%
rename from doc/develop/moveconfig.rst
rename to doc/develop/qconfig.rst
index ad8596e6c61..22bfe2bd2a7 100644
--- a/doc/develop/moveconfig.rst
+++ b/doc/develop/qconfig.rst
@@ -1,100 +1,37 @@
.. SPDX-License-Identifier: GPL-2.0+
-moveconfig - Migrating and querying CONFIG options
-==================================================
+qconfig - Querying CONFIG options
+=================================
-Since Kconfig was introduced to U-Boot, we have worked on moving
-config options from headers to Kconfig (defconfig).
+It is not possible to see all the CONFIG options used by a board without
+building its `.config` file. This tool allowing this to be done efficiently for
+all boards, or a subset, writing the results to a unified database file.
-This tool intends to help this tremendous work.
+This database can be queried, to find boards which used a certain combination
+of options, to aid in discovering Kconfig options which imply others.
+
+The tool also permits syncing of defconfigs, which corrects the ordering and
+drops options which are implied by others.
+
+Finally, it allow scanning the source code to look for inconsistencies in the
+use of Kconfig options.
Installing
----------
You may need to install 'python3-asteval' for the 'asteval' module.
-Usage
------
-
-First, you must edit the Kconfig to add the menu entries for the configs
-you are moving.
-
-Then run this tool giving CONFIG names you want to move.
-For example, if you want to move CONFIG_CMD_USB and CONFIG_TEXT_BASE,
-simply type as follows::
-
- $ tools/moveconfig.py CONFIG_CMD_USB CONFIG_TEXT_BASE
-
-The tool walks through all the defconfig files and move the given CONFIGs.
-
-The log is also displayed on the terminal.
-
-The log is printed for each defconfig as follows::
-
- <defconfig_name>
- <action1>
- <action2>
- <action3>
- ...
-
-`<defconfig_name>` is the name of the defconfig.
-
-`<action*>` shows what the tool did for that defconfig.
-It looks like one of the following:
-
- - Move 'CONFIG\_... '
- This config option was moved to the defconfig
-
- - CONFIG\_... is not defined in Kconfig. Do nothing.
- The entry for this CONFIG was not found in Kconfig. The option is not
- defined in the config header, either. So, this case can be just skipped.
-
- - CONFIG\_... is not defined in Kconfig (suspicious). Do nothing.
- This option is defined in the config header, but its entry was not found
- in Kconfig.
- There are two common cases:
-
- - You forgot to create an entry for the CONFIG before running
- this tool, or made a typo in a CONFIG passed to this tool.
- - The entry was hidden due to unmet 'depends on'.
-
- The tool does not know if the result is reasonable, so please check it
- manually.
-
- - 'CONFIG\_...' is the same as the define in Kconfig. Do nothing.
- The define in the config header matched the one in Kconfig.
- We do not need to touch it.
-
- - Compiler is missing. Do nothing.
- The compiler specified for this architecture was not found
- in your PATH environment.
- (If -e option is passed, the tool exits immediately.)
-
- - Failed to process.
- An error occurred during processing this defconfig. Skipped.
- (If -e option is passed, the tool exits immediately on error.)
-
-Finally, you will be asked, Clean up headers? [y/n]:
-
-If you say 'y' here, the unnecessary config defines are removed
-from the config headers (include/configs/\*.h).
-It just uses the regex method, so you should not rely on it.
-Just in case, please do 'git diff' to see what happened.
-
-
How does it work?
-----------------
-This tool runs configuration and builds include/autoconf.mk for every
-defconfig. The config options defined in Kconfig appear in the .config
-file (unless they are hidden because of unmet dependency.)
+When building a database (`-b`), this tool runs configuration and builds
+include/autoconf.mk for every defconfig. The config options defined in Kconfig
+appear in the .config file (unless they are hidden because of unmet dependency.)
On the other hand, the config options defined by board headers are seen
-in include/autoconf.mk. The tool looks for the specified options in both
-of them to decide the appropriate action for the options. If the given
-config option is found in the .config, but its value does not match the
-one from the board header, the config option in the .config is replaced
-with the define in the board header. Then, the .config is synced by
-"make savedefconfig" and the defconfig is updated with it.
+in include/autoconf.mk.
+
+When resyncing defconfigs (`-s`) the .config is synced by "make savedefconfig"
+and the defconfig is updated with it.
For faster processing, this tool handles multi-threading. It creates
separate build directories where the out-of-tree build is run. The
@@ -109,7 +46,7 @@ Toolchains
Appropriate toolchain are necessary to generate include/autoconf.mk
for all the architectures supported by U-Boot. Most of them are available
at the kernel.org site, some are not provided by kernel.org. This tool uses
-the same tools as buildman, so see that tool for setup (e.g. --fetch-arch).
+the same tools as buildman, so see that tool for setup (e.g. `--fetch-arch`).
Tips and trips
@@ -117,32 +54,32 @@ Tips and trips
To sync only X86 defconfigs::
- ./tools/moveconfig.py -s -d <(grep -l X86 configs/*)
+ ./tools/qconfig.py -s -d <(grep -l X86 configs/*)
or::
- grep -l X86 configs/* | ./tools/moveconfig.py -s -d -
+ grep -l X86 configs/* | ./tools/qconfig.py -s -d -
To process CONFIG_CMD_FPGAD only for a subset of configs based on path match::
ls configs/{hrcon*,iocon*,strider*} | \
- ./tools/moveconfig.py -Cy CONFIG_CMD_FPGAD -d -
+ ./tools/qconfig.py -Cy CONFIG_CMD_FPGAD -d -
Finding boards with particular CONFIG combinations
--------------------------------------------------
-You can use `moveconfig.py` to figure out which boards have a CONFIG enabled, or
+You can use `qconfig.py` to figure out which boards have a CONFIG enabled, or
which do not. To use it, first build a database::
- ./tools/moveconfig.py -b
+ ./tools/qconfig.py -b
Then you can run queries using the `-f` flag followed by a list of CONFIG terms.
Each term is CONFIG name, with or without a tilde (~) prefix. The tool searches
for boards which match the CONFIG name, or do not match if tilde is used. For
example, to find boards which enabled CONFIG_SCSI but not CONFIG_BLK::
- tools/moveconfig.py -f SCSI ~BLK
+ tools/qconfig.py -f SCSI ~BLK
3 matches
pg_wcom_seli8_defconfig highbank_defconfig pg_wcom_expu1_defconfig
@@ -158,11 +95,11 @@ each of the x86 defconfig files.
This tool can help find such configs. To use it, first build a database::
- ./tools/moveconfig.py -b
+ ./tools/qconfig.py -b
Then try to query it::
- ./tools/moveconfig.py -i CONFIG_I8042_KEYB
+ ./tools/qconfig.py -i CONFIG_I8042_KEYB
CONFIG_I8042_KEYB found in 33/5155 defconfigs
28 : CONFIG_X86
28 : CONFIG_SA_PCIEX_LENGTH
@@ -193,12 +130,12 @@ indicates that CONFIG_I8042_KEYB is not needed for the remaining 5 boards. Many
of the options listed are not suitable as they are not related. E.g. it would be
odd for CONFIG_RAMBASE to imply CONFIG_I8042_KEYB.
-Using this search you can reduce the size of moveconfig patches.
+Using this search you can reduce the size of qconfig patches.
You can automatically add 'imply' statements in the Kconfig with the -a
option::
- ./tools/moveconfig.py -s -i CONFIG_SCSI \
+ ./tools/qconfig.py -s -i CONFIG_SCSI \
-a CONFIG_ARCH_LS1021A,CONFIG_ARCH_LS1043A
This will add 'imply SCSI' to the two CONFIG options mentioned, assuming that
@@ -220,7 +157,7 @@ the size of their defconfig files.
If you want to add an 'imply' to every imply config in the list, you can use::
- ./tools/moveconfig.py -s -i CONFIG_SCSI -a all
+ ./tools/qconfig.py -s -i CONFIG_SCSI -a all
To control which ones are displayed, use -I <list> where list is a list of
options (use '-I help' to see possible options and their meaning).
@@ -230,7 +167,7 @@ To skip showing you options that already have an 'imply' attached, use -A.
When you have finished adding 'imply' options you can regenerate the
defconfig files for affected boards with something like::
- git show --stat | ./tools/moveconfig.py -s -d -
+ git show --stat | ./tools/qconfig.py -s -d -
This will regenerate only those defconfigs changed in the current commit.
If you start with (say) 100 defconfigs being changed in the commit, and add
@@ -241,13 +178,9 @@ number of defconfigs changed in the commit.
Available options
-----------------
- -c, --color
- Surround each portion of the log with escape sequences to display it
- in color on the terminal.
-
- -C, --commit
- Create a git commit with the changes when the operation is complete. A
- standard commit message is used which may need to be edited.
+ --nocolour
+ Disables colouring of output. This is normally used when writing to a
+ terminal.
-d, --defconfigs
Specify a file containing a list of defconfigs to move. The defconfig
@@ -275,9 +208,6 @@ Available options
because SPL related options (mostly prefixed with CONFIG_SPL\_) are
sometimes blocked by CONFIG_SPL_BUILD ifdef conditionals.
- -H, --headers-only
- Only cleanup the headers; skip the defconfig processing
-
-j, --jobs
Specify the number of threads to run simultaneously. If not specified,
the number of threads is the same as the number of CPU cores.
@@ -293,10 +223,6 @@ Available options
-v, --verbose
Show any build errors as boards are built
- -y, --yes
- Instead of prompting, automatically go ahead with all operations. This
- includes cleaning up headers, the config whitelist and the README.
-
To see the complete list of supported options, run::
- tools/moveconfig.py -h
+ tools/qconfig.py -h
--
2.41.0.640.ga95def55d0-goog
More information about the U-Boot
mailing list