fix split dox

3 files changed, 45 insertions, 215 deletions

diff --git a/trex_faq.asciidoc b/trex_faq.asciidoc
index 793f3372..15a9560f 100644
--- a/trex_faq.asciidoc
+++ b/trex_faq.asciidoc
@@ -203,7 +203,7 @@ This issue would be fixed when we consolidate ``Stateful'' and ``Stateless'' RPC
 TRex does not support ARP yet, you should configure the DUT to send the packets to the TRex port MAC address. From Stateless mode, you can change the port mode to promiscuous. +
 Also, revisit your MAC address configuration in the TRex config file. Wrong MAC address configuration will cause all packets to be dropped.
 
-==== Why is the performance low?
+==== Why the performance is low?
 
 TRex performance depends on many factors:
 
@@ -304,7 +304,7 @@ Yes. Multiple TRex clients can connect to the same TRex server.
 Yes. You can build any packet you like using Scapy. 
 However, there is no way to create corrupted L1 fields (Like Ethernet FCS), since these are usually handled by the NIC hardware.
 
-==== Why is the performance low?
+==== Why the performance is low?
 What would reduce the performance: 
 
 1. Many concurent streams.
diff --git a/trex_rpc_server_spec.asciidoc b/trex_rpc_server_spec.asciidoc
index 15bfc97f..e7c669ca 100755
--- a/trex_rpc_server_spec.asciidoc
+++ b/trex_rpc_server_spec.asciidoc
@@ -692,6 +692,45 @@ Any element in the array can be one of the following object types:
 | step        | uint64_t as string          | step, how much to inc or dec. 1 is the default (in case of 'random' this field is not used) 
 |=================
 
