projects/linux·blob master · refs

578 lines · 17.4 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 crate::{
10 ffi::{c_char, c_void},
11 fmt,
12 prelude::*,
13 str::RawFormatter,
14 sync::atomic::{
15 Atomic,
16 AtomicType,
17 Relaxed, //
18 },
19};
20
21// Called from `vsprintf` with format specifier `%pA`.
22#[expect(clippy::missing_safety_doc)]
23#[export]
24unsafe extern "C" fn rust_fmt_argument(
25 buf: *mut c_char,
26 end: *mut c_char,
27 ptr: *const c_void,
28) -> *mut c_char {
29 use fmt::Write;
30 // SAFETY: The C contract guarantees that `buf` is valid if it's less than `end`.
31 let mut w = unsafe { RawFormatter::from_ptrs(buf.cast(), end.cast()) };
32 // SAFETY: TODO.
33 let _ = w.write_fmt(unsafe { *ptr.cast::<fmt::Arguments<'_>>() });
34 w.pos().cast()
35}
36
37/// Format strings.
38///
39/// Public but hidden since it should only be used from public macros.
40#[doc(hidden)]
41pub mod format_strings {
42 /// The length we copy from the `KERN_*` kernel prefixes.
43 const LENGTH_PREFIX: usize = 2;
44
45 /// The length of the fixed format strings.
46 pub const LENGTH: usize = 10;
47
48 /// Generates a fixed format string for the kernel's [`_printk`].
49 ///
50 /// The format string is always the same for a given level, i.e. for a
51 /// given `prefix`, which are the kernel's `KERN_*` constants.
52 ///
53 /// [`_printk`]: srctree/include/linux/printk.h
54 const fn generate(is_cont: bool, prefix: &[u8; 3]) -> [u8; LENGTH] {
55 // Ensure the `KERN_*` macros are what we expect.
56 assert!(prefix[0] == b'\x01');
57 if is_cont {
58 assert!(prefix[1] == b'c');
59 } else {
60 assert!(prefix[1] >= b'0' && prefix[1] <= b'7');
61 }
62 assert!(prefix[2] == b'\x00');
63
64 let suffix: &[u8; LENGTH - LENGTH_PREFIX] = if is_cont {
65 b"%pA\0\0\0\0\0"
66 } else {
67 b"%s: %pA\0"
68 };
69
70 [
71 prefix[0], prefix[1], suffix[0], suffix[1], suffix[2], suffix[3], suffix[4], suffix[5],
72 suffix[6], suffix[7],
73 ]
74 }
75
76 // Generate the format strings at compile-time.
77 //
78 // This avoids the compiler generating the contents on the fly in the stack.
79 //
80 // Furthermore, `static` instead of `const` is used to share the strings
81 // for all the kernel.
82 pub static EMERG: [u8; LENGTH] = generate(false, bindings::KERN_EMERG);
83 pub static ALERT: [u8; LENGTH] = generate(false, bindings::KERN_ALERT);
84 pub static CRIT: [u8; LENGTH] = generate(false, bindings::KERN_CRIT);
85 pub static ERR: [u8; LENGTH] = generate(false, bindings::KERN_ERR);
86 pub static WARNING: [u8; LENGTH] = generate(false, bindings::KERN_WARNING);
87 pub static NOTICE: [u8; LENGTH] = generate(false, bindings::KERN_NOTICE);
88 pub static INFO: [u8; LENGTH] = generate(false, bindings::KERN_INFO);
89 pub static DEBUG: [u8; LENGTH] = generate(false, bindings::KERN_DEBUG);
90 pub static CONT: [u8; LENGTH] = generate(true, bindings::KERN_CONT);
91}
92
93/// Prints a message via the kernel's [`_printk`].
94///
95/// Public but hidden since it should only be used from public macros.
96///
97/// # Safety
98///
99/// The format string must be one of the ones in [`format_strings`], and
100/// the module name must be null-terminated.
101///
102/// [`_printk`]: srctree/include/linux/printk.h
103#[doc(hidden)]
104#[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
105pub unsafe fn call_printk(
106 format_string: &[u8; format_strings::LENGTH],
107 module_name: &[u8],
108 args: fmt::Arguments<'_>,
109) {
110 // `_printk` does not seem to fail in any path.
111 #[cfg(CONFIG_PRINTK)]
112 // SAFETY: TODO.
113 unsafe {
114 bindings::_printk(
115 format_string.as_ptr(),
116 module_name.as_ptr(),
117 core::ptr::from_ref(&args).cast::<c_void>(),
118 );
119 }
120}
121
122/// Prints a message via the kernel's [`_printk`] for the `CONT` level.
123///
124/// Public but hidden since it should only be used from public macros.
125///
126/// [`_printk`]: srctree/include/linux/printk.h
127#[doc(hidden)]
128#[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
129pub fn call_printk_cont(args: fmt::Arguments<'_>) {
130 // `_printk` does not seem to fail in any path.
131 //
132 // SAFETY: The format string is fixed.
133 #[cfg(CONFIG_PRINTK)]
134 unsafe {
135 bindings::_printk(
136 format_strings::CONT.as_ptr(),
137 core::ptr::from_ref(&args).cast::<c_void>(),
138 );
139 }
140}
141
142/// Performs formatting and forwards the string to [`call_printk`].
143///
144/// Public but hidden since it should only be used from public macros.
145#[doc(hidden)]
146#[cfg(not(testlib))]
147#[macro_export]
148#[expect(clippy::crate_in_macro_def)]
149macro_rules! print_macro (
150 // The non-continuation cases (most of them, e.g. `INFO`).
151 ($format_string:path, false, $($arg:tt)+) => (
152 // To remain sound, `arg`s must be expanded outside the `unsafe` block.
153 // Typically one would use a `let` binding for that; however, `format_args!`
154 // takes borrows on the arguments, but does not extend the scope of temporaries.
155 // Therefore, a `match` expression is used to keep them around, since
156 // the scrutinee is kept until the end of the `match`.
157 match $crate::prelude::fmt!($($arg)+) {
158 // SAFETY: This hidden macro should only be called by the documented
159 // printing macros which ensure the format string is one of the fixed
160 // ones. All `__LOG_PREFIX`s are null-terminated as they are generated
161 // by the `module!` proc macro or fixed values defined in a kernel
162 // crate.
163 args => unsafe {
164 $crate::print::call_printk(
165 &$format_string,
166 crate::__LOG_PREFIX,
167 args,
168 );
169 }
170 }
171 );
172
173 // The `CONT` case.
174 ($format_string:path, true, $($arg:tt)+) => (
175 $crate::print::call_printk_cont(
176 $crate::prelude::fmt!($($arg)+),
177 );
178 );
179);
180
181/// Stub for doctests
182#[cfg(testlib)]
183#[macro_export]
184macro_rules! print_macro (
185 ($format_string:path, $e:expr, $($arg:tt)+) => (
186 ()
187 );
188);
189
190// We could use a macro to generate these macros. However, doing so ends
191// up being a bit ugly: it requires the dollar token trick to escape `$` as
192// well as playing with the `doc` attribute. Furthermore, they cannot be easily
193// imported in the prelude due to [1]. So, for the moment, we just write them
194// manually, like in the C side; while keeping most of the logic in another
195// macro, i.e. [`print_macro`].
196//
197// [1]: https://github.com/rust-lang/rust/issues/52234
198
199/// Prints an emergency-level message (level 0).
200///
201/// Use this level if the system is unusable.
202///
203/// Equivalent to the kernel's [`pr_emerg`] macro.
204///
205/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
206/// [`std::format!`] for information about the formatting syntax.
207///
208/// [`pr_emerg`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_emerg
209/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
210/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
211///
212/// # Examples
213///
214/// ```
215/// pr_emerg!("hello {}\n", "there");
216/// ```
217#[macro_export]
218macro_rules! pr_emerg (
219 ($($arg:tt)*) => (
220 $crate::print_macro!($crate::print::format_strings::EMERG, false, $($arg)*)
221 )
222);
223
224/// Prints an alert-level message (level 1).
225///
226/// Use this level if action must be taken immediately.
227///
228/// Equivalent to the kernel's [`pr_alert`] macro.
229///
230/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
231/// [`std::format!`] for information about the formatting syntax.
232///
233/// [`pr_alert`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_alert
234/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
235/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
236///
237/// # Examples
238///
239/// ```
240/// pr_alert!("hello {}\n", "there");
241/// ```
242#[macro_export]
243macro_rules! pr_alert (
244 ($($arg:tt)*) => (
245 $crate::print_macro!($crate::print::format_strings::ALERT, false, $($arg)*)
246 )
247);
248
249/// Prints a critical-level message (level 2).
250///
251/// Use this level for critical conditions.
252///
253/// Equivalent to the kernel's [`pr_crit`] macro.
254///
255/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
256/// [`std::format!`] for information about the formatting syntax.
257///
258/// [`pr_crit`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_crit
259/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
260/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
261///
262/// # Examples
263///
264/// ```
265/// pr_crit!("hello {}\n", "there");
266/// ```
267#[macro_export]
268macro_rules! pr_crit (
269 ($($arg:tt)*) => (
270 $crate::print_macro!($crate::print::format_strings::CRIT, false, $($arg)*)
271 )
272);
273
274/// Prints an error-level message (level 3).
275///
276/// Use this level for error conditions.
277///
278/// Equivalent to the kernel's [`pr_err`] macro.
279///
280/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
281/// [`std::format!`] for information about the formatting syntax.
282///
283/// [`pr_err`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_err
284/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
285/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
286///
287/// # Examples
288///
289/// ```
290/// pr_err!("hello {}\n", "there");
291/// ```
292#[macro_export]
293macro_rules! pr_err (
294 ($($arg:tt)*) => (
295 $crate::print_macro!($crate::print::format_strings::ERR, false, $($arg)*)
296 )
297);
298
299/// Prints a warning-level message (level 4).
300///
301/// Use this level for warning conditions.
302///
303/// Equivalent to the kernel's [`pr_warn`] macro.
304///
305/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
306/// [`std::format!`] for information about the formatting syntax.
307///
308/// [`pr_warn`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_warn
309/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
310/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
311///
312/// # Examples
313///
314/// ```
315/// pr_warn!("hello {}\n", "there");
316/// ```
317#[macro_export]
318macro_rules! pr_warn (
319 ($($arg:tt)*) => (
320 $crate::print_macro!($crate::print::format_strings::WARNING, false, $($arg)*)
321 )
322);
323
324/// Prints a notice-level message (level 5).
325///
326/// Use this level for normal but significant conditions.
327///
328/// Equivalent to the kernel's [`pr_notice`] macro.
329///
330/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
331/// [`std::format!`] for information about the formatting syntax.
332///
333/// [`pr_notice`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_notice
334/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
335/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
336///
337/// # Examples
338///
339/// ```
340/// pr_notice!("hello {}\n", "there");
341/// ```
342#[macro_export]
343macro_rules! pr_notice (
344 ($($arg:tt)*) => (
345 $crate::print_macro!($crate::print::format_strings::NOTICE, false, $($arg)*)
346 )
347);
348
349/// Prints an info-level message (level 6).
350///
351/// Use this level for informational messages.
352///
353/// Equivalent to the kernel's [`pr_info`] macro.
354///
355/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
356/// [`std::format!`] for information about the formatting syntax.
357///
358/// [`pr_info`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_info
359/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
360/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
361///
362/// # Examples
363///
364/// ```
365/// pr_info!("hello {}\n", "there");
366/// ```
367#[macro_export]
368#[doc(alias = "print")]
369macro_rules! pr_info (
370 ($($arg:tt)*) => (
371 $crate::print_macro!($crate::print::format_strings::INFO, false, $($arg)*)
372 )
373);
374
375/// Prints a debug-level message (level 7).
376///
377/// Use this level for debug messages.
378///
379/// Equivalent to the kernel's [`pr_debug`] macro, except that it doesn't support dynamic debug
380/// yet.
381///
382/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
383/// [`std::format!`] for information about the formatting syntax.
384///
385/// [`pr_debug`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_debug
386/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
387/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
388///
389/// # Examples
390///
391/// ```
392/// pr_debug!("hello {}\n", "there");
393/// ```
394#[macro_export]
395#[doc(alias = "print")]
396macro_rules! pr_debug (
397 ($($arg:tt)*) => (
398 if cfg!(debug_assertions) {
399 $crate::print_macro!($crate::print::format_strings::DEBUG, false, $($arg)*)
400 }
401 )
402);
403
404/// Continues a previous log message in the same line.
405///
406/// Use only when continuing a previous `pr_*!` macro (e.g. [`pr_info!`]).
407///
408/// Equivalent to the kernel's [`pr_cont`] macro.
409///
410/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
411/// [`std::format!`] for information about the formatting syntax.
412///
413/// [`pr_info!`]: crate::pr_info!
414/// [`pr_cont`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_cont
415/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
416/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
417///
418/// # Examples
419///
420/// ```
421/// # use kernel::pr_cont;
422/// pr_info!("hello");
423/// pr_cont!(" {}\n", "there");
424/// ```
425#[macro_export]
426macro_rules! pr_cont (
427 ($($arg:tt)*) => (
428 $crate::print_macro!($crate::print::format_strings::CONT, true, $($arg)*)
429 )
430);
431
432/// A lightweight `call_once` primitive.
433///
434/// This structure provides the Rust equivalent of the kernel's `DO_ONCE_LITE` macro.
435/// While it would be possible to implement the feature entirely as a Rust macro,
436/// the functionality that can be implemented as regular functions has been
437/// extracted and implemented as the `OnceLite` struct for better code maintainability.
438pub struct OnceLite(Atomic<State>);
439
440#[derive(Clone, Copy, PartialEq, Eq)]
441#[repr(i32)]
442enum State {
443 Incomplete = 0,
444 Complete = 1,
445}
446
447// SAFETY: `State` and `i32` has the same size and alignment, and it's round-trip
448// transmutable to `i32`.
449unsafe impl AtomicType for State {
450 type Repr = i32;
451}
452
453impl OnceLite {
454 /// Creates a new [`OnceLite`] in the incomplete state.
455 #[inline(always)]
456 #[allow(clippy::new_without_default)]
457 pub const fn new() -> Self {
458 OnceLite(Atomic::new(State::Incomplete))
459 }
460
461 /// Calls the provided function exactly once.
462 ///
463 /// There is no other synchronization between two `call_once()`s
464 /// except that only one will execute `f`, in other words, callers
465 /// should not use a failed `call_once()` as a proof that another
466 /// `call_once()` has already finished and the effect is observable
467 /// to this thread.
468 pub fn call_once<F>(&self, f: F) -> bool
469 where
470 F: FnOnce(),
471 {
472 // Avoid expensive cmpxchg if already completed.
473 // ORDERING: `Relaxed` is used here since no synchronization is required.
474 let old = self.0.load(Relaxed);
475 if old == State::Complete {
476 return false;
477 }
478
479 // ORDERING: `Relaxed` is used here since no synchronization is required.
480 let old = self.0.xchg(State::Complete, Relaxed);
481 if old == State::Complete {
482 return false;
483 }
484
485 f();
486 true
487 }
488}
489
490/// Run the given function exactly once.
491///
492/// This is equivalent to the kernel's `DO_ONCE_LITE` macro.
493///
494/// # Examples
495///
496/// ```
497/// kernel::do_once_lite! {
498/// kernel::pr_info!("This will be printed only once\n");
499/// };
500/// ```
501#[macro_export]
502macro_rules! do_once_lite {
503 { $($e:tt)* } => {{
504 #[link_section = ".data..once"]
505 static ONCE: $crate::print::OnceLite = $crate::print::OnceLite::new();
506 ONCE.call_once(|| { $($e)* });
507 }};
508}
509
510/// Prints an emergency-level message (level 0) only once.
511///
512/// Equivalent to the kernel's `pr_emerg_once` macro.
513#[macro_export]
514macro_rules! pr_emerg_once (
515 ($($arg:tt)*) => (
516 $crate::do_once_lite! { $crate::pr_emerg!($($arg)*) }
517 )
518);
519
520/// Prints an alert-level message (level 1) only once.
521///
522/// Equivalent to the kernel's `pr_alert_once` macro.
523#[macro_export]
524macro_rules! pr_alert_once (
525 ($($arg:tt)*) => (
526 $crate::do_once_lite! { $crate::pr_alert!($($arg)*) }
527 )
528);
529
530/// Prints a critical-level message (level 2) only once.
531///
532/// Equivalent to the kernel's `pr_crit_once` macro.
533#[macro_export]
534macro_rules! pr_crit_once (
535 ($($arg:tt)*) => (
536 $crate::do_once_lite! { $crate::pr_crit!($($arg)*) }
537 )
538);
539
540/// Prints an error-level message (level 3) only once.
541///
542/// Equivalent to the kernel's `pr_err_once` macro.
543#[macro_export]
544macro_rules! pr_err_once (
545 ($($arg:tt)*) => (
546 $crate::do_once_lite! { $crate::pr_err!($($arg)*) }
547 )
548);
549
550/// Prints a warning-level message (level 4) only once.
551///
552/// Equivalent to the kernel's `pr_warn_once` macro.
553#[macro_export]
554macro_rules! pr_warn_once (
555 ($($arg:tt)*) => (
556 $crate::do_once_lite! { $crate::pr_warn!($($arg)*) }
557 )
558);
559
560/// Prints a notice-level message (level 5) only once.
561///
562/// Equivalent to the kernel's `pr_notice_once` macro.
563#[macro_export]
564macro_rules! pr_notice_once (
565 ($($arg:tt)*) => (
566 $crate::do_once_lite! { $crate::pr_notice!($($arg)*) }
567 )
568);
569
570/// Prints an info-level message (level 6) only once.
571///
572/// Equivalent to the kernel's `pr_info_once` macro.
573#[macro_export]
574macro_rules! pr_info_once (
575 ($($arg:tt)*) => (
576 $crate::do_once_lite! { $crate::pr_info!($($arg)*) }
577 )
578);