[PATCH smatch-devel 1/5] docs: document selecting individual Smatch checks

Smatch can limit a run to selected checker registration functions with
--enable, but the kchecker documentation does not describe this useful
development and triage workflow.

Document how to list and select checks, enable companion hooks, and
choose a cross-function database.  Also explain that
smatch_db.sqlite.new is a staging file which is promoted only after a
successful database build.

Assisted-by: Codex:gpt-5.6
Signed-off-by: Harshit Mogalapalli <[email protected]>
---
 Documentation/smatch.rst | 43 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/Documentation/smatch.rst b/Documentation/smatch.rst
index 4d5cbf34896d..24ff5540601c 100644
--- a/Documentation/smatch.rst
+++ b/Documentation/smatch.rst
@@ -71,6 +71,49 @@ You can also build a directory like this::
 
 The kchecker script prints its warnings to stdout.
 
+Running a single check
+----------------------
+
+Use ``--show-checks`` to list the available check names::
+
+	~/path/to/smatch_dir/smatch --show-checks
+
+Pass ``--enable=<name>`` to kchecker to run one check while retaining the
+internal Smatch infrastructure that the check depends on.  The ``check_``
+prefix is optional::
+
+	~/path/to/smatch_dir/smatch_scripts/kchecker --spammy \
+		--enable=uninitialized drivers/whatever/file.c
+
+Multiple checks can be enabled with a comma-separated list::
+
+	~/path/to/smatch_dir/smatch_scripts/kchecker --spammy \
+		--enable=uninitialized,unreachable \
+		drivers/whatever/file.c
+
+Some source files register companion checks, such as an ``_info`` function
+used when generating cross-function data.  List each companion explicitly
+when it is needed.  For example, the unwind checker registers both
+``check_unwind`` and ``check_unwind_info``::
+
+	~/path/to/smatch_dir/smatch_scripts/kchecker --spammy \
+		--enable=unwind,unwind_info drivers/whatever/file.c
+
+Smatch reads ``smatch_db.sqlite`` from the current directory by default.  Use
+``--db-file=<path>`` to select a different cross-function database::
+
+	~/path/to/smatch_dir/smatch_scripts/kchecker --spammy \
+		--enable=uninitialized \
+		--db-file=~/path/to/kernel_dir/smatch_db.sqlite \
+		drivers/whatever/file.c
+
+The database builder creates ``smatch_db.sqlite.new`` as a staging file.  Once
+the build and its sanity check complete, it renames that file to
+``smatch_db.sqlite``.  A leftover ``.new`` file therefore belongs to an
+in-progress, interrupted, or failed database build and may be incomplete.  Do
+not select it for normal checking; finish or rerun ``build_kernel_data.sh`` so
+that a validated database is promoted to ``smatch_db.sqlite``.
+
 The above scripts will ensure that any ARCH or CROSS_COMPILE environment
 variables are passed to kernel build system - thus allowing for the use of
 Smatch with kernels that are normally built with cross-compilers.
-- 
2.52.0