docs/gettingstarted/developers/vnet.md

   1
   2 VNET (VPP Network Stack)
   3 ========================
   4
   5 The files associated with the VPP network stack layer are located in the
   6 *./src/vnet* folder. The Network Stack Layer is basically an
   7 instantiation of the code in the other layers. This layer has a vnet
   8 library that provides vectorized layer-2 and 3 networking graph nodes, a
   9 packet generator, and a packet tracer.
  10
  11 In terms of building a packet processing application, vnet provides a
  12 platform-independent subgraph to which one connects a couple of
  13 device-driver nodes.
  14
  15 Typical RX connections include "ethernet-input" \[full software
  16 classification, feeds ipv4-input, ipv6-input, arp-input etc.\] and
  17 "ipv4-input-no-checksum" \[if hardware can classify, perform ipv4 header
  18 checksum\].
  19
  20 Effective graph dispatch function coding
  21 ----------------------------------------
  22
  23 Over the 15 years, multiple coding styles have emerged: a
  24 single/dual/quad loop coding model (with variations) and a
  25 fully-pipelined coding model.
  26
  27 Single/dual loops
  28 -----------------
  29
  30 The single/dual/quad loop model variations conveniently solve problems
  31 where the number of items to process is not known in advance: typical
  32 hardware RX-ring processing. This coding style is also very effective
  33 when a given node will not need to cover a complex set of dependent
  34 reads.
  35
  36 Here is an quad/single loop which can leverage up-to-avx512 SIMD vector
  37 units to convert buffer indices to buffer pointers:
  38
  39 ```c
  40    static uword
  41    simulated_ethernet_interface_tx (vlib_main_t * vm,
  42                                  vlib_node_runtime_t *
  43                                  node, vlib_frame_t * frame)
  44    {
  45      u32 n_left_from, *from;
  46      u32 next_index = 0;
  47      u32 n_bytes;
  48      u32 thread_index = vm->thread_index;
  49      vnet_main_t *vnm = vnet_get_main ();
  50      vnet_interface_main_t *im = &vnm->interface_main;
  51      vlib_buffer_t *bufs[VLIB_FRAME_SIZE], **b;
  52      u16 nexts[VLIB_FRAME_SIZE], *next;
  53
  54      n_left_from = frame->n_vectors;
  55      from = vlib_frame_vector_args (frame);
  56
  57      /*
  58       * Convert up to VLIB_FRAME_SIZE indices in "from" to
  59       * buffer pointers in bufs[]
  60       */
  61      vlib_get_buffers (vm, from, bufs, n_left_from);
  62      b = bufs;
  63      next = nexts;
  64
  65      /*
  66       * While we have at least 4 vector elements (pkts) to process..
  67       */
  68      while (n_left_from >= 4)
  69        {
  70          /* Prefetch next quad-loop iteration. */
  71          if (PREDICT_TRUE (n_left_from >= 8))
  72            {
  73              vlib_prefetch_buffer_header (b[4], STORE);
  74              vlib_prefetch_buffer_header (b[5], STORE);
  75              vlib_prefetch_buffer_header (b[6], STORE);
  76              vlib_prefetch_buffer_header (b[7], STORE);
  77            }
  78
  79          /*
  80           * $$$ Process 4x packets right here...
  81           * set next[0..3] to send the packets where they need to go
  82           */
  83
  84           do_something_to (b[0]);
  85           do_something_to (b[1]);
  86           do_something_to (b[2]);
  87           do_something_to (b[3]);
  88
  89          /* Process the next 0..4 packets */
  90          b += 4;
  91          next += 4;
  92          n_left_from -= 4;
  93         }
  94      /*
  95       * Clean up 0...3 remaining packets at the end of the incoming frame
  96       */
  97      while (n_left_from > 0)
  98        {
  99          /*
 100           * $$$ Process one packet right here...
 101           * set next[0..3] to send the packets where they need to go
 102           */
 103           do_something_to (b[0]);
 104
 105          /* Process the next packet */
 106          b += 1;
 107          next += 1;
 108          n_left_from -= 1;
 109        }
 110
 111      /*
 112       * Send the packets along their respective next-node graph arcs
 113       * Considerable locality of reference is expected, most if not all
 114       * packets in the inbound vector will traverse the same next-node
 115       * arc
 116       */
 117      vlib_buffer_enqueue_to_next (vm, node, from, nexts, frame->n_vectors);
 118
 119      return frame->n_vectors;
 120    }
 121 ```
 122
 123 Given a packet processing task to implement, it pays to scout around
 124 looking for similar tasks, and think about using the same coding
 125 pattern. It is not uncommon to recode a given graph node dispatch function
 126 several times during performance optimization.
 127
 128 Creating Packets from Scratch
 129 -----------------------------
 130
 131 At times, it's necessary to create packets from scratch and send
 132 them. Tasks like sending keepalives or actively opening connections
 133 come to mind. Its not difficult, but accurate buffer metadata setup is
 134 required.
 135
 136 ### Allocating Buffers
 137
 138 Use vlib_buffer_alloc, which allocates a set of buffer indices. For
 139 low-performance applications, it's OK to allocate one buffer at a
 140 time. Note that vlib_buffer_alloc(...) does NOT initialize buffer
 141 metadata. See below.
 142
 143 In high-performance cases, allocate a vector of buffer indices,
 144 and hand them out from the end of the vector; decrement _vec_len(..)
 145 as buffer indices are allocated. See tcp_alloc_tx_buffers(...) and
 146 tcp_get_free_buffer_index(...) for an example.
 147
 148 ### Buffer Initialization Example
 149
 150 The following example shows the **main points**, but is not to be
 151 blindly cut-'n-pasted.
 152
 153 ```c
 154   u32 bi0;
 155   vlib_buffer_t *b0;
 156   ip4_header_t *ip;
 157   udp_header_t *udp;
 158
 159   /* Allocate a buffer */
 160   if (vlib_buffer_alloc (vm, &bi0, 1) != 1)
 161     return -1;
 162
 163   b0 = vlib_get_buffer (vm, bi0);
 164
 165   /* At this point b0->current_data = 0, b0->current_length = 0 */
 166
 167   /*
 168    * Copy data into the buffer. This example ASSUMES that data will fit
 169    * in a single buffer, and is e.g. an ip4 packet.
 170    */
 171   if (have_packet_rewrite)
 172      {
 173        clib_memcpy (b0->data, data, vec_len (data));
 174        b0->current_length = vec_len (data);
 175      }
 176   else
 177      {
 178        /* OR, build a udp-ip packet (for example) */
 179        ip = vlib_buffer_get_current (b0);
 180        udp = (udp_header_t *) (ip + 1);
 181        data_dst = (u8 *) (udp + 1);
 182
 183        ip->ip_version_and_header_length = 0x45;
 184        ip->ttl = 254;
 185        ip->protocol = IP_PROTOCOL_UDP;
 186        ip->length = clib_host_to_net_u16 (sizeof (*ip) + sizeof (*udp) +
 187                   vec_len(udp_data));
 188        ip->src_address.as_u32 = src_address->as_u32;
 189        ip->dst_address.as_u32 = dst_address->as_u32;
 190        udp->src_port = clib_host_to_net_u16 (src_port);
 191        udp->dst_port = clib_host_to_net_u16 (dst_port);
 192        udp->length = clib_host_to_net_u16 (vec_len (udp_data));
 193        clib_memcpy (data_dst, udp_data, vec_len(udp_data));
 194
 195        if (compute_udp_checksum)
 196          {
 197            /* RFC 7011 section 10.3.2. */
 198            udp->checksum = ip4_tcp_udp_compute_checksum (vm, b0, ip);
 199            if (udp->checksum == 0)
 200              udp->checksum = 0xffff;
 201       }
 202       b0->current_length = vec_len (sizeof (*ip) + sizeof (*udp) +
 203                                    vec_len (udp_data));
 204
 205     }
 206   b0->flags |= VLIB_BUFFER_TOTAL_LENGTH_VALID;
 207
 208   /* sw_if_index 0 is the "local" interface, which always exists */
 209   vnet_buffer (b0)->sw_if_index[VLIB_RX] = 0;
 210
 211   /* Use the default FIB index for tx lookup. Set non-zero to use another fib */
 212   vnet_buffer (b0)->sw_if_index[VLIB_TX] = 0;
 213
 214 ```
 215
 216 If your use-case calls for large packet transmission, use
 217 vlib_buffer_chain_append_data_with_alloc(...) to create the requisite
 218 buffer chain.
 219
 220 ### Enqueueing packets for lookup and transmission
 221
 222 The simplest way to send a set of packets is to use
 223 vlib_get_frame_to_node(...) to allocate fresh frame(s) to
 224 ip4_lookup_node or ip6_lookup_node, add the constructed buffer
 225 indices, and dispatch the frame using vlib_put_frame_to_node(...).
 226
 227 ```c
 228     vlib_frame_t *f;
 229     f = vlib_get_frame_to_node (vm, ip4_lookup_node.index);
 230     f->n_vectors = vec_len(buffer_indices_to_send);
 231     to_next = vlib_frame_vector_args (f);
 232
 233     for (i = 0; i < vec_len (buffer_indices_to_send); i++)
 234       to_next[i] = buffer_indices_to_send[i];
 235
 236     vlib_put_frame_to_node (vm, ip4_lookup_node_index, f);
 237 ```
 238
 239 It is inefficient to allocate and schedule single packet frames.
 240 That's typical in case you need to send one packet per second, but
 241 should **not** occur in a for-loop!
 242
 243 Packet tracer
 244 -------------
 245
 246 Vlib includes a frame element \[packet\] trace facility, with a simple
 247 debug CLI interface. The cli is straightforward: "trace add
 248 input-node-name count" to start capturing packet traces.
 249
 250 To trace 100 packets on a typical x86\_64 system running the dpdk
 251 plugin: "trace add dpdk-input 100". When using the packet generator:
 252 "trace add pg-input 100"
 253
 254 To display the packet trace: "show trace"
 255
 256 Each graph node has the opportunity to capture its own trace data. It is
 257 almost always a good idea to do so. The trace capture APIs are simple.
 258
 259 The packet capture APIs snapshoot binary data, to minimize processing at
 260 capture time. Each participating graph node initialization provides a
 261 vppinfra format-style user function to pretty-print data when required
 262 by the VLIB "show trace" command.
 263
 264 Set the VLIB node registration ".format\_trace" member to the name of
 265 the per-graph node format function.
 266
 267 Here's a simple example:
 268
 269 ```c
 270     u8 * my_node_format_trace (u8 * s, va_list * args)
 271     {
 272         vlib_main_t * vm = va_arg (*args, vlib_main_t *);
 273         vlib_node_t * node = va_arg (*args, vlib_node_t *);
 274         my_node_trace_t * t = va_arg (*args, my_trace_t *);
 275
 276         s = format (s, "My trace data was: %d", t-><whatever>);
 277
 278         return s;
 279     }
 280 ```
 281
 282 The trace framework hands the per-node format function the data it
 283 captured as the packet whizzed by. The format function pretty-prints the
 284 data as desired.
 285
 286 Graph Dispatcher Pcap Tracing
 287 -----------------------------
 288
 289 The vpp graph dispatcher knows how to capture vectors of packets in pcap
 290 format as they're dispatched. The pcap captures are as follows:
 291
 292 ```
 293     VPP graph dispatch trace record description:
 294
 295         0                   1                   2                   3
 296         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
 297        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 298        | Major Version | Minor Version | NStrings      | ProtoHint     |
 299        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 300        | Buffer index (big endian)                                     |
 301        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 302        + VPP graph node name ...     ...               | NULL octet    |
 303        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 304        | Buffer Metadata ... ...                       | NULL octet    |
 305        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 306        | Buffer Opaque ... ...                         | NULL octet    |
 307        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 308        | Buffer Opaque 2 ... ...                       | NULL octet    |
 309        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 310        | VPP ASCII packet trace (if NStrings > 4)      | NULL octet    |
 311        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 312        | Packet data (up to 16K)                                       |
 313        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 314 ```
 315
 316 Graph dispatch records comprise a version stamp, an indication of how
 317 many NULL-terminated strings will follow the record header and preceed
 318 packet data, and a protocol hint.
 319
 320 The buffer index is an opaque 32-bit cookie which allows consumers of
 321 these data to easily filter/track single packets as they traverse the
 322 forwarding graph.
 323
 324 Multiple records per packet are normal, and to be expected. Packets
 325 will appear multiple times as they traverse the vpp forwarding
 326 graph. In this way, vpp graph dispatch traces are significantly
 327 different from regular network packet captures from an end-station.
 328 This property complicates stateful packet analysis.
 329
 330 Restricting stateful analysis to records from a single vpp graph node
 331 such as "ethernet-input" seems likely to improve the situation.
 332
 333 As of this writing: major version = 1, minor version = 0. Nstrings
 334 SHOULD be 4 or 5. Consumers SHOULD be wary values less than 4 or
 335 greater than 5. They MAY attempt to display the claimed number of
 336 strings, or they MAY treat the condition as an error.
 337
 338 Here is the current set of protocol hints:
 339
 340 ```c
 341     typedef enum
 342       {
 343         VLIB_NODE_PROTO_HINT_NONE = 0,
 344         VLIB_NODE_PROTO_HINT_ETHERNET,
 345         VLIB_NODE_PROTO_HINT_IP4,
 346         VLIB_NODE_PROTO_HINT_IP6,
 347         VLIB_NODE_PROTO_HINT_TCP,
 348         VLIB_NODE_PROTO_HINT_UDP,
 349         VLIB_NODE_N_PROTO_HINTS,
 350       } vlib_node_proto_hint_t;
 351 ```
 352
 353 Example: VLIB_NODE_PROTO_HINT_IP6 means that the first octet of packet
 354 data SHOULD be 0x60, and should begin an ipv6 packet header.
 355
 356 Downstream consumers of these data SHOULD pay attention to the
 357 protocol hint. They MUST tolerate inaccurate hints, which MAY occur
 358 from time to time.
 359
 360 ### Dispatch Pcap Trace Debug CLI
 361
 362 To start a dispatch trace capture of up to 10,000 trace records:
 363
 364 ```
 365      pcap dispatch trace on max 10000 file dispatch.pcap
 366 ```
 367
 368 To start a dispatch trace which will also include standard vpp packet
 369 tracing for packets which originate in dpdk-input:
 370
 371 ```
 372      pcap dispatch trace on max 10000 file dispatch.pcap buffer-trace dpdk-input 1000
 373 ```
 374 To save the pcap trace, e.g. in /tmp/dispatch.pcap:
 375
 376 ```
 377     pcap dispatch trace off
 378 ```
 379
 380 ### Wireshark dissection of dispatch pcap traces
 381
 382 It almost goes without saying that we built a companion wireshark
 383 dissector to display these traces. As of this writing, we have
 384 upstreamed the wireshark dissector.
 385
 386 Since it will be a while before wireshark/master/latest makes it into
 387 all of the popular Linux distros, please see the "How to build a vpp
 388 dispatch trace aware Wireshark" page for build info.
 389
 390 Here is a sample packet dissection, with some fields omitted for
 391 clarity.  The point is that the wireshark dissector accurately
 392 displays **all** of the vpp buffer metadata, and the name of the graph
 393 node in question.
 394
 395 ```
 396     Frame 1: 2216 bytes on wire (17728 bits), 2216 bytes captured (17728 bits)
 397         Encapsulation type: USER 13 (58)
 398         [Protocols in frame: vpp:vpp-metadata:vpp-opaque:vpp-opaque2:eth:ethertype:ip:tcp:data]
 399     VPP Dispatch Trace
 400         BufferIndex: 0x00036663
 401     NodeName: ethernet-input
 402     VPP Buffer Metadata
 403         Metadata: flags:
 404         Metadata: current_data: 0, current_length: 102
 405         Metadata: current_config_index: 0, flow_id: 0, next_buffer: 0
 406         Metadata: error: 0, n_add_refs: 0, buffer_pool_index: 0
 407         Metadata: trace_index: 0, recycle_count: 0, len_not_first_buf: 0
 408         Metadata: free_list_index: 0
 409         Metadata:
 410     VPP Buffer Opaque
 411         Opaque: raw: 00000007 ffffffff 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
 412         Opaque: sw_if_index[VLIB_RX]: 7, sw_if_index[VLIB_TX]: -1
 413         Opaque: L2 offset 0, L3 offset 0, L4 offset 0, feature arc index 0
 414         Opaque: ip.adj_index[VLIB_RX]: 0, ip.adj_index[VLIB_TX]: 0
 415         Opaque: ip.flow_hash: 0x0, ip.save_protocol: 0x0, ip.fib_index: 0
 416         Opaque: ip.save_rewrite_length: 0, ip.rpf_id: 0
 417         Opaque: ip.icmp.type: 0 ip.icmp.code: 0, ip.icmp.data: 0x0
 418         Opaque: ip.reass.next_index: 0, ip.reass.estimated_mtu: 0
 419         Opaque: ip.reass.fragment_first: 0 ip.reass.fragment_last: 0
 420         Opaque: ip.reass.range_first: 0 ip.reass.range_last: 0
 421         Opaque: ip.reass.next_range_bi: 0x0, ip.reass.ip6_frag_hdr_offset: 0
 422         Opaque: mpls.ttl: 0, mpls.exp: 0, mpls.first: 0, mpls.save_rewrite_length: 0, mpls.bier.n_bytes: 0
 423         Opaque: l2.feature_bitmap: 00000000, l2.bd_index: 0, l2.l2_len: 0, l2.shg: 0, l2.l2fib_sn: 0, l2.bd_age: 0
 424         Opaque: l2.feature_bitmap_input:   none configured, L2.feature_bitmap_output:   none configured
 425         Opaque: l2t.next_index: 0, l2t.session_index: 0
 426         Opaque: l2_classify.table_index: 0, l2_classify.opaque_index: 0, l2_classify.hash: 0x0
 427         Opaque: policer.index: 0
 428         Opaque: ipsec.flags: 0x0, ipsec.sad_index: 0
 429         Opaque: map.mtu: 0
 430         Opaque: map_t.v6.saddr: 0x0, map_t.v6.daddr: 0x0, map_t.v6.frag_offset: 0, map_t.v6.l4_offset: 0
 431         Opaque: map_t.v6.l4_protocol: 0, map_t.checksum_offset: 0, map_t.mtu: 0
 432         Opaque: ip_frag.mtu: 0, ip_frag.next_index: 0, ip_frag.flags: 0x0
 433         Opaque: cop.current_config_index: 0
 434         Opaque: lisp.overlay_afi: 0
 435         Opaque: tcp.connection_index: 0, tcp.seq_number: 0, tcp.seq_end: 0, tcp.ack_number: 0, tcp.hdr_offset: 0, tcp.data_offset: 0
 436         Opaque: tcp.data_len: 0, tcp.flags: 0x0
 437         Opaque: sctp.connection_index: 0, sctp.sid: 0, sctp.ssn: 0, sctp.tsn: 0, sctp.hdr_offset: 0
 438         Opaque: sctp.data_offset: 0, sctp.data_len: 0, sctp.subconn_idx: 0, sctp.flags: 0x0
 439         Opaque: snat.flags: 0x0
 440         Opaque:
 441     VPP Buffer Opaque2
 442         Opaque2: raw: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
 443         Opaque2: qos.bits: 0, qos.source: 0
 444         Opaque2: loop_counter: 0
 445         Opaque2: gbp.flags: 0, gbp.src_epg: 0
 446         Opaque2: pg_replay_timestamp: 0
 447         Opaque2:
 448     Ethernet II, Src: 06:d6:01:41:3b:92 (06:d6:01:41:3b:92), Dst: IntelCor_3d:f6    Transmission Control Protocol, Src Port: 22432, Dst Port: 54084, Seq: 1, Ack: 1, Len: 36
 449         Source Port: 22432
 450         Destination Port: 54084
 451         TCP payload (36 bytes)
 452     Data (36 bytes)
 453
 454     0000  cf aa 8b f5 53 14 d4 c7 29 75 3e 56 63 93 9d 11   ....S...)u>Vc...
 455     0010  e5 f2 92 27 86 56 4c 21 ce c5 23 46 d7 eb ec 0d   ...'.VL!..#F....
 456     0020  a8 98 36 5a                                       ..6Z
 457         Data: cfaa8bf55314d4c729753e5663939d11e5f2922786564c21…
 458         [Length: 36]
 459 ```
 460
 461 It's a matter of a couple of mouse-clicks in Wireshark to filter the
 462 trace to a specific buffer index. With that specific kind of filtration,
 463 one can watch a packet walk through the forwarding graph; noting any/all
 464 metadata changes, header checksum changes, and so forth.
 465
 466 This should be of significant value when developing new vpp graph
 467 nodes. If new code mispositions b->current_data, it will be completely
 468 obvious from looking at the dispatch trace in wireshark.
 469
 470 ## pcap rx, tx, and drop tracing
 471
 472 vpp also supports rx, tx, and drop packet capture in pcap format,
 473 through the "pcap trace" debug CLI command.
 474
 475 This command is used to start or stop a packet capture, or show the
 476 status of packet capture. Each of "pcap trace rx", "pcap trace tx",
 477 and "pcap trace drop" is implemented.  Supply one or more of "rx",
 478 "tx", and "drop" to enable multiple simultaneous capture types.
 479
 480 These commands have the following optional parameters:
 481
 482 - <b>rx</b> - trace received packets.
 483
 484 - <b>tx</b> - trace transmitted packets.
 485
 486 - <b>drop</b> - trace dropped packets.
 487
 488 - <b>max _nnnn_</b> - file size, number of packet captures. Once
 489   <nnnn> packets have been received, the trace buffer buffer is flushed
 490   to the indicated file. Defaults to 1000. Can only be updated if packet
 491   capture is off.
 492
 493 - <b>max-bytes-per-pkt _nnnn_</b> - maximum number of bytes to trace
 494   on a per-packet basis. Must be >32 and less than 9000. Default value:
 495   512.
 496
 497 - <b>filter</b> - Use the pcap rx / tx / drop trace filter, which must
 498   be configured. Use <b>classify filter pcap...</b> to configure the
 499   filter. The filter will only be executed if the per-interface or
 500   any-interface tests fail.
 501
 502 - <b>intfc _interface_ | _any_</b> - Used to specify a given interface,
 503   or use '<em>any</em>' to run packet capture on all interfaces.
 504   '<em>any</em>' is the default if not provided. Settings from a previous
 505   packet capture are preserved, so '<em>any</em>' can be used to reset
 506   the interface setting.
 507
 508 - <b>file _filename_</b> - Used to specify the output filename. The
 509   file will be placed in the '<em>/tmp</em>' directory.  If _filename_
 510   already exists, file will be overwritten. If no filename is
 511   provided, '<em>/tmp/rx.pcap or tx.pcap</em>' will be used, depending
 512   on capture direction. Can only be updated when pcap capture is off.
 513
 514 - <b>status</b> - Displays the current status and configured
 515   attributes associated with a packet capture. If packet capture is in
 516   progress, '<em>status</em>' also will return the number of packets
 517   currently in the buffer. Any additional attributes entered on
 518   command line with a '<em>status</em>' request will be ignored.
 519
 520 - <b>filter</b> - Capture packets which match the current packet
 521   trace filter set. See next section. Configure the capture filter
 522   first.
 523
 524 ## packet trace capture filtering
 525
 526 The "classify filter pcap | <interface-name> | trace" debug CLI command
 527 constructs an arbitrary set of packet classifier tables for use with
 528 "pcap rx | tx | drop trace," and with the vpp packet tracer on a
 529 per-interface or system-wide basis.
 530
 531 Packets which match a rule in the classifier table chain will be
 532 traced. The tables are automatically ordered so that matches in the
 533 most specific table are tried first.
 534
 535 It's reasonably likely that folks will configure a single table with
 536 one or two matches. As a result, we configure 8 hash buckets and 128K
 537 of match rule space by default. One can override the defaults by
 538 specifying "buckets <nnn>" and "memory-size <xxx>" as desired.
 539
 540 To build up complex filter chains, repeatedly issue the classify
 541 filter debug CLI command. Each command must specify the desired mask
 542 and match values. If a classifier table with a suitable mask already
 543 exists, the CLI command adds a match rule to the existing table.  If
 544 not, the CLI command add a new table and the indicated mask rule
 545
 546 ### Configure a simple pcap classify filter
 547
 548 ```
 549     classify filter pcap mask l3 ip4 src match l3 ip4 src 192.168.1.11
 550     pcap trace rx max 100 filter
 551 ```
 552
 553 ### Configure a simple per-interface capture filter
 554
 555 ```
 556     classify filter GigabitEthernet3/0/0 mask l3 ip4 src match l3 ip4 src 192.168.1.11"
 557     pcap trace rx max 100 intfc GigabitEthernet3/0/0
 558 ```
 559
 560 Note that per-interface capture filters are _always_ applied.
 561
 562 ### Clear per-interface capture filters
 563
 564 ```
 565     classify filter GigabitEthernet3/0/0 del
 566 ```
 567
 568 ### Configure another fairly simple pcap classify filter
 569
 570 ```
 571    classify filter pcap mask l3 ip4 src dst match l3 ip4 src 192.168.1.10 dst 192.168.2.10
 572    pcap trace tx max 100 filter
 573 ```
 574
 575 ### Configure a vpp packet tracer filter
 576
 577 ```
 578    classify filter trace mask l3 ip4 src dst match l3 ip4 src 192.168.1.10 dst 192.168.2.10
 579    trace add dpdk-input 100 filter
 580 ```
 581
 582 ### Clear all current classifier filters
 583
 584 ```
 585     classify filter [pcap | <interface> | trace] del
 586 ```
 587
 588 ### To inspect the classifier tables
 589
 590 ```
 591    show classify table [verbose]
 592 ```
 593
 594 The verbose form displays all of the match rules, with hit-counters.
 595
 596 ### Terse description of the "mask <xxx>" syntax:
 597
 598 ```
 599     l2 src dst proto tag1 tag2 ignore-tag1 ignore-tag2 cos1 cos2 dot1q dot1ad
 600     l3 ip4 <ip4-mask> ip6 <ip6-mask>
 601     <ip4-mask> version hdr_length src[/width] dst[/width]
 602                tos length fragment_id ttl protocol checksum
 603     <ip6-mask> version traffic-class flow-label src dst proto
 604                payload_length hop_limit protocol
 605     l4 tcp <tcp-mask> udp <udp_mask> src_port dst_port
 606     <tcp-mask> src dst  # ports
 607     <udp-mask> src_port dst_port
 608 ```
 609
 610 To construct **matches**, add the values to match after the indicated
 611 keywords in the mask syntax. For example: "... mask l3 ip4 src" ->
 612 "... match l3 ip4 src 192.168.1.11"
 613
 614 ## VPP Packet Generator
 615
 616 We use the VPP packet generator to inject packets into the forwarding
 617 graph. The packet generator can replay pcap traces, and generate packets
 618 out of whole cloth at respectably high performance.
 619
 620 The VPP pg enables quite a variety of use-cases, ranging from functional
 621 testing of new data-plane nodes to regression testing to performance
 622 tuning.
 623
 624 ## PG setup scripts
 625
 626 PG setup scripts describe traffic in detail, and leverage vpp debug
 627 CLI mechanisms. It's reasonably unusual to construct a pg setup script
 628 which doesn't include a certain amount of interface and FIB configuration.
 629
 630 For example:
 631
 632 ```
 633     loop create
 634     set int ip address loop0 192.168.1.1/24
 635     set int state loop0 up
 636
 637     packet-generator new {
 638         name pg0
 639         limit 100
 640         rate 1e6
 641         size 300-300
 642         interface loop0
 643         node ethernet-input
 644         data { IP4: 1.2.3 -> 4.5.6
 645                UDP: 192.168.1.10 - 192.168.1.254 -> 192.168.2.10
 646                UDP: 1234 -> 2345
 647                incrementing 286
 648         }
 649     }
 650 ```
 651
 652 A packet generator stream definition includes two major sections:
 653 - Stream Parameter Setup
 654 - Packet Data
 655
 656 ### Stream Parameter Setup
 657
 658 Given the example above, let's look at how to set up stream
 659 parameters:
 660
 661 - **name pg0** - Name of the stream, in this case "pg0"
 662
 663 - **limit 1000** - Number of packets to send when the stream is
 664 enabled. "limit 0" means send packets continuously.
 665
 666 - **maxframe \<nnn\>** - Maximum frame size. Handy for injecting
 667 multiple frames no larger than \<nnn\>. Useful for checking dual /
 668 quad loop codes
 669
 670 - **rate 1e6** - Packet injection rate, in this case 1 MPPS. When not
 671 specified, the packet generator injects packets as fast as possible
 672
 673 - **size 300-300** - Packet size range, in this case send 300-byte packets
 674
 675 - **interface loop0** - Packets appear as if they were received on the
 676 specified interface. This datum is used in multiple ways: to select
 677 graph arc feature configuration, to select IP FIBs.  Configure
 678 features e.g. on loop0 to exercise those features.
 679
 680 - **tx-interface \<name\>** - Packets will be transmitted on the
 681 indicated interface. Typically required only when injecting packets
 682 into post-IP-rewrite graph nodes.
 683
 684 - **pcap \<filename\>** - Replay packets from the indicated pcap
 685 capture file. "make test" makes extensive use of this feature:
 686 generate packets using scapy, save them in a .pcap file, then inject
 687 them into the vpp graph via a vpp pg "pcap \<filename\>" stream
 688 definition
 689
 690 - **worker \<nn\>** - Generate packets for the stream using the
 691 indicated vpp worker thread. The vpp pg generates and injects O(10
 692 MPPS / core).  Use multiple stream definitions and worker threads to
 693 generate and inject enough traffic to easily fill a 40 gbit pipe with
 694 small packets.
 695
 696 ### Data definition
 697
 698 Packet generator data definitions make use of a layered implementation
 699 strategy. Networking layers are specified in order, and the notation can
 700 seem a bit counter-intuitive. In the example above, the data
 701 definition stanza constructs a set of L2-L4 headers layers, and
 702 uses an incrementing fill pattern to round out the requested 300-byte
 703 packets.
 704
 705 - **IP4: 1.2.3 -> 4.5.6** - Construct an L2 (MAC) header with the ip4
 706 ethertype (0x800), src MAC address of 00:01:00:02:00:03 and dst MAC
 707 address of 00:04:00:05:00:06. Mac addresses may be specified in either
 708 _xxxx.xxxx.xxxx_ format or _xx:xx:xx:xx:xx:xx_ format.
 709
 710 - **UDP: 192.168.1.10 - 192.168.1.254 -> 192.168.2.10** - Construct an
 711 incrementing set of L3 (IPv4) headers for successive packets with
 712 source addresses ranging from .10 to .254. All packets in the stream
 713 have a constant dest address of 192.168.2.10. Set the protocol field
 714 to 17, UDP.
 715
 716 - **UDP: 1234 -> 2345** - Set the UDP source and destination ports to
 717 1234 and 2345, respectively
 718
 719 - **incrementing 256** - Insert up to 256 incrementing data bytes.
 720
 721 Obvious variations involve "s/IP4/IP6/" in the above, along with
 722 changing from IPv4 to IPv6 address notation.
 723
 724 The vpp pg can set any / all IPv4 header fields, including tos, packet
 725 length, mf / df / fragment id and offset, ttl, protocol, checksum, and
 726 src/dst addresses. Take a look at ../src/vnet/ip/ip[46]_pg.c for
 727 details.
 728
 729 If all else fails, specify the entire packet data in hex:
 730
 731 - **hex 0xabcd...** - copy hex data verbatim into the packet
 732
 733 When replaying pcap files ("**pcap \<filename\>**"), do not specify a
 734 data stanza.
 735
 736 ### Diagnosing "packet-generator new" parse failures
 737
 738 If you want to inject packets into a brand-new graph node, remember
 739 to tell the packet generator debug CLI how to parse the packet
 740 data stanza.
 741
 742 If the node expects L2 Ethernet MAC headers, specify ".unformat_buffer
 743 = unformat_ethernet_header":
 744
 745 ```
 746     /* *INDENT-OFF* */
 747     VLIB_REGISTER_NODE (ethernet_input_node) =
 748     {
 749       <snip>
 750       .unformat_buffer = unformat_ethernet_header,
 751       <snip>
 752     };
 753 ```
 754
 755 Beyond that, it may be necessary to set breakpoints in
 756 .../src/vnet/pg/cli.c. Debug image suggested.
 757
 758 When debugging new nodes, it may be far simpler to directly inject
 759 ethernet frames - and add a corresponding vlib_buffer_advance in the
 760 new node - than to modify the packet generator.
 761
 762 ## Debug CLI
 763
 764 The descriptions above describe the "packet-generator new" debug CLI in
 765 detail.
 766
 767 Additional debug CLI commands include:
 768
 769 ```
 770     vpp# packet-generator enable [<stream-name>]
 771 ```
 772
 773 which enables the named stream, or all streams.
 774
 775 ```
 776     vpp# packet-generator disable [<stream-name>]
 777 ```
 778
 779 disables the named stream, or all streams.
 780
 781
 782 ```
 783     vpp# packet-generator delete <stream-name>
 784 ```
 785
 786 Deletes the named stream.
 787
 788 ```
 789     vpp# packet-generator configure <stream-name> [limit <nnn>]
 790          [rate <f64-pps>] [size <nn>-<nn>]
 791 ```
 792
 793 Changes stream parameters without having to recreate the entire stream
 794 definition. Note that re-issuing a "packet-generator new" command will
 795 correctly recreate the named stream.