anchor.diff:  
   [source,python]
   ----
  -csi-kiwi-02]> ./stl-sim -f stl/pcap.py --yaml
  +$./stl-sim -f stl/pcap.py --yaml
   - name: 1
     next: 2                      <1> 
     stream:
  
positive.code: In this example MPLS label field will be changed.
  
  .MPLS header 
  [cols="32", halign="center"] 
  |==== 
  20+<|Label 3+<|TC 1+<|S 8+<|TTL| 
  0|1|2|3|4|5|6|7|8|9|0|1|2|3|4|5|6|7|8|9|0|1|2|3|4|5|6|7|8|9|0|1|
  
negative.code: <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
  
  