2. Traffic Generator Integration Guide

2.1. Intended Audience

This document is intended to aid those who want to integrate new traffic generator into the vsperf code. It is expected, that reader has already read generic part of VSPERF Design Document.

Let us create a sample traffic generator called sample_tg, step by step.

2.2. Step 1 - create a directory

Implementation of trafficgens is located at tools/pkt_gen/ directory, where every implementation has its dedicated sub-directory. It is required to create a new directory for new traffic generator implementations.

E.g.

$ mkdir tools/pkt_gen/sample_tg

2.3. Step 2 - create a trafficgen module

Every trafficgen class must inherit from generic ITrafficGenerator interface class. VSPERF during its initialization scans content of pkt_gen directory for all python modules, that inherit from ITrafficGenerator. These modules are automatically added into the list of supported traffic generators.

Example:

Let us create a draft of tools/pkt_gen/sample_tg/sample_tg.py module.

from tools.pkt_gen import trafficgen

class SampleTG(trafficgen.ITrafficGenerator):
    """
    A sample traffic generator implementation
    """
    pass

VSPERF is immediately aware of the new class:

$ ./vsperf --list-trafficgen

Output should look like:

Classes derived from: ITrafficGenerator
======

* Ixia:             A wrapper around the IXIA traffic generator.

* IxNet:            A wrapper around IXIA IxNetwork applications.

* Dummy:            A dummy traffic generator whose data is generated by the user.

* SampleTG:         A sample traffic generator implementation

* TestCenter:       Spirent TestCenter

2.4. Step 3 - configuration

All configuration values, required for correct traffic generator function, are passed from VSPERF to the traffic generator in a dictionary. Default values shared among all traffic generators are defined in tools/pkt_gen/trafficgen/trafficgenhelper.py as TRAFFIC_DEFAULTS dictionary. Default values are loaded by ITrafficGenerator interface class automatically, so it is not needed to load them explicitly. In case that there are any traffic generator specific default values, then they should be set within class specific __init__ function.

VSPERF passes test specific configuration within traffic dictionary to every start and send function. So implementation of these functions must ensure, that default values are updated with the testcase specific values. Proper merge of values is assured by call of merge_spec function from trafficgenhelper module.

Example of merge_spec usage in tools/pkt_gen/sample_tg/sample_tg.py module:

from tools.pkt_gen.trafficgen.trafficgenhelper import merge_spec

def start_rfc2544_throughput(self, traffic=None, duration=30):
    self._params = {}
    self._params['traffic'] = self.traffic_defaults.copy()
    if traffic:
        self._params['traffic'] = trafficgen.merge_spec(
            self._params['traffic'], traffic)

2.5. Step 4 - generic functions

There are some generic functions, which every traffic generator should provide. Although these functions are mainly optional, at least empty implementation must be provided. This is required, so that developer is explicitly aware of these functions.

The connect function is called from the traffic generator controller from its __enter__ method. This function should assure proper connection initialization between DUT and traffic generator. In case, that such implementation is not needed, empty implementation is required.

The disconnect function should perform clean up of any connection specific actions called from the connect function.

Example in tools/pkt_gen/sample_tg/sample_tg.py module:

def connect(self):
    pass

def disconnect(self):
    pass

2.6. Step 5 - supported traffic types

Currently VSPERF supports three different types of tests for traffic generators, these are identified in vsperf through the traffic type, which include:

  • RFC2544 throughput - Send fixed size packets at different rates, using

    traffic configuration, until minimum rate at which no packet loss is detected is found. Methods with its implementation have suffix _rfc2544_throughput.

  • RFC2544 back2back - Send fixed size packets at a fixed rate, using traffic

    configuration, for specified time interval. Methods with its implementation have suffix _rfc2544_back2back.

  • continuous flow - Send fixed size packets at given framerate, using traffic

    configuration, for specified time interval. Methods with its implementation have suffix _cont_traffic.

In general, both synchronous and asynchronous interfaces must be implemented for each traffic type. Synchronous functions start with prefix send_. Asynchronous with prefixes start_ and wait_ in case of throughput and back2back and start_ and stop_ in case of continuous traffic type.

Example of synchronous interfaces:

def send_rfc2544_throughput(self, traffic=None, tests=1, duration=20,
                            lossrate=0.0):
def send_rfc2544_back2back(self, traffic=None, tests=1, duration=20,
                           lossrate=0.0):
def send_cont_traffic(self, traffic=None, duration=20):

Example of asynchronous interfaces:

def start_rfc2544_throughput(self, traffic=None, tests=1, duration=20,
                             lossrate=0.0):
def wait_rfc2544_throughput(self):

def start_rfc2544_back2back(self, traffic=None, tests=1, duration=20,
                            lossrate=0.0):
def wait_rfc2544_back2back(self):

def start_cont_traffic(self, traffic=None, duration=20):
def stop_cont_traffic(self):

Description of parameters used by send, start, wait and stop functions:

  • param traffic: A dictionary with detailed definition of traffic pattern. It contains following parameters to be implemented by traffic generator.

    Note: Traffic dictionary has also virtual switch related parameters, which are not listed below.

    Note: There are parameters specific to testing of tunnelling protocols, which are discussed in detail at integration tests userguide

    • param traffic_type: One of the supported traffic types, e.g. rfc2544, continuous or back2back.
    • param frame_rate: Defines desired percentage of frame rate used during continuous stream tests. It can be set by test parameter iLoad or by CLI parameter iload.
    • param bidir: Specifies if generated traffic will be full-duplex (true) or half-duplex (false).
    • param multistream: Defines number of flows simulated by traffic generator. Value 0 disables MultiStream feature.
    • param stream_type: Stream Type defines ISO OSI network layer used for simulation of multiple streams. Supported values:
      • L2 - iteration of destination MAC address
      • L3 - iteration of destination IP address
      • L4 - iteration of destination port of selected transport protocol
    • param l2: A dictionary with data link layer details, e.g. srcmac, dstmac and framesize.
    • param l3: A dictionary with network layer details, e.g. srcip, dstip and proto.
    • param l3: A dictionary with transport layer details, e.g. srcport, dstport.
    • param vlan: A dictionary with vlan specific parameters, e.g. priority, cfi, id and vlan on/off switch enabled.

  • param tests: Number of times the test is executed.

  • param duration: Duration of continuous test or per iteration duration in case of RFC2544 throughput or back2back traffic types.

  • param lossrate: Acceptable lossrate percentage.

2.7. Step 6 - passing back results

It is expected that methods send, wait and stop will return values measured by traffic generator within a dictionary. Dictionary keys are defined in ResultsConstants implemented in core/results/results_constants.py. Please check sections for RFC2544 Throughput & Continuous and for Back2Back. The same key names should be used by all traffic generator implementations.