Report Catchers

Reporting System · Module 24 · Page 24.3

The Engineering Problem

A third-party VIP emits an UVM_ERROR you know is benign — a spurious complaint that fails your test even though nothing is wrong. You can't (and shouldn't) modify the VIP's source to change the severity. Or your spec says a condition that a component reports as a warning is actually fatal for your design — you need it to fail. Or the log is flooded with a known-noise message that buries the real signal. In all these cases, you need to intervene on the report — change its severity, suppress it, or modify it — without touching the emitting component. The mechanism is the report catcher: a callback on the report path that intercepts every message before the report server processes it (prints, counts, decides pass/fail), and can change it. But this power is double-edged: a catcher that demotes an error to a warning or suppresses it removes it from the pass/fail count — and if that error was actually a real bug, the test passes while the bug ships. The problem this chapter solves is report catchers: what they are (a callback intercepting reports), what they can do (suppress, pass, change severity, modify), their legitimate uses, and the cardinal danger that an over-broad demotion or suppression masks real errors.

A report catcher (uvm_report_catcher) is a callback on the report path that intercepts every report message before the report server processes it and can modify or act on it. Its catch() method inspects the report and returns one of two dispositions: THROW (pass it through to the server — the default) or CAUGHT (suppress it — dropped, not printed, not counted). Within catch(), it can change the severity (set_severity — promote a warning to an error to fail on a known-bad condition, or demote an error to a warning to waive a known-benign one), modify the report (set_message, set_id), or count/track it. It is built on the callback mechanism (Module 22) — the report server calls out to registered catchers — so it's registered (globally or targeted by id/component) and non-intrusive (the emitting component is untouched). The legitimate uses: demote a documented, known-benign error (a justified waiver), promote a warning your spec deems fatal, suppress known noise, count events. The cardinal danger: demoting or suppressing a real error masks a bug — so catchers must be narrowly scoped (exact id + component), justified, and documented — exactly like a coverage waiver (Module 19.7), because an over-broad catcher swallows the real errors it wasn't meant to touch. This chapter is report catchers: the interception mechanism, the actions, the uses, and the masking danger.

What is a report catcher — how does it intercept and modify reports before the report server processes them, what can it do (suppress, pass, change severity, modify), what are its legitimate uses, and why does an over-broad demotion or suppression mask real errors?

Motivation — why intervene on reports at all

Sometimes the report is wrong for your context — too severe, too noisy, or under-rated — and you can't fix the emitter. The reasons report catchers exist:

• You can't modify the emitting component. A third-party VIP, a shared component, or a sealed IP emits a report you need to handle differently — but editing its source is off-limits (breaks reuse, Module 22.1). A catcher lets you intervene on the report non-intrusively.
• Severity is context-dependent. A warning in general might be fatal for your spec (promote it); an error from a known-benign condition might be acceptable for your setup (demote it, with justification). The emitter can't know your context; the catcher adjusts severity for it.
• Known noise buries the signal. A frequent, benign message floods the log and hides the real failures. Suppressing it (CAUGHT) cleans the log so the real signal is visible.
• Reports carry information worth counting. A component's reports can mark events (a protocol transition, a retry); a catcher can count or act on them without the emitter providing a separate hook.
• But it's a waiver mechanism — dangerous if misused. Demoting or suppressing an error is a waiver of that failure — and like any waiver, it can hide a real bug if over-broad or unjustified. The power to change severity demands the discipline to scope and justify it.

The motivation, in one line: you intervene on reports because severity is context-dependent (a warning fatal for your spec, an error benign for your setup) and you can't modify the emitter (third-party/sealed), so a catcher adjusts severity, suppresses noise, or counts events non-intrusively — but because demoting/suppressing an error is a waiver of that failure, the power demands discipline: narrow scope and justification, or it masks real bugs.

Mental Model

Hold a report catcher as a checkpoint inspector on the message road — every report passes through, and the inspector can let it through, confiscate it, re-stamp its severity, or edit it:

