diff options
| -rwxr-xr-x | docs/design/index.rst | 2 | ||||
| -rw-r--r-- | docs/design/trafficgen_integration_guide.rst | 199 |
2 files changed, 201 insertions, 0 deletions
diff --git a/docs/design/index.rst b/docs/design/index.rst index bb189cb0..425a32ac 100755 --- a/docs/design/index.rst +++ b/docs/design/index.rst @@ -7,3 +7,5 @@ VSPERF Design :maxdepth: 3 vswitchperf_design.rst + + trafficgen_integration_guide.rst diff --git a/docs/design/trafficgen_integration_guide.rst b/docs/design/trafficgen_integration_guide.rst new file mode 100644 index 00000000..bd41dd95 --- /dev/null +++ b/docs/design/trafficgen_integration_guide.rst @@ -0,0 +1,199 @@ +=================================== +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 +<http://artifacts.opnfv.org/vswitchperf/docs/design/index.html>`__. + +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. + |