DOC ONLY: wireshark dissector upstreamed

Remove the last remnant from extra/wireshark, update the Sphinx docs

Change-Id: I5886557f17192475c03fcb0dfde581e1e63cea5c
Signed-off-by: Dave Barach <dave@barachs.net>

diff --git a/docs/gettingstarted/developers/buildwireshark.md b/docs/gettingstarted/developers/buildwireshark.md
index 3da70e9..5d87b7a 100644 (file)
--- a/docs/gettingstarted/developers/buildwireshark.md
+++ b/docs/gettingstarted/developers/buildwireshark.md
@@ -1,27 +1,20 @@
 How to build a vpp dispatch trace aware Wireshark
 =================================================
 
 How to build a vpp dispatch trace aware Wireshark
 =================================================
 

-At some point, we will upstream our vpp pcap dispatch trace dissector.
-It's not finished - contributions welcome - and we have to work through
-whatever issues will be discovered during the upstreaming process.
+The vpp pcap dispatch trace dissector has been merged into the wireshark
+main branch, so the process is simple. Download wireshark, compile it,
+and install it.

 
 

-On the other hand, it's ready for some tire-kicking. Here's how to build
-wireshark.
+Download wireshark source code
+------------------------------

 
 

-Download and patch wireshark source code
------------------------------------------
-
-The wireshark git repo is large, so it takes a while to clone. 
+The wireshark git repo is large, so it takes a while to clone.

 
 ```
 
 ```

-     git clone https://code.wireshark.org/review/wireshark
-     cp .../extras/wireshark/packet-vpp.c wireshark/epan/dissectors
-     patch -p1 < .../extras/wireshark/diffs.txt
+    git clone https://code.wireshark.org/review/wireshark

 ```
 
 ```
 

-The small patch adds packet-vpp.c to the dissector list.
-
-Install prerequisite Debian packages
+Install prerequisite packages

 ------------------------------------
 
 Here is a list of prerequisite packages which must be present in order
 ------------------------------------
 
 Here is a list of prerequisite packages which must be present in order


@@ -29,22 +22,24 @@ to compile wireshark, beyond what's typically installed on an Ubuntu
 18.04 system:
 
 ```
 18.04 system:
 
 ```

-        libgcrypt11-dev flex bison qtbase5-dev qttools5-dev-tools qttools5-dev
-        qtmultimedia5-dev libqt5svg5-dev libpcap-dev qt5-default
+    libgcrypt11-dev flex bison qtbase5-dev qttools5-dev-tools qttools5-dev
+    qtmultimedia5-dev libqt5svg5-dev libpcap-dev qt5-default

 ```
 
 Compile Wireshark
 -----------------
 
 Mercifully, Wireshark uses cmake, so it's relatively easy to build, at
 ```
 
 Compile Wireshark
 -----------------
 
 Mercifully, Wireshark uses cmake, so it's relatively easy to build, at

-least on Ubuntu 18.04. 
+least on Ubuntu 18.04.

 
 
 ```
 
 
 ```

-     $ cd wireshark
-     $ cmake -G Ninja
-     $ ninja -j 8
-     $ sudo ninja install
+    $ cd wireshark
+    $ mkdir build
+    $ cd build
+    $ cmake -G Ninja ../
+    $ ninja -j 8
+    $ sudo ninja install

 ```
 
 Make a pcap dispatch trace
 ```
 
 Make a pcap dispatch trace


@@ -52,11 +47,12 @@ Make a pcap dispatch trace
 
 Configure vpp to pass traffic in some fashion or other, and then:
 
 
 Configure vpp to pass traffic in some fashion or other, and then:
 

+

 ```
     vpp# pcap dispatch trace on max 10000 file vppcapture buffer-trace dpdk-input 1000
 ```
     vpp# pcap dispatch trace on max 10000 file vppcapture buffer-trace dpdk-input 1000

-

 ```
 
 ```
 

