docs/design/trafficgen_integration_guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation, AT&T and others.
   4
   5 ===================================
   6 Traffic Generator Integration Guide
   7 ===================================
   8
   9 Intended Audience
  10 =================
  11
  12 This document is intended to aid those who want to integrate new traffic
  13 generator into the vsperf code. It is expected, that reader has already
  14 read generic part of `VSPERF Design Document
  15 <http://artifacts.opnfv.org/vswitchperf/docs/design/index.html>`__.
  16
  17 Let us create a sample traffic generator called **sample_tg**, step by step.
  18
  19 Step 1 - create a directory
  20 ===========================
  21
  22 Implementation of trafficgens is located at tools/pkt_gen/ directory,
  23 where every implementation has its dedicated sub-directory. It is
  24 required to create a new directory for new traffic generator
  25 implementations.
  26
  27 E.g.
  28
  29 .. code-block:: console
  30
  31    $ mkdir tools/pkt_gen/sample_tg
  32
  33 Step 2 - create a trafficgen module
  34 ===================================
  35
  36 Every trafficgen class must inherit from generic **ITrafficGenerator**
  37 interface class. VSPERF during its initialization scans content of pkt_gen
  38 directory for all python modules, that inherit from **ITrafficGenerator**. These
  39 modules are automatically added into the list of supported traffic generators.
  40
  41 Example:
  42
  43 Let us create a draft of tools/pkt_gen/sample_tg/sample_tg.py module.
  44
  45 .. code-block:: python
  46
  47     from tools.pkt_gen import trafficgen
  48
  49     class SampleTG(trafficgen.ITrafficGenerator):
  50         """
  51         A sample traffic generator implementation
  52         """
  53         pass
  54
  55 VSPERF is immediately aware of the new class:
  56
  57 .. code-block:: console
  58
  59    $ ./vsperf --list-trafficgen
  60
  61 Output should look like:
  62
  63 .. code-block:: console
  64
  65    Classes derived from: ITrafficGenerator
  66    ======
  67
  68    * Ixia:             A wrapper around the IXIA traffic generator.
  69
  70    * IxNet:            A wrapper around IXIA IxNetwork applications.
  71
  72    * Dummy:            A dummy traffic generator whose data is generated by the user.
  73
  74    * SampleTG:         A sample traffic generator implementation
  75
  76    * TestCenter:       Spirent TestCenter
  77
  78
  79 Step 3 - configuration
  80 ======================
  81
  82 All configuration values, required for correct traffic generator function, are passed
  83 from VSPERF to the traffic generator in a dictionary. Default values shared among
  84 all traffic generators are defined in **tools/pkt_gen/trafficgen/trafficgenhelper.py**
  85 as **TRAFFIC_DEFAULTS** dictionary. Default values are loaded by **ITrafficGenerator**
  86 interface class automatically, so it is not needed to load them explicitly. In case
  87 that there are any traffic generator specific default values, then they should
  88 be set within class specific **__init__** function.
  89
  90 VSPERF passes test specific configuration within **traffic** dictionary to every
  91 start and send function. So implementation of these functions must ensure,
  92 that default values are updated with the testcase specific values. Proper merge
  93 of values is assured by call of **merge_spec** function from **trafficgenhelper**
  94 module.
  95
  96 Example of **merge_spec** usage in **tools/pkt_gen/sample_tg/sample_tg.py** module:
  97
  98 .. code-block:: python
  99
 100     from tools.pkt_gen.trafficgen.trafficgenhelper import merge_spec
 101
 102     def start_rfc2544_throughput(self, traffic=None, duration=30):
 103         self._params = {}
 104         self._params['traffic'] = self.traffic_defaults.copy()
 105         if traffic:
 106             self._params['traffic'] = trafficgen.merge_spec(
 107                 self._params['traffic'], traffic)
 108
 109
 110 Step 4 - generic functions
 111 ==========================
 112
 113 There are some generic functions, which every traffic generator should provide.
 114 Although these functions are mainly optional, at least empty implementation must
 115 be provided. This is required, so that developer is explicitly aware of these
 116 functions.
 117
 118 The **connect** function is called from the traffic generator controller from its
 119 **__enter__** method. This function should assure proper connection initialization
 120 between DUT and traffic generator. In case, that such implementation is not needed,
 121 empty implementation is required.
 122
 123 The **disconnect** function should perform clean up of any connection specific
 124 actions called from the **connect** function.
 125
 126 Example in **tools/pkt_gen/sample_tg/sample_tg.py** module:
 127
 128 .. code-block:: python
 129
 130     def connect(self):
 131         pass
 132
 133     def disconnect(self):
 134         pass
 135
 136 Step 5 - supported traffic types
 137 ================================
 138
 139 Currently VSPERF supports three different types of tests for traffic generators,
 140 these are identified in vsperf through the traffic type, which include:
 141
 142     * RFC2544 throughput - Send fixed size packets at different rates, using
 143         traffic configuration, until minimum rate at which no packet loss is
 144         detected is found. Methods with its implementation have suffix
 145         **_rfc2544_throughput**.
 146
 147     * RFC2544 back2back - Send fixed size packets at a fixed rate, using traffic
 148         configuration, for specified time interval. Methods with its
 149         implementation have suffix **_rfc2544_back2back**.
 150
 151     * continuous flow - Send fixed size packets at given framerate, using traffic
 152         configuration, for specified time interval. Methods with its
 153         implementation have suffix **_cont_traffic**.
 154
 155 In general, both synchronous and asynchronous interfaces must be implemented
 156 for each traffic type. Synchronous functions start with prefix **send_**.
 157 Asynchronous with prefixes **start_** and **wait_** in case of throughput
 158 and back2back and **start_** and **stop_** in case of continuous traffic type.
 159
 160 Example of synchronous interfaces:
 161
 162 .. code-block:: python
 163
 164     def send_rfc2544_throughput(self, traffic=None, tests=1, duration=20,
 165                                 lossrate=0.0):
 166     def send_rfc2544_back2back(self, traffic=None, tests=1, duration=20,
 167                                lossrate=0.0):
 168     def send_cont_traffic(self, traffic=None, duration=20):
 169
 170 Example of asynchronous interfaces:
 171
 172 .. code-block:: python
 173
 174     def start_rfc2544_throughput(self, traffic=None, tests=1, duration=20,
 175                                  lossrate=0.0):
 176     def wait_rfc2544_throughput(self):
 177
 178     def start_rfc2544_back2back(self, traffic=None, tests=1, duration=20,
 179                                 lossrate=0.0):
 180     def wait_rfc2544_back2back(self):
 181
 182     def start_cont_traffic(self, traffic=None, duration=20):
 183     def stop_cont_traffic(self):
 184
 185 Description of parameters used by **send**, **start**, **wait** and **stop**
 186 functions:
 187
 188     * param **traffic**: A dictionary with detailed definition of traffic
 189       pattern. It contains following parameters to be implemented by
 190       traffic generator.
 191
 192       Note: Traffic dictionary has also virtual switch related parameters,
 193       which are not listed below.
 194
 195       Note: There are parameters specific to testing of tunnelling protocols,
 196       which are discussed in detail at `integration tests userguide`_
 197
 198       * param **traffic_type**: One of the supported traffic types,
 199         e.g. **rfc2544**, **continuous** or **back2back**.
 200       * param **frame_rate**: Defines desired percentage of frame
 201         rate used during continuous stream tests. It can be set by test
 202         parameter iLoad or by CLI parameter iload.
 203       * param **bidir**: Specifies if generated traffic will be full-duplex
 204         (true) or half-duplex (false).
 205       * param **multistream**: Defines number of flows simulated by traffic
 206         generator. Value 0 disables MultiStream feature.
 207       * param **stream_type**: Stream Type defines ISO OSI network layer
 208         used for simulation of multiple streams.
 209         Supported values:
 210
 211         * **L2** - iteration of destination MAC address
 212         * **L3** - iteration of destination IP address
 213         * **L4** - iteration of destination port of selected transport protocol
 214
 215       * param **l2**: A dictionary with data link layer details, e.g. **srcmac**,
 216         **dstmac** and **framesize**.
 217       * param **l3**: A dictionary with network layer details, e.g. **srcip**,
 218         **dstip** and **proto**.
 219       * param **l3**: A dictionary with transport layer details, e.g. **srcport**,
 220         **dstport**.
 221       * param **vlan**: A dictionary with vlan specific parameters,
 222         e.g. **priority**, **cfi**, **id** and vlan on/off switch **enabled**.
 223
 224     * param **tests**: Number of times the test is executed.
 225     * param **duration**: Duration of continuous test or per iteration duration
 226       in case of RFC2544 throughput or back2back traffic types.
 227     * param **lossrate**: Acceptable lossrate percentage.
 228
 229 Step 6 - passing back results
 230 =============================
 231
 232 It is expected that methods **send**, **wait** and **stop** will return
 233 values measured by traffic generator within a dictionary. Dictionary keys
 234 are defined in **ResultsConstants** implemented in
 235 **core/results/results_constants.py**. Please check sections for RFC2544
 236 Throughput & Continuous and for Back2Back. The same key names should
 237 be used by all traffic generator implementations.
 238
 239 .. _integration tests userguide: http://artifacts.opnfv.org/vswitchperf/docs/userguide/integration.html
 240