# 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

```systemverilog
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.