The Report Catcher Is a Callback

Treat report catchers as callbacks in a uvm_callbacks pool. Control which reporters each one sees and in what order, chain changes, stop a report, and read the diagnostics.

You Will Be Able To

  • Attach a catcher to one reporter, a name pattern or every reporter, and remove it.
  • Read and change a report in catch(), and choose THROW or CAUGHT.
  • Predict the result of several catchers in a chain.
  • Debug catchers: the double copy and the shared queue of uvm-core 2020.3.1, print_catcher, get_report_catcher, debug_report_catcher and issue().
Lesson
U18.6
Time
30 min
Runs on
Verilator with UVM
Check
4 questions

A test counted expected errors with a catcher added to every reporter, and required exactly three. The run failed with six, although the log showed three. A second catcher had been added to the scoreboard alone, and that add copied the counting catcher into the scoreboard's queue twice.

ReporterReportstap counted
agent_a1 (plus 1 dropped by quiet)1
agent_b11
sb36

Measured in the example on uvm-core 2020.3.1. sb gained its own queue while tap was already typewide.

A Catcher Is a Callback

uvm_report_catcher extends uvm_callback, and uvm_report_cb is uvm_callbacks #(uvm_report_object, uvm_report_catcher). Every reporter calls its catchers before the report server sees a report, through the same pool as lane_cb. U18.2's rules apply, and so do two uvm-core surprises below.

CallWhich reports the catcher sees
uvm_report_cb::add(sb, c)sb's own reports only, not its children's
uvm_report_cb::add(null, c)Every reporter, including ones built later
uvm_report_cb::add_by_name("*.sb", c, root)Every component under root whose full name matches, at the time of the call
uvm_report_cb::delete(sb, c)Stops at once; the catcher keeps its counters

Order follows the queue: an instance add appends after the typewide catchers copied in; UVM_PREPEND goes first.

In uvm-core 2020.3.1 the queue an object owns is shared by every callback type: the pool keeps one queue per object. So a catcher added to a driver gives the driver its own queue for its lane callbacks too. That queue is seeded from the report catchers' typewide queue, so typewide lane callbacks added earlier stop running there.

What catch() Can Do

catch() reads the report with get_severity, get_id, get_message, get_verbosity, get_action, get_fname, get_line and get_client, the reporter. It may change it with set_severity, set_id, set_message, set_verbosity, set_action and set_context, and attach data with add_int, add_string and add_object.

It returns THROW to pass the report on, or CAUGHT to end it. A changed severity also changes the default action unless the catcher called set_action: a warning made an error is counted as an error.

issue() hands the report, as it is now, to the server at once: it prints and counts. The catcher still returns THROW or CAUGHT afterwards. With THROW the report goes on and reaches the server a second time; with CAUGHT it stops after the one issue().

Several Catchers in a Row

agent_b's Warning Through Its CatchersThe example at 20 ns. agent_b's own queue holds quiet, quiet, translate, promote, tap. Arrows are the report passing on; the server prints and counts.
  • Agent
  • Step
  • Tool
  • Data
agent_b's warning through its catchersThe example at 20 ns. agent_b's own queue holds quiet, quiet, translate, promote, tap. Arrows are the report passing on; the server prints and counts. agent agent_b `uvm_warning("OLD_TMO",...) step quiet drops NOISE infos; THROW step translate OLD_TMO -> TIMEOUT;THROW step promote TIMEOUT warning -> error;THROW step tap counts; THROW tool report server prints and countsUVM_ERROR OLD_TMO warningunchangedTIMEOUT warningTIMEOUT errorTIMEOUT error
  1. agent agent_b`uvm_warning("OLD_TMO", ...)
    • OLD_TMO warning → quiet
  2. step quietdrops NOISE infos; THROW
    • unchanged → translate
  3. step translateOLD_TMO -> TIMEOUT; THROW
    • TIMEOUT warning → promote
  4. step promoteTIMEOUT warning -> error; THROW
    • TIMEOUT error → tap
  5. step tapcounts; THROW
    • TIMEOUT error → report server
  6. tool report serverprints and counts UVM_ERROR
  1. Filters run first

    The report starts at the front of agent_b's queue. quiet ignores warnings and throws it on.

  2. A change flows on

    translate renames the ID to TIMEOUT. The next catcher sees the changed report, so promote finds a TIMEOUT warning and makes it an error.

  3. Last in line

    tap counts it, and the server prints UVM_ERROR ... [TIMEOUT] and counts it. A catcher returning CAUGHT would have ended the walk there.

