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 ebd06f5..1c78dff 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst
@@ -157,6 +157,50 @@ 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 @@ dev_managed_string = devm_kstrdup(fake_device, "Hello, World!"); // Everything is cleaned up automatically when the test ends. - } \ No newline at end of file + }