Merge "traffic: Configurable traffic details"

7 files changed, 186 insertions, 71 deletions

diff --git a/docs/configguide/trafficgen.rst b/docs/configguide/trafficgen.rst
index 6d75a56f..e1eaf9f3 100644
--- a/docs/configguide/trafficgen.rst
+++ b/docs/configguide/trafficgen.rst
@@ -28,20 +28,27 @@ and configure the various traffic generators.
 
 Background Information
 ----------------------
-The traffic default configuration can be found in
-tools/pkt_gen/trafficgen/trafficgenhelper.py, and is configured as
-follows:
+The traffic default configuration can be found in **conf/03_traffic.conf**,
+and is configured as follows:
 
 .. code-block:: console
 
-    TRAFFIC_DEFAULTS = {
+    TRAFFIC = {
+        'traffic_type' : 'rfc2544_throughput',
+        'frame_rate' : 100,
+        'bidir' : 'True',  # will be passed as string in title format to tgen
+        'multistream' : 0,
+        'stream_type' : 'L4',
+        'pre_installed_flows' : 'No',           # used by vswitch implementation
+        'flow_type' : 'port',                   # used by vswitch implementation
+
         'l2': {
             'framesize': 64,
             'srcmac': '00:00:00:00:00:00',
             'dstmac': '00:00:00:00:00:00',
         },
         'l3': {
-            'proto': 'tcp',
+            'proto': 'udp',
             'srcip': '1.1.1.1',
             'dstip': '90.90.90.90',
         },
diff --git a/docs/design/trafficgen_integration_guide.rst b/docs/design/trafficgen_integration_guide.rst
index 9bb0e825..1457052b 100644
--- a/docs/design/trafficgen_integration_guide.rst
+++ b/docs/design/trafficgen_integration_guide.rst
@@ -81,29 +81,28 @@ Step 3 - configuration
 
 All configuration values, required for correct traffic generator function, are passed
 from VSPERF to the traffic generator in a dictionary. Default values shared among
-all traffic generators are defined in **tools/pkt_gen/trafficgen/trafficgenhelper.py**
-as **TRAFFIC_DEFAULTS** dictionary. Default values are loaded by **ITrafficGenerator**
-interface class automatically, so it is not needed to load them explicitly. In case
-that there are any traffic generator specific default values, then they should
-be set within class specific **__init__** function.
+all traffic generators are defined in **conf/03_traffic.conf** within **TRAFFIC**
+dictionary. Default values are loaded by **ITrafficGenerator** interface class
+automatically, so it is not needed to load them explicitly. In case that there are
+any traffic generator specific default values, then they should be set within class
+specific **__init__** function.
 
 VSPERF passes test specific configuration within **traffic** dictionary to every
 start and send function. So implementation of these functions must ensure,
 that default values are updated with the testcase specific values. Proper merge
-of values is assured by call of **merge_spec** function from **trafficgenhelper**
-module.
+of values is assured by call of **merge_spec** function from **conf** module.
 
 Example of **merge_spec** usage in **tools/pkt_gen/sample_tg/sample_tg.py** module:
 
 .. code-block:: python
 
-    from tools.pkt_gen.trafficgen.trafficgenhelper import merge_spec
+    from conf import merge_spec
 
     def start_rfc2544_throughput(self, traffic=None, duration=30):
         self._params = {}
         self._params['traffic'] = self.traffic_defaults.copy()
         if traffic:
-            self._params['traffic'] = trafficgen.merge_spec(
+            self._params['traffic'] = merge_spec(
                 self._params['traffic'], traffic)
 
 
@@ -199,8 +198,7 @@ functions:
         e.g. **rfc2544_throughput**, **rfc2544_continuous**
         or **rfc2544_back2back**.
       * param **frame_rate**: Defines desired percentage of frame
-        rate used during continuous stream tests. It can be set by test
-        parameter iLoad or by CLI parameter iload.
+        rate used during continuous stream tests.
       * param **bidir**: Specifies if generated traffic will be full-duplex
         (true) or half-duplex (false).
       * param **multistream**: Defines number of flows simulated by traffic
diff --git a/docs/design/vswitchperf_design.rst b/docs/design/vswitchperf_design.rst
index 4f33a99f..96b97631 100755
--- a/docs/design/vswitchperf_design.rst
+++ b/docs/design/vswitchperf_design.rst
@@ -263,6 +263,130 @@ a section in the ``conf\10_custom.conf`` file that can be used.
 
 .. _VSPERF installation scripts: http://artifacts.opnfv.org/vswitchperf/docs/configguide/installation.html#other-requirements
 
+Configuration of TRAFFIC dictionary
+-----------------------------------
+
+TRAFFIC dictionary is used for configuration of traffic generator. Default values
+can be found in configuration file ``conf/03_traffic.conf``. These default values
+can be modified by (first option has the highest priorty):
+
+    1. ``Parameters`` section of testcase defintion
+    2. command line options specified by ``--test-params`` argument
+    3. custom configuration file
+
+It is to note, that in case of option 1 and 2, it is possible to specify only
+values, which should be changed. In case of custom configuration file, it is
+required to specify whole ``TRAFFIC`` dictionary with its all values or explicitly
+call and update() method of ``TRAFFIC`` dictionary.
+
+Detailed description of ``TRAFFIC`` dictionary items follows:
+
+.. code-block:: console
+
+    'traffic_type'  - One of the supported traffic types.
+                      E.g. rfc2544_throughput, rfc2544_back2back
+                      or rfc2544_continuous
+                      Data type: str
+                      Default value: "rfc2544_throughput".
+    'bidir'         - Specifies if generated traffic will be full-duplex (True)
+                      or half-duplex (False)
+                      Data type: str
+                      Supported values: "True", "False"
+                      Default value: "False".
+    'frame_rate'    - Defines desired percentage of frame rate used during
+                      continuous stream tests.
+                      Data type: int
+                      Default value: 100.
+    'multistream'   - Defines number of flows simulated by traffic generator.
+                      Value 0 disables multistream feature
+                      Data type: int
+                      Supported values: 0-65535
+                      Default value: 0.
+    'stream_type'   - Stream type is an extension of the "multistream" feature.
+                      If multistream is disabled, then stream type will be
+                      ignored. Stream type defines ISO OSI network layer used
+                      for simulation of multiple streams.
+                      Data type: str
+                      Supported values:
+                         "L2" - iteration of destination MAC address
+                         "L3" - iteration of destination IP address
+                         "L4" - iteration of destination port
+                                of selected transport protocol
+                      Default value: "L4".
+    'pre_installed_flows'
+                   -  Pre-installed flows is an extension of the multistream"
+                      feature. If multistream is disabled, then pre-installed
+                      flows will be ignored. It defines if stream specific flows
+                      will be inserted into OVS or not.
+                      Data type: str
+                      Supported values:
+                         "Yes" - flows will be inserted into OVS
+                         "No"  - flows won't be inserted into OVS
+                      Default value: "No".
+    'flow_type'     - Defines flows complexity.
+                      Data type: str
+                      Supported values:
+                         "port" - flow is defined by ingress ports
+                         "IP"   - flow is defined by ingress ports
+                                  and src and dst IP addresses
+                      Default value: "port"
+    'l2'            - A dictionary with l2 network layer details. Supported
+                      values are:
+        'srcmac'    - Specifies source MAC address filled by traffic generator.
+                      NOTE: It can be modified by vsperf in some scenarios.
+                      Data type: str
+                      Default value: "00:00:00:00:00:00".
+        'dstmac'    - Specifies destination MAC address filled by traffic generator.
+                      NOTE: It can be modified by vsperf in some scenarios.
+                      Data type: str
+                      Default value: "00:00:00:00:00:00".
+        'framesize' - Specifies default frame size. This value should not be
+                      changed directly. It will be overridden during testcase
+                      execution by values specified by list TRAFFICGEN_PKT_SIZES.
+                      Data type: int
+                      Default value: 64
+    'l3'            - A dictionary with l3 network layer details. Supported
+                      values are:
+        'srcip'     - Specifies source MAC address filled by traffic generator.
+                      NOTE: It can be modified by vsperf in some scenarios.
+                      Data type: str
+                      Default value: "1.1.1.1".
+        'dstip'     - Specifies destination MAC address filled by traffic generator.
+                      NOTE: It can be modified by vsperf in some scenarios.
+                      Data type: str
+                      Default value: "90.90.90.90".
+        'proto'     - Specifies deflaut protocol type.
+                      Please check particular traffic generator implementation
+                      for supported protocol types.
+                      Data type: str
+                      Default value: "udp".
+    'l4'            - A dictionary with l4 network layer details. Supported
+                      values are:
+        'srcport'   - Specifies source port of selected transport protocol.
+                      NOTE: It can be modified by vsperf in some scenarios.
+                      Data type: int
+                      Default value: 3000
+        'dstport'   - Specifies destination port of selected transport protocol.
+                      NOTE: It can be modified by vsperf in some scenarios.
+                      Data type: int
+                      Default value: 3001
+    'vlan'          - A dictionary with vlan encapsulation details. Supported
+                      values are:
+        'enabled'   - Specifies if vlan encapsulation should be enabled or
+                      disabled.
+                      Data type: bool
+                      Default value: False
+        'id'        - Specifies vlan id.
+                      Data type: int (NOTE: must fit to 12 bits)
+                      Default value: 0
+        'priority'  - Specifies a vlan priority (PCP header field).
+                      Data type: int (NOTE: must fit to 3 bits)
+                      Default value: 0
+        'cfi'       - Specifies if frames can or cannot be dropped during
+                      congestion (DEI header field).
+                      Data type: int (NOTE: must fit to 1 bit)
+                      Default value: 0
+
 Configuration of GUEST options
 ------------------------------
 
diff --git a/docs/userguide/integration.rst b/docs/userguide/integration.rst
index 003e8adb..60ed9245 100755
--- a/docs/userguide/integration.rst
+++ b/docs/userguide/integration.rst
@@ -82,21 +82,21 @@ To run VXLAN encapsulation tests:
   .. code-block:: console
 
     ./vsperf --conf-file user_settings.py --integration \
-             --test-params 'tunnel_type=vxlan' overlay_p2p_tput
+             --test-params 'TUNNEL_TYPE=vxlan' overlay_p2p_tput
 
 To run GRE encapsulation tests:
 
   .. code-block:: console
 
     ./vsperf --conf-file user_settings.py --integration \
-             --test-params 'tunnel_type=gre' overlay_p2p_tput
+             --test-params 'TUNNEL_TYPE=gre' overlay_p2p_tput
 
 To run GENEVE encapsulation tests:
 
   .. code-block:: console
 
     ./vsperf --conf-file user_settings.py --integration \
-             --test-params 'tunnel_type=geneve' overlay_p2p_tput
+             --test-params 'TUNNEL_TYPE=geneve' overlay_p2p_tput
 
 To run OVS NATIVE tunnel tests (VXLAN/GRE/GENEVE):
 
@@ -128,7 +128,7 @@ To run OVS NATIVE tunnel tests (VXLAN/GRE/GENEVE):
   .. code-block:: console
 
     ./vsperf --conf-file user_settings.py --integration \
-             --test-params 'tunnel_type=vxlan' overlay_p2p_tput
+             --test-params 'TUNNEL_TYPE=vxlan' overlay_p2p_tput
 
 
 Executing VXLAN decapsulation tests
@@ -189,7 +189,7 @@ To run GRE decapsulation tests:
 
   .. code-block:: console
 
-    ./vsperf --conf-file user_settings.py --test-params 'tunnel_type=gre' \
+    ./vsperf --conf-file user_settings.py --test-params 'TUNNEL_TYPE=gre' \
              --integration overlay_p2p_decap_cont
 
 
diff --git a/docs/userguide/teststeps.rst b/docs/userguide/teststeps.rst
index 5e2d9570..5029f538 100644
--- a/docs/userguide/teststeps.rst
+++ b/docs/userguide/teststeps.rst
@@ -374,8 +374,12 @@ That is accomplished by using "Stream Type" and "MultiStream" keywords.
         "Name": "multistream_l4",
         "Description": "Multistream on UDP ports",
         "Deployment": "clean",
-        "Stream Type": "L4",
-        "MultiStream": 4,
+        "Parameters": {
+            'TRAFFIC' : {
+                "multistream": 4,
+                "stream_type": "L4",
+            },
+        },
         "TestSteps": [
             ['vswitch', 'add_switch', 'int_br0'],   # STEP 0
             ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1
@@ -542,8 +546,12 @@ destination UDP port.
         "Name": "ex_2pvp_rule_l4dp",
         "Description": "2 PVP with flows on L4 Dest Port",
         "Deployment": "clean",
-        "Stream Type": "L4",    # loop UDP ports
-        "MultiStream": 2,
+        "Parameters": {
+            'TRAFFIC' : {
+                "multistream": 2,
+                "stream_type": "L4",
+            },
+        },
         "TestSteps": [
             ['vswitch', 'add_switch', 'int_br0'],       # STEP 0
             ['vswitch', 'add_phy_port', 'int_br0'],     # STEP 1
@@ -622,12 +630,14 @@ and available in both csv and rst report files.
 
     {
         "Name": "pvvp_pvp_cont",
-        "Traffic Type": "continuous",
         "Deployment": "pvvp",
         "Description": "PVVP and PVP in parallel with Continuous Stream",
-        "biDirectional": "True",
-        "iLoad": "100",
-        "MultiStream": "2",
+        "Parameters" : {
+            "TRAFFIC" : {
+                "traffic_type" : "rfc2544_continuous",
+                "multistream": 2,
+            },
+        },
         "TestSteps": [
                         ['vswitch', 'add_vport', 'br0'],
                         ['vswitch', 'add_vport', 'br0'],
diff --git a/docs/userguide/testusage.rst b/docs/userguide/testusage.rst
index 379618d2..9a9a23c0 100755
--- a/docs/userguide/testusage.rst
+++ b/docs/userguide/testusage.rst
@@ -719,36 +719,19 @@ Mode of operation is driven by configuration parameter -m or --mode
             "trafficgen-pause" - execute vSwitch and VNF but wait before traffic transmission
 
 In case, that VSPERF is executed in "trafficgen" mode, then configuration
-of traffic generator should be configured through ``--test-params`` option.
-Supported CLI options useful for traffic generator configuration are:
-
-.. code-block:: console
-
-    'traffic_type'  - One of the supported traffic types. E.g.
-                      rfc2544_throughput,
-                      rfc2544_back2back or rfc2544_continuous
-                      Default value is "rfc2544_throughput".
-    'bidirectional' - Specifies if generated traffic will be full-duplex (true)
-                      or half-duplex (false)
-                      Default value is "false".
-    'iload'         - Defines desired percentage of frame rate used during
-                      continuous stream tests.
-                      Default value is 100.
-    'multistream'   - Defines number of flows simulated by traffic generator.
-                      Value 0 disables MultiStream feature
-                      Default value is 0.
-    'stream_type'   - Stream Type is an extension of the "MultiStream" feature.
-                      If MultiStream is disabled, then Stream Type will be
-                      ignored. Stream Type defines ISO OSI network layer used
-                      for simulation of multiple streams.
-                      Default value is "L4".
+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
+`Configuration of TRAFFIC dictionary
+<http://artifacts.opnfv.org/vswitchperf/docs/index.html#configuration-of-traffic-dictionary>`__
 
 Example of execution of VSPERF in "trafficgen" mode:
 
 .. code-block:: console
 
     $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf \
-        --test-params "traffic_type=rfc2544_continuous;bidirectional=True;iload=60"
+        --test-params "TRAFFIC={'traffic_type':'rfc2544_continuous','bidir':'False','framerate':60}"
 
 Code change verification by pylint
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/userguide/yardstick.rst b/docs/userguide/yardstick.rst
index 985a25ad..c906df8e 100755
--- a/docs/userguide/yardstick.rst
+++ b/docs/userguide/yardstick.rst
@@ -146,14 +146,10 @@ Example of yaml file:
       type: Vsperf
       options:
         testname: 'p2p_rfc2544_throughput'
-        traffic_type: 'rfc2544_throughput'
-        frame_size '64'
-        bidirectional: 'True'
-        iload: 100
         trafficgen_port1: 'eth1'
         trafficgen_port2: 'eth3'
         external_bridge: 'br-ex'
-        test_params: 'TRAFFICGEN_DURATION=30;'
+        test_params: 'TRAFFICGEN_DURATION=30;TRAFFIC={'traffic_type':'rfc2544_throughput}'
         conf_file: '~/vsperf-yardstick.conf'
 
       host: vsperf.demo
@@ -182,19 +178,9 @@ Section **option** defines details of vswitchperf test scenario. Lot of options
 are identical to the vswitchperf parameters passed through ``--test-params``
 argument. Following options are supported:
 
-- **traffic_type** - specifies the type of traffic executed by traffic generator;
-  Valid values are ``rfc2544_throughput``, ``rfc2544_continuous`` and ``rfc2544_back2back``.
-  Default: ``rfc2544_throughput``
 - **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'
-- **bidirectional** - specifies if traffic will be uni (False) or bi-directional
-  (True); Default: False
-- **iload** - specifies frame rate; Default: 100
-- **multistream** - specifies the number of simulated streams; Default: 0 (i.e.
-  multistream feature is disabled)
-- **stream_type** - specifies network layer used for multistream simulation
-  the valid values are "L4", "L3" and "L2"; Default: 'L4'
 - **conf_file** - sets path to the vswitchperf configuration file, which will be
   uploaded to VM; Default: '~/vsperf-yardstick.conf'
 - **setup_script** - sets path to the setup script, which will be executed
@@ -208,8 +194,10 @@ argument. Following options are supported:
 - **test_params** - specifies a string with a list of vsperf configuration
   parameters, which will be passed to the ``--test-params`` CLI argument;
   Parameters should be stated in the form of ``param=value`` and separated
-  by a semicolon. Please check VSPERF documentation for details about
-  available configuration parameters and their data types.
+  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
+  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
   in the configuration file.
@@ -220,7 +208,7 @@ expected, that OVS runs at the same node, where the testcase is executed. In cas
 of more complex OpenStack installation or a need of additional OVS configuration,
 **setup_script** can be used.
 
-Note: It is essential to specify a configuration for selected traffic generator.
+**NOTE** It is essential to specify a configuration for selected traffic generator.
 In case, that standalone testcase is created, then traffic generator can be
 selected and configured directly in YAML file by **test_params**. On the other
 hand, if multiple testcases should be executed with the same traffic generator
@@ -259,3 +247,8 @@ In case that any of defined metrics will be lower than defined value, then
 testcase will be marked as failed. Based on ``action`` policy, yardstick
 will either stop test execution (value ``assert``) or it will run next test
 (value ``monitor``).
+
+**NOTE** The throughput SLA (or any other SLA) cannot be set to a meaningful
+value without knowledge of the server and networking environment, possibly
+including prior testing in that environment to establish a baseline SLA level
+under well-understood circumstances.