.. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, Intel Corporation, AT&T and others. =================================== Traffic Generator Integration Guide =================================== 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. 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. .. code-block:: console $ mkdir tools/pkt_gen/sample_tg 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. .. code-block:: python from tools.pkt_gen import trafficgen class SampleTG(trafficgen.ITrafficGenerator): """ A sample traffic generator implementation """ pass VSPERF is immediately aware of the new class: .. code-block:: console $ ./vsperf --list-trafficgen Output should look like: .. code-block:: console 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 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: .. code-block:: python 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) 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: .. code-block:: python def connect(self): pass def disconnect(self): pass 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: .. code-block:: python def send_rfc2544_throughput(self, traffic=None, trials=3, duration=20, lossrate=0.0, multistream=False): def send_rfc2544_back2back(self, traffic=None, trials=1, duration=20, lossrate=0.0): def send_cont_traffic(self, traffic=None, duration=20, multistream=False): Example of asynchronous interfaces: .. code-block:: python def start_rfc2544_throughput(self, traffic=None, trials=3, duration=20, lossrate=0.0): def wait_rfc2544_throughput(self): def start_rfc2544_back2back(self, traffic=None, trials=1, duration=20, lossrate=0.0): def wait_rfc2544_back2back(self): def start_cont_traffic(self, traffic=None, duration=20, multistream=False): def stop_cont_traffic(self): Description of parameters used by **send**, **start**, **wait** and **stop** functions: * param **trials**: Number of trials to execute * param **duration**: Duration of continuous test or per iteration duration in case of RFC2544 throughput or back2back traffic types. * param **lossrate**: Acceptable lossrate percentage. * param **multistream**: Enable or disable multistream feature. 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. .. Revision: e7d5da52871dd4f93db5cb2b07fd7fe2049632ff Build date: 2016-03-05