examples/pipeline/examples/learner.spec

   1 ; SPDX-License-Identifier: BSD-3-Clause
   2 ; Copyright(c) 2020 Intel Corporation
   3
   4 ; The learner tables are very useful for learning and connection tracking.
   5 ;
   6 ; As opposed to regular tables, which are read-only for the data plane, the learner tables can be
   7 ; updated by the data plane without any control plane intervention. The "learning" process typically
   8 ; takes place by having the default action (i.e. the table action which is executed on lookup miss)
   9 ; explicitly add to the table with a specific action the key that just missed the lookup operation.
  10 ; Each table key expires automatically after a configurable timeout period if not hit during this
  11 ; interval.
  12 ;
  13 ; This example demonstrates a simple connection tracking setup, where the connections are identified
  14 ; by the IPv4 destination address. The forwarding action assigned to each new connection gets the
  15 ; output port as argument, with the output port of each connection generated by a counter that is
  16 ; persistent between packets. On top of the usual table stats, the learner table stats include the
  17 ; number of packets with learning related events.
  18
  19 //
  20 // Headers
  21 //
  22 struct ethernet_h {
  23         bit<48> dst_addr
  24         bit<48> src_addr
  25         bit<16> ethertype
  26 }
  27
  28 struct ipv4_h {
  29         bit<8> ver_ihl
  30         bit<8> diffserv
  31         bit<16> total_len
  32         bit<16> identification
  33         bit<16> flags_offset
  34         bit<8> ttl
  35         bit<8> protocol
  36         bit<16> hdr_checksum
  37         bit<32> src_addr
  38         bit<32> dst_addr
  39 }
  40
  41 header ethernet instanceof ethernet_h
  42 header ipv4 instanceof ipv4_h
  43
  44 //
  45 // Meta-data
  46 //
  47 struct metadata_t {
  48         bit<32> port_in
  49         bit<32> port_out
  50
  51         // Key timeout.
  52         bit<32> timeout_id
  53
  54         // Arguments for the "fwd_action" action.
  55         bit<32> fwd_action_arg_port_out
  56 }
  57
  58 metadata instanceof metadata_t
  59
  60 //
  61 // Registers.
  62 //
  63 regarray counter size 1 initval 0
  64
  65 //
  66 // Actions
  67 //
  68 struct fwd_action_args_t {
  69         bit<32> port_out
  70 }
  71
  72 action fwd_action args instanceof fwd_action_args_t {
  73         mov m.port_out t.port_out
  74         rearm
  75         return
  76 }
  77
  78 action learn_action args none {
  79         // Pick the key timeout. Timeout ID #1 (i.e. 120 seconds) is selected.
  80         mov m.timeout_id 1
  81
  82         // Read current counter value into m.fwd_action_arg_port_out.
  83         regrd m.fwd_action_arg_port_out counter 0
  84
  85         // Increment the counter.
  86         regadd counter 0 1
  87
  88         // Limit the output port values to 0 .. 3.
  89         and m.fwd_action_arg_port_out 3
  90
  91         // Add the current lookup key to the table with fwd_action as the key action. The action
  92         // arguments are read from the packet meta-data (the m.fwd_action_arg_port_out field). These
  93         // packet meta-data fields have to be written before the "learn" instruction is invoked.
  94         learn fwd_action m.fwd_action_arg_port_out m.timeout_id
  95
  96         // Send the current packet to the same output port.
  97         mov m.port_out m.fwd_action_arg_port_out
  98
  99         return
 100 }
 101
 102 //
 103 // Tables.
 104 //
 105 learner fwd_table {
 106         key {
 107                 h.ipv4.dst_addr
 108         }
 109
 110         actions {
 111                 fwd_action
 112
 113                 learn_action
 114         }
 115
 116         default_action learn_action args none
 117
 118         size 1048576
 119
 120         timeout {
 121                 60
 122                 120
 123                 180
 124         }
 125 }
 126
 127 //
 128 // Pipeline.
 129 //
 130 apply {
 131         rx m.port_in
 132         extract h.ethernet
 133         extract h.ipv4
 134         table fwd_table
 135         emit h.ethernet
 136         emit h.ipv4
 137         tx m.port_out
 138 }