RE: verbosity control

One typo in the proposal below. The new SC_REPORT_<XXX>_V macros expand to calling sc_report() and not sc_report_handler::report().
1.10 Add new macros SC_REPORT_<XXX>_V that accepts a verbosity value
#define SC_REPORT_INFO_V(msg_type , msg, verbosity ) \
    sc_report( SC_INFO , msg_type , msg , verbosity, __FILE__ , __LINE__ )

#define SC_REPORT_WARNING_V( msg_type , msg ) \
    sc_report( SC_WARNING , msg_type , msg , verbosity, __FILE__ , __LINE__ )

#define SC_REPORT_ERROR_V( msg_type , msg ) \
    sc_report( SC_ERROR , msg_type , msg , verbosity, __FILE__ , __LINE__ )

#define SC_REPORT_FATAL_V( msg_type , msg ) \
    sc_report( SC_FATAL , msg_type , msg , verbosity, __FILE__ , __LINE__ )
-Bishnupriya

________________________________
From: owner-systemc-p1666-technical@eda.org [mailto:owner-systemc-p1666-technical@eda.org] On Behalf Of Bishnupriya Bhattacharya
Sent: Friday, December 03, 2010 3:44 PM
To: john.aynsley@doulos.com; systemc-p1666-technical@eda.org
Cc: Qizhang Chao
Subject: RE: verbosity control

John, All,
I've a more refined verbosity proposal below. Changes from original version:
1) take into account Alan's comments
2) add additional macros SC_REPORT_<XXX>_V similar to the SC_REPORT_<XXX> macros that take an additional verbosity argument
3) add a provision for per-module verbosity control
1) and 2) are trivial. If 3) is considered too much to digest in the short time left, we believe there is a lot of value to standardizing verbosity even without 3) at this time.
Thanks,
-Bishnupriya
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 both at the global level and at a finer grained per-module level.
* 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 global verbosity level. The API sc_report_handler::set_verbosity_level_hier() will set the maximum versbosity level at global scope and for the entire module hierarchy.
. sc_module will have a new integer property - verbosity level of SC_INFO messages emitted from within the module scope. The default value of this property is 200. Using the API sc_module::set_verbosity_level(), users can set the maximum verbosity level of that module. The API sc_module::set_verbosity_level_hier() will set the maximum versbosity level of the module sub-hierarchy rooted at that module.
. When generating a report using the SystemC reporting mechanism, users will be able to optionally provide an integer value indicating the verbosity of that message. This verbosity value is only relevant for SC_INFO messages. If the verbosity level of a SC_INFO message is greater than the maximum verbosity setting in the specified scope (global or module), the report will be ignored.
. Existing APIs for message reporting will continue to work with their existing behavior for backwards comaptibility reasons. Additional APIs will be provided that allows a message to be tagged with a verbosity value:
  1) sc_report_handler::report() with new signature that takes integer verbosity value as fourth argument; e.g. sc_report_handler::report(SC_INFO, "myid", "mymsg", 300, __FILE__, __LINE__); SC_INFO messages reported with this API will be controlled by the global maximum verbosity setting;
   - Alan has proposed adding verbosity as optional last argument with a large default value to the existing method sc_report_handler::report(); this is a little less clean in that verbosity "belongs" more naturally as a primary attribute to be clubbed with severity, id, etc. instead of being stuck on at the end after file and line, but the advantage of this approach is only one signature of report(); however, existing designs will not benefit in any case - to use verbosity user has to explicitly add the verbosity paremeter, seems cleaner to add it where it naturally belongs rather than at end; Having said that we are not opposed to this approach if people like this better
  2) sc_module::sc_report() with same signature as 1); SC_INFO messages reported with this API will be controlled by the maximum verbosity setting of that module; the rest of the behavior is same as that of 1)
  3) sc_core::sc_report() with same signature as 1); provides same functionality as 1)
  4) new SC_REPORT_<XXX>_V macros that take an additional third argument as the verbosity value of that message; e.g. SC_REPORT_INFO_V("myid", "mymsg", 300); the macros expand to invoke the function sc_report(); if the macros are invoked from global scope, sc_report() will resolve to the global function, and if invoked from module scope, sc_report() will resolve to the module's sc_report() function; thus, by default, the correct scope is determined, and user can simply use these macros w/o having to worry about the scope
