Merge pull request #912 from ojeda/kunit

rust: improvements to KUnit doctests

Author: ojeda

rust/Makefile

@@ -27,6 +27,9 @@ 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
 
@@ -164,11 +167,14 @@ quiet_cmd_rustdoc_test_kernel = RUSTDOC TK $<
 		--extern build_error --extern macros \
 		--extern bindings \
 		--no-run --crate-name kernel -Zunstable-options \
-		--test-builder $(srctree)/scripts/rustdoc_test_builder.py \
+		--test-builder $(objtree)/scripts/rustdoc_test_builder \
 		$< $(rustdoc_test_kernel_quiet); \
-	$(srctree)/scripts/rustdoc_test_gen.py
+	$(objtree)/scripts/rustdoc_test_gen
 
-%/doctests_kernel_generated.rs %/doctests_kernel_generated_kunit.c: $(src)/kernel/lib.rs $(obj)/kernel.o FORCE
+%/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,

rust/kernel/kasync/executor/workqueue.rs

@@ -177,19 +177,16 @@ struct ExecutorInner {
 /// use kernel::spawn_task;
 /// use kernel::workqueue;
 ///
-/// fn example_shared_workqueue() -> Result {
-///     let mut handle = Executor::try_new(workqueue::system())?;
-///     spawn_task!(handle.executor(), async {
-///         pr_info!("First workqueue task\n");
-///     })?;
-///     spawn_task!(handle.executor(), async {
-///         pr_info!("Second workqueue task\n");
-///     })?;
-///     handle.detach();
-///     Ok(())
-/// }
+/// let mut handle = Executor::try_new(workqueue::system())?;
+/// spawn_task!(handle.executor(), async {
+///     pr_info!("First workqueue task\n");
+/// })?;
+/// spawn_task!(handle.executor(), async {
+///     pr_info!("Second workqueue task\n");
+/// })?;
+/// handle.detach();
 ///
-/// # example_shared_workqueue().unwrap();
+/// # Ok::<(), Error>(())
 /// ```
 pub struct Executor {
     queue: Either<BoxedQueue, &'static Queue>,

rust/kernel/rbtree.rs

@@ -39,7 +39,6 @@ struct Node<K, V> {
 /// ```
 /// use kernel::rbtree::RBTree;
 ///
-/// # fn test() -> Result {
 /// // Create a new tree.
 /// let mut tree = RBTree::new();
 ///
@@ -110,10 +109,7 @@ struct Node<K, V> {
 ///     assert!(iter.next().is_none());
 /// }
 ///
-/// # Ok(())
-/// # }
-/// #
-/// # assert_eq!(test(), Ok(()));
+/// # Ok::<(), Error>(())
 /// ```
 ///
 /// In the example below, we first allocate a node, acquire a spinlock, then insert the node into
@@ -140,7 +136,6 @@ struct Node<K, V> {
 /// ```
 /// use kernel::rbtree::RBTree;
 ///
-/// # fn test() -> Result {
 /// // Create a new tree.
 /// let mut tree = RBTree::new();
 ///
@@ -185,10 +180,7 @@ struct Node<K, V> {
 ///     assert!(iter.next().is_none());
 /// }
 ///
-/// # Ok(())
-/// # }
-/// #
-/// # assert_eq!(test(), Ok(()));
+/// # Ok::<(), Error>(())
 /// ```
 pub struct RBTree<K, V> {
     root: bindings::rb_root,

rust/kernel/workqueue.rs

@@ -119,13 +119,9 @@ macro_rules! init_work_item_adapter {
 ///
 /// ```
 /// # use kernel::{spawn_work_item, workqueue};
-///
-/// # fn example() -> Result {
 /// spawn_work_item!(workqueue::system(), || pr_info!("Hello from a work item\n"))?;
-/// #     Ok(())
-/// # }
 ///
-/// # example().unwrap()
+/// # Ok::<(), Error>(())
 /// ```
 ///
 /// The following example is used to create a work item and enqueue it several times. We note that
@@ -152,7 +148,6 @@ macro_rules! init_work_item_adapter {
 ///     }
 /// });
 ///
-/// # fn example() -> Result {
 /// let e = UniqueArc::try_new(Example {
 ///     count: AtomicU32::new(0),
 ///     // SAFETY: `work` is initialised below.
@@ -163,10 +158,8 @@ macro_rules! init_work_item_adapter {
 ///
 /// // Queue the first time.
 /// workqueue::system().enqueue(e.into());
-/// #     Ok(())
-/// # }
 ///
-/// # example().unwrap()
+/// # Ok::<(), Error>(())
 /// ```
 ///
 /// The following example has two different work items in the same struct, which allows it to be
@@ -187,7 +180,6 @@ macro_rules! init_work_item_adapter {
 /// struct SecondAdapter;
 /// kernel::impl_work_adapter!(SecondAdapter, Example, work2, |_| pr_info!("Second work\n"));
 ///
-/// # fn example() -> Result {
 /// let e = UniqueArc::try_new(Example {
 ///     // SAFETY: `work1` is initialised below.
 ///     work1: unsafe { Work::new() },
@@ -203,10 +195,8 @@ macro_rules! init_work_item_adapter {
 /// // Enqueue the two different work items.
 /// workqueue::system().enqueue(e.clone());
 /// workqueue::system().enqueue_adapter::<SecondAdapter>(e);
-/// #     Ok(())
-/// # }
 ///
-/// # example().unwrap()
+/// # Ok::<(), Error>(())
 /// ```
 #[repr(transparent)]
 pub struct Queue(Opaque<bindings::workqueue_struct>);

scripts/.gitignore

@@ -6,6 +6,8 @@
 /kallsyms
 /module.lds
 /recordmcount
+/rustdoc_test_builder
+/rustdoc_test_gen
 /sign-file
 /sorttable
 /unifdef

scripts/Makefile

@@ -10,9 +10,14 @@ 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)				+= generate_rust_target
+hostprogs-always-$(CONFIG_RUST)				+= \
+	generate_rust_target \
+	rustdoc_test_builder \
+	rustdoc_test_gen
 
 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

scripts/rustdoc_test_builder.py

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Test builder for `rustdoc`-generated tests.
+
+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();
+
+    let name = body
+        .lines()
+        .find_map(|line| {
+            Some(
+                line.split_once("fn ")?
+                    .1
+                    .split_once("rust_kernel_")?
+                    .1
+                    .split_once("()")?
+                    .0,
+            )
+            .filter(|x| x.chars().all(|c| c.is_alphanumeric() || c == '_'))
+        })
+        .expect("No test name found.");
+
+    // Qualify `Result` to avoid the collision with our own `Result`
+    // coming from the prelude.
+    let body = body.replace(
+        &format!("rust_kernel_{name}() -> Result<(), impl core::fmt::Debug> {{"),
+        &format!("rust_kernel_{name}() -> core::result::Result<(), impl core::fmt::Debug> {{"),
+    );
+
+    let name = format!("rust_kernel_doctest_{name}");
+    let path = format!("rust/test/doctests/kernel/{name}");
+
+    write!(
+        BufWriter::new(File::create(path).unwrap()),
+        "{name}\n{body}"
+    )
+    .unwrap();
+}