kprint

kprint is a zero-overhead, stack-efficient logging and formatting crate designed for systems and embedded Rust code in the Zircon kernel environment.

It allows developers to write ergonomic Rust format strings ({}) that produce the same output as standard Rust formatting (core::fmt) while compiling invocations directly down to C printf / snprintf calls without intermediate stack buffers.

Overview & Architecture

Standard Rust formatting (core::fmt::write!, format_args!, and println!) relies heavily on core::fmt::Formatter, trait objects, dynamic dispatch tables, and intermediate stack formatting buffers. In resource-constrained environments or bare-metal kernels, this introduces unwanted binary bloat and stack space overhead.

kprint solves this by translating Rust format strings and arguments at compile time into C printf / snprintf invocations that preserve Rust's formatting output semantics:

1. Rust Output Fidelity: Accuracy is defined by matching the output that standard Rust formatting (core::fmt) would produce, rather than performing a naive 1-to-1 syntax mapping to C printf specifiers. Where C printf differs from Rust (for example, C‘s %#x omits the 0x prefix when formatting 0 and %#X emits uppercase 0X, whereas Rust’s {:#x} and {:#X} always emit lowercase 0x (0x0, 0x2A), and strings default to left-alignment), kprint synthesizes the appropriate C format string and arguments (such as "0x%llx", "0x%06llX", "%*s%llx" with a computed prefix width, or "%-8.*s") so the resulting output matches Rust without allocating stack buffers.
2. Compile-Time Format Translation: A procedural macro parses Rust format strings (e.g., "{:04x}" or "{:10s}") and converts them into static, null-terminated C format string literals (b"%04llx\0" or b"%-10.*s\0").
3. Trait-Based Argument Marshaling: Formatting arguments are bound once to local variables and converted via lightweight backend traits and helpers (AsKPrintStr, AsKPrintCString, AsKPrintSignedInt, AsKPrintUnsignedInt, AsKPrintPointer, AsKPrintChar, hex_alt_prefix_width).
4. Minimal Stack & Zero Heap Allocation: When formatting slices (&str, &[u8], &CStr), kprint passes (slice.len(), slice.as_ptr()) to C %.*s specifiers, avoiding heap allocations or temporary string-copying buffers.
5. Single Evaluation Semantics: Every format expression is evaluated strictly once, guaranteeing safe usage with side-effecting expressions.
6. Direct C Backend: Invocations compile directly into printf calls (or snprintf for kformat!), avoiding core::fmt dispatch tables.

Usage

Basic Printing

use kprint::{kprint, kprintln};

fn example() {
    let score = 42;
    let user = "alice";

    // Standard output without newline using captured variables
    kprint!("Connecting user {user:s} with ID {score:#06x}...");

    // Standard output with newline
    kprintln!("Connection established.");
}

In-Memory Formatting (kformat!)

When you need to format into a stack buffer without allocating:

use kprint::kformat;

fn format_example() {
    let mut buffer = [0u8; 128];
    let result: &[u8] = kformat!(&mut buffer, "Status: {:#08X} ({})", 0x1A, true);
    assert_eq!(result, b"Status: 0x00001A (true)");
}

Advanced Formatting Features

// Compile-time string concatenation
kprintln!(concat!("prefix_", "status: {}"), 42);

// Named and positional arguments
kprintln!("{0} + {1} = {0}", "a", "b");
kprintln!("{greeting:s}, {name:s}!", greeting = "hello", name = "world");

// Null-terminated C string pointers (*const c_char)
let c_ptr = c"kernel".as_ptr();
kprintln!("booting {:cs}", c_ptr);

Supported Format Variations

The procedural macro infers C format families from literal types, cast expressions, or explicit format specifiers, translating them into C printf specifiers and arguments that match Rust's formatting behavior:

Limitations & Intentional Differences from core::fmt

To avoid Rust-side formatting loops and intermediate stack buffers, kprint delegates all formatting to C printf / snprintf and has the following intentional limitations:

• Byte-Based Width and Precision: For strings ({:s}) and characters ({:c}), field width and precision are measured in UTF-8 bytes (as understood by C printf's %.*s) rather than Unicode scalar values (chars).
• Explicit Type Specifiers for Non-Literals: Because procedural macros run prior to Rust type checking, non-literal and non-cast expressions default to signed integer formatting (%lld) unless an explicit type specifier (:s, :u, :x, :X, :p, :c, :b, :f, :e, :E, :cs) is provided.
• No Custom Fill Characters or Center Alignment: Only space and '0' padding with left (<) or right (>) alignment are supported by C printf. Specifying a custom fill character (such as {:_>8}) or center alignment ({:^8}) produces a compile-time error.
• 64-Bit Integer Width: Integer specifiers convert arguments to c_longlong / c_ulonglong (64-bit).
• Direct C printf Delegation for :o, :f, :e, :E, and :b:
  • {:b} formats bool values ("true" / "false") rather than base-2 integers.
  • {:o}, {:f}, {:e}, and {:E} map directly to C printf‘s %llo, %f, %e, and %E (e.g., {:.1e} formats the exponent using C’s 1.0e+03 notation).