(no subject)

All,

Following yesterday's telecon, here is the text of the Cadence proposal for verbosity control.

Comments please.

John A

Below is a proposal to add an additional knob to the SystemC reporting mechanism - verbosity control. The change itself is trivial, but it provides a powerful debug feature to SystemC users.

1.1          Overview

In many scenarios, SystemC applications want to report informational messages tagged by different degrees of importance, and provide the end user the flexibility of selecting which message types they want emitted or ignored, depending on its degree of importance. This enhancement proposes such a mechanism to be added to SystemC reporting - verbosity control.

Verbosity control will provide an additional knob to control the SystemC reporting mechanism.

· SystemC designs will have a new global property - maximum verbosity level of SC_INFO messages - defined as an integer value. The default value of this property is 200. 

· Using the API sc_report_handler::set_verbosity_level(), users can set the maximum verbosity level. 

· When generating a report using sc_report_handler::report(), users can specify an integer verbosity level associated with that message. Users can also use the SC_REPORT macros, which will provide a pre-defined verbosity level corresponding to each kind of message severity. 

· If the severity level of the message is of type SC_INFO, and the verbosity level of the message is greater than the maximum verbosity level - as set by the sc_report_handler::set_verbosity_level() API - then the report will be ignored. Messages of severity level SC_FATAL, SC_ERROR, and SC_WARNING are not controlled by the verbosity level. This is because the simulator itself uses the SC_ERROR/SC_FATAL/SC_WARNING mechanism to report issues, and the verbosity setting makes it very easy for the user to accidentally turn off ERROR/FATAL/WARNING messages without knowing what he is doing. Note that the user can suppress a specific ERRIOR/FATAL/WARNING message using sc_report_handler::set_actions(... , SC_DO_NOTHING), but in that case, the user is very consciously taking action.

It seems a little redundant to define the verbosity mechanism for other severity levels besides SC_INFO, since the verbosity is ignored in those cases. However, the verbosity mechanism is kept the same for all severity types for the sake of a consistent API. 

· sc_report_handler::report() maintains counts of the number of reports generated as described in Section 8.3.7 of the IEEE-1666 LRM. These counts contribute to the functionality of the sc_report_handler::stop_after() member methods. These counts will not be incremented if the report gets ignored due to the verbosity level setting.

1.2          Define enums for verbosity level

An enum sc_verbosity will be defined for indicative verbosity levels.

namespace sc_core {

enum sc_verbosity {
  SC_NONE = 0,
  SC_LOW = 100,
  SC_MEDIUM = 200,
  SC_HIGH = 300,
  SC_FULL = 400,
  SC_DEBUG = 500
};
} // namespace sc_core

1.3          Add member method get_verbosity() to sc_report

The get_verbosity() member method will be added to the sc_report class. This method will return the verbosity property of the sc_report object. The verbosity property can only be set by passing its value as an argument to the function sc_report_handler::report() - see Section 2.4.

class sc_report : public std::exception
{
public:
  ...
  int get_verbosity() const;
  ...
};

1.4          Add member method set_verbosity_level() to sc_report_handler

The set_verbosity_level() member method will be added to the sc_report_handler class. This method will accept an integer parameter and will set up the global maximum verbosity level in SystemC. The method will return the existing maximum verbosity level.

class sc_report_handler {
public:
  int set_verbosity_level(int verbosity_level);
};  

When a message is issued in SystemC using sc_report_handler::report(), if the verbosity specified in the message is greater than the global maximum verbosity level, and the message has SC_INFO severity, then the message is ignored, and not reported.

1.5          Add member method get_verbosity_level() to sc_report_handler

The get_verbosity_level() member method will be added to the sc_report_handler class. This method will return the maximum verbosity level in SystemC.

class sc_report_handler {
public:
  int get_verbosity_level();
};  

1.6          Add member method report() to sc_report_handler

Add a new member method report() to the sc_report_handler class. This member method will have a different signature than the existing member method report(). The new report() method will accept an integer verbosity level parameter as its fourth argument.

class sc_report_handler
{
public:
    static void report(sc_severity,
                               const char* msg_type,
                               const char* msg,
                               int verbosity,
                               const char* file,
                               int line
    );
}

1.7          Backwards compatibility

The original sc_report_handler::report() member method will be maintained for backwards compatibility. If this member method is called, it won’t have an explicit verbosity level specified by the user. Instead, this method will calculate the verbosity level according to the severity parameter, as specified in Section 1.8. The signature of the existing report() member method is given below.

class sc_report_handler
{
public:
ÿÿÿ static void report(sc_severity,
ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ const char* msg_type,
ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ const char* msg,
ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ const char* file,
ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ int line
ÿÿÿ );
}ÿ

1.8ÿÿÿÿÿÿÿÿÿ Provide predefined verbosity levels for SC_REPORT macros

The SC_REPORT macros will be modified to invoke the new member method report() in the sc_report_handler class, with a pre-defined verbosity level depending on the message severity.

#define SC_REPORT_INFO( msg_type , msg ) \
ÿÿÿ sc_report_handler::report( SC_INFO , msg_type , msg , sc_core::SC_MEDIUM, __FILE__ , __LINE__ )

#define SC_REPORT_WARNING( msg_type , msg ) \
ÿÿÿ sc_report_handler::report( SC_WARNING , msg_type , msg , sc_core::SC_MEDIUM, __FILE__ , __LINE__ )

#define SC_REPORT_ERROR( msg_type , msg ) \
ÿÿÿ sc_report_handler::report( SC_ERROR , msg_type , msg , sc_core::SC_LOW, __FILE__ , __LINE__ )

#define SC_REPORT_FATAL( msg_type , msg ) \
ÿÿÿ sc_report_handler::report( SC_FATAL , msg_type , msg , sc_core::SC_NONE, __FILE__ , __LINE__ )

Note that if an application issuing messages through the reporting mechanism desires that the end user be able to configure the verbosity, then it cannot use the SC_REPORT_INFO macro. Instead, it has to use the sc_report_handler::report() API with different verbosity settings for different categories of info messages.

-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.