1 // SPDX-License-Identifier: GPL-2.0 2 3 //! KUnit-based macros for Rust unit tests. 4 //! 5 //! C header: [`include/kunit/test.h`](../../../../../include/kunit/test.h) 6 //! 7 //! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html> 8 9 use 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)] 15 pub fn err(args: fmt::Arguments<'_>) { 16 // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we 17 // are passing. 18 #[cfg(CONFIG_PRINTK)] 19 unsafe { 20 bindings::_printk( 21 b"\x013%pA\0".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)] 31 pub fn info(args: fmt::Arguments<'_>) { 32 // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we 33 // are passing. 34 #[cfg(CONFIG_PRINTK)] 35 unsafe { 36 bindings::_printk( 37 b"\x016%pA\0".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 KUnit 48 /// facilities. See [`assert!`] for more details. 49 #[doc(hidden)] 50 #[macro_export] 51 macro_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 call 67 // KUnit, but at least print an error to the kernel log. This may happen if this 68 // macro is called from an spawned thread in a test (see 69 // `scripts/rustdoc_test_gen.rs`) or if some non-test code calls this macro by 70 // 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 $name 76 )); 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 to 93 // 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 to 97 // 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 from 113 // `kunit_get_current_test()` and it was not null. This means we are in a KUnit 114 // test, and that the pointer can be passed to KUnit functions and assertions. 115 // - The string pointers (`file` and `condition` above) point to null-terminated 116 // 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 stopping 121 // the thread, without running destructors. While that is problematic in itself, 122 // it is considered UB to have what is effectively a forced foreign unwind 123 // with `extern "C"` ABI. One could observe the stack that is now gone from 124 // 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 the 126 // next test runs, that test failures should be fixed and that KUnit is explicitly 127 // 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 only 140 // be called by the generated documentation tests which forward the test pointer given 141 // 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 KUnit 154 /// facilities. See [`assert!`] for more details. 155 #[doc(hidden)] 156 #[macro_export] 157 macro_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