Debugging

Waveforms and evidence

Attach a capture, or let the run record its own, and see what the agent read from it.

A waveform is the difference between reasoning about what a signal probably did and reading what it actually did. Debug runs capture one automatically, and you can attach one of your own when you already know where the trouble is.

Capture happens on its own

When a debug run simulates your design, it records a waveform without touching your testbench. A small helper file is generated alongside your sources purely to turn capture on; your testbench is left exactly as you wrote it, because an edit there would show up in the diff as a change you never asked for.

The captured file is attached to the turn and can be downloaded, so you can open the same waveform in your own viewer and check the run's reasoning against it.

Attaching your own

The intake form takes a VCD. Two cases where attaching one is much better than letting the run capture its own:

The failure is hard to reproduce. If you have already caught it once, your capture is the reproduction; the run inspects it before trying to recreate the conditions itself.
The failure was on hardware. An ILA or SignalTap export is a waveform like any other. Every query below works on it unchanged, which is the one part of a board investigation that carries over cleanly.

Note

Very large captures are truncated rather than rejected, and the turn tells you when that happened along with the time range that was kept. If you can, export a window around the failure instead of the whole run.

What the run does with it

The waveform is queried, not dumped. Asking for every transition on a clock would fill the entire run with noise and end it before anything was learned, so the questions are narrow and each answer is capped.

Question	What it answers
List the signals	What is in the capture, and how wide each signal is.
Show a window	Every value change for a chosen set of signals between two times.
Show around a moment	The cycles either side of an interesting time.
Find an edge	The first time a signal rises or falls after a given point.
Find when a condition holds	The first time a combination of signal values becomes true; this is how the first divergence gets located.
Scan for X and Z	Which signals are undefined or high-impedance, and when. A register that is X after reset explains a large share of real bugs.

Undefined is not zero

An undefined bit is reported as undefined, never quietly rounded down to zero. This sounds like a detail and it is not: treating X as 0 turns "this register was never initialised" into "this register held a small number", which is exactly the bug the run exists to find.

Reading a window

t = 300 ns   clk=1  rst_n=1  wr_ptr=0111  full=0  push=1
t = 310 ns   clk=0  rst_n=1  wr_ptr=1000  full=0  push=1
t = 320 ns   clk=1  rst_n=1  wr_ptr=1000  full=1  push=0
                                          ^ full asserts a cycle late

Values are shown in the width the signal actually has, so a partly-undefined vector reads as partly undefined rather than as a number that happens to look plausible.

Where it shows up in the answer

Waveform readings appear in the evidence list on the diagnosis, each with the time it was taken and the signal values at that time. If a claim about behaviour has no time attached to it, treat it as reasoning rather than as an observation; see Reading a diagnosis.

Tip

Captured waveforms are kept inside the workspace and are excluded from the file tree, the download zip and the change report, so they never turn up in your project as files somebody added.