Skip to content

Comm Effect Model

Jump to bottom
Steven Galgano edited this page Aug 18, 2017 · 12 revisions

Contents

Features

The Comm Effect utility model provides the ability to define the following network impairments:

  • Loss: The percentage of packets that will be dropped utilizing a uniform loss distribution model.

  • Latency: The average delay for a packet to traverse the network. The total delay is composed of a fixed and variable component. The fixed amount of the delay is defined via a latency configuration parameter and the variable amount via a jitter configuration parameter The jitter is determined randomly using a uniform random distribution model around +/- jitter . The randomly generated jitter value is then added to the fixed latency to determine the total delay.

  • Duplicates: The percentage of packets that will be duplicated at the receiver.

  • Unicast Bitrate: The bitrate for packets destined for the NEM or handled in promiscuous mode.

  • Broadcast Bitrate: The bitrate for packets destined for the NEM broadcast address.

The network impairments defined above can be controlled via two mechanisms: Comm Effect Events and static filter based impairments.

Static Filters

In addition to the event based network impairments, the Comm Effect model provides the ability to define static filters to control network impairments. Filters are defined via an XML configuration file and have the following characteristics:

  1. The filter file used by a given NEM within the emulation is identified at initialization time via the NEM’s filterfile configuration parameter. Each filter defined in the filterfile is characterized by one or more target elements and a single effect element.

  2. Currently only IPv4 Ethernet packet filter targets are supported. The target element has the following format within the filter XML file:

    <target>
  <ipv4 src=’0.0.0.0’ dst=’0.0.0.0’ len=’0’ ttl=’0’ tos=’0’>
  <udp sport=’0’ dport=’0’/>
  <protocol type=’0’/>
  </ipv4>
</target>

  3. All of the IPv4 attributes are optional:

    1. src - Source address in IPv4 header. Valid range 0.0.0.0 - 255.255.255.255, where 0.0.0.0 implies don’t care.
    2. dst - Destination address in IPv4 header. Valid range 0.0.0.0 - 255.255.255.255, where 0.0.0.0 implies don’t care.
    3. len - Total length in IPv4 header. Valid range 0 - 65535, where 0 implies don’t care.
    4. ttl - Time to live in IPv4 header. Valid range 0 - 255, where 0 implies don’t care.
    5. tos - Type of Service/Differentiated Services in IPv4 header. Valid range 0 - 255, where 0 implies don’t care.

    In addition, a filter can be defined via the IPv4 protocol field in the header. The communication protocol can be defined by name or numerical value. Currently, udp is the only protocol that can be defined by name. All other protocols must be identified via numerical value.

    1. udp - Used to identify UDP protocol by name. When using this mechanism to define the udp protocol, sport and/or dport can also be identified for the udp protocol header. The valid range for sport and dport are 0 to 65535, where 0 implies don’t care.

      <target>
  <ipv4 dst=’224.1.2.3’>
    <udp sport=’12345’ dport=’12346’/>
  </ipv4>
</target>

    2. protocol - Used when identifying the communication protocol based on numerical value. The type attribute identifies the numerical value for the IPv4 communication protocol with a valid range from 0 to 255.

      <target>
  <ipv4 dst=’224.1.2.3’>
    <protocol type=’89’/>
  </ipv4>
</target>

  4. Each filter is assigned static network impairments (loss, latency, jitter, duplicates, unicastbitrate and broadcastbitrate).

    <effect>
  <loss>20</loss>
  <duplicate>0</duplicate>
  <latency sec=’0’ usec=’200000’/>
  <jitter sec=’0’ usec=’0’/>
  <broadcastbitrate>1024</broadcastbitrate>
  <unicastbitrate>8096</unicastbitrate>
