proposal for naming sc_event

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 upto and including phase start_of_simulation
- 'dynamic' events created after phase start_of_simulation
- kernel events that are directly or indierctly 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 upto 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.