Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354// SPDX-License-Identifier: GPL-2.0
//! KUnit-based macros for Rust unit tests.//!//! C header: [`include/kunit/test.h`](srctree/include/kunit/test.h)//!//! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>
use crate::fmt;use crate::prelude::*;
/// Prints a KUnit error-level message.////// Public but hidden since it should only be used from KUnit generated code.#[doc(hidden)]pub fn err(args: fmt::Arguments<'_>) { // `args` is unused if `CONFIG_PRINTK` is not set - this avoids a build-time warning. #[cfg(not(CONFIG_PRINTK))] let _ = args;
// SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we // are passing. #[cfg(CONFIG_PRINTK)] unsafe { bindings::_printk( c"\x013%pA".as_char_ptr(), core::ptr::from_ref(&args).cast::<c_void>(), ); }}
/// Prints a KUnit info-level message.////// Public but hidden since it should only be used from KUnit generated code.#[doc(hidden)]pub fn info(args: fmt::Arguments<'_>) { // `args` is unused if `CONFIG_PRINTK` is not set - this avoids a build-time warning. #[cfg(not(CONFIG_PRINTK))] let _ = args;
// SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we // are passing. #[cfg(CONFIG_PRINTK)] unsafe { bindings::_printk( c"\x016%pA".as_char_ptr(), core::ptr::from_ref(&args).cast::<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, $file:literal, $diff:expr, $condition:expr $(,)?) => { 'out: { // Do nothing if the condition is `true`. if $condition { break 'out; }
static FILE: &'static $crate::str::CStr = $file; static LINE: i32 = ::core::line!() as i32 - $diff; 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($crate::prelude::fmt!( " # {}: ASSERTION FAILED at {FILE}:{LINE}\n", $name )); $crate::kunit::err($crate::prelude::fmt!( " Expected {CONDITION} to be true, but is false\n" )); $crate::kunit::err($crate::prelude::fmt!( " 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: $crate::str::as_char_ptr_in_const_context(FILE), line: LINE, }); static ASSERTION: UnaryAssert = UnaryAssert($crate::bindings::kunit_unary_assert { assert: $crate::bindings::kunit_assert {}, condition: $crate::str::as_char_ptr_in_const_context(CONDITION), 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(), ); }
// SAFETY: FFI call; the `test` pointer is valid because this hidden macro should only // be called by the generated documentation tests which forward the test pointer given // by KUnit. unsafe { $crate::bindings::__kunit_abort(kunit_test); } } };}
/// 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, $file:literal, $diff: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, $file, $diff, $left == $right); }};}
trait TestResult { fn is_test_result_ok(&self) -> bool;}
impl TestResult for () { fn is_test_result_ok(&self) -> bool { true }}
impl<T, E> TestResult for Result<T, E> { fn is_test_result_ok(&self) -> bool { self.is_ok() }}
/// Returns whether a test result is to be considered OK.////// This will be `assert!`ed from the generated tests.#[doc(hidden)]#[expect(private_bounds)]pub fn is_test_result_ok(t: impl TestResult) -> bool { t.is_test_result_ok()}
/// Represents an individual test case.#[doc(hidden)]pub const fn kunit_case( name: &'static kernel::str::CStr, run_case: unsafe extern "C" fn(*mut kernel::bindings::kunit),) -> kernel::bindings::kunit_case { kernel::bindings::kunit_case { run_case: Some(run_case), name: kernel::str::as_char_ptr_in_const_context(name), attr: kernel::bindings::kunit_attributes { speed: kernel::bindings::kunit_speed_KUNIT_SPEED_NORMAL, }, generate_params: None, status: kernel::bindings::kunit_status_KUNIT_SUCCESS, module_name: core::ptr::null_mut(), log: core::ptr::null_mut(), param_init: None, param_exit: None, }}
/// Registers a KUnit test suite.////// # Safety////// `test_cases` must be a `NULL` terminated array of valid test cases,/// whose lifetime is at least that of the test suite (i.e., static).////// # Examples////// ```ignore/// extern "C" fn test_fn(_test: *mut kernel::bindings::kunit) {/// let actual = 1 + 1;/// let expected = 2;/// assert_eq!(actual, expected);/// }////// static mut KUNIT_TEST_CASES: [kernel::bindings::kunit_case; 2] = [/// kernel::kunit::kunit_case(c"name", test_fn),/// pin_init::zeroed(),/// ];/// kernel::kunit_unsafe_test_suite!(suite_name, KUNIT_TEST_CASES);/// ```#[doc(hidden)]#[macro_export]macro_rules! kunit_unsafe_test_suite { ($name:ident, $test_cases:ident) => { const _: () = { const KUNIT_TEST_SUITE_NAME: [::kernel::ffi::c_char; 256] = { let name_u8 = ::core::stringify!($name).as_bytes(); let mut ret = [0; 256];
if name_u8.len() > 255 { panic!(concat!( "The test suite name `", ::core::stringify!($name), "` exceeds the maximum length of 255 bytes." )); }
let mut i = 0; while i < name_u8.len() { ret[i] = name_u8[i] as ::kernel::ffi::c_char; i += 1; }
ret };
static mut KUNIT_TEST_SUITE: ::kernel::bindings::kunit_suite = ::kernel::bindings::kunit_suite { name: KUNIT_TEST_SUITE_NAME, #[allow(unused_unsafe)] // SAFETY: `$test_cases` is passed in by the user, and // (as documented) must be valid for the lifetime of // the suite (i.e., static). test_cases: unsafe { ::core::ptr::addr_of_mut!($test_cases) .cast::<::kernel::bindings::kunit_case>() }, suite_init: None, suite_exit: None, init: None, exit: None, attr: ::kernel::bindings::kunit_attributes { speed: ::kernel::bindings::kunit_speed_KUNIT_SPEED_NORMAL, }, status_comment: [0; 256usize], debugfs: ::core::ptr::null_mut(), log: ::core::ptr::null_mut(), suite_init_err: 0, is_init: false, };
#[used(compiler)] #[allow(unused_unsafe)] #[cfg_attr(not(target_os = "macos"), link_section = ".kunit_test_suites")] static mut KUNIT_TEST_SUITE_ENTRY: *const ::kernel::bindings::kunit_suite = // SAFETY: `KUNIT_TEST_SUITE` is static. unsafe { ::core::ptr::addr_of_mut!(KUNIT_TEST_SUITE) }; }; };}
/// Returns whether we are currently running a KUnit test.////// In some cases, you need to call test-only code from outside the test case, for example, to/// create a function mock. This function allows to change behavior depending on whether we are/// currently running a KUnit test or not.////// # Examples////// This example shows how a function can be mocked to return a well-known value while testing:////// ```/// # use kernel::kunit::in_kunit_test;/// fn fn_mock_example(n: i32) -> i32 {/// if in_kunit_test() {/// return 100;/// }////// n + 1/// }////// let mock_res = fn_mock_example(5);/// assert_eq!(mock_res, 100);/// ```pub fn in_kunit_test() -> bool { // SAFETY: `kunit_get_current_test()` is always safe to call (it has fallbacks for // when KUnit is not enabled). !unsafe { bindings::kunit_get_current_test() }.is_null()}
#[cfg(CONFIG_RUST_KUNIT_SELFTEST)]#[kunit_tests(rust_kernel_kunit)]mod tests { use super::*;
#[test] fn rust_test_kunit_example_test() { assert_eq!(1 + 1, 2); }
#[test] fn rust_test_kunit_in_kunit_test() { assert!(in_kunit_test()); }
#[test] #[cfg(not(all()))] fn rust_test_kunit_always_disabled_test() { // This test should never run because of the `cfg`. assert!(false); }}