anchor.diff:  <3> Write stream tuple.port variable into the second UDP header 
   
   
  +==== Tutorial 18: Mask instruction 
  +
  +The STLVmWrMaskFlowVar is a handy command. The pseudocode is a folow 
  +
  +.Pseudocode 
  +[source,bash]
  +----
  +        uint32_t val=(cast_to_size)rd_from_varible("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
  +        pkt_val = (pkt_val & ~m_mask) | (val & m_mask)
  +        wr_to_pkt(pkt_offset,pkt_val)
  +----
  +
  +
  +===== Example 1
  +
  +[source,python]
  +----
  +        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) # mask command ->write it as one byte
  +                          ]
  +                       )
  +
  +----
  +
  +This will cast stream variable with 2 byte to be 1 byte 
  +
  +===== Example 2
  +
  +[source,python]
  +----
  +
  +        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= 10,
  +                                              pkt_cast_size=2, 
  +                                              mask=0xff00,
  +                                              shift=8) # take the var shift it 8 (x256) write only to LSB
  +                          ]
  +                       )
  +----
  +
  +The output will be shift by 8 
  +
  +.Output 
  +[format="csv",cols="1^", options="header",width="20%"]
  +|=================
  + value
  + 0x0100 
  + 0x0200 
  + 0x0300 
  +|=================
  +
  +===== Example 3
  +
  +[source,python]
  +----
  +        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= 10,
  +                                              pkt_cast_size=1, 
  +                                              mask=0x1,
  +                                              shift=-1)         <1>
  +                          ]
  +                       )
  +
  +----
  +<1> take var mac_src>>1 and write the LSB every two packet there should be a change
  +
  +.Output 
  +[format="csv",cols="1^", options="header",width="20%"]
  +|=================
  +value
  + 0x00 
  + 0x00 
  + 0x01 
  + 0x01 
  + 0x00 
  + 0x00 
  + 0x01 
  + 0x01 
  +|=================
  +
  +
  +=== Tutorials HLT profile 
  +
  +HLTAPI is a Cisco standard API for traffic generation.IXIA and Spirent support this standard.  traffic_config API has set of arguments  for specifying  the packet, how to send it and what field to change while sending it. 
  +We created a Python module that you can specify the traffic profile in HLT like format and load it as native profile for smooth transition .
  +Under the hood there is a compiler that converts it to native scapy/field engine instruction
  +The support is limited to [TBD] this argument.
  +
  +
  +file: `stl/hlt/hlt_udp_inc_dec_len_9k.py`
  +
  +[source,python]
  +----
  +
  +class STLS1(object):
  +    '''
  +    Create 2 Eth/IP/UDP steams with different packet size:
  +    First stream will start from 64 bytes (default) and will increase until max_size (9,216)
  +    Seconds stream will decrease the packet size in reverse way
  +    '''
  +
  +    def create_streams (self):
  +        max_size = 9*1024
  +        return [STLHltStream(length_mode = 'increment',
  +                             frame_size_max = max_size,
  +                             l3_protocol = 'ipv4',
  +                             ip_src_addr = '16.0.0.1',
  +                             ip_dst_addr = '48.0.0.1',
  +                             l4_protocol = 'udp',
  +                             udp_src_port = 1025,
  +                             udp_dst_port = 12,
  +                             rate_pps = 1,
  +                             ),
  +                STLHltStream(length_mode = 'decrement',
  +                             frame_size_max = max_size,
  +                             l3_protocol = 'ipv4',
  +                             ip_src_addr = '16.0.0.1',
  +                             ip_dst_addr = '48.0.0.1',
  +                             l4_protocol = 'udp',
  +                             udp_src_port = 1025,
  +                             udp_dst_port = 12,
  +                             rate_pps = 1,
  +                             )
  +               ]
  +
  +    def get_streams (self, direction = 0):
  +        return self.create_streams()
  +----
  +
  +This profile can be run with the simulator to generate pcap file
  +
  +[source,bash]
  +----
  +$ ./stl-sim -f stl/hlt/hlt_udp_inc_dec_len_9k.py -o b.pcap -l 10 
  +----
  +
  +It can be converted to native json or YAML
  +
  +[source,bash]
  +----
  +$ ./stl-sim -f stl/hlt/hlt_udp_inc_dec_len_9k.py --josn
  +----
  +
  +or converted to native Python native Scapy/FE using this command 
  +
  +[source,bash]
  +----
  +$ ./stl-sim -f stl/hlt/hlt_udp_inc_dec_len_9k.py --native 
  +----
  +
  +to run it using using the TRex Console 
  +
  +[source,bash]
  +----
  +TRex>start -f stl/hlt/hlt_udp_inc_dec_len_9k.py -m 10mbps -a     
  +----
  +
  +
  +more profiles and example can be found in `stl/hlt` folder 
  +
  +
  +=== Tutorials Native Python API 
  +
  +==== Tutorial 1: 
  +
  +Python API examples are located here: `automation/trex_control_plane/stl/examples`
  +Python API library is located here: `automation/trex_control_plane/stl/trex_stl_lib`
  +
  +The Console is using the library to interact with TRex server and protocol is JSON-RPC2 over ZMQ
  +
  +file: `stl_bi_dir_flows.py`
  +
  +
  +[source,python]
  +----
  +
  +def simple_burst ():
  + 
  +    # create client
  +    c = STLClient()
  +    passed = True
  +
  +    try:
  +        # turn this on for some information
  +        #c.set_verbose("high")
  +
  +        # create two streams
  +        s1 = STLStream(packet = create_pkt(200, 0),
  +                       mode = STLTXCont(pps = 100))
  +
  +        # second stream with a phase of 1ms (inter stream gap)
  +        s2 = STLStream(packet = create_pkt(200, 1),
  +                       isg = 1000,
  +                       mode = STLTXCont(pps = 100))
  +
  +
  +        # connect to server
  +        c.connect()
  +
  +        # prepare our ports (my machine has 0 <--> 1 with static route)
  +        c.reset(ports = [0, 1]) # it will Acquire port 0,1
  +
  +        # add both streams to ports
  +        c.add_streams(s1, ports = [0])
  +        c.add_streams(s2, ports = [1])
  +
  +        # clear the stats before injecting
  +        c.clear_stats()
  +
  +        # choose rate and start traffic for 10 seconds on 5 mpps
  +        print "Running 5 Mpps on ports 0, 1 for 10 seconds..."
  +        c.start(ports = [0, 1], mult = "5mpps", duration = 10)      <1>
  +
  +        # block until done
  +        c.wait_on_traffic(ports = [0, 1])
  +
  +        # read the stats after the test
  +        stats = c.get_stats()
  +
  +        print json.dumps(stats[0], indent = 4, separators=(',', ': '), sort_keys = True)
  +        print json.dumps(stats[1], indent = 4, separators=(',', ': '), sort_keys = True)
  +
  +        lost_a = stats[0]["opackets"] - stats[1]["ipackets"]
  +        lost_b = stats[1]["opackets"] - stats[0]["ipackets"]
  +
  +        print "\npackets lost from 0 --> 1:   {0} pkts".format(lost_a)
  +        print "packets lost from 1 --> 0:   {0} pkts".format(lost_b)
  +
  +        if (lost_a == 0) and (lost_b == 0):
  +            passed = True
  +        else:
  +            passed = False
  +
  +    except STLError as e:
  +        passed = False
  +        print e
  +
  +    finally:
  +        c.disconnect()
  +
  +    if passed:
  +        print "\nTest has passed :-)\n"
  +    else:
  +        print "\nTest has failed :-(\n"
  +
  +
  +# run the tests
  +simple_burst()
  +----
  +<1> Start can work on mask of ports
  +
  +
  +=== Tutorials HLT Python API 
  +
  +
  +
  +HLT Python API is a layer on top the native layer. it support 
  +
  +* Device Control
  +** connect
  +** cleanup_session
  +** device_info
  +** info
  +* Interface
  +** interface_config
  +** interface_stats
  +* Traffic
  +** traffic_config - not all arguments are supported  
  +** traffic_control
  +** traffic_stats
  +
  +
  +file: `hlt_udp_simple.py`
  +
  +
  +[source,python]
  +----
  +
  +import sys
  +import argparse
  +import stl_path
  +from trex_stl_lib.api import *                                          <1>
  +from trex_stl_lib.trex_stl_hltapi import *                              <2>
  +
  +
  +if __name__ == "__main__":
  +    parser = argparse.ArgumentParser(usage=""" 
  +    Connect to TRex and send burst of packets
  +
  +    examples
  +
  +     hlt_udp_simple.py -s 9000 -d 30
  +
  +     hlt_udp_simple.py -s 9000 -d 30 -rate_percent 10
  +
  +     hlt_udp_simple.py -s 300 -d 30 -rate_pps 5000000
  +
  +     hlt_udp_simple.py -s 800 -d 30 -rate_bps 500000000 --debug
  +
  +     then run the simulator on the output 
  +       ./stl-sim -f example.yaml -o a.pcap  ==> a.pcap include the packet
  +
  +    """,
  +    description="Example for TRex HLTAPI",
  +    epilog=" based on hhaim's stl_run_udp_simple example");
  +
  +    parser.add_argument("--ip", 
  +                        dest="ip",
  +                        help='Remote trex ip',
  +                        default="127.0.0.1",
  +                        type = str)
  +
  +    parser.add_argument("-s", "--frame-size", 
  +                        dest="frame_size",
  +                        help='L2 frame size in bytes without FCS',
  +                        default=60,
  +                        type = int,)
  +
  +    parser.add_argument('-d','--duration', 
  +                        dest='duration',
  +                        help='duration in second ',
  +                        default=10,
  +                        type = int,)
  +
  +    parser.add_argument('--rate-pps', 
  +                        dest='rate_pps',
  +                        help='speed in pps',
  +                        default="100")
  +
  +    parser.add_argument('--src', 
  +                        dest='src_mac',
  +                        help='src MAC',
  +                        default='00:50:56:b9:de:75')
  +
  +    parser.add_argument('--dst', 
  +                        dest='dst_mac',
  +                        help='dst MAC',
  +                        default='00:50:56:b9:34:f3')
  +
  +    args = parser.parse_args();
  +
  +    hltapi = CTRexHltApi()
  +    print 'Connecting to TRex'
  +    res = hltapi.connect(device = args.ip, port_list = [0, 1], reset = True, break_locks = True)
  +    check_res(res)
  +    ports = res['port_handle']
  +    if len(ports) < 2:
  +        error('Should have at least 2 ports for this test')
  +    print 'Connected, acquired ports: %s' % ports
  +
  +    print 'Creating traffic'
  +
  +    res = hltapi.traffic_config(mode = 'create', bidirectional = True,
  +                                port_handle = ports[0], port_handle2 = ports[1],
  +                                frame_size = args.frame_size,
  +                                mac_src = args.src_mac, mac_dst = args.dst_mac,
  +                                mac_src2 = args.dst_mac, mac_dst2 = args.src_mac,
  +                                l3_protocol = 'ipv4',
  +                                ip_src_addr = '10.0.0.1', ip_src_mode = 'increment', ip_src_count = 254,
  +                                ip_dst_addr = '8.0.0.1', ip_dst_mode = 'increment', ip_dst_count = 254,
  +                                l4_protocol = 'udp',
  +                                udp_dst_port = 12, udp_src_port = 1025,
  +                                stream_id = 1, # temporary workaround, add_stream does not return stream_id
  +                                rate_pps = args.rate_pps,
  +                                )
  +    check_res(res)
  +
  +    print 'Starting traffic'
  +    res = hltapi.traffic_control(action = 'run', port_handle = ports[:2])
  +    check_res(res)
  +    wait_with_progress(args.duration)
  +
  +    print 'Stopping traffic'
  +    res = hltapi.traffic_control(action = 'stop', port_handle = ports[:2])
  +    check_res(res)
  +
  +    res = hltapi.traffic_stats(mode = 'aggregate', port_handle = ports[:2])
  +    check_res(res)
  +    print_brief_stats(res)
  +    
  +    res = hltapi.cleanup_session(port_handle = 'all')
  +    check_res(res)
  +
  +    print 'Done' 
  +----
  +<1> import Native TRex API
  +<2> import HLT   TRex
  +
  +
   
   === Reference
   
  
positive.code: 
  === Console commands 
  
  === Python API 
  
  
  
  
  
  
  
  
  
  
  
  
negative.code: 
  [source,python]
  ----
  $./stl-sim -f stl/pcap.py --yaml
  - name: 1
    next: 2                      <1> 
    stream:
  