Reporting Debug Techniques

Reporting System · Module 24 · Page 24.6

The Engineering Problem

The reporting system isn't just for pass/fail — it's your primary window into what the testbench and DUT are doing, and using it well is a debugging skill. A test fails, and now you must find why — but the naive approaches fail. Turn verbosity all the way up globally and you get a flood — millions of lines that bury the real failure and slow the sim 10x. Debug the loudest or most-frequent error and you chase a symptom — because the 50 errors in the log are usually a cascade from one root, and the loudest is downstream of the cause. Grep blindly and you can't trace anything because the message IDs are inconsistent. The reporting system gives you the tools to do this right — surgical verbosity to zoom into the suspect area, message IDs to filter and trace, actions to trigger a dump or stop at the failure, and the discipline to trace backward from the first error. The problem this chapter solves is reporting debug techniques: using the reporting system as a debug instrument — zooming surgically, filtering by id, trapping the failure state, reducing noise, and debugging the root, not the cascade.

Reporting debug techniques are the practices for using the reporting system as a debug instrument. Surgical verbosity: instead of a global flood, raise verbosity on only the suspect component or id (set_report_verbosity_level_hier, set_report_id_verbosity, targeted +uvm_set_verbosity), so you get detail where you need it and quiet elsewhere — signal without noise. Message IDs as filters and traces: consistent, meaningful IDs turn the log into a queryable database — grep by id, count an id, follow a transaction's lifecycle by its id, set per-id verbosity/actions. Trigger actions at the failure: use UVM_STOP (drop into the debugger at a specific error), or a catcher/UVM_CALL_HOOK to trigger a waveform dump or snapshot when a specific id/error fires — catch the state at the bug. Reduce noise to find signal: lower the verbosity of chatty components and suppress known noise so the real failure is visible. And the cardinal rule: the first counted error is usually the root cause — later errors are often cascades from the broken state, so trace backward from the earliest error (fixing the root collapses the cascade), not the loudest or most-frequent (a downstream symptom). This chapter is reporting debug techniques: surgical verbosity, IDs, action triggers, noise reduction, and root-versus-cascade.

How do you use the reporting system to debug — zoom surgically with verbosity, filter and trace with message IDs, trigger actions (stop, dump, snapshot) at the failure, reduce noise to find signal, and why is the first counted error usually the root cause while later errors are cascades?

Motivation — why debugging with reports is a skill

The reporting system is information-rich — and using it badly drowns you while using it well finds the bug fast. The reasons these techniques matter:

• Global verbosity is a flood, not a tool. Turning everything up produces millions of lines that bury the real signal and slow the sim — more information is not better information. Surgical verbosity (zoom into the suspect) gives signal without noise.
• IDs make the log queryable. Consistent, meaningful IDs turn an unsearchable wall of text into a database you can filter, count, and trace. Without them, you can't follow a transaction or isolate an event; with them, the log is a debug tool.
• The failure state is fleeting — trap it. When the error fires, the state that caused it is right there — but gone a cycle later. Triggering a dump, stop, or snapshot at the error captures the state at the bug, so you debug the moment of failure, not its aftermath.
• The first error is usually the root. A flood of errors is usually a cascade — one root cause propagating into many downstream symptoms. Debugging the first (root) collapses the cascade; chasing the loudest (a symptom) wastes effort on an effect.
• Noise hides signal. A chatty component or a known-noise message floods the log and hides the real failure. Reducing noise (lower verbosity, suppress) surfaces the signal — debugging is as much about removing noise as adding detail.

The motivation, in one line: the reporting system is information-rich, so debugging with it is a skill — global verbosity floods (zoom surgically instead), IDs make the log queryable (filter/trace), the failure state is fleeting (trap it with an action), the first error is usually the root (a flood is a cascade — debug the first), and noise hides signal (reduce it) — using these well finds the bug fast; using them badly drowns you.

Mental Model

Hold reporting debug as a diagnostic instrument with a zoom and filters — zoom surgically on the suspect, filter by id, trace backward from the first sign of damage, and trip a snapshot at the moment of failure:

