mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-11-24 21:54:01 +00:00
qconfig: Update the documentation
Update qconfig's documentation to better reflect its new purpose in life. Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass
parent
519637929b
commit
4840b71bb0
2 changed files with 47 additions and 115 deletions
|
|
@ -88,7 +88,7 @@ Refactoring
|
|||
|
||||
checkpatch
|
||||
coccinelle
|
||||
moveconfig
|
||||
qconfig
|
||||
|
||||
Code quality
|
||||
------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
----------
|
||||
The tool also permits syncing of defconfigs, which corrects the ordering and
|
||||
drops options which are implied by others.
|
||||
|
||||
Finally, it allows scanning the source code to look for inconsistencies in the
|
||||
use of Kconfig options.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
For faster processing, this tool handles multi-threading. It creates
|
||||
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
|
||||
Loading…
Reference in a new issue