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    * Dummy:            A dummy traffic generator whose data is generated by the user.
  68
  69    * IxNet:            A wrapper around IXIA IxNetwork applications.
  70
  71    * Ixia:             A wrapper around the IXIA traffic generator.
  72
  73    * Moongen:          Moongen Traffic generator wrapper.
  74
  75    * TestCenter:       Spirent TestCenter
  76
  77    * Trex:             Trex Traffic generator wrapper.
  78
  79    * Xena:             Xena Traffic generator wrapper class
  80
  81
  82 Step 3 - configuration
  83 ======================
  84
  85 All configuration values, required for correct traffic generator function, are passed
  86 from VSPERF to the traffic generator in a dictionary. Default values shared among
  87 all traffic generators are defined in **conf/03_traffic.conf** within **TRAFFIC**
  88 dictionary. Default values are loaded by **ITrafficGenerator** interface class
  89 automatically, so it is not needed to load them explicitly. In case that there are
  90 any traffic generator specific default values, then they should be set within class
  91 specific **__init__** function.
  92
  93 VSPERF passes test specific configuration within **traffic** dictionary to every
  94 start and send function. So implementation of these functions must ensure,
  95 that default values are updated with the testcase specific values. Proper merge
  96 of values is assured by call of **merge_spec** function from **conf** module.
  97
  98 Example of **merge_spec** usage in **tools/pkt_gen/sample_tg/sample_tg.py** module:
  99
 100 .. code-block:: python
 101
 102     from conf import merge_spec
 103
 104     def start_rfc2544_throughput(self, traffic=None, duration=30):
 105         self._params = {}
 106         self._params['traffic'] = self.traffic_defaults.copy()
 107         if traffic:
 108             self._params['traffic'] = merge_spec(
 109                 self._params['traffic'], traffic)
 110
 111
 112 Step 4 - generic functions
 113 ==========================
 114
 115 There are some generic functions, which every traffic generator should provide.
 116 Although these functions are mainly optional, at least empty implementation must
 117 be provided. This is required, so that developer is explicitly aware of these
 118 functions.
 119
 120 The **connect** function is called from the traffic generator controller from its
 121 **__enter__** method. This function should assure proper connection initialization
 122 between DUT and traffic generator. In case, that such implementation is not needed,
 123 empty implementation is required.
 124
 125 The **disconnect** function should perform clean up of any connection specific
 126 actions called from the **connect** function.
 127
 128 Example in **tools/pkt_gen/sample_tg/sample_tg.py** module:
 129
 130 .. code-block:: python
 131
 132     def connect(self):
 133         pass
 134
 135     def disconnect(self):
 136         pass
 137
 138 .. _step-5-supported-traffic-types:
 139
 140 Step 5 - supported traffic types
 141 ================================
 142
 143 Currently VSPERF supports three different types of tests for traffic generators,
 144 these are identified in vsperf through the traffic type, which include:
 145
 146     * RFC2544 throughput - Send fixed size packets at different rates, using
 147         traffic configuration, until minimum rate at which no packet loss is
 148         detected is found. Methods with its implementation have suffix
 149         **_rfc2544_throughput**.
 150
 151     * RFC2544 back2back - Send fixed size packets at a fixed rate, using traffic
 152         configuration, for specified time interval. Methods with its
 153         implementation have suffix **_rfc2544_back2back**.
 154
 155     * continuous flow - Send fixed size packets at given framerate, using traffic
 156         configuration, for specified time interval. Methods with its
 157         implementation have suffix **_cont_traffic**.
 158
 159 In general, both synchronous and asynchronous interfaces must be implemented
 160 for each traffic type. Synchronous functions start with prefix **send_**.
 161 Asynchronous with prefixes **start_** and **wait_** in case of throughput
 162 and back2back and **start_** and **stop_** in case of continuous traffic type.
 163
 164 Example of synchronous interfaces:
 165
 166 .. code-block:: python
 167
 168     def send_rfc2544_throughput(self, traffic=None, tests=1, duration=20,
 169                                 lossrate=0.0):
 170     def send_rfc2544_back2back(self, traffic=None, tests=1, duration=20,
 171                                lossrate=0.0):
 172     def send_cont_traffic(self, traffic=None, duration=20):
 173
 174 Example of asynchronous interfaces:
 175
 176 .. code-block:: python
 177
 178     def start_rfc2544_throughput(self, traffic=None, tests=1, duration=20,
 179                                  lossrate=0.0):
 180     def wait_rfc2544_throughput(self):
 181
 182     def start_rfc2544_back2back(self, traffic=None, tests=1, duration=20,
 183                                 lossrate=0.0):
 184     def wait_rfc2544_back2back(self):
 185
 186     def start_cont_traffic(self, traffic=None, duration=20):
 187     def stop_cont_traffic(self):
 188
 189 Description of parameters used by **send**, **start**, **wait** and **stop**
 190 functions:
 191
 192     * param **traffic**: A dictionary with detailed definition of traffic
 193       pattern. It contains following parameters to be implemented by
 194       traffic generator.
 195
 196       Note: Traffic dictionary has also virtual switch related parameters,
 197       which are not listed below.
 198
 199       Note: There are parameters specific to testing of tunnelling protocols,
 200       which are discussed in detail at :ref:`integration-tests` userguide.
 201
 202       Note: A detailed description of the ``TRAFFIC`` dictionary can be found at
 203       :ref:`configuration-of-traffic-dictionary`.
 204
 205       * param **traffic_type**: One of the supported traffic types,
 206         e.g. **rfc2544_throughput**, **rfc2544_continuous**,
 207         **rfc2544_back2back** or **burst**.
 208       * param **bidir**: Specifies if generated traffic will be full-duplex
 209         (true) or half-duplex (false).
 210       * param **frame_rate**: Defines desired percentage of frame
 211         rate used during continuous stream tests.
 212       * param **burst_size**: Defines a number of frames in the single burst,
 213         which is sent by burst traffic type. Burst size is applied for each
 214         direction, i.e. the total number of tx frames will be 2*burst_size
 215         in case of bidirectional traffic.
 216       * param **multistream**: Defines number of flows simulated by traffic
 217         generator. Value 0 disables MultiStream feature.
 218       * param **stream_type**: Stream Type defines ISO OSI network layer
 219         used for simulation of multiple streams.
 220         Supported values:
 221
 222         * **L2** - iteration of destination MAC address
 223         * **L3** - iteration of destination IP address
 224         * **L4** - iteration of destination port of selected transport protocol
 225
 226       * param **l2**: A dictionary with data link layer details, e.g. **srcmac**,
 227         **dstmac** and **framesize**.
 228       * param **l3**: A dictionary with network layer details, e.g. **srcip**,
 229         **dstip**, **proto** and l3 on/off switch **enabled**.
 230       * param **l4**: A dictionary with transport layer details, e.g. **srcport**,
 231         **dstport** and l4 on/off switch **enabled**.
 232       * param **vlan**: A dictionary with vlan specific parameters,
 233         e.g. **priority**, **cfi**, **id** and vlan on/off switch **enabled**.
 234       * param **scapy**: A dictionary with definition of the frame content for both traffic
 235         directions. The frame content is defined by a SCAPY notation.
 236
 237     * param **tests**: Number of times the test is executed.
 238     * param **duration**: Duration of continuous test or per iteration duration
 239       in case of RFC2544 throughput or back2back traffic types.
 240     * param **lossrate**: Acceptable lossrate percentage.
 241
 242 Step 6 - passing back results
 243 =============================
 244
 245 It is expected that methods **send**, **wait** and **stop** will return
 246 values measured by traffic generator within a dictionary. Dictionary keys
 247 are defined in **ResultsConstants** implemented in
 248 **core/results/results_constants.py**. Please check sections for RFC2544
 249 Throughput & Continuous and for Back2Back. The same key names should
 250 be used by all traffic generator implementations.
 251