rust/kernel/print.rs

   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 );