diff options
6 files changed, 191 insertions, 55 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 bc9d521a..16a00122 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 @@ -13,7 +13,7 @@ The API has two type of API Example1:: - c = STLClient() + c = STLClient(username = "itay",server = "10.0.0.10", verbose_level = LoggerApi.VERBOSE_HIGH) try: # connect to server 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 index 8b192491..95a23ac1 100644 --- a/scripts/automation/trex_control_plane/doc_stl/api/field_engine.rst +++ b/scripts/automation/trex_control_plane/doc_stl/api/field_engine.rst @@ -14,7 +14,7 @@ The FE can allocate stream variables in a Stream context, write a stream variabl * Update IPv4 checksum -for example this snippet will create SYN Attack:: +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 @@ -108,7 +108,8 @@ STLVmTupleGen Field Engine snippet -------------------- -Example1:: +.. code-block:: python + :caption: Example1 base_pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025) @@ -130,9 +131,10 @@ Example1:: pkt = STLPktBuilder(pkt = base_pkt/pad, vm = vm) - -Example2:: +.. code-block:: python + :caption: Example2 + #range of source mac-addr 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 index 9484f565..b2b23e48 100644 --- a/scripts/automation/trex_control_plane/doc_stl/api/profile_code.rst +++ b/scripts/automation/trex_control_plane/doc_stl/api/profile_code.rst @@ -81,7 +81,9 @@ STLProfile snippet ------------------ -Example1:: +.. code-block:: python + :caption: 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) @@ -110,7 +112,9 @@ Example1:: ]).get_streams() -Example2:: +.. code-block:: python + :caption: Example2 + class STLS1(object): diff --git a/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_client.py b/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_client.py index c76abeea..f7e63ccf 100644 --- a/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_client.py +++ b/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_client.py @@ -406,7 +406,9 @@ class STLClient(object): async_port : int the ASYNC port - For example:: + .. code-block:: python + :caption: Example + # connect to local TRex server c = STLClient() diff --git a/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_packet_builder_scapy.py b/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_packet_builder_scapy.py index 35326590..46218bd3 100644 --- a/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_packet_builder_scapy.py +++ b/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_packet_builder_scapy.py @@ -424,7 +424,7 @@ class CTRexScapyPktUtl(object): def get_field_offet_by_str(self, field_des): """ return field_des (offset,size) layer:cnt.field - for example + for example 802|1Q.vlan get 802.1Q->valn replace | with . IP.src IP:0.src (first IP.src like IP.src) @@ -556,7 +556,9 @@ class STLVmFlowVar(CTRexVmDescBase): op : string could be "inc", "dec", "random" - For example:: + .. code-block:: python + :caption: Example1 + # input STLVmFlowVar(min_value=0, max_value=3, size=1,op="inc") @@ -618,7 +620,8 @@ class STLVmFixIpv4(CTRexVmDescBase): **IPv4 header** offset from packet start. It is **not** the offset of the checksum field itself. in could be string in case of scapy packet. format IP[:[id]] - For example:: + .. code-block:: python + :caption: Example2 pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025) @@ -668,7 +671,8 @@ class STLVmWrFlowVar(CTRexVmDescBase): is_big : bool how to write the variable to the the packet. is it big-edian or little edian - For example:: + .. code-block:: python + :caption: Example3 pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025) @@ -708,6 +712,108 @@ class STLVmWrFlowVar(CTRexVmDescBase): class STLVmWrMaskFlowVar(CTRexVmDescBase): def __init__(self, fv_name, pkt_offset, pkt_cast_size=1, mask=0xff, shift=0, add_value=0, offset_fixup=0, is_big=True): + + """ + Write a stream variable into a packet field with some operations. + Using this instruction the variable size and the field could be with different size. + + Pseudocode of this code:: + + uint32_t val=(cast_to_size)rd_from_variable("name") # read flow-var + val+=m_add_value # add value + + if (m_shift>0) { # shift + val=val<<m_shift + }else{ + if (m_shift<0) { + val=val>>(-m_shift) + } + } + + pkt_val=rd_from_pkt(pkt_offset) # RMW to the packet + pkt_val = (pkt_val & ~m_mask) | (val & m_mask) + wr_to_pkt(pkt_offset,pkt_val) + + + :parameters: + fv_name : string + The stream variable name to write to a packet field + + pkt_cast_size : uint8_t + The size in bytes of the packet field + + + mask : uint32_t + The mask of the field. 1 means to write. 0 don't care + + shift : uint8_t + How many bits to shift + + pkt_offset : string or in + the name of the field or offset in byte from packet start. + + offset_fixup : int + how many bytes to go forward. In case of a negative value go backward + + add_val : int + value to add to stream variable before writing it to packet field. can be used as a constant offset + + is_big : bool + how to write the variable to the the packet. is it big-edian or little edian + + Example 1- casting from uint16_t (var) to uint8_t (pkt):: + + + base_pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025) + + vm = STLScVmRaw( [ 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) # mask command ->write it as one byte + ] + ) + + pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025) + + Example 2- change MSB of uint16_t variable:: + + + vm = STLScVmRaw( [ STLVmFlowVar(name="mac_src", + min_value=1, + max_value=30, + size=2, op="dec",step=1), + STLVmWrMaskFlowVar(fv_name="mac_src", + pkt_offset= 10, + pkt_cast_size=2, + mask=0xff00, + shift=8) # take the var shift it 8 (x256) write only to LSB + ] + ) + + + + Example 3- Every 2 packet change the MAC (shift right):: + + vm = STLScVmRaw( [ STLVmFlowVar(name="mac_src", + min_value=1, + max_value=30, + size=2, op="dec",step=1), + STLVmWrMaskFlowVar(fv_name="mac_src", + pkt_offset= 10, + pkt_cast_size=1, + mask=0x1, + shift=-1) # take var mac_src>>1 and write the LSB every two packet there should be a change + ] + ) + + + """ + super(STLVmWrMaskFlowVar, self).__init__() self.name =fv_name assert type(fv_name)==str, 'type of fv_name is not str' @@ -751,8 +857,7 @@ class STLVmTrimPktSize(CTRexVmDescBase): the stream variable name. the value from this variable would be the new total packet size. - - For example:: + For Example:: def create_stream (self): # pkt @@ -873,8 +978,8 @@ class STLVmTupleGen(CTRexVmDescBase): ="0.0.0.10", port_min=1025, port_max=65535, limit_flows=100000, flags=0 - - For example:: + .. code-block:: python + :caption: Example5 def create_stream (self): # pkt @@ -949,7 +1054,38 @@ class STLPktBuilder(CTrexPktBuilderInterface): pkt could be Scapy pkt or pcap file name When path_relative_to_profile is a True load pcap file from a path relative to the profile - Instantiate a CTRexPktBuilder object + + .. code-block:: python + :caption: Example6 + + + # packet is scapy + STLPktBuilder( pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)/(10*'x') ) + + + # packet is taken from pcap file relative to python + STLPktBuilder( pkt ="stl/yaml/udp_64B_no_crc.pcap") + + # packet is taken from pcap file relative to profile file + STLPktBuilder( pkt ="stl/yaml/udp_64B_no_crc.pcap", + path_relative_to_profile = True ) + + + vm = STLScVmRaw( [ 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 + ] + ) + + 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' + + STLPktBuilder(pkt = base_pkt/pad, vm= vm) + :parameters: @@ -959,7 +1095,7 @@ class STLPktBuilder(CTrexPktBuilderInterface): pkt_buffer : string a packet as buffer - vm : list + vm : list or base on :class:`trex_stl_lib.trex_stl_packet_builder_scapy.STLScVmRaw` a list of instructions to manipolate packet fields path_relative_to_profile : bool @@ -971,34 +1107,6 @@ class STLPktBuilder(CTrexPktBuilderInterface): remove_fcs : bool in case of buffer do we want to remove fcs - for Example:: - - # packet is scapy - STLPktBuilder( pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)/(10*'x') - - # packet is taken from pcap file relative to python - STLPktBuilder(pkt ="stl/yaml/udp_64B_no_crc.pcap") - - # packet is taken from pcap file relative to profile file - STLPktBuilder(pkt ="stl/yaml/udp_64B_no_crc.pcap", - path_relative_to_profile = True) - - - vm = STLScVmRaw( [ 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 - ] - ); - - 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' - - STLPktBuilder(pkt = base_pkt/pad, - vm= vm) """ @@ -1156,7 +1264,12 @@ class STLPktBuilder(CTrexPktBuilderInterface): def set_packet (self, pkt): """ - Scapy packet Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)/IP()/"A"*10 + Scapy packet + + For Example:: + + pkt =Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)/IP()/('x'*10) + """ if isinstance(pkt, Packet): self.pkt = pkt; diff --git a/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_streams.py b/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_streams.py index 939c8ed5..b1bde030 100644 --- a/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_streams.py +++ b/scripts/automation/trex_control_plane/stl/trex_stl_lib/trex_stl_streams.py @@ -38,10 +38,15 @@ class STLTXMode(object): percentage : float link interface precent 0-100 e.g. 10 is 10%% of the port link setup - For example:: + .. code-block:: python + :caption: STLTXMode Example + mode = STLTXCont(pps = 10) + mode = STLTXCont(bps_L1 = 10000000) #10mbps L1 + mode = STLTXCont(bps_L2 = 10000000) #10mbps L2 + mode = STLTXCont(percentage = 10) #10% """ @@ -98,7 +103,9 @@ class STLTXCont(STLTXMode): see :class:`trex_stl_lib.trex_stl_streams.STLTXMode` for rate - For example:: + .. code-block:: python + :caption: STLTXCont Example + mode = STLTXCont(pps = 10) """ @@ -125,7 +132,9 @@ class STLTXSingleBurst(STLTXMode): see :class:`trex_stl_lib.trex_stl_streams.STLTXMode` for rate - For example:: + .. code-block:: python + :caption: STLTXSingleBurst Example + mode = STLTXSingleBurst( pps = 10, total_pkts = 1) """ @@ -168,7 +177,9 @@ class STLTXMultiBurst(STLTXMode): see :class:`trex_stl_lib.trex_stl_streams.STLTXMode` for rate - For example:: + .. code-block:: python + :caption: STLTXMultiBurst Example + mode = STLTXMultiBurst(pps = 10, pkts_per_burst = 1,count 10, ibg=10.0) """ @@ -202,7 +213,8 @@ STLStreamDstMAC_ARP =2 class STLFlowStats(object): """ Define per stream stats - For example:: + .. code-block:: python + :caption: STLFlowStats Example flow_stats = STLFlowStats(pg_id = 7) @@ -228,7 +240,9 @@ class STLFlowStats(object): class STLStream(object): """ One stream object, include mode, Field Engine mode packet template and Rx stats - For example:: + .. code-block:: python + :caption: STLStream Example + 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' @@ -265,7 +279,7 @@ class STLStream(object): name : string The name of the stream. Needed if this stream is dependent on another stream and another stream need to refer to this stream by its name. - packet : STLPktBuilder + packet : STLPktBuilder see :class:`trex_stl_lib.trex_stl_packet_builder_scapy.STLPktBuilder` The template packet and field engine program e.g. packet = STLPktBuilder(pkt = base_pkt/pad) mode : :class:`trex_stl_lib.trex_stl_streams.STLTXCont` or :class:`trex_stl_lib.trex_stl_streams.STLTXSingleBurst` or :class:`trex_stl_lib.trex_stl_streams.STLTXMultiBurst` @@ -742,7 +756,8 @@ class YAMLLoader(object): class STLProfile(object): """ Describe a list of streams - For example:: + .. code-block:: python + :caption: STLProfile Example profile = STLProfile( [ STLStream( isg = 10.0, # star in delay name ='S0', |