[PATCH v1 05/10] Documentation: Describe kconfig-checker usage and design

["Ahmed S. Darwish" <darwi@linutronix.de>]

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 <darwi@linutronix.de>
---
 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