[PATCH v2 27/27] qconfig: Update the documentation

[Heinrich Schuchardt]

Am 15. September 2023 02:22:29 MESZ schrieb Simon Glass <sjg at chromium.org>:
>Update qconfig's documentation to better reflect its new purpose in life.
>
>Signed-off-by: Simon Glass <sjg at chromium.org>
>---
>
>Changes in v2:
>- Reinstate the -C option
>
> doc/develop/index.rst                       |   2 +-
> doc/develop/{moveconfig.rst => qconfig.rst} | 144 +++++---------------
> 2 files changed, 38 insertions(+), 108 deletions(-)
> rename doc/develop/{moveconfig.rst => qconfig.rst} (61%)
>
>diff --git a/doc/develop/index.rst b/doc/develop/index.rst
>index 0d12484ace8a..003cdfccf112 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
>similarity index 61%
>rename from doc/develop/moveconfig.rst
>rename to doc/develop/qconfig.rst
>index ad8596e6c61a..111e2b2545d9 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

%s/allowing/allows/


>+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

%s/syncing/synchronizing/


>+drops options which are implied by others.
>+
>+Finally, it allow scanning the source code to look for inconsistencies in the

%s/allow/allows/


>+use of Kconfig options.
> 
> Installing
> ----------


%s/Installing/Installation/

> 
> 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

How about *.config fragments?

>+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"

%s/resyncing/resynchronizing/

>+and the defconfig is updated with it.
> 
> For faster processing, this tool handles multi-threading.  It creates

%s/handles multi-threading/uses parallelization/

> 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

%s/toolchain/toolchains/

> 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

That 'some are not ...' clause is superfluous.


>-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`).

Are you really referring to other tools than buildman itself? Which tools?

Please, provide a link to the buildman documentation and provide an example here.


> 
> 
> Tips and trips

Do you mean 'Examples'?

Best regards

Heinrich


>@@ -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 -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 +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,9 +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.
>+ --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 +212,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 +227,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