[PATCH v5 2/3] rust: macros: add macro to easily run KUnit tests
From: David Gow
Date: Fri Dec 13 2024 - 03:11:40 EST
From: José Expósito <jose.exposito89@xxxxxxxxx>
Add a new procedural macro (`#[kunit_tests(kunit_test_suit_name)]`) to
run KUnit tests using a user-space like syntax.
The macro, that should be used on modules, transforms every `#[test]`
in a `kunit_case!` and adds a `kunit_unsafe_test_suite!` registering
all of them.
The only difference with user-space tests is that instead of using
`#[cfg(test)]`, `#[kunit_tests(kunit_test_suit_name)]` is used.
Note that `#[cfg(CONFIG_KUNIT)]` is added so the test module is not
compiled when `CONFIG_KUNIT` is set to `n`.
Reviewed-by: David Gow <davidgow@xxxxxxxxxx>
Signed-off-by: José Expósito <jose.exposito89@xxxxxxxxx>
Co-developed-by: Boqun Feng <boqun.feng@xxxxxxxxx>
Signed-off-by: Boqun Feng <boqun.feng@xxxxxxxxx>
Signed-off-by: David Gow <davidgow@xxxxxxxxxx>
---
Changes since v4:
https://lore.kernel.org/linux-kselftest/20241101064505.3820737-3-davidgow@xxxxxxxxxx/
- Rebased against 6.13-rc1
- "Expect" that the sample assert_eq!(1+1, 2) produces a clippy warning
due to a redundant assertion. (Thanks Boqun, Miguel)
Changes since v3:
https://lore.kernel.org/linux-kselftest/20241030045719.3085147-6-davidgow@xxxxxxxxxx/
- The #[kunit_tests()] macro now preserves span information, so
errors can be better reported. (Thanks, Boqun!)
- The example test has been replaced to no longer use assert_eq!() with
a constant bool argument (which triggered a clippy warning now we
have the span info). It now checks 1 + 1 == 2, to match the C example.
- (The in_kunit_test() test in the next patch uses assert!() to check
a bool, so having something different here seemed to make a better
example.)
Changes since v2:
https://lore.kernel.org/linux-kselftest/20241029092422.2884505-3-davidgow@xxxxxxxxxx/
- Include missing rust/macros/kunit.rs file from v2. (Thanks Boqun!)
- The proc macro now emits an error if the suite name is too long.
Changes since v1:
https://lore.kernel.org/lkml/20230720-rustbind-v1-2-c80db349e3b5@xxxxxxxxxx/
- Rebased on top of rust-next
- Make use of the new const functions, rather than the kunit_case!()
macro.
---
MAINTAINERS | 1 +
rust/kernel/kunit.rs | 16 ++++-
rust/macros/kunit.rs | 168 +++++++++++++++++++++++++++++++++++++++++++
rust/macros/lib.rs | 29 ++++++++
4 files changed, 213 insertions(+), 1 deletion(-)
create mode 100644 rust/macros/kunit.rs
diff --git a/MAINTAINERS b/MAINTAINERS
index e6e71b05710b..cbe5a99eefea 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12562,6 +12562,7 @@ F: Documentation/dev-tools/kunit/
F: include/kunit/
F: lib/kunit/
F: rust/kernel/kunit.rs
+F: rust/macros/kunit.rs
F: scripts/rustdoc_test_*
F: tools/testing/kunit/
diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs
index 5003282cb4c4..a92f12da77d5 100644
--- a/rust/kernel/kunit.rs
+++ b/rust/kernel/kunit.rs
@@ -40,6 +40,8 @@ pub fn info(args: fmt::Arguments<'_>) {
}
}
+use macros::kunit_tests;
+
/// Asserts that a boolean expression is `true` at runtime.
///
/// Public but hidden since it should only be used from generated tests.
@@ -272,10 +274,22 @@ macro_rules! kunit_unsafe_test_suite {
};
#[used]
+ #[allow(unused_unsafe)]
#[link_section = ".kunit_test_suites"]
static mut KUNIT_TEST_SUITE_ENTRY: *const $crate::bindings::kunit_suite =
// SAFETY: `KUNIT_TEST_SUITE` is static.
- unsafe { core::ptr::addr_of_mut!(KUNIT_TEST_SUITE) };
+ unsafe {
+ core::ptr::addr_of_mut!(KUNIT_TEST_SUITE)
+ };
};
};
}
+
+#[kunit_tests(rust_kernel_kunit)]
+mod tests {
+ #[test]
+ fn rust_test_kunit_example_test() {
+ #![expect(clippy::eq_op)]
+ assert_eq!(1 + 1, 2);
+ }
+}
diff --git a/rust/macros/kunit.rs b/rust/macros/kunit.rs
new file mode 100644
index 000000000000..c421ff65f7f9
--- /dev/null
+++ b/rust/macros/kunit.rs
@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Procedural macro to run KUnit tests using a user-space like syntax.
+//!
+//! Copyright (c) 2023 José Expósito <jose.exposito89@xxxxxxxxx>
+
+use proc_macro::{Delimiter, Group, TokenStream, TokenTree};
+use std::fmt::Write;
+
+pub(crate) fn kunit_tests(attr: TokenStream, ts: TokenStream) -> TokenStream {
+ if attr.to_string().is_empty() {
+ panic!("Missing test name in #[kunit_tests(test_name)] macro")
+ }
+
+ if attr.to_string().as_bytes().len() > 255 {
+ panic!("The test suite name `{}` exceeds the maximum length of 255 bytes.", attr)
+ }
+
+ let mut tokens: Vec<_> = ts.into_iter().collect();
+
+ // Scan for the "mod" keyword.
+ tokens
+ .iter()
+ .find_map(|token| match token {
+ TokenTree::Ident(ident) => match ident.to_string().as_str() {
+ "mod" => Some(true),
+ _ => None,
+ },
+ _ => None,
+ })
+ .expect("#[kunit_tests(test_name)] attribute should only be applied to modules");
+
+ // Retrieve the main body. The main body should be the last token tree.
+ let body = match tokens.pop() {
+ Some(TokenTree::Group(group)) if group.delimiter() == Delimiter::Brace => group,
+ _ => panic!("cannot locate main body of module"),
+ };
+
+ // Get the functions set as tests. Search for `[test]` -> `fn`.
+ let mut body_it = body.stream().into_iter();
+ let mut tests = Vec::new();
+ while let Some(token) = body_it.next() {
+ match token {
+ TokenTree::Group(ident) if ident.to_string() == "[test]" => match body_it.next() {
+ Some(TokenTree::Ident(ident)) if ident.to_string() == "fn" => {
+ let test_name = match body_it.next() {
+ Some(TokenTree::Ident(ident)) => ident.to_string(),
+ _ => continue,
+ };
+ tests.push(test_name);
+ }
+ _ => continue,
+ },
+ _ => (),
+ }
+ }
+
+ // Add `#[cfg(CONFIG_KUNIT)]` before the module declaration.
+ let config_kunit = "#[cfg(CONFIG_KUNIT)]".to_owned().parse().unwrap();
+ tokens.insert(
+ 0,
+ TokenTree::Group(Group::new(Delimiter::None, config_kunit)),
+ );
+
+ // Generate the test KUnit test suite and a test case for each `#[test]`.
+ // The code generated for the following test module:
+ //
+ // ```
+ // #[kunit_tests(kunit_test_suit_name)]
+ // mod tests {
+ // #[test]
+ // fn foo() {
+ // assert_eq!(1, 1);
+ // }
+ //
+ // #[test]
+ // fn bar() {
+ // assert_eq!(2, 2);
+ // }
+ // ```
+ //
+ // Looks like:
+ //
+ // ```
+ // unsafe extern "C" fn kunit_rust_wrapper_foo(_test: *mut kernel::bindings::kunit) {
+ // foo();
+ // }
+ // static mut KUNIT_CASE_FOO: kernel::bindings::kunit_case =
+ // kernel::kunit::kunit_case(foo, kunit_rust_wrapper_foo);
+ //
+ // unsafe extern "C" fn kunit_rust_wrapper_bar(_test: * mut kernel::bindings::kunit) {
+ // bar();
+ // }
+ // static mut KUNIT_CASE_BAR: kernel::bindings::kunit_case =
+ // kernel::kunit::kunit_case(bar, kunit_rust_wrapper_bar);
+ //
+ // static mut KUNIT_CASE_NULL: kernel::bindings::kunit_case = kernel::kunit::kunit_case_null();
+ //
+ // static mut TEST_CASES : &mut[kernel::bindings::kunit_case] = unsafe {
+ // &mut [KUNIT_CASE_FOO, KUNIT_CASE_BAR, KUNIT_CASE_NULL]
+ // };
+ //
+ // kernel::kunit_unsafe_test_suite!(kunit_test_suit_name, TEST_CASES);
+ // ```
+ let mut kunit_macros = "".to_owned();
+ let mut test_cases = "".to_owned();
+ for test in tests {
+ let kunit_wrapper_fn_name = format!("kunit_rust_wrapper_{}", test);
+ let kunit_case_name = format!("KUNIT_CASE_{}", test.to_uppercase());
+ let kunit_wrapper = format!(
+ "unsafe extern \"C\" fn {}(_test: *mut kernel::bindings::kunit) {{ {}(); }}",
+ kunit_wrapper_fn_name, test
+ );
+ let kunit_case = format!(
+ "static mut {}: kernel::bindings::kunit_case = kernel::kunit::kunit_case(kernel::c_str!(\"{}\"), {});",
+ kunit_case_name, test, kunit_wrapper_fn_name
+ );
+ writeln!(kunit_macros, "{kunit_wrapper}").unwrap();
+ writeln!(kunit_macros, "{kunit_case}").unwrap();
+ writeln!(test_cases, "{kunit_case_name},").unwrap();
+ }
+
+ writeln!(
+ kunit_macros,
+ "static mut KUNIT_CASE_NULL: kernel::bindings::kunit_case = kernel::kunit::kunit_case_null();"
+ )
+ .unwrap();
+
+ writeln!(
+ kunit_macros,
+ "static mut TEST_CASES : &mut[kernel::bindings::kunit_case] = unsafe {{ &mut[{test_cases} KUNIT_CASE_NULL] }};"
+ )
+ .unwrap();
+
+ writeln!(
+ kunit_macros,
+ "kernel::kunit_unsafe_test_suite!({attr}, TEST_CASES);"
+ )
+ .unwrap();
+
+ // Remove the `#[test]` macros.
+ // We do this at a token level, in order to preserve span information.
+ let mut new_body = vec![];
+ let mut body_it = body.stream().into_iter();
+
+ while let Some(token) = body_it.next() {
+ match token {
+ TokenTree::Punct(ref c) if c.as_char() == '#' => {
+ match body_it.next() {
+ Some(TokenTree::Group(group)) if group.to_string() == "[test]" => (),
+ Some(next) => { new_body.extend([token, next]); },
+ _ => { new_body.push(token); },
+ }
+ },
+ _ => { new_body.push(token); },
+ }
+ }
+
+ let mut new_body = TokenStream::from_iter(new_body);
+ new_body.extend::<TokenStream>(kunit_macros.parse().unwrap());
+
+ tokens.push(TokenTree::Group(Group::new(
+ Delimiter::Brace,
+ new_body
+ )));
+
+ tokens.into_iter().collect()
+}
diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs
index 4ab94e44adfe..beff19cc6d16 100644
--- a/rust/macros/lib.rs
+++ b/rust/macros/lib.rs
@@ -10,6 +10,7 @@
mod quote;
mod concat_idents;
mod helpers;
+mod kunit;
mod module;
mod paste;
mod pin_data;
@@ -492,3 +493,31 @@ pub fn paste(input: TokenStream) -> TokenStream {
pub fn derive_zeroable(input: TokenStream) -> TokenStream {
zeroable::derive(input)
}
+
+/// Registers a KUnit test suite and its test cases using a user-space like syntax.
+///
+/// This macro should be used on modules. If `CONFIG_KUNIT` (in `.config`) is `n`, the target module
+/// is ignored.
+///
+/// # Examples
+///
+/// ```ignore
+/// # use macros::kunit_tests;
+///
+/// #[kunit_tests(kunit_test_suit_name)]
+/// mod tests {
+/// #[test]
+/// fn foo() {
+/// assert_eq!(1, 1);
+/// }
+///
+/// #[test]
+/// fn bar() {
+/// assert_eq!(2, 2);
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn kunit_tests(attr: TokenStream, ts: TokenStream) -> TokenStream {
+ kunit::kunit_tests(attr, ts)
+}
--
2.47.1.613.gc27f4b7a9f-goog