. Existing SC_REPORT_XXX macrors will be modified to pass on a pre-defined verbosity value for each message severity - existing designs will continue to get existing behavior; note that these macros will maintain current behavior of expanding to sc_report_handler::report() to eliminate any risk to existing designs

* Note that messages of severity level SC_FATAL, SC_ERROR, and SC_WARNING are not controlled by the verbosity level. This is because implementations themselves may use the SC_ERROR/SC_FATAL/SC_WARNING mechanism to report issues in the design, and the verbosity setting may make it very easy for the user to accidentally turn off ERROR/FATAL/WARNING messages without actually meaning to. Note that the user can always 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.
* sc_report_handler::report(), sc_module::sc_report(), and sc_core::sc_report() will maintain 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,
  SC_IGNORE_VERBOSITY = 9999 // as suggested by Alan
};
} // 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. The set_verbosity_level_hier() method will set up the global verbosity and the verbosity level of the entire module hierarchy.

class sc_report_handler {
public:
  int set_verbosity_level(int verbosity_level);
  int set_verbosity_level_hier(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 global maximum verbosity in SystemC.

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

1.6 Add member method report() to sc_report_handler with new signature

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 Add sc_module methods to set the verbosity level for that module and its descendants
int sc_module::set_verbosity_level(int verbosity);
int sc_module::set_verbosity_level_hier(int verbosity);
set_verbosity_level() will set up the specified value as the maximum verbosity level of the sc_module. set_verbosity_level_hier() will affect the module and all its descendants.
The priority between the global APIs and the sc_module APIs is temporal - the last one prevails.
When a message is reported from within a module scope - i.e. from any member method within the module, or its ctor/dtor - the message's verbosity will be checked against the maximum verbosity level of the module, and if the verbosity is greater than the parent module's maximum verbosity, the message will not be reported. When a message is reported from a non-module scope - e.g. sc_main() - the global maximum verbosity level will apply.

1.8 Add sc_report() method to sc_module and to sc_core in global scope
sc_module will be enhanced to provide a reporting interface. Today, becasue of the global nature of the reporting mechanism, the reporting API consist of a static report() method in the static sc_report_handler class. There are also the convenience SC_REPORT_XXX macros that expand to invoking sc_report_handler::report().
In addition, sc_module will provide a member method sc_report().
namespace sc_core {
void sc_module::sc_report(sc_severity severity,
                       const char* msg_type,
                       const char* msg,
                       int verbosity,
                       const char* file,
                       int line);
void sc_report(sc_severity severity,
                       const char* msg_type,
                       const char* msg,
                       int verbosity,
                       const char* file,
                       int line);
}
When a method within a module scope invokes sc_report(), it will resolve to sc_module::sc_report(), which will compare the message's verbosity with the max verbosity in the module, and accordingly take action. When a method within a non-module scope invokes sc_report(), it will resolve to the global function, which will compare the message's verbosity with the global max verbosity, and accordingly take action.

1.9 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.
1.10 Add new macros SC_REPORT_<XXX>_V that accepts a verbosity value
#define SC_REPORT_INFO_V(msg_type , msg, verbosity ) \
    sc_report_handler::report( SC_INFO , msg_type , msg , verbosity, __FILE__ , __LINE__ )

#define SC_REPORT_WARNING_V( msg_type , msg ) \
    sc_report_handler::report( SC_WARNING , msg_type , msg , verbosity, __FILE__ , __LINE__ )

#define SC_REPORT_ERROR_V( msg_type , msg ) \
    sc_report_handler::report( SC_ERROR , msg_type , msg , verbosity, __FILE__ , __LINE__ )

#define SC_REPORT_FATAL_V( msg_type , msg ) \
    sc_report_handler::report( SC_FATAL , msg_type , msg , verbosity, __FILE__ , __LINE__ )

1.11 Existing sc_report_handler::report() method will calculate versbosity according to the message severity

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.9. 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
    );
}

--
This message has been scanned for viruses and
dangerous content by MailScanner<http://www.mailscanner.info/>, and is
believed to be clean.
-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.