Code Review / kvmfornfv.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | review | tree
raw | inline | side by side
This patch is used to update the documents of D-release.
[kvmfornfv.git] / docs / userguide / packet_forwarding.userguide.rst
diff --git a/docs/userguide/packet_forwarding.userguide.rst b/docs/userguide/packet_forwarding.userguide.rst
index ba11750..594952b 100644 (file)
--- a/docs/userguide/packet_forwarding.userguide.rst
+++ b/docs/userguide/packet_forwarding.userguide.rst
@@ -5,14 +5,14 @@
 =================
 PACKET FORWARDING
 =================
 =================
 PACKET FORWARDING
 =================
-=======================
+
 About Packet Forwarding
 About Packet Forwarding
-=======================
+-----------------------
 
 
-Packet Forwarding is a test suite of KVMFORNFV which is used to measure the total time taken by a
-**Packet** generated by the traffic generator to return from Guest/Host as per the implemented
-scenario. Packet Forwarding is implemented using VSWITCHPERF/``VSPERF software of OPNFV`` and an
-``IXIA Traffic Generator``.
+Packet Forwarding is a test suite of KVMFORNFV. These latency tests measures the time taken by a
+**Packet** generated by the traffic generator to travel from the originating device through the
+network to the destination device. Packet Forwarding is implemented using test framework
+implemented by OPNFV VSWITCHPERF project and an ``IXIA Traffic Generator``.
 
 Version Features
 ----------------
 
 Version Features
 ----------------
@@ -29,14 +29,14 @@ Version Features
 |                             | - Packet Forwarding is a testcase in KVMFORNFV    |
 |                             | - Implements three scenarios (Host/Guest/SRIOV)   |
 |                             |   as part of testing in KVMFORNFV                 |
 |                             | - Packet Forwarding is a testcase in KVMFORNFV    |
 |                             | - Implements three scenarios (Host/Guest/SRIOV)   |
 |                             |   as part of testing in KVMFORNFV                 |
-|       Danube                | - Uses available testcases of OPNFV's VSWTICHPERF |
-|                             |   software (PVP/PVVP)                             |
+|       Danube                | - Uses automated test framework of OPNFV          |
+|                             |    VSWITCHPERF software (PVP/PVVP)                |
+|                             |                                                   |
 |                             | - Works with IXIA Traffic Generator               |
 +-----------------------------+---------------------------------------------------+
 
 |                             | - Works with IXIA Traffic Generator               |
 +-----------------------------+---------------------------------------------------+
 
-======
 VSPERF
 VSPERF
-======
+------
 
 VSPerf is an OPNFV testing project.
 VSPerf will develop a generic and architecture agnostic vSwitch testing framework and associated
 
 VSPerf is an OPNFV testing project.
 VSPerf will develop a generic and architecture agnostic vSwitch testing framework and associated
@@ -47,17 +47,18 @@ VNF level testing and validation.
 
 For complete VSPERF documentation go to `link.`_
 
 
 For complete VSPERF documentation go to `link.`_
 
-.. _link.: <http://artifacts.opnfv.org/vswitchperf/colorado/index.html>
+.. _link.: http://artifacts.opnfv.org/vswitchperf/colorado/index.html
 
 
 Installation
 
 
 Installation
-------------
+~~~~~~~~~~~~
+
 Guidelines of installating `VSPERF`_.
 
 Guidelines of installating `VSPERF`_.
 
-.. _VSPERF: <http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html>
+.. _VSPERF: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html
 
 Supported Operating Systems
 
 Supported Operating Systems
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * CentOS 7
 * Fedora 20
 
 * CentOS 7
 * Fedora 20
@@ -67,19 +68,21 @@ Supported Operating Systems
 * Ubuntu 14.04
 
 Supported vSwitches
 * Ubuntu 14.04
 
 Supported vSwitches
--------------------
+~~~~~~~~~~~~~~~~~~~
+
 The vSwitch must support Open Flow 1.3 or greater.
 
 * OVS (built from source).
 * OVS with DPDK (built from source).
 
 Supported Hypervisors
 The vSwitch must support Open Flow 1.3 or greater.
 
 * OVS (built from source).
 * OVS with DPDK (built from source).
 
 Supported Hypervisors
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 * Qemu version 2.3.
 
 Other Requirements
 
 * Qemu version 2.3.
 
 Other Requirements
