Reporting Classes

In SystemVerilog, messages are usually printed with $display:
$display ("%t addr = 0x%0h data = 0x%0h", addr, data);

With plain $display, there is no way to tell whether a message is informational, a debug detail, a warning, an error or a fatal problem. It is also hard to keep the same format across hundreds of files. The UVM reporting classes solve this. They issue every message with a consistent format, let you choose what action to take and which file to write to based on severity, ID or both, and filter messages by verbosity.

8 min read | Intermediate Level

What You'll Learn

• The four UVM reporting classes and the role each plays
• How severity, verbosity, ID and action decide what happens to a message
• Configure verbosity, actions and log files per component or per ID
• Use the report server and a report catcher to control test results

Why Not Just Use $display?

The UVM Reporting Classes

Reporting in UVM is split across four main classes. You rarely create them yourself, but knowing what each one does tells you where to configure a behavior.

Every component is a report object, so a driver, monitor or test can report directly. Sequences and sequence items are not components, but they also support the reporting macros. Their messages are routed through the sequencer they run on, or through the top of the hierarchy if there is none.

A message first passes the verbosity check in the report object. The handler then attaches the action and file configured for its severity and ID. Any registered catchers can change or drop it, and finally the server formats it and carries out the actions.

Severity, Verbosity and Actions

Severity

Each message has one of four severities, and each severity has a default action.

Verbosity

Verbosity sets how much detail you want to see. Each component has a verbosity threshold, UVM_MEDIUM by default. A message is printed only if its verbosity is less than or equal to that threshold.

Actions

An action tells the server what to do with a message. Actions are bit flags, so they are combined with |. The most common are UVM_DISPLAY (print to the console), UVM_LOG (write to a file), UVM_COUNT (add to the quit count), UVM_EXIT (end the simulation), UVM_STOP (call $stop) and UVM_NO_ACTION (do nothing).

Syntax

Messages are normally issued through the reporting macros, which add the file name and line number for you. These are covered in detail in Reporting Functions.

`uvm_info    (ID, MESSAGE, VERBOSITY)   // Only info messages take a verbosity
`uvm_warning (ID, MESSAGE)
`uvm_error   (ID, MESSAGE)
`uvm_fatal   (ID, MESSAGE)

• ID - a short string that names the message type, such as "DRV" or "SCB_MISMATCH". Configuration can target it (required)
• MESSAGE - the text, usually built with $sformatf (required)
• VERBOSITY - one of the levels above, for `uvm_info only (required)

Configuring Reports

Because every component is a report object, its reporting behavior can be changed from outside, usually from the test. Each set_report_* function also has a _hier version that applies to the component and everything below it.

class my_test extends uvm_test;
  `uvm_component_utils (my_test)
  // Rest of the code (constructor, build_phase, etc.)

  UVM_FILE m_err_log;

  virtual function void end_of_elaboration_phase (uvm_phase phase);
    super.end_of_elaboration_phase (phase);

    // 1. Show UVM_HIGH messages from the env and all components below it
    m_env.set_report_verbosity_level_hier (UVM_HIGH);

    // 2. Silence one known, harmless message ID everywhere in the env
    m_env.set_report_id_action_hier ("DRV_IDLE", UVM_NO_ACTION);

    // 3. Also write every error to a separate file, and keep counting them
    m_err_log = $fopen ("errors.log", "w");
    m_env.set_report_severity_file_hier (UVM_ERROR, m_err_log);
    m_env.set_report_severity_action_hier (UVM_ERROR, UVM_DISPLAY | UVM_LOG | UVM_COUNT);
  endfunction
endclass

When more than one setting matches a message, the most specific one wins: a severity-and-ID setting overrides an ID setting, which overrides a severity setting.

Many settings can also be changed without recompiling. For example, +UVM_VERBOSITY=UVM_HIGH sets the default verbosity for every component, and +UVM_MAX_QUIT_COUNT=5 ends the test after five counted errors.

The Report Server

The report server counts every message by severity and ID and prints the "UVM Report Summary" at the end of the test. It also tracks the quit count: each message with the UVM_COUNT action increments it, and when it reaches the maximum, the test ends.

uvm_report_server svr = uvm_report_server::get_server ();   // The single global server
svr.set_max_quit_count (10);                               // End the test after 10 counted errors

Stopping early saves simulation time when a design is badly broken, because errors after the first few are rarely useful.

The Report Catcher

A report catcher sees each message before the server processes it. Extend uvm_report_catcher, implement catch(), and return THROW to pass the message on, or CAUGHT to drop it.

A common use is an error-injection test, where certain errors are expected and should not fail the test.

class demote_catcher extends uvm_report_catcher;
  `uvm_object_utils (demote_catcher)

  function new (string name = "demote_catcher");
    super.new (name);
  endfunction

  // Called for every message before the report server sees it
  virtual function action_e catch ();
    if (get_severity () == UVM_ERROR && get_id () == "PARITY_ERR")
      set_severity (UVM_WARNING);    // Expected in this test, so do not fail it
    return THROW;                    // Pass the (possibly modified) message on
  endfunction
endclass

// In the test, for example in end_of_elaboration_phase:
// demote_catcher m_catcher = demote_catcher::type_id::create ("m_catcher");
// uvm_report_cb::add (null, m_catcher);    // null = apply to all report objects

class my_test extends uvm_test;
  `uvm_component_utils (my_test)
  // Rest of the code (constructor, build_phase, etc.)

  UVM_FILE m_scb_log;

  virtual function void end_of_elaboration_phase (uvm_phase phase);
    super.end_of_elaboration_phase (phase);

    // Only the monitor gets full detail
    m_env.m_agent.m_mon.set_report_verbosity_level (UVM_FULL);

    // Route all "SCB" messages in the env to scoreboard.log
    m_scb_log = $fopen ("scoreboard.log", "w");
    m_env.set_report_id_file_hier ("SCB", m_scb_log);

    // Add UVM_LOG only for info; errors keep their default action (DISPLAY | COUNT)
    m_env.set_report_severity_id_action_hier (UVM_INFO, "SCB", UVM_DISPLAY | UVM_LOG);
  endfunction

  virtual function void final_phase (uvm_phase phase);
    super.final_phase (phase);
    $fclose (m_scb_log);                 // Flush and close the log file
  endfunction
endclass