Advanced Error Reporting

When building complex virtual platforms, simple std::cout statements are not enough. You need a structured way to report warnings, errors, and fatal faults, while allowing the top-level testbench to filter, log, or abort the simulation based on these reports. SystemC provides a robust reporting mechanism through sc_core::sc_report_handler and the associated SC_REPORT_* macros, specified in the IEEE 1666 Standard.

LRM Standard Severity Levels

The SystemC Language Reference Manual (LRM) defines four strict severity levels, represented by the sc_core::sc_severity enumeration:

1. SC_INFO: Informative messages. By default, these are printed to the standard output and do not interrupt simulation.
2. SC_WARNING: Indicates a potentially incorrect condition. The simulation can continue, but the user should be aware. By default, it prints to standard output.
3. SC_ERROR: A definitive error condition. By default, this action is configured to SC_DEFAULT_ERROR_ACTIONS, which throws a C++ exception of type sc_core::sc_report.
4. SC_FATAL: A critical failure that cannot be recovered from. By default, this executes SC_DEFAULT_FATAL_ACTIONS, which prints the message and calls abort() to terminate the process immediately.

These levels are typically triggered using their corresponding macros:

• SC_REPORT_INFO(msg_type, msg)
• SC_REPORT_WARNING(msg_type, msg)
• SC_REPORT_ERROR(msg_type, msg)
• SC_REPORT_FATAL(msg_type, msg)

The Message Type String (msg_type)

Notice the first argument in all macros: msg_type. This is a crucial LRM concept. It acts as a unique categorical identifier for the error.

By categorizing errors with a specific msg_type, you allow the end user or top-level integrator to override how those specific errors are handled across the entire simulation! A good practice is to use a hierarchical naming convention, such as "/Company/IP/Component/ErrorCode".

Overriding Report Actions (sc_action)

The true power of sc_report_handler is action overriding. Suppose an IP block you bought throws an SC_REPORT_ERROR because a packet was dropped. But in your specific testbench, dropping packets is expected (e.g., negative testing). You don't want the simulation to crash!

You can change the action for that specific msg_type or for an entire severity level.

Available Actions (sc_core::sc_action)

Actions can be bitwise OR'd together (e.g., SC_LOG | SC_DISPLAY):

• SC_DO_NOTHING: Suppress the report entirely.
• SC_THROW: Throw an sc_core::sc_report exception.
• SC_LOG: Write the report to the configured log file.
• SC_DISPLAY: Print the report to the standard output.
• SC_CACHE: Save the report so it can be retrieved later via sc_report_handler::get_cached_report().
• SC_INTERRUPT: Interrupt execution (useful for debugger breakpoints).
• SC_STOP: Call sc_core::sc_stop() to gracefully end the simulation at the end of the current delta cycle.
• SC_ABORT: Call std::abort() for an immediate, hard crash.

You apply these overrides using sc_report_handler::set_actions.

Complete Example: Advanced Report Handling

The following example demonstrates overriding actions, catching exceptions from SC_REPORT_ERROR, and logging fatal messages to a file. It is a complete, compilable SystemC design.

#include <systemc>
#include <iostream>
 
// A dummy IP block that generates various reports
SC_MODULE(NetworkIP) {
    SC_CTOR(NetworkIP) {
        SC_THREAD(run);
    }
 
    void run() {
        // 1. A standard info message
        SC_REPORT_INFO("/Company/NetworkIP/Status", "Network IP initialized successfully.");
 
        wait(10, sc_core::SC_NS);
 
        // 2. A warning message
        SC_REPORT_WARNING("/Company/NetworkIP/Bandwidth", "Bandwidth utilization exceeding 80%.");
 
        wait(10, sc_core::SC_NS);
 
        // 3. An error message. By default, this throws an exception.
        // We will configure the handler in sc_main to NOT throw for this specific msg_type.
        SC_REPORT_ERROR("/Company/NetworkIP/PacketDrop", "Packet dropped due to buffer overflow.");
 
        wait(10, sc_core::SC_NS);
 
        // 4. An error message that WILL throw an exception.
        try {
            SC_REPORT_ERROR("/Company/NetworkIP/Checksum", "Invalid packet checksum detected.");
        } catch (const sc_core::sc_report& e) {
            std::cout << "\n[CATCH] Caught a SystemC report exception!\n";
            std::cout << "        Message: " << e.get_msg() << "\n";
            std::cout << "        Type:    " << e.get_msg_type() << "\n";
            std::cout << "        Time:    " << e.get_time() << "\n\n";
        }
 
        wait(10, sc_core::SC_NS);
 
        // 5. A fatal message. We configure this in sc_main to NOT abort, but to stop simulation instead.
        SC_REPORT_FATAL("/Company/NetworkIP/HardwareFault", "Thermal limit exceeded! Halting.");
 
        // This line will not be reached because SC_STOP will end simulation during the next phase.
        SC_REPORT_INFO("/Company/NetworkIP/Status", "This should not print.");
    }
};
 
int sc_main(int argc, char* argv[]) {
    // ---------------------------------------------------------
    // LRM-Compliant Report Handler Configuration
    // ---------------------------------------------------------
 
    // Ignore all PacketDrop errors!
    sc_core::sc_report_handler::set_actions("/Company/NetworkIP/PacketDrop", sc_core::SC_DO_NOTHING);
    
    // Log all warnings to a file, but ALSO display them on stdout
    sc_core::sc_report_handler::set_log_file_name("simulation_warnings.log");
    sc_core::sc_report_handler::set_actions(sc_core::SC_WARNING, sc_core::SC_LOG | sc_core::SC_DISPLAY);
 
    // Override the fatal action for this specific type to STOP instead of ABORT
    sc_core::sc_report_handler::set_actions(
        "/Company/NetworkIP/HardwareFault", 
        sc_core::SC_DISPLAY | sc_core::SC_LOG | sc_core::SC_STOP
    );
 
    // Instantiate the module
    NetworkIP ip("network_ip_inst");
 
    std::cout << "Starting simulation...\n";
    sc_core::sc_start();
    std::cout << "Simulation finished at " << sc_core::sc_time_stamp() << "\n";
 
    return 0;
}

Key Takeaways

1. Never use std::cout for errors: Always use SC_REPORT_ERROR or SC_REPORT_FATAL.
2. Standardize your msg_type: A consistent naming convention makes your IP blocks professional and configurable.
3. Graceful exits: Overriding SC_FATAL to SC_STOP allows your testbench to cleanly extract coverage data before exiting, rather than suffering a hard abort().