The reporting system is a diagnostic microscope. It has a zoom — verbosity — that controls how much detail you see, and filters — message ids — that highlight specific kinds of events. A novice debugging a problem cranks the magnification to maximum across the entire slide: now everything is in extreme detail, a blur of cells, and the one abnormal cell is lost in the flood, while the microscope itself crawls under the load. An expert does the opposite. They first reduce the clutter — turn down the chatty regions — then zoom in surgically on just the suspect area, raising detail only there. They use the filters to highlight only the relevant events — follow this one transaction, isolate this one protocol event — turning the slide into something searchable. They trace the pathology backward: the visible damage is usually downstream of an origin, so they look for the earliest sign, because the first lesion is the root and the rest is spread. And they set a trip-wire to capture the moment of damage — when the specific abnormality appears, freeze the slide and take a full snapshot — so they study the failure as it happens, not its aftermath. The instrument is the same; the difference is technique. Maximum magnification everywhere is not diagnosis — it's drowning. Surgical zoom, targeted filters, backward tracing from the first sign, and a trip-wire snapshot is diagnosis. Picture the reporting system as a diagnostic microscope. It has a zoom (verbosity) and filters (message ids). A novice cranks the magnification to maximum across the entire slide — everything in extreme detail, a blur, the one abnormal cell lost in the flood, the instrument crawling. An expert does the opposite: reduce the clutter (turn down the chatty regions), then zoom surgically on just the suspect area (detail only there), use the filters to highlight only the relevant events (follow this transaction, isolate this event — making the slide searchable), trace the pathology backward (the visible damage is downstream of an origin — find the earliest sign, the first lesion is the root, the rest is spread), and set a trip-wire to capture the moment of damage (when the specific abnormality appears, freeze and snapshot — study the failure as it happens). The instrument is the same; the difference is technique. Maximum magnification everywhere is not diagnosis — it's drowning. Surgical zoom, targeted filters, backward tracing from the first sign, and a trip-wire snapshot is diagnosis.

So reporting debug is a diagnostic microscope wielded with technique: reduce clutter (noise), zoom surgically (verbosity on the suspect, not globally), filter by id (highlight the relevant events — the log as queryable), trace backward from the first sign (the first error is the root, the rest is cascade), and trip a snapshot at the failure (an action that dumps/stops at the bug). Max magnification everywhere is drowning; surgical, filtered, backward-traced, trip-wired is diagnosis. Zoom surgically, filter by id, trace backward from the first error, and snapshot the failure — don't crank the magnification everywhere and drown.

Visual Explanation — the reporting debug toolkit

The defining picture is the toolkit: surgical verbosity (zoom), IDs (filter/trace), actions (trip-wires), and noise reduction (signal) — the instruments for debugging with reports.

The figure shows the reporting debug toolkit. Surgical verbosity (the brand-colored top — the zoom): raise detail on only the suspect component/id (per-component/per-id verbosity) — not a global flood. Message IDs (filter and trace): consistent, meaningful ids make the log a queryable database — grep, count, follow a transaction, set per-id actions. Action triggers (the warning-colored layer — the trip-wire): UVM_STOP, or a catcher / UVM_CALL_HOOK firing a waveform dump or snapshot at a specific error — capture the failure state. Noise reduction (find the signal): lower verbosity of chatty components and suppress known noise so the real failure is visible. The crucial reading is that these four tools address the four debugging needs: getting the right detail (verbosity — zoom), finding/following the relevant messages (IDs — filter), capturing the failure state (actions — trip-wire), and clearing the clutter (noise reduction — signal). Together, they transform the reporting system from a passive wall of text into a precise debug instrument. The interplay matters: noise reduction + surgical verbosity work together (turn down the chatty, turn up the suspect) to produce signal without noise; IDs make the verbosity and actions targetable (you zoom and trip by id); and action triggers capture what the verbosity reveals (dump at the moment the detail shows the bug). The warning-colored action triggers are highlighted because they're the most powerful and underused — making a report do something (stop, dump) at the failure is what catches the fleeting state. The diagram is the debug toolkit: surgical verbosity (zoom) + IDs (filter) + action triggers (trip-wire) + noise reduction (signal) — the instruments that make the reporting system a debug tool. Zoom surgically, filter by id, trip a snapshot at the failure, and reduce noise — the reporting system as a precise debug instrument.

RTL / Simulation Perspective — the techniques in code

In code, the techniques are targeted verbosity, id-based filtering/actions, and triggering a dump/stop at a specific error. The example shows each.

