Usage¶

These tests can be run via KUnit. For example viakunit_tool (kunit.py)on the command line:

./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y

Alternatively, KUnit can run them as kernel built-in at boot. Refer toKUnit - Linux Kernel Unit Testing for the general KUnit documentationandKUnit Architecture for the details of kernelbuilt-in vs. command line testing.

To use these KUnit doctests, the following must be enabled:

CONFIG_KUNIT   Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit testsCONFIG_RUST_KERNEL_DOCTESTS   Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate

in the kernel config system.

KUnit tests are documentation tests¶

These documentation tests are typically examples of usage of any item (e.g.function, struct, module...).

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

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

In userspace, the tests are collected and run viarustdoc. Using the toolas-is would be useful already, since it allows verifying that examples compile(thus enforcing they are kept in sync with the code they document) and as wellas running those that do not depend on in-kernel APIs.

For the kernel, however, these tests get transformed into KUnit test suites.This means that doctests get compiled as Rust kernel objects, allowing them torun against a built kernel.

A benefit of this KUnit integration is that Rust doctests get to reuse existingtesting facilities. For instance, the kernel log would look like:

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

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\n"))?;/// # Ok::<(), Error>(())/// ```

The tests are also compiled with Clippy underCLIPPY=1, just like normalcode, thus also benefitting from extra linting.

In order for developers to easily see which line of doctest code caused afailure, a KTAP diagnostic line is printed to the log. This contains thelocation (file and line) of the original test (i.e. instead of the location inthe generated Rust file):

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

Rust tests appear to assert using the usualassert! andassert_eq!macros from the Rust standard library (core). We provide a custom versionthat forwards the call to KUnit instead. Importantly, these macros do notrequire passing context, unlike those for KUnit testing (i.e.structkunit*). This makes them easier to use, and readers of thedocumentation do not need to care about which testing framework is used. Inaddition, it may allow us to test third-party code more easily in the future.

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 assertionactually failed. Additionally, doctests are not run for nonpublic functions.

Since these tests are examples, i.e. they are part of the documentation, theyshould generally be written like “real code”. Thus, for example, instead ofusingunwrap() orexpect(), use the? operator. For more background,please see:

https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust