Statistic Wire Configuration

A statistic wire is a physical connection that attaches a source port of one module to a destination port of another module in the same node. Source ports for statistic wires are referred to as output statistics, and destination ports are referred to as input statistics. The source module of a statistic wire can be any module that generates statistics. However, only processors and queue modules can act as the destinations of statistic wires, because these are the only modules that can contain processes that would receive a statistic value.

Graphically, statistic wires are represented in a manner similar to packet streams, but are distinguished by a dashed connection path (as opposed to the solid lines used to depict packet streams). Statistic wire input ports are referred to by integer indices that can range from 0 to 99.

Figure 222: Statistic Wire Connections with Fan-Out and Fan-In

Statistic Wire Connections with Fan-Out and Fan-In

Input statistics are capable of accepting multiple statistic wires to provide the local module with a sequence of values that results from merging the individual sequences of values sent via multiple output statistics, possibly from different modules.

Statistic wires can be used to transfer any of the values that constitute the predefined output statistics known to the Simulation Kernel. In most cases, these are the same values that can be collected in a simulation’s output vector file via statistic probes. For all modules except processors, output statistics can be predefined values computed automatically by the Simulation Kernel, a new value being transferred whenever a change occurs. For example, a queue module generates statistics such as the number of packets it contains or the average amount of time a packet remains in the queue; and a receiver module generates statistics such as throughput and utilization for each of its channels. For a complete definition of available predefined statistics for each type of module, see Chapter 2 “Node Reference” on page 8.

Because the significance and behavior of queue and process modules can be specified in a fully general manner by assigning user-defined process models, generic output statistics are provided for custom applications. For each queue or processor module, you can declare any number of output statistics. These output statistics can act as the source of a statistic wire to convey new values to their destination at the request of processes within the source module. Processes can initiate the transfer of a new statistic value on a particular statistic wire by calling the KP op_stat_write() and specifying the index of the output statistic to which the statistic wire is attached. Any floating point number can be sent to a statistic wire destination this way.

Apart from the manner in which new values are generated, statistic wires operate identically, regardless of whether they are fed by predefined or generic statistics. When a new value is generated at a statistic wire source, two possible behaviors may result, depending upon the value assigned to the “intrpt method” attribute of the statistic wire. If the interrupt method is “forced”, then no delay is possible for the statistic transfer, and an immediate change occurs at the destination module’s input statistic. However, if the interrupt method is “scheduled”, which is the default, an arrival time at the destination module’s input statistic is calculated based on the “delay” attribute of the statistic wire.

When a new statistic value arrives at the destination module, it is stored in the input statistic, replacing the value that was there previously. The value subsequently can be obtained at any time (until the next replacement) by any process in the destination module, using the KP op_stat_local_read(). The integer index of the input statistic must be specified when calling this KP. Note that the previous value can no longer be obtained, because it has been overwritten.

In addition to making a new statistic value available to the destination module each time that an update occurs, a statistic wire can provide active notification of changes. Notification takes the form of a statistic event that is generated for the destination module if appropriate conditions are met. The statistic event may then result in an interrupt for one of the module’s processes if appropriate interrupts are enabled. For more information on restricting interrupts, see Chapter 4 “Modeling Framework” on page 80.

A statistic wire can be configured in such a way as to generate events only when particular types of changes occur in the input statistic value at its destination. A set of criteria, called triggers, are used to determine when an event should be generated. Triggers are specified as attributes of a statistic wire object that characterize six types of changes in value. For an event to occur as a result of a statistic value change, the logical OR of the conditions represented by the statistic wire’s enabled triggers must be true; in other words, at least one of the trigger conditions detailed below must be satisfied, and the corresponding trigger attribute must not be set to the “disabled” value.

  • rising edge trigger – The newly received value is strictly greater than the previously received value.
  • falling edge trigger – The newly received value is strictly less than the previously received value.
  • repeated value trigger – The newly received value and the previously received value are identical.
  • zero crossing trigger – The newly received value has the opposite sign of the previously received value, or the newly received value is exactly zero.
  • low threshold trigger – The newly received value is less than or equal to a user specified low threshold value.
  • high threshold trigger – The newly received value is greater than or equal to a user specified high threshold value.

The default configuration for statistic wire triggers is to enable the rising edge and falling edge triggers and to disable all others. This implies that a statistic event will be generated whenever any change occurs in the input statistic’s value; however no event will be generated if a statistic update is received that is the same as the previous value. Another common configuration enables the repeated value trigger in addition to the falling and rising edge triggers to allow any received statistic value to generate an active notification. Finally, a third common configuration disables all triggers to implement a passive statistic transfer; in other words, the destination module can observe statistic values generated at the statistic wire source, but no interrupts are ever received as a result.