rust/kernel/kunit.rs

   1 // SPDX-License-Identifier: GPL-2.0
   2
   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
   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 }