docs/design/trafficgen_integration_guide.rst

   1 ===================================
   2 Traffic Generator Integration Guide
   3 ===================================
   4
   5 Intended Audience
   6 =================
   7
   8 This document is intended to aid those who want to integrate new traffic
   9 generator into the vsperf code. It is expected, that reader has already
  10 read generic part of `VSPERF Design Document
  11 <http://artifacts.opnfv.org/vswitchperf/docs/design/index.html>`__.
  12
  13 Let us create a sample traffic generator called **sample_tg**, step by step.
  14
  15 Step 1 - create a directory
  16 ===========================
  17
  18 Implementation of trafficgens is located at tools/pkt_gen/ directory,
  19 where every implementation has its dedicated sub-directory. It is
  20 required to create a new directory for new traffic generator
  21 implementations.
  22
  23 E.g.
  24
  25 .. code-block:: console
  26
  27    $ mkdir tools/pkt_gen/sample_tg
  28
  29 Step 2 - create a trafficgen module
  30 ===================================
  31
  32 Every trafficgen class must inherit from generic **ITrafficGenerator**
  33 interface class. VSPERF during its initialization scans content of pkt_gen
  34 directory for all python modules, that inherit from **ITrafficGenerator**. These
  35 modules are automatically added into the list of supported traffic generators.
  36
  37 Example:
  38
  39 Let us create a draft of tools/pkt_gen/sample_tg/sample_tg.py module.
  40
  41 .. code-block:: python
  42
  43     from tools.pkt_gen import trafficgen
  44
  45     class SampleTG(trafficgen.ITrafficGenerator):
  46         """
  47         A sample traffic generator implementation
  48         """
  49         pass
  50
  51 VSPERF is immediately aware of the new class:
  52
  53 .. code-block:: console
  54
  55    $ ./vsperf --list-trafficgen
  56
  57 Output should look like:
  58
  59 .. code-block:: console
  60
  61    Classes derived from: ITrafficGenerator
  62    ======
  63
  64    * Ixia:             A wrapper around the IXIA traffic generator.
  65
  66    * IxNet:            A wrapper around IXIA IxNetwork applications.
  67
  68    * Dummy:            A dummy traffic generator whose data is generated by the user.
  69
  70    * SampleTG:         A sample traffic generator implementation
  71
  72    * TestCenter:       Spirent TestCenter
  73
  74
  75 Step 3 - configuration
  76 ======================
  77
  78 All configuration values, required for correct traffic generator function, are passed
  79 from VSPERF to the traffic generator in a dictionary. Default values shared among
  80 all traffic generators are defined in **tools/pkt_gen/trafficgen/trafficgenhelper.py**
  81 as **TRAFFIC_DEFAULTS** dictionary. Default values are loaded by **ITrafficGenerator**
  82 interface class automatically, so it is not needed to load them explicitly. In case
  83 that there are any traffic generator specific default values, then they should
  84 be set within class specific **__init__** function.
  85
  86 VSPERF passes test specific configuration within **traffic** dictionary to every
  87 start and send function. So implementation of these functions must ensure,
  88 that default values are updated with the testcase specific values. Proper merge
  89 of values is assured by call of **merge_spec** function from **trafficgenhelper**
  90 module.
  91
  92 Example of **merge_spec** usage in **tools/pkt_gen/sample_tg/sample_tg.py** module:
  93
  94 .. code-block:: python
  95
  96     from tools.pkt_gen.trafficgen.trafficgenhelper import merge_spec
  97
  98     def start_rfc2544_throughput(self, traffic=None, duration=30):
  99         self._params = {}
 100         self._params['traffic'] = self.traffic_defaults.copy()
 101         if traffic:
 102             self._params['traffic'] = trafficgen.merge_spec(
 103                 self._params['traffic'], traffic)
 104
 105
 106 Step 4 - generic functions
 107 ==========================
 108
 109 There are some generic functions, which every traffic generator should provide.
 110 Although these functions are mainly optional, at least empty implementation must
 111 be provided. This is required, so that developer is explicitly aware of these
 112 functions.
 113
 114 The **connect** function is called from the traffic generator controller from its
 115 **__enter__** method. This function should assure proper connection initialization
 116 between DUT and traffic generator. In case, that such implementation is not needed,
 117 empty implementation is required.
 118
 119 The **disconnect** function should perform clean up of any connection specific
 120 actions called from the **connect** function.
 121
 122 Example in **tools/pkt_gen/sample_tg/sample_tg.py** module:
 123
 124 .. code-block:: python
 125
 126     def connect(self):
 127         pass
 128
 129     def disconnect(self):
 130         pass
 131
 132 Step 5 - supported traffic types
 133 ================================
 134
 135 Currently VSPERF supports three different types of tests for traffic generators,
 136 these are identified in vsperf through the traffic type, which include:
 137
 138     * RFC2544 throughput - Send fixed size packets at different rates, using
 139         traffic configuration, until minimum rate at which no packet loss is
 140         detected is found. Methods with its implementation have suffix
 141         **_rfc2544_throughput**.
 142
 143     * RFC2544 back2back - Send fixed size packets at a fixed rate, using traffic
 144         configuration, for specified time interval. Methods with its
 145         implementation have suffix **_rfc2544_back2back**.
 146
 147     * continuous flow - Send fixed size packets at given framerate, using traffic
 148         configuration, for specified time interval. Methods with its
 149         implementation have suffix **_cont_traffic**.
 150
 151 In general, both synchronous and asynchronous interfaces must be implemented
 152 for each traffic type. Synchronous functions start with prefix **send_**.
 153 Asynchronous with prefixes **start_** and **wait_** in case of throughput
 154 and back2back and **start_** and **stop_** in case of continuous traffic type.
 155
 156 Example of synchronous interfaces:
 157
 158 .. code-block:: python
 159
 160     def send_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
 161                                 lossrate=0.0, multistream=False):
 162     def send_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
 163                                lossrate=0.0):
 164     def send_cont_traffic(self, traffic=None, duration=20, multistream=False):
 165
 166 Example of asynchronous interfaces:
 167
 168 .. code-block:: python
 169
 170     def start_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
 171                                  lossrate=0.0):
 172     def wait_rfc2544_throughput(self):
 173
 174     def start_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
 175                                 lossrate=0.0):
 176     def wait_rfc2544_back2back(self):
 177
 178     def start_cont_traffic(self, traffic=None, duration=20, multistream=False):
 179     def stop_cont_traffic(self):
 180
 181 Description of parameters used by **send**, **start**, **wait** and **stop**
 182 functions:
 183
 184     * param **trials**: Number of trials to execute
 185     * param **duration**: Duration of continuous test or per iteration duration
 186         in case of RFC2544 throughput or back2back traffic types.
 187     * param **lossrate**: Acceptable lossrate percentage.
 188     * param **multistream**: Enable or disable multistream feature.
 189
 190 Step 6 - passing back results
 191 =============================
 192
 193 It is expected that methods **send**, **wait** and **stop** will return
 194 values measured by traffic generator within a dictionary. Dictionary keys
 195 are defined in **ResultsConstants** implemented in
 196 **core/results/results_constants.py**. Please check sections for RFC2544
 197 Throughput & Continuous and for Back2Back. The same key names should
 198 be used by all traffic generator implementations.
 199