enhanched tunable section

1 files changed, 133 insertions, 38 deletions

diff --git a/draft_trex_stateless.asciidoc b/draft_trex_stateless.asciidoc
index 6418f55f..1369f3e3 100644
--- a/draft_trex_stateless.asciidoc
+++ b/draft_trex_stateless.asciidoc
@@ -224,7 +224,7 @@ class STLS1(object):
              mode = STLTXCont())                                                        <2>
 
 
-    def get_streams (self, direction = 0):                                              <3>
+    def get_streams (self, direction = 0, **kwargs):                                              <3>
         # create 1 stream 
         return [ self.create_stream() ]
 
@@ -433,7 +433,7 @@ To solve this there is a way to use direction flag in the script
                     ),
              mode = STLTXCont())
 
-    def get_streams (self, direction = 0):
+    def get_streams (self, direction = 0, **kwargs):
         # create 1 stream 
         if direction==0:                                                        <1>
             src_ip="16.0.0.1"
@@ -917,7 +917,7 @@ class STLS1(object):
              mode = STLTXCont())                                                        <2>
 
 
-    def get_streams (self, direction = 0):
+    def get_streams (self, direction = 0, **kwargs):
         # create 1 stream 
         return [ self.create_stream() ]
 
@@ -1422,7 +1422,7 @@ This profile has 3 streams, each with different size packet. The rate is differe
                          mode = STLTXCont(pps = pps))
 
 
-    def get_streams (self, direction = 0):                                      <1>
+    def get_streams (self, direction = 0, **kwargs):                                      <1>
 
         if direction == 0:                                                      <2>
             src = self.ip_range['src']
@@ -2106,7 +2106,7 @@ There is an assumption that this pcap has one packet. In case it has more only t
 [source,python]
 ----
 
-    def get_streams (self, direction = 0):
+    def get_streams (self, direction = 0, **kwargs):
         return [STLStream(packet = 
                           STLPktBuilder(pkt ="stl/yaml/udp_64B_no_crc.pcap"), # path relative to pwd   <1>
                            mode = STLTXCont(pps=10)) ] 
@@ -2121,7 +2121,7 @@ There is an assumption that this pcap has one packet. In case it has more only t
 [source,python]
 ----
 
-    def get_streams (self, direction = 0):
+    def get_streams (self, direction = 0, **kwargs):
         return [STLStream(packet = STLPktBuilder(pkt ="yaml/udp_64B_no_crc.pcap",
                                                  path_relative_to_profile = True), <1>
                          mode = STLTXCont(pps=10)) ] 
@@ -2492,15 +2492,65 @@ value
  0x01 
 |=================
 
-==== Tutorial: Advance traffic profile - platform  [TODO]
+==== Tutorial: Advance traffic profile
+
+As said above, every traffic profile must define the following function:
+
+[source,python]
+----
+def get_streams (self, direction = 0, **kwargs)
+----
+
+'direction' is a mandatory field that will always be provided for any profile
+being loaded.
+
+Besides that, a profile can be provided with any key-value pairs which can be
+used to customize this profile - we call these 'tunables'.
+
+It is up to the profile to define which tunables it can accept and customize
+the output based on them.
+
+[NOTE] 
+=====================================================================
+All paramteres must be provided with default values. A profile must be loadable with no paramters.
+**kwargs contains all the automatically provided values which are not
+tunables.
+Every tuanble must be expressed as key-value pair with default value.
+=====================================================================
+
+
+For example,
+let's take a look at a profile called 'pcap_with_vm.py'
+
+*file*:: link:{github_stl_path}/pcap_with_vm.py[stl/pcap_with_vm.py]
+
+[source,python]
+----
+def get_streams (self,
+	         direction = 0,
+		 ipg_usec = 10.0,
+                 loop_count = 5,
+                 ip_src_range = None,
+                 ip_dst_range = {'start' : '10.0.0.1', 'end': '10.0.0.254'},
+                 **kwargs)
+----
+
+This profile gets 'direction' as a tunable and mandatory field.
+Define 4 more tunables which the profile decided about,
+And automatic values such as 'port_id' which are not tunables will be provided on kwargs.
 
 *Direction*::
+Direction is a tunable that will always be provided by the API/console when loading
+a profile, but it can be overriden by the user.
+It is used to make the traffic profile more usable such as bi-directional profile.
+However, a profile is free to ignore this parameter.
 
-To make the traffic profile more usable, the traffic profile support per direction/interface. 
+As default 'direction' will be equal to port_id % 2, so the *even* ports will be
+provided with ''0'' and the *odd* ones with ''1''.
 
 [source,python]
 ----
-def create_streams (self, direction = 0,**args):
+def get_streams (self, direction = 0,**kwargs):
     if direction = 0:
         rate =100                                       <1>
     else:    
