diff options
| -rw-r--r-- | docs/gettingstarted/developers/buildwireshark.md | 49 | ||||
| -rw-r--r-- | docs/gettingstarted/developers/vnet.md | 57 | ||||
| -rw-r--r-- | extras/wireshark/readme.md | 84 |
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. |