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, Tieto and others.
14 This document is intended to aid those who want to modify the vsperf code. Or
15 to extend it - for example to add support for new traffic generators,
16 deployment scenarios and so on.
21 Example Connectivity to DUT
22 ---------------------------
24 Establish connectivity to the VSPERF DUT Linux host. If this is in an OPNFV lab
25 following the steps provided by `Pharos <https://www.opnfv.org/community/projects/pharos>`_
26 to `access the POD <https://wiki.opnfv.org/display/INF/INFRA+Lab+Support>`_
28 The followign steps establish the VSPERF environment.
33 List all the cli options:
35 .. code-block:: console
39 Run all tests that have ``tput`` in their name - ``phy2phy_tput``, ``pvp_tput`` etc.:
41 .. code-block:: console
43 $ ./vsperf --tests 'tput'
45 As above but override default configuration with settings in '10_custom.conf'.
46 This is useful as modifying configuration directly in the configuration files
47 in ``conf/NN_*.py`` shows up as changes under git source control:
49 .. code-block:: console
51 $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests 'tput'
53 Override specific test parameters. Useful for shortening the duration of tests
54 for development purposes:
56 .. code-block:: console
58 $ ./vsperf --test-params 'TRAFFICGEN_DURATION=10;TRAFFICGEN_RFC2544_TESTS=1;' \
59 'TRAFFICGEN_PKT_SIZES=(64,)' pvp_tput
64 This is a typical flow of control for a test.
68 .. _design-configuration:
73 The conf package contains the configuration files (``*.conf``) for all system
74 components, it also provides a ``settings`` object that exposes all of these
77 Settings are not passed from component to component. Rather they are available
78 globally to all components once they import the conf package.
80 .. code-block:: python
82 from conf import settings
84 log_file = settings.getValue('LOG_FILE_DEFAULT')
86 Settings files (``*.conf``) are valid python code so can be set to complex
87 types such as lists and dictionaries as well as scalar types:
89 .. code-block:: python
91 first_packet_size = settings.getValue('PACKET_SIZE_LIST')[0]
93 Configuration Procedure and Precedence
94 --------------------------------------
96 Configuration files follow a strict naming convention that allows them to be
97 processed in a specific order. All the .conf files are named ``NNx_name.conf``,
98 where ``NN`` is a decimal number and ``x`` is an optional alphabetical suffix.
99 The files are processed in order from ``00_name.conf`` to ``99_name.conf``
100 (and from ``00a_name`` to ``00z_name``), so that if the name setting is given
101 in both a lower and higher numbered conf file then the higher numbered file
102 is the effective setting as it is processed after the setting in the lower
105 The values in the file specified by ``--conf-file`` takes precedence over all
106 the other configuration files and does not have to follow the naming
109 .. _paths-documentation:
111 Configuration of PATHS dictionary
112 ---------------------------------
114 VSPERF uses external tools like Open vSwitch and Qemu for execution of testcases. These
115 tools may be downloaded and built automatically (see :ref:`vsperf-installation-script`)
116 or installed manually by user from binary packages. It is also possible to use a combination
117 of both approaches, but it is essential to correctly set paths to all required tools.
118 These paths are stored within a PATHS dictionary, which is evaluated before execution
119 of each testcase, in order to setup testcase specific environment. Values selected for testcase
120 execution are internally stored inside TOOLS dictionary, which is used by VSPERF to execute
121 external tools, load kernel modules, etc.
123 The default configuration of PATHS dictionary is spread among three different configuration files
124 to follow logical grouping of configuration options. Basic description of PATHS dictionary
125 is placed inside ``conf/00_common.conf``. The configuration specific to DPDK and vswitches
126 is located at ``conf/02_vswitch.conf``. The last part related to the Qemu is defined inside
127 ``conf/04_vnf.conf``. Default configuration values can be used in case, that all required
128 tools were downloaded and built automatically by vsperf itself. In case, that some of
129 tools were installed manually from binary packages, then it will be necessary to modify
130 the content of PATHS dictionary accordingly.
132 Dictionary has a specific section of configuration options for every tool type, it means:
134 * ``PATHS['vswitch']`` - contains a separate dictionary for each of vswitches supported by VSPEF
138 .. code-block:: python
141 'OvsDpdkVhost': { ... },
142 'OvsVanilla' : { ... },
146 * ``PATHS['dpdk']`` - contains paths to the dpdk sources, kernel modules and tools (e.g. testpmd)
150 .. code-block:: python
155 'path': os.path.join(ROOT_DIR, 'src/dpdk/dpdk/'),
156 'modules' : ['uio', os.path.join(RTE_TARGET, 'kmod/igb_uio.ko')],
157 'bind-tool': 'tools/dpdk*bind.py',
158 'testpmd': os.path.join(RTE_TARGET, 'app', 'testpmd'),
163 * ``PATHS['qemu']`` - contains paths to the qemu sources and executable file
167 .. code-block:: python
172 'qemu-system': 'qemu-system-x86_64'
177 Every section specific to the particular vswitch, dpdk or qemu may contain following types
178 of configuration options:
180 * option ``type`` - is a string, which defines the type of configured paths ('src' or 'bin')
181 to be selected for a given section:
183 * value ``src`` means, that VSPERF will use vswitch, DPDK or QEMU built from sources
184 e.g. by execution of ``systems/build_base_machine.sh`` script during VSPERF
187 * value ``bin`` means, that VSPERF will use vswitch, DPDK or QEMU binaries installed
188 directly in the operating system, e.g. via OS specific packaging system
190 * option ``path`` - is a string with a valid system path; Its content is checked for
191 existence, prefixed with section name and stored into TOOLS for later use
192 e.g. ``TOOLS['dpdk_src']`` or ``TOOLS['vswitch_src']``
194 * option ``modules`` - is list of strings with names of kernel modules; Every module name
195 from given list is checked for a '.ko' suffix. In case that it matches and if it is not
196 an absolute path to the module, then module name is prefixed with value of ``path``
197 option defined for the same section
201 .. code-block:: python
204 snippet of PATHS definition from the configuration file:
210 'path': '/tmp/vsperf/src_vanilla/ovs/ovs/',
211 'modules' : ['datapath/linux/openvswitch.ko'],
220 Final content of TOOLS dictionary used during runtime:
222 TOOLS['vswitch_modules'] = ['/tmp/vsperf/src_vanilla/ovs/ovs/datapath/linux/openvswitch.ko']
224 * all other options are strings with names and paths to specific tools; If a given string
225 contains a relative path and option ``path`` is defined for a given section, then string
226 content will be prefixed with content of the ``path``. Otherwise the name of the tool will be
227 searched within standard system directories. In case that filename contains OS specific
228 wildcards, then they will be expanded to the real path. At the end of the processing, every
229 absolute path will be checked for its existence. In case that temporary path (i.e. path with
230 a ``_tmp`` suffix) does not exist, then log will be written and vsperf will continue. If any
231 other path will not exist, then vsperf execution will be terminated with a runtime error.
235 .. code-block:: python
238 snippet of PATHS definition from the configuration file:
244 'path': '/tmp/vsperf/src_vanilla/ovs/ovs/',
245 'ovs-vswitchd': 'vswitchd/ovs-vswitchd',
246 'ovsdb-server': 'ovsdb/ovsdb-server',
255 Final content of TOOLS dictionary used during runtime:
257 TOOLS['ovs-vswitchd'] = '/tmp/vsperf/src_vanilla/ovs/ovs/vswitchd/ovs-vswitchd'
258 TOOLS['ovsdb-server'] = '/tmp/vsperf/src_vanilla/ovs/ovs/ovsdb/ovsdb-server'
260 Note: In case that ``bin`` type is set for DPDK, then ``TOOLS['dpdk_src']`` will be set to
261 the value of ``PATHS['dpdk']['src']['path']``. The reason is, that VSPERF uses downloaded
262 DPDK sources to copy DPDK and testpmd into the GUEST, where testpmd is built. In case,
263 that DPDK sources are not available, then vsperf will continue with test execution,
264 but testpmd can't be used as a guest loopback. This is useful in case, that other guest
265 loopback applications (e.g. buildin or l2fwd) are used.
267 Note: In case of RHEL 7.3 OS usage, binary package configuration is required
268 for Vanilla OVS tests. With the installation of a supported rpm for OVS there is
269 a section in the ``conf\10_custom.conf`` file that can be used.
271 .. _configuration-of-traffic-dictionary:
273 Configuration of TRAFFIC dictionary
274 -----------------------------------
276 TRAFFIC dictionary is used for configuration of traffic generator. Default values
277 can be found in configuration file ``conf/03_traffic.conf``. These default values
278 can be modified by (first option has the highest priorty):
280 1. ``Parameters`` section of testcase definition
281 2. command line options specified by ``--test-params`` argument
282 3. custom configuration file
284 It is to note, that in case of option 1 and 2, it is possible to specify only
285 values, which should be changed. In case of custom configuration file, it is
286 required to specify whole ``TRAFFIC`` dictionary with its all values or explicitly
287 call and update() method of ``TRAFFIC`` dictionary.
289 Detailed description of ``TRAFFIC`` dictionary items follows:
291 .. code-block:: console
293 'traffic_type' - One of the supported traffic types.
294 E.g. rfc2544_throughput, rfc2544_back2back,
295 rfc2544_continuous or burst
297 Default value: "rfc2544_throughput".
298 'bidir' - Specifies if generated traffic will be full-duplex (True)
299 or half-duplex (False)
301 Supported values: "True", "False"
302 Default value: "False".
303 'frame_rate' - Defines desired percentage of frame rate used during
304 continuous stream tests.
307 'burst_size' - Defines a number of frames in the single burst, which is sent
308 by burst traffic type. Burst size is applied for each direction,
309 i.e. the total number of tx frames will be 2*burst_size in case of
310 bidirectional traffic.
313 'multistream' - Defines number of flows simulated by traffic generator.
314 Value 0 disables multistream feature
316 Supported values: 0-65536 for 'L4' stream type
317 unlimited for 'L2' and 'L3' stream types
319 'stream_type' - Stream type is an extension of the "multistream" feature.
320 If multistream is disabled, then stream type will be
321 ignored. Stream type defines ISO OSI network layer used
322 for simulation of multiple streams.
325 "L2" - iteration of destination MAC address
326 "L3" - iteration of destination IP address
327 "L4" - iteration of destination port
328 of selected transport protocol
330 'pre_installed_flows'
331 - Pre-installed flows is an extension of the "multistream"
332 feature. If enabled, it will implicitly insert a flow
333 for each stream. If multistream is disabled, then
334 pre-installed flows will be ignored.
337 "Yes" - flows will be inserted into OVS
338 "No" - flows won't be inserted into OVS
340 'flow_type' - Defines flows complexity.
343 "port" - flow is defined by ingress ports
344 "IP" - flow is defined by ingress ports
345 and src and dst IP addresses
346 Default value: "port"
347 'flow_control' - Controls flow control support by traffic generator.
349 False - flow control is disabled
350 True - flow control is enabled
352 Note: Currently it is supported by IxNet only
353 'learning_frames' - Controls learning frames support by traffic generator.
355 False - learning frames are disabled
356 True - learning frames are enabled
358 Note: Currently it is supported by IxNet only
359 'l2' - A dictionary with l2 network layer details. Supported
361 'srcmac' - Specifies source MAC address filled by traffic generator.
362 NOTE: It can be modified by vsperf in some scenarios.
364 Default value: "00:00:00:00:00:00".
365 'dstmac' - Specifies destination MAC address filled by traffic generator.
366 NOTE: It can be modified by vsperf in some scenarios.
368 Default value: "00:00:00:00:00:00".
369 'framesize' - Specifies default frame size. This value should not be
370 changed directly. It will be overridden during testcase
371 execution by values specified by list TRAFFICGEN_PKT_SIZES.
374 'l3' - A dictionary with l3 network layer details. Supported
376 'enabled' - Specifies if l3 layer should be enabled or disabled.
379 NOTE: Supported only by IxNet trafficgen class
380 'srcip' - Specifies source MAC address filled by traffic generator.
381 NOTE: It can be modified by vsperf in some scenarios.
383 Default value: "1.1.1.1".
384 'dstip' - Specifies destination MAC address filled by traffic generator.
385 NOTE: It can be modified by vsperf in some scenarios.
387 Default value: "90.90.90.90".
388 'proto' - Specifies deflaut protocol type.
389 Please check particular traffic generator implementation
390 for supported protocol types.
392 Default value: "udp".
393 'l4' - A dictionary with l4 network layer details. Supported
395 'enabled' - Specifies if l4 layer should be enabled or disabled.
398 NOTE: Supported only by IxNet trafficgen class
399 'srcport' - Specifies source port of selected transport protocol.
400 NOTE: It can be modified by vsperf in some scenarios.
403 'dstport' - Specifies destination port of selected transport protocol.
404 NOTE: It can be modified by vsperf in some scenarios.
407 'vlan' - A dictionary with vlan encapsulation details. Supported
409 'enabled' - Specifies if vlan encapsulation should be enabled or
413 'id' - Specifies vlan id.
414 Data type: int (NOTE: must fit to 12 bits)
416 'priority' - Specifies a vlan priority (PCP header field).
417 Data type: int (NOTE: must fit to 3 bits)
419 'cfi' - Specifies if frames can or cannot be dropped during
420 congestion (DEI header field).
421 Data type: int (NOTE: must fit to 1 bit)
423 'capture' - A dictionary with traffic capture configuration.
424 NOTE: It is supported only by T-Rex traffic generator.
425 'enabled' - Specifies if traffic should be captured
428 'tx_ports' - A list of ports, where frames transmitted towards DUT will
429 be captured. Ports have numbers 0 and 1. TX packet capture
430 is disabled if list of ports is empty.
433 'rx_ports' - A list of ports, where frames received from DUT will
434 be captured. Ports have numbers 0 and 1. RX packet capture
435 is disabled if list of ports is empty.
438 'count' - A number of frames to be captured. The same count value
439 is applied to both TX and RX captures.
442 'filter' - An expression used to filter TX and RX packets. It uses the same
443 syntax as pcap library. See pcap-filter man page for additional
447 'scapy' - A dictionary with definition of a frame content for both traffic
448 directions. The frame content is defined by a SCAPY notation.
449 NOTE: It is supported only by the T-Rex traffic generator.
450 Following keywords can be used to refer to the related parts of
451 the TRAFFIC dictionary:
452 Ether_src - refers to TRAFFIC['l2']['srcmac']
453 Ether_dst - refers to TRAFFIC['l2']['dstmac']
454 IP_proto - refers to TRAFFIC['l3']['proto']
455 IP_PROTO - refers to upper case version of TRAFFIC['l3']['proto']
456 IP_src - refers to TRAFFIC['l3']['srcip']
457 IP_dst - refers to TRAFFIC['l3']['dstip']
458 IP_PROTO_sport - refers to TRAFFIC['l4']['srcport']
459 IP_PROTO_dport - refers to TRAFFIC['l4']['dstport']
460 Dot1Q_prio - refers to TRAFFIC['vlan']['priority']
461 Dot1Q_id - refers to TRAFFIC['vlan']['cfi']
462 Dot1Q_vlan - refers to TRAFFIC['vlan']['id']
463 '0' - A string with the frame definition for the 1st direction.
465 Default value: 'Ether(src={Ether_src}, dst={Ether_dst})/'
466 'Dot1Q(prio={Dot1Q_prio}, id={Dot1Q_id}, vlan={Dot1Q_vlan})/'
467 'IP(proto={IP_proto}, src={IP_src}, dst={IP_dst})/'
468 '{IP_PROTO}(sport={IP_PROTO_sport}, dport={IP_PROTO_dport})'
469 '1' - A string with the frame definition for the 2nd direction.
471 Default value: 'Ether(src={Ether_dst}, dst={Ether_src})/'
472 'Dot1Q(prio={Dot1Q_prio}, id={Dot1Q_id}, vlan={Dot1Q_vlan})/'
473 'IP(proto={IP_proto}, src={IP_dst}, dst={IP_src})/'
474 '{IP_PROTO}(sport={IP_PROTO_dport}, dport={IP_PROTO_sport})',
476 - A dictionary with definition of a latency histogram provision in results.
477 'enabled' - Specifies if the histogram provisioning is enabled or not.
478 'type' - Defines how histogram is provided. Currenty only 'Default' is defined.
479 'Default' - Default histogram as provided by the Traffic-generator.
480 'imix' - A dictionary for IMIX Specification.
481 'enabled' - Specifies if IMIX is enabled or NOT.
482 'type' - The specification type - denotes how IMIX is specified.
483 Currently only 'genome' type is defined.
484 Other types (ex: table-of-proportions) can be added in future.
485 'genome' - The Genome Encoding of Pkt-Sizes and Ratio for IMIX.
486 The Ratio is inferred from the number of particular geneome characters
487 Genome encoding is described in RFC 6985. This specification is closest
488 to the method described in section 6.2 of RFC 6985.
489 Ex: 'aaaaaaaddddg' denotes ratio of 7:4:1 of packets sizes 64:512:1518.
490 Note: Exact-sequence is not maintained, only the ratio of packets
493 Default Value: 'aaaaaaaddddg'
495 .. _configuration-of-guest-options:
497 Configuration of GUEST options
498 ------------------------------
500 VSPERF is able to setup scenarios involving a number of VMs in series or in parallel.
501 All configuration options related to a particular VM instance are defined as
502 lists and prefixed with ``GUEST_`` label. It is essential, that there is enough
503 items in all ``GUEST_`` options to cover all VM instances involved in the test.
504 In case there is not enough items, then VSPERF will use the first item of
505 particular ``GUEST_`` option to expand the list to required length.
507 Example of option expansion for 4 VMs:
509 .. code-block:: python
515 GUEST_MEMORY = ['2048', '4096']
518 Values after automatic expansion:
520 GUEST_SMP = ['2', '2', '2', '2']
521 GUEST_MEMORY = ['2048', '4096', '2048', '2048']
524 First option can contain macros starting with ``#`` to generate VM specific values.
525 These macros can be used only for options of ``list`` or ``str`` types with ``GUEST_``
528 Example of macros and their expansion for 2 VMs:
530 .. code-block:: python
535 GUEST_SHARE_DIR = ['/tmp/qemu#VMINDEX_share']
536 GUEST_BRIDGE_IP = ['#IP(1.1.1.5)/16']
539 Values after automatic expansion:
541 GUEST_SHARE_DIR = ['/tmp/qemu0_share', '/tmp/qemu1_share']
542 GUEST_BRIDGE_IP = ['1.1.1.5/16', '1.1.1.6/16']
544 Additional examples are available at ``04_vnf.conf``.
546 Note: In case, that macro is detected in the first item of the list, then
547 all other items are ignored and list content is created automatically.
549 Multiple macros can be used inside one configuration option definition, but macros
550 cannot be used inside other macros. The only exception is macro ``#VMINDEX``, which
551 is expanded first and thus it can be used inside other macros.
553 Following macros are supported:
555 * ``#VMINDEX`` - it is replaced by index of VM being executed; This macro
556 is expanded first, so it can be used inside other macros.
560 .. code-block:: python
562 GUEST_SHARE_DIR = ['/tmp/qemu#VMINDEX_share']
564 * ``#MAC(mac_address[, step])`` - it will iterate given ``mac_address``
565 with optional ``step``. In case that step is not defined, then it is set to 1.
566 It means, that first VM will use the value of ``mac_address``, second VM
567 value of ``mac_address`` increased by ``step``, etc.
571 .. code-block:: python
573 GUEST_NICS = [[{'mac' : '#MAC(00:00:00:00:00:01,2)'}]]
575 * ``#IP(ip_address[, step])`` - it will iterate given ``ip_address``
576 with optional ``step``. In case that step is not defined, then it is set to 1.
577 It means, that first VM will use the value of ``ip_address``, second VM
578 value of ``ip_address`` increased by ``step``, etc.
582 .. code-block:: python
584 GUEST_BRIDGE_IP = ['#IP(1.1.1.5)/16']
586 * ``#EVAL(expression)`` - it will evaluate given ``expression`` as python code;
587 Only simple expressions should be used. Call of the functions is not supported.
591 .. code-block:: python
593 GUEST_CORE_BINDING = [('#EVAL(6+2*#VMINDEX)', '#EVAL(7+2*#VMINDEX)')]
598 ``conf.settings`` also loads configuration from the command line and from the environment.
605 Every testcase uses one of the supported deployment scenarios to setup test environment.
606 The controller responsible for a given scenario configures flows in the vswitch to route
607 traffic among physical interfaces connected to the traffic generator and virtual
608 machines. VSPERF supports several deployments including PXP deployment, which can
609 setup various scenarios with multiple VMs.
611 These scenarios are realized by VswitchControllerPXP class, which can configure and
612 execute given number of VMs in serial or parallel configurations. Every VM can be
613 configured with just one or an even number of interfaces. In case that VM has more than
614 2 interfaces, then traffic is properly routed among pairs of interfaces.
616 Example of traffic routing for VM with 4 NICs in serial configuration:
618 .. code-block:: console
620 +------------------------------------------+
622 | +---------------+ +---------------+ |
623 | | Application | | Application | |
624 | +---------------+ +---------------+ |
627 | +---------------+ +---------------+ |
628 | | logical ports | | logical ports | |
630 +--+---------------+----+---------------+--+
634 +-----------+---------------+----+---------------+----------+
635 | vSwitch | 0 1 | | 2 3 | |
636 | | logical ports | | logical ports | |
637 | previous +---------------+ +---------------+ next |
638 | VM or PHY ^ | ^ | VM or PHY|
639 | port -----+ +------------+ +---> port |
640 +-----------------------------------------------------------+
642 It is also possible to define different number of interfaces for each VM to better
643 simulate real scenarios.
645 Example of traffic routing for 2 VMs in serial configuration, where 1st VM has
646 4 NICs and 2nd VM 2 NICs:
648 .. code-block:: console
650 +------------------------------------------+ +---------------------+
651 | 1st VM with 4 NICs | | 2nd VM with 2 NICs |
652 | +---------------+ +---------------+ | | +---------------+ |
653 | | Application | | Application | | | | Application | |
654 | +---------------+ +---------------+ | | +---------------+ |
657 | +---------------+ +---------------+ | | +---------------+ |
658 | | logical ports | | logical ports | | | | logical ports | |
659 | | 0 1 | | 2 3 | | | | 0 1 | |
660 +--+---------------+----+---------------+--+ +--+---------------+--+
664 +-----------+---------------+----+---------------+-------+---------------+----------+
665 | vSwitch | 0 1 | | 2 3 | | 4 5 | |
666 | | logical ports | | logical ports | | logical ports | |
667 | previous +---------------+ +---------------+ +---------------+ next |
668 | VM or PHY ^ | ^ | ^ | VM or PHY|
669 | port -----+ +------------+ +---------------+ +----> port |
670 +-----------------------------------------------------------------------------------+
672 The number of VMs involved in the test and the type of their connection is defined
673 by deployment name as follows:
675 * ``pvvp[number]`` - configures scenario with VMs connected in series with
676 optional ``number`` of VMs. In case that ``number`` is not specified, then
679 Example of 2 VMs in a serial configuration:
681 .. code-block:: console
683 +----------------------+ +----------------------+
684 | 1st VM | | 2nd VM |
685 | +---------------+ | | +---------------+ |
686 | | Application | | | | Application | |
687 | +---------------+ | | +---------------+ |
690 | +---------------+ | | +---------------+ |
691 | | logical ports | | | | logical ports | |
692 | | 0 1 | | | | 0 1 | |
693 +---+---------------+--+ +---+---------------+--+
697 +---+---------------+---------+---------------+--+
699 | | logical ports | vSwitch | logical ports | |
700 | +---------------+ +---------------+ |
702 | | +-----------------+ v |
703 | +----------------------------------------+ |
704 | | physical ports | |
706 +---+----------------------------------------+---+
710 +------------------------------------------------+
712 | traffic generator |
714 +------------------------------------------------+
716 * ``pvpv[number]`` - configures scenario with VMs connected in parallel with
717 optional ``number`` of VMs. In case that ``number`` is not specified, then
718 2 VMs will be used. Multistream feature is used to route traffic to particular
719 VMs (or NIC pairs of every VM). It means, that VSPERF will enable multistream
720 feature and sets the number of streams to the number of VMs and their NIC
721 pairs. Traffic will be dispatched based on Stream Type, i.e. by UDP port,
722 IP address or MAC address.
724 Example of 2 VMs in a parallel configuration, where traffic is dispatched
725 based on the UDP port.
727 .. code-block:: console
729 +----------------------+ +----------------------+
730 | 1st VM | | 2nd VM |
731 | +---------------+ | | +---------------+ |
732 | | Application | | | | Application | |
733 | +---------------+ | | +---------------+ |
736 | +---------------+ | | +---------------+ |
737 | | logical ports | | | | logical ports | |
738 | | 0 1 | | | | 0 1 | |
739 +---+---------------+--+ +---+---------------+--+
743 +---+---------------+---------+---------------+--+
745 | | logical ports | vSwitch | logical ports | |
746 | +---------------+ +---------------+ |
748 | | ......................: : |
750 | port| port: +--------------------+ : |
753 | +----------------------------------------+ |
754 | | physical ports | |
756 +---+----------------------------------------+---+
760 +------------------------------------------------+
762 | traffic generator |
764 +------------------------------------------------+
767 PXP deployment is backward compatible with PVP deployment, where ``pvp`` is
768 an alias for ``pvvp1`` and it executes just one VM.
770 The number of interfaces used by VMs is defined by configuration option
771 ``GUEST_NICS_NR``. In case that more than one pair of interfaces is defined
774 * for ``pvvp`` (serial) scenario every NIC pair is connected in serial
775 before connection to next VM is created
776 * for ``pvpv`` (parallel) scenario every NIC pair is directly connected
777 to the physical ports and unique traffic stream is assigned to it
781 * Deployment ``pvvp10`` will start 10 VMs and connects them in series
782 * Deployment ``pvpv4`` will start 4 VMs and connects them in parallel
783 * Deployment ``pvpv1`` and GUEST_NICS_NR = [4] will start 1 VM with
784 4 interfaces and every NIC pair is directly connected to the
786 * Deployment ``pvvp`` and GUEST_NICS_NR = [2, 4] will start 2 VMs;
787 1st VM will have 2 interfaces and 2nd VM 4 interfaces. These interfaces
788 will be connected in serial, i.e. traffic will flow as follows:
789 PHY1 -> VM1_1 -> VM1_2 -> VM2_1 -> VM2_2 -> VM2_3 -> VM2_4 -> PHY2
791 Note: In case that only 1 or more than 2 NICs are configured for VM,
792 then ``testpmd`` should be used as forwarding application inside the VM.
793 As it is able to forward traffic between multiple VM NIC pairs.
795 Note: In case of ``linux_bridge``, all NICs are connected to the same
796 bridge inside the VM.
798 Note: In case that multistream feature is configured and ``pre_installed_flows``
799 is set to ``Yes``, then stream specific flows will be inserted only for connections
800 originating at physical ports. The rest of the flows will be based on port
801 numbers only. The same logic applies in case that ``flow_type`` TRAFFIC option
802 is set to ``ip``. This configuration will avoid a testcase malfunction if frame headers
803 are modified inside VM (e.g. MAC swap or IP change).
805 VM, vSwitch, Traffic Generator Independence
806 ===========================================
808 VSPERF supports different VSwitches, Traffic Generators, VNFs
809 and Forwarding Applications by using standard object-oriented polymorphism:
811 * Support for vSwitches is implemented by a class inheriting from IVSwitch.
812 * Support for Traffic Generators is implemented by a class inheriting from
814 * Support for VNF is implemented by a class inheriting from IVNF.
815 * Support for Forwarding Applications is implemented by a class inheriting
818 By dealing only with the abstract interfaces the core framework can support
819 many implementations of different vSwitches, Traffic Generators, VNFs
820 and Forwarding Applications.
825 .. code-block:: python
830 add_switch(switch_name)
831 del_switch(switch_name)
832 add_phy_port(switch_name)
833 add_vport(switch_name)
834 get_ports(switch_name)
835 del_port(switch_name, port_name)
836 add_flow(switch_name, flow)
837 del_flow(switch_name, flow=None)
842 .. code-block:: python
844 class ITrafficGenerator:
848 send_burst_traffic(traffic, time)
850 send_cont_traffic(traffic, time, framerate)
851 start_cont_traffic(traffic, time, framerate)
852 stop_cont_traffic(self):
854 send_rfc2544_throughput(traffic, tests, duration, lossrate)
855 start_rfc2544_throughput(traffic, tests, duration, lossrate)
856 wait_rfc2544_throughput(self)
858 send_rfc2544_back2back(traffic, tests, duration, lossrate)
859 start_rfc2544_back2back(traffic, , tests, duration, lossrate)
860 wait_rfc2544_back2back()
862 Note ``send_xxx()`` blocks whereas ``start_xxx()`` does not and must be followed by a subsequent call to ``wait_xxx()``.
867 .. code-block:: python
871 monitor_path, shared_path_host,
872 shared_path_guest, guest_prompt)
876 execute_and_wait (command)
881 .. code-block:: python
891 Controllers are used in conjunction with abstract interfaces as way
892 of decoupling the control of vSwtiches, VNFs, TrafficGenerators
893 and Forwarding Applications from other components.
895 The controlled classes provide basic primitive operations. The Controllers
896 sequence and co-ordinate these primitive operation in to useful actions. For
897 instance the vswitch_controller_p2p can be used to bring any vSwitch (that
898 implements the primitives defined in IVSwitch) into the configuration required
899 by the Phy-to-Phy Deployment Scenario.
901 In order to support a new vSwitch only a new implementation of IVSwitch needs
902 be created for the new vSwitch to be capable of fulfilling all the Deployment
903 Scenarios provided for by existing or future vSwitch Controllers.
905 Similarly if a new Deployment Scenario is required it only needs to be written
906 once as a new vSwitch Controller and it will immediately be capable of
907 controlling all existing and future vSwitches in to that Deployment Scenario.
909 Similarly the Traffic Controllers can be used to co-ordinate basic operations
910 provided by implementers of ITrafficGenerator to provide useful tests. Though
911 traffic generators generally already implement full test cases i.e. they both
912 generate suitable traffic and analyse returned traffic in order to implement a
913 test which has typically been predefined in an RFC document. However the
914 Traffic Controller class allows for the possibility of further enhancement -
915 such as iterating over tests for various packet sizes or creating new tests.
917 Traffic Controller's Role
918 -------------------------
920 .. image:: traffic_controller.png
923 Loader & Component Factory
924 --------------------------
926 The working of the Loader package (which is responsible for *finding* arbitrary
927 classes based on configuration data) and the Component Factory which is
928 responsible for *choosing* the correct class for a particular situation - e.g.
929 Deployment Scenario can be seen in this diagram.
931 .. image:: factory_and_loader.png
936 Vsperf uses a standard set of routing tables in order to allow tests to easily
937 mix and match Deployment Scenarios (PVP, P2P topology), Tuple Matching and
938 Frame Modification requirements.
940 The usage of routing tables is driven by configuration parameter ``OVS_ROUTING_TABLES``.
941 Routing tables are disabled by default (i.e. parameter is set to ``False``) for better
942 comparison of results among supported vSwitches (e.g. OVS vs. VPP).
944 .. code-block:: console
948 | Table 0 | table#0 - Match table. Flows designed to force 5 & 10
949 | | tuple matches go here.
955 +--------------+ table#1 - Routing table. Flow entries to forward
956 | | packets between ports goes here.
957 | Table 1 | The chosen port is communicated to subsequent tables by
958 | | setting the metadata value to the egress port number.
959 | | Generally this table is set-up by by the
960 +--------------+ vSwitchController.
964 +--------------+ table#2 - Frame modification table. Frame modification
965 | | flow rules are isolated in this table so that they can
966 | Table 2 | be turned on or off without affecting the routing or
967 | | tuple-matching flow rules. This allows the frame
968 | | modification and tuple matching required by the tests
969 | | in the VSWITCH PERFORMANCE FOR TELCO NFV test
970 +--------------+ specification to be independent of the Deployment
971 | Scenario set up by the vSwitchController.
976 | Table 3 | table#3 - Egress table. Egress packets on the ports
977 | | setup in Table 1.