Read the diagram as text
  • agent_b: `uvm_warning("OLD_TMO", ...)
  • quiet: drops NOISE infos; THROW
  • translate: OLD_TMO -> TIMEOUT; THROW
  • promote: TIMEOUT warning -> error; THROW
  • tap: counts; THROW
  • report server: prints and counts UVM_ERROR
  • agent_b → quiet: OLD_TMO warning
  • quiet → translate: unchanged
  • translate → promote: TIMEOUT warning
  • promote → tap: TIMEOUT error
  • tap → report server: TIMEOUT error

Swap translate and promote and the warning stays a warning: promote sees OLD_TMO.

Each catcher sees the report as the catchers before it left it. That makes order part of the meaning: translate must run before promote. CAUGHT stops the walk: quiet drops agent_a's NOISE info, and tap, after it, never counts it.

The Double Copy

In uvm-core 2020.3.1 the first instance add on any component copies two typewide queues. They are the report catchers' queue, then the pool type's own. For a report catcher those are the same queue. So every typewide catcher lands in the reporter's queue twice.

sb gained its own queue at 20 ns, when add_by_name opened the window for demote. quiet and tap were typewide by then, so sb's queue held each of them twice. tap counted sb's three reports six times. agent_b got its queue in connect_phase, before tap was added, so tap reached it once.

uvm_report_cb::get_all(list, sb) hides the double copy: it removes duplicates before it returns. To see what really runs, walk the queue with get_first and get_next, as the report path does.

Diagnostics and Patterns

uvm_report_catcher::summarize() runs at the end of every test and prints how many reports catchers demoted and caught, by severity. print_catcher() lists the typewide catchers; get_report_catcher(name) finds one by name. Both walk the typewide queue with an iterator that skips switched-off catchers. So they miss instance catchers, and a catcher you switched off vanishes from the list instead of showing OFF.

debug_report_catcher(flags) is for debugging: DO_NOT_CATCH makes CAUGHT act like THROW, and DO_NOT_MODIFY undoes every catcher's changes. Reports then show what they would have been. The example lists the catchers, switches quiet off by name, then repeats agent_b's timeout under DO_NOT_MODIFY. It prints as the plain OLD_TMO warning.

PatternHow
Expect exactly N errorsMatch severity, ID and reporter; demote; count; check the count in check_phase
Translate a legacy VIPRename IDs with set_id; later catchers see the new ID
Promote chosen warningsset_severity(UVM_ERROR) on one reporter's ID; THROW
A windowadd or add_by_name when the injection starts, delete or delete_by_name when it ends

U16.1 builds the first pattern; the example uses all four. U18.6.1 counts per reporter.

Try It

agent_a's OLD_TMO stays a warning: only agent_b has translate and promote. The two DATA errors inside the window print as infos with expected:; the third, after delete, is a real error. The first NOISE info never prints. The catcher summary counts the two demotions.

The debug part lists the typewide catchers, quiet and tap, then switches quiet off by name. The second NOISE info prints, and agent_b's timeout under DO_NOT_MODIFY prints as the plain OLD_TMO warning.

Move print_catcher after the switch and run again: the list shows tap only. It skips switched-off catchers instead of marking them OFF.

Swap the two uvm_report_cb::add(agent_b, ...) lines and run again. Then add tap before the add_by_name window only, and watch sb's count fall to 3.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: UVM_WARNING main.sv(12) @ 10: uvm_test_top.agent_a [OLD_TMO] no response in 64 clocks UVM_ERROR main.sv(12) @ 20: uvm_test_top.agent_b [TIMEOUT] no response in 64 clocks UVM_INFO main.sv(13) @ 30: uvm_test_top.sb [DATA] expected: read 2: got 21, expected 20 UVM_INFO main.sv(13) @ 40: uvm_test_top.sb [DATA] expected: read 4: got 41, expected 40 UVM_ERROR main.sv(13) @ 50: uvm_test_top.sb [DATA] read 6: got 61, expected 60 tap saw: agent_a 1, agent_b 1, sb 6; demote caught 2; errors counted 2 quiet : ON tap : ON UVM_INFO main.sv(11) @ 55: uvm_test_top.agent_a [NOISE] idle again UVM_WARNING main.sv(12) @ 60: uvm_test_top.agent_b [OLD_TMO] no response in 64 clocks Number of demoted UVM_ERROR reports : 2

Check Yourself

Predict the outputThe example, with agent_b's two catchers added in the other order: promote, then translate. What line does the $display print?
`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;

// Three reporters. Each says what the test tells it to, at a set time.
class reporter extends uvm_component;
  `uvm_component_utils(reporter)
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task say(uvm_severity sev, string id, string msg);
    case (sev)
      UVM_INFO:    `uvm_info(id, msg, UVM_LOW)
      UVM_WARNING: `uvm_warning(id, msg)
      UVM_ERROR:   `uvm_error(id, msg)
    endcase
  endtask
endclass

// A legacy agent reports response timeouts as OLD_TMO. Rename them to the project's TIMEOUT ID.
class translate_c extends uvm_report_catcher;
  function new(string name = "translate_c"); super.new(name); endfunction
  function action_e catch();
    if (get_id() == "OLD_TMO") set_id("TIMEOUT");
    return THROW;
  endfunction
endclass

// On agent_b, a TIMEOUT warning is a real failure: make it an error.
class promote_c extends uvm_report_catcher;
  function new(string name = "promote_c"); super.new(name); endfunction
  function action_e catch();
    if (get_severity() == UVM_WARNING && get_id() == "TIMEOUT") set_severity(UVM_ERROR);
    return THROW;
  endfunction
endclass

