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.
5 ===================================
6 Traffic Generator Integration Guide
7 ===================================
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>`__.
17 Let us create a sample traffic generator called **sample_tg**, step by step.
19 Step 1 - create a directory
20 ===========================
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
29 .. code-block:: console
31 $ mkdir tools/pkt_gen/sample_tg
33 Step 2 - create a trafficgen module
34 ===================================
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.
43 Let us create a draft of tools/pkt_gen/sample_tg/sample_tg.py module.
45 .. code-block:: python
47 from tools.pkt_gen import trafficgen
49 class SampleTG(trafficgen.ITrafficGenerator):
51 A sample traffic generator implementation
55 VSPERF is immediately aware of the new class:
57 .. code-block:: console
59 $ ./vsperf --list-trafficgen
61 Output should look like:
63 .. code-block:: console
65 Classes derived from: ITrafficGenerator
68 * Ixia: A wrapper around the IXIA traffic generator.
70 * IxNet: A wrapper around IXIA IxNetwork applications.
72 * Dummy: A dummy traffic generator whose data is generated by the user.
74 * SampleTG: A sample traffic generator implementation
76 * TestCenter: Spirent TestCenter
79 Step 3 - configuration
80 ======================
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.
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**
96 Example of **merge_spec** usage in **tools/pkt_gen/sample_tg/sample_tg.py** module:
98 .. code-block:: python
100 from tools.pkt_gen.trafficgen.trafficgenhelper import merge_spec
102 def start_rfc2544_throughput(self, traffic=None, duration=30):
104 self._params['traffic'] = self.traffic_defaults.copy()
106 self._params['traffic'] = trafficgen.merge_spec(
107 self._params['traffic'], traffic)
110 Step 4 - generic functions
111 ==========================
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
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.
123 The **disconnect** function should perform clean up of any connection specific
124 actions called from the **connect** function.
126 Example in **tools/pkt_gen/sample_tg/sample_tg.py** module:
128 .. code-block:: python
133 def disconnect(self):
136 Step 5 - supported traffic types
137 ================================
139 Currently VSPERF supports three different types of tests for traffic generators,
140 these are identified in vsperf through the traffic type, which include:
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**.
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**.
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**.
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.
160 Example of synchronous interfaces:
162 .. code-block:: python
164 def send_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
166 def send_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
168 def send_cont_traffic(self, traffic=None, duration=20):
170 Example of asynchronous interfaces:
172 .. code-block:: python
174 def start_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
176 def wait_rfc2544_throughput(self):
178 def start_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
180 def wait_rfc2544_back2back(self):
182 def start_cont_traffic(self, traffic=None, duration=20):
183 def stop_cont_traffic(self):
185 Description of parameters used by **send**, **start**, **wait** and **stop**
188 * param **traffic**: A dictionary with detailed definition of traffic
189 pattern. It contains following parameters to be implemented by
192 Note: Traffic dictionary has also virtual switch related parameters,
193 which are not listed below.
195 Note: There are parameters specific to testing of tunnelling protocols,
196 which are discussed in detail at `integration tests userguide`_
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.
211 * **L2** - iteration of destination MAC address
212 * **L3** - iteration of destination IP address
213 * **L4** - iteration of destination port of selected transport protocol
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**,
221 * param **vlan**: A dictionary with vlan specific parameters,
222 e.g. **priority**, **cfi**, **id** and vlan on/off switch **enabled**.
224 * param **trials**: Number of trials to execute.
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.
229 Step 6 - passing back results
230 =============================
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.
239 .. _integration tests userguide: http://artifacts.opnfv.org/vswitchperf/docs/userguide/integration.html