[PATCH v4 4/5] Documentation: add kconfirm

[Julian Braha]

Add usage documentation and a brief description of kconfirm to
Documentation/dev-tools/

Signed-off-by: Julian Braha <julianbraha@xxxxxxxxx>
---
 Documentation/dev-tools/index.rst    |   1 +
 Documentation/dev-tools/kconfirm.rst | 229 +++++++++++++++++++++++++++
 2 files changed, 230 insertions(+)
 create mode 100644 Documentation/dev-tools/kconfirm.rst

diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 59cbb77b33ff..130ebc0d7282 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -40,3 +40,4 @@ Documentation/process/debugging/index.rst
    autofdo
    propeller
    container
+   kconfirm
diff --git a/Documentation/dev-tools/kconfirm.rst b/Documentation/dev-tools/kconfirm.rst
new file mode 100644
index 000000000000..64ab9d1c3057
--- /dev/null
+++ b/Documentation/dev-tools/kconfirm.rst
@@ -0,0 +1,229 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+.. Copyright (C) 2026 Julian Braha <julianbraha@xxxxxxxxx>
+
+========
+kconfirm
+========
+
+kconfirm is a static analysis tool for the kernel's Kconfig.  It checks
+the entire tree-wide Kconfig, and reports misusage like dead code.  In the
+case of dead default statements, these can be a code smell.
+
+kconfirm has some additional, optional checks. The first is for dead links
+in the Kconfig help texts.  Since this has a high potential for false
+positives (due to websites blocking bots) and slows down runtime
+significantly, it is disabled by default.
+
+Another optional check is for config options that select visible config
+options.  Examples of how to enable the optional checks are included
+below.
+
+kconfirm is written in Rust and lives in ``scripts/kconfig/kconfirm``.  Other
+than the dead link checks, kconfirm aims for zero false positives, though some
+will necessarily happen for config options that use macros referencing the host
+environment.  These are common for host compiler-related options.
+
+kconfirm checks one architecture per run.  When run with ``make kconfirm``, it
+checks the same architecture as the kernel build.  That is, it reads the
+``ARCH`` environment variable, similarly to the build system.  Findings include
+the source architecture Kconfig option as a tag; for example, ``[RISCV]``
+indicates a finding from a tree that sourced ``arch/riscv/Kconfig``.
+
+**NOTE**: kconfirm does not build the kernel; it is strictly a static checker.
+Also note that parsing Kconfig runs Kconfig's own ``$(shell,...)`` and
+``$(success,...)`` feature probes, just as ``make menuconfig`` does, so some
+scripts under ``scripts/`` are executed and your compiler is queried along the
+way.
+
+
+Getting Started
+===============
+
+
+Beyond the usual kernel build environment, kconfirm needs the Rust toolchain:
+``rustc`` and ``bindgen`` (which in turn uses libclang). See also
+Documentation/rust/quick-start.rst for how to install and set it up, and
+Documentation/process/changes.rst for the minimum versions.  kconfirm's
+Minimum Supported Rust Version follows the kernel's host-Rust toolchain
+requirement.
+
+kconfirm is built directly by Kbuild with ``rustc`` and has no third-party
+Rust dependencies.  Bindgen generates the raw Rust bindings directly from the
+Kconfig parser's headers in ``scripts/kconfig``; the generated file is kept in
+the Kbuild output tree.  ``make kconfirm`` verifies that ``rustc`` and
+``bindgen`` are available and recent enough before building, and exits with
+guidance when they are not.
+
+The optional ``dead_link`` check verifies HTTP and HTTPS links and requires the
+``curl`` command at runtime.
+Attempting to enable ``dead_link`` without ``curl`` available in ``PATH`` exits
+with an error.  An internet connection is only required when this check is run.
+
+kconfirm can be built and run from the top of the kernel source tree::
+
+  make kconfirm
+
+The compiled binary will be available at
+``scripts/kconfig/kconfirm/kconfirm`` for an in-tree build, or under the
+corresponding ``scripts/kconfig/kconfirm`` directory in the Kbuild output
+tree when using ``O=``.
+
+Run the kconfirm tests with::
+
+  make kconfirmtest
+
+Run the tests with the kernel's Rust lint configuration with::
+
+  make CLIPPY=1 kconfirmtest
+
+The default checks currently cover dead code analysis, as well as invalid
+(reverse) ranges and constant conditions.  ``select_visible`` and
+``dead_link`` must be turned on explicitly with ``--enable-check``;
+conversely, any default check can be turned off with ``--disable-check``.  Both
+options accept either a comma-separated list or repeated flags, so the
+following two invocations are equivalent::
+
+  make ARCH=x86 kconfirm KCONFIRM_ARGS="--enable-check select_visible,dead_link"
+  make ARCH=x86 kconfirm KCONFIRM_ARGS="--enable-check select_visible --enable-check dead_link"
+
+
+Command-line options
+====================
+
+**NOTE**: kconfirm's arguments must be provided in the ``KCONFIRM_ARGS`` make
+variable. See `Examples`_.
+
+Every option below also has a single-letter form, and accepts its value
+either as the next argument or attached with ``=``, so
+``--enable-check dead_link``, ``--enable-check=dead_link`` and
+``-e dead_link`` are all equivalent.
+
+Available options:
+
+``-l, --linux-path PATH``
+
+  The path to the linux source tree to analyze.  Required.  ``make`` uses
+  this internal option to pass the current linux tree.
+
+``-e, --enable-check CHECK[,CHECK...]``
+
+  Enable one or more checks in addition to the default set.  May be
+  given multiple times, or as a single comma-separated list.  See
+  `Available checks`_ below for valid names.
+
+``-d, --disable-check CHECK[,CHECK...]``
+
+  Disable one or more checks from the default set.  May be given
+  multiple times, or as a single comma-separated list.
+
+``-k, --kconfig FILE``
+
+  The top-level Kconfig file to start from, relative to ``--linux-path``.
+  Defaults to ``Kconfig``.  ``make`` passes the same file that the other
+  Kconfig targets use, so ``KBUILD_KCONFIG`` is honoured.
+
+``-h, --help``
+
+  Show the help message and exit.
+
+
+Available checks
+================
+
+Each check has a string name that is accepted by ``--enable-check`` and
+``--disable-check``.  Checks marked *(default)* are enabled unless turned
+off explicitly.
+
+``duplicate_dependency`` *(default)*
+
+  Reports duplicated ``depends on`` entries on a single Kconfig symbol.
+
+``duplicate_range`` *(default)*
+
+  Reports duplicated ``range`` entries on a single Kconfig symbol.
+
+``dead_range`` *(default)*
+
+  Reports ``range`` entries that will never be evaluated, due to an
+  unconditional range entry.
+
+``duplicate_select`` *(default)*
+
+  Reports duplicated ``select`` entries on a single Kconfig symbol.
+
+``dead_select`` *(default)*
+
+  Reports dead ``select`` entries that will never be evaluated, due to an
+  unconditional select entry of the same config option.
+
+``duplicate_imply`` *(default)*
+
+  Reports duplicated ``imply`` entries on a single Kconfig symbol.
+
+``dead_imply`` *(default)*
+
+  Reports dead ``imply`` entries that will never be evaluated, due to an
+  unconditional imply entry for the same config option.
+
+``duplicate_default`` *(default)*
+
+  Reports duplicated ``default`` entries on a single Kconfig symbol.
+
+``dead_default`` *(default)*
+
+  Reports ``default`` entries that can never be selected because an earlier
+  unconditional default or a default with the same condition takes
+  precedence.
+
+``constant_condition`` *(default)*
+
+  Reports conditions on defaults, selects, implies, and ranges that always
+  evaluate to ``true`` or ``false`` because the condition, or its negation,
+  is already a dependency.
+
+``reverse_range`` *(default)*
+
+  Reports invalid ranges for int and hex configuration options.
+
+``select_visible``
+
+  Reports configuration options that ``select`` a config option that is
+  visible to users.
+
+``dead_link``
+
+  Reports broken HTTP and HTTPS URLs found in Kconfig help text.  Because this
+  performs network requests it can be quite slow, and is disabled by
+  default. May also have false positives.
+
+``duplicate_default_value``
+
+  Reports duplicate default values that have different conditions.
+  Suggests combining the conditions using a logical-or ``||``.
+  This is a style check, and is disabled by default.
+
+
+Examples
+========
+
+Compile (as needed) and run on the current tree::
+
+  make kconfirm
+
+To additionally enable the dead link and select-visible checks::
+
+  make kconfirm KCONFIRM_ARGS="--enable-check=dead_link,select_visible"
+
+To disable a check (here, ``duplicate_dependency``) while keeping the
+rest of the default set::
+
+  make kconfirm KCONFIRM_ARGS="--disable-check duplicate_dependency"
+
+To check another architecture, such as RISC-V::
+
+  make ARCH=riscv kconfirm
+
+To run the default checks from a kernel tree separate from the current
+directory, such as ``~/repos/linux``::
+
+  make -C ~/repos/linux ARCH=x86 kconfirm
-- 
2.54.0