Describe the kconfig-checker design, invocation, and external dependencies.
For PREEMPT_RT users, mention that the checker can now be used for validating a kernel's .config against PREEMPT_RT requirements. For the kconfig-checker external dependencies error handling code, reference the newly added documentation as well. Signed-off-by: Ahmed S. Darwish <[email protected]> --- Documentation/admin-guide/README.rst | 24 +++++++++ .../real-time/kernel-configuration.rst | 3 ++ Documentation/tools/index.rst | 1 + Documentation/tools/kconfig_checker.rst | 50 +++++++++++++++++++ tools/kconfig-checker/check.py | 7 ++- 5 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 Documentation/tools/kconfig_checker.rst diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 77fec1de6dc8..77ffe4dcb85b 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -256,6 +256,30 @@ Configuring the kernel should probably answer 'n' to the questions for "development", "experimental", or "debugging" features. +Checking the kernel configuration +--------------------------------- + +The kconfig build system can validate the generated kernel ``.config`` +against a selected rules profile. Running ``make checkconfig`` prints +usage information and the available profiles:: + + Usage: make RULES=<profile> checkconfig + Available RULES: preempt_rt + +For example, to validate the current configuration against the PREEMPT_RT +profile, run:: + + make RULES=preempt_rt checkconfig + +``checkconfig`` reports kconfig options whose values do not match the +selected rules profile. Each diagnostic includes a severity, such as +``FATAL`` or ``INFO``, plus the suggested configuration change. + +Apply the reported changes as needed and run ``make checkconfig`` again, +against the same rules, until no relevant diagnostics remain. + +For more information, see Documentation/tools/kconfig_checker.rst + Compiling the kernel -------------------- diff --git a/Documentation/core-api/real-time/kernel-configuration.rst b/Documentation/core-api/real-time/kernel-configuration.rst index d7f08e7b8760..15245c34a053 100644 --- a/Documentation/core-api/real-time/kernel-configuration.rst +++ b/Documentation/core-api/real-time/kernel-configuration.rst @@ -14,6 +14,9 @@ Introduction This document lists the kernel configuration options that might affect a real-time kernel's worst-case latency. It is intended for system integrators. +You can validate your kernel's ``.config`` against the guidelines below using +the ``kconfig-checker`` tool. See Documentation/tools/kconfig_checker.rst + Configuration options ===================== diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst index 1adf4a6f909b..8912a627a7ac 100644 --- a/Documentation/tools/index.rst +++ b/Documentation/tools/index.rst @@ -10,6 +10,7 @@ more additions are needed here: .. toctree:: :maxdepth: 1 + kconfig_checker rtla/index rv/index python diff --git a/Documentation/tools/kconfig_checker.rst b/Documentation/tools/kconfig_checker.rst new file mode 100644 index 000000000000..73717ac56ea9 --- /dev/null +++ b/Documentation/tools/kconfig_checker.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +Kernel configuration checker +============================ + +``kconfig-checker`` is a Python tool for checking a kernel ``.config`` file +against a set of rules; e.g., PREEMPT_RT configuration requirements. It +gives users and system integrators a sanity report showing whether the +passed kernel configuration satisfies a known profile. + +Invocation +========== + +The checker can be invoked from anywhere in the file system:: + + check.py list-rules + + check.py check -c path/to/.config -r preempt_rt + +As described in Documentation/admin-guide/README.rst, it is also used by +``make checkconfig``. + +External dependencies +===================== + +The checker requires the ``PyYAML`` and ``jsonschema`` python packages. +Install them using your distribution's package manager, for example: + +.. table:: + :align: left + + ============ ================== ====================== + Distribution PyYAML jsonschema + ============ ================== ====================== + Debian ``python3-yaml`` ``python3-jsonschema`` + Red Hat ``python3-pyyaml`` ``python3-jsonschema`` + Arch Linux ``python-yaml`` ``python-jsonschema`` + ============ ================== ====================== + +Rule files +========== + +The checker's rule files are written in YAML, and are stored in:: + + tools/kconfig-checker/rules/ + +The schema for these files is fully documented in:: + + tools/kconfig-checker/schema.yml diff --git a/tools/kconfig-checker/check.py b/tools/kconfig-checker/check.py index 476cd13e59eb..ef49c28b9dab 100755 --- a/tools/kconfig-checker/check.py +++ b/tools/kconfig-checker/check.py @@ -69,7 +69,12 @@ try: import jsonschema # type: ignore import yaml as yaml_m # type: ignore except ModuleNotFoundError as e: - error(f'Missing Python module: {e.name}', os.EX_UNAVAILABLE) + docs = 'Documentation/tools/kconfig_checker.rst' + error( + f'Missing Python module: {e.name}\n' + f'Check {docs} for how to install required dependencies', + os.EX_UNAVAILABLE + ) # # Actual script: -- 2.56.0