</effect>

    The effect element has the following format:

    1. loss - The loss 0 to 100 in percentage to be applied to the packets that match the associated target.
    2. duplicate - The duplicates 0 to 100 in percentage to be applied to the packets that match the associated target.
    3. latency - The fixed average delay to be applied to the packets that match the associated target.
      sec - Seconds have a valid range 0 to 65535.
      usec -Microseconds have a valid range 0 to 999999.
    4. jitter - The random variation applied to the packets that match the associated target.
      sec - Seconds have a valid range 0 to 65535.
      usec - Microseconds have a valid range 0 to 999999.
    5. unicastbitrate - The bitrate (bps) applied to packets addressed to the NEM or received in promiscuous mode matching the associated target . The bitrate has a valid range from 0, meaning unused, to max unsigned 64 bit number.
    6. broadcastbitrate -The bitrate (bps) applied to packets addressed to the NEM broadcast address matching the associated target . The bitrate has a valid range from 0, meaning unused, to max unsigned 64 bit number.

  5. The filters and their associated impairments are defined at initialization and cannot be altered during emulation.

  6. Filter ordering determines the network impairment, and as such, more specific filters should be defined first. Each received packet is evaluated against the defined filters in order and the first match determines the impairment to be applied. In the below example, a packet as it is received by a node will be evaluated against each of the four filters (OSPF, TOS, UDP, DEFAULT) in order and the respective effect will be applied based on the first match. It should be noted that the inclusion of the DEFAULT filter should only be used when Comm Effect events are not being utilized since the filters take precedence. When filters are used in conjunction with Comm Effect events, the event driven impairments serve as the default effect for all packets that do not match a filter target.

    <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE commeffect SYSTEM "file:///usr/share/emane/dtd/commeffectfilters.dtd">
<commeffect>
<filter>
  <description>OSPF Packets</description>
  <target>
    <ipv4>
      <protocol type="89"/>
    </ipv4>
  </target>
  <effect>
    <loss>0</loss>
    <duplicate>0</duplicate>
    <latency sec='0' usec='0'/>
    <jitter sec='0' usec='0'/>
  </effect>
</filter>
<filter>
  <description>TOS (Type of Service) = 192</description>
  <target>
    <ipv4 tos='192'>
    </ipv4>
  </target>
  <effect>
    <loss>10</loss>
    <duplicate>150</duplicate>
    <latency sec='0' usec='100000'/>
    <jitter sec='0' usec='0'/>
  </effect>
</filter>
<filter>
  <description>UDP Multicast (destination address = 224.1.2.3 and destination port = 12345)</description>
  <target>
    <ipv4 dst='224.1.2.3'>
      <udp dport='12345'/>
    </ipv4>
  </target>
  <effect>
    <loss>20</loss>
    <duplicate>0</duplicate>
    <latency sec='0' usec='200000'/>
    <jitter sec='0' usec='0'/>
  </effect>
</filter>
<filter>
  <description>DEFAULT:  All Other Packets</description>
  <target/>
  <effect>
    <loss>40</loss>
    <duplicate>30</duplicate>
    <latency sec='0' usec='600000'/>
    <jitter sec='0' usec='100000'/>
    <broadcastbitrate>8096</broadcastbitrate>
    <unicastbitrate>8096</unicastbitrate>
  </effect>
</filter>
</commeffect>

Configuration Parameters

The following configuration parameters are available to tailor layer functionality:

defaultconnectivitymode

Defines the default connectivity mode for Comm Effects. When set to on, full connectivity will be engaged until a valid Comm Effect event is received.

Type: bool
Running-State Modifiable: no
Occurrence Range: [1,1]
Value Range: [no,yes]
Default Value(s): yes

enablepromiscuousmode

Defines whether promiscuous mode is enabled or not. If promiscuous mode is enabled, all received packets (intended for the given node or not) that pass the receive test are sent upstream to the transport.

Type: bool
Running-State Modifiable: no
Occurrence Range: [1,1]
Value Range: [no,yes]
Default Value(s): no

filterfile

Defines the URI of the effects filter XML file which contains static filters to control network impairments.

Type: string
Running-State Modifiable: no
Occurrence Range: [1,1]

groupid

Defines the Comm Effect Group Id. Only NEMs in the same Comm Effect Group can communicate.

Type: uint32
Running-State Modifiable: no
Occurrence Range: [1,1]
Value Range: [0,4294967295]
Default Value(s): 0

receivebufferperiod

Defines the max buffering time in seconds for packets received from an NEM. The buffering interval for a given packet is determined by the bitrate for the source NEM and the packet size. Packets are then placed in a timed queue based on this interval and all packets that would cause the receive buffer period to be exceeded are discarded. A value of 0.0 disables the limit and allows all received packets to stack up in the queue.

Type: double
Running-State Modifiable: no
Occurrence Range: [1,1]
Value Range: [-DOUBLE_MAX,DOUBLE_MAX]
Default Value(s): 1.000000

Example XML

Comm Effect configuration is specified using two files:

  1. NEM definition file
  2. Shim definition file

The NEM definition file groups the Shim definition file together with the transport definition file. The Comm Effect Model is not a radio model. It does not use the emulator physical layer so you must set the NEM type attribute to unstructured.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE nem SYSTEM "file:///usr/share/emane/dtd/nem.dtd">
<nem type="unstructured">
  <transport definition="transvirtual.xml"/>
  <shim definition="commeffectshim.xml"/>
