systemc-2.2.0

EXCEPTION REPORTING Based on SystemC Verification Standard Specification, Feb, 2003. The exception reporting facility provides a common and configurable API to report an exceptional situation. The facility is presented by two classes: sc_report_handler and sc_report. The former provides configuration and report generation calls. The latter just contains the report related information. The application defines an exceptional situation by using one of SC_REPORT_ macros to generate a report. The report is identified by its severity (represented by sc_severity enum type) and the message type. The message type is a string of characters, uniquely identifing a specific type of the exception. This sc_severity describes the severity of a report: enum sc_severity { SC_INFO, SC_WARNING, SC_ERROR, SC_FATAL }; SC_INFO The report is informative only. SC_WARNING The report indicates a potentially incorrect condition. SC_ERROR The report indicates a definite problem during execution. The default configuration forces a throw of a C++ exception sc_exception with the corresponding report information attached. SC_FATAL The report indicates a problem which cannot be recovered from. In default configuration, the simulation is terminated immediately using an abort() call after reporting a SC_FATAL report. The application can define actions to be taken for a generated report. Whereas a usual reaction on a exceptional situation includes just printing a message, more complex scenarios could involve a logging of the report into a file, throwing a C++ exception or drop in the debugger. The enum type sc_actions describes such a set of operations. There are several predefined values for this type: enum { SC_UNSPECIFIED = 0x00, SC_DO_NOTHING = 0x01, SC_THROW = 0x02, SC_LOG = 0x04, SC_DISPLAY = 0x08, SC_CACHE_REPORT = 0x10, SC_INTERRUPT = 0x20, SC_STOP = 0x40, SC_ABORT = 0x80 }; SC_UNSPECIFIED Take the action specified by a configuration rule of a lower precedence. SC_DO_NOTHING Don't take any actions for the report, the action will be ignored, if other actions are given. SC_THROW Throw a C++ exception (sc_exception) that represents the report. The method sc_exception::get_report() can be used to access the report instance later. SC_LOG Print the report into the report log, typically a file on disk. The actual behaviour is defined by the report handler function described below. SC_DISPLAY Display the report to the screen, typically by writing it in to the standard output channel using std::cout. SC_INTERRUPT Interrupt simulation if simulation is not being run in batch mode. Actual behaviour is implementation defined, the default configuration calls sc_interrupt_here(...) debugging hook and has no furhter side effects. SC_CACHE_REPORT Save a copy of the report. The report could be read later using sc_report_handler::get_cached_report(). The reports saved by different processes do not overwrite each other. SC_STOP Call sc_stop(). See sc_stop() manual for further detail. SC_ABORT The action requests the report handler to call abort(). The report handler, a function known to the class sc_report_handler, takes the responsibility of execution the requested actions. Application is able to redefine the report handler to take additional steps on execution of a specific action or extend the default set of possible actions. As the report handler is responsible for all predefined actions it can also be used to redefine the behaviour of predefined actions. Each exception report can be configured to take one or more sc_actions. Multiple actions can be specified using bit-wise OR. When SC_DO_NOTHING is combined with any thing other than SC_UNSPECIFIED, the bit is ignored by the facility. In addition to the actions specified within the sc_actions enum, via sc_actions, the exception API also can take two additional actions. The first action is always taken: the sc_stop_here() function is called for every report, thus providing users a convenient location to set breakpoints to detect error reports, warning reports, etc. The second action that can be taken is to force SC_STOP in the set of the actions to be executed. The action is configured via the stop_after() method described below, which allows users to set specific limits on the number of reports of various types that will usually cause simulation to call sc_stop(). The configuration and report generation API is contained within the sc_report_handler class. The sc_report_handler Class The class provides only static API. The user cannot construct an instance of the class. void report( sc_severity severity, const char* msg_type, const char* msg, const char* file, int line ); Generate a report instance, which will cause the facility to take the appropriate actions based on the current configuration. The call will configure a not known before exception of msg_type to take default set of actions for given severity. The first occurence of the particular msg_type starts its stop_after() counter. sc_actions set_actions( sc_severity severity, sc_actions actions = SC_UNSPECIFIED ); Configure the set of actions to take for reports of the given severity (lowest precedence match). The previous actions set for this severity is returned as the result. SC_UNSPECIFIED is returned if there was no previous actions set for this severity. TODO: what if to be taken actions are SC_UNSPECIFIED and there is now highe precedence match? do nothing? sc_actions set_actions( const char* msg_type, sc_actions actions = SC_UNSPECIFIED ); Configure the set of actions to take for reports of the given message type (middle precedence match). The previous actions set for this message type is returned as the result. SC_UNSPECIFIED is returned if there was no previous actions set for this message type. sc_actions set_actions( const char* msg_type, sc_severity severity, sc_actions actions = SC_UNSPECIFIED ); Configure the set of actions to take for reports having both the given message type and severity (high precedence match). The previous actions set for this message type and severity is returned as the result. SC_UNSPECIFIED is returned if there was no previous actions set for this message type and severity. The functions stop_after(...) modify only the limit, they do not affect the counter of the number of reports. Setting the limit below the number of already occured reports will cause sc_stop() for the next matching report. int stop_after( sc_severity severity, int limit = -1 ); Call sc_stop() after encountering limit number of reports of the given severity (lowest precedence match). If limit is set to one, the first occurrence of a matching report will cause the abort. If limit is 0, abort will never be taken due to a matching report. If limit is negative, abort will never be taken for non-fatal error, and abort will be taken for the first occurrence of a fatal error. The previous limit for this severity is returned as the result. The stop_after() call will return UINT_MAX (int -1) in the case where no previous corresponding stop_after() call was made. int stop_after( const char* msg_type, int limit = -1 ); Call sc_stop() after encountering limit number of reports of the given message type (middle precedence match). The previous limit for this message type is returned as the result. If limit is 0, abort will never be taken due to a matching report.