rust: kunit: allow to know if we are in a test

In some cases, we need to call test-only code from outside the test
case, for example, to mock a function or a module.

In order to check whether we ar

rust: kunit: allow to know if we are in a test

In some cases, we need to call test-only code from outside the test
case, for example, to mock a function or a module.

In order to check whether we are in a test or not, we need to test if
`CONFIG_KUNIT` is set.
Unfortunately, we cannot rely only on this condition because:
- a test could be running in another thread,
- some distros compile KUnit in production kernels, so checking at runtime
that `current->kunit_test != NULL` is required.

Forturately, KUnit provides an optimised check in
`kunit_get_current_test()`, which checks CONFIG_KUNIT, a global static
key, and then the current thread's running KUnit test.

Add a safe wrapper function around this to know whether or not we are in
a KUnit test and examples showing how to mock a function and a module.

Signed-off-by: José Expósito <[email protected]>
Co-developed-by: Miguel Ojeda <[email protected]>
Signed-off-by: Miguel Ojeda <[email protected]>
Co-developed-by: David Gow <[email protected]>
Signed-off-by: David Gow <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Miguel Ojeda <[email protected]>

show more ...

rust: macros: add macro to easily run KUnit tests

Add a new procedural macro (`#[kunit_tests(kunit_test_suit_name)]`) to
run KUnit tests using a user-space like syntax.

The macro, that should be us

rust: macros: add macro to easily run KUnit tests

Add a new procedural macro (`#[kunit_tests(kunit_test_suit_name)]`) to
run KUnit tests using a user-space like syntax.

The macro, that should be used on modules, transforms every `#[test]`
in a `kunit_case!` and adds a `kunit_unsafe_test_suite!` registering
all of them.

The only difference with user-space tests is that instead of using
`#[cfg(test)]`, `#[kunit_tests(kunit_test_suit_name)]` is used.

Note that `#[cfg(CONFIG_KUNIT)]` is added so the test module is not
compiled when `CONFIG_KUNIT` is set to `n`.

