some cleanup for API doc

5 files changed, 339 insertions, 6 deletions

diff --git a/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst b/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst
index 29d524e1..bc9d521a 100644
--- a/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst
+++ b/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst
@@ -1,6 +1,6 @@
 
-Module documentation
-================================
+TRex Client Module 
+==================
 
 TRex Client is an object to access TRex server. It is per user. Each user can own number of interfaces. 
 Multi user can interact with one TRex server each user should own a different set of interfaces.
@@ -11,6 +11,31 @@ The API has two type of API
 1. Normal API 
 2. xx_line:  this api get a line like the Console and parse it and call the low level api 
 
+Example1::
+
+    c = STLClient()
+
+    try:
+        # connect to server
+        c.connect()
+
+        # prepare our ports (my machine has 0 <--> 1 with static route)
+        c.reset(ports = [0, 1])
+
+        # add both streams to ports
+        c.add_streams(s1, ports = [0])
+
+        # clear the stats before injecting
+        c.clear_stats()
+
+        c.start(ports = [0, 1], mult = "5mpps", duration = 10)
+
+        # block until done
+        c.wait_on_traffic(ports = [0, 1])
+
+    finally:
+        c.disconnect()
+
 
 STLClient class
 ---------------
@@ -125,7 +150,7 @@ Example3: Console like::
 
 Example4: Load profile from a file::
 
-def simple ():
+  def simple ():
 
     # create client
     #verbose_level = LoggerApi.VERBOSE_HIGH
diff --git a/scripts/automation/trex_control_plane/doc_stl/api/field_engine.rst b/scripts/automation/trex_control_plane/doc_stl/api/field_engine.rst
new file mode 100644
index 00000000..271ff058
--- /dev/null
+++ b/scripts/automation/trex_control_plane/doc_stl/api/field_engine.rst
@@ -0,0 +1,164 @@
+
+Field Engine modules 
+=======================
+
+The Field Engine (FE) has limited number of instructions/operation for supporting most use cases. 
+There is a plan to add LuaJIT to be more flexible at the cost of performance.
+The FE can allocate stream variables in a Stream context, write a stream variable to a packet offset, change packet size,  etc.
+
+*Some examples for what can be done:*
+
+* Change ipv4.tos 1-10
+* Change packet size to be random in the range 64-9K
+* Create range of flows (change src_ip, dest_ip, src_port, dest_port) 
+* Update IPv4 checksum 
+
+
+for example this snippet will create SYN Attack::
+
+    # create attack from random src_ip from 16.0.0.0-18.0.0.254 and random src_port 1025-65000    
+    # attack 48.0.0.1 server 
+        
+    def create_stream (self):
+
+        
+        # TCP SYN
+        base_pkt  = Ether()/IP(dst="48.0.0.1")/TCP(dport=80,flags="S")
+
+
+        # vm
+        vm = CTRexScRaw( [ STLVmFlowVar(name="ip_src", 
+                                              min_value="16.0.0.0", 
+                                              max_value="18.0.0.254", 
+                                              size=4, op="random"),
+
+                            STLVmFlowVar(name="src_port", 
+                                              min_value=1025, 
+                                              max_value=65000, 
+                                              size=2, op="random"),
+
+                           STLVmWrFlowVar(fv_name="ip_src", pkt_offset= "IP.src" ),
+
+                           STLVmFixIpv4(offset = "IP"), # fix checksum
+
+                           STLVmWrFlowVar(fv_name="src_port", 
+                                                pkt_offset= "TCP.sport") # fix udp len  
+
+                          ]
+                       )
+
+        pkt = STLPktBuilder(pkt = base_pkt,
+                            vm = vm)
+
+        return STLStream(packet = pkt,
+                         random_seed = 0x1234,# can be remove. will give the same random value any run
+                         mode = STLTXCont())
+
+
+
+
+CTRexScRaw class
+----------------
+
+Aggregate a raw instructions objects 
+
+.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexScRaw
+    :members: 
+    :member-order: bysource
+
+
+STLVmFlowVar 
+------------
+
+It is alias for CTRexVmDescFlowVar
+
+.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescFlowVar
+    :members: 
+    :member-order: bysource
+
+STLVmWrMaskFlowVar
+------------------
+
+It is alias for CTRexVmDescWrMaskFlowVar
+
+.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescWrMaskFlowVar
+    :members: 
+    :member-order: bysource
+
+STLVmFixIpv4
+------------------
+
+It is alias for CTRexVmDescFixIpv4
+
+.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescFixIpv4
+    :members: 
+    :member-order: bysource
+ 
+
+STLVmTrimPktSize
+------------------
+
+It is alias for CTRexVmDescTrimPktSize
+
+.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescTrimPktSize
+    :members: 
+    :member-order: bysource
+
+STLVmTupleGen
+------------------
+
+It is alias for CTRexVmDescTupleGen
+
+.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescTupleGen
+    :members: 
+    :member-order: bysource
+
+STLVmTupleGen
+------------------
+
+It is alias for STLVmTupleGen
+
+.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.CTRexVmDescTupleGen
+    :members: 
+    :member-order: bysource
+
+  
+
+Field Engine snippet
+--------------------
+
+Example1:: 
+
+
+        base_pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)
+
+        pad = max(0, size - len(base_pkt)) * 'x'
+                             
+        vm = CTRexScRaw( [   STLVmTupleGen ( ip_min="16.0.0.1", ip_max="16.0.0.2", 
+                                                   port_min=1025, port_max=65535,
+                                                    name="tuple"), # define tuple gen 
+
+                             STLVmWrFlowVar (fv_name="tuple.ip", pkt_offset= "IP.src" ), # write ip to packet IP.src
+                             STLVmFixIpv4(offset = "IP"),                                # fix checksum
+                             STLVmWrFlowVar (fv_name="tuple.port", pkt_offset= "UDP.sport" )  #write udp.port
+                                  ]
+                              );
+
+        pkt = STLPktBuilder(pkt = base_pkt/pad,
+                            vm = vm)
+
+        
+
+Example2::
+
+        #range of source mac-addr
+
+        base_pkt =  Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)
+        pad = max(0, size - len(base_pkt)) * 'x'
+
+        vm = CTRexScRaw( [ STLVmFlowVar(name="mac_src", min_value=1, max_value=30, size=2, op="dec",step=1), 
+                           STLVmWrMaskFlowVar(fv_name="mac_src", pkt_offset= 11,pkt_cast_size=1, mask=0xff) 
+                          ]
+                       )
+
+
diff --git a/scripts/automation/trex_control_plane/doc_stl/api/index.rst b/scripts/automation/trex_control_plane/doc_stl/api/index.rst
index 4e4be230..733a896d 100644
--- a/scripts/automation/trex_control_plane/doc_stl/api/index.rst
+++ b/scripts/automation/trex_control_plane/doc_stl/api/index.rst
@@ -2,12 +2,28 @@
 TRex Stateless API Reference
 ============================
 
