docs/testing/developer/devguide/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 :ref:`vsperf-design`.
  15
  16 Let us create a sample traffic generator called **sample_tg**, step by step.
  17
  18 Step 1 - create a directory
  19 ===========================
  20
  21 Implementation of trafficgens is located at tools/pkt_gen/ directory,
  22 where every implementation has its dedicated sub-directory. It is
  23 required to create a new directory for new traffic generator
  24 implementations.
  25
  26 E.g.
  27
  28 .. code-block:: console
  29
  30    $ mkdir tools/pkt_gen/sample_tg
  31
  32 Step 2 - create a trafficgen module
  33 ===================================
  34
  35 Every trafficgen class must inherit from generic **ITrafficGenerator**
  36 interface class. VSPERF during its initialization scans content of pkt_gen
  37 directory for all python modules, that inherit from **ITrafficGenerator**. These
  38 modules are automatically added into the list of supported traffic generators.
  39
  40 Example:
  41
  42 Let us create a draft of tools/pkt_gen/sample_tg/sample_tg.py module.
  43
  44 .. code-block:: python
  45
  46     from tools.pkt_gen import trafficgen
  47
  48     class SampleTG(trafficgen.ITrafficGenerator):
  49         """
  50         A sample traffic generator implementation
  51         """
  52         pass
  53
  54 VSPERF is immediately aware of the new class:
  55
  56 .. code-block:: console
  57
  58    $ ./vsperf --list-trafficgen
  59
  60 Output should look like:
  61
  62 .. code-block:: console
  63
  64    Classes derived from: ITrafficGenerator
  65    ======
  66
  67    * Ixia:             A wrapper around the IXIA traffic generator.
  68
  69    * IxNet:            A wrapper around IXIA IxNetwork applications.
  70
  71    * Dummy:            A dummy traffic generator whose data is generated by the user.
  72
  73    * SampleTG:         A sample traffic generator implementation
  74
  75    * TestCenter:       Spirent TestCenter
  76
  77
  78 Step 3 - configuration
  79 ======================
  80
  81 All configuration values, required for correct traffic generator function, are passed
  82 from VSPERF to the traffic generator in a dictionary. Default values shared among
  83 all traffic generators are defined in **conf/03_traffic.conf** within **TRAFFIC**
  84 dictionary. Default values are loaded by **ITrafficGenerator** interface class
  85 automatically, so it is not needed to load them explicitly. In case that there are
  86 any traffic generator specific default values, then they should be set within class
  87 specific **__init__** function.
  88
  89 VSPERF passes test specific configuration within **traffic** dictionary to every
  90 start and send function. So implementation of these functions must ensure,
  91 that default values are updated with the testcase specific values. Proper merge
  92 of values is assured by call of **merge_spec** function from **conf** module.
  93
  94 Example of **merge_spec** usage in **tools/pkt_gen/sample_tg/sample_tg.py** module:
  95
  96 .. code-block:: python
  97
  98     from conf import merge_spec
  99
 100     def start_rfc2544_throughput(self, traffic=None, duration=30):
 101         self._params = {}
 102         self._params['traffic'] = self.traffic_defaults.copy()
 103         if traffic:
 104             self._params['traffic'] = merge_spec(
 105                 self._params['traffic'], traffic)
 106
 107
 108 Step 4 - generic functions
 109 ==========================
 110
 111 There are some generic functions, which every traffic generator should provide.
 112 Although these functions are mainly optional, at least empty implementation must
 113 be provided. This is required, so that developer is explicitly aware of these
 114 functions.
 115
 116 The **connect** function is called from the traffic generator controller from its
 117 **__enter__** method. This function should assure proper connection initialization
 118 between DUT and traffic generator. In case, that such implementation is not needed,
 119 empty implementation is required.
 120
 121 The **disconnect** function should perform clean up of any connection specific
 122 actions called from the **connect** function.
 123
 124 Example in **tools/pkt_gen/sample_tg/sample_tg.py** module:
 125
 126 .. code-block:: python
 127
 128     def connect(self):
 129         pass
 130
 131     def disconnect(self):
 132         pass
 133
 134 .. _step-5-supported-traffic-types:
 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 :ref:`integration-tests` userguide.
 197
 198       * param **traffic_type**: One of the supported traffic types,
 199         e.g. **rfc2544_throughput**, **rfc2544_continuous**
 200         or **rfc2544_back2back**.
 201       * param **frame_rate**: Defines desired percentage of frame
 202         rate used during continuous stream tests.
 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**, **proto** and l3 on/off switch **enabled**.
 219       * param **l4**: A dictionary with transport layer details, e.g. **srcport**,
 220         **dstport** and l4 on/off switch **enabled**.
 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