diff options
Diffstat (limited to 'docs/userguide/testusage.rst')
| -rwxr-xr-x | docs/userguide/testusage.rst | 314 |
1 files changed, 198 insertions, 116 deletions
diff --git a/docs/userguide/testusage.rst b/docs/userguide/testusage.rst index 3c5cc4d4..f446f261 100755 --- a/docs/userguide/testusage.rst +++ b/docs/userguide/testusage.rst @@ -105,14 +105,61 @@ or via another command line argument will override both the default and your custom configuration files. This "priority hierarchy" can be described like so (1 = max priority): -1. Command line arguments -2. Environment variables -3. Configuration file(s) +1. Testcase definition section ``Parameters`` +2. Command line arguments +3. Environment variables +4. Configuration file(s) Further details about configuration files evaluation and special behaviour of options with ``GUEST_`` prefix could be found at `design document <http://artifacts.opnfv.org/vswitchperf/docs/design/vswitchperf_design.html#configuration>`__. +Overriding values defined in configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The configuration items can be overridden by command line argument +``--test-params``. In this case, the configuration items and +their values should be passed in form of ``item=value`` and separated +by semicolon. + +Example: + +.. code:: console + + $ ./vsperf --test-params "TRAFFICGEN_DURATION=10;TRAFFICGEN_PKT_SIZES=(128,);" \ + "GUEST_LOOPBACK=['testpmd','l2fwd']" pvvp_tput + +The second option is to override configuration items by ``Parameters`` section +of the test case definition. The configuration items can be added into ``Parameters`` +dictionary with their new values. These values will override values defined in +configuration files or specified by ``--test-params`` command line argument. + +Example: + +.. code:: python + + "Parameters" : {'TRAFFICGEN_PKT_SIZES' : (128,), + 'TRAFFICGEN_DURATION' : 10, + 'GUEST_LOOPBACK' : ['testpmd','l2fwd'], + } + +**NOTE:** In both cases, configuration item names and their values must be specified +in the same form as they are defined inside configuration files. Parameter names +must be specified in uppercase and data types of original and new value must match. +Python syntax rules related to data types and structures must be followed. +For example, parameter ``TRAFFICGEN_PKT_SIZES`` above is defined as a tuple +with a single value ``128``. In this case trailing comma is mandatory, otherwise +value can be wrongly interpreted as a number instead of a tuple and vsperf +execution would fail. Please check configuration files for default values and their +types and use them as a basis for any customized values. In case of any doubt, please +check official python documentation related to data structures like tuples, lists +and dictionaries. + +**NOTE:** Vsperf execution will terminate with runtime error in case, that unknown +parameter name is passed via ``--test-params`` CLI argument or defined in ``Parameters`` +section of test case definition. It is also forbidden to redefine a value of +``TEST_PARAMS`` configuration item via CLI or ``Parameters`` section. + vloop_vnf ^^^^^^^^^ @@ -131,6 +178,7 @@ installation instructions for information on these images vloop_vnf forwards traffic through a VM using one of: + * DPDK testpmd * Linux Bridge * l2fwd kernel Module. @@ -147,6 +195,9 @@ IP addresses. l2fwd can be found in <vswitchperf_dir>/src/l2fwd Executing tests ^^^^^^^^^^^^^^^ +All examples inside these docs assume, that user is inside the VSPERF +directory. VSPERF can be executed from any directory. + Before running any tests make sure you have root permissions by adding the following line to /etc/sudoers: @@ -188,9 +239,9 @@ Some tests allow for configurable parameters, including test duration .. code:: bash - $ ./vsperf --conf-file user_settings.py - --tests RFC2544Tput - --test-params "duration=10;pkt_sizes=128" + $ ./vsperf --conf-file user_settings.py \ + --tests RFC2544Tput \ + --test-params "TRAFFICGEN_DURATION=10;TRAFFICGEN_PKT_SIZES=(128,)" For all available options, check out the help dialog: @@ -203,35 +254,30 @@ Executing Vanilla OVS tests 1. If needed, recompile src for all OVS variants -.. code-block:: console - - $ cd src - $ make distclean - $ make + .. code-block:: console -2. Update your ''10_custom.conf'' file to use the appropriate variables -for Vanilla OVS: + $ cd src + $ make distclean + $ make -.. code-block:: console +2. Update your ``10_custom.conf`` file to use Vanilla OVS: - VSWITCH = 'OvsVanilla' + .. code-block:: python -Where $PORT1 and $PORT2 are the Linux interfaces you'd like to bind -to the vswitch. + VSWITCH = 'OvsVanilla' 3. Run test: -.. code-block:: console + .. code-block:: console - $ ./vsperf --conf-file=<path_to_custom_conf> + $ ./vsperf --conf-file=<path_to_custom_conf> -Please note if you don't want to configure Vanilla OVS through the -configuration file, you can pass it as a CLI argument; BUT you must -set the ports. + Please note if you don't want to configure Vanilla OVS through the + configuration file, you can pass it as a CLI argument. -.. code-block:: console + .. code-block:: console - $ ./vsperf --vswitch OvsVanilla + $ ./vsperf --vswitch OvsVanilla Executing tests with VMs @@ -241,24 +287,24 @@ To run tests using vhost-user as guest access method: 1. Set VHOST_METHOD and VNF of your settings file to: -.. code-block:: console + .. code-block:: python - VSWITCH = 'OvsDpdkVhost' - VNF = 'QemuDpdkVhost' + VSWITCH = 'OvsDpdkVhost' + VNF = 'QemuDpdkVhost' 2. If needed, recompile src for all OVS variants -.. code-block:: console + .. code-block:: console - $ cd src - $ make distclean - $ make + $ cd src + $ make distclean + $ make 3. Run test: -.. code-block:: console + .. code-block:: console - $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf Executing tests with VMs using Vanilla OVS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -267,39 +313,42 @@ To run tests using Vanilla OVS: 1. Set the following variables: -.. code-block:: console + .. code-block:: python - VSWITCH = 'OvsVanilla' - VNF = 'QemuVirtioNet' + VSWITCH = 'OvsVanilla' + VNF = 'QemuVirtioNet' - VANILLA_TGEN_PORT1_IP = n.n.n.n - VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn + VANILLA_TGEN_PORT1_IP = n.n.n.n + VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn - VANILLA_TGEN_PORT2_IP = n.n.n.n - VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn + VANILLA_TGEN_PORT2_IP = n.n.n.n + VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn - VANILLA_BRIDGE_IP = n.n.n.n + VANILLA_BRIDGE_IP = n.n.n.n - or use --test-param + or use ``--test-params`` option - $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf - --test-params "vanilla_tgen_tx_ip=n.n.n.n; - vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn" + .. code-block:: console + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf \ + --test-params "VANILLA_TGEN_PORT1_IP=n.n.n.n;" \ + "VANILLA_TGEN_PORT1_MAC=nn:nn:nn:nn:nn:nn;" \ + "VANILLA_TGEN_PORT2_IP=n.n.n.n;" \ + "VANILLA_TGEN_PORT2_MAC=nn:nn:nn:nn:nn:nn" 2. If needed, recompile src for all OVS variants -.. code-block:: console + .. code-block:: console - $ cd src - $ make distclean - $ make + $ cd src + $ make distclean + $ make 3. Run test: -.. code-block:: console + .. code-block:: console - $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf + $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf .. _vfio-pci: @@ -309,7 +358,7 @@ Using vfio_pci with DPDK To use vfio with DPDK instead of igb_uio add into your custom configuration file the following parameter: -.. code-block:: console +.. code-block:: python PATHS['dpdk']['src']['modules'] = ['uio', 'vfio-pci'] @@ -389,7 +438,7 @@ Execution of test with PCI passthrough with vswitch disabled: .. code-block:: console - $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf \ --vswitch none --vnf QemuPciPassthrough pvp_tput Any of supported guest-loopback-application_ can be used inside VM with @@ -403,19 +452,19 @@ deployment. Selection of loopback application for tests with VMs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To select loopback application, which will perform traffic forwarding -inside VM, following configuration parameter should be configured: +To select the loopback applications which will forward packets inside VMs, +the following parameter should be configured: -.. code-block:: console +.. code-block:: python GUEST_LOOPBACK = ['testpmd'] -or use --test-param +or use ``--test-params`` CLI argument: .. code-block:: console - $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf - --test-params "guest_loopback=testpmd" + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf \ + --test-params "GUEST_LOOPBACK=['testpmd']" Supported loopback applications are: @@ -431,37 +480,69 @@ Guest loopback application must be configured, otherwise traffic will not be forwarded by VM and testcases with VM related deployments will fail. Guest loopback application is set to 'testpmd' by default. -Note: In case that only 1 or more than 2 NICs are configured for VM, +**NOTE:** In case that only 1 or more than 2 NICs are configured for VM, then 'testpmd' should be used. As it is able to forward traffic between multiple VM NIC pairs. -Note: In case of linux_bridge, all guest NICs are connected to the same +**NOTE:** In case of linux_bridge, all guest NICs are connected to the same bridge inside the guest. +Selection of dpdk binding driver for tests with VMs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To select dpdk binding driver, which will specify which driver the vm NICs will +use for dpdk bind, the following configuration parameter should be configured: + +.. code-block:: console + + GUEST_DPDK_BIND_DRIVER = ['igb_uio_from_src'] + +The supported dpdk guest bind drivers are: + +.. code-block:: console + + 'uio_pci_generic' - Use uio_pci_generic driver + 'igb_uio_from_src' - Build and use the igb_uio driver from the dpdk src + files + 'vfio_no_iommu' - Use vfio with no iommu option. This requires custom + guest images that support this option. The default + vloop image does not support this driver. + +Note: uio_pci_generic does not support sr-iov testcases with guests attached. +This is because uio_pci_generic only supports legacy interrupts. In case +uio_pci_generic is selected with the vnf as QemuPciPassthrough it will be +modified to use igb_uio_from_src instead. + +Note: vfio_no_iommu requires kernels equal to or greater than 4.5 and dpdk +16.04 or greater. Using this option will also taint the kernel. + +Please refer to the dpdk documents at http://dpdk.org/doc/guides for more +information on these drivers. + Multi-Queue Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^ VSPerf currently supports multi-queue with the following limitations: - 1. Requires QEMU 2.5 or greater and any OVS version higher than 2.5. The - default upstream package versions installed by VSPerf satisfies this - requirement. +1. Requires QEMU 2.5 or greater and any OVS version higher than 2.5. The + default upstream package versions installed by VSPerf satisfies this + requirement. - 2. Guest image must have ethtool utility installed if using l2fwd or linux - bridge inside guest for loopback. +2. Guest image must have ethtool utility installed if using l2fwd or linux + bridge inside guest for loopback. - 3. If using OVS versions 2.5.0 or less enable old style multi-queue as shown - in the ''02_vswitch.conf'' file. +3. If using OVS versions 2.5.0 or less enable old style multi-queue as shown + in the ''02_vswitch.conf'' file. - .. code-block:: console + .. code-block:: python - OVS_OLD_STYLE_MQ = True + OVS_OLD_STYLE_MQ = True To enable multi-queue for dpdk modify the ''02_vswitch.conf'' file. - .. code-block:: console +.. code-block:: python - VSWITCH_DPDK_MULTI_QUEUES = 2 + VSWITCH_DPDK_MULTI_QUEUES = 2 **NOTE:** you should consider using the switch affinity to set a pmd cpu mask that can optimize your performance. Consider the numa of the NIC in use if this @@ -475,9 +556,9 @@ port by port option. To enable multi-queue on the guest modify the ''04_vnf.conf'' file. - .. code-block:: console +.. code-block:: python - GUEST_NIC_QUEUES = 2 + GUEST_NIC_QUEUES = [2] Enabling multi-queue at the guest will add multiple queues to each NIC port when qemu launches the guest. @@ -489,13 +570,12 @@ multi-queue on the guest is sufficient for Vanilla OVS multi-queue. Testpmd should be configured to take advantage of multi-queue on the guest if using DPDKVhostUser. This can be done by modifying the ''04_vnf.conf'' file. - .. code-block:: console - - GUEST_TESTPMD_CPU_MASK = '-l 0,1,2,3,4' +.. code-block:: python - GUEST_TESTPMD_NB_CORES = 4 - GUEST_TESTPMD_TXQ = 2 - GUEST_TESTPMD_RXQ = 2 + GUEST_TESTPMD_PARAMS = ['-l 0,1,2,3,4 -n 4 --socket-mem 512 -- ' + '--burst=64 -i --txqflags=0xf00 ' + '--nb-cores=4 --rxq=2 --txq=2 ' + '--disable-hw-vlan'] **NOTE:** The guest SMP cores must be configured to allow for testpmd to use the optimal number of cores to take advantage of the multiple guest queues. @@ -505,11 +585,11 @@ by binding vhost-net threads to cpus. This can be done by enabling the affinity in the ''04_vnf.conf'' file. This can be done to non multi-queue enabled configurations as well as there will be 2 vhost-net threads. - .. code-block:: console +.. code-block:: python - VSWITCH_VHOST_NET_AFFINITIZATION = True + VSWITCH_VHOST_NET_AFFINITIZATION = True - VSWITCH_VHOST_CPU_MAP = [4,5,8,11] + VSWITCH_VHOST_CPU_MAP = [4,5,8,11] **NOTE:** This method of binding would require a custom script in a real environment. @@ -521,51 +601,53 @@ assigned at least (nb_cores +1) total cores with the cpu mask. Executing Packet Forwarding tests ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To select application, which will perform packet forwarding, -following configuration parameter should be configured: +To select the applications which will forward packets, +the following parameters should be configured: - .. code-block:: console +.. code-block:: python + + VSWITCH = 'none' + PKTFWD = 'TestPMD' - VSWITCH = 'none' - PKTFWD = 'TestPMD' +or use ``--vswitch`` and ``--fwdapp`` CLI arguments: - or use --vswitch and --fwdapp +.. code-block:: console - $ ./vsperf --conf-file user_settings.py - --vswitch none - --fwdapp TestPMD + $ ./vsperf --conf-file user_settings.py \ + --vswitch none \ + --fwdapp TestPMD Supported Packet Forwarding applications are: - .. code-block:: console +.. code-block:: console - 'testpmd' - testpmd from dpdk + 'testpmd' - testpmd from dpdk 1. Update your ''10_custom.conf'' file to use the appropriate variables -for selected Packet Forwarder: - - .. code-block:: console - - # testpmd configuration - TESTPMD_ARGS = [] - # packet forwarding mode supported by testpmd; Please see DPDK documentation - # for comprehensive list of modes supported by your version. - # e.g. io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho|... - # Note: Option "mac_retry" has been changed to "mac retry" since DPDK v16.07 - TESTPMD_FWD_MODE = 'csum' - # checksum calculation layer: ip|udp|tcp|sctp|outer-ip - TESTPMD_CSUM_LAYER = 'ip' - # checksum calculation place: hw (hardware) | sw (software) - TESTPMD_CSUM_CALC = 'sw' - # recognize tunnel headers: on|off - TESTPMD_CSUM_PARSE_TUNNEL = 'off' + for selected Packet Forwarder: + + .. code-block:: python + + # testpmd configuration + TESTPMD_ARGS = [] + # packet forwarding mode supported by testpmd; Please see DPDK documentation + # for comprehensive list of modes supported by your version. + # e.g. io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho|... + # Note: Option "mac_retry" has been changed to "mac retry" since DPDK v16.07 + TESTPMD_FWD_MODE = 'csum' + # checksum calculation layer: ip|udp|tcp|sctp|outer-ip + TESTPMD_CSUM_LAYER = 'ip' + # checksum calculation place: hw (hardware) | sw (software) + TESTPMD_CSUM_CALC = 'sw' + # recognize tunnel headers: on|off + TESTPMD_CSUM_PARSE_TUNNEL = 'off' 2. Run test: - .. code-block:: console + .. code-block:: console - $ ./vsperf --conf-file <path_to_settings_py> + $ ./vsperf --conf-file <path_to_settings_py> VSPERF modes of operation ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -587,7 +669,7 @@ Mode of operation is driven by configuration parameter -m or --mode "trafficgen-pause" - execute vSwitch and VNF but wait before traffic transmission In case, that VSPERF is executed in "trafficgen" mode, then configuration -of traffic generator should be configured through --test-params option. +of traffic generator should be configured through ``--test-params`` option. Supported CLI options useful for traffic generator configuration are: .. code-block:: console @@ -614,7 +696,7 @@ Example of execution of VSPERF in "trafficgen" mode: .. code-block:: console - $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf + $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf \ --test-params "traffic_type=continuous;bidirectional=True;iload=60" Code change verification by pylint @@ -650,7 +732,7 @@ By default the vswitchd is launched with 1Gb of memory, to change this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate an appropriate amount of memory: -.. code-block:: console +.. code-block:: python VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0'] VSWITCHD_DPDK_CONFIG = { |