Named events

All,

The race is now on to get all the enhancements finished by the end of
November.

The final enhancement on our priority list is named events. I include
Cadence's proposal below.

Comments please

John A

-----

John, All,

In response to ST's enhancement request presented in this forum, below is
a proposal from Cadence for naming sc_events. In this proposal sc_event
does not derive from sc_object for performance concerns. One concern is
sc_events are meant to be lightweight objects, and deriving from sc_object
can make it too heavyweight.

Three categories of events are considered in the proposal:

- 'static' events created up to and including phase start_of_simulation
- 'dynamic' events created after phase start_of_simulation
- kernel events that are directly or indirectly specified in the LRM (e.g.
posedge_event of sc_signal<bool>)

The proposal aims to provide a simple, consistent set of rules aligned
with sc_object naming semantics, and also keeping in mind performance
considerations.

The detailed proposal is given below.

Thanks,
-Bishnupriya

class sc_event {
public:
....
  sc_event(); <-------------- existing
  sc_event(const char* nm); <------------ new
  const char* name() const; <------------ new
  ...
};

1) constructors and hierarchical name of sc_event
   ==============================================

a) static events - created up to and including phase start_of_simulation
   ---------------------------------------------------------------------

Before simulation starts running, both constructors shall register the
sc_event as part of the event hierarchy and shall construct a hierarchical
name for the event using the string name passed as an argument. Calling
the constructor sc_event(const char*) with an empty string shall have the
same behavior as the default constructor, that is, the string name shall
be set to "event".

A hierarchical name shall be composed of a set of string names separated
by the period character '.', starting with the string name of a top-level
sc_object instance and including the string name of each module instance
or process instance descending down through the object hierarchy until the
current sc_event is reached. The hierarchical name shall end with the
string name of the sc_event itself.

Hierarchical names are case-sensitive.

It shall be an error if a string name includes the period character (.) or
any white-space characters. It is strongly recommended that an application
limit the character set of a string name to the following:
a) The lower-case letters a-z
b) The upper-case letters A-Z
c) The decimal digits 0-9
d) The underscore character _

An implementation may generate a warning if a string name contains
characters outside this set but is not obliged to do so.

There shall be a single global namespace for hierarchical names of objects
and events. Each sc_object and sc_event shall have a unique nonempty
hierarchical name. An implementation shall not add any names to this
namespace other than the hierarchical names of sc_objects and sc_events
explicitly constructed by an application.

The sc_event constructor shall build a hierarchical name from the string
name (either passed in as an argument or the default name "event") and
test whether that hierarchical name is unique in the global namespace
consisting of objects and events. If it is unique, that hierarchical name
shall become the hierarchical name of the event. If not, the constructor
shall call function
sc_gen_unique_name, passing the string name as a seed. It shall use the
value returned as a replacement for the string name and shall repeat this
process until a unique hierarchical name is generated. If function
sc_gen_unique_name is called more than once in the course of constructing
any given sc_object, the choice of seed passed to sc_gen_unique_name on
the second and subsequent calls shall be implementation-defined but shall
in any case be either the string name passed as the seed on the first such
call or shall be one of the string names returned from sc_gen_unique_name
in the course of constructing the given sc_event. In other words, the
final string name shall have the original string name as a prefix.

If the constructor needs to substitute a new string name in place of the
original string name as the result of a name clash, the constructor shall
generate a single warning.

b) Dynamic events - created after phase start_of_simulation
   ---------------------------------------------------------

After simulation starts running, there can be a run-time performance
impact associated with hierarchically naming an event, e.g.,in the case of
a dynamically spawned process with a local event where the process comes
and goes repeatedly. To address this performance concern, the behavior of
sc_event's default ctor after simulation start is kept unspecified, i.e.
implemenntation-defined. An implementation may choose to treat such events
exactly the same as static events, or it can choose to not name them at
all, or somewhere in between.

The behavior of the second constructor for dynamic events shall be the
same as that for static events, i.e. if the user explicitly names a
dynamic event, it shall be a part of the event hierarchy, and it shall
have a proper hierarchical name following the same rules as in 1a).
Calling the constructor sc_event(const char*) with an empty string shall
have the same behavior as the default constructor, i.e the behavior is
left implementation-dependent.

c) Kernel events
   ---------------

There are events created by the SystemC kernel for various purposes. These
events can be classified into two categories

i) Events that are directly or indirectly specified in the LRM, e.g. LRM
specifies "const sc_event& sc_signal<bool>::posedge_event()". Lets call
these explicit kernel events.

ii) Events that kernel creates for internal implementation. Lets call
these implementation kernel events

For implementation kernel events, the implementation is obliged to exclude
those events from the event hierarchy and from the namespace of
hierarchical names. This would necessitate an extension to the semantics
of class sc_event, and the implementation would be obliged to make such an
extension transparent to the application.

For explicit kernel events also, the implementation is obliged to exclude
such events from the event hierarchy, and from the namespace of
hierarchical names, thus not polluting the global namespace. This implies
if get_child_events() is invoked on the parent scope of an explicit kernel
event, the returned vector shall not contain a reference to the explicit
kernel event. Furthermore, the user is always free to name his own
application event as he chooses to, without having to worry about his
event clashing with an explicit kernel event.

2) obtaining the name of a sc_event
   ================================

const char* sc_event::name() const;

Member function name shall return the hierarchical name of the sc_event
instance in the event
hierarchy.

3) add member method to retrieve a list of sc_events from parent scope
   ===================================================================

add member method to sc_module, and sc_process_handle, as below:

  const std::vector<sc_event*>& get_child_events() const;

Member function get_child_events shall return a std::vector containing a
pointer to every instance of class sc_event that lies within the
module/process in the design hierarchy.

NOTE 1-The phrase within a module does not include instances nested within
modules instances but only includes the immediate children of the given
module.

4) add global functions to retrieve top-level events and to find event by
name
 
=============================================================================

namespace sc_core {
  const std::vector<sc_event*>& get_top_level_events() const;
  sc_event* sc_find_event(const char* name);
};

Function sc_get_top_level_events shall return a std::vector containing
pointers to all of the toplevel sc_events.

Function sc_find_event shall return a pointer to the sc_event that has a
hierarchical name that
exactly matches the value of the string argument or shall return the null
pointer if there is no
sc_event having a matching name.

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