// === SURGICAL VERBOSITY: zoom into ONLY the suspect component/id (not global) ===
// raise detail on just the suspect driver's subtree:
env.agent.driver.set_report_verbosity_level_hier(UVM_HIGH);   // suspect: full detail
// or, even narrower, just one id everywhere:
uvm_top.set_report_id_verbosity("PROTO_TRACE", UVM_HIGH);      // only this id's messages
// (command line equivalent: +uvm_set_verbosity=env.agent.driver,_ALL_,UVM_HIGH,run)
 
// === MESSAGE IDs as FILTERS/TRACES: consistent ids → queryable log ===
`uvm_info("TXN_LIFECYCLE", $sformatf("id=%0d started", t.id), UVM_HIGH)   // follow a txn by this id
//   grep the log:  grep "TXN_LIFECYCLE" run.log | grep "id=42"   → that transaction's whole life
 
// === TRIGGER AN ACTION AT THE FAILURE: stop or dump when a specific error fires ===
// (a) STOP into the debugger at a specific error id:
uvm_top.set_report_id_action("DATA_MISMATCH", UVM_DISPLAY | UVM_LOG | UVM_COUNT | UVM_STOP);
//   when DATA_MISMATCH fires → drop into the interactive debugger AT the failure → inspect state
// (b) a CATCHER that dumps waveforms / snapshots when the error fires (Module 24.3):
class dump_on_error extends uvm_report_catcher;
  virtual function action_e catch();
    if (get_severity() == UVM_ERROR && get_id() == "DATA_MISMATCH") $dumpon;  // capture the moment
    return THROW;
  endfunction
endclass
 
// === NOISE REDUCTION: quiet a chatty component so the real signal surfaces ===
env.noisy_monitor.set_report_verbosity_level_hier(UVM_LOW);   // turn DOWN the chatter
 
// ✗ MISTAKE: +UVM_VERBOSITY=UVM_HIGH globally → millions of lines, 10x slower, signal BURIED
// ✗ MISTAKE: debug the LAST/loudest error (a cascade symptom), not the FIRST (the root) — DebugLab

The code shows the techniques. Surgical verbosity: env.agent.driver.set_report_verbosity_level_hier(UVM_HIGH) raises detail on just the suspect driver's subtree; set_report_id_verbosity("PROTO_TRACE", UVM_HIGH) raises only one id's messages; (command-line +uvm_set_verbosity=env.agent.driver,...). Message IDs as filters/traces: a consistent id ("TXN_LIFECYCLE") lets you grep the log (grep "TXN_LIFECYCLE" | grep "id=42" → that transaction's whole life) — the log as queryable. Trigger an action at the failure: (a) set_report_id_action("DATA_MISMATCH", ... | UVM_STOP) drops into the interactive debugger at the failure (inspect state at the bug); (b) a catcher (dump_on_error) that fires $dumpon (or a snapshot) when DATA_MISMATCH fires — capture the moment. Noise reduction: env.noisy_monitor.set_report_verbosity_level_hier(UVM_LOW) turns down the chatter. The mistakes (commented): +UVM_VERBOSITY=UVM_HIGH globally (millions of lines, 10x slower, signal buried), and debugging the last/loudest error (a cascade symptom) instead of the first (the root — the DebugLab). The shape to carry: the techniques are targeted — verbosity by component/id (not global), IDs for filtering/tracing (the log as a database), actions (UVM_STOP, a dump catcher) to trap the failure state, and noise reduction (turn down the chatty). The action trigger (stop/dump at the error) is the power tool — it catches the fleeting state at the moment of failure, which a post-hoc log can't. The surgical verbosity + noise reduction combine to give signal without noise. Zoom by component/id, filter and trace by id, trip a stop or dump at the failure, and turn down the chatter — never flood globally.

Verification Perspective — surgical versus global verbosity

The first technique — and the most-misused — is verbosity. The line between surgical (a tool) and global (a flood) is where debugging succeeds or drowns.

The figure shows surgical versus global verbosity. Global high verbosity (raise everywhere) → millions of lines, the real signal buried in noise, the sim slowed many times over — a flood, not a tool. Surgical verbosity (raise only the suspect component or id, leaving the rest quiet) → the relevant detail is visible, the noise is absent, the sim stays fast — signal without noise. The verification insight is that the same verbosity mechanism is a flood when global and a precision tool when targeted — and debugging effectively means zooming, not flooding. The temptation, when you need more detail, is to turn it all up — but that's counterproductive: more lines isn't more insight; it's more to search through, and the one relevant message is harder to find in millions than in thousands. And the sim slows (every message has cost), so a global-high run is expensive. Surgical verbosity — set_report_verbosity_level_hier on the suspect subtree, or per-id verbosity on the suspect id — gives you exactly the detail you need (the suspect's internals) without the noise (everything else stays at normal verbosity) and without the slowdown (only the suspect is verbose). The default-colored global flood and the brand/success-colored surgical signal are the two outcomes of the same mechanism — and the skill is choosing surgical. The practical workflow: when you need detail, ask where (which component/id is suspect?) and raise verbosity there only — iterating (zoom into the suspect, then narrower as you localize). The diagram is the verbosity choice: global → flood (buried, slow); surgical → signal (visible, fast) — the line between drowning and diagnosing. Raise verbosity surgically on the suspect, not globally — the same mechanism is a flood when global and a tool when targeted.

Runtime / Execution Flow — tracing backward from the first error

At debug time, the systematic approach is to trace backward from the first error — the root — not the loudest or last. The flow shows the backward trace.

The flow shows tracing backward from the first error. First (step 1): find the first counted error in the log — usually the root, because later errors cascade from the broken state. Context (step 2): read its context — the message, component, time, id — what failed, where, when. Zoom (step 3): raise verbosity on that component/time and re-run, or trigger a dump at that error, to see the detail leading up to it. Fix (step 4): identify the cause from the lead-up detail; fixing the root typically collapses the whole cascade of later errors (which were only symptoms). The runtime insight is the first-error-is-root principle — and why it matters for efficiency. A failing test often produces a flood of errors, and the instinct is to debug the most frequent or most recent — but those are usually downstream: one root cause (a misconfigured register, a wrong address, a protocol break) corrupts the state, and every subsequent operation fails as a consequence. So the 50 errors are 1 root + 49 cascades. Debugging a cascade error leads you to a symptom (this operation failed because the state was wrong) — not the cause (why the state got wrong). Tracing backward to the first error finds the point where the state first broke — the root — and fixing it makes the cascade vanish (the subsequent operations no longer see a broken state). The zoom (step 3) is applied at the first error — surgical verbosity around that component/time, or a dump triggered there — to see the lead-up to the root. The brand-colored first/context feed the success-colored zoom, yielding the default-colored root fix. This is why max_quit_count interacts here — quitting early (after few errors) focuses you on the first (root); but you also want enough errors to confirm the pattern (is it a cascade from one root, or independent failures?). The flow is the backward trace: first error (root) → context → zoom in → cause → fix (collapses cascade) — debugging the cause, not the symptom. Trace backward from the first error — it's usually the root, and fixing it collapses the cascade of later symptoms.

Waveform Perspective — the root error and its cascade

The first-error-is-root dynamic is visible on a timeline: a root error at one point, then a cascade of follow-on errors caused by the broken state. The waveform shows the root and the cascade it spawns.

The waveform shows the root error and its cascade. A root cause breaks the state at one point (root_err) — e.g. a register misconfigured, corrupting the datapath (state_bad goes high and stays). From then on, every subsequent operation fails as a consequence: a cascade of follow-on errors (cascade_err) keeps firing, all symptoms of the one broken state. The error count climbs (err_count), but the later errors are not independent bugs — they're the root propagating. The crucial reading is the causal structure: root_err (the first error) breaks the state (state_bad), and every cascade_err after is caused by that broken state — not a separate bug. So the err_count of 6 is 1 root + 5 cascades. Debugging a cascade error (any of the later ones) leads to a symptom: "this operation failed because state_bad" — true, but not the cause. Tracing back to root_err (the first, where state_bad first went high) finds the cause: why the state broke. And fixing the root makes state_bad never go high, so the entire cascade vanishes — all the cascade_errs were only there because of the root. The picture to carry is that a flood of errors often has a single root and a long cascade — and the first error is where the root struck, while the rest are the wave it spawned. Reading the waveform this way — which error is the root (first, where the state broke), and which are the cascade (later, caused by the broken state)? — is seeing past the flood to the cause. The root_err at the start, cascade_err repeating after, all from one broken state is the signature of a cascade — and the debug move is trace back to the first, not chase the loudest. A root error breaks the state and spawns a cascade of symptom errors — debug the first (the root), and the cascade collapses.

DebugLab — the week spent debugging the cascade instead of the root

✗ DEBUG the most-frequent/loudest error (a cascade symptom):
  // log has 47 errors:
  //   [10ns]  UVM_ERROR illegal register write to CTRL   ← fired ONCE, FIRST (the ROOT)
  //   [50ns]  UVM_ERROR scoreboard mismatch              ← fired 38 times (the CASCADE)
  //   ...                                                   (each mismatch = a symptom of the bad mode)
  // team debugs the 38 mismatches (loudest) → each is a real "DUT output wrong" symptom
  //   → but the CAUSE (illegal write → wrong mode → wrong datapath) is upstream, in the FIRST error
  //   → a WEEK chasing symptoms
 
✓ TRACE BACKWARD from the FIRST error (the root):
  // read the FIRST counted error: "illegal register write to CTRL" at 10ns
  //   → the illegal write misconfigured the mode register → datapath in wrong mode → all mismatches
  // fix the illegal write (a sequence bug writing CTRL wrongly) → the 38 mismatches VANISH
  // the first error named the root directly; the cascade was 38 symptoms of it

Common Mistakes

• Raising verbosity globally. A global flood buries the signal and slows the sim; zoom surgically on the suspect component or id.
• Debugging the loudest or last error. The most-frequent error is usually a cascade symptom; read and debug the first error (the root) first.
• Inconsistent message IDs. Loose or generic ids make the log unsearchable; use consistent, meaningful ids so the log is queryable and traceable.
• Not trapping the failure state. The state at the bug is fleeting; trigger a stop, dump, or snapshot at the specific error to capture it.
• Adding detail without removing noise. Debugging is as much reducing noise as adding detail; quiet chatty components so the signal surfaces.
• Ignoring the cascade structure. Treating each error as independent wastes effort; recognize when many errors share one broken-state root.

Senior Design Review Notes

Interview Insights

Exercises

1. Zoom surgically. Show how to raise verbosity on only a suspect driver and one suspect id, leaving the rest quiet.
2. Trace the cascade. Given a log with one early illegal-write error and 30 later mismatches, explain which to debug and why.
3. Trap the failure. Set an action so a specific error drops into the debugger and a catcher dumps waveforms at it.
4. Make the log queryable. Describe an id convention that lets you follow a transaction's lifecycle and isolate protocol events.

Summary

• Reporting debug techniques use the reporting system as a debug instrument: surgical verbosity (raise detail on only the suspect component/id — not a global flood that buries the signal and slows the sim), message IDs (consistent, meaningful ids make the log a queryable database — filter, count, trace, target), action triggers (UVM_STOP, or a catcher/UVM_CALL_HOOK firing a dump/snapshot at a specific error — capture the failure state), and noise reduction (quiet chatty components, suppress known noise).
• The cardinal rule: the first counted error is usually the root cause — a flood of errors is usually a cascade from one root that corrupted the state, so the loudest/most-frequent error is usually a downstream symptom; trace backward from the earliest error (read the top of the log first), because fixing the root collapses the cascade.
• Surgical verbosity beats global: the same mechanism is a flood when global (signal buried, sim slow) and a precision tool when targeted (signal without noise, fast) — zoom, don't flood.
• Trapping the fleeting failure state (stop/dump/snapshot at the error) captures the bug as it happens, far better than a post-hoc log; target it narrowly by id.
• The durable rule of thumb: debug with the reporting system as a precise instrument — zoom verbosity surgically onto the suspect component or id rather than flooding globally, use consistent message ids to filter and trace the log as a queryable database, trigger a stop or waveform dump at the specific failure to capture its fleeting state, reduce noise so the signal surfaces, and above all read the first error first and trace backward from it, because a flood of errors is usually a cascade from one root, and fixing the root collapses the cascade while chasing the loudest symptom wastes days on an effect.

Next — Interrupt Modeling: the next module turns to a specific, ubiquitous verification challenge — interrupts. Real designs raise interrupts asynchronously, and verifying them means modeling the interrupt mechanism, detecting and responding to assertions, and checking the handling and clearing flow. The module opens with interrupt modeling: how to represent an interrupt source and its line in the testbench, observe its assertion, and structure the environment to react to and verify interrupt behavior.