Every report message travels a road from the component that emitted it to the report server that processes it — prints it, counts it, and decides pass/fail. A report catcher is a checkpoint inspector standing on that road, and every message passes through the checkpoint before reaching the server. The inspector has four powers. Let it through (throw): wave the message on unchanged — the default. Confiscate it (caught): take the message off the road entirely, so it never reaches the server — not printed, not counted, gone. Re-stamp its severity: change an error stamp to a warning (demote) or a warning to an error (promote), so the server treats it differently. And edit it: rewrite the message text or id. These powers are legitimate and useful: you can confiscate a known-noise message to keep the road clear, re-stamp a third-party VIP's spurious error down to a warning so it doesn't fail your run (with a documented note explaining why), or re-stamp a warning up to an error because your spec says it's critical. But the inspector is also a point of enormous danger, because confiscating or downgrading a message removes it from the count that decides pass/fail — and if the inspector is briefed too broadly ("downgrade all errors of this severity," "confiscate anything from this area"), it will also downgrade or confiscate real errors it was never meant to touch, and those failures vanish silently while the run reports clean. So the inspector must be briefed narrowly — act only on this exact message id, from this exact component, for this documented reason — or it becomes a censor that hides the failures it wasn't supposed to see. Picture every report message traveling a road from the emitting component to the report server (which prints, counts, decides pass/fail). A report catcher is a checkpoint inspector on that road — every message passes through before reaching the server. The inspector has four powers: let it through (THROW — wave it on, the default); confiscate it (CAUGHT — take it off the road, so it never reaches the server — not printed, not counted, gone); re-stamp its severity (error→warning demote, warning→error promote); and edit it (rewrite the message/id). These are legitimate: confiscate known-noise to keep the road clear, re-stamp a VIP's spurious error down (with a documented note), or re-stamp a warning up because your spec says critical. But the inspector is a point of enormous danger: confiscating or downgrading a message removes it from the pass/fail count — and if briefed too broadly ("downgrade all errors of this severity"), it also downgrades real errors it was never meant to touch, and those failures vanish silently while the run reports clean. So the inspector must be briefed narrowly — only this exact id, from this exact component, for this documented reason — or it becomes a censor that hides the failures it wasn't supposed to see.

So a report catcher is a checkpoint inspector on the message road: every report passes through, and the inspector can let it through (THROW), confiscate it (CAUGHT/suppress), re-stamp its severity (promote/demote), or edit it. Legitimate for documented waivers (demote known-benign, with a note), escalations (promote a spec-critical warning), and noise suppression — but dangerous because confiscating/downgrading removes a message from the pass/fail count, so an over-broad inspector hides real failures. Brief the inspector narrowly (exact id + component + documented reason), or it censors the very failures it wasn't meant to touch. Intercept reports to waive, escalate, or clean — but brief the catcher narrowly, or it masks the real errors it was never meant to touch.

Visual Explanation — the catcher on the report path

The defining picture is the interception: the report passes through the catcher before the report server processes it.

The figure shows the catcher intercepting on the report path. A component emits a report (the brand-colored top — uvm_info/uvm_warning/uvm_error/uvm_fatal, with severity, id, text). Before the report server processes it, the report passes through report catchers (the warning-colored layer — each catch() inspects and either THROWs (pass on, maybe modified) or CAUGHTs (suppress)). Only thrown reports reach the server, which prints, routes to logs, and counts toward pass/fail — feeding the pass/fail count (error/fatal counts decide the result). The crucial reading is the position of the catcher — between the emitter and the server — and what that position means: the catcher sees every report before it's processed, with the power to modify or remove it before it's counted. This is why the catcher is powerful: it can change a report's severity (so the server counts it differently) or suppress it (so the server never sees it). And it's why it's dangerous: a caught or demoted error never reaches the pass/fail count — so an over-broad catcher can silently drop real errors before they'd fail the test. The warning-colored catcher layer is highlighted because it's where the interception (and the risk) lives: it's a gate on the pass/fail-determining path. The success-colored server and count are downstream — they only see what the catcher let through. So the report server's verdict (pass/fail) is only as trustworthy as the catchers are narrow — a broad catcher upstream can manufacture a passing result by swallowing errors. The diagram is the report path: emit → catchers (intercept: throw/catch/modify) → server (print/count) → pass/fail — with the catcher a gate that every report passes through before being counted. The catcher intercepts every report before the server counts it — modifying or removing it ahead of the pass/fail decision.

