Module ltrace 

Local trace (LOCAL_TRACE) logging mechanism for the Zircon kernel.

Overview

This crate provides a compile-time-guarded debug tracing and logging mechanism (LOCAL_TRACE, ltrace!, ltracef!, etc.) for Zircon kernel development. It allows developers to maintain detailed, file-scoped debug logging inside source files with zero overhead in production builds, while enabling targeted high-verbosity logs when developing or debugging.

Defining Local Trace Verbosity

Unlike unconditional trace macros (trace!, tracef!, etc.), the ltrace* family of macros requires a u32 constant named LOCAL_TRACE to be defined in the caller’s scope.

To use local tracing in a Rust file or module (foo.rs), define a file-scoped or module-scoped u32 constant at the top of the file:

// Disable local tracing by default for this file/module:
const LOCAL_TRACE: u32 = 0;

Enabling Trace Output Locally During Debugging

To locally enable verbose trace logs in a specific file while developing or debugging, edit the local const definition:

const LOCAL_TRACE: u32 = 1; // Or a higher verbosity level like 2

Because Rust lexical scoping prefers constants defined in the current module over those in outer modules, crates or parent modules can define a default fallback const LOCAL_TRACE: u32 = 0; at their root, and any specific submodule or file can override that fallback locally by defining its own LOCAL_TRACE.

Zero Runtime Overhead When Disabled

When LOCAL_TRACE is 0 at compile-time, trace macros expand to if false { ... }. The Rust compiler (rustc/LLVM) type-checks and syntax-checks the arguments inside the macro block, but eliminates the dead branch during compilation. Therefore, disabled trace statements incur zero runtime CPU cost and generate zero string data in .rodata.

Porting from C++ (trace.h)

When porting C++ kernel code that uses zircon/kernel/include/trace.h (#define LOCAL_TRACE 0, LTRACE_ENTRY, LTRACEF, etc.), trace logging statements should be preserved using this crate.

The table below maps C++ trace.h macros to their Rust ltrace equivalents:

• TRACE_ENTRY -> [trace_entry!]
• TRACE_EXIT -> [trace_exit!]
• TRACE_ENTRY_OBJ -> [trace_entry_obj!]
• TRACE_EXIT_OBJ -> [trace_exit_obj!]
• TRACE -> [trace!]
• TRACEF(str, x...) -> [tracef!]
• LTRACE_ENTRY -> [ltrace_entry!]
• LTRACE_EXIT -> [ltrace_exit!]
• LTRACE_ENTRY_OBJ -> [ltrace_entry_obj!]
• LTRACE_EXIT_OBJ -> [ltrace_exit_obj!]
• LTRACE -> [ltrace!]
• LTRACEF(x...) -> [ltracef!]
• LTRACEF_LEVEL(lvl, x...) -> [ltracef_level!]