docs: traffic generator integration guide

Simple guide with description of integration
of new traffic generator into the VSPERF.

Change-Id: Iab84d1356dbf3ef3405817606c094ffe31355b9f
JIRA: VSPERF-174
Signed-off-by: Martin Klozik <martinx.klozik@intel.com>
Reviewed-by: Maryam Tahhan <maryam.tahhan@intel.com>
Reviewed-by: Al Morton <acmorton@att.com>
Reviewed-by: Brian Castelli <brian.castelli@spirent.com>
Reviewed-by: Christian Trautman <ctrautma@redhat.com>

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.
+