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