+

 or similar. Run traffic for long enough to capture some data. Save the
 dispatch trace capture like so:
 
 or similar. Run traffic for long enough to capture some data. Save the
 dispatch trace capture like so:
 


@@ -73,9 +69,4 @@ dispatch trace pcap files because they won't understand the encap type.
 
 Set wireshark to filter on vpp.bufferindex to watch a single packet
 traverse the forwarding graph. Otherwise, you'll see a vector of packets
 
 Set wireshark to filter on vpp.bufferindex to watch a single packet
 traverse the forwarding graph. Otherwise, you'll see a vector of packets

-in e.g. ip4-lookup, then a vector of packets in ip4-rewrite, etc. 
-
-
-
-
-
+in e.g. ip4-lookup, then a vector of packets in ip4-rewrite, etc.

diff --git a/docs/gettingstarted/developers/vnet.md b/docs/gettingstarted/developers/vnet.md
index 092da1a..d8d9a3b 100644 (file)
--- a/docs/gettingstarted/developers/vnet.md
+++ b/docs/gettingstarted/developers/vnet.md
@@ -54,16 +54,16 @@ units to convert buffer indices to buffer pointers:
      n_left_from = frame->n_vectors;
      from = vlib_frame_vector_args (frame);
 
      n_left_from = frame->n_vectors;
      from = vlib_frame_vector_args (frame);
 

-     /* 
-      * Convert up to VLIB_FRAME_SIZE indices in "from" to 
+     /*
+      * Convert up to VLIB_FRAME_SIZE indices in "from" to

       * buffer pointers in bufs[]
       */
      vlib_get_buffers (vm, from, bufs, n_left_from);
      b = bufs;
      next = nexts;
 
       * buffer pointers in bufs[]
       */
      vlib_get_buffers (vm, from, bufs, n_left_from);
      b = bufs;
      next = nexts;
 

-     /* 
-      * While we have at least 4 vector elements (pkts) to process.. 
+     /*
+      * While we have at least 4 vector elements (pkts) to process..

       */
      while (n_left_from >= 4)
        {
       */
      while (n_left_from >= 4)
        {


@@ -76,7 +76,7 @@ units to convert buffer indices to buffer pointers:
             vlib_prefetch_buffer_header (b[7], STORE);
            }
 
             vlib_prefetch_buffer_header (b[7], STORE);
            }
 

-         /* 
+         /*

           * $$$ Process 4x packets right here...
           * set next[0..3] to send the packets where they need to go
           */
           * $$$ Process 4x packets right here...
           * set next[0..3] to send the packets where they need to go
           */


@@ -91,12 +91,12 @@ units to convert buffer indices to buffer pointers:
         next += 4;
         n_left_from -= 4;
        }
         next += 4;
         n_left_from -= 4;
        }

-     /* 
+     /*

       * Clean up 0...3 remaining packets at the end of the incoming frame
       */
      while (n_left_from > 0)
        {
       * Clean up 0...3 remaining packets at the end of the incoming frame
       */
      while (n_left_from > 0)
        {

-         /* 
+         /*

           * $$$ Process one packet right here...
           * set next[0..3] to send the packets where they need to go
           */
           * $$$ Process one packet right here...
           * set next[0..3] to send the packets where they need to go
           */


@@ -117,7 +117,7 @@ units to convert buffer indices to buffer pointers:
      vlib_buffer_enqueue_to_next (vm, node, from, nexts, frame->n_vectors);
 
      return frame->n_vectors;
      vlib_buffer_enqueue_to_next (vm, node, from, nexts, frame->n_vectors);
 
      return frame->n_vectors;

-   }  
+   }

 ```
 
 Given a packet processing task to implement, it pays to scout around
 ```
 
 Given a packet processing task to implement, it pays to scout around


@@ -150,7 +150,7 @@ tcp_get_free_buffer_index(...) for an example.
 The following example shows the **main points**, but is not to be
 blindly cut-'n-pasted.
 
 The following example shows the **main points**, but is not to be
 blindly cut-'n-pasted.
 

-```c                               
+```c

   u32 bi0;
   vlib_buffer_t *b0;
   ip4_header_t *ip;
   u32 bi0;
   vlib_buffer_t *b0;
   ip4_header_t *ip;


@@ -170,7 +170,7 @@ blindly cut-'n-pasted.
 
   /* At this point b0->current_data = 0, b0->current_length = 0 */
 
 
   /* At this point b0->current_data = 0, b0->current_length = 0 */
 

-  /* 
+  /*

    * Copy data into the buffer. This example ASSUMES that data will fit
    * in a single buffer, and is e.g. an ip4 packet.
    */
    * Copy data into the buffer. This example ASSUMES that data will fit
    * in a single buffer, and is e.g. an ip4 packet.
    */


@@ -179,7 +179,7 @@ blindly cut-'n-pasted.
        clib_memcpy (b0->data, data, vec_len (data));
        b0->current_length = vec_len (data);
      }
        clib_memcpy (b0->data, data, vec_len (data));
        b0->current_length = vec_len (data);
      }

-  else 
+  else

      {
        /* OR, build a udp-ip packet (for example) */
        ip = vlib_buffer_get_current (b0);
      {
        /* OR, build a udp-ip packet (for example) */
        ip = vlib_buffer_get_current (b0);


@@ -204,7 +204,7 @@ blindly cut-'n-pasted.
            udp->checksum = ip4_tcp_udp_compute_checksum (vm, b0, ip);
            if (udp->checksum == 0)
              udp->checksum = 0xffff;
            udp->checksum = ip4_tcp_udp_compute_checksum (vm, b0, ip);
            if (udp->checksum == 0)
              udp->checksum = 0xffff;

-      }  
+      }

       b0->current_length = vec_len (sizeof (*ip) + sizeof (*udp) +
                                    vec_len (udp_data));
 
       b0->current_length = vec_len (sizeof (*ip) + sizeof (*udp) +
                                    vec_len (udp_data));
 


@@ -217,7 +217,7 @@ blindly cut-'n-pasted.
   /* Use the default FIB index for tx lookup. Set non-zero to use another fib */
   vnet_buffer (b0)->sw_if_index[VLIB_TX] = 0;
 
   /* Use the default FIB index for tx lookup. Set non-zero to use another fib */
   vnet_buffer (b0)->sw_if_index[VLIB_TX] = 0;
 

-```  
+```

 
 If your use-case calls for large packet transmission, use
 vlib_buffer_chain_append_data_with_alloc(...) to create the requisite
 
 If your use-case calls for large packet transmission, use
 vlib_buffer_chain_append_data_with_alloc(...) to create the requisite


@@ -239,8 +239,8 @@ indices, and dispatch the frame using vlib_put_frame_to_node(...).
     for (i = 0; i < vec_len (buffer_indices_to_send); i++)
       to_next[i] = buffer_indices_to_send[i];
 
     for (i = 0; i < vec_len (buffer_indices_to_send); i++)
       to_next[i] = buffer_indices_to_send[i];
 

-    vlib_put_frame_to_node (vm, ip4_lookup_node_index, f); 
-``` 
+    vlib_put_frame_to_node (vm, ip4_lookup_node_index, f);
+```

 
 It is inefficient to allocate and schedule single packet frames.
 That's typical in case you need to send one packet per second, but
 
 It is inefficient to allocate and schedule single packet frames.
 That's typical in case you need to send one packet per second, but


@@ -282,7 +282,7 @@ Here's a simple example:
         s = format (s, "My trace data was: %d", t-><whatever>);
 
         return s;
         s = format (s, "My trace data was: %d", t-><whatever>);
 
         return s;

-    } 
+    }

 ```
 
 The trace framework hands the per-node format function the data it
 ```
 
 The trace framework hands the per-node format function the data it


@@ -381,17 +381,17 @@ To save the pcap trace, e.g. in /tmp/dispatch.pcap:
 
 ```
     pcap dispatch trace off
 
 ```
     pcap dispatch trace off

-```    
+```

 
 ### Wireshark dissection of dispatch pcap traces
 
 It almost goes without saying that we built a companion wireshark
 
 ### Wireshark dissection of dispatch pcap traces
 
 It almost goes without saying that we built a companion wireshark

-dissector to display these traces. As of this writing, we're in the
-process of trying to upstream the wireshark dissector.
+dissector to display these traces. As of this writing, we have
+upstreamed the wireshark dissector.

 
 

-Until we manage to upstream the wireshark dissector, please see the
-"How to build a vpp dispatch trace aware Wireshark" page for build
-info, and/or take a look at .../extras/wireshark.
+Since it will be a while before wireshark/master/latest makes it into
+all of the popular Linux distros, please see the "How to build a vpp
+dispatch trace aware Wireshark" page for build info.

 
 Here is a sample packet dissection, with some fields omitted for
 clarity.  The point is that the wireshark dissector accurately
 
 Here is a sample packet dissection, with some fields omitted for
 clarity.  The point is that the wireshark dissector accurately


@@ -406,15 +406,15 @@ node in question.
         BufferIndex: 0x00036663
     NodeName: ethernet-input
     VPP Buffer Metadata
         BufferIndex: 0x00036663
     NodeName: ethernet-input
     VPP Buffer Metadata

-        Metadata: flags: 
+        Metadata: flags:

         Metadata: current_data: 0, current_length: 102
         Metadata: current_config_index: 0, flow_id: 0, next_buffer: 0
         Metadata: error: 0, n_add_refs: 0, buffer_pool_index: 0
         Metadata: trace_index: 0, recycle_count: 0, len_not_first_buf: 0
         Metadata: free_list_index: 0
         Metadata: current_data: 0, current_length: 102
         Metadata: current_config_index: 0, flow_id: 0, next_buffer: 0
         Metadata: error: 0, n_add_refs: 0, buffer_pool_index: 0
         Metadata: trace_index: 0, recycle_count: 0, len_not_first_buf: 0
         Metadata: free_list_index: 0

-        Metadata: 
+        Metadata:

     VPP Buffer Opaque
     VPP Buffer Opaque

-        Opaque: raw: 00000007 ffffffff 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
+        Opaque: raw: 00000007 ffffffff 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000

         Opaque: sw_if_index[VLIB_RX]: 7, sw_if_index[VLIB_TX]: -1
         Opaque: L2 offset 0, L3 offset 0, L4 offset 0, feature arc index 0
         Opaque: ip.adj_index[VLIB_RX]: 0, ip.adj_index[VLIB_TX]: 0
         Opaque: sw_if_index[VLIB_RX]: 7, sw_if_index[VLIB_TX]: -1
         Opaque: L2 offset 0, L3 offset 0, L4 offset 0, feature arc index 0
         Opaque: ip.adj_index[VLIB_RX]: 0, ip.adj_index[VLIB_TX]: 0


@@ -443,14 +443,14 @@ node in question.
         Opaque: sctp.connection_index: 0, sctp.sid: 0, sctp.ssn: 0, sctp.tsn: 0, sctp.hdr_offset: 0
         Opaque: sctp.data_offset: 0, sctp.data_len: 0, sctp.subconn_idx: 0, sctp.flags: 0x0
         Opaque: snat.flags: 0x0
         Opaque: sctp.connection_index: 0, sctp.sid: 0, sctp.ssn: 0, sctp.tsn: 0, sctp.hdr_offset: 0
         Opaque: sctp.data_offset: 0, sctp.data_len: 0, sctp.subconn_idx: 0, sctp.flags: 0x0
         Opaque: snat.flags: 0x0

-        Opaque: 
+        Opaque:

     VPP Buffer Opaque2
     VPP Buffer Opaque2

-        Opaque2: raw: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
+        Opaque2: raw: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000

         Opaque2: qos.bits: 0, qos.source: 0
         Opaque2: loop_counter: 0
         Opaque2: gbp.flags: 0, gbp.src_epg: 0
         Opaque2: pg_replay_timestamp: 0
         Opaque2: qos.bits: 0, qos.source: 0
         Opaque2: loop_counter: 0
         Opaque2: gbp.flags: 0, gbp.src_epg: 0
         Opaque2: pg_replay_timestamp: 0

-        Opaque2: 
+        Opaque2:

     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
         Source Port: 22432
         Destination Port: 54084
     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
         Source Port: 22432
         Destination Port: 54084


@@ -472,4 +472,3 @@ metadata changes, header checksum changes, and so forth.
 This should be of significant value when developing new vpp graph
 nodes. If new code mispositions b->current_data, it will be completely
 obvious from looking at the dispatch trace in wireshark.
 This should be of significant value when developing new vpp graph
 nodes. If new code mispositions b->current_data, it will be completely
 obvious from looking at the dispatch trace in wireshark.

-

diff --git a/extras/wireshark/readme.md b/extras/wireshark/readme.md
deleted file mode 100644 (file)
index fe4fdbf..0000000
--- a/extras/wireshark/readme.md
+++ /dev/null
@@ -1,84 +0,0 @@
-How to build a vpp dispatch trace aware Wireshark
-=================================================
-
-We have upstreamed our vpp pcap dispatch trace dissector. After
-working through a laundry list of issues discovered during the
-upstreaming process, it appears that the code is close to being
-merged. See https://code.wireshark.org/review/#/c/31466.
-
-As of this writing, the simplest way to build a vpp dispatch trace
-aware wireshark is to clone the wireshark repo, and apply the vpp
-dissector patch.
-
-
-Download wireshark source code
-------------------------------
-
-The wireshark git repo is large, so it takes a while to clone.
-
-```
-     git clone https://code.wireshark.org/review/wireshark
-```
-
-Download Gerrit 31466 using the URL shown above. If you have "git
-review" set up, it's as simple as "git review -d 31466" in the wireshark
-workspace.
-
-Alternatively, download a patch-file from the gerrit server and apply
-the patch.
-
-Install prerequisite Debian packages
-------------------------------------
-
-Here is a list of prerequisite packages which must be present in order
-to compile wireshark, beyond what's typically installed on an Ubuntu
-18.04 system:
-
-```
-        libgcrypt11-dev flex bison qtbase5-dev qttools5-dev-tools qttools5-dev
-        qtmultimedia5-dev libqt5svg5-dev libpcap-dev qt5-default
-```
-
-Compile Wireshark
------------------
-
-Wireshark uses cmake, so it's relatively easy to build, at least on
-Ubuntu 18.04.
-
-```
-     $ cd wireshark
-     $ mkdir build
-     $ cd build
-     $ cmake -G Ninja ../
-     $ ninja -j 8
-     $ sudo ninja install
-```
-
-Make a pcap dispatch trace
---------------------------
-
-Configure vpp to pass traffic in some fashion or other, and then:
-
-```
-    vpp# pcap dispatch trace on max 10000 file vppcapture buffer-trace dpdk-input 1000
-
-```
-
-or similar. Run traffic for long enough to capture some data. Save the
-dispatch trace capture like so:
-
-```
-    vpp# pcap dispatch trace off
-```
-
-Display in Wireshark
---------------------
-
-Display /tmp/vppcapture in the vpp-enabled version of wireshark.
-Normal version of wireshark will refuse to process vpp dispatch trace
-pcap files because they won't understand the encap type.
-
-Set wireshark to filter on vpp.bufferindex to watch a single packet
-traverse the forwarding graph. Otherwise, you'll see a vector of
-packets in e.g. ip4-lookup, then a vector of packets in ip4-rewrite,
-etc.