linux-stable.git/Documentation/dev-tools/kunit, branch v6.5.2

Documentation: kunit: Rename references to kunit_abort()

2023-06-06T14:57:37+00:00

The kunit_abort() function has been renamed __kunit_abort(), update the
references to it in the documentation.

Suggested-by: Daniel Latypov 
Signed-off-by: David Gow 
Reviewed-by: Daniel Latypov 
Signed-off-by: Shuah Khan

Documentation: Kunit: add MODULE_LICENSE to sample code

2023-05-31T18:42:40+00:00

The sample code has Kconfig for tristate configuration. In the case, it
could be friendly to developers that the code has MODULE_LICENSE, since
the missing MODULE_LICENSE brings error to modpost when the code is built
as loadable kernel module.

Signed-off-by: Takashi Sakamoto 
Reviewed-by: David Gow 
Signed-off-by: Shuah Khan

Documentation: kunit: Add usage notes for kunit_add_action()

2023-05-25T14:53:12+00:00

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

Reviewed-by: Rae Moar 
Signed-off-by: David Gow 
Signed-off-by: Shuah Khan

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

2023-05-12T00:17:35+00:00

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 
Link: https://lore.kernel.org/linux-kselftest/a39af0400abedb2e9b31d84c37551cecc3eed0e1.camel@sipsolutions.net/
Reviewed-by: Sadiya Kazi 
Signed-off-by: David Gow 
Signed-off-by: Shuah Khan

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

2023-05-12T00:17:29+00:00

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 
Signed-off-by: David Gow 
Signed-off-by: Shuah Khan

Documentation: kunit: Modular tests should not depend on KUNIT=y

2023-05-08T14:39:49+00:00

When the documentation was updated for modular tests, the dependency on
"KUNIT=y" was forgotten to be updated, now encouraging people to create
tests that cannot be enabled when the KUNIT framework itself is modular.
Fix this by changing the dependency to "KUNIT".

Document when it is appropriate (and required) to depend on "KUNIT=y".

Fixes: c9ef2d3e3f3b ("KUnit: Docs: make start.rst example Kconfig follow style.rst")
Signed-off-by: Geert Uytterhoeven 
Reviewed-by: David Gow 
Signed-off-by: Shuah Khan

Documentation: Add Function Redirection API docs

2023-02-08T21:28:17+00:00

Added a new page (functionredirection.rst) that describes the Function
Redirection (static stubbing) API. This page will be expanded if we add,
for example, ftrace-based stubbing.

In addition,
1. Updated the api/index.rst page to create an entry for function
   redirection api
2. Updated the toctree to be hidden, reducing redundancy on the
   generated page.

Signed-off-by: Sadiya Kazi 
Co-developed-by: Daniel Latypov 
Signed-off-by: Daniel Latypov 
Co-developed-by: David Gow 
Signed-off-by: David Gow 
Reviewed-by: Brendan Higgins 
Signed-off-by: Shuah Khan

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

2023-02-08T21:26:25+00:00

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 

Resolved merge conflicts with:
db105c37a4d6 ("kunit: Export kunit_running()")
This patch supersedes the above.
Shuah Khan 

Signed-off-by: David Gow 
Reviewed-by: Rae Moar 
Reviewed-by: Brendan Higgins 
Signed-off-by: Shuah Khan

Documentation: kunit: Fix "How Do I Use This" / "Next Steps" sections

2022-12-12T21:13:48+00:00

The "How Do I Use This" section of index.rst and "Next Steps" section of
start.rst were just copies of the table of contents, and therefore
weren't really useful either when looking a sphinx generated output
(which already had the TOC visible) or when reading the source (where
it's just a list of files that ls could give you).

Instead, provide a small number of concrete next steps, and a bit more
description about what the pages contain.

This also removes the broken reference to 'tips.rst', which was
previously removed.

Fixed git am whitespace complaints during commit:
Shuah Khan 

Fixes: 4399c737a97d ("Documentation: kunit: Remove redundant 'tips.rst' page")
Signed-off-by: David Gow 
Reviewed-by: Sadiya Kazi 
Reviewed-by: Bagas Sanjaya 
Signed-off-by: Shuah Khan

kunit: Use the static key when retrieving the current test

2022-12-12T21:13:47+00:00

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 
Cc: Sadiya Kazi 
Signed-off-by: David Gow 
Reviewed-by: Daniel Latypov 
Signed-off-by: Shuah Khan