Reviewed-by: David Gow <[email protected]>
Signed-off-by: José Expósito <[email protected]>
Co-developed-by: Boqun Feng <[email protected]>
Signed-off-by: Boqun Feng <[email protected]>
Co-developed-by: Miguel Ojeda <[email protected]>
Signed-off-by: Miguel Ojeda <[email protected]>
Reviewed-by: Tamir Duberstein <[email protected]>
Signed-off-by: David Gow <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
[ Removed spurious (in rendered form) newline in docs. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>

show more ...

rust: kunit: add KUnit case and suite macros

Add a couple of Rust const functions and macros to allow to develop
KUnit tests without relying on generated C code:

- The `kunit_unsafe_test_suite!` R

rust: kunit: add KUnit case and suite macros

Add a couple of Rust const functions and macros to allow to develop
KUnit tests without relying on generated C code:

- The `kunit_unsafe_test_suite!` Rust macro is similar to the
`kunit_test_suite` C macro. It requires a NULL-terminated array of
test cases (see below).
- The `kunit_case` Rust function is similar to the `KUNIT_CASE` C macro.
It generates as case from the name and function.
- The `kunit_case_null` Rust function generates a NULL test case, which
is to be used as delimiter in `kunit_test_suite!`.

While these functions and macros can be used on their own, a future
patch will introduce another macro to create KUnit tests using a
user-space like syntax.

Signed-off-by: José Expósito <[email protected]>
Co-developed-by: Matt Gilbride <[email protected]>
Signed-off-by: Matt Gilbride <[email protected]>
Co-developed-by: Miguel Ojeda <[email protected]>
Signed-off-by: Miguel Ojeda <[email protected]>
Co-developed-by: David Gow <[email protected]>
Signed-off-by: David Gow <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
[ Applied Markdown in comment. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>

show more ...

rust: kunit: use C-string literals to clean warning

Starting with upstream Rust commit a5e3a3f9b6bd ("move
`manual_c_str_literals` to complexity"), to be released in Rust 1.83.0
[1], Clippy now warn

rust: kunit: use C-string literals to clean warning

Starting with upstream Rust commit a5e3a3f9b6bd ("move
`manual_c_str_literals` to complexity"), to be released in Rust 1.83.0
[1], Clippy now warns on `manual_c_str_literals` by default, e.g.:

error: manually constructing a nul-terminated string
--> rust/kernel/kunit.rs:21:13
|
21 | b"\x013%pA\0".as_ptr() as _,
| ^^^^^^^^^^^^^ help: use a `c""` literal: `c"\x013%pA"`
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#manual_c_str_literals
= note: `-D clippy::manual-c-str-literals` implied by `-D warnings`
= help: to override `-D warnings` add `#[allow(clippy::manual_c_str_literals)]`

Apply the suggestion to clean up the warnings.

Link: https://github.com/rust-lang/rust-clippy/pull/13263 [1]
Reviewed-by: Trevor Gross <[email protected]>
Reviewed-by: Benno Lossin <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Miguel Ojeda <[email protected]>

show more ...

rust: support `srctree`-relative links

Some of our links use relative paths in order to point to files in the
source tree, e.g.:

//! C header: [`include/linux/printk.h`](../../../../include/lin

rust: support `srctree`-relative links

Some of our links use relative paths in order to point to files in the
source tree, e.g.:

//! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h)
/// [`struct mutex`]: ../../../../include/linux/mutex.h

These are problematic because they are hard to maintain and do not support
`O=` builds.

Instead, provide support for `srctree`-relative links, e.g.:

//! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
/// [`struct mutex`]: srctree/include/linux/mutex.h

The links are fixed after `rustdoc` generation to be based on the absolute
path to the source tree.

Essentially, this is the automatic version of Tomonori's fix [1],
suggested by Gary [2].

Suggested-by: Gary Guo <[email protected]>
Reported-by: FUJITA Tomonori <[email protected]>
Closes: https://lore.kernel.org/r/[email protected] [1]
Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2]
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
Reviewed-by: Benno Lossin <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Miguel Ojeda <[email protected]>

show more ...

rust: support running Rust documentation tests as KUnit ones

Rust has documentation tests: these are typically examples of
usage of any item (e.g. function, struct, module...).

They are very conven

rust: support running Rust documentation tests as KUnit ones

Rust has documentation tests: these are typically examples of
usage of any item (e.g. function, struct, module...).

They are very convenient because they are just written
alongside the documentation. For instance:

/// Sums two numbers.
///
/// ```
/// assert_eq!(mymod::f(10, 20), 30);
/// ```
pub fn f(a: i32, b: i32) -> i32 {
a + b
}

In userspace, the tests are collected and run via `rustdoc`.
Using the tool as-is would be useful already, since it allows
to compile-test most tests (thus enforcing they are kept
in sync with the code they document) and run those that do not
depend on in-kernel APIs.

However, by transforming the tests into a KUnit test suite,
they can also be run inside the kernel. Moreover, the tests
get to be compiled as other Rust kernel objects instead of
targeting userspace.

On top of that, the integration with KUnit means the Rust
support gets to reuse the existing testing facilities. For
instance, the kernel log would look like:

KTAP version 1
1..1
KTAP version 1
# Subtest: rust_doctests_kernel
1..59
# rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13
ok 1 rust_doctest_kernel_build_assert_rs_0
# rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56
ok 2 rust_doctest_kernel_build_assert_rs_1
# rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122
ok 3 rust_doctest_kernel_init_rs_0
...
# rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
ok 59 rust_doctest_kernel_types_rs_2
# rust_doctests_kernel: pass:59 fail:0 skip:0 total:59
# Totals: pass:59 fail:0 skip:0 total:59
ok 1 rust_doctests_kernel

Therefore, add support for running Rust documentation tests
in KUnit. Some other notes about the current implementation
and support follow.

The transformation is performed by a couple scripts written
as Rust hostprogs.

Tests using the `?` operator are also supported as usual, e.g.:

/// ```
/// # use kernel::{spawn_work_item, workqueue};
/// spawn_work_item!(workqueue::system(), || pr_info!("x"))?;
/// # Ok::<(), Error>(())
/// ```

The tests are also compiled with Clippy under `CLIPPY=1`, just
like normal code, thus also benefitting from extra linting.

The names of the tests are currently automatically generated.
This allows to reduce the burden for documentation writers,
while keeping them fairly stable for bisection. This is an
improvement over the `rustdoc`-generated names, which include
the line number; but ideally we would like to get `rustdoc` to
provide the Rust item path and a number (for multiple examples
in a single documented Rust item).

In order for developers to easily see from which original line
a failed doctests came from, a KTAP diagnostic line is printed
to the log, containing the location (file and line) of the
original test (i.e. instead of the location in the generated
Rust file):

# rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150

This line follows the syntax for declaring test metadata in the
proposed KTAP v2 spec [1], which may be used for the proposed
KUnit test attributes API [2]. Thus hopefully this will make
migration easier later on (suggested by David [3]).

The original line in that test attribute is figured out by
providing an anchor (suggested by Boqun [4]). The original file
is found by walking the filesystem, checking directory prefixes
to reduce the amount of combinations to check, and it is only
done once per file. Ambiguities are detected and reported.

A notable difference from KUnit C tests is that the Rust tests
appear to assert using the usual `assert!` and `assert_eq!`
macros from the Rust standard library (`core`). We provide
a custom version that forwards the call to KUnit instead.
Importantly, these macros do not require passing context,
unlike the KUnit C ones (i.e. `struct kunit *`). This makes
them easier to use, and readers of the documentation do not need
to care about which testing framework is used. In addition, it
may allow us to test third-party code more easily in the future.

However, a current limitation is that KUnit does not support
assertions in other tasks. Thus we presently simply print an
error to the kernel log if an assertion actually failed. This
should be revisited to properly fail the test, perhaps saving
the context somewhere else, or letting KUnit handle it.

Link: https://lore.kernel.org/lkml/[email protected]/ [1]
Link: https://lore.kernel.org/linux-kselftest/[email protected]/ [2]
Link: https://lore.kernel.org/rust-for-linux/CABVgOSkOLO-8v6kdAGpmYnZUb+LKOX0CtYCo-Bge7r_2YTuXDQ@mail.gmail.com/ [3]
Link: https://lore.kernel.org/rust-for-linux/ZIps86MbJF%2FiGIzd@boqun-archlinux/ [4]
Signed-off-by: Miguel Ojeda <[email protected]>
Reviewed-by: David Gow <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>

show more ...