docs: update userguides after reviewing

Review and update userguides for Release B.
JIRA: VSPERF-160

Change-Id: I54c4dd37fa5951cab9d0e17bb2f3a4d273741cb0
Signed-off-by: Maryam Tahhan <maryam.tahhan@intel.com>

3 files changed, 136 insertions, 105 deletions

diff --git a/docs/userguides/installation.rst b/docs/userguides/installation.rst
index 96970bdb..bd47519a 100755
--- a/docs/userguides/installation.rst
+++ b/docs/userguides/installation.rst
@@ -17,21 +17,26 @@ Execution of installation script:
 
 .. code:: bash
 
-    cd systems
-    ./build_base_machine.sh
+    $ cd systems
+    $ ./build_base_machine.sh
 
 Please note: you don't need to go into any of the systems subdirectories,
 simply run the top level build_base_machine.sh, your OS will be detected
 automatically.
 
+build_base_machine.sh will install all the vsperf dependencies in terms of
+system packages and Python modules, it will also use `virtualenv`_ to create a
+vsperf virtual environment that's isolated from the default Python env. This
+environment will reside in a directory called vsperfenv in $HOME.
+
 You will need to activate the virtual environment every time you start a
 new shell session. To activate, simple run:
 
 .. code:: bash
 
-    scl enable python33 bash
-    cd $HOME/vsperfenv
-    source bin/activate
+    $ scl enable python33 bash
+    $ cd $HOME/vsperfenv
+    $ source bin/activate
 
 --------------
 
@@ -47,3 +52,4 @@ running any of the above. For example:
     export https_proxy=proxy.mycompany.com:123
 
 .. _a link: http://www.softwarecollections.org/en/scls/rhscl/python33/
+.. _virtualenv: https://virtualenv.readthedocs.org/en/latest/
diff --git a/docs/userguides/quickstart.rst b/docs/userguides/quickstart.rst
index 91162f88..e93a040f 100755
--- a/docs/userguides/quickstart.rst
+++ b/docs/userguides/quickstart.rst
@@ -2,66 +2,90 @@
 Getting Started with 'vsperf'
 =============================
 
-Hardware Requirements
----------------------
+Requirements
+-------------
 
-VSPERF requires one of the following traffic generators to run tests:
+VSPERF requires a traffic generators to run tests, automated traffic gen
+support in VSPERF includes:
 
-- IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA client software
-- Spirent traffic generator (TestCenter hardware chassis or TestCenter virtual in a VM) and a
-  VM to run the Spirent Virtual Deployment Service image, formerly known as "Spirent LabServer".
+- IXIA traffic generator (IxNetwork hardware) and a machine that runs the IXIA
+  client software.
+- Spirent traffic generator (TestCenter hardware chassis or TestCenter virtual
+  in a VM) and a VM to run the Spirent Virtual Deployment Service image,
+  formerly known as "Spirent LabServer".
 
-Both test configurations, above, also require a CentOS Linux release 7.1.1503 (Core) host.
+If you want to use another traffic generator, please select the Dummy generator
+option as shown in `Traffic generator instructions
+<http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/trafficgen.html>`__
+
+Supported OSes include:
+
+* CentOS Linux release 7.1.1503 (Core) host.
+* Fedora 21 and 22.
+* Ubuntu 14.04
 
 vSwitch Requirements
 --------------------
 
-The vSwitch must support Open Flow 1.3 or greater.
+The vSwitch must support Open Flow 1.3 or greater. VSPERF supports both:
 
-Installation
-------------
+* OVS
+* OVS with DPDK
 
-Follow the `installation instructions <http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/index.html>`__ to install.
+VSPERF Installation
+--------------------
+
+Follow the `installation instructions
+<http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/index.html>`__ to
+install.
 
 Traffic Generator Setup
 -----------------------
-Follow the `Traffic generator instructions <http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/trafficgen.html>`__ to install and configure a suitable traffic generator.
+Follow the `Traffic generator instructions
+<http://artifacts.opnfv.org/vswitchperf/docs/docs/guides/trafficgen.html>`__ to
+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
-do this manually and build them in a preferred location, or you could
+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, such as DPDK and OVS. To clone and build simply:
 