@@ -2531,9 +2581,13 @@ interfaces 1/3 is direction 1
  
 So rate will be changed accordingly. 
 
-*Per Interface*::
- 
-In this case there is a different  profile base on interface ID 
+*Customzing Profiles Using ''port_id''*::
+
+**kwargs provide default values that are passed along to the profile.
+such a value is 'port_id' - which is the port ID for the profile.
+
+Using that you can define one can define a complex profile based
+on different ID of ports.
  
 [source,python]
 ----
@@ -2541,8 +2595,6 @@ In this case there is a different  profile base on interface ID
 def create_streams (self, direction = 0, **args):
 
     port_id = args.get('port_id')
-    if port_id==None:
-        port_id=0
 
     if port_id == 0:
      return [STLHltStream(tcp_src_port_mode = 'decrement',
@@ -2590,41 +2642,84 @@ def create_streams (self, direction = 0, **args):
          ..
 ----
  
-The Console will give the port/direction and will get the right stream in each interface
- 
+*Full example using the TRex Console*::
 
-*Tunable*::
- 
-[source,python]
+Let's take the previous pcap_with_vm.py and examine it with the console:
+
+[source,bash]
 ----
- 
-class STLS1(object):
+-=TRex Console v1.1=-
 
-    def __init__ (self):
-        self.num_clients  =30000 # max is 16bit  <1>
-        self.fsize        =64                     
+Type 'help' or '?' for supported actions
 
-    def create_stream (self):
+trex>profile -f stl/pcap_with_vm.py
 
-        # create a base packet and pad it to size
-        size = self.fsize - 4 # no FCS
-        base_pkt =  Ether(src="00:00:dd:dd:00:01")/IP(src="55.55.1.1",dst="58.0.0.1")/UDP(dport=12,sport=1025)
-        pad = max(0, size - len(base_pkt)) * 'x'
- 
+Profile Information:
+
+
+General Information:
+Filename:         stl/pcap_with_vm.py
+Stream count:          5
+
+Specific Information:
+Type:             Python Module
+Tunables:         ['direction = 0', 'ip_src_range = None', 'loop_count = 5', 'ipg_usec = 10.0',
+                   "ip_dst_range = {'start': '10.0.0.1', 'end': '10.0.0.254'}"]
+
+trex>                                                                                                                                                        
 ----
-<1> Define object args 
 
- 
+So we can provide tunables on all those fields.
+Let's change some:
+
 [source,bash]
 ----
-$start -f ex1.py -t "fsize=1500,num_clients=10000" #<1>
+trex>start -f stl/pcap_with_vm.py -t ipg_usec=15.0,loop_count=25
+
+Removing all streams from port(s) [0, 1, 2, 3]:              [SUCCESS]
+
+
+Attaching 5 streams to port(s) [0]:                          [SUCCESS]
+
+
+Attaching 5 streams to port(s) [1]:                          [SUCCESS]
+
+
+Attaching 5 streams to port(s) [2]:                          [SUCCESS]
+
+
+Attaching 5 streams to port(s) [3]:                          [SUCCESS]
+
+
+Starting traffic on port(s) [0, 1, 2, 3]:                    [SUCCESS]
+
+61.10 [ms]
+
+trex>
 ----
-<1> Change the Tunable using -t option
 
-Once a profile was defined, it is possible to give a tunable from Console and change the default value.
-In this example, change the fsize to 1500 bytes 
+[source,bash]
+----
+We can also customize these to different ports:
+
+trex>start -f stl/pcap_with_vm.py --port 0 1 -t ipg_usec=15.0,loop_count=25#ipg_usec=100,loop_count=300
+
+Removing all streams from port(s) [0, 1]:                    [SUCCESS]
 
 
+Attaching 5 streams to port(s) [0]:                          [SUCCESS]
+
+
+Attaching 5 streams to port(s) [1]:                          [SUCCESS]
+
+
+Starting traffic on port(s) [0, 1]:                          [SUCCESS]
+
+51.00 [ms]
+
+trex>
+----
+
 ==== Tutorial: Per stream statistics 
 
 * Per stream statistics is implemented using hardware assist when possible (X710/XL710 Intel NICs flow director rules for example).
@@ -2648,7 +2743,7 @@ In this example, change the fsize to 1500 bytes
 
 class STLS1(object):
 
-    def get_streams (self, direction = 0):
+    def get_streams (self, direction = 0, **kwargs):
         return [STLStream(packet = 
                           STLPktBuilder(
                           pkt ="stl/yaml/udp_64B_no_crc.pcap"), 
@@ -2710,7 +2805,7 @@ class STLS1(object):
                              )
                ]
 
-    def get_streams (self, direction = 0):
+    def get_streams (self, direction = 0, **kwargs):
         return self.create_streams()
 ----