Documentation: KUnit: Update the instructions on how to test static functions

Now that we have the VISIBLE_IF_KUNIT and EXPORT_SYMBOL_IF_KUNIT macros,
update the instructions to recommend this way o

Documentation: KUnit: Update the instructions on how to test static functions

Now that we have the VISIBLE_IF_KUNIT and EXPORT_SYMBOL_IF_KUNIT macros,
update the instructions to recommend this way of testing static
functions.

Signed-off-by: Arthur Grillo <[email protected]>
Reviewed-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

kunit: add parameter generation macro using description from array

The existing KUNIT_ARRAY_PARAM macro requires a separate function to
get the description. However, in a lot of cases the descriptio

kunit: add parameter generation macro using description from array

The existing KUNIT_ARRAY_PARAM macro requires a separate function to
get the description. However, in a lot of cases the description can
just be copied directly from the array. Add a second macro that
avoids having to write a static function just for a single strscpy.

Signed-off-by: Benjamin Berg <[email protected]>
Reviewed-by: David Gow <[email protected]>
Link: https://msgid.link/[email protected]
Signed-off-by: Johannes Berg <[email protected]>

show more ...

kunit: Add APIs for managing devices

Tests for drivers often require a struct device to pass to other
functions. While it's possible to create these with
root_device_register(), or to use something

kunit: Add APIs for managing devices

Tests for drivers often require a struct device to pass to other
functions. While it's possible to create these with
root_device_register(), or to use something like a platform device, this
is both a misuse of those APIs, and can be difficult to clean up after,
for example, a failed assertion.

Add some KUnit-specific functions for registering and unregistering a
struct device:
- kunit_device_register()
- kunit_device_register_with_driver()
- kunit_device_unregister()

These helpers allocate a on a 'kunit' bus which will either probe the
driver passed in (kunit_device_register_with_driver), or will create a
stub driver (kunit_device_register) which is cleaned up on test shutdown.

Devices are automatically unregistered on test shutdown, but can be
manually unregistered earlier with kunit_device_unregister() in order
to, for example, test device release code.

Reviewed-by: Matti Vaittinen <[email protected]>
Reviewed-by: Maxime Ripard <[email protected]>
Signed-off-by: David Gow <[email protected]>
Reviewed-by: Greg Kroah-Hartman <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

kunit: Add a macro to wrap a deferred action function

KUnit's deferred action API accepts a void(*)(void *) function pointer
which is called when the test is exited. However, we very frequently
want

kunit: Add a macro to wrap a deferred action function

