This is the initial KUnit integration for running Rust documentation
tests within the kernel.
Thank you to the KUnit team for all the input and feedback on this
over the months, as well as the Intel LKP 0-Day team!
This may be merged through either the KUnit or the Rust trees. If
the KUnit team wants to merge it, then that would be great.
Please see the message in the main commit for the details.
Miguel Ojeda (6):
rust: init: make doctests compilable/testable
rust: str: make doctests compilable/testable
rust: sync: make doctests compilable/testable
rust: types: make doctests compilable/testable
rust: support running Rust documentation tests as KUnit ones
MAINTAINERS: add Rust KUnit files to the KUnit entry
MAINTAINERS | 2 +
lib/Kconfig.debug | 13 +++
rust/.gitignore | 2 +
rust/Makefile | 29 ++++++
rust/bindings/bindings_helper.h | 1 +
rust/helpers.c | 7 ++
rust/kernel/init.rs | 25 +++--
rust/kernel/kunit.rs | 156 ++++++++++++++++++++++++++++
rust/kernel/lib.rs | 2 +
rust/kernel/str.rs | 4 +-
rust/kernel/sync/arc.rs | 9 +-
rust/kernel/sync/lock/mutex.rs | 1 +
rust/kernel/sync/lock/spinlock.rs | 1 +
rust/kernel/types.rs | 6 +-
scripts/.gitignore | 2 +
scripts/Makefile | 4 +
scripts/rustdoc_test_builder.rs | 73 ++++++++++++++
scripts/rustdoc_test_gen.rs | 162 ++++++++++++++++++++++++++++++
18 files changed, 484 insertions(+), 15 deletions(-)
create mode 100644 rust/kernel/kunit.rs
create mode 100644 scripts/rustdoc_test_builder.rs
create mode 100644 scripts/rustdoc_test_gen.rs
base-commit: d2e3115d717197cb2bc020dd1f06b06538474ac3
--
2.41.0
Rust documentation tests are going to be build/run-tested
with the KUnit integration added in a future patch, thus
update them to make them compilable/testable so that we
may start enforcing it.
Signed-off-by: Miguel Ojeda <[email protected]>
---
rust/kernel/init.rs | 25 ++++++++++++++++---------
1 file changed, 16 insertions(+), 9 deletions(-)
diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
index b4332a4ec1f4..1073515ed40e 100644
--- a/rust/kernel/init.rs
+++ b/rust/kernel/init.rs
@@ -120,14 +120,23 @@
//! `slot` gets called.
//!
//! ```rust
-//! use kernel::{prelude::*, init};
+//! # #![allow(unreachable_pub, clippy::disallowed_names)]
+//! use kernel::{prelude::*, init, types::Opaque};
//! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin};
//! # mod bindings {
+//! # #![allow(non_camel_case_types)]
//! # pub struct foo;
//! # pub unsafe fn init_foo(_ptr: *mut foo) {}
//! # pub unsafe fn destroy_foo(_ptr: *mut foo) {}
//! # pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 }
//! # }
+//! # trait FromErrno {
+//! # fn from_errno(errno: core::ffi::c_int) -> Error {
+//! # // Dummy error that can be constructed outside the `kernel` crate.
+//! # Error::from(core::fmt::Error)
+//! # }
+//! # }
+//! # impl FromErrno for Error {}
//! /// # Invariants
//! ///
//! /// `foo` is always initialized
@@ -158,7 +167,7 @@
//! if err != 0 {
//! // Enabling has failed, first clean up the foo and then return the error.
//! bindings::destroy_foo(Opaque::raw_get(foo));
-//! return Err(Error::from_kernel_errno(err));
+//! return Err(Error::from_errno(err));
//! }
//!
//! // All fields of `RawFoo` have been initialized, since `_p` is a ZST.
@@ -226,8 +235,7 @@
///
/// ```rust
/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
-/// # use kernel::{init, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
-/// # use macros::pin_data;
+/// # use kernel::{init, macros::pin_data, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
/// # use core::pin::Pin;
/// #[pin_data]
/// struct Foo {
@@ -277,7 +285,7 @@ macro_rules! stack_pin_init {
///
/// # Examples
///
-/// ```rust
+/// ```rust,ignore
/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
/// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
/// # use macros::pin_data;
@@ -303,7 +311,7 @@ macro_rules! stack_pin_init {
/// pr_info!("a: {}", &*foo.a.lock());
/// ```
///
-/// ```rust
+/// ```rust,ignore
/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
/// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
/// # use macros::pin_data;
@@ -513,8 +521,7 @@ macro_rules! stack_try_pin_init {
/// For instance:
///
/// ```rust
-/// # use kernel::pin_init;
-/// # use macros::pin_data;
+/// # use kernel::{macros::pin_data, pin_init};
/// # use core::{ptr::addr_of_mut, marker::PhantomPinned};
/// #[pin_data]
/// struct Buf {
@@ -841,7 +848,7 @@ macro_rules! init {
/// # Examples
///
/// ```rust
-/// use kernel::{init::PinInit, error::Error, InPlaceInit};
+/// use kernel::{init::{PinInit, zeroed}, error::Error};
/// struct BigBuf {
/// big: Box<[u8; 1024 * 1024 * 1024]>,
/// small: [u8; 1024 * 1024],
--
2.41.0
The KUnit maintainers would like to maintain these files on their
side too (thanks!), so add them to their entry.
With this in place, `scripts/get_maintainer.pl` prints both sets
of maintainers/reviewers (i.e. KUnit and Rust) for those files,
which is the behavior we are looking for.
Signed-off-by: Miguel Ojeda <[email protected]>
---
MAINTAINERS | 2 ++
1 file changed, 2 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 250518fc70ff..f4c9ce1b685f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11323,6 +11323,8 @@ W: https://google.github.io/kunit-docs/third_party/kernel/docs/
F: Documentation/dev-tools/kunit/
F: include/kunit/
F: lib/kunit/
+F: rust/kernel/kunit.rs
+F: scripts/rustdoc_test_*
F: tools/testing/kunit/
KERNEL USERMODE HELPER
--
2.41.0
Rust documentation tests are going to be build/run-tested
with the KUnit integration added in a future patch, thus
update them to make them compilable/testable so that we
may start enforcing it.
Signed-off-by: Miguel Ojeda <[email protected]>
---
rust/kernel/str.rs | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs
index c9dd3bf59e34..c41607b2e4fe 100644
--- a/rust/kernel/str.rs
+++ b/rust/kernel/str.rs
@@ -213,6 +213,7 @@ impl fmt::Display for CStr {
///
/// ```
/// # use kernel::c_str;
+ /// # use kernel::fmt;
/// # use kernel::str::CStr;
/// # use kernel::str::CString;
/// let penguin = c_str!("????");
@@ -241,6 +242,7 @@ impl fmt::Debug for CStr {
///
/// ```
/// # use kernel::c_str;
+ /// # use kernel::fmt;
/// # use kernel::str::CStr;
/// # use kernel::str::CString;
/// let penguin = c_str!("????");
@@ -529,7 +531,7 @@ fn write_str(&mut self, s: &str) -> fmt::Result {
/// # Examples
///
/// ```
-/// use kernel::str::CString;
+/// use kernel::{str::CString, fmt};
///
/// let s = CString::try_from_fmt(fmt!("{}{}{}", "abc", 10, 20)).unwrap();
/// assert_eq!(s.as_bytes_with_nul(), "abc1020\0".as_bytes());
--
2.41.0
Rust documentation tests are going to be build/run-tested
with the KUnit integration added in a future patch, thus
update them to make them compilable/testable so that we
may start enforcing it.
Signed-off-by: Miguel Ojeda <[email protected]>
---
rust/kernel/sync/arc.rs | 9 +++++++--
rust/kernel/sync/lock/mutex.rs | 1 +
rust/kernel/sync/lock/spinlock.rs | 1 +
3 files changed, 9 insertions(+), 2 deletions(-)
diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs
index a89843cacaad..1ecb2efab51e 100644
--- a/rust/kernel/sync/arc.rs
+++ b/rust/kernel/sync/arc.rs
@@ -73,6 +73,7 @@
/// assert_eq!(cloned.b, 20);
///
/// // The refcount drops to zero when `cloned` goes out of scope, and the memory is freed.
+/// # Ok::<(), Error>(())
/// ```
///
/// Using `Arc<T>` as the type of `self`:
@@ -98,6 +99,7 @@
/// let obj = Arc::try_new(Example { a: 10, b: 20 })?;
/// obj.use_reference();
/// obj.take_over();
+/// # Ok::<(), Error>(())
/// ```
///
/// Coercion from `Arc<Example>` to `Arc<dyn MyTrait>`:
@@ -121,6 +123,7 @@
///
/// // `coerced` has type `Arc<dyn MyTrait>`.
/// let coerced: Arc<dyn MyTrait> = obj;
+/// # Ok::<(), Error>(())
/// ```
pub struct Arc<T: ?Sized> {
ptr: NonNull<ArcInner<T>>,
@@ -337,7 +340,7 @@ fn from(item: Pin<UniqueArc<T>>) -> Self {
/// # Example
///
/// ```
-/// use crate::sync::{Arc, ArcBorrow};
+/// use kernel::sync::{Arc, ArcBorrow};
///
/// struct Example;
///
@@ -350,12 +353,13 @@ fn from(item: Pin<UniqueArc<T>>) -> Self {
///
/// // Assert that both `obj` and `cloned` point to the same underlying object.
/// assert!(core::ptr::eq(&*obj, &*cloned));
+/// # Ok::<(), Error>(())
/// ```
///
/// Using `ArcBorrow<T>` as the type of `self`:
///
/// ```
-/// use crate::sync::{Arc, ArcBorrow};
+/// use kernel::sync::{Arc, ArcBorrow};
///
/// struct Example {
/// a: u32,
@@ -370,6 +374,7 @@ fn from(item: Pin<UniqueArc<T>>) -> Self {
///
/// let obj = Arc::try_new(Example { a: 10, b: 20 })?;
/// obj.as_arc_borrow().use_reference();
+/// # Ok::<(), Error>(())
/// ```
pub struct ArcBorrow<'a, T: ?Sized + 'a> {
inner: NonNull<ArcInner<T>>,
diff --git a/rust/kernel/sync/lock/mutex.rs b/rust/kernel/sync/lock/mutex.rs
index 923472f04af4..09276fedc091 100644
--- a/rust/kernel/sync/lock/mutex.rs
+++ b/rust/kernel/sync/lock/mutex.rs
@@ -63,6 +63,7 @@ macro_rules! new_mutex {
/// assert_eq!(e.c, 10);
/// assert_eq!(e.d.lock().a, 20);
/// assert_eq!(e.d.lock().b, 30);
+/// # Ok::<(), Error>(())
/// ```
///
/// The following example shows how to use interior mutability to modify the contents of a struct
diff --git a/rust/kernel/sync/lock/spinlock.rs b/rust/kernel/sync/lock/spinlock.rs
index 979b56464a4e..91eb2c9e9123 100644
--- a/rust/kernel/sync/lock/spinlock.rs
+++ b/rust/kernel/sync/lock/spinlock.rs
@@ -61,6 +61,7 @@ macro_rules! new_spinlock {
/// assert_eq!(e.c, 10);
/// assert_eq!(e.d.lock().a, 20);
/// assert_eq!(e.d.lock().b, 30);
+/// # Ok::<(), Error>(())
/// ```
///
/// The following example shows how to use interior mutability to modify the contents of a struct
--
2.41.0
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
# Doctest from line 13
ok 1 rust_doctest_kernel_build_assert_rs_0
# Doctest from line 56
ok 2 rust_doctest_kernel_build_assert_rs_1
# Doctest from line 122
ok 3 rust_doctest_kernel_init_rs_0
...
# Doctest from line 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. In the future, we may be able to use a proper KUnit
facility to append this sort of information instead.
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.
Signed-off-by: Miguel Ojeda <[email protected]>
---
lib/Kconfig.debug | 13 +++
rust/.gitignore | 2 +
rust/Makefile | 29 ++++++
rust/bindings/bindings_helper.h | 1 +
rust/helpers.c | 7 ++
rust/kernel/kunit.rs | 156 ++++++++++++++++++++++++++++++
rust/kernel/lib.rs | 2 +
scripts/.gitignore | 2 +
scripts/Makefile | 4 +
scripts/rustdoc_test_builder.rs | 73 ++++++++++++++
scripts/rustdoc_test_gen.rs | 162 ++++++++++++++++++++++++++++++++
11 files changed, 451 insertions(+)
create mode 100644 rust/kernel/kunit.rs
create mode 100644 scripts/rustdoc_test_builder.rs
create mode 100644 scripts/rustdoc_test_gen.rs
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index ce51d4dc6803..49f5e9c42200 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -2911,6 +2911,19 @@ config RUST_BUILD_ASSERT_ALLOW
If unsure, say N.
+config RUST_KERNEL_KUNIT_TEST
+ bool "KUnit test for the `kernel` crate" if !KUNIT_ALL_TESTS
+ depends on RUST && KUNIT=y
+ default KUNIT_ALL_TESTS
+ help
+ This builds the documentation tests of the `kernel` crate
+ as KUnit tests.
+
+ For more information on KUnit and unit tests in general,
+ please refer to the KUnit documentation in Documentation/dev-tools/kunit/.
+
+ If unsure, say N.
+
endmenu # "Rust"
endmenu # Kernel hacking
diff --git a/rust/.gitignore b/rust/.gitignore
index 21552992b401..d3829ffab80b 100644
--- a/rust/.gitignore
+++ b/rust/.gitignore
@@ -2,6 +2,8 @@
bindings_generated.rs
bindings_helpers_generated.rs
+doctests_kernel_generated.rs
+doctests_kernel_generated_kunit.c
uapi_generated.rs
exports_*_generated.h
doc/
diff --git a/rust/Makefile b/rust/Makefile
index 7c9d9f11aec5..e4e8b83752e2 100644
--- a/rust/Makefile
+++ b/rust/Makefile
@@ -27,6 +27,12 @@ endif
obj-$(CONFIG_RUST) += exports.o
+always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated.rs
+always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated_kunit.c
+
+obj-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated.o
+obj-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated_kunit.o
+
# Avoids running `$(RUSTC)` for the sysroot when it may not be available.
ifdef CONFIG_RUST
@@ -39,9 +45,11 @@ ifeq ($(quiet),silent_)
cargo_quiet=-q
rust_test_quiet=-q
rustdoc_test_quiet=--test-args -q
+rustdoc_test_kernel_quiet=>/dev/null
else ifeq ($(quiet),quiet_)
rust_test_quiet=-q
rustdoc_test_quiet=--test-args -q
+rustdoc_test_kernel_quiet=>/dev/null
else
cargo_quiet=--verbose
endif
@@ -157,6 +165,27 @@ quiet_cmd_rustdoc_test = RUSTDOC T $<
-L$(objtree)/$(obj)/test --output $(objtree)/$(obj)/doc \
--crate-name $(subst rusttest-,,$@) $<
+quiet_cmd_rustdoc_test_kernel = RUSTDOC TK $<
+ cmd_rustdoc_test_kernel = \
+ rm -rf $(objtree)/$(obj)/test/doctests/kernel; \
+ mkdir -p $(objtree)/$(obj)/test/doctests/kernel; \
+ OBJTREE=$(abspath $(objtree)) \
+ $(RUSTDOC) --test $(rust_flags) \
+ @$(objtree)/include/generated/rustc_cfg \
+ -L$(objtree)/$(obj) --extern alloc --extern kernel \
+ --extern build_error --extern macros \
+ --extern bindings --extern uapi \
+ --no-run --crate-name kernel -Zunstable-options \
+ --test-builder $(objtree)/scripts/rustdoc_test_builder \
+ $< $(rustdoc_test_kernel_quiet); \
+ $(objtree)/scripts/rustdoc_test_gen
+
+%/doctests_kernel_generated.rs %/doctests_kernel_generated_kunit.c: \
+ $(src)/kernel/lib.rs $(obj)/kernel.o \
+ $(objtree)/scripts/rustdoc_test_builder \
+ $(objtree)/scripts/rustdoc_test_gen FORCE
+ $(call if_changed,rustdoc_test_kernel)
+
# We cannot use `-Zpanic-abort-tests` because some tests are dynamic,
# so for the moment we skip `-Cpanic=abort`.
quiet_cmd_rustc_test = RUSTC T $<
diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
index 3e601ce2548d..0f8d37c31ac2 100644
--- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h
@@ -6,6 +6,7 @@
* Sorted alphabetically.
*/
+#include <kunit/test.h>
#include <linux/errname.h>
#include <linux/slab.h>
#include <linux/refcount.h>
diff --git a/rust/helpers.c b/rust/helpers.c
index bb594da56137..49a5e1a4f0ae 100644
--- a/rust/helpers.c
+++ b/rust/helpers.c
@@ -18,6 +18,7 @@
* accidentally exposed.
*/
+#include <kunit/test-bug.h>
#include <linux/bug.h>
#include <linux/build_bug.h>
#include <linux/err.h>
@@ -135,6 +136,12 @@ void rust_helper_put_task_struct(struct task_struct *t)
}
EXPORT_SYMBOL_GPL(rust_helper_put_task_struct);
+struct kunit *rust_helper_kunit_get_current_test(void)
+{
+ return kunit_get_current_test();
+}
+EXPORT_SYMBOL_GPL(rust_helper_kunit_get_current_test);
+
/*
* We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type
* as the Rust `usize` type, so we can use it in contexts where Rust
diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs
new file mode 100644
index 000000000000..3c94efcd7f76
--- /dev/null
+++ b/rust/kernel/kunit.rs
@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! KUnit-based macros for Rust unit tests.
+//!
+//! C header: [`include/kunit/test.h`](../../../../../include/kunit/test.h)
+//!
+//! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>
+
+use core::{ffi::c_void, fmt};
+
+/// Prints a KUnit error.
+///
+/// Public but hidden since it should only be used from KUnit generated code.
+#[doc(hidden)]
+pub fn err(args: fmt::Arguments<'_>) {
+ // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we
+ // are passing.
+ #[cfg(CONFIG_PRINTK)]
+ unsafe {
+ bindings::_printk(
+ b"\x013%pA\0".as_ptr() as _,
+ &args as *const _ as *const c_void,
+ );
+ }
+}
+
+/// Prints a KUnit error.
+///
+/// Public but hidden since it should only be used from KUnit generated code.
+#[doc(hidden)]
+pub fn info(args: fmt::Arguments<'_>) {
+ // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we
+ // are passing.
+ #[cfg(CONFIG_PRINTK)]
+ unsafe {
+ bindings::_printk(
+ b"\x016%pA\0".as_ptr() as _,
+ &args as *const _ as *const c_void,
+ );
+ }
+}
+
+/// Asserts that a boolean expression is `true` at runtime.
+///
+/// Public but hidden since it should only be used from generated tests.
+///
+/// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit
+/// facilities. See [`assert!`] for more details.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! kunit_assert {
+ ($name:literal, $condition:expr $(,)?) => {
+ 'out: {
+ // Do nothing if the condition is `true`.
+ if $condition {
+ break 'out;
+ }
+
+ static LINE: i32 = core::line!() as i32;
+ static FILE: &'static $crate::str::CStr = $crate::c_str!(core::file!());
+ static CONDITION: &'static $crate::str::CStr = $crate::c_str!(stringify!($condition));
+
+ // SAFETY: FFI call without safety requirements.
+ let kunit_test = unsafe { $crate::bindings::kunit_get_current_test() };
+ if kunit_test.is_null() {
+ // The assertion failed but this task is not running a KUnit test, so we cannot call
+ // KUnit, but at least print an error to the kernel log. This may happen if this
+ // macro is called from an spawned thread in a test (see
+ // `scripts/rustdoc_test_gen.rs`) or if some non-test code calls this macro by
+ // mistake (it is hidden to prevent that).
+ //
+ // This mimics KUnit's failed assertion format.
+ $crate::kunit::err(format_args!(
+ " # {}: ASSERTION FAILED at {FILE}:{LINE}\n",
+ $name
+ ));
+ $crate::kunit::err(format_args!(
+ " Expected {CONDITION} to be true, but is false\n"
+ ));
+ $crate::kunit::err(format_args!(
+ " Failure not reported to KUnit since this is a non-KUnit task\n"
+ ));
+ break 'out;
+ }
+
+ #[repr(transparent)]
+ struct Location($crate::bindings::kunit_loc);
+
+ #[repr(transparent)]
+ struct UnaryAssert($crate::bindings::kunit_unary_assert);
+
+ // SAFETY: There is only a static instance and in that one the pointer field points to
+ // an immutable C string.
+ unsafe impl Sync for Location {}
+
+ // SAFETY: There is only a static instance and in that one the pointer field points to
+ // an immutable C string.
+ unsafe impl Sync for UnaryAssert {}
+
+ static LOCATION: Location = Location($crate::bindings::kunit_loc {
+ file: FILE.as_char_ptr(),
+ line: LINE,
+ });
+ static ASSERTION: UnaryAssert = UnaryAssert($crate::bindings::kunit_unary_assert {
+ assert: $crate::bindings::kunit_assert {},
+ condition: CONDITION.as_char_ptr(),
+ expected_true: true,
+ });
+
+ // SAFETY:
+ // - FFI call.
+ // - The `kunit_test` pointer is valid because we got it from
+ // `kunit_get_current_test()` and it was not null. This means we are in a KUnit
+ // test, and that the pointer can be passed to KUnit functions and assertions.
+ // - The string pointers (`file` and `condition` above) point to null-terminated
+ // strings since they are `CStr`s.
+ // - The function pointer (`format`) points to the proper function.
+ // - The pointers passed will remain valid since they point to `static`s.
+ // - The format string is allowed to be null.
+ // - There are, however, problems with this: first of all, this will end up stopping
+ // the thread, without running destructors. While that is problematic in itself,
+ // it is considered UB to have what is effectively a forced foreign unwind
+ // with `extern "C"` ABI. One could observe the stack that is now gone from
+ // another thread. We should avoid pinning stack variables to prevent library UB,
+ // too. For the moment, given that test failures are reported immediately before the
+ // next test runs, that test failures should be fixed and that KUnit is explicitly
+ // documented as not suitable for production environments, we feel it is reasonable.
+ unsafe {
+ $crate::bindings::kunit_do_failed_assertion(
+ kunit_test,
+ core::ptr::addr_of!(LOCATION.0),
+ $crate::bindings::kunit_assert_type_KUNIT_ASSERTION,
+ core::ptr::addr_of!(ASSERTION.0.assert),
+ Some($crate::bindings::kunit_unary_assert_format),
+ core::ptr::null(),
+ );
+ }
+ }
+ };
+}
+
+/// Asserts that two expressions are equal to each other (using [`PartialEq`]).
+///
+/// Public but hidden since it should only be used from generated tests.
+///
+/// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit
+/// facilities. See [`assert!`] for more details.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! kunit_assert_eq {
+ ($name:literal, $left:expr, $right:expr $(,)?) => {{
+ // For the moment, we just forward to the expression assert because, for binary asserts,
+ // KUnit supports only a few types (e.g. integers).
+ $crate::kunit_assert!($name, $left == $right);
+ }};
+}
diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index 85b261209977..3642cadc34b1 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -34,6 +34,8 @@
pub mod error;
pub mod init;
pub mod ioctl;
+#[cfg(CONFIG_KUNIT)]
+pub mod kunit;
pub mod prelude;
pub mod print;
mod static_assert;
diff --git a/scripts/.gitignore b/scripts/.gitignore
index 6e9ce6720a05..3dbb8bb2457b 100644
--- a/scripts/.gitignore
+++ b/scripts/.gitignore
@@ -5,6 +5,8 @@
/kallsyms
/module.lds
/recordmcount
+/rustdoc_test_builder
+/rustdoc_test_gen
/sign-file
/sorttable
/target.json
diff --git a/scripts/Makefile b/scripts/Makefile
index 32b6ba722728..d5a5382e753c 100644
--- a/scripts/Makefile
+++ b/scripts/Makefile
@@ -9,6 +9,8 @@ hostprogs-always-$(CONFIG_BUILDTIME_TABLE_SORT) += sorttable
hostprogs-always-$(CONFIG_ASN1) += asn1_compiler
hostprogs-always-$(CONFIG_MODULE_SIG_FORMAT) += sign-file
hostprogs-always-$(CONFIG_SYSTEM_EXTRA_CERTIFICATE) += insert-sys-cert
+hostprogs-always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += rustdoc_test_builder
+hostprogs-always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += rustdoc_test_gen
always-$(CONFIG_RUST) += target.json
filechk_rust_target = $< < include/config/auto.conf
@@ -18,6 +20,8 @@ $(obj)/target.json: scripts/generate_rust_target include/config/auto.conf FORCE
hostprogs += generate_rust_target
generate_rust_target-rust := y
+rustdoc_test_builder-rust := y
+rustdoc_test_gen-rust := y
HOSTCFLAGS_sorttable.o = -I$(srctree)/tools/include
HOSTLDLIBS_sorttable = -lpthread
diff --git a/scripts/rustdoc_test_builder.rs b/scripts/rustdoc_test_builder.rs
new file mode 100644
index 000000000000..e3b7138fb4f9
--- /dev/null
+++ b/scripts/rustdoc_test_builder.rs
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Test builder for `rustdoc`-generated tests.
+//!
+//! This script is a hack to extract the test from `rustdoc`'s output. Ideally, `rustdoc` would
+//! have an option to generate this information instead, e.g. as JSON output.
+//!
+//! The `rustdoc`-generated test names look like `{file}_{line}_{number}`, e.g.
+//! `...path_rust_kernel_sync_arc_rs_42_0`. `number` is the "test number", needed in cases like
+//! a macro that expands into items with doctests is invoked several times within the same line.
+//!
+//! However, since these names are used for bisection in CI, the line number makes it not stable
+//! at all. In the future, we would like `rustdoc` to give us the Rust item path associated with
+//! the test, plus a "test number" (for cases with several examples per item) and generate a name
+//! from that. For the moment, we generate ourselves a new name, `{file}_{number}` instead, in
+//! the `gen` script (done there since we need to be aware of all the tests in a given file).
+
+use std::fs::File;
+use std::io::{BufWriter, Read, Write};
+
+fn main() {
+ let mut stdin = std::io::stdin().lock();
+ let mut body = String::new();
+ stdin.read_to_string(&mut body).unwrap();
+
+ // Find the generated function name looking for the inner function inside `main()`.
+ //
+ // The line we are looking for looks like one of the following:
+ //
+ // ```
+ // fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_28_0() {
+ // fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_37_0() -> Result<(), impl core::fmt::Debug> {
+ // ```
+ //
+ // It should be unlikely that doctest code matches such lines (when code is formatted properly).
+ let rustdoc_function_name = body
+ .lines()
+ .find_map(|line| {
+ Some(
+ line.split_once("fn main() {")?
+ .1
+ .split_once("fn ")?
+ .1
+ .split_once("()")?
+ .0,
+ )
+ .filter(|x| x.chars().all(|c| c.is_alphanumeric() || c == '_'))
+ })
+ .expect("No test function found in `rustdoc`'s output.");
+
+ // Qualify `Result` to avoid the collision with our own `Result` coming from the prelude.
+ let body = body.replace(
+ &format!("{rustdoc_function_name}() -> Result<(), impl core::fmt::Debug> {{"),
+ &format!("{rustdoc_function_name}() -> core::result::Result<(), impl core::fmt::Debug> {{"),
+ );
+
+ // For tests that get generated with `Result`, like above, `rustdoc` generates an `unwrap()` on
+ // the return value to check there were no returned errors. Instead, we use our assert macro
+ // since we want to just fail the test, not panic the kernel.
+ //
+ // We save the result in a variable so that the failed assertion message looks nicer.
+ let body = body.replace(
+ &format!("}} {rustdoc_function_name}().unwrap() }}"),
+ &format!("}} let test_return_value = {rustdoc_function_name}(); assert!(test_return_value.is_ok()); }}"),
+ );
+
+ // Figure out a smaller test name based on the generated function name.
+ let name = rustdoc_function_name.split_once("_rust_kernel_").unwrap().1;
+
+ let path = format!("rust/test/doctests/kernel/{name}");
+
+ write!(BufWriter::new(File::create(path).unwrap()), "{body}").unwrap();
+}
diff --git a/scripts/rustdoc_test_gen.rs b/scripts/rustdoc_test_gen.rs
new file mode 100644
index 000000000000..793885c32c0d
--- /dev/null
+++ b/scripts/rustdoc_test_gen.rs
@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generates KUnit tests from saved `rustdoc`-generated tests.
+//!
+//! KUnit passes a context (`struct kunit *`) to each test, which should be forwarded to the other
+//! KUnit functions and macros.
+//!
+//! However, we want to keep this as an implementation detail because:
+//!
+//! - Test code should not care about the implementation.
+//!
+//! - Documentation looks worse if it needs to carry extra details unrelated to the piece
+//! being described.
+//!
+//! - Test code should be able to define functions and call them, without having to carry
+//! the context.
+//!
+//! - Later on, we may want to be able to test non-kernel code (e.g. `core`, `alloc` or
+//! third-party crates) which likely use the standard library `assert*!` macros.
+//!
+//! For this reason, instead of the passed context, `kunit_get_current_test()` is used instead
+//! (i.e. `current->kunit_test`).
+//!
+//! Note that this means other threads/tasks potentially spawned by a given test, if failing, will
+//! report the failure in the kernel log but will not fail the actual test. Saving the pointer in
+//! e.g. a `static` per test does not fully solve the issue either, because currently KUnit does
+//! not support assertions (only expectations) from other tasks. Thus leave that feature for
+//! the future, which simplifies the code here too. We could also simply not allow `assert`s in
+//! other tasks, but that seems overly constraining, and we do want to support them, eventually.
+
+use std::io::{BufWriter, Read, Write};
+use std::{fs, fs::File};
+
+fn main() {
+ let mut paths = fs::read_dir("rust/test/doctests/kernel")
+ .unwrap()
+ .map(|entry| entry.unwrap().path())
+ .collect::<Vec<_>>();
+
+ // Sort paths for clarity.
+ paths.sort();
+
+ let mut rust_tests = String::new();
+ let mut c_test_declarations = String::new();
+ let mut c_test_cases = String::new();
+ let mut body = String::new();
+ let mut last_file = String::new();
+ let mut number = 0;
+ for path in paths {
+ // The `name` follows the `{file}_{line}_{number}` pattern (see description in
+ // `scripts/rustdoc_test_builder.rs`). Discard the `number`.
+ let name = path.file_name().unwrap().to_str().unwrap().to_string();
+
+ // Extract the `file` and the `line`, discarding the `number`.
+ let (file, line) = name.rsplit_once('_').unwrap().0.rsplit_once('_').unwrap();
+
+ // Generate an ID sequence ("test number") for each one in the file.
+ if file == last_file {
+ number += 1;
+ } else {
+ number = 0;
+ last_file = file.to_string();
+ }
+
+ // Generate a KUnit name (i.e. test name and C symbol) for this test.
+ //
+ // We avoid the line number, like `rustdoc` does, to make things slightly more stable for
+ // bisection purposes. However, to aid developers in mapping back what test failed, we will
+ // print a diagnostics line in the KTAP report.
+ let kunit_name = format!("rust_doctest_kernel_{file}_{number}");
+
+ // Read the test's text contents to dump it below.
+ body.clear();
+ File::open(path).unwrap().read_to_string(&mut body).unwrap();
+
+ let line = line.parse::<core::ffi::c_int>().unwrap();
+
+ use std::fmt::Write;
+ write!(
+ rust_tests,
+ r#"/// Generated `{name}` KUnit test case from a Rust documentation test.
+#[no_mangle]
+pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
+ /// Overrides the usual [`assert!`] macro with one that calls KUnit instead.
+ #[allow(unused)]
+ macro_rules! assert {{
+ ($cond:expr $(,)?) => {{{{
+ kernel::kunit_assert!("{kunit_name}", $cond);
+ }}}}
+ }}
+
+ /// Overrides the usual [`assert_eq!`] macro with one that calls KUnit instead.
+ #[allow(unused)]
+ macro_rules! assert_eq {{
+ ($left:expr, $right:expr $(,)?) => {{{{
+ kernel::kunit_assert_eq!("{kunit_name}", $left, $right);
+ }}}}
+ }}
+
+ // Many tests need the prelude, so provide it by default.
+ #[allow(unused)]
+ use kernel::prelude::*;
+
+ // Display line number so that developers can map the test easily to the source code.
+ kernel::kunit::info(format_args!(" # Doctest from line {line}\n"));
+
+ {{
+ {body}
+ main();
+ }}
+}}
+
+"#
+ )
+ .unwrap();
+
+ write!(c_test_declarations, "void {kunit_name}(struct kunit *);\n").unwrap();
+ write!(c_test_cases, " KUNIT_CASE({kunit_name}),\n").unwrap();
+ }
+
+ let rust_tests = rust_tests.trim();
+ let c_test_declarations = c_test_declarations.trim();
+ let c_test_cases = c_test_cases.trim();
+
+ write!(
+ BufWriter::new(File::create("rust/doctests_kernel_generated.rs").unwrap()),
+ r#"//! `kernel` crate documentation tests.
+
+const __LOG_PREFIX: &[u8] = b"rust_doctests_kernel\0";
+
+{rust_tests}
+"#
+ )
+ .unwrap();
+
+ write!(
+ BufWriter::new(File::create("rust/doctests_kernel_generated_kunit.c").unwrap()),
+ r#"/*
+ * `kernel` crate documentation tests.
+ */
+
+#include <kunit/test.h>
+
+{c_test_declarations}
+
+static struct kunit_case test_cases[] = {{
+ {c_test_cases}
+ {{ }}
+}};
+
+static struct kunit_suite test_suite = {{
+ .name = "rust_doctests_kernel",
+ .test_cases = test_cases,
+}};
+
+kunit_test_suite(test_suite);
+
+MODULE_LICENSE("GPL");
+"#
+ )
+ .unwrap();
+}
--
2.41.0
Miguel Ojeda <[email protected]> writes:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
Reviewed-by: Alice Ryhl <[email protected]>
Miguel Ojeda <[email protected]> writes:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
Reviewed-by: Alice Ryhl <[email protected]>
Miguel Ojeda <[email protected]> writes:
> 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
> # Doctest from line 13
> ok 1 rust_doctest_kernel_build_assert_rs_0
> # Doctest from line 56
> ok 2 rust_doctest_kernel_build_assert_rs_1
> # Doctest from line 122
> ok 3 rust_doctest_kernel_init_rs_0
> ...
> # Doctest from line 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. In the future, we may be able to use a proper KUnit
> facility to append this sort of information instead.
>
> 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.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
(One nit later below.)
Reviewed-by: Alice Ryhl <[email protected]>
> +fn main() {
> + let mut stdin = std::io::stdin().lock();
> + let mut body = String::new();
> + stdin.read_to_string(&mut body).unwrap();
> +
> + // Find the generated function name looking for the inner function inside `main()`.
> + //
> + // The line we are looking for looks like one of the following:
> + //
> + // ```
> + // fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_28_0() {
> + // fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_37_0() -> Result<(), impl core::fmt::Debug> {
> + // ```
> + //
> + // It should be unlikely that doctest code matches such lines (when code is formatted properly).
> + let rustdoc_function_name = body
> + .lines()
> + .find_map(|line| {
> + Some(
> + line.split_once("fn main() {")?
> + .1
> + .split_once("fn ")?
> + .1
> + .split_once("()")?
> + .0,
> + )
> + .filter(|x| x.chars().all(|c| c.is_alphanumeric() || c == '_'))
> + })
> + .expect("No test function found in `rustdoc`'s output.");
> +
> + // Qualify `Result` to avoid the collision with our own `Result` coming from the prelude.
> + let body = body.replace(
> + &format!("{rustdoc_function_name}() -> Result<(), impl core::fmt::Debug> {{"),
> + &format!("{rustdoc_function_name}() -> core::result::Result<(), impl core::fmt::Debug> {{"),
> + );
> +
> + // For tests that get generated with `Result`, like above, `rustdoc` generates an `unwrap()` on
> + // the return value to check there were no returned errors. Instead, we use our assert macro
> + // since we want to just fail the test, not panic the kernel.
> + //
> + // We save the result in a variable so that the failed assertion message looks nicer.
> + let body = body.replace(
> + &format!("}} {rustdoc_function_name}().unwrap() }}"),
> + &format!("}} let test_return_value = {rustdoc_function_name}(); assert!(test_return_value.is_ok()); }}"),
> + );
> +
> + // Figure out a smaller test name based on the generated function name.
> + let name = rustdoc_function_name.split_once("_rust_kernel_").unwrap().1;
> +
> + let path = format!("rust/test/doctests/kernel/{name}");
> +
> + write!(BufWriter::new(File::create(path).unwrap()), "{body}").unwrap();
This could just be
std::fs::write(path, body.as_bytes());
Alice
Miguel Ojeda <[email protected]> writes:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
Reviewed-by: Alice Ryhl <[email protected]>
On Wed, Jun 14, 2023 at 10:38 PM Alice Ryhl <[email protected]> wrote:
>
> This could just be
>
> std::fs::write(path, body.as_bytes());
+1, simpler, less `use`s needed and less size:
320429 12736 368 333533 516dd
scripts/rustdoc_test_builder
314701 12440 368 327509 4ff55
scripts/rustdoc_test_builder
Thanks for the review!
Cheers,
Miguel
diff --git a/scripts/rustdoc_test_builder.rs b/scripts/rustdoc_test_builder.rs
index e3b7138fb4f9..e5894652f12c 100644
--- a/scripts/rustdoc_test_builder.rs
+++ b/scripts/rustdoc_test_builder.rs
@@ -15,8 +15,7 @@
//! from that. For the moment, we generate ourselves a new name,
`{file}_{number}` instead, in
//! the `gen` script (done there since we need to be aware of all the
tests in a given file).
-use std::fs::File;
-use std::io::{BufWriter, Read, Write};
+use std::io::Read;
fn main() {
let mut stdin = std::io::stdin().lock();
@@ -69,5 +68,5 @@ fn main() {
let path = format!("rust/test/doctests/kernel/{name}");
- write!(BufWriter::new(File::create(path).unwrap()), "{body}").unwrap();
+ std::fs::write(path, body.as_bytes()).unwrap();
}
On Wed, Jun 14, 2023 at 8:09 PM Miguel Ojeda <[email protected]> wrote:
>
> +/// Prints a KUnit error.
Nit: this should be "info" instead.
By the way, we may want to have "raw" `pr_*!` macros without the
module prefix for cases like this in the future, in `print.rs`. But,
for the moment, I added these two ad-hoc ones here.
Cheers,
Miguel
> 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
> # Doctest from line 13
> ok 1 rust_doctest_kernel_build_assert_rs_0
> # Doctest from line 56
> ok 2 rust_doctest_kernel_build_assert_rs_1
> # Doctest from line 122
> ok 3 rust_doctest_kernel_init_rs_0
> ...
> # Doctest from line 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. In the future, we may be able to use a proper KUnit
> facility to append this sort of information instead.
>
> 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.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
Tested-by: Matt Gilbride <[email protected]>
On Wed, Jun 14, 2023 at 08:08:24PM +0200, Miguel Ojeda wrote:
> This is the initial KUnit integration for running Rust documentation
> tests within the kernel.
>
> Thank you to the KUnit team for all the input and feedback on this
> over the months, as well as the Intel LKP 0-Day team!
>
> This may be merged through either the KUnit or the Rust trees. If
> the KUnit team wants to merge it, then that would be great.
>
> Please see the message in the main commit for the details.
>
Great work! I've played this for a while, and it's really useful ;-)
One thing though, maybe we can provide more clues for users to locate
the corresponding Doctests? For example, I did the following to trigger
an assertion:
diff --git a/rust/kernel/sync/lock/spinlock.rs b/rust/kernel/sync/lock/spinlock.rs
index 91eb2c9e9123..9ead152e2c7e 100644
--- a/rust/kernel/sync/lock/spinlock.rs
+++ b/rust/kernel/sync/lock/spinlock.rs
@@ -58,7 +58,7 @@ macro_rules! new_spinlock {
///
/// // Allocate a boxed `Example`.
/// let e = Box::pin_init(Example::new())?;
-/// assert_eq!(e.c, 10);
+/// assert_eq!(e.c, 11);
/// assert_eq!(e.d.lock().a, 20);
/// assert_eq!(e.d.lock().b, 30);
/// # Ok::<(), Error>(())
Originally I got:
[..] # Doctest from line 35
[..] # rust_doctest_kernel_sync_lock_spinlock_rs_0: ASSERTION FAILED at rust/doctests_kernel_generated.rs:2437
[..] Expected e.c == 11 to be true, but is false
[..] [FAILED] rust_doctest_kernel_sync_lock_spinlock_rs_0
The assertion warning only says line 35 but which file? Yes, the
".._sync_lock_spinlock_rs" name does provide the lead, however since we
generate the test code, so we actually know the line # for each real
test body, so I come up a way to give us the following:
[..] # rust_doctest_kernel_sync_lock_spinlock_rs_0: ASSERTION FAILED at rust/kernel/sync/lock/spinlock.rs:61
[..] Expected e.c == 11 to be true, but is false
[..] [FAILED] rust_doctest_kernel_sync_lock_spinlock_rs_0
Thoughts?
Regards,
Boqun
----------------->8
diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs
index 3c94efcd7f76..807fe3633567 100644
--- a/rust/kernel/kunit.rs
+++ b/rust/kernel/kunit.rs
@@ -49,15 +49,15 @@ pub fn info(args: fmt::Arguments<'_>) {
#[doc(hidden)]
#[macro_export]
macro_rules! kunit_assert {
- ($name:literal, $condition:expr $(,)?) => {
+ ($name:literal, $diff:expr, $file:expr, $condition:expr $(,)?) => {
'out: {
// Do nothing if the condition is `true`.
if $condition {
break 'out;
}
- static LINE: i32 = core::line!() as i32;
- static FILE: &'static $crate::str::CStr = $crate::c_str!(core::file!());
+ static LINE: i32 = core::line!() as i32 - $diff;
+ static FILE: &'static $crate::str::CStr = $crate::c_str!($file);
static CONDITION: &'static $crate::str::CStr = $crate::c_str!(stringify!($condition));
// SAFETY: FFI call without safety requirements.
@@ -148,9 +148,9 @@ unsafe impl Sync for UnaryAssert {}
#[doc(hidden)]
#[macro_export]
macro_rules! kunit_assert_eq {
- ($name:literal, $left:expr, $right:expr $(,)?) => {{
+ ($name:literal, $diff:expr, $file:expr, $left:expr, $right:expr $(,)?) => {{
// For the moment, we just forward to the expression assert because, for binary asserts,
// KUnit supports only a few types (e.g. integers).
- $crate::kunit_assert!($name, $left == $right);
+ $crate::kunit_assert!($name, $diff, $file, $left == $right);
}};
}
diff --git a/scripts/rustdoc_test_gen.rs b/scripts/rustdoc_test_gen.rs
index 793885c32c0d..4786a2ef0dc6 100644
--- a/scripts/rustdoc_test_gen.rs
+++ b/scripts/rustdoc_test_gen.rs
@@ -75,6 +75,11 @@ fn main() {
let line = line.parse::<core::ffi::c_int>().unwrap();
+ let src_file = format!("rust/kernel/{}", file.replace("_rs", ".rs").replace("_", "/"));
+
+ // Calculate how many lines before `main` function (including the `main` function line).
+ let body_offset = body.lines().take_while(|l| !l.contains("fn main() {")).count() + 1;
+
use std::fmt::Write;
write!(
rust_tests,
@@ -85,7 +90,7 @@ pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
#[allow(unused)]
macro_rules! assert {{
($cond:expr $(,)?) => {{{{
- kernel::kunit_assert!("{kunit_name}", $cond);
+ kernel::kunit_assert!("{kunit_name}", anchor - {line}, "{src_file}", $cond);
}}}}
}}
@@ -93,7 +98,7 @@ macro_rules! assert {{
#[allow(unused)]
macro_rules! assert_eq {{
($left:expr, $right:expr $(,)?) => {{{{
- kernel::kunit_assert_eq!("{kunit_name}", $left, $right);
+ kernel::kunit_assert_eq!("{kunit_name}", anchor - {line}, "{src_file}", $left, $right);
}}}}
}}
@@ -101,9 +106,8 @@ macro_rules! assert_eq {{
#[allow(unused)]
use kernel::prelude::*;
- // Display line number so that developers can map the test easily to the source code.
- kernel::kunit::info(format_args!(" # Doctest from line {line}\n"));
-
+ // The anchor where the test code body starts.
+ static anchor: i32 = core::line!() as i32 + {body_offset} + 1;
{{
{body}
main();
On 6/14/23 15:08, Miguel Ojeda wrote:
> 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
> # Doctest from line 13
> ok 1 rust_doctest_kernel_build_assert_rs_0
> # Doctest from line 56
> ok 2 rust_doctest_kernel_build_assert_rs_1
> # Doctest from line 122
> ok 3 rust_doctest_kernel_init_rs_0
> ...
> # Doctest from line 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. In the future, we may be able to use a proper KUnit
> facility to append this sort of information instead.
>
> 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.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> [...]
> diff --git a/scripts/rustdoc_test_builder.rs b/scripts/rustdoc_test_builder.rs
> new file mode 100644
> index 000000000000..e3b7138fb4f9
> --- /dev/null
> +++ b/scripts/rustdoc_test_builder.rs
> @@ -0,0 +1,73 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> [...]
> +
> +fn main() {
> [...]
> +
> + write!(BufWriter::new(File::create(path).unwrap()), "{body}").unwrap();
I can't remember that if this panic it will mention the path on it.
Though if it does, then use something more explicit than
`.unwrap()`.
> +}
> diff --git a/scripts/rustdoc_test_gen.rs b/scripts/rustdoc_test_gen.rs
> new file mode 100644
> index 000000000000..793885c32c0d
> --- /dev/null
> +++ b/scripts/rustdoc_test_gen.rs
> @@ -0,0 +1,162 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> [...]
> +
> +use std::io::{BufWriter, Read, Write};
> +use std::{fs, fs::File};
> +
> +fn main() {
> + let mut paths = fs::read_dir("rust/test/doctests/kernel")
> + .unwrap()
> + .map(|entry| entry.unwrap().path())
> + .collect::<Vec<_>>();
> +
> + // Sort paths for clarity.
> + paths.sort();
> +
> + let mut rust_tests = String::new();
> + let mut c_test_declarations = String::new();
> + let mut c_test_cases = String::new();
> + let mut body = String::new();
> + let mut last_file = String::new();
> + let mut number = 0;
> + for path in paths {
> + // The `name` follows the `{file}_{line}_{number}` pattern (see description in
> + // `scripts/rustdoc_test_builder.rs`). Discard the `number`.
> + let name = path.file_name().unwrap().to_str().unwrap().to_string();
> +
> + // Extract the `file` and the `line`, discarding the `number`.
> + let (file, line) = name.rsplit_once('_').unwrap().0.rsplit_once('_').unwrap();
Please do not use unwrap here, one can easily create a path that
it's not compliant under `rust/test/doctests/kernel` and get no
clue about where this script has failed. Use `.expect()` or
something else instead.
> +
> [...]
> +
> + write!(
> + BufWriter::new(File::create("rust/doctests_kernel_generated.rs").unwrap()),
> + r#"//! `kernel` crate documentation tests.
> +
> +const __LOG_PREFIX: &[u8] = b"rust_doctests_kernel\0";
> +
> +{rust_tests}
> +"#
> + )
> + .unwrap();
> +
> + write!(
> + BufWriter::new(File::create("rust/doctests_kernel_generated_kunit.c").unwrap()),
> + r#"/*
> + * `kernel` crate documentation tests.
> + */
> +
> +#include <kunit/test.h>
> +
> +{c_test_declarations}
> +
> +static struct kunit_case test_cases[] = {{
> + {c_test_cases}
> + {{ }}
> +}};
> +
> +static struct kunit_suite test_suite = {{
> + .name = "rust_doctests_kernel",
> + .test_cases = test_cases,
> +}};
> +
> +kunit_test_suite(test_suite);
> +
> +MODULE_LICENSE("GPL");
> +"#
> + )
> + .unwrap();
Same from `scripts/rustdoc_test_builder.rs` applies here.
> +}
On 6/14/23 15:08, Miguel Ojeda wrote:
> The KUnit maintainers would like to maintain these files on their
> side too (thanks!), so add them to their entry.
>
> With this in place, `scripts/get_maintainer.pl` prints both sets
> of maintainers/reviewers (i.e. KUnit and Rust) for those files,
> which is the behavior we are looking for.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> [...]
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
On 6/14/23 15:08, Miguel Ojeda wrote:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> [...]
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
On 6/14/23 15:08, Miguel Ojeda wrote:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> [...]
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
On 6/14/23 15:08, Miguel Ojeda wrote:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> [...]
> //! # pub unsafe fn destroy_foo(_ptr: *mut foo) {}
> //! # pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 }
> //! # }
> +//! # trait FromErrno {
> +//! # fn from_errno(errno: core::ffi::c_int) -> Error {
> +//! # // Dummy error that can be constructed outside the `kernel` crate.
> +//! # Error::from(core::fmt::Error)
> +//! # }
> +//! # }
> +//! # impl FromErrno for Error {}
> //! /// # Invariants
> //! ///
> //! /// `foo` is always initialized
> [...]
Little question, what's the purpose of `FromErrno` here?
On Thu, Jun 15, 2023 at 3:44 AM Boqun Feng <[email protected]> wrote:
>
> Great work! I've played this for a while, and it's really useful ;-)
Thanks!
> The assertion warning only says line 35 but which file? Yes, the
> ".._sync_lock_spinlock_rs" name does provide the lead, however since we
> generate the test code, so we actually know the line # for each real
> test body, so I come up a way to give us the following:
>
> [..] # rust_doctest_kernel_sync_lock_spinlock_rs_0: ASSERTION FAILED at rust/kernel/sync/lock/spinlock.rs:61
> [..] Expected e.c == 11 to be true, but is false
> [..] [FAILED] rust_doctest_kernel_sync_lock_spinlock_rs_0
>
> Thoughts?
Sounds good to me. However, David/Philip, is this OK or do you really
need/use the actual/compiled source file there? If you don't need it,
does it need to exist / be a real file at least? If the latter answer
is a "yes", which I guess it may be likely, then:
> + let src_file = format!("rust/kernel/{}", file.replace("_rs", ".rs").replace("_", "/"));
This would not work for files with a `_` in their name, like
`locked_by.rs`. I guess we could still find the real filename based on
that information walking the dir, which is another hack I recall
considering at some point.
Otherwise, if "fake" filenames in the line above are OK for
David/Philip (I suspect they may want to open them for reporting?),
then I guess the `file` one may be good enough and eventually we
should get `rustdoc` to give us the proper metadata anyway.
Cheers,
Miguel
On Thu, Jun 15, 2023 at 5:52 AM Martin Rodriguez Reboredo
<[email protected]> wrote:
>
> I can't remember that if this panic it will mention the path on it.
> Though if it does, then use something more explicit than
> `.unwrap()`.
It doesn't print it, and I am happy to make things more explicit, but
in which case(s) do you see it failing?
> Please do not use unwrap here, one can easily create a path that
> it's not compliant under `rust/test/doctests/kernel` and get no
> clue about where this script has failed. Use `.expect()` or
> something else instead.
The folder is removed every time, so that should not happen I think.
Yes, you can still hack things and call the script manually, but I
wouldn't call that "easily".
Nevertheless, I am happy to change it if we think there is a risk,
e.g. `rustdoc` changing the pattern (though we pin the version so
far).
Thanks for taking a look Martin!
Cheers,
Miguel
On Thu, Jun 15, 2023 at 5:52 AM Martin Rodriguez Reboredo
<[email protected]> wrote:
>
> Little question, what's the purpose of `FromErrno` here?
It was because `Error::from_errno` is `pub(crate)` in the `kernel`
crate. I should have added a comment -- my bad! :)
If we decided to make it `pub` eventually, then this `FromErrno` hack
can be removed.
Cheers,
Miguel
On 6/15/23 06:31, Miguel Ojeda wrote:
> On Thu, Jun 15, 2023 at 5:52 AM Martin Rodriguez Reboredo
> <[email protected]> wrote:
>>
>> Little question, what's the purpose of `FromErrno` here?
>
> It was because `Error::from_errno` is `pub(crate)` in the `kernel`
> crate. I should have added a comment -- my bad! :)
>
> If we decided to make it `pub` eventually, then this `FromErrno` hack
> can be removed.
>
> Cheers,
> Miguel
I think that `FromErrno` should be made public the moment when more
doctests rely upon it, until then.
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
On 6/15/23 06:23, Miguel Ojeda wrote:
> On Thu, Jun 15, 2023 at 5:52 AM Martin Rodriguez Reboredo
> <[email protected]> wrote:
>>
>> I can't remember that if this panic it will mention the path on it.
>> Though if it does, then use something more explicit than
>> `.unwrap()`.
>
> It doesn't print it, and I am happy to make things more explicit, but
> in which case(s) do you see it failing?
>
>> Please do not use unwrap here, one can easily create a path that
>> it's not compliant under `rust/test/doctests/kernel` and get no
>> clue about where this script has failed. Use `.expect()` or
>> something else instead.
>
> The folder is removed every time, so that should not happen I think.
> Yes, you can still hack things and call the script manually, but I
> wouldn't call that "easily".
Ah, you are right, I've forgot that the folder was deleted and
remade, and because of that an error is more likely to occur at that
stage and not while `scripts/rustdoc_test_{builder,gen}.rs` is
running. Thus.
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
>
> Nevertheless, I am happy to change it if we think there is a risk,
> e.g. `rustdoc` changing the pattern (though we pin the version so
> far).
>
> Thanks for taking a look Martin!
>
> Cheers,
> Miguel
> The KUnit maintainers would like to maintain these files on their
> side too (thanks!), so add them to their entry.
>
> With this in place, `scripts/get_maintainer.pl` prints both sets
> of maintainers/reviewers (i.e. KUnit and Rust) for those files,
> which is the behavior we are looking for.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
Reviewed-by: Vincenzo Palazzo <[email protected]>
> 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
> # Doctest from line 13
> ok 1 rust_doctest_kernel_build_assert_rs_0
> # Doctest from line 56
> ok 2 rust_doctest_kernel_build_assert_rs_1
> # Doctest from line 122
> ok 3 rust_doctest_kernel_init_rs_0
> ...
> # Doctest from line 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. In the future, we may be able to use a proper KUnit
> facility to append this sort of information instead.
>
> 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.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
Reviewed-by: Vincenzo Palazzo <[email protected]>
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
Reviewed-by: Vincenzo Palazzo <[email protected]>
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
Reviewed-by: Vincenzo Palazzo <[email protected]>
On Thu, 15 Jun 2023 at 16:20, Miguel Ojeda
<[email protected]> wrote:
>
> On Thu, Jun 15, 2023 at 3:44 AM Boqun Feng <[email protected]> wrote:
> >
> > Great work! I've played this for a while, and it's really useful ;-)
>
> Thanks!
>
> > The assertion warning only says line 35 but which file? Yes, the
> > ".._sync_lock_spinlock_rs" name does provide the lead, however since we
> > generate the test code, so we actually know the line # for each real
> > test body, so I come up a way to give us the following:
> >
> > [..] # rust_doctest_kernel_sync_lock_spinlock_rs_0: ASSERTION FAILED at rust/kernel/sync/lock/spinlock.rs:61
> > [..] Expected e.c == 11 to be true, but is false
> > [..] [FAILED] rust_doctest_kernel_sync_lock_spinlock_rs_0
> >
> > Thoughts?
I like it.
A part of me would like to keep the
kernel::kunit::info(format_args!(" # Doctest from line {line}\n"));
If only so we can preserve the line information when the tests
actually pass. This is something that'd probably ultimately fit as a
"test attribute":
https://lore.kernel.org/linux-kselftest/[email protected]/
For C tests we're not bothering outputting line numbers now (though
again, are considering if we can do it with an attribute), but those
tests have much more searchable names, so I think it still makes sense
for the Rust ones.
How about printing something like:
# source_line: {}
kunit.py will hide this when the test passes unless the user
explicitly passes --raw_output.
>
> Sounds good to me. However, David/Philip, is this OK or do you really
> need/use the actual/compiled source file there? If you don't need it,
> does it need to exist / be a real file at least? If the latter answer
> is a "yes", which I guess it may be likely, then:
I don't think there's anything automated using the file:line in
assertion messages, it's just for human consumption.
This may change in the future (and there are probably some text
editors around which will turn a path like that into, e.g., a
clickable link now), but we're not currently doing anything which
would actually open the file.
>
> > + let src_file = format!("rust/kernel/{}", file.replace("_rs", ".rs").replace("_", "/"));
>
> This would not work for files with a `_` in their name, like
> `locked_by.rs`. I guess we could still find the real filename based on
> that information walking the dir, which is another hack I recall
> considering at some point.
>
> Otherwise, if "fake" filenames in the line above are OK for
> David/Philip (I suspect they may want to open them for reporting?),
> then I guess the `file` one may be good enough and eventually we
> should get `rustdoc` to give us the proper metadata anyway.
Personally, I'd think a "fake filename" is okay (especially if it's
temporary until we can get the right one), though I'd prefer there to
be some indication that it's "fake": maybe leaving the _ separator in,
or wrapping it in brackets, or something? Unless the whole
walk-the-filesystem technique ends up being worth doing, so we don't
have a significant chance of the filename being dud.
-- David
On Thu, 15 Jun 2023 at 02:09, Miguel Ojeda <[email protected]> wrote:
>
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
Reviewed-by: David Gow <[email protected]>
Cheers,
-- David
On Thu, 15 Jun 2023 at 02:09, Miguel Ojeda <[email protected]> wrote:
>
> The KUnit maintainers would like to maintain these files on their
> side too (thanks!), so add them to their entry.
>
> With this in place, `scripts/get_maintainer.pl` prints both sets
> of maintainers/reviewers (i.e. KUnit and Rust) for those files,
> which is the behavior we are looking for.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
Reviewed-by: David Gow <[email protected]>
We're happy to maintain this as part of the KUnit tree, though may
shout out for some help reviewing anything beyond our beginner-level
Rust knowledge.
Cheers,
-- David
> MAINTAINERS | 2 ++
> 1 file changed, 2 insertions(+)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 250518fc70ff..f4c9ce1b685f 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11323,6 +11323,8 @@ W: https://google.github.io/kunit-docs/third_party/kernel/docs/
> F: Documentation/dev-tools/kunit/
> F: include/kunit/
> F: lib/kunit/
> +F: rust/kernel/kunit.rs
> +F: scripts/rustdoc_test_*
> F: tools/testing/kunit/
>
> KERNEL USERMODE HELPER
> --
> 2.41.0
>
> --
> You received this message because you are subscribed to the Google Groups "KUnit Development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
> To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/20230614180837.630180-7-ojeda%40kernel.org.
On Thu, 15 Jun 2023 at 02:09, Miguel Ojeda <[email protected]> wrote:
>
> This is the initial KUnit integration for running Rust documentation
> tests within the kernel.
>
> Thank you to the KUnit team for all the input and feedback on this
> over the months, as well as the Intel LKP 0-Day team!
>
> This may be merged through either the KUnit or the Rust trees. If
> the KUnit team wants to merge it, then that would be great.
>
> Please see the message in the main commit for the details.
>
>
Thanks very much for putting this together! I've been looking forward
to it, and it works well here.
I've been running it on linux-next to get both the pending KUnit and
Rust changes, and it works well apart from needing to fix a couple of
conflicts from
https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/commit/?h=kunit&id=260755184cbdb267a046e7ffd397c1d2ba09bb5e
In particular, the tests run with:
./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_RUST=y
--make_options LLVM=1 'rust_doctests_kernel'
And also under QEMU / x86_64 with:
./tools/testing/kunit/kunit.py run --arch x86_64 --kconfig_add
CONFIG_RUST=y --make_options LLVM=1 'rust_doctests_kernel'
(And I'm looking forward to trying out the other architecture support
patches with it, too)
The doctests also run nicely as part of the default test suite when
CONFIG_RUST=y. At some point, we might want to add a Rust-specific
.kunitconfig to make it easier to just run Rust-related test suites,
but it's not a big deal for just these.
I assume we'll take this in via the kselftest/kunit tree for 6.6, but
if you'd rather take them via the Rust tree, that's fine too.
Cheers,
-- David
> Miguel Ojeda (6):
> rust: init: make doctests compilable/testable
> rust: str: make doctests compilable/testable
> rust: sync: make doctests compilable/testable
> rust: types: make doctests compilable/testable
> rust: support running Rust documentation tests as KUnit ones
> MAINTAINERS: add Rust KUnit files to the KUnit entry
>
> MAINTAINERS | 2 +
> lib/Kconfig.debug | 13 +++
> rust/.gitignore | 2 +
> rust/Makefile | 29 ++++++
> rust/bindings/bindings_helper.h | 1 +
> rust/helpers.c | 7 ++
> rust/kernel/init.rs | 25 +++--
> rust/kernel/kunit.rs | 156 ++++++++++++++++++++++++++++
> rust/kernel/lib.rs | 2 +
> rust/kernel/str.rs | 4 +-
> rust/kernel/sync/arc.rs | 9 +-
> rust/kernel/sync/lock/mutex.rs | 1 +
> rust/kernel/sync/lock/spinlock.rs | 1 +
> rust/kernel/types.rs | 6 +-
> scripts/.gitignore | 2 +
> scripts/Makefile | 4 +
> scripts/rustdoc_test_builder.rs | 73 ++++++++++++++
> scripts/rustdoc_test_gen.rs | 162 ++++++++++++++++++++++++++++++
> 18 files changed, 484 insertions(+), 15 deletions(-)
> create mode 100644 rust/kernel/kunit.rs
> create mode 100644 scripts/rustdoc_test_builder.rs
> create mode 100644 scripts/rustdoc_test_gen.rs
>
>
> base-commit: d2e3115d717197cb2bc020dd1f06b06538474ac3
> --
> 2.41.0
>
On Thu, 15 Jun 2023 at 02:09, Miguel Ojeda <[email protected]> wrote:
>
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
Looks good, thanks!
Reviewed-by: David Gow <[email protected]>
Cheers,
-- David
On Thu, 15 Jun 2023 at 02:09, Miguel Ojeda <[email protected]> wrote:
>
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
Reviewed-by: David Gow <[email protected]>
Cheers,
-- David
On Thu, 15 Jun 2023 at 02:09, Miguel Ojeda <[email protected]> wrote:
>
> 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
> # Doctest from line 13
> ok 1 rust_doctest_kernel_build_assert_rs_0
> # Doctest from line 56
> ok 2 rust_doctest_kernel_build_assert_rs_1
> # Doctest from line 122
> ok 3 rust_doctest_kernel_init_rs_0
> ...
> # Doctest from line 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.
This is very neat, and works very well here -- thanks!
I can reproduce your above results with:
./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_RUST=y
--make_options LLVM=1 'rust_doctests_kernel'
(And also with --arch x86_64 to run under Qemu, rather than UML)
>
> 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).
Yeah, it'd be great to have rustdoc generate a better name. I agree
that <file>_<counter> is the best balance of stability and
descriptivity in the meantime. It should only change if new tests are
added or reordered, not just with any change to the actual code.
The other idea we discussed of doing, e.g., hashes of the test source
would be more stable, but the ugliness of it probably isn't worth it.
> 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. In the future, we may be able to use a proper KUnit
> facility to append this sort of information instead.
Yeah, we're looking at a general "test attributes" feature, which
would provide a standard way of providing extra data about test cases,
which would be included in the output, and could even be filtered
upon.
There's a link to it below.
> 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.
While I have some reservations about this in general, I think it makes
sense for the doctests at least. It may be worth also supplying "more
direct" bindings for features which map less well to existing Rust
assertions and features, such as expectations, resources, mocks, etc.
However, I think we can add these (a) as we develop tests which would
benefit for them, and (b) once we expand the scope of KUnit testing
beyond just doctests.
The context becoming implicit is also a tradeoff (as mentioned a bit
below), but I think it's worth doing for those stated reasons. If it
proves really successful, we can look into changing the C API to
implicitly use the current task's test context as well, though we'll
accept the divergence for now.
> 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.
Yes: this is a restriction on the KUnit execution environment at the
moment. Tests are expected to be single-threaded, or at least to
manage any extra threads themselves. This means that:
- assertions don't work in non-main threads (though the KUnit
'expectation' feature does, which we can expose in Rust if it is
needed)
- it's the user's responsibility to make sure all threads exit when
the test's main thread ends.
These obviously aren't ideal (particularly compared to the level of
safety Rust usually provides), but we'll look at better ways of
handling tests which spawn threads in KUnit going forward.
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
This looks good to me. I've left a few comments below, but none of
them are deal breakers if you feel strongly about keeping things the
way they are.
Otherwise,
Reviewed-by: David Gow <[email protected]>
Thanks a bunch,
-- David
> lib/Kconfig.debug | 13 +++
> rust/.gitignore | 2 +
> rust/Makefile | 29 ++++++
> rust/bindings/bindings_helper.h | 1 +
> rust/helpers.c | 7 ++
> rust/kernel/kunit.rs | 156 ++++++++++++++++++++++++++++++
> rust/kernel/lib.rs | 2 +
> scripts/.gitignore | 2 +
> scripts/Makefile | 4 +
> scripts/rustdoc_test_builder.rs | 73 ++++++++++++++
> scripts/rustdoc_test_gen.rs | 162 ++++++++++++++++++++++++++++++++
> 11 files changed, 451 insertions(+)
> create mode 100644 rust/kernel/kunit.rs
> create mode 100644 scripts/rustdoc_test_builder.rs
> create mode 100644 scripts/rustdoc_test_gen.rs
>
> diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
> index ce51d4dc6803..49f5e9c42200 100644
> --- a/lib/Kconfig.debug
> +++ b/lib/Kconfig.debug
> @@ -2911,6 +2911,19 @@ config RUST_BUILD_ASSERT_ALLOW
>
> If unsure, say N.
>
> +config RUST_KERNEL_KUNIT_TEST
> + bool "KUnit test for the `kernel` crate" if !KUNIT_ALL_TESTS
I wonder whether it'd make sense to have the name / description here
call out doctests specifically. If we want to add Rust support for
more explicit KUnit tests, as in
https://github.com/Rust-for-Linux/linux/pull/950 then those might have
a better claim to the _KUNIT_TEST suffix.
I'd be happy if this became RUST_KERNEL_DOCTESTS or similar.
> + depends on RUST && KUNIT=y
> + default KUNIT_ALL_TESTS
> + help
> + This builds the documentation tests of the `kernel` crate
> + as KUnit tests.
> +
> + For more information on KUnit and unit tests in general,
> + please refer to the KUnit documentation in Documentation/dev-tools/kunit/.
> +
> + If unsure, say N.
> +
> endmenu # "Rust"
>
> endmenu # Kernel hacking
> diff --git a/rust/.gitignore b/rust/.gitignore
> index 21552992b401..d3829ffab80b 100644
> --- a/rust/.gitignore
> +++ b/rust/.gitignore
> @@ -2,6 +2,8 @@
>
> bindings_generated.rs
> bindings_helpers_generated.rs
> +doctests_kernel_generated.rs
> +doctests_kernel_generated_kunit.c
> uapi_generated.rs
> exports_*_generated.h
> doc/
> diff --git a/rust/Makefile b/rust/Makefile
> index 7c9d9f11aec5..e4e8b83752e2 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -27,6 +27,12 @@ endif
>
> obj-$(CONFIG_RUST) += exports.o
>
> +always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated.rs
> +always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated_kunit.c
> +
> +obj-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated.o
> +obj-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated_kunit.o
> +
> # Avoids running `$(RUSTC)` for the sysroot when it may not be available.
> ifdef CONFIG_RUST
>
> @@ -39,9 +45,11 @@ ifeq ($(quiet),silent_)
> cargo_quiet=-q
> rust_test_quiet=-q
> rustdoc_test_quiet=--test-args -q
> +rustdoc_test_kernel_quiet=>/dev/null
> else ifeq ($(quiet),quiet_)
> rust_test_quiet=-q
> rustdoc_test_quiet=--test-args -q
> +rustdoc_test_kernel_quiet=>/dev/null
> else
> cargo_quiet=--verbose
> endif
> @@ -157,6 +165,27 @@ quiet_cmd_rustdoc_test = RUSTDOC T $<
> -L$(objtree)/$(obj)/test --output $(objtree)/$(obj)/doc \
> --crate-name $(subst rusttest-,,$@) $<
>
> +quiet_cmd_rustdoc_test_kernel = RUSTDOC TK $<
> + cmd_rustdoc_test_kernel = \
> + rm -rf $(objtree)/$(obj)/test/doctests/kernel; \
> + mkdir -p $(objtree)/$(obj)/test/doctests/kernel; \
> + OBJTREE=$(abspath $(objtree)) \
> + $(RUSTDOC) --test $(rust_flags) \
> + @$(objtree)/include/generated/rustc_cfg \
> + -L$(objtree)/$(obj) --extern alloc --extern kernel \
> + --extern build_error --extern macros \
> + --extern bindings --extern uapi \
> + --no-run --crate-name kernel -Zunstable-options \
> + --test-builder $(objtree)/scripts/rustdoc_test_builder \
> + $< $(rustdoc_test_kernel_quiet); \
> + $(objtree)/scripts/rustdoc_test_gen
> +
> +%/doctests_kernel_generated.rs %/doctests_kernel_generated_kunit.c: \
> + $(src)/kernel/lib.rs $(obj)/kernel.o \
> + $(objtree)/scripts/rustdoc_test_builder \
> + $(objtree)/scripts/rustdoc_test_gen FORCE
> + $(call if_changed,rustdoc_test_kernel)
> +
> # We cannot use `-Zpanic-abort-tests` because some tests are dynamic,
> # so for the moment we skip `-Cpanic=abort`.
> quiet_cmd_rustc_test = RUSTC T $<
> diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
> index 3e601ce2548d..0f8d37c31ac2 100644
> --- a/rust/bindings/bindings_helper.h
> +++ b/rust/bindings/bindings_helper.h
> @@ -6,6 +6,7 @@
> * Sorted alphabetically.
> */
>
> +#include <kunit/test.h>
> #include <linux/errname.h>
> #include <linux/slab.h>
> #include <linux/refcount.h>
> diff --git a/rust/helpers.c b/rust/helpers.c
> index bb594da56137..49a5e1a4f0ae 100644
> --- a/rust/helpers.c
> +++ b/rust/helpers.c
> @@ -18,6 +18,7 @@
> * accidentally exposed.
> */
>
> +#include <kunit/test-bug.h>
> #include <linux/bug.h>
> #include <linux/build_bug.h>
> #include <linux/err.h>
> @@ -135,6 +136,12 @@ void rust_helper_put_task_struct(struct task_struct *t)
> }
> EXPORT_SYMBOL_GPL(rust_helper_put_task_struct);
>
> +struct kunit *rust_helper_kunit_get_current_test(void)
> +{
> + return kunit_get_current_test();
> +}
> +EXPORT_SYMBOL_GPL(rust_helper_kunit_get_current_test);
> +
> /*
> * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type
> * as the Rust `usize` type, so we can use it in contexts where Rust
> diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs
> new file mode 100644
> index 000000000000..3c94efcd7f76
> --- /dev/null
> +++ b/rust/kernel/kunit.rs
> @@ -0,0 +1,156 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! KUnit-based macros for Rust unit tests.
> +//!
> +//! C header: [`include/kunit/test.h`](../../../../../include/kunit/test.h)
> +//!
> +//! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>
> +
> +use core::{ffi::c_void, fmt};
> +
> +/// Prints a KUnit error.
> +///
> +/// Public but hidden since it should only be used from KUnit generated code.
> +#[doc(hidden)]
> +pub fn err(args: fmt::Arguments<'_>) {
> + // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we
> + // are passing.
> + #[cfg(CONFIG_PRINTK)]
> + unsafe {
> + bindings::_printk(
> + b"\x013%pA\0".as_ptr() as _,
> + &args as *const _ as *const c_void,
> + );
> + }
> +}
> +
> +/// Prints a KUnit error.
> +///
> +/// Public but hidden since it should only be used from KUnit generated code.
> +#[doc(hidden)]
> +pub fn info(args: fmt::Arguments<'_>) {
> + // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we
> + // are passing.
> + #[cfg(CONFIG_PRINTK)]
> + unsafe {
> + bindings::_printk(
> + b"\x016%pA\0".as_ptr() as _,
> + &args as *const _ as *const c_void,
> + );
> + }
> +}
> +
> +/// Asserts that a boolean expression is `true` at runtime.
> +///
> +/// Public but hidden since it should only be used from generated tests.
> +///
> +/// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit
> +/// facilities. See [`assert!`] for more details.
> +#[doc(hidden)]
> +#[macro_export]
> +macro_rules! kunit_assert {
> + ($name:literal, $condition:expr $(,)?) => {
> + 'out: {
> + // Do nothing if the condition is `true`.
> + if $condition {
> + break 'out;
> + }
> +
> + static LINE: i32 = core::line!() as i32;
> + static FILE: &'static $crate::str::CStr = $crate::c_str!(core::file!());
> + static CONDITION: &'static $crate::str::CStr = $crate::c_str!(stringify!($condition));
> +
> + // SAFETY: FFI call without safety requirements.
> + let kunit_test = unsafe { $crate::bindings::kunit_get_current_test() };
> + if kunit_test.is_null() {
> + // The assertion failed but this task is not running a KUnit test, so we cannot call
> + // KUnit, but at least print an error to the kernel log. This may happen if this
> + // macro is called from an spawned thread in a test (see
> + // `scripts/rustdoc_test_gen.rs`) or if some non-test code calls this macro by
> + // mistake (it is hidden to prevent that).
> + //
> + // This mimics KUnit's failed assertion format.
> + $crate::kunit::err(format_args!(
> + " # {}: ASSERTION FAILED at {FILE}:{LINE}\n",
> + $name
> + ));
> + $crate::kunit::err(format_args!(
> + " Expected {CONDITION} to be true, but is false\n"
> + ));
> + $crate::kunit::err(format_args!(
> + " Failure not reported to KUnit since this is a non-KUnit task\n"
> + ));
> + break 'out;
> + }
> +
> + #[repr(transparent)]
> + struct Location($crate::bindings::kunit_loc);
> +
> + #[repr(transparent)]
> + struct UnaryAssert($crate::bindings::kunit_unary_assert);
> +
> + // SAFETY: There is only a static instance and in that one the pointer field points to
> + // an immutable C string.
> + unsafe impl Sync for Location {}
> +
> + // SAFETY: There is only a static instance and in that one the pointer field points to
> + // an immutable C string.
> + unsafe impl Sync for UnaryAssert {}
> +
> + static LOCATION: Location = Location($crate::bindings::kunit_loc {
> + file: FILE.as_char_ptr(),
> + line: LINE,
> + });
> + static ASSERTION: UnaryAssert = UnaryAssert($crate::bindings::kunit_unary_assert {
> + assert: $crate::bindings::kunit_assert {},
> + condition: CONDITION.as_char_ptr(),
> + expected_true: true,
> + });
> +
> + // SAFETY:
> + // - FFI call.
> + // - The `kunit_test` pointer is valid because we got it from
> + // `kunit_get_current_test()` and it was not null. This means we are in a KUnit
> + // test, and that the pointer can be passed to KUnit functions and assertions.
> + // - The string pointers (`file` and `condition` above) point to null-terminated
> + // strings since they are `CStr`s.
> + // - The function pointer (`format`) points to the proper function.
> + // - The pointers passed will remain valid since they point to `static`s.
> + // - The format string is allowed to be null.
> + // - There are, however, problems with this: first of all, this will end up stopping
> + // the thread, without running destructors. While that is problematic in itself,
> + // it is considered UB to have what is effectively a forced foreign unwind
> + // with `extern "C"` ABI. One could observe the stack that is now gone from
> + // another thread. We should avoid pinning stack variables to prevent library UB,
> + // too. For the moment, given that test failures are reported immediately before the
> + // next test runs, that test failures should be fixed and that KUnit is explicitly
> + // documented as not suitable for production environments, we feel it is reasonable.
> + unsafe {
> + $crate::bindings::kunit_do_failed_assertion(
> + kunit_test,
> + core::ptr::addr_of!(LOCATION.0),
> + $crate::bindings::kunit_assert_type_KUNIT_ASSERTION,
> + core::ptr::addr_of!(ASSERTION.0.assert),
> + Some($crate::bindings::kunit_unary_assert_format),
> + core::ptr::null(),
> + );
This will conflict with:
https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/commit/?h=kunit&id=260755184cbdb267a046e7ffd397c1d2ba09bb5e
Basically, kunit_do_failed_assertion() has gained a couple of
underscores to become __kunit_do_failed_assertion(), and it no longer
aborts the test itself, requiring an extra call to __kunit_abort().
With those two changes, this works well here: I assume they'll be
picked up on a rebase if we want to push this via the kselftest/kunit
tree for 6.6.
> + }
> + }
> + };
> +}
> +
> +/// Asserts that two expressions are equal to each other (using [`PartialEq`]).
> +///
> +/// Public but hidden since it should only be used from generated tests.
> +///
> +/// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit
> +/// facilities. See [`assert!`] for more details.
> +#[doc(hidden)]
> +#[macro_export]
> +macro_rules! kunit_assert_eq {
> + ($name:literal, $left:expr, $right:expr $(,)?) => {{
> + // For the moment, we just forward to the expression assert because, for binary asserts,
> + // KUnit supports only a few types (e.g. integers).
> + $crate::kunit_assert!($name, $left == $right);
> + }};
> +}
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index 85b261209977..3642cadc34b1 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -34,6 +34,8 @@
> pub mod error;
> pub mod init;
> pub mod ioctl;
> +#[cfg(CONFIG_KUNIT)]
> +pub mod kunit;
> pub mod prelude;
> pub mod print;
> mod static_assert;
> diff --git a/scripts/.gitignore b/scripts/.gitignore
> index 6e9ce6720a05..3dbb8bb2457b 100644
> --- a/scripts/.gitignore
> +++ b/scripts/.gitignore
> @@ -5,6 +5,8 @@
> /kallsyms
> /module.lds
> /recordmcount
> +/rustdoc_test_builder
> +/rustdoc_test_gen
> /sign-file
> /sorttable
> /target.json
> diff --git a/scripts/Makefile b/scripts/Makefile
> index 32b6ba722728..d5a5382e753c 100644
> --- a/scripts/Makefile
> +++ b/scripts/Makefile
> @@ -9,6 +9,8 @@ hostprogs-always-$(CONFIG_BUILDTIME_TABLE_SORT) += sorttable
> hostprogs-always-$(CONFIG_ASN1) += asn1_compiler
> hostprogs-always-$(CONFIG_MODULE_SIG_FORMAT) += sign-file
> hostprogs-always-$(CONFIG_SYSTEM_EXTRA_CERTIFICATE) += insert-sys-cert
> +hostprogs-always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += rustdoc_test_builder
> +hostprogs-always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += rustdoc_test_gen
> always-$(CONFIG_RUST) += target.json
>
> filechk_rust_target = $< < include/config/auto.conf
> @@ -18,6 +20,8 @@ $(obj)/target.json: scripts/generate_rust_target include/config/auto.conf FORCE
>
> hostprogs += generate_rust_target
> generate_rust_target-rust := y
> +rustdoc_test_builder-rust := y
> +rustdoc_test_gen-rust := y
>
> HOSTCFLAGS_sorttable.o = -I$(srctree)/tools/include
> HOSTLDLIBS_sorttable = -lpthread
> diff --git a/scripts/rustdoc_test_builder.rs b/scripts/rustdoc_test_builder.rs
> new file mode 100644
> index 000000000000..e3b7138fb4f9
> --- /dev/null
> +++ b/scripts/rustdoc_test_builder.rs
> @@ -0,0 +1,73 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Test builder for `rustdoc`-generated tests.
> +//!
> +//! This script is a hack to extract the test from `rustdoc`'s output. Ideally, `rustdoc` would
> +//! have an option to generate this information instead, e.g. as JSON output.
> +//!
> +//! The `rustdoc`-generated test names look like `{file}_{line}_{number}`, e.g.
> +//! `...path_rust_kernel_sync_arc_rs_42_0`. `number` is the "test number", needed in cases like
> +//! a macro that expands into items with doctests is invoked several times within the same line.
> +//!
> +//! However, since these names are used for bisection in CI, the line number makes it not stable
> +//! at all. In the future, we would like `rustdoc` to give us the Rust item path associated with
> +//! the test, plus a "test number" (for cases with several examples per item) and generate a name
> +//! from that. For the moment, we generate ourselves a new name, `{file}_{number}` instead, in
> +//! the `gen` script (done there since we need to be aware of all the tests in a given file).
> +
> +use std::fs::File;
> +use std::io::{BufWriter, Read, Write};
> +
> +fn main() {
> + let mut stdin = std::io::stdin().lock();
> + let mut body = String::new();
> + stdin.read_to_string(&mut body).unwrap();
> +
> + // Find the generated function name looking for the inner function inside `main()`.
> + //
> + // The line we are looking for looks like one of the following:
> + //
> + // ```
> + // fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_28_0() {
> + // fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_37_0() -> Result<(), impl core::fmt::Debug> {
> + // ```
> + //
> + // It should be unlikely that doctest code matches such lines (when code is formatted properly).
> + let rustdoc_function_name = body
> + .lines()
> + .find_map(|line| {
> + Some(
> + line.split_once("fn main() {")?
> + .1
> + .split_once("fn ")?
> + .1
> + .split_once("()")?
> + .0,
> + )
> + .filter(|x| x.chars().all(|c| c.is_alphanumeric() || c == '_'))
> + })
> + .expect("No test function found in `rustdoc`'s output.");
> +
> + // Qualify `Result` to avoid the collision with our own `Result` coming from the prelude.
> + let body = body.replace(
> + &format!("{rustdoc_function_name}() -> Result<(), impl core::fmt::Debug> {{"),
> + &format!("{rustdoc_function_name}() -> core::result::Result<(), impl core::fmt::Debug> {{"),
> + );
> +
> + // For tests that get generated with `Result`, like above, `rustdoc` generates an `unwrap()` on
> + // the return value to check there were no returned errors. Instead, we use our assert macro
> + // since we want to just fail the test, not panic the kernel.
> + //
> + // We save the result in a variable so that the failed assertion message looks nicer.
> + let body = body.replace(
> + &format!("}} {rustdoc_function_name}().unwrap() }}"),
> + &format!("}} let test_return_value = {rustdoc_function_name}(); assert!(test_return_value.is_ok()); }}"),
> + );
> +
> + // Figure out a smaller test name based on the generated function name.
> + let name = rustdoc_function_name.split_once("_rust_kernel_").unwrap().1;
> +
> + let path = format!("rust/test/doctests/kernel/{name}");
> +
> + write!(BufWriter::new(File::create(path).unwrap()), "{body}").unwrap();
> +}
> diff --git a/scripts/rustdoc_test_gen.rs b/scripts/rustdoc_test_gen.rs
> new file mode 100644
> index 000000000000..793885c32c0d
> --- /dev/null
> +++ b/scripts/rustdoc_test_gen.rs
> @@ -0,0 +1,162 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Generates KUnit tests from saved `rustdoc`-generated tests.
> +//!
> +//! KUnit passes a context (`struct kunit *`) to each test, which should be forwarded to the other
> +//! KUnit functions and macros.
> +//!
> +//! However, we want to keep this as an implementation detail because:
> +//!
> +//! - Test code should not care about the implementation.
> +//!
> +//! - Documentation looks worse if it needs to carry extra details unrelated to the piece
> +//! being described.
> +//!
> +//! - Test code should be able to define functions and call them, without having to carry
> +//! the context.
> +//!
> +//! - Later on, we may want to be able to test non-kernel code (e.g. `core`, `alloc` or
> +//! third-party crates) which likely use the standard library `assert*!` macros.
> +//!
> +//! For this reason, instead of the passed context, `kunit_get_current_test()` is used instead
> +//! (i.e. `current->kunit_test`).
While I think there are some advantages to passing the `struct kunit
*` context around manually (in particular, I suspect a number of the
lifecycle issues we have with threads would actually be nicely
modelled by the Rust ownership/borrowing model on the context), I
agree that being more consistent with the way doctests work outside
the kernel is the better path here.
We may revisit this with future KUnit bindings, though, or we may
update the C version to use kunit_get_current_test() more.
(Particularly once we have a better solution for the threading issues
below.)
> +//!
> +//! Note that this means other threads/tasks potentially spawned by a given test, if failing, will
> +//! report the failure in the kernel log but will not fail the actual test. Saving the pointer in
> +//! e.g. a `static` per test does not fully solve the issue either, because currently KUnit does
> +//! not support assertions (only expectations) from other tasks. Thus leave that feature for
> +//! the future, which simplifies the code here too. We could also simply not allow `assert`s in
> +//! other tasks, but that seems overly constraining, and we do want to support them, eventually.
> +
> +use std::io::{BufWriter, Read, Write};
> +use std::{fs, fs::File};
> +
> +fn main() {
> + let mut paths = fs::read_dir("rust/test/doctests/kernel")
> + .unwrap()
> + .map(|entry| entry.unwrap().path())
> + .collect::<Vec<_>>();
> +
> + // Sort paths for clarity.
> + paths.sort();
> +
> + let mut rust_tests = String::new();
> + let mut c_test_declarations = String::new();
> + let mut c_test_cases = String::new();
> + let mut body = String::new();
> + let mut last_file = String::new();
> + let mut number = 0;
> + for path in paths {
> + // The `name` follows the `{file}_{line}_{number}` pattern (see description in
> + // `scripts/rustdoc_test_builder.rs`). Discard the `number`.
> + let name = path.file_name().unwrap().to_str().unwrap().to_string();
> +
> + // Extract the `file` and the `line`, discarding the `number`.
> + let (file, line) = name.rsplit_once('_').unwrap().0.rsplit_once('_').unwrap();
> +
> + // Generate an ID sequence ("test number") for each one in the file.
> + if file == last_file {
> + number += 1;
> + } else {
> + number = 0;
> + last_file = file.to_string();
> + }
> +
> + // Generate a KUnit name (i.e. test name and C symbol) for this test.
> + //
> + // We avoid the line number, like `rustdoc` does, to make things slightly more stable for
> + // bisection purposes. However, to aid developers in mapping back what test failed, we will
> + // print a diagnostics line in the KTAP report.
> + let kunit_name = format!("rust_doctest_kernel_{file}_{number}");
> +
> + // Read the test's text contents to dump it below.
> + body.clear();
> + File::open(path).unwrap().read_to_string(&mut body).unwrap();
> +
> + let line = line.parse::<core::ffi::c_int>().unwrap();
> +
> + use std::fmt::Write;
> + write!(
> + rust_tests,
> + r#"/// Generated `{name}` KUnit test case from a Rust documentation test.
> +#[no_mangle]
> +pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
> + /// Overrides the usual [`assert!`] macro with one that calls KUnit instead.
> + #[allow(unused)]
> + macro_rules! assert {{
> + ($cond:expr $(,)?) => {{{{
> + kernel::kunit_assert!("{kunit_name}", $cond);
> + }}}}
> + }}
> +
> + /// Overrides the usual [`assert_eq!`] macro with one that calls KUnit instead.
> + #[allow(unused)]
> + macro_rules! assert_eq {{
> + ($left:expr, $right:expr $(,)?) => {{{{
> + kernel::kunit_assert_eq!("{kunit_name}", $left, $right);
> + }}}}
> + }}
> +
> + // Many tests need the prelude, so provide it by default.
> + #[allow(unused)]
> + use kernel::prelude::*;
> +
> + // Display line number so that developers can map the test easily to the source code.
> + kernel::kunit::info(format_args!(" # Doctest from line {line}\n"));
Ideally, I think this should try to follow the (still in progress)
KTAP attribute format:
https://lore.kernel.org/lkml/[email protected]/T/
Ultimately, that should probably be implemented as a KUnit attribute,
but just printing something like "# line: {}" or "# <test_name>.line:
{}" ought to work until that's landed:
https://lore.kernel.org/linux-kselftest/[email protected]/
I think Boqun's suggestion from the cover letter to map assertion
file/lines is better still, but that obviously only triggers when an
assertion actually fails. And while kunit.py does hide diagnostic
lines when a test passes, something like this could still be useful
for people running KUnit manually, or using the --raw_output option.
> +
> + {{
> + {body}
> + main();
> + }}
> +}}
> +
> +"#
> + )
> + .unwrap();
> +
> + write!(c_test_declarations, "void {kunit_name}(struct kunit *);\n").unwrap();
> + write!(c_test_cases, " KUNIT_CASE({kunit_name}),\n").unwrap();
> + }
> +
> + let rust_tests = rust_tests.trim();
> + let c_test_declarations = c_test_declarations.trim();
> + let c_test_cases = c_test_cases.trim();
> +
> + write!(
> + BufWriter::new(File::create("rust/doctests_kernel_generated.rs").unwrap()),
> + r#"//! `kernel` crate documentation tests.
> +
> +const __LOG_PREFIX: &[u8] = b"rust_doctests_kernel\0";
> +
> +{rust_tests}
> +"#
> + )
> + .unwrap();
> +
> + write!(
> + BufWriter::new(File::create("rust/doctests_kernel_generated_kunit.c").unwrap()),
We may want to eventually do all of this in Rust, rather than
generating a C file, but that obviously should wait until more
complete KUnit bindings exist. (And, even then, it may still make
sense to piggy-back on the C macro implementations if they still make
sense.)
> + r#"/*
> + * `kernel` crate documentation tests.
> + */
> +
> +#include <kunit/test.h>
> +
> +{c_test_declarations}
> +
> +static struct kunit_case test_cases[] = {{
> + {c_test_cases}
> + {{ }}
> +}};
> +
> +static struct kunit_suite test_suite = {{
> + .name = "rust_doctests_kernel",
> + .test_cases = test_cases,
> +}};
> +
> +kunit_test_suite(test_suite);
> +
> +MODULE_LICENSE("GPL");
> +"#
> + )
> + .unwrap();
> +}
> --
> 2.41.0
>
------- Original Message -------
On Wednesday, June 14th, 2023 at 20:08, Miguel Ojeda <[email protected]> wrote:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> rust/kernel/sync/arc.rs | 9 +++++++--
> rust/kernel/sync/lock/mutex.rs | 1 +
> rust/kernel/sync/lock/spinlock.rs | 1 +
> 3 files changed, 9 insertions(+), 2 deletions(-)
>
> diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs
> index a89843cacaad..1ecb2efab51e 100644
> --- a/rust/kernel/sync/arc.rs
> +++ b/rust/kernel/sync/arc.rs
> @@ -73,6 +73,7 @@
> /// assert_eq!(cloned.b, 20);
> ///
> /// // The refcount drops to zero when `cloned` goes out of scope, and the memory is freed.
> +/// # Ok::<(), Error>(())
> /// ```
> ///
> /// Using `Arc<T>` as the type of `self`:
> @@ -98,6 +99,7 @@
> /// let obj = Arc::try_new(Example { a: 10, b: 20 })?;
> /// obj.use_reference();
> /// obj.take_over();
> +/// # Ok::<(), Error>(())
> /// ```
> ///
> /// Coercion from `Arc<Example>` to `Arc<dyn MyTrait>`:
> @@ -121,6 +123,7 @@
> ///
> /// // `coerced` has type `Arc<dyn MyTrait>`.
> /// let coerced: Arc<dyn MyTrait> = obj;
> +/// # Ok::<(), Error>(())
> /// ```
> pub struct Arc<T: ?Sized> {
> ptr: NonNull<ArcInner<T>>,
> @@ -337,7 +340,7 @@ fn from(item: Pin<UniqueArc<T>>) -> Self {
> /// # Example
> ///
> /// ```
> -/// use crate::sync::{Arc, ArcBorrow};
> +/// use kernel::sync::{Arc, ArcBorrow};
> ///
> /// struct Example;
> ///
> @@ -350,12 +353,13 @@ fn from(item: Pin<UniqueArc<T>>) -> Self {
> ///
> /// // Assert that both `obj` and `cloned` point to the same underlying object.
> /// assert!(core::ptr::eq(&*obj, &*cloned));
> +/// # Ok::<(), Error>(())
> /// ```
> ///
> /// Using `ArcBorrow<T>` as the type of `self`:
> ///
> /// ```
> -/// use crate::sync::{Arc, ArcBorrow};
> +/// use kernel::sync::{Arc, ArcBorrow};
> ///
> /// struct Example {
> /// a: u32,
> @@ -370,6 +374,7 @@ fn from(item: Pin<UniqueArc<T>>) -> Self {
> ///
> /// let obj = Arc::try_new(Example { a: 10, b: 20 })?;
> /// obj.as_arc_borrow().use_reference();
> +/// # Ok::<(), Error>(())
> /// ```
> pub struct ArcBorrow<'a, T: ?Sized + 'a> {
> inner: NonNull<ArcInner<T>>,
> diff --git a/rust/kernel/sync/lock/mutex.rs b/rust/kernel/sync/lock/mutex.rs
> index 923472f04af4..09276fedc091 100644
> --- a/rust/kernel/sync/lock/mutex.rs
> +++ b/rust/kernel/sync/lock/mutex.rs
> @@ -63,6 +63,7 @@ macro_rules! new_mutex {
> /// assert_eq!(e.c, 10);
> /// assert_eq!(e.d.lock().a, 20);
> /// assert_eq!(e.d.lock().b, 30);
> +/// # Ok::<(), Error>(())
> /// ```
> ///
> /// The following example shows how to use interior mutability to modify the contents of a struct
> diff --git a/rust/kernel/sync/lock/spinlock.rs b/rust/kernel/sync/lock/spinlock.rs
> index 979b56464a4e..91eb2c9e9123 100644
> --- a/rust/kernel/sync/lock/spinlock.rs
> +++ b/rust/kernel/sync/lock/spinlock.rs
> @@ -61,6 +61,7 @@ macro_rules! new_spinlock {
> /// assert_eq!(e.c, 10);
> /// assert_eq!(e.d.lock().a, 20);
> /// assert_eq!(e.d.lock().b, 30);
> +/// # Ok::<(), Error>(())
> /// ```
> ///
> /// The following example shows how to use interior mutability to modify the contents of a struct
> --
> 2.41.0
Reviewed-by: Björn Roy Baron <[email protected]>
------- Original Message -------
On Wednesday, June 14th, 2023 at 20:08, Miguel Ojeda <[email protected]> wrote:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> rust/kernel/str.rs | 4 +++-
> 1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs
> index c9dd3bf59e34..c41607b2e4fe 100644
> --- a/rust/kernel/str.rs
> +++ b/rust/kernel/str.rs
> @@ -213,6 +213,7 @@ impl fmt::Display for CStr {
> ///
> /// ```
> /// # use kernel::c_str;
> + /// # use kernel::fmt;
> /// # use kernel::str::CStr;
> /// # use kernel::str::CString;
> /// let penguin = c_str!("????");
> @@ -241,6 +242,7 @@ impl fmt::Debug for CStr {
> ///
> /// ```
> /// # use kernel::c_str;
> + /// # use kernel::fmt;
> /// # use kernel::str::CStr;
> /// # use kernel::str::CString;
> /// let penguin = c_str!("????");
> @@ -529,7 +531,7 @@ fn write_str(&mut self, s: &str) -> fmt::Result {
> /// # Examples
> ///
> /// ```
> -/// use kernel::str::CString;
> +/// use kernel::{str::CString, fmt};
> ///
> /// let s = CString::try_from_fmt(fmt!("{}{}{}", "abc", 10, 20)).unwrap();
> /// assert_eq!(s.as_bytes_with_nul(), "abc1020\0".as_bytes());
> --
> 2.41.0
Reviewed-by: Björn Roy Baron <[email protected]>
------- Original Message -------
On Wednesday, June 14th, 2023 at 20:08, Miguel Ojeda <[email protected]> wrote:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> rust/kernel/init.rs | 25 ++++++++++++++++---------
> 1 file changed, 16 insertions(+), 9 deletions(-)
>
> diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
> index b4332a4ec1f4..1073515ed40e 100644
> --- a/rust/kernel/init.rs
> +++ b/rust/kernel/init.rs
> @@ -120,14 +120,23 @@
> //! `slot` gets called.
> //!
> //! ```rust
> -//! use kernel::{prelude::*, init};
> +//! # #![allow(unreachable_pub, clippy::disallowed_names)]
> +//! use kernel::{prelude::*, init, types::Opaque};
> //! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin};
> //! # mod bindings {
> +//! # #![allow(non_camel_case_types)]
> //! # pub struct foo;
> //! # pub unsafe fn init_foo(_ptr: *mut foo) {}
> //! # pub unsafe fn destroy_foo(_ptr: *mut foo) {}
> //! # pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 }
> //! # }
> +//! # trait FromErrno {
> +//! # fn from_errno(errno: core::ffi::c_int) -> Error {
> +//! # // Dummy error that can be constructed outside the `kernel` crate.
> +//! # Error::from(core::fmt::Error)
> +//! # }
> +//! # }
> +//! # impl FromErrno for Error {}
> //! /// # Invariants
> //! ///
> //! /// `foo` is always initialized
> @@ -158,7 +167,7 @@
> //! if err != 0 {
> //! // Enabling has failed, first clean up the foo and then return the error.
> //! bindings::destroy_foo(Opaque::raw_get(foo));
> -//! return Err(Error::from_kernel_errno(err));
> +//! return Err(Error::from_errno(err));
> //! }
> //!
> //! // All fields of `RawFoo` have been initialized, since `_p` is a ZST.
> @@ -226,8 +235,7 @@
> ///
> /// ```rust
> /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
> -/// # use kernel::{init, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
> -/// # use macros::pin_data;
> +/// # use kernel::{init, macros::pin_data, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
> /// # use core::pin::Pin;
> /// #[pin_data]
> /// struct Foo {
> @@ -277,7 +285,7 @@ macro_rules! stack_pin_init {
> ///
> /// # Examples
> ///
> -/// ```rust
> +/// ```rust,ignore
> /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
> /// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
> /// # use macros::pin_data;
> @@ -303,7 +311,7 @@ macro_rules! stack_pin_init {
> /// pr_info!("a: {}", &*foo.a.lock());
> /// ```
> ///
> -/// ```rust
> +/// ```rust,ignore
> /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
> /// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
> /// # use macros::pin_data;
> @@ -513,8 +521,7 @@ macro_rules! stack_try_pin_init {
> /// For instance:
> ///
> /// ```rust
> -/// # use kernel::pin_init;
> -/// # use macros::pin_data;
> +/// # use kernel::{macros::pin_data, pin_init};
> /// # use core::{ptr::addr_of_mut, marker::PhantomPinned};
> /// #[pin_data]
> /// struct Buf {
> @@ -841,7 +848,7 @@ macro_rules! init {
> /// # Examples
> ///
> /// ```rust
> -/// use kernel::{init::PinInit, error::Error, InPlaceInit};
> +/// use kernel::{init::{PinInit, zeroed}, error::Error};
> /// struct BigBuf {
> /// big: Box<[u8; 1024 * 1024 * 1024]>,
> /// small: [u8; 1024 * 1024],
> --
> 2.41.0
Reviewed-by: Björn Roy Baron <[email protected]>
On Wed, 14 Jun 2023 at 20:12, Miguel Ojeda <[email protected]> wrote:
>
> 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
> # Doctest from line 13
> ok 1 rust_doctest_kernel_build_assert_rs_0
> # Doctest from line 56
> ok 2 rust_doctest_kernel_build_assert_rs_1
> # Doctest from line 122
> ok 3 rust_doctest_kernel_init_rs_0
> ...
> # Doctest from line 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. In the future, we may be able to use a proper KUnit
> facility to append this sort of information instead.
>
> 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.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> lib/Kconfig.debug | 13 +++
> rust/.gitignore | 2 +
> rust/Makefile | 29 ++++++
> rust/bindings/bindings_helper.h | 1 +
> rust/helpers.c | 7 ++
> rust/kernel/kunit.rs | 156 ++++++++++++++++++++++++++++++
> rust/kernel/lib.rs | 2 +
> scripts/.gitignore | 2 +
> scripts/Makefile | 4 +
> scripts/rustdoc_test_builder.rs | 73 ++++++++++++++
> scripts/rustdoc_test_gen.rs | 162 ++++++++++++++++++++++++++++++++
> 11 files changed, 451 insertions(+)
> create mode 100644 rust/kernel/kunit.rs
> create mode 100644 scripts/rustdoc_test_builder.rs
> create mode 100644 scripts/rustdoc_test_gen.rs
>
> diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
> index ce51d4dc6803..49f5e9c42200 100644
> --- a/lib/Kconfig.debug
> +++ b/lib/Kconfig.debug
> @@ -2911,6 +2911,19 @@ config RUST_BUILD_ASSERT_ALLOW
>
> If unsure, say N.
>
> +config RUST_KERNEL_KUNIT_TEST
> + bool "KUnit test for the `kernel` crate" if !KUNIT_ALL_TESTS
> + depends on RUST && KUNIT=y
> + default KUNIT_ALL_TESTS
> + help
> + This builds the documentation tests of the `kernel` crate
> + as KUnit tests.
> +
> + For more information on KUnit and unit tests in general,
> + please refer to the KUnit documentation in Documentation/dev-tools/kunit/.
> +
> + If unsure, say N.
> +
> endmenu # "Rust"
>
> endmenu # Kernel hacking
> diff --git a/rust/.gitignore b/rust/.gitignore
> index 21552992b401..d3829ffab80b 100644
> --- a/rust/.gitignore
> +++ b/rust/.gitignore
> @@ -2,6 +2,8 @@
>
> bindings_generated.rs
> bindings_helpers_generated.rs
> +doctests_kernel_generated.rs
> +doctests_kernel_generated_kunit.c
> uapi_generated.rs
> exports_*_generated.h
> doc/
> diff --git a/rust/Makefile b/rust/Makefile
> index 7c9d9f11aec5..e4e8b83752e2 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -27,6 +27,12 @@ endif
>
> obj-$(CONFIG_RUST) += exports.o
>
> +always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated.rs
> +always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated_kunit.c
> +
> +obj-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated.o
> +obj-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += doctests_kernel_generated_kunit.o
> +
> # Avoids running `$(RUSTC)` for the sysroot when it may not be available.
> ifdef CONFIG_RUST
>
> @@ -39,9 +45,11 @@ ifeq ($(quiet),silent_)
> cargo_quiet=-q
> rust_test_quiet=-q
> rustdoc_test_quiet=--test-args -q
> +rustdoc_test_kernel_quiet=>/dev/null
> else ifeq ($(quiet),quiet_)
> rust_test_quiet=-q
> rustdoc_test_quiet=--test-args -q
> +rustdoc_test_kernel_quiet=>/dev/null
> else
> cargo_quiet=--verbose
> endif
> @@ -157,6 +165,27 @@ quiet_cmd_rustdoc_test = RUSTDOC T $<
> -L$(objtree)/$(obj)/test --output $(objtree)/$(obj)/doc \
> --crate-name $(subst rusttest-,,$@) $<
>
> +quiet_cmd_rustdoc_test_kernel = RUSTDOC TK $<
> + cmd_rustdoc_test_kernel = \
> + rm -rf $(objtree)/$(obj)/test/doctests/kernel; \
> + mkdir -p $(objtree)/$(obj)/test/doctests/kernel; \
> + OBJTREE=$(abspath $(objtree)) \
> + $(RUSTDOC) --test $(rust_flags) \
> + @$(objtree)/include/generated/rustc_cfg \
> + -L$(objtree)/$(obj) --extern alloc --extern kernel \
> + --extern build_error --extern macros \
> + --extern bindings --extern uapi \
> + --no-run --crate-name kernel -Zunstable-options \
> + --test-builder $(objtree)/scripts/rustdoc_test_builder \
> + $< $(rustdoc_test_kernel_quiet); \
> + $(objtree)/scripts/rustdoc_test_gen
> +
> +%/doctests_kernel_generated.rs %/doctests_kernel_generated_kunit.c: \
> + $(src)/kernel/lib.rs $(obj)/kernel.o \
> + $(objtree)/scripts/rustdoc_test_builder \
> + $(objtree)/scripts/rustdoc_test_gen FORCE
> + $(call if_changed,rustdoc_test_kernel)
> +
> # We cannot use `-Zpanic-abort-tests` because some tests are dynamic,
> # so for the moment we skip `-Cpanic=abort`.
> quiet_cmd_rustc_test = RUSTC T $<
> diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
> index 3e601ce2548d..0f8d37c31ac2 100644
> --- a/rust/bindings/bindings_helper.h
> +++ b/rust/bindings/bindings_helper.h
> @@ -6,6 +6,7 @@
> * Sorted alphabetically.
> */
>
> +#include <kunit/test.h>
> #include <linux/errname.h>
> #include <linux/slab.h>
> #include <linux/refcount.h>
> diff --git a/rust/helpers.c b/rust/helpers.c
> index bb594da56137..49a5e1a4f0ae 100644
> --- a/rust/helpers.c
> +++ b/rust/helpers.c
> @@ -18,6 +18,7 @@
> * accidentally exposed.
> */
>
> +#include <kunit/test-bug.h>
> #include <linux/bug.h>
> #include <linux/build_bug.h>
> #include <linux/err.h>
> @@ -135,6 +136,12 @@ void rust_helper_put_task_struct(struct task_struct *t)
> }
> EXPORT_SYMBOL_GPL(rust_helper_put_task_struct);
>
> +struct kunit *rust_helper_kunit_get_current_test(void)
> +{
> + return kunit_get_current_test();
> +}
> +EXPORT_SYMBOL_GPL(rust_helper_kunit_get_current_test);
> +
> /*
> * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type
> * as the Rust `usize` type, so we can use it in contexts where Rust
> diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs
> new file mode 100644
> index 000000000000..3c94efcd7f76
> --- /dev/null
> +++ b/rust/kernel/kunit.rs
> @@ -0,0 +1,156 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! KUnit-based macros for Rust unit tests.
> +//!
> +//! C header: [`include/kunit/test.h`](../../../../../include/kunit/test.h)
> +//!
> +//! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>
> +
> +use core::{ffi::c_void, fmt};
> +
> +/// Prints a KUnit error.
> +///
> +/// Public but hidden since it should only be used from KUnit generated code.
> +#[doc(hidden)]
> +pub fn err(args: fmt::Arguments<'_>) {
> + // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we
> + // are passing.
> + #[cfg(CONFIG_PRINTK)]
> + unsafe {
> + bindings::_printk(
> + b"\x013%pA\0".as_ptr() as _,
> + &args as *const _ as *const c_void,
> + );
> + }
> +}
> +
> +/// Prints a KUnit error.
> +///
> +/// Public but hidden since it should only be used from KUnit generated code.
> +#[doc(hidden)]
> +pub fn info(args: fmt::Arguments<'_>) {
> + // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we
> + // are passing.
> + #[cfg(CONFIG_PRINTK)]
> + unsafe {
> + bindings::_printk(
> + b"\x016%pA\0".as_ptr() as _,
> + &args as *const _ as *const c_void,
> + );
> + }
> +}
> +
> +/// Asserts that a boolean expression is `true` at runtime.
> +///
> +/// Public but hidden since it should only be used from generated tests.
> +///
> +/// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit
> +/// facilities. See [`assert!`] for more details.
> +#[doc(hidden)]
> +#[macro_export]
> +macro_rules! kunit_assert {
> + ($name:literal, $condition:expr $(,)?) => {
> + 'out: {
> + // Do nothing if the condition is `true`.
> + if $condition {
> + break 'out;
> + }
> +
> + static LINE: i32 = core::line!() as i32;
> + static FILE: &'static $crate::str::CStr = $crate::c_str!(core::file!());
> + static CONDITION: &'static $crate::str::CStr = $crate::c_str!(stringify!($condition));
> +
> + // SAFETY: FFI call without safety requirements.
> + let kunit_test = unsafe { $crate::bindings::kunit_get_current_test() };
> + if kunit_test.is_null() {
> + // The assertion failed but this task is not running a KUnit test, so we cannot call
> + // KUnit, but at least print an error to the kernel log. This may happen if this
> + // macro is called from an spawned thread in a test (see
> + // `scripts/rustdoc_test_gen.rs`) or if some non-test code calls this macro by
> + // mistake (it is hidden to prevent that).
> + //
> + // This mimics KUnit's failed assertion format.
> + $crate::kunit::err(format_args!(
> + " # {}: ASSERTION FAILED at {FILE}:{LINE}\n",
> + $name
> + ));
> + $crate::kunit::err(format_args!(
> + " Expected {CONDITION} to be true, but is false\n"
> + ));
> + $crate::kunit::err(format_args!(
> + " Failure not reported to KUnit since this is a non-KUnit task\n"
> + ));
> + break 'out;
> + }
> +
> + #[repr(transparent)]
> + struct Location($crate::bindings::kunit_loc);
> +
> + #[repr(transparent)]
> + struct UnaryAssert($crate::bindings::kunit_unary_assert);
> +
> + // SAFETY: There is only a static instance and in that one the pointer field points to
> + // an immutable C string.
> + unsafe impl Sync for Location {}
> +
> + // SAFETY: There is only a static instance and in that one the pointer field points to
> + // an immutable C string.
> + unsafe impl Sync for UnaryAssert {}
> +
> + static LOCATION: Location = Location($crate::bindings::kunit_loc {
> + file: FILE.as_char_ptr(),
> + line: LINE,
> + });
> + static ASSERTION: UnaryAssert = UnaryAssert($crate::bindings::kunit_unary_assert {
> + assert: $crate::bindings::kunit_assert {},
> + condition: CONDITION.as_char_ptr(),
> + expected_true: true,
> + });
> +
> + // SAFETY:
> + // - FFI call.
> + // - The `kunit_test` pointer is valid because we got it from
> + // `kunit_get_current_test()` and it was not null. This means we are in a KUnit
> + // test, and that the pointer can be passed to KUnit functions and assertions.
> + // - The string pointers (`file` and `condition` above) point to null-terminated
> + // strings since they are `CStr`s.
> + // - The function pointer (`format`) points to the proper function.
> + // - The pointers passed will remain valid since they point to `static`s.
> + // - The format string is allowed to be null.
> + // - There are, however, problems with this: first of all, this will end up stopping
> + // the thread, without running destructors. While that is problematic in itself,
> + // it is considered UB to have what is effectively a forced foreign unwind
> + // with `extern "C"` ABI. One could observe the stack that is now gone from
> + // another thread. We should avoid pinning stack variables to prevent library UB,
> + // too. For the moment, given that test failures are reported immediately before the
> + // next test runs, that test failures should be fixed and that KUnit is explicitly
> + // documented as not suitable for production environments, we feel it is reasonable.
> + unsafe {
> + $crate::bindings::kunit_do_failed_assertion(
> + kunit_test,
> + core::ptr::addr_of!(LOCATION.0),
> + $crate::bindings::kunit_assert_type_KUNIT_ASSERTION,
> + core::ptr::addr_of!(ASSERTION.0.assert),
> + Some($crate::bindings::kunit_unary_assert_format),
> + core::ptr::null(),
> + );
> + }
> + }
> + };
> +}
> +
> +/// Asserts that two expressions are equal to each other (using [`PartialEq`]).
> +///
> +/// Public but hidden since it should only be used from generated tests.
> +///
> +/// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit
> +/// facilities. See [`assert!`] for more details.
> +#[doc(hidden)]
> +#[macro_export]
> +macro_rules! kunit_assert_eq {
> + ($name:literal, $left:expr, $right:expr $(,)?) => {{
> + // For the moment, we just forward to the expression assert because, for binary asserts,
> + // KUnit supports only a few types (e.g. integers).
> + $crate::kunit_assert!($name, $left == $right);
> + }};
> +}
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index 85b261209977..3642cadc34b1 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -34,6 +34,8 @@
> pub mod error;
> pub mod init;
> pub mod ioctl;
> +#[cfg(CONFIG_KUNIT)]
> +pub mod kunit;
> pub mod prelude;
> pub mod print;
> mod static_assert;
> diff --git a/scripts/.gitignore b/scripts/.gitignore
> index 6e9ce6720a05..3dbb8bb2457b 100644
> --- a/scripts/.gitignore
> +++ b/scripts/.gitignore
> @@ -5,6 +5,8 @@
> /kallsyms
> /module.lds
> /recordmcount
> +/rustdoc_test_builder
> +/rustdoc_test_gen
> /sign-file
> /sorttable
> /target.json
> diff --git a/scripts/Makefile b/scripts/Makefile
> index 32b6ba722728..d5a5382e753c 100644
> --- a/scripts/Makefile
> +++ b/scripts/Makefile
> @@ -9,6 +9,8 @@ hostprogs-always-$(CONFIG_BUILDTIME_TABLE_SORT) += sorttable
> hostprogs-always-$(CONFIG_ASN1) += asn1_compiler
> hostprogs-always-$(CONFIG_MODULE_SIG_FORMAT) += sign-file
> hostprogs-always-$(CONFIG_SYSTEM_EXTRA_CERTIFICATE) += insert-sys-cert
> +hostprogs-always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += rustdoc_test_builder
> +hostprogs-always-$(CONFIG_RUST_KERNEL_KUNIT_TEST) += rustdoc_test_gen
> always-$(CONFIG_RUST) += target.json
>
> filechk_rust_target = $< < include/config/auto.conf
> @@ -18,6 +20,8 @@ $(obj)/target.json: scripts/generate_rust_target include/config/auto.conf FORCE
>
> hostprogs += generate_rust_target
> generate_rust_target-rust := y
> +rustdoc_test_builder-rust := y
> +rustdoc_test_gen-rust := y
>
> HOSTCFLAGS_sorttable.o = -I$(srctree)/tools/include
> HOSTLDLIBS_sorttable = -lpthread
> diff --git a/scripts/rustdoc_test_builder.rs b/scripts/rustdoc_test_builder.rs
> new file mode 100644
> index 000000000000..e3b7138fb4f9
> --- /dev/null
> +++ b/scripts/rustdoc_test_builder.rs
> @@ -0,0 +1,73 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Test builder for `rustdoc`-generated tests.
> +//!
> +//! This script is a hack to extract the test from `rustdoc`'s output. Ideally, `rustdoc` would
> +//! have an option to generate this information instead, e.g. as JSON output.
> +//!
> +//! The `rustdoc`-generated test names look like `{file}_{line}_{number}`, e.g.
> +//! `...path_rust_kernel_sync_arc_rs_42_0`. `number` is the "test number", needed in cases like
> +//! a macro that expands into items with doctests is invoked several times within the same line.
> +//!
> +//! However, since these names are used for bisection in CI, the line number makes it not stable
> +//! at all. In the future, we would like `rustdoc` to give us the Rust item path associated with
> +//! the test, plus a "test number" (for cases with several examples per item) and generate a name
> +//! from that. For the moment, we generate ourselves a new name, `{file}_{number}` instead, in
> +//! the `gen` script (done there since we need to be aware of all the tests in a given file).
> +
> +use std::fs::File;
> +use std::io::{BufWriter, Read, Write};
> +
> +fn main() {
> + let mut stdin = std::io::stdin().lock();
> + let mut body = String::new();
> + stdin.read_to_string(&mut body).unwrap();
> +
> + // Find the generated function name looking for the inner function inside `main()`.
> + //
> + // The line we are looking for looks like one of the following:
> + //
> + // ```
> + // fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_28_0() {
> + // fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_37_0() -> Result<(), impl core::fmt::Debug> {
> + // ```
> + //
> + // It should be unlikely that doctest code matches such lines (when code is formatted properly).
> + let rustdoc_function_name = body
> + .lines()
> + .find_map(|line| {
> + Some(
> + line.split_once("fn main() {")?Tested-by: Sergio González Collado <[email protected]>
> + .1
> + .split_once("fn ")?
> + .1
> + .split_once("()")?
> + .0,
> + )
> + .filter(|x| x.chars().all(|c| c.is_alphanumeric() || c == '_'))
> + })
> + .expect("No test function found in `rustdoc`'s output.");
> +
> + // Qualify `Result` to avoid the collision with our own `Result` coming from the prelude.
> + let body = body.replace(
> + &format!("{rustdoc_function_name}() -> Result<(), impl core::fmt::Debug> {{"),
> + &format!("{rustdoc_function_name}() -> core::result::Result<(), impl core::fmt::Debug> {{"),
> + );
> +
> + // For tests that get generated with `Result`, like above, `rustdoc` generates an `unwrap()` on
> + // the return value to check there were no returned errors. Instead, we use our assert macro
> + // since we want to just fail the test, not panic the kernel.
> + //
> + // We save the result in a variable so that the failed assertion message looks nicer.
> + let body = body.replace(
> + &format!("}} {rustdoc_function_name}().unwrap() }}"),
> + &format!("}} let test_return_value = {rustdoc_function_name}(); assert!(test_return_value.is_ok()); }}"),
> + );
> +
> + // Figure out a smaller test name based on the generated function name.
> + let name = rustdoc_function_name.split_once("_rust_kernel_").unwrap().1;
> +
> + let path = format!("rust/test/doctests/kernel/{name}");
> +
> + write!(BufWriter::new(File::create(path).unwrap()), "{body}").unwrap();
> +}
> diff --git a/scripts/rustdoc_test_gen.rs b/scripts/rustdoc_test_gen.rs
> new file mode 100644
> index 000000000000..793885c32c0d
> --- /dev/null
> +++ b/scripts/rustdoc_test_gen.rs
> @@ -0,0 +1,162 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Generates KUnit tests from saved `rustdoc`-generated tests.
> +//!
> +//! KUnit passes a context (`struct kunit *`) to each test, which should be forwarded to the other
> +//! KUnit functions and macros.
> +//!
> +//! However, we want to keep this as an implementation detail because:
> +//!
> +//! - Test code should not care about the implementation.
> +//!
> +//! - Documentation looks worse if it needs to carry extra details unrelated to the piece
> +//! being described.
> +//!
> +//! - Test code should be able to define functions and call them, without having to carry
> +//! the context.
> +//!
> +//! - Later on, we may want to be able to test non-kernel code (e.g. `core`, `alloc` or
> +//! third-party crates) which likely use the standard library `assert*!` macros.
> +//!
> +//! For this reason, instead of the passed context, `kunit_get_current_test()` is used instead
> +//! (i.e. `current->kunit_test`).
> +//!
> +//! Note that this means other threads/tasks potentially spawned by a given test, if failing, will
> +//! report the failure in the kernel log but will not fail the actual test. Saving the pointer in
> +//! e.g. a `static` per test does not fully solve the issue either, because currently KUnit does
> +//! not support assertions (only expectations) from other tasks. Thus leave that feature for
> +//! the future, which simplifies the code here too. We could also simply not allow `assert`s in
> +//! other tasks, but that seems overly constraining, and we do want to support them, eventually.
> +
> +use std::io::{BufWriter, Read, Write};
> +use std::{fs, fs::File};
> +
> +fn main() {
> + let mut paths = fs::read_dir("rust/test/doctests/kernel")
> + .unwrap()
> + .map(|entry| entry.unwrap().path())
> + .collect::<Vec<_>>();
> +
> + // Sort paths for clarity.
> + paths.sort();
> +
> + let mut rust_tests = String::new();
> + let mut c_test_declarations = String::new();
> + let mut c_test_cases = String::new();
> + let mut body = String::new();
> + let mut last_file = String::new();
> + let mut number = 0;
> + for path in paths {
> + // The `name` follows the `{file}_{line}_{number}` pattern (see description in
> + // `scripts/rustdoc_test_builder.rs`). Discard the `number`.
> + let name = path.file_name().unwrap().to_str().unwrap().to_string();
> +
> + // Extract the `file` and the `line`, discarding the `number`.
> + let (file, line) = name.rsplit_once('_').unwrap().0.rsplit_once('_').unwrap();
> +
> + // Generate an ID sequence ("test number") for each one in the file.
> + if file == last_file {
> + number += 1;
> + } else {
> + number = 0;
> + last_file = file.to_string();
> + }
> +
> + // Generate a KUnit name (i.e. test name and C symbol) for this test.
> + //
> + // We avoid the line number, like `rustdoc` does, to make things slightly more stable for
> + // bisection purposes. However, to aid developers in mapping back what test failed, we will
> + // print a diagnostics line in the KTAP report.
> + let kunit_name = format!("rust_doctest_kernel_{file}_{number}");
> +
> + // Read the test's text contents to dump it below.
> + body.clear();
> + File::open(path).unwrap().read_to_string(&mut body).unwrap();
> +
> + let line = line.parse::<core::ffi::c_int>().unwrap();
> +
> + use std::fmt::Write;
> + write!(
> + rust_tests,
> + r#"/// Generated `{name}` KUnit test case from a Rust documentation test.
> +#[no_mangle]
> +pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
> + /// Overrides the usual [`assert!`] macro with one that calls KUnit instead.
> + #[allow(unused)]
> + macro_rules! assert {{
> + ($cond:expr $(,)?) => {{{{
> + kernel::kunit_assert!("{kunit_name}", $cond);
> + }}}}
> + }}
> +
> + /// Overrides the usual [`assert_eq!`] macro with one that calls KUnit instead.
> + #[allow(unused)]
> + macro_rules! assert_eq {{
> + ($left:expr, $right:expr $(,)?) => {{{{
> + kernel::kunit_assert_eq!("{kunit_name}", $left, $right);
> + }}}}
> + }}
> +
> + // Many tests need the prelude, so provide it by default.
> + #[allow(unused)]
> + use kernel::prelude::*;
> +
> + // Display line number so that developers can map the test easily to the source code.
> + kernel::kunit::info(format_args!(" # Doctest from line {line}\n"));
> +
> + {{
> + {body}
> + main();
> + }}
> +}}
> +
> +"#
> + )
> + .unwrap();
> +
> + write!(c_test_declarations, "void {kunit_name}(struct kunit *);\n").unwrap();
> + write!(c_test_cases, " KUNIT_CASE({kunit_name}),\n").unwrap();
> + }
> +
> + let rust_tests = rust_tests.trim();
> + let c_test_declarations = c_test_declarations.trim();
> + let c_test_cases = c_test_cases.trim();
> +
> + write!(
> + BufWriter::new(File::create("rust/doctests_kernel_generated.rs").unwrap()),
> + r#"//! `kernel` crate documentation tests.
> +
> +const __LOG_PREFIX: &[u8] = b"rust_doctests_kernel\0";
> +
> +{rust_tests}
> +"#
> + )
> + .unwrap();
> +
> + write!(
> + BufWriter::new(File::create("rust/doctests_kernel_generated_kunit.c").unwrap()),
> + r#"/*
> + * `kernel` crate documentation tests.
> + */
> +
> +#include <kunit/test.h>
> +
> +{c_test_declarations}
> +
> +static struct kunit_case test_cases[] = {{
> + {c_test_cases}
> + {{ }}
> +}};
> +
> +static struct kunit_suite test_suite = {{
> + .name = "rust_doctests_kernel",
> + .test_cases = test_cases,
> +}};
> +
> +kunit_test_suite(test_suite);
> +
> +MODULE_LICENSE("GPL");
> +"#
> + )
> + .unwrap();
> +}
> --
> 2.41.0
>
Tested-by: Sergio González Collado <[email protected]>
On 6/14/23 20:08, Miguel Ojeda wrote:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <[email protected]>
Reviewed-by: Benno Lossin <[email protected]>
--
Cheers,
Benno
> ---
> rust/kernel/init.rs | 25 ++++++++++++++++---------
> 1 file changed, 16 insertions(+), 9 deletions(-)
>
> diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
> index b4332a4ec1f4..1073515ed40e 100644
> --- a/rust/kernel/init.rs
> +++ b/rust/kernel/init.rs
> @@ -120,14 +120,23 @@
> //! `slot` gets called.
> //!
> //! ```rust
> -//! use kernel::{prelude::*, init};
> +//! # #![allow(unreachable_pub, clippy::disallowed_names)]
> +//! use kernel::{prelude::*, init, types::Opaque};
> //! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin};
> //! # mod bindings {
> +//! # #![allow(non_camel_case_types)]
> //! # pub struct foo;
> //! # pub unsafe fn init_foo(_ptr: *mut foo) {}
> //! # pub unsafe fn destroy_foo(_ptr: *mut foo) {}
> //! # pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 }
> //! # }
> +//! # trait FromErrno {
> +//! # fn from_errno(errno: core::ffi::c_int) -> Error {
> +//! # // Dummy error that can be constructed outside the `kernel` crate.
> +//! # Error::from(core::fmt::Error)
> +//! # }
> +//! # }
> +//! # impl FromErrno for Error {}
> //! /// # Invariants
> //! ///
> //! /// `foo` is always initialized
> @@ -158,7 +167,7 @@
> //! if err != 0 {
> //! // Enabling has failed, first clean up the foo and then return the error.
> //! bindings::destroy_foo(Opaque::raw_get(foo));
> -//! return Err(Error::from_kernel_errno(err));
> +//! return Err(Error::from_errno(err));
> //! }
> //!
> //! // All fields of `RawFoo` have been initialized, since `_p` is a ZST.
> @@ -226,8 +235,7 @@
> ///
> /// ```rust
> /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
> -/// # use kernel::{init, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
> -/// # use macros::pin_data;
> +/// # use kernel::{init, macros::pin_data, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
> /// # use core::pin::Pin;
> /// #[pin_data]
> /// struct Foo {
> @@ -277,7 +285,7 @@ macro_rules! stack_pin_init {
> ///
> /// # Examples
> ///
> -/// ```rust
> +/// ```rust,ignore
> /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
> /// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
> /// # use macros::pin_data;
> @@ -303,7 +311,7 @@ macro_rules! stack_pin_init {
> /// pr_info!("a: {}", &*foo.a.lock());
> /// ```
> ///
> -/// ```rust
> +/// ```rust,ignore
> /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
> /// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
> /// # use macros::pin_data;
> @@ -513,8 +521,7 @@ macro_rules! stack_try_pin_init {
> /// For instance:
> ///
> /// ```rust
> -/// # use kernel::pin_init;
> -/// # use macros::pin_data;
> +/// # use kernel::{macros::pin_data, pin_init};
> /// # use core::{ptr::addr_of_mut, marker::PhantomPinned};
> /// #[pin_data]
> /// struct Buf {
> @@ -841,7 +848,7 @@ macro_rules! init {
> /// # Examples
> ///
> /// ```rust
> -/// use kernel::{init::PinInit, error::Error, InPlaceInit};
> +/// use kernel::{init::{PinInit, zeroed}, error::Error};
> /// struct BigBuf {
> /// big: Box<[u8; 1024 * 1024 * 1024]>,
> /// small: [u8; 1024 * 1024],
> --
> 2.41.0
>
On Wed, Jun 14, 2023 at 08:08:29PM +0200, Miguel Ojeda wrote:
> diff --git a/rust/helpers.c b/rust/helpers.c
> index bb594da56137..49a5e1a4f0ae 100644
> --- a/rust/helpers.c
> +++ b/rust/helpers.c
> @@ -18,6 +18,7 @@
> * accidentally exposed.
> */
>
> +#include <kunit/test-bug.h>
When CONFIG_KUNIT=n, the above file is mostly just a function that
returns "NULL", however, since "NULL" is not defined: kunit/test-bug.h
includes nothing if CONFIG_KUNIT=n, bindgen is not happy about it:
./include/kunit/test-bug.h:63:67: error: use of undeclared identifier 'NULL'
, we can fix this in Rust side by adding linux/stddef.h before
kunit/test-bug.h as below, but maybe it's better fixed inside
kunit/test-bug.h?
Regards,
Boqun
-------------------------------->8
diff --git a/rust/helpers.c b/rust/helpers.c
index 49a5e1a4f0ae..048d11c7d796 100644
--- a/rust/helpers.c
+++ b/rust/helpers.c
@@ -18,6 +18,7 @@
* accidentally exposed.
*/
+#include <linux/stddef.h>
#include <kunit/test-bug.h>
#include <linux/bug.h>
#include <linux/build_bug.h>
> #include <linux/bug.h>
> #include <linux/build_bug.h>
> #include <linux/err.h>
> @@ -135,6 +136,12 @@ void rust_helper_put_task_struct(struct task_struct *t)
> }
> EXPORT_SYMBOL_GPL(rust_helper_put_task_struct);
>
> +struct kunit *rust_helper_kunit_get_current_test(void)
> +{
> + return kunit_get_current_test();
> +}
> +EXPORT_SYMBOL_GPL(rust_helper_kunit_get_current_test);
> +
> /*
> * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type
> * as the Rust `usize` type, so we can use it in contexts where Rust