RE: verbosity control

Hi Bishnupriya,

I also was suggesting that you change the prototype of this function to
make it directly backwards compatible

class sc_report_handler
{
public:
    static void report(sc_severity,
                               const char* msg_type,
                               const char* msg,
                               const char* file,
                               int line,
                               int verbosity = SC_IGNORE_VERBOSITY //
make this the last parameter and give it a default
    );
};

regards
Alan

From:
Bishnupriya Bhattacharya <bpriya@cadence.com>
To:
"john.aynsley@doulos.com" <john.aynsley@doulos.com>,
"systemc-p1666-technical@eda.org" <systemc-p1666-technical@eda.org>
Cc:
Qizhang Chao <qzc@cadence.com>
Date:
03/12/2010 10:14
Subject:
RE: verbosity control
Sent by:
owner-systemc-p1666-technical@eda.org

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. 
-- 
Alan Fitch
Senior Consultant
Doulos - Developing Design Know-how
VHDL * Verilog * SystemVerilog * SystemC * PSL * Perl * Tcl/Tk * Project 
Services
Doulos Ltd. Church Hatch, 22 Market Place, Ringwood, Hampshire, BH24 1AW, 
UK
Tel:  + 44 (0)1425 471223                       Email: 
alan.fitch@doulos.com 
Fax:  +44 (0)1425 471573                        http://www.doulos.com
--------------------------------------------------------------------------------
Doulos Ltd is registered in England and Wales with company no. 3723454
Its registered office is 4 Brackley Close, Bournemouth International 
Airport,
 Christchurch, BH23 6SE, UK. 
This message (and associated files) may contain information that is 
confidential, 
proprietary, privileged, or subject to copyright. It is intended solely 
for the use
of the individual to whom it is addressed and others authorised to receive 
it. If
you have received this email in error, please notify the sender and delete 
all
copies. This message may contain personal views which are not the views of
Doulos, unless specifically stated.
-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.