UVM Reporting Facility

How to Read This Lesson

UVM-SystemC is methodology in C++ clothing. Keep the verification intent in view: reusable components, controlled stimulus, reporting, and phase-aware execution.

SystemC provides standard std::cout and the native sc_report_handler for printing messages. However, when working in a large verification environment, you need much more control. You need to be able to filter messages by severity, origin, or verbosity, and you might want errors to automatically terminate the simulation.

The UVM Reporting Facility provides a consistent, configurable message-reporting mechanism as defined in the IEEE 1800.2 standard.

Under the Hood: C++ Implementation in Accellera UVM-SystemC

While SystemC uses sc_report_handler, UVM uses a more distributed architecture. If you look at the Accellera uvm-systemc source code, reporting is handled by a triad of classes:

1. uvm_report_object: As discussed previously, uvm_component inherits from this. It provides the front-end API (uvm_report_info(), macro UVM_INFO).
2. uvm_report_handler: Each uvm_report_object owns a uvm_report_handler. The handler is responsible for storing the verbosity settings, severity overrides, and action overrides specific to that component.
3. uvm_report_server: This is a global singleton accessible via the uvm_coreservice_t. Once a handler decides a message should be printed, it delegates the actual string formatting and printing (to std::cout or a file) to the central uvm_report_server.

When you call UVM_INFO, the macro expands to check the component's uvm_report_handler to see if the message verbosity passes the threshold. If it does, it dynamically allocates a uvm_report_message object, populates it with filename, line number, and context, and sends it to the server.

Source and LRM Trail

For UVM-SystemC, use Docs/LRMs/uvm-systemc-language-reference-manual.pdf as the methodology contract. In source, inspect .codex-src/uvm-systemc/src/uvmsc: components, phases, factory macros, sequences, sequencers, TLM ports, reporting, and configuration helpers.

UVM Severities

Every message in UVM is assigned a severity. The severity indicates the nature of the message and dictates the default action the simulator will take:

1. UVM_INFO: Informative message. Does not affect simulation execution.
2. UVM_WARNING: Indicates a potential problem. Simulation continues, but the warning counter is incremented.
3. UVM_ERROR: Indicates a real problem. Simulation continues, but the error counter is incremented. If the error count reaches a maximum threshold (max_quit_count), the simulation aborts.
4. UVM_FATAL: Indicates a critical problem from which the simulation cannot recover. The simulation is terminated immediately (UVM_EXIT).

UVM Verbosity

While Severities describe what the message is, Verbosity describes how important it is to print. Verbosity levels allow you to leave thousands of debug prints in your code but only print them when you explicitly ask for them.

The standard verbosity levels are:

• UVM_NONE (always printed)
• UVM_LOW
• UVM_MEDIUM (default)
• UVM_HIGH
• UVM_FULL

When you issue a message, you assign it a verbosity. If that verbosity is less than or equal to the configured verbosity of the component (or the global uvm_top), the message is printed.

Complete Reporting Example

Below is a complete, compilable sc_main example that demonstrates reporting macros, modifying verbosity, changing default actions, setting quit counts, and using a report catcher to demote errors.

#include <systemc>
#include <uvm>
 
// 1. Define a Report Catcher to intercept and modify messages
// In the C++ implementation, uvm_report_catcher uses the visitor pattern.
// Before the uvm_report_server prints, it visits all registered catchers.
class my_catcher : public uvm::uvm_report_catcher {
public:
    action_e do_catch() override {
        // If we see an expected error, demote it to an INFO message
        if (get_severity() == uvm::UVM_ERROR && get_id() == "EXPECTED_ERR") {
            set_severity(uvm::UVM_INFO);
            set_message("Error was expected and demoted: " + get_message());
        }
        // Always return THROW to let the message proceed to the output
        return THROW;
    }
};
 
class my_test : public uvm::uvm_test {
public:
    UVM_COMPONENT_UTILS(my_test);
 
    my_test(uvm::uvm_component_name name) : uvm::uvm_test(name) {}
 
    void build_phase(uvm::uvm_phase& phase) override {
        uvm::uvm_test::build_phase(phase);
        
        // Change verbosity for this component and its children
        this->set_report_verbosity_level_hier(uvm::UVM_HIGH);
 
        // Force the simulation to exit on ANY warning from this component
        // (Commented out so we can see the rest of the simulation)
        // this->set_report_severity_action(uvm::UVM_WARNING, uvm::UVM_DISPLAY | uvm::UVM_EXIT);
 
        // Abort simulation after 5 UVM_ERRORs
        uvm::uvm_coreservice_t* cs = uvm::uvm_coreservice_t::get();
        uvm::uvm_report_server* svr = cs->get_report_server();
        svr->set_max_quit_count(5);
    }
    
    void run_phase(uvm::uvm_phase& phase) override {
        phase.raise_objection(this);
 
        // Standard Info messages with varying verbosities
        UVM_INFO("TEST_LOW", "This is a UVM_LOW message.", uvm::UVM_LOW);
        UVM_INFO("TEST_HIGH", "This is a UVM_HIGH message. It prints because we changed the verbosity level.", uvm::UVM_HIGH);
        
        // This will not print, because UVM_FULL > UVM_HIGH
        UVM_INFO("TEST_FULL", "This is a UVM_FULL message and will be hidden.", uvm::UVM_FULL);
 
        // Warning
        UVM_WARNING("TEST_WARN", "Timeout value is suspiciously low.");
 
        // Error that gets caught and demoted by our catcher
        UVM_ERROR("EXPECTED_ERR", "This payload mismatch was expected in this test!");
        
        // Real Error (increments error count)
        UVM_ERROR("REAL_ERR", "An actual error occurred.");
 
        phase.drop_objection(this);
    }
};
 
int sc_main(int argc, char* argv[]) {
    // Register the custom report catcher globally
    my_catcher* catcher = new my_catcher();
    uvm::uvm_report_cb::add(nullptr, catcher);
 
    uvm::run_test("my_test");
    return 0;
}

Using UVM's reporting mechanism guarantees that your testbench logs are consistent, easily parsable by external scripts, and highly configurable at runtime without recompiling code.