projects/linux·blob v6.13 · refs

416 lines · 12.6 KiB

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