-  .. code-block:: console
+.. code-block:: console
+
+    $ cd src
+    $ make
 
-    cd src
-    make
+VSPERF can be used with stock OVS (without DPDK support). In this case you have
+to specify path to the kernel sources when building OVS in src by specifying
+WITH\_LINUX parameter:
 
-VSPERF can be used with OVS without DPDK support. In this case you have
-to specify path to the kernel sources by WITH\_LINUX parameter:
+.. code-block:: console
 
-  .. code-block:: console
+     $ cd src
+     $ make WITH_LINUX=/lib/modules/`uname -r`/build
 
-     cd src
-     make WITH_LINUX=/lib/modules/`uname -r`/build
+To build DPDK and OVS in the src directory for PVP and PVVP testing with
+vhost_user as the guest access method, use:
 
-To build DPDK and OVS for PVP and PVVP testing with vhost_user as the guest
-access method, use:
+.. code-block:: console
 
-  .. code-block:: console
+     $ make VHOST_USER=y
 
-     make VHOST_USER=y
+To build all options in src:
 
-To build everything: Vanilla OVS, OVS with vhost_user as the guest access
-method and OVS with vhost_cuse access simply:
+* Vanilla OVS
+* OVS with vhost_user as the guest access method (with DPDK support)
+* OVS with vhost_cuse s the guest access method (with DPDK support)
 
-  .. code-block:: console
+simply call 'make' in the src directory :
 
-     make
+.. code-block:: console
+
+     $ make
 
 The vhost_user build will reside in src/ovs/
 The vhost_cuse build will reside in vswitchperf/src_cuse
@@ -70,15 +94,15 @@ The Vanilla OVS build will reside in vswitchperf/src_vanilla
 To delete a src subdirectory and its contents to allow you to re-clone simply
 use:
 
-  .. code-block:: console
+.. code-block:: console
 
-     make clobber
+     $ make clobber
 
 Configure the ``./conf/10_custom.conf`` file
 --------------------------------------------
 The ``10_custom.conf`` file is the configuration file that overrides
 default configurations in all the other configuration files in ``./conf``
-The supplied ``10_custom.conf`` file must be modified, as it contains
+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
@@ -93,9 +117,9 @@ If your ``10_custom.conf`` doesn't reside in the ``./conf`` directory
 of if you want to use an alternative configuration file, the file can
 be passed to ``vsperf`` via the ``--conf-file`` argument.
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --conf-file <path_to_settings_py> ...
+    $ ./vsperf --conf-file <path_to_custom_conf> ...
 
 Note that configuration passed in via the environment (``--load-env``)
 or via another command line argument will override both the default and
@@ -114,7 +138,7 @@ Executing tests
 Before running any tests make sure you have root permissions by adding
 the following line to /etc/sudoers:
 
-  .. code-block:: console
+.. code-block:: console
 
     username ALL=(ALL)       NOPASSWD: ALL
 
@@ -122,45 +146,45 @@ username in the example above should be replaced with a real username.
 
 To list the available tests:
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --list
+    $ ./vsperf --list
 
 To run a single test:
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf $TESTNAME
+    $ ./vsperf $TESTNAME
 
 Where $TESTNAME is the name of the vsperf test you would like to run.
 
 To run a group of tests, for example all tests with a name containing
 'RFC2544':
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --conf-file=user_settings.py --tests="RFC2544"
+    $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests="RFC2544"
 
 To run all tests:
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --conf-file=user_settings.py
+    $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
 
 Some tests allow for configurable parameters, including test duration
 (in seconds) as well as packet sizes (in bytes).
 
 .. code:: bash
 
-    ./vsperf --conf-file user_settings.py
+    $ ./vsperf --conf-file user_settings.py
         --tests RFC2544Tput
         --test-param "duration=10;pkt_sizes=128"
 
 For all available options, check out the help dialog:
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --help
+    $ ./vsperf --help
 
 Executing Vanilla OVS tests
 ----------------------------
