1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Printing facilities. 4 //! 5 //! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h) 6 //! 7 //! Reference: <https://www.kernel.org/doc/html/latest/core-api/printk-basics.html> 8 9 use core::{ 10 ffi::{c_char, c_void}, 11 fmt, 12 }; 13 14 use crate::str::RawFormatter; 15 16 #[cfg(CONFIG_PRINTK)] 17 use crate::bindings; 18 19 // Called from `vsprintf` with format specifier `%pA`. 20 #[no_mangle] 21 unsafe fn rust_fmt_argument(buf: *mut c_char, end: *mut c_char, ptr: *const c_void) -> *mut c_char { 22 use fmt::Write; 23 // SAFETY: The C contract guarantees that `buf` is valid if it's less than `end`. 24 let mut w = unsafe { RawFormatter::from_ptrs(buf.cast(), end.cast()) }; 25 let _ = w.write_fmt(unsafe { *(ptr as *const fmt::Arguments<'_>) }); 26 w.pos().cast() 27 } 28 29 /// Format strings. 30 /// 31 /// Public but hidden since it should only be used from public macros. 32 #[doc(hidden)] 33 pub mod format_strings { 34 use crate::bindings; 35 36 /// The length we copy from the `KERN_*` kernel prefixes. 37 const LENGTH_PREFIX: usize = 2; 38 39 /// The length of the fixed format strings. 40 pub const LENGTH: usize = 10; 41 42 /// Generates a fixed format string for the kernel's [`_printk`]. 43 /// 44 /// The format string is always the same for a given level, i.e. for a 45 /// given `prefix`, which are the kernel's `KERN_*` constants. 46 /// 47 /// [`_printk`]: ../../../../include/linux/printk.h 48 const fn generate(is_cont: bool, prefix: &[u8; 3]) -> [u8; LENGTH] { 49 // Ensure the `KERN_*` macros are what we expect. 50 assert!(prefix[0] == b'\x01'); 51 if is_cont { 52 assert!(prefix[1] == b'c'); 53 } else { 54 assert!(prefix[1] >= b'0' && prefix[1] <= b'7'); 55 } 56 assert!(prefix[2] == b'\x00'); 57 58 let suffix: &[u8; LENGTH - LENGTH_PREFIX] = if is_cont { 59 b"%pA\0\0\0\0\0" 60 } else { 61 b"%s: %pA\0" 62 }; 63 64 [ 65 prefix[0], prefix[1], suffix[0], suffix[1], suffix[2], suffix[3], suffix[4], suffix[5], 66 suffix[6], suffix[7], 67 ] 68 } 69 70 // Generate the format strings at compile-time. 71 // 72 // This avoids the compiler generating the contents on the fly in the stack. 73 // 74 // Furthermore, `static` instead of `const` is used to share the strings 75 // for all the kernel. 76 pub static EMERG: [u8; LENGTH] = generate(false, bindings::KERN_EMERG); 77 pub static ALERT: [u8; LENGTH] = generate(false, bindings::KERN_ALERT); 78 pub static CRIT: [u8; LENGTH] = generate(false, bindings::KERN_CRIT); 79 pub static ERR: [u8; LENGTH] = generate(false, bindings::KERN_ERR); 80 pub static WARNING: [u8; LENGTH] = generate(false, bindings::KERN_WARNING); 81 pub static NOTICE: [u8; LENGTH] = generate(false, bindings::KERN_NOTICE); 82 pub static INFO: [u8; LENGTH] = generate(false, bindings::KERN_INFO); 83 pub static DEBUG: [u8; LENGTH] = generate(false, bindings::KERN_DEBUG); 84 pub static CONT: [u8; LENGTH] = generate(true, bindings::KERN_CONT); 85 } 86 87 /// Prints a message via the kernel's [`_printk`]. 88 /// 89 /// Public but hidden since it should only be used from public macros. 90 /// 91 /// # Safety 92 /// 93 /// The format string must be one of the ones in [`format_strings`], and 94 /// the module name must be null-terminated. 95 /// 96 /// [`_printk`]: ../../../../include/linux/_printk.h 97 #[doc(hidden)] 98 #[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))] 99 pub unsafe fn call_printk( 100 format_string: &[u8; format_strings::LENGTH], 101 module_name: &[u8], 102 args: fmt::Arguments<'_>, 103 ) { 104 // `_printk` does not seem to fail in any path. 105 #[cfg(CONFIG_PRINTK)] 106 unsafe { 107 bindings::_printk( 108 format_string.as_ptr() as _, 109 module_name.as_ptr(), 110 &args as *const _ as *const c_void, 111 ); 112 } 113 } 114 115 /// Prints a message via the kernel's [`_printk`] for the `CONT` level. 116 /// 117 /// Public but hidden since it should only be used from public macros. 118 /// 119 /// [`_printk`]: ../../../../include/linux/printk.h 120 #[doc(hidden)] 121 #[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))] 122 pub fn call_printk_cont(args: fmt::Arguments<'_>) { 123 // `_printk` does not seem to fail in any path. 124 // 125 // SAFETY: The format string is fixed. 126 #[cfg(CONFIG_PRINTK)] 127 unsafe { 128 bindings::_printk( 129 format_strings::CONT.as_ptr() as _, 130 &args as *const _ as *const c_void, 131 ); 132 } 133 } 134 135 /// Performs formatting and forwards the string to [`call_printk`]. 136 /// 137 /// Public but hidden since it should only be used from public macros. 138 #[doc(hidden)] 139 #[cfg(not(testlib))] 140 #[macro_export] 141 #[allow(clippy::crate_in_macro_def)] 142 macro_rules! print_macro ( 143 // The non-continuation cases (most of them, e.g. `INFO`). 144 ($format_string:path, false, $($arg:tt)+) => ( 145 // To remain sound, `arg`s must be expanded outside the `unsafe` block. 146 // Typically one would use a `let` binding for that; however, `format_args!` 147 // takes borrows on the arguments, but does not extend the scope of temporaries. 148 // Therefore, a `match` expression is used to keep them around, since 149 // the scrutinee is kept until the end of the `match`. 150 match format_args!($($arg)+) { 151 // SAFETY: This hidden macro should only be called by the documented 152 // printing macros which ensure the format string is one of the fixed 153 // ones. All `__LOG_PREFIX`s are null-terminated as they are generated 154 // by the `module!` proc macro or fixed values defined in a kernel 155 // crate. 156 args => unsafe { 157 $crate::print::call_printk( 158 &$format_string, 159 crate::__LOG_PREFIX, 160 args, 161 ); 162 } 163 } 164 ); 165 166 // The `CONT` case. 167 ($format_string:path, true, $($arg:tt)+) => ( 168 $crate::print::call_printk_cont( 169 format_args!($($arg)+), 170 ); 171 ); 172 ); 173 174 /// Stub for doctests 175 #[cfg(testlib)] 176 #[macro_export] 177 macro_rules! print_macro ( 178 ($format_string:path, $e:expr, $($arg:tt)+) => ( 179 () 180 ); 181 ); 182 183 // We could use a macro to generate these macros. However, doing so ends 184 // up being a bit ugly: it requires the dollar token trick to escape `$` as 185 // well as playing with the `doc` attribute. Furthermore, they cannot be easily 186 // imported in the prelude due to [1]. So, for the moment, we just write them 187 // manually, like in the C side; while keeping most of the logic in another 188 // macro, i.e. [`print_macro`]. 189 // 190 // [1]: https://github.com/rust-lang/rust/issues/52234 191 192 /// Prints an emergency-level message (level 0). 193 /// 194 /// Use this level if the system is unusable. 195 /// 196 /// Equivalent to the kernel's [`pr_emerg`] macro. 197 /// 198 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and 199 /// `alloc::format!` for information about the formatting syntax. 200 /// 201 /// [`pr_emerg`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_emerg 202 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html 203 /// 204 /// # Examples 205 /// 206 /// ``` 207 /// pr_emerg!("hello {}\n", "there"); 208 /// ``` 209 #[macro_export] 210 macro_rules! pr_emerg ( 211 ($($arg:tt)*) => ( 212 $crate::print_macro!($crate::print::format_strings::EMERG, false, $($arg)*) 213 ) 214 ); 215 216 /// Prints an alert-level message (level 1). 217 /// 218 /// Use this level if action must be taken immediately. 219 /// 220 /// Equivalent to the kernel's [`pr_alert`] macro. 221 /// 222 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and 223 /// `alloc::format!` for information about the formatting syntax. 224 /// 225 /// [`pr_alert`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_alert 226 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html 227 /// 228 /// # Examples 229 /// 230 /// ``` 231 /// pr_alert!("hello {}\n", "there"); 232 /// ``` 233 #[macro_export] 234 macro_rules! pr_alert ( 235 ($($arg:tt)*) => ( 236 $crate::print_macro!($crate::print::format_strings::ALERT, false, $($arg)*) 237 ) 238 ); 239 240 /// Prints a critical-level message (level 2). 241 /// 242 /// Use this level for critical conditions. 243 /// 244 /// Equivalent to the kernel's [`pr_crit`] macro. 245 /// 246 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and 247 /// `alloc::format!` for information about the formatting syntax. 248 /// 249 /// [`pr_crit`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_crit 250 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html 251 /// 252 /// # Examples 253 /// 254 /// ``` 255 /// pr_crit!("hello {}\n", "there"); 256 /// ``` 257 #[macro_export] 258 macro_rules! pr_crit ( 259 ($($arg:tt)*) => ( 260 $crate::print_macro!($crate::print::format_strings::CRIT, false, $($arg)*) 261 ) 262 ); 263 264 /// Prints an error-level message (level 3). 265 /// 266 /// Use this level for error conditions. 267 /// 268 /// Equivalent to the kernel's [`pr_err`] macro. 269 /// 270 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and 271 /// `alloc::format!` for information about the formatting syntax. 272 /// 273 /// [`pr_err`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_err 274 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html 275 /// 276 /// # Examples 277 /// 278 /// ``` 279 /// pr_err!("hello {}\n", "there"); 280 /// ``` 281 #[macro_export] 282 macro_rules! pr_err ( 283 ($($arg:tt)*) => ( 284 $crate::print_macro!($crate::print::format_strings::ERR, false, $($arg)*) 285 ) 286 ); 287 288 /// Prints a warning-level message (level 4). 289 /// 290 /// Use this level for warning conditions. 291 /// 292 /// Equivalent to the kernel's [`pr_warn`] macro. 293 /// 294 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and 295 /// `alloc::format!` for information about the formatting syntax. 296 /// 297 /// [`pr_warn`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_warn 298 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html 299 /// 300 /// # Examples 301 /// 302 /// ``` 303 /// pr_warn!("hello {}\n", "there"); 304 /// ``` 305 #[macro_export] 306 macro_rules! pr_warn ( 307 ($($arg:tt)*) => ( 308 $crate::print_macro!($crate::print::format_strings::WARNING, false, $($arg)*) 309 ) 310 ); 311 312 /// Prints a notice-level message (level 5). 313 /// 314 /// Use this level for normal but significant conditions. 315 /// 316 /// Equivalent to the kernel's [`pr_notice`] macro. 317 /// 318 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and 319 /// `alloc::format!` for information about the formatting syntax. 320 /// 321 /// [`pr_notice`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_notice 322 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html 323 /// 324 /// # Examples 325 /// 326 /// ``` 327 /// pr_notice!("hello {}\n", "there"); 328 /// ``` 329 #[macro_export] 330 macro_rules! pr_notice ( 331 ($($arg:tt)*) => ( 332 $crate::print_macro!($crate::print::format_strings::NOTICE, false, $($arg)*) 333 ) 334 ); 335 336 /// Prints an info-level message (level 6). 337 /// 338 /// Use this level for informational messages. 339 /// 340 /// Equivalent to the kernel's [`pr_info`] macro. 341 /// 342 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and 343 /// `alloc::format!` for information about the formatting syntax. 344 /// 345 /// [`pr_info`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_info 346 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html 347 /// 348 /// # Examples 349 /// 350 /// ``` 351 /// pr_info!("hello {}\n", "there"); 352 /// ``` 353 #[macro_export] 354 #[doc(alias = "print")] 355 macro_rules! pr_info ( 356 ($($arg:tt)*) => ( 357 $crate::print_macro!($crate::print::format_strings::INFO, false, $($arg)*) 358 ) 359 ); 360 361 /// Prints a debug-level message (level 7). 362 /// 363 /// Use this level for debug messages. 364 /// 365 /// Equivalent to the kernel's [`pr_debug`] macro, except that it doesn't support dynamic debug 366 /// yet. 367 /// 368 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and 369 /// `alloc::format!` for information about the formatting syntax. 370 /// 371 /// [`pr_debug`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_debug 372 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html 373 /// 374 /// # Examples 375 /// 376 /// ``` 377 /// pr_debug!("hello {}\n", "there"); 378 /// ``` 379 #[macro_export] 380 #[doc(alias = "print")] 381 macro_rules! pr_debug ( 382 ($($arg:tt)*) => ( 383 if cfg!(debug_assertions) { 384 $crate::print_macro!($crate::print::format_strings::DEBUG, false, $($arg)*) 385 } 386 ) 387 ); 388 389 /// Continues a previous log message in the same line. 390 /// 391 /// Use only when continuing a previous `pr_*!` macro (e.g. [`pr_info!`]). 392 /// 393 /// Equivalent to the kernel's [`pr_cont`] macro. 394 /// 395 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and 396 /// `alloc::format!` for information about the formatting syntax. 397 /// 398 /// [`pr_cont`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_cont 399 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html 400 /// 401 /// # Examples 402 /// 403 /// ``` 404 /// # use kernel::pr_cont; 405 /// pr_info!("hello"); 406 /// pr_cont!(" {}\n", "there"); 407 /// ``` 408 #[macro_export] 409 macro_rules! pr_cont ( 410 ($($arg:tt)*) => ( 411 $crate::print_macro!($crate::print::format_strings::CONT, true, $($arg)*) 412 ) 413 ); 414