-------------------
+~~~~~~~~~~~~~~~~~~
+
 The test suite requires Python 3.3 and relies on a number of other
 packages. These need to be installed for the test suite to function.
 
 The test suite requires Python 3.3 and relies on a number of other
 packages. These need to be installed for the test suite to function.
 
@@ -93,9 +96,9 @@ user account, which will be used for vsperf execution.
 
 Execution of installation script:
 
 
 Execution of installation script:
 
-.. code:: bashFtrace.debugging.tool.userguide.rst
+.. code:: bash
 
 
-    $ cd Vswitchperf
+    $ cd vswitchperf
     $ cd systems
     $ ./build_base_machine.sh
 
     $ cd systems
     $ ./build_base_machine.sh
 
@@ -115,10 +118,10 @@ For running testcases VSPERF is installed on Intel pod1-node2 in which centos
 operating system is installed. Only VSPERF installion on Centos is discussed here.
 For installation steps on other operating systems please refer to `here`_.
 
 operating system is installed. Only VSPERF installion on Centos is discussed here.
 For installation steps on other operating systems please refer to `here`_.
 
-.. _here: <http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html>
+.. _here: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html
 
 For CentOS 7
 
 For CentOS 7
------------------
+~~~~~~~~~~~~~~
 
 ## Python 3 Packages
 
 
 ## Python 3 Packages
 
@@ -147,16 +150,16 @@ To activate, simple run:
 
 
 Working Behind a Proxy
 
 
 Working Behind a Proxy
------------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 If you're behind a proxy, you'll likely want to configure this before running any of the above. For example:
 
 .. code:: bash
 
 
 If you're behind a proxy, you'll likely want to configure this before running any of the above. For example:
 
 .. code:: bash
 
-   export http_proxy=proxy.mycompany.com:123
-   export https_proxy=proxy.mycompany.com:123
-
-
+   export http_proxy="http://<username>:<password>@<proxy>:<port>/";
+   export https_proxy="https://<username>:<password>@<proxy>:<port>/";
+   export ftp_proxy="ftp://<username>:<password>@<proxy>:<port>/";
+   export socks_proxy="socks://<username>:<password>@<proxy>:<port>/";
 
 .. _a link: http://www.softwarecollections.org/en/scls/rhscl/python33/
 .. _virtualenv: https://virtualenv.readthedocs.org/en/latest/
 
 .. _a link: http://www.softwarecollections.org/en/scls/rhscl/python33/
 .. _virtualenv: https://virtualenv.readthedocs.org/en/latest/
@@ -166,10 +169,11 @@ For other OS specific activation click `this link`_:
 .. _this link: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/installation.html#other-requirements
 
 Traffic-Generators
 .. _this link: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/installation.html#other-requirements
 
 Traffic-Generators
--------------------
+------------------
+
 VSPERF supports many Traffic-generators. For configuring VSPERF to work with the available traffic-generator go through `this`_.
 
 VSPERF supports many Traffic-generators. For configuring VSPERF to work with the available traffic-generator go through `this`_.
 
-.. _this: <http://artifacts.opnfv.org/vswitchperf/colorado/configguide/trafficgen.html>
+.. _this: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/trafficgen.html
 
 VSPERF supports the following traffic generators:
 
 
 VSPERF supports the following traffic generators:
 
@@ -191,35 +195,40 @@ and configure the various traffic generators.
 
 As KVM4NFV uses only IXIA traffic generator, it is discussed here. For complete documentation regarding traffic generators please follow this `link`_.
 
 
 As KVM4NFV uses only IXIA traffic generator, it is discussed here. For complete documentation regarding traffic generators please follow this `link`_.
 