RTL / Simulation Perspective — writing a catcher and its actions

In code, a catcher is a class with a catch() method returning THROW/CAUGHT, registered on the report path. The example shows a narrowly-scoped demotion, a promotion, suppression, and the registration.

// === A REPORT CATCHER: intercept reports, act in catch() ===
class my_catcher extends uvm_report_catcher;
  virtual function action_e catch();
    // (1) DEMOTE a SPECIFIC known-benign error to a warning — NARROWLY scoped (exact id + component)
    if (get_severity() == UVM_ERROR && get_id() == "VIP_SPURIOUS" &&
        get_context() == "uvm_test_top.env.tpz_vip") begin
      set_severity(UVM_WARNING);                 // documented waiver: VIP-TICKET-123, known-benign
      return THROW;                              // pass it on (now as a warning)
    end
    // (2) PROMOTE a warning your spec deems fatal — exact id
    if (get_severity() == UVM_WARNING && get_id() == "OVERFLOW_NEAR") begin
      set_severity(UVM_ERROR); return THROW;     // your spec: this must fail
    end
    // (3) SUPPRESS known noise — exact id
    if (get_id() == "CHATTY_DEBUG") return CAUGHT;   // dropped: not printed, not counted
    // (4) everything else: pass through unchanged
    return THROW;
  endfunction
endclass
 
// === REGISTER the catcher on the report path (built on the callback mechanism, Module 22) ===
my_catcher cat = new();
uvm_report_cb::add(null, cat);     // global; or add(specific_component, cat) to TARGET it
 
// ✗ DANGER: a BROAD demote/suppress masks REAL errors (DebugLab):
//   if (get_severity() == UVM_ERROR) set_severity(UVM_WARNING);  // ← demotes ALL errors → bug ships!

The code shows a report catcher and its actions. The catch() method inspects each report (get_severity(), get_id(), get_context()) and acts: (1) Demote a specific known-benign error to a warning — narrowly scoped (exact id "VIP_SPURIOUS" and exact component "...tpz_vip"), with a documented waiver note (VIP-TICKET-123), returning THROW (pass it on, now as a warning). (2) Promote a warning your spec deems fatal (exact id "OVERFLOW_NEAR") to an error. (3) Suppress known noise (exact id "CHATTY_DEBUG") — return CAUGHT (dropped: not printed, not counted). (4) Everything else — return THROW (pass through unchanged). The catcher is registered on the report path (uvm_report_cb::add(null, cat) — global; or add(specific_component, cat) to target it), built on the callback mechanism (Module 22). The danger (commented) is a broad demote — if (get_severity() == UVM_ERROR) set_severity(UVM_WARNING) — which demotes all errors → a real bug ships (the DebugLab). The shape to carry: a catcher's catch() matches narrowly (exact id and component) and acts (demote/promote/suppress/modify), returning THROW (pass, maybe modified) or CAUGHT (suppress). The narrow matching (1) is what makes a demotion safe — it only affects the one known-benign report, with a documented reason — versus the broad matching (the danger) that swallows all errors. The promotion (2) and suppression (3) are similarly scoped by exact id. The registration (global vs targeted) also scopes the catcher's reach — add(specific_component, ...) limits it to one component's reports. The demote should carry justification (the comment VIP-TICKET-123 stands for a documented waiver). Match narrowly by exact id and component, act (demote/promote/suppress) with justification, and never demote broadly.

Verification Perspective — the catcher's actions and the legitimate-versus-dangerous line

The catcher's power is four actions — and the line between legitimate and dangerous use runs through demote/suppress. Seeing the actions and the line clarifies responsible use.

