linux-toradex.git/Documentation/dev-tools/kunit, branch v6.4-rc1

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

Documentation: kunit: Remove redundant 'tips.rst' page

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

The contents of 'tips.rst' was mostly included in 'usage.rst' way back in
commit 953574390634 ("Documentation: KUnit: Rework writing page to focus on writing tests"),
but the tips page remained behind as well.

The parent patches in this series fill in the gaps, so now 'tips.rst' is
redundant.
Therefore, delete 'tips.rst'.

While I regret breaking any links to 'tips' which might exist
externally, it's confusing to have two subtly different versions of the
same content around.

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

Documentation: KUnit: reword description of assertions

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

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

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

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

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

Documentation: Kunit: Update architecture.rst for minor fixes

2022-10-27T08:32:41+00:00

Updated the architecture.rst page with the following changes:
-Add missing article _the_ across the document.
-Reword content across for style and standard.
-Update all occurrences of Command Line to Command-line
 across the document.
-Correct grammatical issues, for example,
 added _it_wherever missing.
-Update all occurrences of “via" to either use
 “through” or “using”.
-Update the text preceding the external links and pushed the full
 link to a new line for better readability.
-Reword content under the config command to make it more clear and concise.

Signed-off-by: Sadiya Kazi 
Reviewed-by: David Gow 
Signed-off-by: Shuah Khan

Documentation: kunit: Update description of --alltests option

2022-10-07T16:19:25+00:00

kunit_tool's --alltests option was changed in commit
980ac3ad0512 ("kunit: tool: rename all_test_uml.config, use it for --alltests")
to use a manually curated list of architecture-indpendent Kconfig
options, rather than attempting to use make allyesconfig on UML, which
was broken.

Update the kunit_tool documentation to reflect the new behaviour of
--alltests.

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

Documentation: Kunit: Use full path to .kunitconfig

2022-09-30T19:23:06+00:00

The numbered list contains full path to every files that need to be
modified or created in order to implement misc-example kunit test.
Except for .kunitconfig. Which might make a newcommer confused about
where the file exists. Since there are multiple .kunitconfig files.

Fix this by using the full path to .kunitconfig.

Signed-off-by: Khalid Masum 
Reviewed-by: David Gow 
Signed-off-by: Shuah Khan