diff options
author | Sridhar K. N. Rao <sridhar.rao@spirent.com> | 2021-06-22 14:48:01 +0530 |
---|---|---|
committer | Sridhar K. N. Rao <sridhar.rao@spirent.com> | 2021-06-23 11:59:02 +0530 |
commit | d5c0a03054f720da2a5ff9eba74feee57fb0296d (patch) | |
tree | 9aa3b35f7e6cb82158ab364e8e855b4c8f23649c /docs/testing/user/userguide | |
parent | 8af88b77b668bf2c6bdf61d4bc777f414c935f6c (diff) |
DOCS: Thorough update of ViNePerf Documentation.
Included Kali release notes too.
Made changes based on review from Al.
More changes - thanks to Al.
Signed-off-by: Sridhar K. N. Rao <sridhar.rao@spirent.com>
Change-Id: I50b02c2389ddad9596433fd33430270da0fab5db
Diffstat (limited to 'docs/testing/user/userguide')
-rw-r--r-- | docs/testing/user/userguide/index.rst | 10 | ||||
-rw-r--r-- | docs/testing/user/userguide/integration.rst | 6 | ||||
-rw-r--r-- | docs/testing/user/userguide/testlist.rst | 10 | ||||
-rw-r--r-- | docs/testing/user/userguide/teststeps.rst | 13 | ||||
-rw-r--r-- | docs/testing/user/userguide/testusage.rst | 54 | ||||
-rw-r--r-- | docs/testing/user/userguide/trafficcapture.rst | 8 | ||||
-rw-r--r-- | docs/testing/user/userguide/yardstick.rst | 54 |
7 files changed, 79 insertions, 76 deletions
diff --git a/docs/testing/user/userguide/index.rst b/docs/testing/user/userguide/index.rst index 2c7a78ff..de38db7e 100644 --- a/docs/testing/user/userguide/index.rst +++ b/docs/testing/user/userguide/index.rst @@ -2,14 +2,14 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, Intel Corporation, AT&T, Red Hat, Spirent, Ixia and others. -.. OPNFV VSPERF Documentation master file. +.. Anuket ViNePerf Documentation master file. -================= -VSPERF Test Guide -================= +=================== +ViNePerf Test Guide +=================== .. toctree:: - :caption: VSPERF Test Execution + :caption: ViNePerf Test Execution :maxdepth: 2 ./testusage.rst diff --git a/docs/testing/user/userguide/integration.rst b/docs/testing/user/userguide/integration.rst index 9d847fd8..0a7be40a 100644 --- a/docs/testing/user/userguide/integration.rst +++ b/docs/testing/user/userguide/integration.rst @@ -7,7 +7,7 @@ Integration tests ================= -VSPERF includes a set of integration tests defined in conf/integration. +ViNePerf includes a set of integration tests defined in conf/integration. These tests can be run by specifying --integration as a parameter to vsperf. Current tests in conf/integration include switch functionality and Overlay tests. @@ -15,7 +15,7 @@ tests. Tests in the conf/integration can be used to test scaling of different switch configurations by adding steps into the test case. -For the overlay tests VSPERF supports VXLAN, GRE and GENEVE tunneling protocols. +For the overlay tests ViNePerf supports VXLAN, GRE and GENEVE tunneling protocols. Testing of these protocols is limited to unidirectional traffic and P2P (Physical to Physical scenarios). @@ -31,7 +31,7 @@ or GENEVE protocols. In that case options "Tunnel Operation" and Executing Integration Tests --------------------------- -To execute integration tests VSPERF is run with the integration parameter. To +To execute integration tests ViNePerf is run with the integration parameter. To view the current test list simply execute the following command: .. code-block:: console diff --git a/docs/testing/user/userguide/testlist.rst b/docs/testing/user/userguide/testlist.rst index fe8c840a..42786244 100644 --- a/docs/testing/user/userguide/testlist.rst +++ b/docs/testing/user/userguide/testlist.rst @@ -125,9 +125,9 @@ Example of execution of all OVS/DPDK regression tests: Testcases are defined in the file ``conf/integration/01b_dpdk_regression_tests.conf``. This file contains a set of configuration options with prefix ``OVSDPDK_``. These parameters can be used -for customization of regression tests and they will override some of standard VSPERF configuration +for customization of regression tests and they will override some of standard ViNePerf configuration options. It is recommended to check OVSDPDK configuration parameters and modify them in accordance -with VSPERF configuration. +with ViNePerf configuration. At least following parameters should be examined. Their values shall ensure, that DPDK and QEMU threads are pinned to cpu cores of the same NUMA slot, where tested NICs are connected. @@ -229,7 +229,7 @@ Multiqueue Support A set of functional testcases for validation of multiqueue support for both physical and vHost User DPDK ports. Testcases utilize P2P and PVP network deployments and -native support of multiqueue configuration available in VSPERF. +native support of multiqueue configuration available in ViNePerf. ======================================== ====================================================================================== Testcase Name Description @@ -293,7 +293,7 @@ Jumbo Frame Support A set of functional testcases for verification of jumbo frame support in OVS. Testcases utilize P2P and PVP network deployments and native support of jumbo -frames available in VSPERF. +frames available in ViNePerf. ============================================ ================================================================================== Testcase Name Description @@ -392,7 +392,7 @@ Custom Statistics +++++++++++++++++ A set of functional testcases for validation of Custom Statistics support by OVS. -This feature allows Custom Statistics to be accessed by VSPERF. +This feature allows Custom Statistics to be accessed by ViNePerf. These testcases require DPDK v17.11, the latest Open vSwitch(v2.9.90) and the IxNet traffic-generator. diff --git a/docs/testing/user/userguide/teststeps.rst b/docs/testing/user/userguide/teststeps.rst index cb627bc5..63bb33b1 100644 --- a/docs/testing/user/userguide/teststeps.rst +++ b/docs/testing/user/userguide/teststeps.rst @@ -10,10 +10,10 @@ Step driven tests In general, test scenarios are defined by a ``deployment`` used in the particular test case definition. The chosen deployment scenario will take care of the vSwitch configuration, deployment of VNFs and it can also affect configuration of a traffic -generator. In order to allow a more flexible way of testcase scripting, VSPERF supports +generator. In order to allow a more flexible way of testcase scripting, ViNePerf supports a detailed step driven testcase definition. It can be used to configure and program vSwitch, deploy and terminate VNFs, execute a traffic generator, -modify a VSPERF configuration, execute external commands, etc. +modify a ViNePerf configuration, execute external commands, etc. Execution of step driven tests is done on a step by step work flow starting with step 0 as defined inside the test case. Each step of the test increments @@ -121,7 +121,7 @@ parameters. List of supported functions: - * ``start`` - starts a VNF based on VSPERF configuration + * ``start`` - starts a VNF based on ViNePerf configuration * ``stop`` - gracefully terminates given VNF * ``execute command [delay]`` - executes command `cmd` inside VNF; Optional delay defines number of seconds to wait before next step is executed. Method @@ -183,7 +183,10 @@ parameters. .. _step-driven-tests-variable-usage: - * ``settings`` - reads or modifies VSPERF configuration +Step Driven Tests Variable Usage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * ``settings`` - reads or modifies ViNePerf configuration List of supported functions: @@ -202,7 +205,7 @@ parameters. ['settings', 'resetValue', 'WHITELIST_NICS'], - It is possible and more convenient to access any VSPERF configuration option directly + It is possible and more convenient to access any ViNePerf configuration option directly via ``$NAME`` notation. Option evaluation is done during runtime and vsperf will automatically translate it to the appropriate call of ``settings.getValue``. If the referred parameter does not exist, then vsperf will keep ``$NAME`` diff --git a/docs/testing/user/userguide/testusage.rst b/docs/testing/user/userguide/testusage.rst index 3dd41846..a16fd326 100644 --- a/docs/testing/user/userguide/testusage.rst +++ b/docs/testing/user/userguide/testusage.rst @@ -2,14 +2,14 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, Intel Corporation, Spirent, AT&T and others. -vSwitchPerf test suites userguide +ViNePerf test suites userguide --------------------------------- General ^^^^^^^ -VSPERF requires a traffic generators to run tests, automated traffic gen -support in VSPERF includes: +ViNePerf requires a traffic generators to run tests, automated traffic gen +support in ViNePerf includes: - IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA client software. @@ -26,8 +26,8 @@ support in VSPERF includes: If you want to use another traffic generator, please select the :ref:`trafficgen-dummy` generator. -VSPERF Installation -^^^^^^^^^^^^^^^^^^^ +ViNePerf Installation +^^^^^^^^^^^^^^^^^^^^^ To see the supported Operating Systems, vSwitches and system requirements, please follow the `installation instructions <vsperf-installation>`. @@ -41,10 +41,10 @@ install and configure a suitable traffic generator. Cloning and building src dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to run VSPERF, you will need to download DPDK and OVS. You can +In order to run ViNePerf, you will need to download DPDK and OVS. You can do this manually and build them in a preferred location, OR you could -use vswitchperf/src. The vswitchperf/src directory contains makefiles -that will allow you to clone and build the libraries that VSPERF depends +use vineperf/src. The vineperf/src directory contains makefiles +that will allow you to clone and build the libraries that ViNePerf depends on, such as DPDK and OVS. To clone and build simply: .. code-block:: console @@ -52,7 +52,7 @@ on, such as DPDK and OVS. To clone and build simply: $ cd src $ make -VSPERF can be used with stock OVS (without DPDK support). When build +ViNePerf can be used with stock OVS (without DPDK support). When build is finished, the libraries are stored in src_vanilla directory. The 'make' builds all options in src: @@ -61,7 +61,7 @@ The 'make' builds all options in src: * OVS with vhost_user as the guest access method (with DPDK support) The vhost_user build will reside in src/ovs/ -The Vanilla OVS build will reside in vswitchperf/src_vanilla +The Vanilla OVS build will reside in vineperf/src_vanilla To delete a src subdirectory and its contents to allow you to re-clone simply use: @@ -193,7 +193,7 @@ Referencing parameter values It is possible to use a special macro ``#PARAM()`` to refer to the value of another configuration parameter. This reference is evaluated during access of the parameter value (by ``settings.getValue()`` call), so it -can refer to parameters created during VSPERF runtime, e.g. NICS dictionary. +can refer to parameters created during ViNePerf runtime, e.g. NICS dictionary. It can be used to reflect DUT HW details in the testcase definition. Example: @@ -216,7 +216,7 @@ Example: vloop_vnf ^^^^^^^^^ -VSPERF uses a VM image called vloop_vnf for looping traffic in the deployment +ViNePerf uses a VM image called vloop_vnf for looping traffic in the deployment scenarios involving VMs. The image can be downloaded from `<http://artifacts.opnfv.org/>`__. @@ -230,7 +230,7 @@ l2fwd Kernel Module A Kernel Module that provides OSI Layer 2 Ipv4 termination or forwarding with support for Destination Network Address Translation (DNAT) for both the MAC and -IP addresses. l2fwd can be found in <vswitchperf_dir>/src/l2fwd +IP addresses. l2fwd can be found in <vineperf_dir>/src/l2fwd Additional Tools Setup ^^^^^^^^^^^^^^^^^^^^^^ @@ -241,8 +241,8 @@ install and configure additional tools such as collectors and loadgens. Executing tests ^^^^^^^^^^^^^^^ -All examples inside these docs assume, that user is inside the VSPERF -directory. VSPERF can be executed from any directory. +All examples inside these docs assume, that user is inside the ViNePerf +directory. ViNePerf can be executed from any directory. Before running any tests make sure you have root permissions by adding the following line to /etc/sudoers: @@ -525,15 +525,15 @@ of NIC PCI slot definition: Where 'vf' is an indication of virtual function usage and following number defines a VF to be used. In case that VF usage is detected, -then vswitchperf will enable SRIOV support for given card and it will +then vineperf will enable SRIOV support for given card and it will detect PCI slot numbers of selected VFs. So in example above, one VF will be configured for NIC '0000:05:00.0' -and four VFs will be configured for NIC '0000:05:00.1'. Vswitchperf +and four VFs will be configured for NIC '0000:05:00.1'. ViNePerf will detect PCI addresses of selected VFs and it will use them during test execution. -At the end of vswitchperf execution, SRIOV support will be disabled. +At the end of vineperf execution, SRIOV support will be disabled. SRIOV support is generic and it can be used in different testing scenarios. For example: @@ -668,7 +668,7 @@ information on these drivers. Guest Core and Thread Binding ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -VSPERF provides options to achieve better performance by guest core binding and +ViNePerf provides options to achieve better performance by guest core binding and guest vCPU thread binding as well. Core binding is to bind all the qemu threads. Thread binding is to bind the house keeping threads to some CPU and vCPU thread to some other CPU, this helps to reduce the noise from qemu house keeping threads. @@ -787,7 +787,7 @@ assigned at least (nb_cores +1) total cores with the cpu mask. Jumbo Frame Testing ^^^^^^^^^^^^^^^^^^^ -VSPERF provides options to support jumbo frame testing with a jumbo frame supported +ViNePerf provides options to support jumbo frame testing with a jumbo frame supported NIC and traffic generator for the following vswitches: 1. OVSVanilla @@ -820,7 +820,7 @@ its mtu size changed manually using ifconfig or applicable tools: documents as it differs from distribution to distribution. To start a test for jumbo frames modify the conf file packet sizes or pass the option -through the VSPERF command line. +through the ViNePerf command line. .. code-block:: python @@ -945,10 +945,10 @@ Execution of TestPMD can be run with the following command line **NOTE:** To achieve the best 0% loss numbers with rfc2544 throughput testing, other tunings should be applied to host and guest such as tuned profiles and CPU tunings to prevent possible interrupts to worker threads. -VSPERF modes of operation -^^^^^^^^^^^^^^^^^^^^^^^^^ +ViNePerf modes of operation +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -VSPERF can be run in different modes. By default it will configure vSwitch, +ViNePerf can be run in different modes. By default it will configure vSwitch, traffic generator and VNF. However it can be used just for configuration and execution of traffic generator. Another option is execution of all components except traffic generator itself. @@ -964,14 +964,14 @@ Mode of operation is driven by configuration parameter -m or --mode "trafficgen-off" - execute vSwitch and VNF "trafficgen-pause" - execute vSwitch and VNF but wait before traffic transmission -In case, that VSPERF is executed in "trafficgen" mode, then configuration +In case, that ViNePerf is executed in "trafficgen" mode, then configuration of traffic generator can be modified through ``TRAFFIC`` dictionary passed to the ``--test-params`` option. It is not needed to specify all values of ``TRAFFIC`` dictionary. It is sufficient to specify only values, which should be changed. Detailed description of ``TRAFFIC`` dictionary can be found at :ref:`configuration-of-traffic-dictionary`. -Example of execution of VSPERF in "trafficgen" mode: +Example of execution of ViNePerf in "trafficgen" mode: .. code-block:: console @@ -1014,7 +1014,7 @@ Example output: Code change verification by pylint ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Every developer participating in VSPERF project should run +Every developer participating in ViNePerf project should run pylint before his python code is submitted for review. Project specific configuration for pylint is available at 'pylint.rc'. diff --git a/docs/testing/user/userguide/trafficcapture.rst b/docs/testing/user/userguide/trafficcapture.rst index 8a224dcb..bc32f2ab 100644 --- a/docs/testing/user/userguide/trafficcapture.rst +++ b/docs/testing/user/userguide/trafficcapture.rst @@ -6,7 +6,7 @@ many of the functional tests. It allows the verification of functionality for both the vSwitch and the NICs using hardware acceleration for packet manipulation and modification. -There are three different methods of traffic capture supported by VSPERF. +There are three different methods of traffic capture supported by ViNePerf. Detailed descriptions of these methods as well as their pros and cons can be found in the following chapters. @@ -166,7 +166,7 @@ An example of Traffic Capture for testing NICs with HW offloading test: # The removal of VLAN headers is verified by inspection of captured frames. # # NOTE: This setup expects a DUT with two NICs with two ports each. First NIC is - # connected to the traffic generator (standard VSPERF setup). Ports of a second NIC + # connected to the traffic generator (standard ViNePerf setup). Ports of a second NIC # are interconnected by a patch cable. PCI addresses of all four ports have to be # properly configured in the WHITELIST_NICS parameter. { @@ -215,9 +215,9 @@ Traffic Capture on the Traffic Generator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using the functionality of the Traffic generator makes it possible to configure -Traffic Capture on both it's ports. With Traffic Capture enabled, VSPERF +Traffic Capture on both it's ports. With Traffic Capture enabled, ViNePerf instructs the Traffic Generator to automatically export captured data into -a pcap file. The captured packets are then sent to VSPERF for analysis and +a pcap file. The captured packets are then sent to ViNePerf for analysis and verification, monitoring any changes done by both vSwitch and the NICs. Vsperf currently only supports this functionality with the **T-Rex** generator. diff --git a/docs/testing/user/userguide/yardstick.rst b/docs/testing/user/userguide/yardstick.rst index b5e5c72d..35dfd1c9 100644 --- a/docs/testing/user/userguide/yardstick.rst +++ b/docs/testing/user/userguide/yardstick.rst @@ -2,7 +2,7 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, Intel Corporation, AT&T and others. -Execution of vswitchperf testcases by Yardstick +Execution of ViNePerf testcases by Yardstick ----------------------------------------------- General @@ -10,12 +10,12 @@ General Yardstick is a generic framework for a test execution, which is used for validation of installation of OPNFV platform. In the future, Yardstick will -support two options of vswitchperf testcase execution: +support two options of ViNePerf testcase execution: -- plugin mode, which will execute native vswitchperf testcases; Tests will +- plugin mode, which will execute native ViNePerf testcases; Tests will be executed natively by vsperf, and test results will be processed and reported by yardstick. -- traffic generator mode, which will run vswitchperf in **trafficgen** +- traffic generator mode, which will run ViNePerf in **trafficgen** mode only; Yardstick framework will be used to launch VNFs and to configure flows to ensure, that traffic is properly routed. This mode will allow to test OVS performance in real world scenarios. @@ -32,19 +32,19 @@ to install the yardstick. Please note, that yardstick uses OpenStack for execution of testcases. OpenStack must be installed with Heat and Neutron services. Otherwise -vswitchperf testcases cannot be executed. +ViNePerf testcases cannot be executed. -VM image with vswitchperf +VM image with ViNePerf ^^^^^^^^^^^^^^^^^^^^^^^^^ -A special VM image is required for execution of vswitchperf specific testcases +A special VM image is required for execution of ViNePerf specific testcases by yardstick. It is possible to use a sample VM image available at OPNFV artifactory or to build customized image. -Sample VM image with vswitchperf +Sample VM image with ViNePerf ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sample VM image is available at vswitchperf section of OPNFV artifactory +Sample VM image is available at ViNePerf section of OPNFV artifactory for free download: .. code-block:: console @@ -58,18 +58,18 @@ generator. This software is not included in the sample image and must be installed by user. **NOTE:** This image will be updated only in case, that new features related -to yardstick integration will be added to the vswitchperf. +to yardstick integration will be added to the ViNePerf. Preparation of custom VM image ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In general, any Linux distribution supported by vswitchperf can be used as -a base image for vswitchperf. One of the possibilities is to modify vloop-vnf +In general, any Linux distribution supported by ViNePerf can be used as +a base image for ViNePerf. One of the possibilities is to modify vloop-vnf image, which can be downloaded from `<http://artifacts.opnfv.org/vswitchperf.html/>`__ (see :ref:`vloop-vnf`). Please follow the :ref:`vsperf-installation` to -install vswitchperf inside vloop-vnf image. As vswitchperf will be run in +install ViNePerf inside vloop-vnf image. As ViNePerf will be run in trafficgen mode, it is possible to skip installation and compilation of OVS, QEMU and DPDK to keep image size smaller. @@ -80,8 +80,8 @@ of IXIA, you would need to install IxOS and IxNetowrk TCL API. VM image usage ~~~~~~~~~~~~~~ -Image with vswitchperf must be uploaded into the glance service and -vswitchperf specific flavor configured, e.g.: +Image with ViNePerf must be uploaded into the glance service and +ViNePerf specific flavor configured, e.g.: .. code-block:: console @@ -110,14 +110,14 @@ Next step is configuration of OpenStack environment, e.g. in case of devstack: source /opt/openstack/devstack/openrc export EXTERNAL_NETWORK=public -Vswitchperf testcases executable by yardstick are located at vswitchperf +ViNePerf testcases executable by yardstick are located at ViNePerf repository inside ``yardstick/tests`` directory. Example of their download and execution follows: .. code-block:: console - git clone https://gerrit.opnfv.org/gerrit/vswitchperf - cd vswitchperf + git clone https://gerrit.opnfv.org/gerrit/vineperf + cd vineperf yardstick -d task start yardstick/tests/rfc2544_throughput_dummy.yaml @@ -126,10 +126,10 @@ and execution follows: Testcase customization ^^^^^^^^^^^^^^^^^^^^^^ -Yardstick testcases are described by YAML files. vswitchperf specific testcases -are part of the vswitchperf repository and their yaml files can be found at +Yardstick testcases are described by YAML files. ViNePerf specific testcases +are part of the ViNePerf repository and their yaml files can be found at ``yardstick/tests`` directory. For detailed description of yaml file structure, -please see yardstick documentation and testcase samples. Only vswitchperf specific +please see yardstick documentation and testcase samples. Only ViNePerf specific parts will be discussed here. Example of yaml file: @@ -170,14 +170,14 @@ Example of yaml file: Section option ~~~~~~~~~~~~~~ -Section **option** defines details of vswitchperf test scenario. Lot of options -are identical to the vswitchperf parameters passed through ``--test-params`` +Section **option** defines details of ViNePerf test scenario. Lot of options +are identical to the ViNePerf parameters passed through ``--test-params`` argument. Following options are supported: - **frame_size** - a packet size for which test should be executed; Multiple packet sizes can be tested by modification of Sequence runner section inside YAML definition. Default: '64' -- **conf_file** - sets path to the vswitchperf configuration file, which will be +- **conf_file** - sets path to the ViNePerf configuration file, which will be uploaded to VM; Default: '~/vsperf-yardstick.conf' - **setup_script** - sets path to the setup script, which will be executed during setup and teardown phases @@ -192,7 +192,7 @@ argument. Following options are supported: Parameters should be stated in the form of ``param=value`` and separated by a semicolon. Configuration of traffic generator is driven by ``TRAFFIC`` dictionary, which can be also updated by values defined by ``test_params``. - Please check VSPERF documentation for details about available configuration + Please check ViNePerf documentation for details about available configuration parameters and their data types. In case that both **test_params** and **conf_file** are specified, then values from **test_params** will override values defined @@ -216,7 +216,7 @@ Section runner Yardstick supports several `runner types <http://artifacts.opnfv.org/yardstick/docs/userguide/architecture.html#runner-types>`__. -In case of vswitchperf specific TCs, **Sequence** runner type can be used to +In case of ViNePerf specific TCs, **Sequence** runner type can be used to execute the testcase for given list of frame sizes. @@ -226,7 +226,7 @@ Section sla In case that sla section is not defined, then testcase will be always considered as successful. On the other hand, it is possible to define a set of test metrics and their minimal values to evaluate test success. Any numeric -value, reported by vswitchperf inside CSV result file, can be used. +value, reported by ViNePerf inside CSV result file, can be used. Multiple metrics can be defined as a coma separated list of items. Minimal value must be set separately for each metric. |