</nem>

The Shim definition file specifies the model DLL the emulator will load and the desired model configuration.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE shim SYSTEM "file:///usr/share/emane/dtd/shim.dtd">
<shim library="commeffectshim">
 <param name="defaultconnectivity" value="off" />
 <param name="enablepromiscuousmode" value="off" />
</shim>

Statistics

The below statistics can be accessed using emanesh.

Name Type Clearable Description
avgDownstreamProcessingDelay0 float yes Average downstream processing delay
avgProcessAPIQueueDepth double yes Average API queue depth for a processUpstreamPacket, processUpstreamControl, processDownstreamPacket, processDownstreamControl, processEvent and processTimedEvent.
avgProcessAPIQueueWait double yes Average API queue wait for a processUpstreamPacket, processUpstreamControl, processDownstreamPacket, processDownstreamControl, processEvent and processTimedEvent in microseconds.
avgTimedEventLatency double yes
avgTimedEventLatencyRatio double yes Average ratio of the delta between the scheduled timer expiration and the actual firing over the requested duration. An average ratio approaching 1 indicates that timer latencies are large in comparison to the requested durations.
avgUpstreamProcessingDelay0 float yes Average upstream processing delay
numDownstreamBytesBroadcastGenerated0 uint64 yes Number of layer generated downstream broadcast bytes
numDownstreamBytesBroadcastRx0 uint64 yes Number of downstream broadcast bytes received
numDownstreamBytesBroadcastTx0 uint64 yes Number of downstream broadcast bytes transmitted
numDownstreamBytesUnicastGenerated0 uint64 yes Number of layer generated downstream unicast bytes
numDownstreamBytesUnicastRx0 uint64 yes Number of downstream unicast bytes received
numDownstreamBytesUnicastTx0 uint64 yes Number of downstream unicast bytes transmitted
numDownstreamPacketsBroadcastDrop0 uint64 yes Number of downstream broadcast packets dropped
numDownstreamPacketsBroadcastGenerated0 uint64 yes Number of layer generated downstream broadcast packets
numDownstreamPacketsBroadcastRx0 uint64 yes Number of downstream broadcast packets received
numDownstreamPacketsBroadcastTx0 uint64 yes Number of downstream broadcast packets transmitted
numDownstreamPacketsUnicastDrop0 uint64 yes Number of downstream unicast packets dropped
numDownstreamPacketsUnicastGenerated0 uint64 yes Number of layer generated downstream unicast packets
numDownstreamPacketsUnicastRx0 uint64 yes Number of downstream unicast packets received
numDownstreamPacketsUnicastTx0 uint64 yes Number of downstream unicast packets transmitted
numUpstreamBytesBroadcastRx0 uint64 yes Number of upstream broadcast bytes received
numUpstreamBytesBroadcastTx0 uint64 yes Number of updtream broadcast bytes transmitted
numUpstreamBytesUnicastRx0 uint64 yes Number upstream unicast bytes received
numUpstreamBytesUnicastTx0 uint64 yes Number of upstream unicast bytes transmitted
numUpstreamPacketsBroadcastDrop0 uint64 yes Number of upstream broadcast packets dropped
numUpstreamPacketsBroadcastRx0 uint64 yes Number of upstream broadcast packets received
numUpstreamPacketsBroadcastTx0 uint64 yes Number of upstream broadcast packets transmitted
numUpstreamPacketsUnicastDrop0 uint64 yes Number of upstream unicast packets dropped
numUpstreamPacketsUnicastRx0 uint64 yes Number upstream unicast packets received
numUpstreamPacketsUnicastTx0 uint64 yes Number of upstream unicast packets transmitted
processedConfiguration uint64 yes
processedDownstreamControl uint64 yes
processedDownstreamPackets uint64 yes
processedEvents uint64 yes
processedTimedEvents uint64 yes
processedUpstreamControl uint64 yes
processedUpstreamPackets uint64 yes

Statistic Tables

The below statistics can be accessed using emanesh.

Name Clearable Description
BroadcastPacketAcceptTable0 yes Broadcast packets accepted
BroadcastPacketDropTable0 yes Broadcast packets dropped by reason code
EventReceptionTable yes Received event counts
UnicastPacketAcceptTable0 yes Unicast packets accepted
UnicastPacketDropTable0 yes Unicast packets dropped by reason code
Clone this wiki locally