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
  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 we
 17    // 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 we
 33    // 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 KUnit
 48/// 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 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]
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}