@@ -169,16 +193,16 @@ step 1.
 
 1. Recompile src for Vanilla OVS testing
 
-  .. code-block:: console
+.. code-block:: console
 
-     cd src
-     make cleanse
-     make WITH_LINUX=/lib/modules/`uname -r`/build
+     $ cd src
+     $ make cleanse
+     $ make WITH_LINUX=/lib/modules/`uname -r`/build
 
 2. Update your ''10_custom.conf'' file to use the appropriate variables
 for Vanilla OVS:
 
-  .. code-block:: console
+.. code-block:: console
 
    VSWITCH = 'OvsVanilla'
    VSWITCH_VANILLA_PHY_PORT_NAMES = ['$PORT1', '$PORT1']
@@ -188,17 +212,17 @@ to the vswitch.
 
 3. Run test:
 
-  .. code-block:: console
+.. code-block:: console
 
-     ./vsperf --conf-file <path_to_settings_py>
+     $ ./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.
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --vswitch OvsVanilla
+    $ ./vsperf --vswitch OvsVanilla
 
 
 Executing PVP and PVVP tests
@@ -207,47 +231,47 @@ 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:: console
 
    VHOST_METHOD='user'
    VNF = 'QemuDpdkVhost'
 
 2. Recompile src for VHOST USER testing
 
-  .. code-block:: console
+.. code-block:: console
 
-     cd src
-     make cleanse
-     make VHOST_USER=y
+     $ cd src
+     $ make cleanse
+     $ make VHOST_USER=y
 
 3. Run test:
 
-  .. code-block:: console
+.. code-block:: console
 
-     ./vsperf --conf-file <path_to_settings_py>
+     $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
 
 To run tests using vhost-cuse as guest access method:
 
 1. Set VHOST_METHOD and VNF of your settings file to:
 
-  .. code-block:: console
+.. code-block:: console
 
      VHOST_METHOD='cuse'
      VNF = 'QemuDpdkVhostCuse'
 
 2. Recompile src for VHOST USER testing
 
-  .. code-block:: console
+.. code-block:: console
 
-     cd src
-     make cleanse
-     make VHOST_USER=n
+     $ cd src
+     $ make cleanse
+     $ make VHOST_USER=n
 
 3. Run test:
 
-  .. code-block:: console
+.. code-block:: console
 
-     ./vsperf --conf-file <path_to_settings_py>
+     $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
 
 Executing PVP tests using Vanilla OVS
 -------------------------------------
@@ -255,7 +279,7 @@ To run tests using Vanilla OVS:
 
 1. Set the following variables:
 
-  .. code-block:: console
+.. code-block:: console
 
    VSWITCH = 'OvsVanilla'
    VNF = 'QemuVirtioNet'
@@ -270,42 +294,44 @@ To run tests using Vanilla OVS:
 
    or use --test-param
 
-   ./vsperf --conf-file user_settings.py
+   ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
             --test-param "vanilla_tgen_tx_ip=n.n.n.n;
                           vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn"
 
 
 2. Recompile src for Vanilla OVS testing
 
-  .. code-block:: console
+.. code-block:: console
 
-     cd src
-     make cleanse
-     make WITH_LINUX=/lib/modules/`uname -r`/build
+     $ cd src
+     $ make cleanse
+     $ make WITH_LINUX=/lib/modules/`uname -r`/build
 
 3. Run test:
 
-  .. code-block:: console
+.. code-block:: console
 
-     ./vsperf --conf-file <path_to_settings_py>
+     $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf
 
 Selection of loopback application for PVP and PVVP tests
 --------------------------------------------------------
 To select loopback application, which will perform traffic forwarding
 inside VM, following configuration parameter should be configured:
 
-  .. code-block:: console
+.. code-block:: console
 
      GUEST_LOOPBACK = ['testpmd', 'testpmd']
 
-     or use --test-param
+or use --test-param
+
+.. code-block:: console
 
