1 // SPDX-License-Identifier: GPL-2.0
3 //! Printing facilities.
5 //! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h)
7 //! Reference: <https://www.kernel.org/doc/html/latest/core-api/printk-basics.html>
10 ffi::{c_char, c_void},
14 use crate::str::RawFormatter;
19 // Called from `vsprintf` with format specifier `%pA`.
21 unsafe extern "C" fn rust_fmt_argument(
27 // SAFETY: The C contract guarantees that `buf` is valid if it's less than `end`.
28 let mut w = unsafe { RawFormatter::from_ptrs(buf.cast(), end.cast()) };
29 let _ = w.write_fmt(unsafe { *(ptr as *const fmt::Arguments<'_>) });
35 /// Public but hidden since it should only be used from public macros.
37 pub mod format_strings {
40 /// The length we copy from the `KERN_*` kernel prefixes.
41 const LENGTH_PREFIX: usize = 2;
43 /// The length of the fixed format strings.
44 pub const LENGTH: usize = 10;
46 /// Generates a fixed format string for the kernel's [`_printk`].
48 /// The format string is always the same for a given level, i.e. for a
49 /// given `prefix`, which are the kernel's `KERN_*` constants.
51 /// [`_printk`]: ../../../../include/linux/printk.h
52 const fn generate(is_cont: bool, prefix: &[u8; 3]) -> [u8; LENGTH] {
53 // Ensure the `KERN_*` macros are what we expect.
54 assert!(prefix[0] == b'\x01');
56 assert!(prefix[1] == b'c');
58 assert!(prefix[1] >= b'0' && prefix[1] <= b'7');
60 assert!(prefix[2] == b'\x00');
62 let suffix: &[u8; LENGTH - LENGTH_PREFIX] = if is_cont {
69 prefix[0], prefix[1], suffix[0], suffix[1], suffix[2], suffix[3], suffix[4], suffix[5],
74 // Generate the format strings at compile-time.
76 // This avoids the compiler generating the contents on the fly in the stack.
78 // Furthermore, `static` instead of `const` is used to share the strings
79 // for all the kernel.
80 pub static EMERG: [u8; LENGTH] = generate(false, bindings::KERN_EMERG);
81 pub static INFO: [u8; LENGTH] = generate(false, bindings::KERN_INFO);
84 /// Prints a message via the kernel's [`_printk`].
86 /// Public but hidden since it should only be used from public macros.
90 /// The format string must be one of the ones in [`format_strings`], and
91 /// the module name must be null-terminated.
93 /// [`_printk`]: ../../../../include/linux/_printk.h
95 #[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
96 pub unsafe fn call_printk(
97 format_string: &[u8; format_strings::LENGTH],
99 args: fmt::Arguments<'_>,
101 // `_printk` does not seem to fail in any path.
102 #[cfg(CONFIG_PRINTK)]
105 format_string.as_ptr() as _,
106 module_name.as_ptr(),
107 &args as *const _ as *const c_void,
112 /// Performs formatting and forwards the string to [`call_printk`].
114 /// Public but hidden since it should only be used from public macros.
118 #[allow(clippy::crate_in_macro_def)]
119 macro_rules! print_macro (
120 // The non-continuation cases (most of them, e.g. `INFO`).
121 ($format_string:path, $($arg:tt)+) => (
122 // To remain sound, `arg`s must be expanded outside the `unsafe` block.
123 // Typically one would use a `let` binding for that; however, `format_args!`
124 // takes borrows on the arguments, but does not extend the scope of temporaries.
125 // Therefore, a `match` expression is used to keep them around, since
126 // the scrutinee is kept until the end of the `match`.
127 match format_args!($($arg)+) {
128 // SAFETY: This hidden macro should only be called by the documented
129 // printing macros which ensure the format string is one of the fixed
130 // ones. All `__LOG_PREFIX`s are null-terminated as they are generated
131 // by the `module!` proc macro or fixed values defined in a kernel
134 $crate::print::call_printk(
144 /// Stub for doctests
147 macro_rules! print_macro (
148 ($format_string:path, $e:expr, $($arg:tt)+) => (
153 // We could use a macro to generate these macros. However, doing so ends
154 // up being a bit ugly: it requires the dollar token trick to escape `$` as
155 // well as playing with the `doc` attribute. Furthermore, they cannot be easily
156 // imported in the prelude due to [1]. So, for the moment, we just write them
157 // manually, like in the C side; while keeping most of the logic in another
158 // macro, i.e. [`print_macro`].
160 // [1]: https://github.com/rust-lang/rust/issues/52234
162 /// Prints an emergency-level message (level 0).
164 /// Use this level if the system is unusable.
166 /// Equivalent to the kernel's [`pr_emerg`] macro.
168 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
169 /// `alloc::format!` for information about the formatting syntax.
171 /// [`pr_emerg`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_emerg
172 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
177 /// pr_emerg!("hello {}\n", "there");
180 macro_rules! pr_emerg (
182 $crate::print_macro!($crate::print::format_strings::EMERG, $($arg)*)
186 /// Prints an info-level message (level 6).
188 /// Use this level for informational messages.
190 /// Equivalent to the kernel's [`pr_info`] macro.
192 /// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
193 /// `alloc::format!` for information about the formatting syntax.
195 /// [`pr_info`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_info
196 /// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
201 /// pr_info!("hello {}\n", "there");
204 #[doc(alias = "print")]
205 macro_rules! pr_info (
207 $crate::print_macro!($crate::print::format_strings::INFO, $($arg)*)