[PATCH v1 09/10] Documentation: Describe kconfig-checker overlays

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

Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
---
 Documentation/tools/kconfig_checker.rst | 57 +++++++++++++++++++++++--
 1 file changed, 54 insertions(+), 3 deletions(-)

diff --git a/Documentation/tools/kconfig_checker.rst b/Documentation/tools/kconfig_checker.rst
index 73717ac56ea9..152bc0c634ea 100644
--- a/Documentation/tools/kconfig_checker.rst
+++ b/Documentation/tools/kconfig_checker.rst
@@ -18,8 +18,12 @@ The checker can be invoked from anywhere in the file system::
 
    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``.
+An optional overlay may be supplied with ``-o``::
+
+   check.py check -c path/to/.config -r preempt_rt -o path/to/overlay.yml
+
+As described in Documentation/admin-guide/README.rst, the checker is also
+used by ``make checkconfig``.
 
 External dependencies
 =====================
@@ -47,4 +51,51 @@ The checker's rule files are written in YAML, and are stored in::
 
 The schema for these files is fully documented in::
 
-   tools/kconfig-checker/schema.yml
+   tools/kconfig-checker/base.yml
+   tools/kconfig-checker/rules.yml
+
+Overlays
+========
+
+An overlay is a YAML file applied on top of an existing mainline rule
+profile.  Overlays are intended for local policy, distribution kernel
+packaging, CI environments, and board support packages.
+
+An overlay may override fields of an existing rule.  For example, if the
+mainline PREEMPT_RT profile contains these rules:
+
+.. code-block:: yaml
+
+   rules:
+
+     - name: CONFIG_DRM
+       expected: n
+       severity: info
+       docs_hint: config
+
+     - name: CONFIG_EFI_DISABLE_RUNTIME
+       expected: y
+       severity: medium
+       docs_hint: config
+
+A board support package may override such rules with an overlay like:
+
+.. code-block:: yaml
+
+   rules:
+
+     - name: CONFIG_DRM
+       expected: allowed
+       rationale:
+         This product requires a display controller and accepts the latency
+         cost.
+
+     - name: CONFIG_EFI_DISABLE_RUNTIME
+       expected: n
+       rationale:
+         The efi_runtime workqueue is pinned to housekeeping CPU#0.
+
+.. note::
+
+   If a rule is generally useful to kernel users, please submit it to the
+   mainline profile instead of carrying it as a local overlay.
-- 
2.56.0