// The scoreboard's DATA errors are expected while the injection window is open.
class demote_c extends uvm_report_catcher;
  int seen;
  function new(string name = "demote_c"); super.new(name); endfunction
  function action_e catch();
    if (get_severity() != UVM_ERROR || get_id() != "DATA") return THROW;
    seen++;
    set_severity(UVM_INFO);
    set_message({"expected: ", get_message()});
    return THROW;
  endfunction
endclass

// Drop the noisy NOISE infos everywhere.
class quiet_c extends uvm_report_catcher;
  function new(string name = "quiet_c"); super.new(name); endfunction
  function action_e catch();
    if (get_severity() == UVM_INFO && get_id() == "NOISE") return CAUGHT;
    return THROW;
  endfunction
endclass

// Counts every report it is shown, by reporter name.
class tap_c extends uvm_report_catcher;
  int seen[string];
  function new(string name = "tap_c"); super.new(name); endfunction
  function action_e catch();
    string who = get_client().get_name();
    if (!seen.exists(who)) seen[who] = 0;
    seen[who]++;
    return THROW;
  endfunction
endclass

class catch_test extends uvm_test;
  `uvm_component_utils(catch_test)
  reporter    agent_a, agent_b, sb;
  translate_c translate;
  promote_c   promote;
  demote_c    demote;
  quiet_c     quiet;
  tap_c       tap;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    agent_a   = reporter::type_id::create("agent_a", this);
    agent_b   = reporter::type_id::create("agent_b", this);
    sb        = reporter::type_id::create("sb", this);
    translate = new("translate");
    promote   = new("promote");
    demote    = new("demote");
    quiet     = new("quiet");
    tap       = new("tap");
  endfunction
  function void connect_phase(uvm_phase phase);
    uvm_report_cb::add(null, quiet);                       // every reporter
    uvm_report_cb::add(agent_b, promote);
    uvm_report_cb::add(agent_b, translate);
    uvm_report_cb::add(null, tap);                         // every reporter, after quiet
    uvm_root::get().set_report_id_action("UVM/REPORT/CATCHER", UVM_NO_ACTION);   // no catcher summary
  endfunction
  task run_phase(uvm_phase phase);
    phase.raise_objection(this);
    #10 agent_a.say(UVM_WARNING, "OLD_TMO", "no response in 64 clocks");
    #10 agent_b.say(UVM_WARNING, "OLD_TMO", "no response in 64 clocks");
    uvm_report_cb::add_by_name("*.sb", demote, this);      // open the injection window
    #10 sb.say(UVM_ERROR, "DATA", "read 2: got 21, expected 20");
    #5  agent_a.say(UVM_INFO, "NOISE", "idle");
    #5  sb.say(UVM_ERROR, "DATA", "read 4: got 41, expected 40");
    uvm_report_cb::delete(sb, demote);                     // close it
    #10 sb.say(UVM_ERROR, "DATA", "read 6: got 61, expected 60");
    phase.drop_objection(this);
  endtask
  function void show();
    uvm_report_server srv = uvm_report_server::get_server();
    $display("tap saw: agent_a %0d, agent_b %0d, sb %0d; demote caught %0d; errors counted %0d",
             tap.seen["agent_a"], tap.seen["agent_b"], tap.seen["sb"], demote.seen, srv.get_severity_count(UVM_ERROR));
  endfunction
  function void report_phase(uvm_phase phase); show(); endfunction
endclass

module tb;
  initial run_test("catch_test");
endmodule
ConceptWhich catcher call covers every report from the scoreboard env.sb and nothing else?
ConceptA catcher demotes an expected error with set_severity(UVM_INFO) and returns CAUGHT. What does the log show for that report?
ConceptA test calls uvm_report_catcher::get_report_catcher("demote") while demote is attached to env.sb only. What does it return?

Common Mistakes

Wrong Attach a catcher to the environment to cover the scoreboard inside it.

An instance catcher sees only its own object's reports, not its children's.

Fix Attach it to the reporter itself, or use add_by_name with a pattern that names it.

Wrong Return CAUGHT from a catcher that should change a report.

CAUGHT ends the report: it is not printed, not counted, and later catchers never see it.

Fix Change it with set_severity or set_id and return THROW.

Wrong Add a typewide counting catcher, then instance catchers on some reporters.

In uvm-core 2020.3.1 each first instance add copies the typewide catchers twice, so the counter runs twice there.

Fix Add instance catchers first and typewide ones after, or keep typewide catchers free of counting.

Remember

  • uvm_report_cb is an ordinary callback pool: instance, typewide and by-name adds, deletes and order work as in U18.2.
  • catch() may change a report and THROW it on; CAUGHT ends it, unprinted and uncounted.
  • Each catcher sees the report as earlier catchers left it, so order is part of the meaning.
  • uvm-core 2020.3.1: a first instance catcher copies the typewide catchers twice. Its queue serves every callback type, so earlier typewide callbacks of other types stop.
  • print_catcher and get_report_catcher see enabled typewide catchers only; debug_report_catcher undoes changes or catches; issue() sends the report at once.

Practice

Report a problem with this page