-.. _link: <https://gerrit.opnfv.org/gerrit/gitweb?p=vswitchperf.git;a=blob;f=docs/configguide/trafficgen.rst;h=85fc35b886d30db3b92a6b7dcce7ca742b70cbdc;hb=HEAD>
+.. _link: https://gerrit.opnfv.org/gerrit/gitweb?p=vswitchperf.git;a=blob;f=docs/configguide/trafficgen.rst;h=85fc35b886d30db3b92a6b7dcce7ca742b70cbdc;hb=HEAD
 
 
-==========
 IXIA Setup
 IXIA Setup
-==========
+----------
 
 
-=====================
 Hardware Requirements
 Hardware Requirements
-=====================
-VSPERF requires the following hardware to run tests: IXIA traffic generator (IxNetwork), a machine that runs the IXIA client software and a CentOS Linux release 7.1.1503 (Core) host.
+~~~~~~~~~~~~~~~~~~~~~
+
+VSPERF requires the following hardware to run tests: IXIA traffic generator (IxNetwork), a machine that
+runs the IXIA client software and a CentOS Linux release 7.1.1503 (Core) host.
 
 Installation
 
 Installation
--------------
+~~~~~~~~~~~~
 
 Follow the [installation instructions] to install.
 
 
 Follow the [installation instructions] to install.
 
-IXIA Setup
-------------
 On the CentOS 7 system
 On the CentOS 7 system
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
+
 You need to install IxNetworkTclClient$(VER_NUM)Linux.bin.tgz.
 
 On the IXIA client software system
 You need to install IxNetworkTclClient$(VER_NUM)Linux.bin.tgz.
 
 On the IXIA client software system
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Find the IxNetwork TCL server app (start -> All Programs -> IXIA -> IxNetwork -> IxNetwork_$(VER_NUM) -> IxNetwork TCL Server)
   - Right click on IxNetwork TCL Server, select properties
 Find the IxNetwork TCL server app (start -> All Programs -> IXIA -> IxNetwork -> IxNetwork_$(VER_NUM) -> IxNetwork TCL Server)
   - Right click on IxNetwork TCL Server, select properties
-  - Under shortcut tab in the Target dialogue box make sure there is the argument "-tclport xxxx" where xxxx is your port number (take note of this port number you will need it for the 10_custom.conf file).
+  - Under shortcut tab in the Target dialogue box make sure there is the argument "-tclport xxxx"
+
+where xxxx is your port number (take note of this port number you will need it for the 10_custom.conf file).
 
 
-.. Figure:: ../images/IXIA1.png
+.. figure:: images/IXIA1.png
+   :name: IXIA1 setup
+   :width: 100%
+   :align: center
 
 - Hit Ok and start the TCL server application
 
 
 - Hit Ok and start the TCL server application
 
@@ -261,7 +270,7 @@ Detailed description of options follows:
 .. _test-results-share:
 
 Test results share
 .. _test-results-share:
 
 Test results share
--------------------
+~~~~~~~~~~~~~~~~~~
 
 VSPERF is not able to retrieve test results via TCL API directly. Instead, all test
 results are stored at IxNetwork TCL server. Results are stored at folder defined by
 
 VSPERF is not able to retrieve test results via TCL API directly. Instead, all test
 results are stored at IxNetwork TCL server. Results are stored at folder defined by
@@ -285,19 +294,20 @@ Example of sharing configuration:
 
    Note: It is essential to use slashes '/' also in path
    configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter.
 
    Note: It is essential to use slashes '/' also in path
    configured by ``TRAFFICGEN_IXNET_TESTER_RESULT_DIR`` parameter.
- * Install cifs-utils package.
+
+* Install cifs-utils package.
 
    e.g. at rpm based Linux distribution:
 
 
    e.g. at rpm based Linux distribution:
 
-   .. code-block:: console
+.. code-block:: console
 
        yum install cifs-utils
 
 
        yum install cifs-utils
 
- * Mount shared directory, so VSPERF can access test results.
+* Mount shared directory, so VSPERF can access test results.
 
    e.g. by adding new record into ``/etc/fstab``
 
 
    e.g. by adding new record into ``/etc/fstab``
 
-   .. code-block:: console
+.. code-block:: console
 
        mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results
              -o file_mode=0777,dir_mode=0777,nounix
 
        mount -t cifs //_TCL_SERVER_IP_OR_FQDN_/ixia_results /mnt/ixia_results
              -o file_mode=0777,dir_mode=0777,nounix
