A test reports that traffic stopped: flits are still pending after thousands of cycles. There is no corrupted data and no assertion message, only silence. Hangs are intimidating because nothing points at the cause. They are also the most systematic failures to debug, because every hang has something waiting, and every wait has a condition that never became true.

Walk me through a stuck valid.

The obvious answer, and why it breaks

The obvious approach scrolls through the waveform looking for something odd. In a long simulation with many signals, everything looks odd and nothing points anywhere. The method is to start from the one thing known to be stuck and ask a single question repeatedly: what is it waiting for?

The idea: follow the wait backwards

Build it: a DCRouter hang

The testbench builds DCRouter with Bug Zoo BUG_21, sends one packet, lets the router fall asleep, then offers a packet on input 3 alone, and records what the pins show.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// uses: dcrouter BUG_21
// Lesson 13.3: a hang to debug. DCRouter is built with Bug Zoo BUG_21. One packet crosses the
// router, the router falls asleep after the idle threshold, then input 3 alone offers a
// packet. The test records what the pins show for 40 cycles and passes when the hang is
// reproduced exactly as reported: input 3 holding valid, in_rdy low, the router asleep.
module tb;
  `include "dcr_env.svh"
  int held = 0;
  initial begin
    reset_dut();
    queue_pkt(0, 1, 0, 2);
    wait_drain();
    repeat (12) @(posedge clk);                   // idle long enough to sleep
    queue_pkt(3, 2, 0, 2);                        // input 3 alone offers a packet
    repeat (40) @(posedge clk) if (in_vld[3] && !in_rdy[3] && sleeping) held++;
    if (held >= 38) $display("PASS: hang reproduced: input 3 held valid for %0d of 40 cycles with in_rdy low while the router stayed asleep", held);
    else $display("FAIL: no hang (input 3 stalled for %0d cycles)", held);
    $finish;
  end
endmodule

It prints:

PASS: hang reproduced: input 3 held valid for 40 of 40 cycles with in_rdy low while the router stayed asleep

Following the wait

1
2
3
4
5
6

logic wake;
`ifdef BUG_21
  assign wake = |in_vld[2:0];                                // BUG_21: port 3 cannot wake it
`else
  assign wake = |in_vld;
`endif

With BUG_21 defined, wake looks only at in_vld[2:0]. Input 3 can never wake the router. Five questions from a silent hang to one line of RTL, without reading any logic that was not on the path. In this course's testbenches, the R13 wake assertion (lesson 5.3) reports the same thing at the cycle it happens, which is exactly why such assertions are worth writing.

The method for corruption, too

• For wrong data, the same method runs backwards from the wrong value: where did this value come from, one register stage at a time, until the stage where right became wrong.

• For lost data, follow the item: where was it last seen, and which handshake failed to pass it on?

• In all cases, follow one signal's dependencies, not the whole waveform.

How real teams debug hangs

What breaks

A team (illustrative) debugged a system hang by inspecting hundreds of signals in the last thousand cycles of a long simulation. The bus that stalled first had stopped 200,000 cycles earlier; everything near the end was a consequence. A watchdog printing the oldest stalled handshake would have pointed straight at it.

Key takeaways

• Every hang has something waiting; follow what it waits for, one dependency at a time.

• For corruption, follow the wrong value backwards stage by stage.

• Progress assertions and watchdogs turn hangs into precise reports.

Related topics

• Part 13 overview: Debug