blob: 3d732249cc9c006ecd9aaffbf6889fd5b2aa35ba [file]
// Copyright 2026 The Fuchsia Authors
//
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file or at
// https://opensource.org/licenses/MIT
#![cfg_attr(not(test), no_std)]
#[cfg(test)]
use kprint as _;
// For use in `kernel_oops!`.
#[doc(hidden)]
pub use kprint::kprint as __kprint;
pub mod dprintf;
pub mod ltrace;
/// Banner which starts every `DRIVER OOPS` message (`tefmocheck` looks for this in logs).
// LINT.IfChange
pub const DRIVER_OOPS_BANNER: &str = "\nDRIVER OOPS\n";
// LINT.ThenChange(
// //zircon/kernel/include/debug.h,
// //tools/testing/tefmocheck/string_in_log_check.go,
// )
/// Banner which starts every `DRIVER WARNING` message.
// LINT.IfChange
pub const DRIVER_WARN_BANNER: &str = "\nDRIVER WARNING\n";
// LINT.ThenChange(//zircon/kernel/include/debug.h)
/// Zero-sized [`core::fmt::Write`] adapter that writes directly to the kernel console.
pub struct KernelConsoleWriter;
impl core::fmt::Write for KernelConsoleWriter {
#[cfg(not(test))]
fn write_str(&mut self, s: &str) -> core::fmt::Result {
kprint::kprint!("{:s}", s);
Ok(())
}
#[cfg(test)]
fn write_str(&mut self, s: &str) -> core::fmt::Result {
std::print!("{}", s);
Ok(())
}
}
/// Fixed-size stack buffer implementing [`core::fmt::Write`] that truncates on a UTF-8 character
/// boundary when full.
struct StackBufWriter<const N: usize> {
buf: [u8; N],
len: usize,
}
impl<const N: usize> StackBufWriter<N> {
const fn new() -> Self {
Self { buf: [0u8; N], len: 0 }
}
fn as_str(&self) -> &str {
// SAFETY: `write_str` only ever appends valid UTF-8 substrings (truncated on a character
// boundary) into `self.buf[..self.len]`.
unsafe { core::str::from_utf8_unchecked(&self.buf[..self.len]) }
}
}
impl<const N: usize> core::fmt::Write for StackBufWriter<N> {
fn write_str(&mut self, s: &str) -> core::fmt::Result {
let avail = N - self.len;
let mut to_copy = s.len().min(avail);
while !s.is_char_boundary(to_copy) {
to_copy -= 1;
}
self.buf[self.len..self.len + to_copy].copy_from_slice(&s.as_bytes()[..to_copy]);
self.len += to_copy;
Ok(())
}
}
#[doc(hidden)]
#[cold]
#[inline(never)]
pub fn print_with_banner(banner: &str, args: core::fmt::Arguments<'_>) {
use core::fmt::Write as _;
let mut buf = StackBufWriter::<512>::new();
let _ = buf.write_str(banner);
let _ = buf.write_fmt(args);
let _ = KernelConsoleWriter.write_str(buf.as_str());
}
/// A [`kprint`]-like macro which prepend's the user's message with the special
/// "ZIRCON KERNEL OOPS" tag. Automated builds look for tags like this and
/// consider their presence to indicate test failures, even if the higher level
/// test framework code thinks the test passed.
///
/// A kernel OOPS indicates the presence of a bug, however, the bug may not be
/// in the kernel itself.
///
/// # Examples
/// ```rust
/// kernel_oops!("value {} is out of range", val);
/// ```
#[macro_export]
macro_rules! kernel_oops {
($fmt:literal, $($arg:tt)*) => {
$crate::__kprint!(concat!("\nZIRCON KERNEL OOPS\n", $fmt), $($arg)*)
};
}
/// Formats a message prefixed with [`DRIVER_OOPS_BANNER`] into a stack buffer and emits it in a
/// single console write so concurrent CPUs cannot interleave output between the banner and message
/// body.
///
/// Equivalent to C++ `DRIVER_OOPS` in `<debug.h>`.
#[macro_export]
macro_rules! driver_oops {
($($arg:tt)*) => {
$crate::print_with_banner($crate::DRIVER_OOPS_BANNER, core::format_args!($($arg)*))
};
}
/// Formats a message prefixed with [`DRIVER_WARN_BANNER`] into a stack buffer and emits it in a
/// single console write.
///
/// Equivalent to C++ `DRIVER_WARN` in `<debug.h>`.
#[macro_export]
macro_rules! driver_warn {
($($arg:tt)*) => {
$crate::print_with_banner($crate::DRIVER_WARN_BANNER, core::format_args!($($arg)*))
};
}
#[cfg(test)]
mod tests {
use super::*;
use core::fmt::Write as _;
#[test]
fn test_stack_buf_writer_utf8_truncation() {
let mut w = StackBufWriter::<6>::new();
let _ = w.write_str("ab🦀cd");
// "ab" is 2 bytes; "🦀" is 4 bytes (fits in 6), "cd" is truncated.
assert_eq!(w.as_str(), "ab🦀");
let mut w2 = StackBufWriter::<5>::new();
let _ = w2.write_str("ab🦀cd");
// "🦀" (4 bytes) does not fit in the remaining 3 bytes, so truncation stops on the
// character boundary after "ab".
assert_eq!(w2.as_str(), "ab");
}
#[test]
fn test_driver_oops_and_warn() {
driver_oops!("test oops {}\n", 42);
driver_warn!("test warn {}\n", "msg");
}
}