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.
12 This document is intended to aid those who want to modify the vsperf code. Or
13 to extend it - for example to add support for new traffic generators,
14 deployment scenarios and so on.
19 Example Connectivity to DUT
20 ---------------------------
22 Establish connectivity to the VSPERF DUT Linux host, such as the DUT in Pod 3,
23 by following the steps in `Testbed POD3
24 <https://wiki.opnfv.org/get_started/pod_3_-_characterize_vswitch_performance>`__
26 The steps cover booking the DUT and establishing the VSPERF environment.
31 List all the cli options:
33 .. code-block:: console
37 Run all tests that have ``tput`` in their name - ``p2p_tput``, ``pvp_tput`` etc.:
39 .. code-block:: console
41 $ ./vsperf --tests 'tput'
43 As above but override default configuration with settings in '10_custom.conf'.
44 This is useful as modifying configuration directly in the configuration files
45 in ``conf/NN_*.py`` shows up as changes under git source control:
47 .. code-block:: console
49 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests 'tput'
51 Override specific test parameters. Useful for shortening the duration of tests
52 for development purposes:
54 .. code-block:: console
56 $ ./vsperf --test-params 'duration=10;rfc2544_tests=1;pkt_sizes=64' --tests 'pvp_tput'
61 This is a typical flow of control for a test.
69 The conf package contains the configuration files (``*.conf``) for all system
70 components, it also provides a ``settings`` object that exposes all of these
73 Settings are not passed from component to component. Rather they are available
74 globally to all components once they import the conf package.
76 .. code-block:: python
78 from conf import settings
80 log_file = settings.getValue('LOG_FILE_DEFAULT')
82 Settings files (``*.conf``) are valid python code so can be set to complex
83 types such as lists and dictionaries as well as scalar types:
85 .. code-block:: python
87 first_packet_size = settings.getValue('PACKET_SIZE_LIST')[0]
89 Configuration Procedure and Precedence
90 --------------------------------------
92 Configuration files follow a strict naming convention that allows them to be
93 processed in a specific order. All the .conf files are named ``NN_name.conf``,
94 where NN is a decimal number. The files are processed in order from 00_name.conf
95 to 99_name.conf so that if the name setting is given in both a lower and higher
96 numbered conf file then the higher numbered file is the effective setting as it
97 is processed after the setting in the lower numbered file.
99 The values in the file specified by ``--conf-file`` takes precedence over all
100 the other configuration files and does not have to follow the naming
107 ``conf.settings`` also loads configuration from the command line and from the environment.
109 VM, vSwitch, Traffic Generator Independence
110 ===========================================
112 VSPERF supports different vSwithes, Traffic Generators, VNFs
113 and Forwarding Applications by using standard object-oriented polymorphism:
115 * Support for vSwitches is implemented by a class inheriting from IVSwitch.
116 * Support for Traffic Generators is implemented by a class inheriting from
118 * Support for VNF is implemented by a class inheriting from IVNF.
119 * Support for Forwarding Applications is implemented by a class inheriting
122 By dealing only with the abstract interfaces the core framework can support
123 many implementations of different vSwitches, Traffic Generators, VNFs
124 and Forwarding Applications.
129 .. code-block:: python
134 add_switch(switch_name)
135 del_switch(switch_name)
136 add_phy_port(switch_name)
137 add_vport(switch_name)
138 get_ports(switch_name)
139 del_port(switch_name, port_name)
140 add_flow(switch_name, flow)
141 del_flow(switch_name, flow=None)
146 .. code-block:: python
148 class ITrafficGenerator:
152 send_burst_traffic(traffic, numpkts, time, framerate)
154 send_cont_traffic(traffic, time, framerate)
155 start_cont_traffic(traffic, time, framerate)
156 stop_cont_traffic(self):
158 send_rfc2544_throughput(traffic, tests, duration, lossrate)
159 start_rfc2544_throughput(traffic, tests, duration, lossrate)
160 wait_rfc2544_throughput(self)
162 send_rfc2544_back2back(traffic, tests, duration, lossrate)
163 start_rfc2544_back2back(traffic, , tests, duration, lossrate)
164 wait_rfc2544_back2back()
166 Note ``send_xxx()`` blocks whereas ``start_xxx()`` does not and must be followed by a subsequent call to ``wait_xxx()``.
171 .. code-block:: python
175 monitor_path, shared_path_host,
176 shared_path_guest, guest_prompt)
180 execute_and_wait (command)
185 .. code-block:: python
195 Controllers are used in conjunction with abstract interfaces as way
196 of decoupling the control of vSwtiches, VNFs, TrafficGenerators
197 and Forwarding Applications from other components.
199 The controlled classes provide basic primitive operations. The Controllers
200 sequence and co-ordinate these primitive operation in to useful actions. For
201 instance the vswitch_controller_PVP can be used to bring any vSwitch (that
202 implements the primitives defined in IVSwitch) into the configuration required
203 by the Phy-to-Phy Deployment Scenario.
205 In order to support a new vSwitch only a new implementation of IVSwitch needs
206 be created for the new vSwitch to be capable of fulfilling all the Deployment
207 Scenarios provided for by existing or future vSwitch Controllers.
209 Similarly if a new Deployment Scenario is required it only needs to be written
210 once as a new vSwitch Controller and it will immediately be capable of
211 controlling all existing and future vSwitches in to that Deployment Scenario.
213 Similarly the Traffic Controllers can be used to co-ordinate basic operations
214 provided by implementers of ITrafficGenerator to provide useful tests. Though
215 traffic generators generally already implement full test cases i.e. they both
216 generate suitable traffic and analyse returned traffic in order to implement a
217 test which has typically been predefined in an RFC document. However the
218 Traffic Controller class allows for the possibility of further enhancement -
219 such as iterating over tests for various packet sizes or creating new tests.
221 Traffic Controller's Role
222 -------------------------
224 .. image:: traffic_controller.png
227 Loader & Component Factory
228 --------------------------
230 The working of the Loader package (which is responsible for *finding* arbitrary
231 classes based on configuration data) and the Component Factory which is
232 responsible for *choosing* the correct class for a particular situation - e.g.
233 Deployment Scenario can be seen in this diagram.
235 .. image:: factory_and_loader.png
240 Vsperf uses a standard set of routing tables in order to allow tests to easily
241 mix and match Deployment Scenarios (PVP, P2P topology), Tuple Matching and
242 Frame Modification requirements.
244 .. code-block:: console
248 | Table 0 | table#0 - Match table. Flows designed to force 5 & 10
249 | | tuple matches go here.
255 +--------------+ table#1 - Routing table. Flow entries to forward
256 | | packets between ports goes here.
257 | Table 1 | The chosen port is communicated to subsequent tables by
258 | | setting the metadata value to the egress port number.
259 | | Generally this table is set-up by by the
260 +--------------+ vSwitchController.
264 +--------------+ table#2 - Frame modification table. Frame modification
265 | | flow rules are isolated in this table so that they can
266 | Table 2 | be turned on or off without affecting the routing or
267 | | tuple-matching flow rules. This allows the frame
268 | | modification and tuple matching required by the tests
269 | | in the VSWITCH PERFORMANCE FOR TELCO NFV test
270 +--------------+ specification to be independent of the Deployment
271 | Scenario set up by the vSwitchController.
276 | Table 3 | table#3 - Egress table. Egress packets on the ports
277 | | setup in Table 1.