164 lines · rust
1// SPDX-License-Identifier: GPL-2.02 3//! KUnit-based macros for Rust unit tests.4//!5//! C header: [`include/kunit/test.h`](srctree/include/kunit/test.h)6//!7//! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>8 9use core::{ffi::c_void, fmt};10 11/// Prints a KUnit error-level message.12///13/// Public but hidden since it should only be used from KUnit generated code.14#[doc(hidden)]15pub fn err(args: fmt::Arguments<'_>) {16 // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we17 // are passing.18 #[cfg(CONFIG_PRINTK)]19 unsafe {20 bindings::_printk(21 c"\x013%pA".as_ptr() as _,22 &args as *const _ as *const c_void,23 );24 }25}26 27/// Prints a KUnit info-level message.28///29/// Public but hidden since it should only be used from KUnit generated code.30#[doc(hidden)]31pub fn info(args: fmt::Arguments<'_>) {32 // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we33 // are passing.34 #[cfg(CONFIG_PRINTK)]35 unsafe {36 bindings::_printk(37 c"\x016%pA".as_ptr() as _,38 &args as *const _ as *const c_void,39 );40 }41}42 43/// Asserts that a boolean expression is `true` at runtime.44///45/// Public but hidden since it should only be used from generated tests.46///47/// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit48/// facilities. See [`assert!`] for more details.49#[doc(hidden)]50#[macro_export]51macro_rules! kunit_assert {52 ($name:literal, $file:literal, $diff:expr, $condition:expr $(,)?) => {53 'out: {54 // Do nothing if the condition is `true`.55 if $condition {56 break 'out;57 }58 59 static FILE: &'static $crate::str::CStr = $crate::c_str!($file);60 static LINE: i32 = core::line!() as i32 - $diff;61 static CONDITION: &'static $crate::str::CStr = $crate::c_str!(stringify!($condition));62 63 // SAFETY: FFI call without safety requirements.64 let kunit_test = unsafe { $crate::bindings::kunit_get_current_test() };65 if kunit_test.is_null() {66 // The assertion failed but this task is not running a KUnit test, so we cannot call67 // KUnit, but at least print an error to the kernel log. This may happen if this68 // macro is called from an spawned thread in a test (see69 // `scripts/rustdoc_test_gen.rs`) or if some non-test code calls this macro by70 // mistake (it is hidden to prevent that).71 //72 // This mimics KUnit's failed assertion format.73 $crate::kunit::err(format_args!(74 " # {}: ASSERTION FAILED at {FILE}:{LINE}\n",75 $name76 ));77 $crate::kunit::err(format_args!(78 " Expected {CONDITION} to be true, but is false\n"79 ));80 $crate::kunit::err(format_args!(81 " Failure not reported to KUnit since this is a non-KUnit task\n"82 ));83 break 'out;84 }85 86 #[repr(transparent)]87 struct Location($crate::bindings::kunit_loc);88 89 #[repr(transparent)]90 struct UnaryAssert($crate::bindings::kunit_unary_assert);91 92 // SAFETY: There is only a static instance and in that one the pointer field points to93 // an immutable C string.94 unsafe impl Sync for Location {}95 96 // SAFETY: There is only a static instance and in that one the pointer field points to97 // an immutable C string.98 unsafe impl Sync for UnaryAssert {}99 100 static LOCATION: Location = Location($crate::bindings::kunit_loc {101 file: FILE.as_char_ptr(),102 line: LINE,103 });104 static ASSERTION: UnaryAssert = UnaryAssert($crate::bindings::kunit_unary_assert {105 assert: $crate::bindings::kunit_assert {},106 condition: CONDITION.as_char_ptr(),107 expected_true: true,108 });109 110 // SAFETY:111 // - FFI call.112 // - The `kunit_test` pointer is valid because we got it from113 // `kunit_get_current_test()` and it was not null. This means we are in a KUnit114 // test, and that the pointer can be passed to KUnit functions and assertions.115 // - The string pointers (`file` and `condition` above) point to null-terminated116 // strings since they are `CStr`s.117 // - The function pointer (`format`) points to the proper function.118 // - The pointers passed will remain valid since they point to `static`s.119 // - The format string is allowed to be null.120 // - There are, however, problems with this: first of all, this will end up stopping121 // the thread, without running destructors. While that is problematic in itself,122 // it is considered UB to have what is effectively a forced foreign unwind123 // with `extern "C"` ABI. One could observe the stack that is now gone from124 // another thread. We should avoid pinning stack variables to prevent library UB,125 // too. For the moment, given that test failures are reported immediately before the126 // next test runs, that test failures should be fixed and that KUnit is explicitly127 // documented as not suitable for production environments, we feel it is reasonable.128 unsafe {129 $crate::bindings::__kunit_do_failed_assertion(130 kunit_test,131 core::ptr::addr_of!(LOCATION.0),132 $crate::bindings::kunit_assert_type_KUNIT_ASSERTION,133 core::ptr::addr_of!(ASSERTION.0.assert),134 Some($crate::bindings::kunit_unary_assert_format),135 core::ptr::null(),136 );137 }138 139 // SAFETY: FFI call; the `test` pointer is valid because this hidden macro should only140 // be called by the generated documentation tests which forward the test pointer given141 // by KUnit.142 unsafe {143 $crate::bindings::__kunit_abort(kunit_test);144 }145 }146 };147}148 149/// Asserts that two expressions are equal to each other (using [`PartialEq`]).150///151/// Public but hidden since it should only be used from generated tests.152///153/// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit154/// facilities. See [`assert!`] for more details.155#[doc(hidden)]156#[macro_export]157macro_rules! kunit_assert_eq {158 ($name:literal, $file:literal, $diff:expr, $left:expr, $right:expr $(,)?) => {{159 // For the moment, we just forward to the expression assert because, for binary asserts,160 // KUnit supports only a few types (e.g. integers).161 $crate::kunit_assert!($name, $file, $diff, $left == $right);162 }};163}164