kunit: Add documentation for warning backtrace suppression API

Document API functions for suppressing warning backtraces.

Link: https://lore.kernel.org/r/20260514-kunit_add_support-v11-4-b36a530a6d8f@redhat.com
Tested-by: Linux Kernel Functional Testing <lkft@linaro.org>
Acked-by: Dan Carpenter <dan.carpenter@linaro.org>
Reviewed-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Guenter Roeck <linux@roeck-us.net>
Signed-off-by: Alessandro Carminati <acarmina@redhat.com>
Reviewed-by: David Gow <david@davidgow.net>
Signed-off-by: Albert Esteve <aesteve@redhat.com>
Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>

diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst
index ebd06f5ea4550a23754f5644357285a01b835d68..1c78dfff94e8a876cb10c90657a3ca9a2ea6564a 100644 (file)
--- a/Documentation/dev-tools/kunit/usage.rst
+++ b/Documentation/dev-tools/kunit/usage.rst
@@ -157,6 +157,50 @@ Alternatively, one can take full control over the error message by using
        if (some_setup_function())
                KUNIT_FAIL(test, "Failed to setup thing for testing");
 
+Suppressing warning backtraces
+------------------------------
+
+Some unit tests trigger warning backtraces either intentionally or as a side
+effect. Such backtraces are normally undesirable since they distract from
+the actual test and may result in the impression that there is a problem.
+
+Backtraces can be suppressed with **task-scoped suppression**: while
+suppression is active on the current task, the backtrace and stack dump from
+``WARN*()``, ``WARN_ON*()``, and related macros on that task are suppressed.
+Two API forms are available.
+
+- Scoped suppression is the simplest form. Wrap the code that triggers
+  warnings in a ``kunit_warning_suppress()`` block:
+
+.. code-block:: c
+
+       static void some_test(struct kunit *test)
+       {
+               kunit_warning_suppress(test) {
+                       trigger_backtrace();
+                       KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(test, 1);
+               }
+       }
+
+.. note::
+   The warning count must be checked inside the block; the suppression handle
+   is not accessible after the block exits.
+
+- Direct functions return an explicit handle pointer. Use them when the handle
+  needs to be retained or passed across helper functions:
+
+.. code-block:: c
+
+       static void some_test(struct kunit *test)
+       {
+               struct kunit_suppressed_warning *w;
+
+               w = kunit_start_suppress_warning(test);
+               trigger_backtrace();
+               kunit_end_suppress_warning(test, w);
+
+               KUNIT_EXPECT_EQ(test, kunit_suppressed_warning_count(w), 1);
+       }
 
 Test Suites
 ~~~~~~~~~~~
@@ -1211,4 +1255,4 @@ For example:
                dev_managed_string = devm_kstrdup(fake_device, "Hello, World!");
 
                // Everything is cleaned up automatically when the test ends.
-       }
\ No newline at end of file
+       }