1 // SPDX-License-Identifier: Apache-2.0 OR MIT 2 3 //! Rust standard library vendored code. 4 //! 5 //! The contents of this file come from the Rust standard library, hosted in 6 //! the <https://github.com/rust-lang/rust> repository, licensed under 7 //! "Apache-2.0 OR MIT" and adapted for kernel use. For copyright details, 8 //! see <https://github.com/rust-lang/rust/blob/master/COPYRIGHT>. 9 10 /// [`std::dbg`], but using [`pr_info`] instead of [`eprintln`]. 11 /// 12 /// Prints and returns the value of a given expression for quick and dirty 13 /// debugging. 14 /// 15 /// An example: 16 /// 17 /// ```rust 18 /// let a = 2; 19 /// # #[expect(clippy::disallowed_macros)] 20 /// let b = dbg!(a * 2) + 1; 21 /// // ^-- prints: [src/main.rs:3:9] a * 2 = 4 22 /// assert_eq!(b, 5); 23 /// ``` 24 /// 25 /// The macro works by using the `Debug` implementation of the type of 26 /// the given expression to print the value with [`printk`] along with the 27 /// source location of the macro invocation as well as the source code 28 /// of the expression. 29 /// 30 /// Invoking the macro on an expression moves and takes ownership of it 31 /// before returning the evaluated expression unchanged. If the type 32 /// of the expression does not implement `Copy` and you don't want 33 /// to give up ownership, you can instead borrow with `dbg!(&expr)` 34 /// for some expression `expr`. 35 /// 36 /// The `dbg!` macro works exactly the same in release builds. 37 /// This is useful when debugging issues that only occur in release 38 /// builds or when debugging in release mode is significantly faster. 39 /// 40 /// Note that the macro is intended as a temporary debugging tool to be 41 /// used during development. Therefore, avoid committing `dbg!` macro 42 /// invocations into the kernel tree. 43 /// 44 /// For debug output that is intended to be kept in the kernel tree, 45 /// use [`pr_debug`] and similar facilities instead. 46 /// 47 /// # Stability 48 /// 49 /// The exact output printed by this macro should not be relied upon 50 /// and is subject to future changes. 51 /// 52 /// # Further examples 53 /// 54 /// With a method call: 55 /// 56 /// ```rust 57 /// # #[expect(clippy::disallowed_macros)] 58 /// fn foo(n: usize) { 59 /// if dbg!(n.checked_sub(4)).is_some() { 60 /// // ... 61 /// } 62 /// } 63 /// 64 /// foo(3) 65 /// ``` 66 /// 67 /// This prints to the kernel log: 68 /// 69 /// ```text,ignore 70 /// [src/main.rs:3:8] n.checked_sub(4) = None 71 /// ``` 72 /// 73 /// Naive factorial implementation: 74 /// 75 /// ```rust 76 /// # #![expect(clippy::disallowed_macros)] 77 /// fn factorial(n: u32) -> u32 { 78 /// if dbg!(n <= 1) { 79 /// dbg!(1) 80 /// } else { 81 /// dbg!(n * factorial(n - 1)) 82 /// } 83 /// } 84 /// 85 /// dbg!(factorial(4)); 86 /// ``` 87 /// 88 /// This prints to the kernel log: 89 /// 90 /// ```text,ignore 91 /// [src/main.rs:3:8] n <= 1 = false 92 /// [src/main.rs:3:8] n <= 1 = false 93 /// [src/main.rs:3:8] n <= 1 = false 94 /// [src/main.rs:3:8] n <= 1 = true 95 /// [src/main.rs:4:9] 1 = 1 96 /// [src/main.rs:5:9] n * factorial(n - 1) = 2 97 /// [src/main.rs:5:9] n * factorial(n - 1) = 6 98 /// [src/main.rs:5:9] n * factorial(n - 1) = 24 99 /// [src/main.rs:11:1] factorial(4) = 24 100 /// ``` 101 /// 102 /// The `dbg!(..)` macro moves the input: 103 /// 104 /// ```ignore 105 /// /// A wrapper around `usize` which importantly is not Copyable. 106 /// #[derive(Debug)] 107 /// struct NoCopy(usize); 108 /// 109 /// let a = NoCopy(42); 110 /// let _ = dbg!(a); // <-- `a` is moved here. 111 /// let _ = dbg!(a); // <-- `a` is moved again; error! 112 /// ``` 113 /// 114 /// You can also use `dbg!()` without a value to just print the 115 /// file and line whenever it's reached. 116 /// 117 /// Finally, if you want to `dbg!(..)` multiple values, it will treat them as 118 /// a tuple (and return it, too): 119 /// 120 /// ``` 121 /// # #![expect(clippy::disallowed_macros)] 122 /// assert_eq!(dbg!(1usize, 2u32), (1, 2)); 123 /// ``` 124 /// 125 /// However, a single argument with a trailing comma will still not be treated 126 /// as a tuple, following the convention of ignoring trailing commas in macro 127 /// invocations. You can use a 1-tuple directly if you need one: 128 /// 129 /// ``` 130 /// # #![expect(clippy::disallowed_macros)] 131 /// assert_eq!(1, dbg!(1u32,)); // trailing comma ignored 132 /// assert_eq!((1,), dbg!((1u32,))); // 1-tuple 133 /// ``` 134 /// 135 /// [`std::dbg`]: https://doc.rust-lang.org/std/macro.dbg.html 136 /// [`eprintln`]: https://doc.rust-lang.org/std/macro.eprintln.html 137 /// [`printk`]: https://docs.kernel.org/core-api/printk-basics.html 138 /// [`pr_info`]: crate::pr_info! 139 /// [`pr_debug`]: crate::pr_debug! 140 #[macro_export] 141 macro_rules! dbg { 142 // NOTE: We cannot use `concat!` to make a static string as a format argument 143 // of `pr_info!` because `file!` could contain a `{` or 144 // `$val` expression could be a block (`{ .. }`), in which case the `pr_info!` 145 // will be malformed. 146 () => { 147 $crate::pr_info!("[{}:{}:{}]\n", ::core::file!(), ::core::line!(), ::core::column!()) 148 }; 149 ($val:expr $(,)?) => { 150 // Use of `match` here is intentional because it affects the lifetimes 151 // of temporaries - https://stackoverflow.com/a/48732525/1063961 152 match $val { 153 tmp => { 154 $crate::pr_info!("[{}:{}:{}] {} = {:#?}\n", 155 ::core::file!(), ::core::line!(), ::core::column!(), 156 ::core::stringify!($val), &tmp); 157 tmp 158 } 159 } 160 }; 161 ($($val:expr),+ $(,)?) => { 162 ($($crate::dbg!($val)),+,) 163 }; 164 } 165