Kernel Trace Ring

Define `TraceRing<const N: usize>` in kernel-core. Why it matters: A lockless per-core ring avoids contention on the hot path; placing it in kernel-core makes it host-testable with standard cargo test just like the existing LogRing. Focus on `TraceRing` and `LogRing` in `kernel-core/src/trace_ring.rs` while you trace the snippet.

/// Per-core lockless circular trace buffer.
///
/// Holds the most recent `N` entries. New entries overwrite the oldest on wrap.
/// No mutex — safe for single-writer (owning core) use.
pub struct TraceRing<const N: usize> {
    buf: [TraceEntry; N],
    write_idx: usize,
    count: usize,
}

impl<const N: usize> TraceRing<N> {

View on GitHub

Per-core trace ring allocation in kernel. Why it matters: Each core needs its own ring to avoid lock contention; the ring must be sized to hold enough events to cover a typical fork+dispatch+fault sequence. Focus on `PerCoreData` and `TraceRing::new` in `kernel/src/smp/mod.rs` while you trace the snippet.

/// Per-core state block.
///
/// Each core has one of these, initialized during BSP init or AP bootstrap.
/// The `gs_base` MSR points to this struct so that `per_core()` can retrieve
/// it in O(1) without MMIO.
#[repr(C)]
pub struct PerCoreData {
    /// Self-pointer at offset 0 — reserved for future `gs:[0]` access.
    /// Currently unused: `per_core()` reads `IA32_GS_BASE` via `rdmsr`.
    self_ptr: *const PerCoreData,
    /// Logical core index (0 = BSP, 1..n = APs in MADT order).
    pub core_id: u8,
    /// LAPIC ID from the MADT.
    pub apic_id: u8,
    /// Set to `true` once this core has completed initialization.
    pub is_online: AtomicBool,
    /// Pointer to this core's TSS (for runtime RSP0 updates).
    tss_ptr: *mut TaskStateSegment,
    /// Pointer to this core's GDT (pre-allocated on BSP, loaded on AP).
    gdt_ptr: *const GlobalDescriptorTable,
    /// Segment selectors for this core's GDT.
    gdt_code: SegmentSelector,
    gdt_data: SegmentSelector,
    gdt_tss: SegmentSelector,

View on GitHub

Trace emit helper. Why it matters: A single trace_event(event) call site keeps instrumentation minimal (one line per call site) and handles timestamping and core-ID tagging automatically. Focus on `trace_event` and `trace_event(event)` in `kernel/src/trace.rs` while you trace the snippet.

/// Emit a trace event on the current core's trace ring.
///
/// Compiles to nothing when the `trace` feature is off.
#[cfg(feature = "trace")]
pub fn trace_event(event: TraceEvent) {
    if !crate::smp::is_per_core_ready() {
        return;
    }
    let core_id = crate::smp::per_core().core_id;
    let tick = crate::arch::x86_64::interrupts::tick_count();
    // Safety: trace_ring is wrapped in UnsafeCell for interior mutability.
    // Only the owning core writes to its ring (single-writer guarantee via
    // gs_base per-core data). The UnsafeCell makes the mutable access sound.
    let ring_ptr = crate::smp::per_core().trace_ring.get();
    unsafe {
        (*ring_ptr).push(TraceEntry {
            tick,
            core: core_id,
            _pad: [0; 7],
            event,
        });
    }
}

View on GitHub