retroDE_ps2/rtl/debug/README.md

rtl/debug

Trace taps, observability modules, and first-class debug infrastructure.

This directory is intentionally first-class per the debug/validation strategy in docs/contracts/validation.md. Nothing here is ornamental; stubs and real blocks alike depend on it.

Wave 1 contents

• trace_pkg.sv — shared types (subsys_e, event_e) and string renderers used by all trace producers and trace_sink_stub.
• trace_sink_stub.sv — simulation-only text trace writer. One instance per output file; each Wave 1 stub wires its event port to its own sink. See docs/decisions/0000-trace-format.md for format rationale.

Usage pattern for Wave 1 testbenches

trace_sink_stub #(
    .FILENAME  ("ee.trace"),
    .SINK_LABEL("ee_fetch")
) u_trace_ee (
    .clk      (clk),
    .rst_n    (rst_n),
    .ev_valid (dut_ev_valid),
    .ev_subsys(dut_ev_subsys),
    .ev_event (dut_ev_event),
    .ev_arg0  (dut_ev_arg0),
    .ev_arg1  (dut_ev_arg1),
    .ev_arg2  (dut_ev_arg2),
    .ev_arg3  (dut_ev_arg3),
    .ev_flags (dut_ev_flags)
);

Notes

• Cycle counter is internal to the sink and advances on clk while rst_n is high. Cross-clock correlation is a later-wave concern.
• ev_flags == 0 renders as - in the trace line; any non-zero value is printed as an 8-hex-digit field.
• Event/subsystem codes are globally unique in Wave 1 (not per-subsystem). Revisit if the namespace gets crowded.