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,
165 lossrate=0.0, multistream=False):
166 def send_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
168 def send_cont_traffic(self, traffic=None, duration=20, multistream=False):
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, multistream=False):
183 def stop_cont_traffic(self):
185 Description of parameters used by **send**, **start**, **wait** and **stop**
188 * param **trials**: Number of trials to execute
189 * param **duration**: Duration of continuous test or per iteration duration
190 in case of RFC2544 throughput or back2back traffic types.
191 * param **lossrate**: Acceptable lossrate percentage.
192 * param **multistream**: Enable or disable multistream feature.
194 Step 6 - passing back results
195 =============================
197 It is expected that methods **send**, **wait** and **stop** will return
198 values measured by traffic generator within a dictionary. Dictionary keys
199 are defined in **ResultsConstants** implemented in
200 **core/results/results_constants.py**. Please check sections for RFC2544
201 Throughput & Continuous and for Back2Back. The same key names should
202 be used by all traffic generator implementations.