Re: verbosity control

David,

You brought up the point of set_handler.

We currently have

typedef void ( * sc_report_handler_proc ) ( const sc_report& , const sc_actions& );
static void set_handler( sc_report_handler_proc );

so the user-defined hander gets passed an sc_report object. It does not have to implement sc_report_hander::report. After adding verbosity, the sc_report object would have an extra attribute, which the application-defined handler may or may not use. So I think it works.

John A

-----David C Black <dcblack@xtreme-eda.com> wrote: -----
To: Bishnupriya Bhattacharya <bpriya@cadence.com>
From: David C Black <dcblack@xtreme-eda.com>
Date: 12/03/2010 01:16PM
Cc: "john.aynsley@doulos.com" <john.aynsley@doulos.com>, "systemc-p1666-technical@eda.org" <systemc-p1666-technical@eda.org>, Qizhang Chao <qzc@cadence.com>
Subject: Re: verbosity control

I must say that I really like and support this proposal.  For several years, we've used kludges (overriding the default handler) to address the very issues this addresses. I've thought a few times about proposing something along these lines. This one is quite acceptable. It does not bother me whether the new parameter is in the middle or at the end as I think both accomplish backwards compatibility. Cadence proposal is slightly more elegant from an intent point of view. Doulos proposal adds just a touch less to the overall change this implies. There is one aspect that might tip the balance: set_handler(), which I suspect was forgotten. I think I prefer Doulos because set_handler() needs only one signature and an implementer needs only worry about one.
 
On Fri, Dec 3, 2010 at 4:13 AM, Bishnupriya Bhattacharya <bpriya@cadence.com> wrote:
     
 
 
 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, and is
believed to be clean.
  

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