-**TRex Modules**
+**TRex Client: STLClient**
 
 .. toctree::
     :maxdepth: 4
     
     client_code
 
-**TRex JSON Template**
+**TRex Traffic profile: STLProfile,STLStream **
+
+.. toctree::
+    :maxdepth: 4
+    
+    profile_code
+
+
+**TRex Field Engine: **
+
+.. toctree::
+    :maxdepth: 4
+    
+    field_engine
+    
+
+
 
diff --git a/scripts/automation/trex_control_plane/doc_stl/api/profile_code.rst b/scripts/automation/trex_control_plane/doc_stl/api/profile_code.rst
new file mode 100644
index 00000000..9484f565
--- /dev/null
+++ b/scripts/automation/trex_control_plane/doc_stl/api/profile_code.rst
@@ -0,0 +1,128 @@
+
+Traffic profile modules 
+=======================
+
+TRex STLProfile profile include a list of STLStream. The profile is a ``program`` of streams with a relation betwean the streams.
+Each stream can trigger another stream. Stream can be given a name for a full examples see here Manual_.
+
+..   _Manual: ../draft_trex_stateless1.html
+
+
+for example::
+
+    def create_stream (self):
+
+        # create a base packet and pad it to size
+        size = self.fsize - 4; # no FCS
+        base_pkt =  Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)
+        base_pkt1 =  Ether()/IP(src="16.0.0.2",dst="48.0.0.1")/UDP(dport=12,sport=1025)
+        base_pkt2 =  Ether()/IP(src="16.0.0.3",dst="48.0.0.1")/UDP(dport=12,sport=1025)
+        pad = max(0, size - len(base_pkt)) * 'x'
+
+
+        return STLProfile( [ STLStream( isg = 1.0, # star in delay in usec 
+                                        packet = STLPktBuilder(pkt = base_pkt/pad),
+                                        mode = STLTXCont( pps = 10),
+                                        ), 
+
+                             STLStream( isg = 2.0,
+                                        packet  = STLPktBuilder(pkt = base_pkt1/pad),
+                                        mode    = STLTXCont( pps = 20),
+                                        ),
+
+                             STLStream(  isg = 3.0,
+                                         packet = STLPktBuilder(pkt = base_pkt2/pad),
+                                         mode    = STLTXCont( pps = 30)
+                                         
+                                        )
+                            ]).get_streams()
+
+
+STLProfile class
+----------------
+
+.. autoclass:: trex_stl_lib.trex_stl_streams.STLProfile
+    :members: 
+    :member-order: bysource
+
+STLStream 
+---------
+
+.. autoclass:: trex_stl_lib.trex_stl_streams.STLStream
+    :members: 
+    :member-order: bysource
+    
+
+STLStream modes
+----------------
+
+.. autoclass:: trex_stl_lib.trex_stl_streams.STLTXMode
+    :members: 
+    :member-order: bysource
+
+.. autoclass:: trex_stl_lib.trex_stl_streams.STLTXCont
+    :members: 
+    :member-order: bysource
+
+.. autoclass:: trex_stl_lib.trex_stl_streams.STLTXSingleBurst
+    :members: 
+    :member-order: bysource
+
+.. autoclass:: trex_stl_lib.trex_stl_streams.STLTXMultiBurst
+    :members: 
+    :member-order: bysource
+
+.. autoclass:: trex_stl_lib.trex_stl_streams.STLFlowStats
+    :members: 
+    :member-order: bysource
+
+
+STLProfile snippet
+------------------
+
+
+Example1::
+
+        size = self.fsize - 4; # no FCS
+        base_pkt =  Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)
+        base_pkt1 =  Ether()/IP(src="16.0.0.2",dst="48.0.0.1")/UDP(dport=12,sport=1025)
+        base_pkt2 =  Ether()/IP(src="16.0.0.3",dst="48.0.0.1")/UDP(dport=12,sport=1025)
+        pad = max(0, size - len(base_pkt)) * 'x'
+
+
+        return STLProfile( [ STLStream( isg = 10.0, # star in delay 
+                                        name    ='S0',
+                                        packet = STLPktBuilder(pkt = base_pkt/pad),
+                                        mode = STLTXSingleBurst( pps = 10, total_pkts = 10),
+                                        next = 'S1'), # point to next stream 
+
+                             STLStream( self_start = False, # stream is  disabled enable trow S0
+                                        name    ='S1',
+                                        packet  = STLPktBuilder(pkt = base_pkt1/pad),
+                                        mode    = STLTXSingleBurst( pps = 10, total_pkts = 20),
+                                        next    = 'S2' ),
+
+                             STLStream(  self_start = False, # stream is  disabled enable trow S0
+                                         name   ='S2',
+                                         packet = STLPktBuilder(pkt = base_pkt2/pad),
+                                         mode = STLTXSingleBurst( pps = 10, total_pkts = 30 )
+                                        )
+                            ]).get_streams()
+
+
+Example2:: 
+
+        class STLS1(object):
+        
+            def get_streams (self, direction = 0):
+                return [STLStream(packet = STLPktBuilder(pkt ="stl/yaml/udp_64B_no_crc.pcap"), 
+                                  mode = STLTXCont(pps=1000),
+                                  flow_stats = STLFlowStats(pg_id = 7)),
+        
+                        STLStream(packet = STLPktBuilder(pkt ="stl/yaml/udp_594B_no_crc.pcap"),
+                                  mode = STLTXCont(pps=5000),
+                                  flow_stats = STLFlowStats(pg_id = 12))
+                       ]
+        
+
+
diff --git a/scripts/automation/trex_control_plane/doc_stl/index.rst b/scripts/automation/trex_control_plane/doc_stl/index.rst
index 5437f1f9..b8a1a8e5 100644
--- a/scripts/automation/trex_control_plane/doc_stl/index.rst
+++ b/scripts/automation/trex_control_plane/doc_stl/index.rst
@@ -16,7 +16,7 @@ How to Install
 .. toctree::
     :maxdepth: 2
 
-* TODO[]
+* **TODO**
         
 
 API Reference