qconfig: Update the documentation

Update qconfig's documentation to better reflect its new purpose in life.

Signed-off-by: Simon Glass <sjg@chromium.org>

2 files changed, 47 insertions, 115 deletions

diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 0d12484ace8..003cdfccf11 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -88,7 +88,7 @@ Refactoring
 
    checkpatch
    coccinelle
-   moveconfig
+   qconfig
 
 Code quality
 ------------
diff --git a/doc/develop/moveconfig.rst b/doc/develop/qconfig.rst
index ad8596e6c61..8efb1eb2685 100644
--- a/doc/develop/moveconfig.rst
+++ b/doc/develop/qconfig.rst
@@ -1,148 +1,87 @@
 .. 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 allows 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.
 
-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:
+The tool also permits syncing of defconfigs, which corrects the ordering and
+drops options which are implied by others.
 
- - Move 'CONFIG\_... '
-   This config option was moved to the defconfig
+Finally, it allows scanning the source code to look for inconsistencies in the
+use of Kconfig options.
 
- - 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.
+Installation
+------------
 
+You may need to install 'python3-asteval' for the 'asteval' module.
 
 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.
-
-For faster processing, this tool handles multi-threading.  It creates
+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 is multi-threaded.  It creates
 separate build directories where the out-of-tree build is run.  The
 temporary build directories are automatically created and deleted as
 needed.  The number of threads are chosen based on the number of the CPU
 cores of your system although you can change it via -j (--jobs) option.
 
+Note that `*.config` fragments are not supported.
 
 Toolchains
 ----------
 
-Appropriate toolchain are necessary to generate include/autoconf.mk
+Appropriate toolchains 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).
+at the kernel.org site. This tool uses the same tools as
+:doc:`../build/buildman`, so you can use `buildman --fetch-arch` to fetch
+toolchains.
 
 
-Tips and trips
---------------
+Examples
+--------
 
 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 -C 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 +97,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 +132,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 +159,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 +169,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,9 +180,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.
+ --nocolour
+   Disables colouring of output. This is normally used when writing to a
+   terminal.
 
  -C, --commit
    Create a git commit with the changes when the operation is complete. A
@@ -275,9 +214,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 +229,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