@@ -308,6 +318,7 @@ is visible at DUT inside ``/mnt/ixia_results`` directory.
 
 Cloning and building src dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Cloning and building src dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 In order to run VSPERF, 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 on,
 In order to run VSPERF, 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 on,
@@ -326,13 +337,16 @@ To delete a src subdirectory and its contents to allow you to re-clone simply us
 
 Configure the `./conf/10_custom.conf` file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Configure the `./conf/10_custom.conf` file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The supplied `10_custom.conf` file must be modified, as it contains configuration items for which there are no reasonable default values.
 
 The supplied `10_custom.conf` file must be modified, as it contains configuration items for which there are no reasonable default values.
 
-The configuration items that can be added is not limited to the initial contents. Any configuration item mentioned in any .conf file in `./conf` directory can be added and that item will be overridden by the custom
+The configuration items that can be added is not limited to the initial contents. Any configuration item
+mentioned in any .conf file in `./conf` directory can be added and that item will be overridden by the custom
 configuration value.
 
 Using a custom settings file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 configuration value.
 
 Using a custom settings file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Alternatively a custom settings file can be passed to `vsperf` via the `--conf-file` argument.
 
 .. code:: bash
 Alternatively a custom settings file can be passed to `vsperf` via the `--conf-file` argument.
 
 .. code:: bash
@@ -347,8 +361,34 @@ argument will override both the default and your custom configuration files. Thi
 2. Environment variables
 3. Configuration file(s)
 
 2. Environment variables
 3. Configuration file(s)
 
+vloop_vnf
+~~~~~~~~~
+
+VSPERF 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/>`__.
+
+Please see the installation instructions for information on :ref:`vloop-vnf`
+images.
+
+.. _l2fwd-module:
+
+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
+
+.. figure:: images/Guest_Scenario.png
+   :name: Guest_Scenario
+   :width: 100%
+   :align: center
+
+
 Executing tests
 ~~~~~~~~~~~~~~~~
 Executing tests
 ~~~~~~~~~~~~~~~~
+
 Before running any tests make sure you have root permissions by adding the following line to /etc/sudoers:
 .. code:: bash
 
 Before running any tests make sure you have root permissions by adding the following line to /etc/sudoers:
 .. code:: bash
 
@@ -382,7 +422,7 @@ Some tests allow for configurable parameters, including test duration (in second
 
    ./vsperf --conf-file user_settings.py
        --tests RFC2544Tput
 
    ./vsperf --conf-file user_settings.py
        --tests RFC2544Tput
-       --test-param "rfc2544_duration=10;packet_sizes=128"
+       --test-param` "rfc2544_duration=10;packet_sizes=128"
 
 For all available options, check out the help dialog:
 
 
 For all available options, check out the help dialog:
 
@@ -393,6 +433,7 @@ For all available options, check out the help dialog:
 
 Testcases
 ----------
 
 Testcases
 ----------
+
 Available Tests in VSPERF are:
 
    * phy2phy_tput
 Available Tests in VSPERF are:
 
    * phy2phy_tput
@@ -444,9 +485,9 @@ Example of execution of VSPERF in "trafficgen" mode:
         --test-params "TRAFFIC={'traffic_type':'rfc2544_continuous','bidir':'False','framerate':60}"
 
 
         --test-params "TRAFFIC={'traffic_type':'rfc2544_continuous','bidir':'False','framerate':60}"
 
 
-================================
 Packet Forwarding Test Scenarios
 Packet Forwarding Test Scenarios
-================================
+--------------------------------
+
 KVMFORNFV currently implements three scenarios as part of testing:
 
   * Host Scenario
 KVMFORNFV currently implements three scenarios as part of testing:
 
   * Host Scenario
@@ -455,32 +496,47 @@ KVMFORNFV currently implements three scenarios as part of testing:
 
 
 Packet Forwarding Host Scenario
 
 
 Packet Forwarding Host Scenario