The figure shows the catcher's actions and the legitimate-versus-dangerous line. Throw / modify / promote (the success-colored — safe): throw passes a report on unchanged (always safe); modify rewrites the text or id (cosmetic, safe); promote raises severity (warning→error) — safe, it makes the test stricter. Demote / suppress (the warning-colored — the waiver actions): both remove a report from the pass/fail count — legitimate only when narrowly scoped to a documented, known-benign report, and dangerous when broad (they then mask real errors). The verification insight is that not all four actions carry the same risk — and the risk runs through demote/suppress. Throw (no change) and modify (cosmetic) can't hide a failure. Promote can't hide a failure either — it adds strictness (more things fail), which is safe (at worst, it over-fails, which you'd notice). But demote (error→warning) and suppress (CAUGHT) remove an error from the pass/fail count — so they're waivers of failures, and like any waiver (Module 19.7), they're legitimate only when narrow and documented (this exact known-benign report, for this reason) and dangerous when broad (they also waive real errors). The success-colored safe actions (throw/modify/promote) and the narrow+documented demote/suppress are legitimate; the default-colored broad demote/suppress masks real errors. The practical rule: promote freely (stricter is safe), modify cosmetically, but treat every demote and suppress as a waiver — scope it narrowly (exact id + component), justify it, document it, and never apply it broadly. The diagram is the risk map: throw/modify/promote → safe; demote/suppress → a waiver, safe only if narrow+documented, dangerous if broad — the line between responsible and masking use. Promote and modify are safe; demote and suppress are waivers — narrow and document them, or they mask real errors.

Runtime / Execution Flow — a report passing through the catcher

At run time, each report flows through the catcher's catch(), which decides its fate — pass, modify, demote/promote, or suppress — before the server counts it. The flow shows it.

The flow shows a report passing through the catcher. Emit (step 1): a component emits a report with a severity, id, and context. Match (step 2): catch() matches it against the catcher's criteria — is this the exact id and component this catcher acts on? — the narrow match decides whether it's touched. Act (step 3): on a match, demote/promote/suppress/modify; on no match, throw it through untouched. Count (step 4): thrown reports (maybe modified) reach the server's pass/fail count; caught reports are dropped before it. The runtime insight is that the match is the gate — it determines whether the catcher touches the report at all. A narrow match (exact id + component) means the catcher acts on only the intended reports and throws everything else unchanged — so it can't affect unrelated reports. A broad match (by severity alone, or a loose id) means the catcher acts on many reports — including ones it wasn't meant to touch. So the match scope is what makes a catcher safe or dangerous: narrow → surgical (only the known-benign report); broad → indiscriminate (any matching error, real or not). This is why the catch() logic must match narrowly — it's the guard that limits the catcher's reach. The every-report-flows-through design (step 1→2) means every report is subject to the catcher's match, so a broad match has broad reach. The brand-colored emit/match feed the success-colored act-or-throw, and thrown reports reach the default-colored server count (caught are dropped). The flow is the catch() decision: emit → match (narrow?) → act (if match) or throw (if not) → server counts thrown — and the match scope is the safety control. Every report flows through the catcher's match; a narrow match touches only the intended reports, a broad one reaches reports it shouldn't.

Waveform Perspective — a narrowly-scoped catcher demoting one error id

The catcher's effect is visible on the report stream: a matching error (the one id the catcher targets) is demoted (so the error count doesn't increment), while a non-matching error passes through (and does count). The waveform shows the narrow demotion.

The waveform shows a narrowly-scoped catcher in action. Reports flow by. The catcher targets only error id VIP_SPURIOUS. When that report arrives (report_id=VIP), it matches (catcher_match), is demoted to a warning (sev_out=WARN), so the error count does not increment — the known-benign error is waived. When a different error arrives (report_id=REAL), it does not match, passes through unchanged (sev_out=ERR), and the error count increments (err_count→1) — the real error still fails the test. The crucial reading is the selectivity of the narrow catcher: it acts on its one target (VIP_SPURIOUS → demoted, waived) and leaves everything else untouched (REAL → passes as ERR, counts, fails). The error count tells the story: it stays 0 through the benign (demoted) error and increments on the real one — so the test fails on the real error, exactly as it should, while the benign one is waived. This is the signature of a responsible catcher: it waives the one documented benign report and does not touch the real failures. The contrast (the DebugLab) is a broad catcher that demotes REAL too (because it matched by severity alone) — which would leave err_count=0 and the test passing despite the real bug. The picture to carry is that the narrow match is what separates waiving the benign from masking the real: the catcher touches only its target, so the real error survives to fail. Reading the waveform this way — does the catcher demote only its target, leaving real errors to count? — is seeing a responsible catcher. The benign error demoted (count stays 0) while the real error passes (count increments, test fails) is the signature of a narrow, documented catcher doing its job without masking anything. A narrow catcher demotes only its target; the real error it doesn't match still counts and fails the test — which is exactly the point.

