[PATCH v8 4/4] kunit: Add documentation for warning backtrace suppression API

[David Gow]

Le 04/05/2026 à 3:41 PM, Albert Esteve a écrit :
> From: Guenter Roeck <linux at roeck-us.net>
> 
> Document API functions for suppressing warning backtraces.
> 
> Tested-by: Linux Kernel Functional Testing <lkft at linaro.org>
> Acked-by: Dan Carpenter <dan.carpenter at linaro.org>
> Reviewed-by: Kees Cook <keescook at chromium.org>
> Signed-off-by: Guenter Roeck <linux at roeck-us.net>
> Reviewed-by: David Gow <davidgow at google.com>
> Signed-off-by: Alessandro Carminati <acarmina at redhat.com>
> Reviewed-by: David Gow <david at davidgow.net>
> Signed-off-by: Albert Esteve <aesteve at redhat.com>
> ---

This is great, thanks!

Reviewed-by: David Gow <david at davidgow.net>

Cheers,
-- David

>   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
> +	}
>