+
+===== repetable_random 
+
+Instruction to choose a limited number of random values from a big range  
+The values could be deterministic by providing seed 
+
+.Object type 'vm - flow_var'
+[options="header",cols="1,1,3"]
+|=================
+| Field       | Type                        | Description
+| type        | string                      | ''flow_var_rand_limit'''
+| name        | string                      | flow var name - this should be a unique identifier
+| size        | [1,2,4,8]                   | size of the var in bytes
+| limit       | uint64_t as string          | the number of values to choose 
+| seed        | uint64_t as string          | seed of the random, in case there is no seed time will be taken
+| min_value   | uint64_t as string          | minimum value for the field
+| max_value   | uint64_t as string          | maximum value for the field
+|=================
+
+
+an example of tuple_flow_var variable
+
+[source,bash]
+----
+ size       = 2 
+ limit      = 5
+ seed       = 0x1234
+ min_value  = 0
+ max_value  = 10
+----
+
+results could be
+
+[source,bash]
+----
+7 , 8, 1 ,5, 2 ,  7 , 8, 1 ,5, 2, 7 , 8, 1 ,5, 2
+----
+
+
 ===== write_flow_var
 
 .Object type 'vm - write_flow_var'
diff --git a/trex_stateless.asciidoc b/trex_stateless.asciidoc
index 4296b430..0b6ad8f7 100755
--- a/trex_stateless.asciidoc
+++ b/trex_stateless.asciidoc
@@ -2032,57 +2032,10 @@ This principal can be done for IPv6 too. ARP could be replaced with Neighbor Sol
  
 ==== Tutorial: Field Engine, split to core 
 
-The following example splits generated traffic into a number of threads. You can specify the field to use for determining how to split the traffic into threads. Without this feature, traffic is duplicated and all threads transmit the same traffic. (See the results tables in the examples below in this tutorial.)
+Post v2.08 version split to core directive was deprecated and was kept for backward compatibility.
+The new implementation is always to split as if the profile was sent from one core. 
+The user of TRex is oblivious to the number of cores. 
 
-*Without Split*::
-
-Scenario: 2 transmitters, DP threads
-
-[source,python]
-----
-    def create_stream (self):
-
-        # TCP SYN
-        base_pkt  = Ether()/IP(dst="48.0.0.1")/TCP(dport=80,flags="S")     
-
-
-        # vm
-        vm = STLScVmRaw( [ STLVmFlowVar(name="ip_src", 
-                                              min_value="16.0.0.0", 
-                                              max_value="16.0.0.254", 
-                                              size=4, op="inc"),                     <1>
-
-
-                           STLVmWrFlowVar(fv_name="ip_src", pkt_offset= "IP.src" ),  <2>
-
-                           STLVmFixIpv4(offset = "IP"), # fix checksum              
-                          ]
-
-                       )
-
-----
-<1> Define stream variable ip_src
-<2> Write stream variable we defined to `IPv4.src`.
-
-
-.Variable per thread 
-[format="csv",cols="1^,3^,3^", options="header",width="40%"]
-|=================
-pkt, thread-0 ip_src,thread-1 ip_src
- 1  , 16.0.0.1 , 16.0.0.1
- 2  , 16.0.0.2 , 16.0.0.2
- 3  , 16.0.0.3 , 16.0.0.3
- 4  , 16.0.0.4 , 16.0.0.4
- 5  , 16.0.0.5 , 16.0.0.5
- 6  , 16.0.0.6,  16.0.0.6
-|=================
-
-* In the case shown above, all threads transmit the same packets.
-
-
-*With Split feature enabled*::
-
-Scenario: 2 transmitters, DP threads
 
 [source,python]
 ----
@@ -2107,41 +2060,8 @@ Scenario: 2 transmitters, DP threads
                        )
 
 ----
-<1> Same example as previous, but split by the `ip_src` stream variable.
+<1> Deprecated split by field. not used any more (post v2.08)
 
-.Variable per thread 
-[format="csv",cols="1^,3^,3^", options="header",width="40%"]
-|=================
-pkt, thread-0 ip_src ,thread-1 ip_src
- 1  , 16.0.0.1 , 16.0.0.128
- 2  , 16.0.0.2 , 16.0.0.129
- 3  , 16.0.0.3 , 16.0.0.130
- 4  , 16.0.0.4 , 16.0.0.131
- 5  , 16.0.0.5 , 16.0.0.132
- 6  , 16.0.0.6,  16.0.0.133
-|=================
-
-* In this case the stream variable is split.
-
-To simulate this, using the `stl/udp_1pkt_range_clients_split.py` traffic profile, you can run the following command:
-
-[source,bash]
-----
-$./stl-sim -f stl/udp_1pkt_range_clients_split.py -o a.pcap -c 2 -l 10   #<1> 
-----
-<1> Simulates 2 threads as specified by the `-c 2` option.
-
-.Variable per thread 
-[format="csv",cols="1^,3^,3^", options="header",width="40%"]
-|=================
-pkt, thread-0 ip_src,thread-1 ip_src
- 1  , 55.55.0.1 , 55.55.58.153
- 2  , 55.55.0.2 , 55.55.58.154
- 3  , 55.55.0.3 , 55.55.58.155
- 4  , 55.55.0.4 , 55.55.58.156
- 5  , 55.55.0.5 , 55.55.58.157
- 6  , 55.55.0.6 , 55.55.58.158
-|=================
 
 *Some rules regarding split stream variables and burst/multi-burst*::
 
@@ -2149,135 +2069,6 @@ pkt, thread-0 ip_src,thread-1 ip_src
 * When the number of packets in a burst is smaller than the number of threads, one thread handles the burst. 
 * In the case of a stream with a burst of *1* packet, only the first DP thread handles the stream.
 
-==== Tutorial: Field Engine, Split to core with burst
-
-The following example splits generated traffic into a number of threads when using a stream configured to Burst. In contrast to the previous tutorial, this example uses the Burst pattern. As with the previous tutorial, the number of packets is split into multiple threads. In the example in this tutorial, the Field Engine is split also.
-
-*Without split feature enabled*::
-
-In this example:
-
-* Number of threads: 2
-* Split: Not configured 
-
-[source,python]
-----              
-# no split
-class STLS1(object):
-    """ attack 48.0.0.1 at port 80
-    """
-
-    def __init__ (self):
-        self.max_pkt_size_l3  =9*1024
-
-    def create_stream (self):
-
-        base_pkt  = Ether()/IP(dst="48.0.0.1")/TCP(dport=80,flags="S")
-
-        vm = STLScVmRaw( [ STLVmFlowVar(name="ip_src",                              <1>
-                                        min_value="16.0.0.0", 
-                                        max_value="18.0.0.254", 
-                                        size=4, op="inc"),
-
-                           STLVmWrFlowVar(fv_name="ip_src", pkt_offset= "IP.src" ), <2>
-
-                           STLVmFixIpv4(offset = "IP"), # fix checksum
-                          ]
-                       )
-
-        pkt = STLPktBuilder(pkt = base_pkt,
-                            vm = vm)
-
-        return STLStream(packet = pkt,
-                         mode = STLTXSingleBurst(total_pkts = 20))                  <3>
-
-----
-<1> Stream variable.
-<2> Writes it to `IPv4.src`.
-<3> Burst of 20 packets.
-
-.Variable per thread 
-[format="csv",cols="1^,3^,3^", options="header",width="40%"]
-|=================
-pkt, thread-0 ip_src,thread-1 ip_src
- 1  , 16.0.0.1 , 16.0.0.1
- 2  , 16.0.0.2 , 16.0.0.2
- 3  , 16.0.0.3 , 16.0.0.3
- 4  , 16.0.0.4 , 16.0.0.4
- 5  , 16.0.0.5 , 16.0.0.5
- 6  , 16.0.0.6,  16.0.0.6
- 7  , 16.0.0.7,  16.0.0.7
- 8  , 16.0.0.8,  16.0.0.8
- 9  , 16.0.0.9,  16.0.0.9
- 10 , 16.0.0.10, 16.0.0.10
-|=================
-
-*Results*::
-
-* Total packets are 20 as expected, 10 generated by each thread.
-* Field engine is the same for both threads.
-
-
-*With split feature enabled*::
-
-[source,python]
-----              
-class STLS1(object):
-    """ attack 48.0.0.1 at port 80
-    """
-
-    def __init__ (self):
-        self.max_pkt_size_l3  =9*1024
-
-    def create_stream (self):
-
-        base_pkt  = Ether()/IP(dst="48.0.0.1")/TCP(dport=80,flags="S")
-
-        vm = STLScVmRaw( [ STLVmFlowVar(name="ip_src",                              
-                                        min_value="16.0.0.0", 
-                                        max_value="18.0.0.254", 
-                                        size=4, op="inc"),
-
-                           STLVmWrFlowVar(fv_name="ip_src", pkt_offset= "IP.src" ), 
-
-                           STLVmFixIpv4(offset = "IP"), # fix checksum
-                          ]
-                         ,split_by_field = "ip_src"                                 <1>
-                          
-                       )
-
-        pkt = STLPktBuilder(pkt = base_pkt,
-                            vm = vm)
-
-        return STLStream(packet = pkt,
-                         mode = STLTXSingleBurst(total_pkts = 20))                  <2>
-
-----
-<1> Split is added by the `ip_src` stream variable.
-<2> Burst of 20 packets.
-
-
-.Variable per thread 
-[format="csv",cols="1^,3^,3^", options="header",width="40%"]
-|=================
-pkt, thread-0 ip_src,thread-1 ip_src
- 1  , 16.0.0.1 , 17.0.0.128
- 2  , 16.0.0.2 , 17.0.0.129
- 3  , 16.0.0.3 , 17.0.0.130
- 4  , 16.0.0.4 , 17.0.0.131
- 5  , 16.0.0.5 , 17.0.0.132
- 6  , 16.0.0.6,  17.0.0.133
- 7  , 16.0.0.7,  17.0.0.134
- 8  , 16.0.0.8,  17.0.0.135
- 9  , 16.0.0.9,  17.0.0.136
- 10 , 16.0.0.10, 17.0.0.137
-|=================
-
-*Results*::
-
-* Total packets are 20 as expected, 10 generated by each thread.
-* Field engine is *not* the same for both threads. 
-
 ==== Tutorial: Field Engine, Null stream 
 
 The following example creates a stream with no packets. The example uses the inter-stream gap (ISG) of the Null stream, and then starts a new stream. Essentially, this uses one property of the stream (ISG) without actually including packets in the stream.