DebugLab — the broad catcher that demoted a real bug to a warning

✗ BROAD demote — matches ALL errors by severity alone:
  virtual function action_e catch();
    if (get_severity() == UVM_ERROR) begin    // ← matches EVERY UVM_ERROR, from ANY component!
      set_severity(UVM_WARNING); return THROW; //   the intent was ONE benign VIP error...
    end                                         //   ...but this demotes the DUT's REAL error too
    return THROW;
  endfunction
  // → every real UVM_ERROR becomes a warning → err_count stays 0 → regression PASSES → bug SHIPS
 
✓ NARROW demote — match the SPECIFIC known-benign report (exact id + component), documented:
  virtual function action_e catch();
    if (get_severity() == UVM_ERROR && get_id() == "VIP_SPURIOUS" &&     // EXACT id
        get_context() == "uvm_test_top.env.tpz_vip") begin               // EXACT component
      set_severity(UVM_WARNING); return THROW;   // waiver: VIP-TICKET-123, known-benign, documented
    end
    return THROW;   // ALL other errors — including the DUT's real one — pass through and COUNT
  endfunction

Common Mistakes

• Demoting or suppressing by severity alone. Matching all errors of a severity waives real errors too; match the exact id and component.
• Treating a demotion as harmless. A demote or suppress is a waiver of a failure; an unjustified or broad one masks bugs — justify and document each.
• Over-broad registration. A global catcher with a loose match touches reports across the testbench; target by component and match narrowly.
• Forgetting catchers outlive their reason. A catcher added for one waiver can keep masking after the underlying issue is fixed; review and remove stale catchers.
• Promoting where a demote was meant (or vice versa). Promote raises severity (stricter, safe); demote lowers it (a waiver, risky) — use the right direction deliberately.
• Suppressing real signal as noise. A suppress meant for noise can drop meaningful messages if the id is loose; confirm the suppressed id is genuinely benign noise.

Senior Design Review Notes

Interview Insights

Exercises

1. Write a narrow demote. Write a catch() that demotes only a specific VIP error by id and component, with everything else passing through.
2. Spot the over-broad catcher. Given a catch() matching by severity alone, explain what it masks and how to narrow it.
3. Promote a warning. Write a catch() that promotes a spec-critical warning to an error, and explain why promotion is safe.
4. Justify a waiver. Describe what documentation a demotion catcher should carry to be a legitimate, accountable waiver.

Summary

• A report catcher (uvm_report_catcher) is a callback on the report path that intercepts every report before the report server processes it (prints, counts, decides pass/fail) and can modify or act on it — catch() returns THROW (pass through) or CAUGHT (suppress).
• Within catch(), it can change severity (set_severity — promote a warning to an error, or demote an error to a warning), modify the message/id, or count/track; it is built on the callback mechanism (Module 22), registered globally or targeted, and non-intrusive.
• Legitimate uses: demote a documented, known-benign error (a justified waiver), promote a warning your spec deems fatal, suppress known noise, count events — promote and modify are safe (stricter/cosmetic); demote and suppress are waivers of failures.
• The cardinal danger: demoting or suppressing too broadly (by severity alone or a loose id) removes real errors from the pass/fail count, so the test passes while the bug ships — masking failures the catcher wasn't meant to touch.
• The durable rule of thumb: a report catcher intercepts reports before the server counts them, so it can demote, suppress, promote, or modify — but a demote or suppress is a waiver of a failure, so scope every catcher narrowly to the exact id and component, justify and document each like a coverage waiver, prefer safe promotions and cosmetic modifications, review catchers so they don't outlive their reason, and never demote or suppress by severity alone, because an over-broad catcher silently swallows the real errors it should have left to fail.

Next — Report Server: with catchers in hand, the next chapter examines the engine they plug into — the report server. How the central report server receives every report after the catchers, applies actions per severity (display, log, count, exit), tallies the error and fatal counts that decide pass/fail, formats and routes messages, and how customizing the report server tailors the whole reporting behavior of the testbench.