--------------------------------
-Here Host is NODE-2. It has VSPERF installed in it and is properly configured to use IXIA Traffic-generator by providing IXIA CARD, PORTS and Lib paths along with IP.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here host DUT has VSPERF installed in it and is properly configured to use IXIA Traffic-generator
+by providing IXIA CARD, PORTS and Lib paths along with IP.
 please refer to figure.2
 
 please refer to figure.2
 
-.. Figure:: ../images/Host_Scenario.png
+.. figure:: images/Host_Scenario.png
+   :name: Host_Scenario
+   :width: 100%
+   :align: center
 
 Packet Forwarding Guest Scenario
 
 Packet Forwarding Guest Scenario
---------------------------------
-Here the guest is a Virtual Machine (VM) launched by using a modified CentOS image(vsperf provided)
-on Node-2 (Host) using  Qemu. In this scenario, the packet is initially forwarded to Host which is
-then forwarded to the launched guest. The time taken by the packet to reach the IXIA traffic-generator
-via Host and Guest is calculated and published as a test result of this scenario.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
-.. Figure:: ../images/Guest_Scenario.png
+Here the guest is a Virtual Machine (VM) launched by using vloop_vnf provided by vsperf project
+on host/DUT using Qemu. In this latency test the time taken by the frame/packet to travel from the
+originating device through network involving a guest to destination device is calculated.
+The resulting latency values will define the performance of installed kernel.
+
+.. figure:: images/Guest_Scenario.png
+   :name: Guest_Scenario
+   :width: 100%
+   :align: center
 
 Packet Forwarding SRIOV Scenario
 
 Packet Forwarding SRIOV Scenario
---------------------------------
-Unlike the packet forwarding to Guest-via-Host scenario, here the packet generated at the IXIA is
-directly forwarded to the Guest VM launched on Host by implementing SR-IOV interface at NIC level
-of Host .i.e., Node-2. The time taken by the packet to reach the IXIA traffic-generator is calculated
-and published as a test result for this scenario. SRIOV-support_ is given below, it details how to use SR-IOV.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this test the packet generated at the IXIA is forwarded to the Guest VM launched on Host by
+implementing SR-IOV interface at NIC level of host .i.e., DUT. The time taken by the packet to
+travel through the network to the destination the IXIA traffic-generator is calculated and
+published as a test result for this scenario.
 
 
-.. Figure:: ../images/SRIOV_Scenario.png
+SRIOV-support_ is given below, it details how to use SR-IOV.
+
+.. figure:: images/SRIOV_Scenario.png
+   :name: SRIOV_Scenario
+   :width: 100%
+   :align: center
 
 Using vfio_pci with DPDK
 
 Using vfio_pci with DPDK
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To use vfio with DPDK instead of igb_uio add into your custom configuration
 file the following parameter:
 
 To use vfio with DPDK instead of igb_uio add into your custom configuration
 file the following parameter:
@@ -521,7 +577,7 @@ To check that IOMMU is enabled on your platform:
 .. _SRIOV-support:
 
 Using SRIOV support
 .. _SRIOV-support:
 
 Using SRIOV support
--------------------
+~~~~~~~~~~~~~~~~~~~
 
 To use virtual functions of NIC with SRIOV support, use extended form
 of NIC PCI slot definition:
 
 To use virtual functions of NIC with SRIOV support, use extended form
 of NIC PCI slot definition:
@@ -553,3 +609,25 @@ For example:
 * tests without vSwitch, where VM accesses VF interfaces directly
   by PCI-passthrough to measure raw VM throughput performance.
 
 * tests without vSwitch, where VM accesses VF interfaces directly
   by PCI-passthrough to measure raw VM throughput performance.
 
+Using QEMU with PCI passthrough support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Raw virtual machine throughput performance can be measured by execution of PVP
+test with direct access to NICs by PCI passthrough. To execute VM with direct
+access to PCI devices, enable vfio-pci_. In order to use virtual functions,
+SRIOV-support_ must be enabled.
+
+Execution of test with PCI passthrough with vswitch disabled:
+
+.. code-block:: console
+
+    $ ./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
+PCI passthrough support.
+
+Note: Qemu with PCI passthrough support can be used only with PVP test
+deployment.
+
+.. _guest-loopback-application: