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>

3 files changed, 48 insertions, 142 deletions

diff --git a/docs/gettingstarted/developers/buildwireshark.md b/docs/gettingstarted/developers/buildwireshark.md
index 3da70e9e0ba..5d87b7a9b7b 100644
--- 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
 =================================================
 
-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
@@ -29,22 +22,24 @@ 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
+    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
-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
@@ -52,11 +47,12 @@ 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:
 
@@ -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
-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 092da1a28a6..d8d9a3b4fec 100644
--- 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);
 
-     /* 
-      * 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;
 
-     /* 
-      * 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)
        {
@@ -76,7 +76,7 @@ units to convert buffer indices to buffer pointers:
    	     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
           */
@@ -91,12 +91,12 @@ units to convert buffer indices to buffer pointers:
    	 next += 4;
    	 n_left_from -= 4;
    	}
-     /* 
+     /*
       * 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
           */
@@ -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;
-   }  
+   }
 ```
 
 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.
 
-```c                               
+```c
   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 */
 
-  /* 
+  /*
    * 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);
      }
-  else 
+  else
      {
        /* 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;
-      }  
+      }
       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;
 
-```  
+```
 
 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];
 
-    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
@@ -282,7 +282,7 @@ Here's a simple example:
         s = format (s, "My trace data was: %d", t-><whatever>);
 
         return s;
-    } 
+    }
 ```
 
 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
-```    
+```
 
 ### 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
@@ -406,15 +406,15 @@ node in question.
         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: 
+        Metadata:
     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
@@ -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: 
+        Opaque:
     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: 
+        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
@@ -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.
-
diff --git a/extras/wireshark/readme.md b/extras/wireshark/readme.md
deleted file mode 100644
index fe4fdbfeb5a..00000000000
--- 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.