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_catcherandissue().
- 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.
| Reporter | Reports | tap counted |
|---|---|---|
| agent_a | 1 (plus 1 dropped by quiet) | 1 |
| agent_b | 1 | 1 |
| sb | 3 | 6 |
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.
| Call | Which 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
- Step
- Tool
- Data
- Filters run first
The report starts at the front of agent_b's queue.
quietignores warnings and throws it on. - A change flows on
translaterenames the ID to TIMEOUT. The next catcher sees the changed report, sopromotefinds a TIMEOUT warning and makes it an error. - Last in line
tapcounts it, and the server printsUVM_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.
| Pattern | How |
|---|---|
| Expect exactly N errors | Match severity, ID and reporter; demote; count; check the count in check_phase |
| Translate a legacy VIP | Rename IDs with set_id; later catchers see the new ID |
| Promote chosen warnings | set_severity(UVM_ERROR) on one reporter's ID; THROW |
| A window | add 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.
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 : 2Check Yourself
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_cbis 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_catcherandget_report_catchersee enabled typewide catchers only;debug_report_catcherundoes changes or catches;issue()sends the report at once.