xref: /openbmc/linux/rust/kernel/kunit.rs (revision a66d733d)
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)]
err(args: fmt::Arguments<'_>)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)]
info(args: fmt::Arguments<'_>)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