-     ./vsperf --conf-file user_settings.py
+        $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf
               --test-param "guest_loopback=testpmd"
 
 Supported loopback applications are:
 
-  .. code-block:: console
+.. code-block:: console
 
      'testpmd'       - testpmd from dpdk will be built and used
      'l2fwd'         - l2fwd module provided by Huawei will be built and used
@@ -325,9 +351,9 @@ specific configuration for pylint is available at 'pylint.rc'.
 
 Example of manual pylint invocation:
 
-  .. code-block:: console
+.. code-block:: console
 
-          pylint --rcfile ./pylintrc ./vsperf
+          $ pylint --rcfile ./pylintrc ./vsperf
 
 GOTCHAs:
 --------
@@ -339,17 +365,16 @@ If you encounter the following error: "before (last 100 chars):
 hugepages: Cannot allocate memory\r\n\r\n" with the PVP or PVVP
 deployment scenario, check the amount of hugepages on your system:
 
-.. code:: bash
+.. code-block:: console
 
-    cat /proc/meminfo | grep HugePages
+    $ cat /proc/meminfo | grep HugePages
 
 
 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:: bash
+.. code-block:: console
 
     VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0']
 
-
diff --git a/docs/userguides/trafficgen.rst b/docs/userguides/trafficgen.rst
index 1bb09103..f510a596 100644
--- a/docs/userguides/trafficgen.rst
+++ b/docs/userguides/trafficgen.rst
@@ -13,9 +13,9 @@ VSPERF supports the following traffic generators:
 
 To see the list of traffic gens from the cli:
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --list-trafficgens
+    $ ./vsperf --list-trafficgens
 
 This guide provides the details of how to install
 and configure the various traffic generators.
@@ -26,7 +26,7 @@ The traffic default configuration can be found in
 tools/pkt_gen/trafficgen/trafficgenhelper.py, and is configured as
 follows:
 
-  .. code-block:: console
+.. code-block:: console
 
     TRAFFIC_DEFAULTS = {
         'l2': {
@@ -53,23 +53,23 @@ The framesize paramter can be overridden from the configuration
 files by adding the following to your custom configuration file
 ``10_custom.conf``:
 
-  .. code-block:: console
+.. code-block:: console
 
     TRAFFICGEN_PKT_SIZES = (64, 128,)
 
 OR from the commandline:
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --test-param "pkt_sizes=x,y" $TESTNAME
+    $ ./vsperf --test-param "pkt_sizes=x,y" $TESTNAME
 
 You can also modify the traffic transmission duration and the number
 of trials run by the traffic generator by extending the example
 commandline above to:
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --test-param "pkt_sizes=x,y;duration=10;rfc2455_trials=3" $TESTNAME
+    $ ./vsperf --test-param "pkt_sizes=x,y;duration=10;rfc2455_trials=3" $TESTNAME
 
 Dummy Setup
 ------------
@@ -77,22 +77,22 @@ To select the Dummy generator please add the following to your
 custom configuration file ``10_custom.conf``.
 
 
-  .. code-block:: console
+.. code-block:: console
 
      TRAFFICGEN = 'Dummy'
 
 OR run ``vsperf`` with the ``--trafficgen`` argument
 
-  .. code-block:: console
+.. code-block:: console
 
-    ./vsperf --trafficgen Dummy $TESTNAME
+    $ ./vsperf --trafficgen Dummy $TESTNAME
 
 Where $TESTNAME is the name of the vsperf test you would like to run.
 This will setup the vSwitch and the VNF (if one is part of your test)
 print the traffic configuration and prompt you to transmit traffic
 when the setup is complete.
 
-  .. code-block:: console
+.. code-block:: console
 
     Please send 'continuous' traffic with the following stream config:
     30mS, 90mpps, multistream False
@@ -128,7 +128,7 @@ When your traffic gen has completed traffic transmission and provided
 the results please input these at the vsperf prompt. vsperf will try
 to verify the input:
 
-  .. code-block:: console
+.. code-block:: console
 
     Is '$input_value' correct?