kernel/
print.rs

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
9use crate::{
10    ffi::{c_char, c_void},
11    str::RawFormatter,
12};
13use core::fmt;
14
15// Called from `vsprintf` with format specifier `%pA`.
16#[expect(clippy::missing_safety_doc)]
17#[no_mangle]
18unsafe 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)]
35pub 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))]
99pub 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(),
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))]
123pub 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(),
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#[expect(clippy::crate_in_macro_def)]
143macro_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]
178macro_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]
211macro_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]
235macro_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]
259macro_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]
283macro_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]
307macro_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]
331macro_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")]
356macro_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")]
382macro_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]
411macro_rules! pr_cont (
412    ($($arg:tt)*) => (
413        $crate::print_macro!($crate::print::format_strings::CONT, true, $($arg)*)
414    )
415);