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.
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/pharos/Pharos+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.
335 Note: It is supported only for p2p deployment scenario.
338 "Yes" - flows will be inserted into OVS
339 "No" - flows won't be inserted into OVS
341 'flow_type' - Defines flows complexity.
344 "port" - flow is defined by ingress ports
345 "IP" - flow is defined by ingress ports
346 and src and dst IP addresses
347 Default value: "port"
348 'flow_control' - Controls flow control support by traffic generator.
350 False - flow control is disabled
351 True - flow control is enabled
353 Note: Currently it is supported by IxNet only
354 'learning_frames' - Controls learning frames support by traffic generator.
356 False - learning frames are disabled
357 True - learning frames are enabled
359 Note: Currently it is supported by IxNet only
360 'l2' - A dictionary with l2 network layer details. Supported
362 'srcmac' - Specifies source MAC address filled by traffic generator.
363 NOTE: It can be modified by vsperf in some scenarios.
365 Default value: "00:00:00:00:00:00".
366 'dstmac' - Specifies destination MAC address filled by traffic generator.
367 NOTE: It can be modified by vsperf in some scenarios.
369 Default value: "00:00:00:00:00:00".
370 'framesize' - Specifies default frame size. This value should not be
371 changed directly. It will be overridden during testcase
372 execution by values specified by list TRAFFICGEN_PKT_SIZES.
375 'l3' - A dictionary with l3 network layer details. Supported
377 'enabled' - Specifies if l3 layer should be enabled or disabled.
380 NOTE: Supported only by IxNet trafficgen class
381 'srcip' - Specifies source MAC address filled by traffic generator.
382 NOTE: It can be modified by vsperf in some scenarios.
384 Default value: "1.1.1.1".
385 'dstip' - Specifies destination MAC address filled by traffic generator.
386 NOTE: It can be modified by vsperf in some scenarios.
388 Default value: "90.90.90.90".
389 'proto' - Specifies deflaut protocol type.
390 Please check particular traffic generator implementation
391 for supported protocol types.
393 Default value: "udp".
394 'l4' - A dictionary with l4 network layer details. Supported
396 'enabled' - Specifies if l4 layer should be enabled or disabled.
399 NOTE: Supported only by IxNet trafficgen class
400 'srcport' - Specifies source port of selected transport protocol.
401 NOTE: It can be modified by vsperf in some scenarios.
404 'dstport' - Specifies destination port of selected transport protocol.
405 NOTE: It can be modified by vsperf in some scenarios.
408 'vlan' - A dictionary with vlan encapsulation details. Supported
410 'enabled' - Specifies if vlan encapsulation should be enabled or
414 'id' - Specifies vlan id.
415 Data type: int (NOTE: must fit to 12 bits)
417 'priority' - Specifies a vlan priority (PCP header field).
418 Data type: int (NOTE: must fit to 3 bits)
420 'cfi' - Specifies if frames can or cannot be dropped during
421 congestion (DEI header field).
422 Data type: int (NOTE: must fit to 1 bit)
424 'capture' - A dictionary with traffic capture configuration.
425 NOTE: It is supported only by T-Rex traffic generator.
426 'enabled' - Specifies if traffic should be captured
429 'tx_ports' - A list of ports, where frames transmitted towards DUT will
430 be captured. Ports have numbers 0 and 1. TX packet capture
431 is disabled if list of ports is empty.
434 'rx_ports' - A list of ports, where frames received from DUT will
435 be captured. Ports have numbers 0 and 1. RX packet capture
436 is disabled if list of ports is empty.
439 'count' - A number of frames to be captured. The same count value
440 is applied to both TX and RX captures.
443 'filter' - An expression used to filter TX and RX packets. It uses the same
444 syntax as pcap library. See pcap-filter man page for additional
448 'scapy' - A dictionary with definition of a frame content for both traffic
449 directions. The frame content is defined by a SCAPY notation.
450 NOTE: It is supported only by the T-Rex traffic generator.
451 Following keywords can be used to refer to the related parts of
452 the TRAFFIC dictionary:
453 Ether_src - refers to TRAFFIC['l2']['srcmac']
454 Ether_dst - refers to TRAFFIC['l2']['dstmac']
455 IP_proto - refers to TRAFFIC['l3']['proto']
456 IP_PROTO - refers to upper case version of TRAFFIC['l3']['proto']
457 IP_src - refers to TRAFFIC['l3']['srcip']
458 IP_dst - refers to TRAFFIC['l3']['dstip']
459 IP_PROTO_sport - refers to TRAFFIC['l4']['srcport']
460 IP_PROTO_dport - refers to TRAFFIC['l4']['dstport']
461 Dot1Q_prio - refers to TRAFFIC['vlan']['priority']
462 Dot1Q_id - refers to TRAFFIC['vlan']['cfi']
463 Dot1Q_vlan - refers to TRAFFIC['vlan']['id']
464 '0' - A string with the frame definition for the 1st direction.
466 Default value: 'Ether(src={Ether_src}, dst={Ether_dst})/'
467 'Dot1Q(prio={Dot1Q_prio}, id={Dot1Q_id}, vlan={Dot1Q_vlan})/'
468 'IP(proto={IP_proto}, src={IP_src}, dst={IP_dst})/'
469 '{IP_PROTO}(sport={IP_PROTO_sport}, dport={IP_PROTO_dport})'
470 '1' - A string with the frame definition for the 2nd direction.
472 Default value: 'Ether(src={Ether_dst}, dst={Ether_src})/'
473 'Dot1Q(prio={Dot1Q_prio}, id={Dot1Q_id}, vlan={Dot1Q_vlan})/'
474 'IP(proto={IP_proto}, src={IP_dst}, dst={IP_src})/'
475 '{IP_PROTO}(sport={IP_PROTO_dport}, dport={IP_PROTO_sport})',
477 .. _configuration-of-guest-options:
479 Configuration of GUEST options
480 ------------------------------
482 VSPERF is able to setup scenarios involving a number of VMs in series or in parallel.
483 All configuration options related to a particular VM instance are defined as
484 lists and prefixed with ``GUEST_`` label. It is essential, that there is enough
485 items in all ``GUEST_`` options to cover all VM instances involved in the test.
486 In case there is not enough items, then VSPERF will use the first item of
487 particular ``GUEST_`` option to expand the list to required length.
489 Example of option expansion for 4 VMs:
491 .. code-block:: python
497 GUEST_MEMORY = ['2048', '4096']
500 Values after automatic expansion:
502 GUEST_SMP = ['2', '2', '2', '2']
503 GUEST_MEMORY = ['2048', '4096', '2048', '2048']
506 First option can contain macros starting with ``#`` to generate VM specific values.
507 These macros can be used only for options of ``list`` or ``str`` types with ``GUEST_``
510 Example of macros and their expansion for 2 VMs:
512 .. code-block:: python
517 GUEST_SHARE_DIR = ['/tmp/qemu#VMINDEX_share']
518 GUEST_BRIDGE_IP = ['#IP(1.1.1.5)/16']
521 Values after automatic expansion:
523 GUEST_SHARE_DIR = ['/tmp/qemu0_share', '/tmp/qemu1_share']
524 GUEST_BRIDGE_IP = ['1.1.1.5/16', '1.1.1.6/16']
526 Additional examples are available at ``04_vnf.conf``.
528 Note: In case, that macro is detected in the first item of the list, then
529 all other items are ignored and list content is created automatically.
531 Multiple macros can be used inside one configuration option definition, but macros
532 cannot be used inside other macros. The only exception is macro ``#VMINDEX``, which
533 is expanded first and thus it can be used inside other macros.
535 Following macros are supported:
537 * ``#VMINDEX`` - it is replaced by index of VM being executed; This macro
538 is expanded first, so it can be used inside other macros.
542 .. code-block:: python
544 GUEST_SHARE_DIR = ['/tmp/qemu#VMINDEX_share']
546 * ``#MAC(mac_address[, step])`` - it will iterate given ``mac_address``
547 with optional ``step``. In case that step is not defined, then it is set to 1.
548 It means, that first VM will use the value of ``mac_address``, second VM
549 value of ``mac_address`` increased by ``step``, etc.
553 .. code-block:: python
555 GUEST_NICS = [[{'mac' : '#MAC(00:00:00:00:00:01,2)'}]]
557 * ``#IP(ip_address[, step])`` - it will iterate given ``ip_address``
558 with optional ``step``. In case that step is not defined, then it is set to 1.
559 It means, that first VM will use the value of ``ip_address``, second VM
560 value of ``ip_address`` increased by ``step``, etc.
564 .. code-block:: python
566 GUEST_BRIDGE_IP = ['#IP(1.1.1.5)/16']
568 * ``#EVAL(expression)`` - it will evaluate given ``expression`` as python code;
569 Only simple expressions should be used. Call of the functions is not supported.
573 .. code-block:: python
575 GUEST_CORE_BINDING = [('#EVAL(6+2*#VMINDEX)', '#EVAL(7+2*#VMINDEX)')]
580 ``conf.settings`` also loads configuration from the command line and from the environment.
587 Every testcase uses one of the supported deployment scenarios to setup test environment.
588 The controller responsible for a given scenario configures flows in the vswitch to route
589 traffic among physical interfaces connected to the traffic generator and virtual
590 machines. VSPERF supports several deployments including PXP deployment, which can
591 setup various scenarios with multiple VMs.
593 These scenarios are realized by VswitchControllerPXP class, which can configure and
594 execute given number of VMs in serial or parallel configurations. Every VM can be
595 configured with just one or an even number of interfaces. In case that VM has more than
596 2 interfaces, then traffic is properly routed among pairs of interfaces.
598 Example of traffic routing for VM with 4 NICs in serial configuration:
600 .. code-block:: console
602 +------------------------------------------+
604 | +---------------+ +---------------+ |
605 | | Application | | Application | |
606 | +---------------+ +---------------+ |
609 | +---------------+ +---------------+ |
610 | | logical ports | | logical ports | |
612 +--+---------------+----+---------------+--+
616 +-----------+---------------+----+---------------+----------+
617 | vSwitch | 0 1 | | 2 3 | |
618 | | logical ports | | logical ports | |
619 | previous +---------------+ +---------------+ next |
620 | VM or PHY ^ | ^ | VM or PHY|
621 | port -----+ +------------+ +---> port |
622 +-----------------------------------------------------------+
624 It is also possible to define different number of interfaces for each VM to better
625 simulate real scenarios.
627 Example of traffic routing for 2 VMs in serial configuration, where 1st VM has
628 4 NICs and 2nd VM 2 NICs:
630 .. code-block:: console
632 +------------------------------------------+ +---------------------+
633 | 1st VM with 4 NICs | | 2nd VM with 2 NICs |
634 | +---------------+ +---------------+ | | +---------------+ |
635 | | Application | | Application | | | | Application | |
636 | +---------------+ +---------------+ | | +---------------+ |
639 | +---------------+ +---------------+ | | +---------------+ |
640 | | logical ports | | logical ports | | | | logical ports | |
641 | | 0 1 | | 2 3 | | | | 0 1 | |
642 +--+---------------+----+---------------+--+ +--+---------------+--+
646 +-----------+---------------+----+---------------+-------+---------------+----------+
647 | vSwitch | 0 1 | | 2 3 | | 4 5 | |
648 | | logical ports | | logical ports | | logical ports | |
649 | previous +---------------+ +---------------+ +---------------+ next |
650 | VM or PHY ^ | ^ | ^ | VM or PHY|
651 | port -----+ +------------+ +---------------+ +----> port |
652 +-----------------------------------------------------------------------------------+
654 The number of VMs involved in the test and the type of their connection is defined
655 by deployment name as follows:
657 * ``pvvp[number]`` - configures scenario with VMs connected in series with
658 optional ``number`` of VMs. In case that ``number`` is not specified, then
661 Example of 2 VMs in a serial configuration:
663 .. code-block:: console
665 +----------------------+ +----------------------+
666 | 1st VM | | 2nd VM |
667 | +---------------+ | | +---------------+ |
668 | | Application | | | | Application | |
669 | +---------------+ | | +---------------+ |
672 | +---------------+ | | +---------------+ |
673 | | logical ports | | | | logical ports | |
674 | | 0 1 | | | | 0 1 | |
675 +---+---------------+--+ +---+---------------+--+
679 +---+---------------+---------+---------------+--+
681 | | logical ports | vSwitch | logical ports | |
682 | +---------------+ +---------------+ |
684 | | +-----------------+ v |
685 | +----------------------------------------+ |
686 | | physical ports | |
688 +---+----------------------------------------+---+
692 +------------------------------------------------+
694 | traffic generator |
696 +------------------------------------------------+
698 * ``pvpv[number]`` - configures scenario with VMs connected in parallel with
699 optional ``number`` of VMs. In case that ``number`` is not specified, then
700 2 VMs will be used. Multistream feature is used to route traffic to particular
701 VMs (or NIC pairs of every VM). It means, that VSPERF will enable multistream
702 feature and sets the number of streams to the number of VMs and their NIC
703 pairs. Traffic will be dispatched based on Stream Type, i.e. by UDP port,
704 IP address or MAC address.
706 Example of 2 VMs in a parallel configuration, where traffic is dispatched
707 based on the UDP port.
709 .. code-block:: console
711 +----------------------+ +----------------------+
712 | 1st VM | | 2nd VM |
713 | +---------------+ | | +---------------+ |
714 | | Application | | | | Application | |
715 | +---------------+ | | +---------------+ |
718 | +---------------+ | | +---------------+ |
719 | | logical ports | | | | logical ports | |
720 | | 0 1 | | | | 0 1 | |
721 +---+---------------+--+ +---+---------------+--+
725 +---+---------------+---------+---------------+--+
727 | | logical ports | vSwitch | logical ports | |
728 | +---------------+ +---------------+ |
730 | | ......................: : |
732 | port| port: +--------------------+ : |
735 | +----------------------------------------+ |
736 | | physical ports | |
738 +---+----------------------------------------+---+
742 +------------------------------------------------+
744 | traffic generator |
746 +------------------------------------------------+
749 PXP deployment is backward compatible with PVP deployment, where ``pvp`` is
750 an alias for ``pvvp1`` and it executes just one VM.
752 The number of interfaces used by VMs is defined by configuration option
753 ``GUEST_NICS_NR``. In case that more than one pair of interfaces is defined
756 * for ``pvvp`` (serial) scenario every NIC pair is connected in serial
757 before connection to next VM is created
758 * for ``pvpv`` (parallel) scenario every NIC pair is directly connected
759 to the physical ports and unique traffic stream is assigned to it
763 * Deployment ``pvvp10`` will start 10 VMs and connects them in series
764 * Deployment ``pvpv4`` will start 4 VMs and connects them in parallel
765 * Deployment ``pvpv1`` and GUEST_NICS_NR = [4] will start 1 VM with
766 4 interfaces and every NIC pair is directly connected to the
768 * Deployment ``pvvp`` and GUEST_NICS_NR = [2, 4] will start 2 VMs;
769 1st VM will have 2 interfaces and 2nd VM 4 interfaces. These interfaces
770 will be connected in serial, i.e. traffic will flow as follows:
771 PHY1 -> VM1_1 -> VM1_2 -> VM2_1 -> VM2_2 -> VM2_3 -> VM2_4 -> PHY2
773 Note: In case that only 1 or more than 2 NICs are configured for VM,
774 then ``testpmd`` should be used as forwarding application inside the VM.
775 As it is able to forward traffic between multiple VM NIC pairs.
777 Note: In case of ``linux_bridge``, all NICs are connected to the same
778 bridge inside the VM.
780 VM, vSwitch, Traffic Generator Independence
781 ===========================================
783 VSPERF supports different VSwitches, Traffic Generators, VNFs
784 and Forwarding Applications by using standard object-oriented polymorphism:
786 * Support for vSwitches is implemented by a class inheriting from IVSwitch.
787 * Support for Traffic Generators is implemented by a class inheriting from
789 * Support for VNF is implemented by a class inheriting from IVNF.
790 * Support for Forwarding Applications is implemented by a class inheriting
793 By dealing only with the abstract interfaces the core framework can support
794 many implementations of different vSwitches, Traffic Generators, VNFs
795 and Forwarding Applications.
800 .. code-block:: python
805 add_switch(switch_name)
806 del_switch(switch_name)
807 add_phy_port(switch_name)
808 add_vport(switch_name)
809 get_ports(switch_name)
810 del_port(switch_name, port_name)
811 add_flow(switch_name, flow)
812 del_flow(switch_name, flow=None)
817 .. code-block:: python
819 class ITrafficGenerator:
823 send_burst_traffic(traffic, time)
825 send_cont_traffic(traffic, time, framerate)
826 start_cont_traffic(traffic, time, framerate)
827 stop_cont_traffic(self):
829 send_rfc2544_throughput(traffic, tests, duration, lossrate)
830 start_rfc2544_throughput(traffic, tests, duration, lossrate)
831 wait_rfc2544_throughput(self)
833 send_rfc2544_back2back(traffic, tests, duration, lossrate)
834 start_rfc2544_back2back(traffic, , tests, duration, lossrate)
835 wait_rfc2544_back2back()
837 Note ``send_xxx()`` blocks whereas ``start_xxx()`` does not and must be followed by a subsequent call to ``wait_xxx()``.
842 .. code-block:: python
846 monitor_path, shared_path_host,
847 shared_path_guest, guest_prompt)
851 execute_and_wait (command)
856 .. code-block:: python
866 Controllers are used in conjunction with abstract interfaces as way
867 of decoupling the control of vSwtiches, VNFs, TrafficGenerators
868 and Forwarding Applications from other components.
870 The controlled classes provide basic primitive operations. The Controllers
871 sequence and co-ordinate these primitive operation in to useful actions. For
872 instance the vswitch_controller_p2p can be used to bring any vSwitch (that
873 implements the primitives defined in IVSwitch) into the configuration required
874 by the Phy-to-Phy Deployment Scenario.
876 In order to support a new vSwitch only a new implementation of IVSwitch needs
877 be created for the new vSwitch to be capable of fulfilling all the Deployment
878 Scenarios provided for by existing or future vSwitch Controllers.
880 Similarly if a new Deployment Scenario is required it only needs to be written
881 once as a new vSwitch Controller and it will immediately be capable of
882 controlling all existing and future vSwitches in to that Deployment Scenario.
884 Similarly the Traffic Controllers can be used to co-ordinate basic operations
885 provided by implementers of ITrafficGenerator to provide useful tests. Though
886 traffic generators generally already implement full test cases i.e. they both
887 generate suitable traffic and analyse returned traffic in order to implement a
888 test which has typically been predefined in an RFC document. However the
889 Traffic Controller class allows for the possibility of further enhancement -
890 such as iterating over tests for various packet sizes or creating new tests.
892 Traffic Controller's Role
893 -------------------------
895 .. image:: traffic_controller.png
898 Loader & Component Factory
899 --------------------------
901 The working of the Loader package (which is responsible for *finding* arbitrary
902 classes based on configuration data) and the Component Factory which is
903 responsible for *choosing* the correct class for a particular situation - e.g.
904 Deployment Scenario can be seen in this diagram.
906 .. image:: factory_and_loader.png
911 Vsperf uses a standard set of routing tables in order to allow tests to easily
912 mix and match Deployment Scenarios (PVP, P2P topology), Tuple Matching and
913 Frame Modification requirements.
915 .. code-block:: console
919 | Table 0 | table#0 - Match table. Flows designed to force 5 & 10
920 | | tuple matches go here.
926 +--------------+ table#1 - Routing table. Flow entries to forward
927 | | packets between ports goes here.
928 | Table 1 | The chosen port is communicated to subsequent tables by
929 | | setting the metadata value to the egress port number.
930 | | Generally this table is set-up by by the
931 +--------------+ vSwitchController.
935 +--------------+ table#2 - Frame modification table. Frame modification
936 | | flow rules are isolated in this table so that they can
937 | Table 2 | be turned on or off without affecting the routing or
938 | | tuple-matching flow rules. This allows the frame
939 | | modification and tuple matching required by the tests
940 | | in the VSWITCH PERFORMANCE FOR TELCO NFV test
941 +--------------+ specification to be independent of the Deployment
942 | Scenario set up by the vSwitchController.
947 | Table 3 | table#3 - Egress table. Egress packets on the ports
948 | | setup in Table 1.