From: Guenter Roeck <[email protected]> Document API functions for suppressing warning backtraces.
Tested-by: Linux Kernel Functional Testing <[email protected]> Acked-by: Dan Carpenter <[email protected]> Reviewed-by: Kees Cook <[email protected]> Signed-off-by: Guenter Roeck <[email protected]> Reviewed-by: David Gow <[email protected]> Signed-off-by: Alessandro Carminati <[email protected]> Reviewed-by: David Gow <[email protected]> Signed-off-by: Albert Esteve <[email protected]> --- Documentation/dev-tools/kunit/usage.rst | 63 ++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index ebd06f5ea4550..25724f7e72969 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -157,6 +157,67 @@ 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. +Three API forms are available, in order of convenience. + +- 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. + +- Manual macros are useful when the suppressed region is large enough that + extra indentation is undesirable, or when the warning count needs to be + checked after suppression ends. ``KUNIT_START_SUPPRESSED_WARNING()`` must + appear before ``KUNIT_END_SUPPRESSED_WARNING()`` in the same scope. + Limited to one pair per scope. + +.. code-block:: c + + static void some_test(struct kunit *test) + { + KUNIT_START_SUPPRESSED_WARNING(test); + trigger_backtrace(); + KUNIT_END_SUPPRESSED_WARNING(test); + + KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(test, 1); + } + +- 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 +1272,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 + } -- 2.53.0