KUnit's deferred action API accepts a void(*)(void *) function pointer
which is called when the test is exited. However, we very frequently
want to use existing functions which accept a single pointer, but which
may not be of type void*. While this is probably dodgy enough to be on
the wrong side of the C standard, it's been often used for similar
callbacks, and gcc's -Wcast-function-type seems to ignore cases where
the only difference is the type of the argument, assuming it's
compatible (i.e., they're both pointers to data).

However, clang 16 has introduced -Wcast-function-type-strict, which no
longer permits any deviation in function pointer type. This seems to be
because it'd break CFI, which validates the type of function calls.

This rather ruins our attempts to cast functions to defer them, and
leaves us with a few options. The one we've chosen is to implement a
macro which will generate a wrapper function which accepts a void*, and
casts the argument to the appropriate type.

For example, if you were trying to wrap:
void foo_close(struct foo *handle);
you could use:
KUNIT_DEFINE_ACTION_WRAPPER(kunit_action_foo_close,
foo_close,
struct foo *);

This would create a new kunit_action_foo_close() function, of type
kunit_action_t, which could be passed into kunit_add_action() and
similar functions.

In addition to defining this macro, update KUnit and its tests to use
it.

Link: https://github.com/ClangBuiltLinux/linux/issues/1750
Reviewed-by: Nathan Chancellor <[email protected]>
Tested-by: Nathan Chancellor <[email protected]>
Acked-by: Daniel Vetter <[email protected]>
Reviewed-by: Maxime Ripard <[email protected]>
Signed-off-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: kunit: Add usage notes for kunit_add_action()

Add some basic documentation for kunit_add_action() and related
deferred action functions.

Reviewed-by: Rae Moar <[email protected]>
Sign

Documentation: kunit: Add usage notes for kunit_add_action()

Add some basic documentation for kunit_add_action() and related
deferred action functions.

Reviewed-by: Rae Moar <[email protected]>
Signed-off-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: kunit: Warn that exit functions run even if init fails

KUnit's exit functions will run even if the corresponding init function
fails. It's easy, when writing an exit function, to assu

Documentation: kunit: Warn that exit functions run even if init fails

KUnit's exit functions will run even if the corresponding init function
fails. It's easy, when writing an exit function, to assume the init
function succeeded, and (for example) access uninitialised memory or
dereference NULL pointers.

Note that this case exists and should be handled in the documentation.

Suggested-by: Benjamin Berg <[email protected]>
Link: https://lore.kernel.org/linux-kselftest/[email protected]/
Reviewed-by: Sadiya Kazi <[email protected]>
Signed-off-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: kunit: Note that assertions should not be used in cleanup

As assertions abort the test cleanup process, they should be avoided
from within a suite's exit function, or from within reso

Documentation: kunit: Note that assertions should not be used in cleanup

As assertions abort the test cleanup process, they should be avoided
from within a suite's exit function, or from within resource 'free'
functions. Unlike with initialisation or main test execution, no further
cleanup will be performed after a failed assertion, potentially causing
a leak of resources.

Reviewed-by: Sadiya Kazi <[email protected]>
Signed-off-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

kunit: Add "hooks" to call into KUnit when it's built as a module

KUnit has several macros and functions intended for use from non-test
code. These hooks, currently the kunit_get_current_test() and

kunit: Add "hooks" to call into KUnit when it's built as a module

KUnit has several macros and functions intended for use from non-test
code. These hooks, currently the kunit_get_current_test() and
kunit_fail_current_test() macros, didn't work when CONFIG_KUNIT=m.

In order to support this case, the required functions and static data
need to be available unconditionally, even when KUnit itself is not
built-in. The new 'hooks.c' file is therefore always included, and has
both the static key required for kunit_get_current_test(), and a table
of function pointers in struct kunit_hooks_table. This is filled in with
the real implementations by kunit_install_hooks(), which is kept in
hooks-impl.h and called when the kunit module is loaded.

This can be extended for future features which require similar
"hook" behaviour, such as static stubs, by simply adding new entries to
the struct, and the appropriate code to set them.

Fixed white-space errors during commit:
Shuah Khan <[email protected]>

Resolved merge conflicts with:
db105c37a4d6 ("kunit: Export kunit_running()")
This patch supersedes the above.
Shuah Khan <[email protected]>

Signed-off-by: David Gow <[email protected]>
Reviewed-by: Rae Moar <[email protected]>
Reviewed-by: Brendan Higgins <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

kunit: Use the static key when retrieving the current test

In order to detect if a KUnit test is running, and to access its
context, the 'kunit_test' member of the current task_struct is used.
Usual

kunit: Use the static key when retrieving the current test

In order to detect if a KUnit test is running, and to access its
context, the 'kunit_test' member of the current task_struct is used.
Usually, this is accessed directly or via the kunit_fail_current_task()
function.

In order to speed up the case where no test is running, add a wrapper,
kunit_get_current_test(), which uses the static key to fail early.
Equally, Speed up kunit_fail_current_test() by using the static key.

This should make it convenient for code to call this
unconditionally in fakes or error paths, without worrying that this will
slow the code down significantly.

If CONFIG_KUNIT=n (or m), this compiles away to nothing. If
CONFIG_KUNIT=y, it will compile down to a NOP (on most architectures) if
no KUnit test is currently running.

Note that kunit_get_current_test() does not work if KUnit is built as a
module. This mirrors the existing restriction on kunit_fail_current_test().

Note that the definition of kunit_fail_current_test() still wraps an
empty, inline function if KUnit is not built-in. This is to ensure that
the printf format string __attribute__ will still work.

Also update the documentation to suggest users use the new
kunit_get_current_test() function, update the example, and to describe
the behaviour when KUnit is disabled better.

Cc: Jonathan Corbet <[email protected]>
Cc: Sadiya Kazi <[email protected]>
Signed-off-by: David Gow <[email protected]>
Reviewed-by: Daniel Latypov <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: KUnit: reword description of assertions

The existing wording implies that kunit_kmalloc_array() is "the method
under test". We're actually testing the sort() function in that example.

Documentation: KUnit: reword description of assertions

The existing wording implies that kunit_kmalloc_array() is "the method
under test". We're actually testing the sort() function in that example.
This is because the example was changed in commit 953574390634
("Documentation: KUnit: Rework writing page to focus on writing tests"),
but the wording was not.

Also add a `note` telling people they can use the KUNIT_ASSERT_EQ()
macros from any function. Some users might be coming from a framework
like gUnit where that'll compile but silently do the wrong thing.

Signed-off-by: Daniel Latypov <[email protected]>
Reviewed-by: Sadiya Kazi <[email protected]>
Reviewed-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: KUnit: make usage.rst a superset of tips.rst, remove duplication

usage.rst had most of the content of the tips.rst page copied over.
But it's missing https://www.kernel.org/doc/html/v

Documentation: KUnit: make usage.rst a superset of tips.rst, remove duplication

usage.rst had most of the content of the tips.rst page copied over.
But it's missing https://www.kernel.org/doc/html/v6.0/dev-tools/kunit/tips.html#customizing-error-messages
Copy it over so we can retire tips.rst w/o losing content.

And in that process, it also gained a duplicate section about how
KUNIT_ASSERT_*() exit the test case early. Remove that.

Signed-off-by: Daniel Latypov <[email protected]>
Reviewed-by: Sadiya Kazi <[email protected]>
Reviewed-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: KUnit: Fix non-uml anchor

The section was rewritten but its anchor got left behind.
Fix the anchor and add some references to running on QEMU.

Signed-off-by: Tales Aparecida <tales.a

Documentation: KUnit: Fix non-uml anchor

The section was rewritten but its anchor got left behind.
Fix the anchor and add some references to running on QEMU.

Signed-off-by: Tales Aparecida <[email protected]>
Reviewed-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: KUnit: Fix example with compilation error

The Parameterized Testing example contains a compilation error, as the
signature for the description helper function is void(*)(const struct

Documentation: KUnit: Fix example with compilation error

The Parameterized Testing example contains a compilation error, as the
signature for the description helper function is void(*)(const struct
sha1_test_case *, char *), and the struct is non-const. This is
warned by Clang:

error: initialization of ‘void (*)(struct sha1_test_case *, char *)’
from incompatible pointer type ‘void (*)(const struct sha1_test_case *,
char *)’ [-Werror=incompatible-pointer-types]
33 | KUNIT_ARRAY_PARAM(sha1, cases, case_to_desc);
| ^~~~~~~~~~~~
../include/kunit/test.h:1339:70: note: in definition of macro
‘KUNIT_ARRAY_PARAM’
1339 | void
(*__get_desc)(typeof(__next), char *) = get_desc; \

Signed-off-by: Maíra Canal <[email protected]>
Reviewed-by: Daniel Latypov <[email protected]>
Reviewed-by: Brendan Higgins <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

kunit: add ability to specify suite-level init and exit functions

KUnit has support for setup/cleanup logic for each test case in a suite.
But it lacks the ability to specify setup/cleanup for the e

kunit: add ability to specify suite-level init and exit functions

KUnit has support for setup/cleanup logic for each test case in a suite.
But it lacks the ability to specify setup/cleanup for the entire suite
itself.

This can be used to do setup that is too expensive or cumbersome to do
for each test.
Or it can be used to do simpler things like log debug information after
the suite completes.
It's a fairly common feature, so the lack of it is noticeable.

Some examples in other frameworks and languages:
* https://docs.python.org/3/library/unittest.html#setupclass-and-teardownclass
* https://google.github.io/googletest/reference/testing.html#Test::SetUpTestSuite

Meta:
This is very similar to this patch here: https://lore.kernel.org/linux-kselftest/[email protected]/
The changes from that patch:
* pass in `struct kunit *` so users can do stuff like
`kunit_info(suite, "debug message")`
* makes sure the init failure is bubbled up as a failure
* updates kunit-example-test.c to use a suite init
* Updates kunit/usage.rst to mention the new support
* some minor cosmetic things
* use `suite_{init,exit}` instead of `{init/exit}_suite`
* make suite init error message more consistent w/ test init
* etc.

Signed-off-by: Daniel Latypov <[email protected]>
Reviewed-by: David Gow <[email protected]>
Reviewed-by: Brendan Higgins <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: KUnit: Fix usage bug

Fix a bug of kunit documentation.
Link: https://bugzilla.kernel.org/show_bug.cgi?id=205773

: Quoting Steve Pfetsch:
:
: kunit documentation is incorrect:
: https

Documentation: KUnit: Fix usage bug

Fix a bug of kunit documentation.
Link: https://bugzilla.kernel.org/show_bug.cgi?id=205773

: Quoting Steve Pfetsch:
:
: kunit documentation is incorrect:
: https://kunit.dev/third_party/stable_kernel/docs/usage.html
: struct rectangle *self = container_of(this, struct shape, parent);
:
:
: Shouldn't it be:
: struct rectangle *self = container_of(this, struct rectangle, parent);
: ?

Signed-off-by: Akira Kawata <[email protected]>
Reviewed-by: Brendan Higgins <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: KUnit: Rework writing page to focus on writing tests

We now have dedicated pages on running tests. Therefore refocus the
usage page on writing tests and add content from tips page and

Documentation: KUnit: Rework writing page to focus on writing tests

We now have dedicated pages on running tests. Therefore refocus the
usage page on writing tests and add content from tips page and
information on other architectures.

Signed-off-by: Harinder Singh <[email protected]>
Reviewed-by: Tim Bird <[email protected]>
Reviewed-by: Brendan Higgins <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation: kunit: Clean up some string casts in examples

As the type checking is no longer excessively strict, get rid of the
unsightly (char*) casts -- and comment discussing them -- from the K

Documentation: kunit: Clean up some string casts in examples

As the type checking is no longer excessively strict, get rid of the
unsightly (char*) casts -- and comment discussing them -- from the KUnit
usage page.

Signed-off-by: David Gow <[email protected]>
Reviewed-by: Daniel Latypov <[email protected]>
Acked-by: Brendan Higgins <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup

The :doc:`foo` tag is auto-generated via automarkup.py.
So, use the filename at the sources, instead of :doc:`foo`.

Reviewed-by: David Gow

docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup

The :doc:`foo` tag is auto-generated via automarkup.py.
So, use the filename at the sources, instead of :doc:`foo`.

Reviewed-by: David Gow <[email protected]>
Acked-by: Brendan Higgins <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/6fde409079959a95b62b9b2692503608d7ff0dbd.1623824363.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation: kunit: document support for QEMU in kunit_tool

Document QEMU support, what it does, and how to use it in kunit_tool.

Signed-off-by: Brendan Higgins <[email protected]>
Review

Documentation: kunit: document support for QEMU in kunit_tool

Document QEMU support, what it does, and how to use it in kunit_tool.

Signed-off-by: Brendan Higgins <[email protected]>
Reviewed-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: kunit: include example of a parameterized test

Commit fadb08e7c750 ("kunit: Support for Parameterized Testing")
introduced support but lacks documentation for how to use it.

This pat

Documentation: kunit: include example of a parameterized test

Commit fadb08e7c750 ("kunit: Support for Parameterized Testing")
introduced support but lacks documentation for how to use it.

This patch builds on commit 1f0e943df68a ("Documentation: kunit: provide
guidance for testing many inputs") to show a minimal example of the new
feature.

Signed-off-by: Daniel Latypov <[email protected]>
Reviewed-by: David Gow <[email protected]>
Tested-by: Brendan Higgins <[email protected]>
Acked-by: Brendan Higgins <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: kunit: provide guidance for testing many inputs

usage.rst goes into a detailed section about faking out classes, but
currently lacks wording about how one might idiomatically test a r

Documentation: kunit: provide guidance for testing many inputs

usage.rst goes into a detailed section about faking out classes, but
currently lacks wording about how one might idiomatically test a range
of inputs.

Add a new chapter for "Common Patterns" and group "Isolating behvaior"
and this new section under there.

Give an example of how one might test a hash function via macros/helper
funcs and a table-driven test and very briefly discuss pros and cons.

Also highlight the KUNIT_EXPECT_*_MSG() variants (that aren't mentioned
elsewhere [1]) which are particularly useful in these situations.

It is also criminally underused at the moment, only appearing in 2
tests (both written by people involved in KUnit).

[1] not even on
https://www.kernel.org/doc/html/latest/dev-tools/kunit/api/test.html

Signed-off-by: Daniel Latypov <[email protected]>
Reviewed-by: Brendan Higgins <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

KUnit: Docs: usage: wording fixes

Fix minor grammar and punctutation glitches.
Hyphenate "architecture-specific" instances.

Signed-off-by: Randy Dunlap <[email protected]>
Cc: David Gow <davidg

KUnit: Docs: usage: wording fixes

Fix minor grammar and punctutation glitches.
Hyphenate "architecture-specific" instances.

Signed-off-by: Randy Dunlap <[email protected]>
Cc: David Gow <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: Shuah Khan <[email protected]>
Cc: Shuah Khan <[email protected]>
Cc: Brendan Higgins <[email protected]>
Reviewed-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: kunit: Update Kconfig parts for KUNIT's module support

If 'CONFIG_KUNIT=m', letting kunit tests that do not support loadable
module build depends on 'KUNIT' instead of 'KUNIT=y' resul

Documentation: kunit: Update Kconfig parts for KUNIT's module support

If 'CONFIG_KUNIT=m', letting kunit tests that do not support loadable
module build depends on 'KUNIT' instead of 'KUNIT=y' result in compile
errors. This commit updates the document for this.

Fixes: 9fe124bf1b77 ("kunit: allow kunit to be loaded as a module")
Signed-off-by: SeongJae Park <[email protected]>
Reviewed-by: David Gow <[email protected]>
Reviewed-by: Brendan Higgins <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: kunit: add a brief blurb about kunit_test_suite

Add a brief blurb saying how and when the kunit_test_suite() macro
works to the usage documentation.

Signed-off-by: Brendan Higgins <b

Documentation: kunit: add a brief blurb about kunit_test_suite

Add a brief blurb saying how and when the kunit_test_suite() macro
works to the usage documentation.

Signed-off-by: Brendan Higgins <[email protected]>
Reviewed-by: Stephen Boyd <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...

Documentation: test.h - fix warnings

Fix warnings at 'make htmldocs', and formatting issues in the resulting
documentation.

- test.h: Fix annotation in kernel-doc parameter description.

- Document

Documentation: test.h - fix warnings

Fix warnings at 'make htmldocs', and formatting issues in the resulting
documentation.

- test.h: Fix annotation in kernel-doc parameter description.

- Documentation/*.rst: Fixing formatting issues, and a duplicate label
issue due to usage of sphinx.ext.autosectionlabel and identical labels
within one document (sphinx warning)

Signed-off-by: Lothar Rubusch <[email protected]>
Reviewed-by: Brendan Higgins <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...