X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Ftesting%2Fuser%2Fuserguide%2Ftestusage.rst;h=4d3528d060ea4e6ad8119d65bbd2e7fa00c7215f;hb=01455386f7186721ffd7578d95a84580a5ff7087;hp=c6037aaffa056344d9f29b93aabfddb20f8bcbc8;hpb=b757c8ba94b9d8664808a39d7517a11651cc0188;p=vswitchperf.git

diff --git a/docs/testing/user/userguide/testusage.rst b/docs/testing/user/userguide/testusage.rst
index c6037aaf..4d3528d0 100644
--- a/docs/testing/user/userguide/testusage.rst
+++ b/docs/testing/user/userguide/testusage.rst
@@ -112,6 +112,32 @@ of options with ``GUEST_`` prefix could be found at :ref:`design document
 
 .. _overriding-parameters-documentation:
 
+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.
+It can be used to reflect DUT HW details in the testcase definition.
+
+Example:
+
+.. code:: python
+
+    {
+        ...
+        "Name": "testcase",
+        "Parameters" : {
+            "TRAFFIC" : {
+                'l2': {
+                    # set destination MAC to the MAC of the first
+                    # interface from WHITELIST_NICS list
+                    'dstmac' : '#PARAM(NICS[0]["mac"])',
+                },
+            },
+        ...
+
 Overriding values defined in configuration files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -270,7 +296,7 @@ Executing tests with VMs
 
 To run tests using vhost-user as guest access method:
 
-1. Set VHOST_METHOD and VNF of your settings file to:
+1. Set VSWITCH and VNF of your settings file to:
 
    .. code-block:: python
 
@@ -291,6 +317,10 @@ To run tests using vhost-user as guest access method:
 
        $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
 
+**NOTE:** By default vSwitch is acting as a server for dpdk vhost-user sockets.
+In case, that QEMU should be a server for vhost-user sockets, then parameter
+``VSWITCH_VHOSTUSER_SERVER_MODE`` should be set to ``False``.
+
 Executing tests with VMs using Vanilla OVS
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -393,6 +423,10 @@ set ``PATHS['dpdk']['bin']['modules']`` instead.
 **NOTE:** Please ensure your boot/grub parameters include
 the following:
 
+**NOTE:** In case of VPP, it is required to explicitly define, that vfio-pci
+DPDK driver should be used. It means to update dpdk part of VSWITCH_VPP_ARGS
+dictionary with uio-driver section, e.g. VSWITCH_VPP_ARGS['dpdk'] = 'uio-driver vfio-pci'
+
 .. code-block:: console
 
     iommu=pt intel_iommu=on
@@ -566,6 +600,46 @@ Note: vfio_no_iommu requires kernels equal to or greater than 4.5 and dpdk
 Please refer to the dpdk documents at http://dpdk.org/doc/guides for more
 information on these drivers.
 
+Guest Core and Thread Binding
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+VSPERF 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.
+
+
+.. code-block:: python
+
+   GUEST_CORE_BINDING = [('#EVAL(6+2*#VMINDEX)', '#EVAL(7+2*#VMINDEX)')]
+
+**NOTE** By default the GUEST_THREAD_BINDING will be none, which means same as
+the GUEST_CORE_BINDING, i.e. the vcpu threads are sharing the physical CPUs with
+the house keeping threads. Better performance using vCPU thread binding can be
+achieved by enabling affinity in the custom configuration file.
+
+For example, if an environment requires 32,33 to be core binded and 29,30&31 for
+guest thread binding to achieve better performance.
+
+.. code-block:: python
+
+   VNF_AFFINITIZATION_ON = True
+   GUEST_CORE_BINDING = [('32','33')]
+   GUEST_THREAD_BINDING = [('29', '30', '31')]
+
+Qemu CPU features
+^^^^^^^^^^^^^^^^^
+
+QEMU default to a compatible subset of performance enhancing cpu features.
+To pass all available host processor features to the guest.
+
+.. code-block:: python
+
+   GUEST_CPU_OPTIONS = ['host,migratable=off']
+
+**NOTE** To enhance the performance, cpu features tsc deadline timer for guest,
+the guest PMU, the invariant TSC can be provided in the custom configuration file.
+
 Multi-Queue Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -645,6 +719,65 @@ environment.
 on the same numa as the NIC in use if possible/applicable. Testpmd should be
 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
+NIC and traffic generator for the following vswitches:
+
+1.  OVSVanilla
+
+2.  OvsDpdkVhostUser
+
+3.  TestPMD loopback with or without a guest
+
+**NOTE:** There is currently no support for SR-IOV or VPP at this time with jumbo
+frames.
+
+All packet forwarding applications for pxp testing is supported.
+
+To enable jumbo frame testing simply enable the option in the conf files and set the
+maximum size that will be used.
+
+.. code-block:: python
+
+    VSWITCH_JUMBO_FRAMES_ENABLED = True
+    VSWITCH_JUMBO_FRAMES_SIZE = 9000
+
+To enable jumbo frame testing with OVSVanilla the NIC in test on the host must have
+its mtu size changed manually using ifconfig or applicable tools:
+
+.. code-block:: console
+
+    ifconfig eth1 mtu 9000 up
+
+**NOTE:** To make the setting consistent across reboots you should reference the OS
+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.
+
+.. code-block:: python
+
+    TEST_PARAMS = {'TRAFFICGEN_PKT_SIZES':(2000,9000)}
+
+.. code-block:: python
+
+    ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=2000,9000"
+
+It is recommended to increase the memory size for OvsDpdkVhostUser testing from the default
+1024. Your size required may vary depending on the number of guests in your testing. 4096
+appears to work well for most typical testing scenarios.
+
+.. code-block:: python
+
+    DPDK_SOCKET_MEM = ['4096', '0']
+
+**NOTE:** For Jumbo frames to work with DpdkVhostUser, mergable buffers will be enabled by
+default. If testing with mergable buffers in QEMU is desired, disable Jumbo Frames and only
+test non jumbo frame sizes. Test Jumbo Frames sizes separately to avoid this collision.
+
+
 Executing Packet Forwarding tests
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^