Merge "This patch is used to update the documents of D-release."

1 files changed, 145 insertions, 67 deletions

diff --git a/docs/userguide/packet_forwarding.userguide.rst b/docs/userguide/packet_forwarding.userguide.rst
index ba117508c..594952bdf 100644
--- a/docs/userguide/packet_forwarding.userguide.rst
+++ b/docs/userguide/packet_forwarding.userguide.rst
@@ -5,14 +5,14 @@
 =================
 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
 ----------------
@@ -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                 |
-|       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               |
 +-----------------------------+---------------------------------------------------+
 
-======
 VSPERF
-======
+------
 
 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.`_
 
-.. _link.: <http://artifacts.opnfv.org/vswitchperf/colorado/index.html>
+.. _link.: http://artifacts.opnfv.org/vswitchperf/colorado/index.html
 
 
 Installation
-------------
+~~~~~~~~~~~~
+
 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
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * CentOS 7
 * Fedora 20
@@ -67,19 +68,21 @@ Supported Operating Systems
 * 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
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 * 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.
 
@@ -93,9 +96,9 @@ user account, which will be used for vsperf execution.
 
 Execution of installation script:
 
-.. code:: bashFtrace.debugging.tool.userguide.rst
+.. code:: bash
 
-    $ cd Vswitchperf
+    $ cd vswitchperf
     $ 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`_.
 
-.. _here: <http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html>
+.. _here: http://artifacts.opnfv.org/vswitchperf/colorado/configguide/index.html
 
 For CentOS 7
------------------
+~~~~~~~~~~~~~~
 
 ## Python 3 Packages
 
@@ -147,16 +150,16 @@ To activate, simple run:
 
 
 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
 
-   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/
@@ -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
--------------------
+------------------
+
 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:
 
@@ -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`_.
 
-.. _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
-==========
+----------
 
-=====================
 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
--------------
+~~~~~~~~~~~~
 
 Follow the [installation instructions] to install.
 
-IXIA Setup
-------------
 On the CentOS 7 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
-  - 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
 
@@ -261,7 +270,7 @@ Detailed description of options follows:
 .. _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
@@ -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.
- * Install cifs-utils package.
+
+* Install cifs-utils package.
 
    e.g. at rpm based Linux distribution:
 
-   .. code-block:: console
+.. code-block:: console
 
        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``
 
-   .. 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
@@ -308,6 +318,7 @@ is visible at DUT inside ``/mnt/ixia_results`` directory.
 
 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,
@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 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)
 
+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
 ~~~~~~~~~~~~~~~~
+
 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
-       --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:
 
@@ -393,6 +433,7 @@ For all available options, check out the help dialog:
 
 Testcases
 ----------
+
 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}"
 
 
-================================
 Packet Forwarding Test Scenarios
-================================
+--------------------------------
+
 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
--------------------------------
-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
 
-.. Figure:: ../images/Host_Scenario.png
+.. figure:: images/Host_Scenario.png
+   :name: Host_Scenario
+   :width: 100%
+   :align: center
 
 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
---------------------------------
-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
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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
--------------------
+~~~~~~~~~~~~~~~~~~~
 
 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.
 
+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: