[spp] [PATCH 6/6] docs: update usecase of spp_pcap

[ogawa.yasufumi@lab.ntt.co.jp]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

This patch is to revise usecase of spp_pcap.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/spp_vf/use_cases/pcap_simple.rst | 253 ++++++++++++-------
 1 file changed, 162 insertions(+), 91 deletions(-)

diff --git a/docs/guides/spp_vf/use_cases/pcap_simple.rst b/docs/guides/spp_vf/use_cases/pcap_simple.rst
index c31324e..34efce3 100644
--- a/docs/guides/spp_vf/use_cases/pcap_simple.rst
+++ b/docs/guides/spp_vf/use_cases/pcap_simple.rst
@@ -1,164 +1,235 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
 
-.. _spp_pcap_use_case:
-
-Packet Capture
-==============
 
+.. _spp_pcap_use_case:
 
-This section describes a usecase for Packet Capture through ``spp_pcap``.
+Packet Capture with spp_pcap
+============================
 
-Incoming packets received by ``phy:0`` is captured by ``spp_pcap``.
+This section describes a usecase for capturing packets with ``spp_pcap``
+and seeing inside of the captured file with ``tcpdump`` command.
+:numref:`figure_simple_capture` shows the overview of scenario in which
+incoming packets via ``phy:0`` are dumped as compressed pcap files by using
+``spp_pcap``.
 
 .. _figure_simple_capture:
 
 .. figure:: ../../images/spp_vf/spp_pcap_overview.*
     :width: 50%
 
-    Simple Packet Capture
+    Packet capture with spp_pcap
+
+
+.. _spp_pcap_use_case_launch_pcap:
 
 Launch spp_pcap
 ~~~~~~~~~~~~~~~
 
-Change directory to spp and confirm that it is already compiled.
+Change directory if you are not in SPP's directory,
+and compile if not done yet.
 
 .. code-block:: console
 
     $ cd /path/to/spp
 
-As spp, launch spp-ctl and spp.py first.
+Launch spp-ctl and SPP CLI in different terminals.
 
 .. code-block:: console
 
-    # Launch spp-ctl and spp.py
-    $ python3 ./src/spp-ctl/spp-ctl -b 127.0.0.1
-    $ python ./src/spp.py -b 127.0.0.1
+    # terminal 1
+    $ python3 ./src/spp-ctl/spp-ctl -b 192.168.1.100
+
+.. code-block:: console
+
+    # terminal 2
+    $ python3 ./src/spp.py -b 192.168.1.100
 
 
-Then, run ``spp_primary``.
+Then, run ``spp_primary`` with one physical port.
 
 .. code-block:: console
 
+    # terminal 3
     $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \
-        -c 0x02 -n 4 \
+        -l 0 -n 4 \
         --socket-mem 512,512 \
-        --huge-dir=/run/hugepages/kvm \
-        --proc-type=primary \
+        --huge-dir /run/hugepages/kvm \
+        --proc-type primary \
         -- \
-        -p 0x03 -n 8 -s 127.0.0.1:5555
+        -p 0x01 \
+        -n 8 -s 192.168.1.100:5555
 
-After ``spp_primary`` is launched, run secondary process ``spp_pcap``.
-If not ``--output`` directory is not created, please create it first.
+After ``spp_primary`` is launched successfully, run ``spp_pcap`` in other
+terminal. In this usecase, you use default values for optional arguments.
+Output directory of captured file is ``/tmp`` and the size of file is
+``1GiB``.
+You notice that six lcores are assigned with ``-l 1-6``.
+It means that you use one locre for master, one for receiver, and four for
+writer threads.
 
 .. code-block:: console
 
-    $ sudo mkdir /mnt/pcap
+    # terminal 4
     $ sudo ./src/pcap/x86_64-native-linuxapp-gcc/spp_pcap \
-       -l 0-4 -n 4 --proc-type=secondary \
+       -l 1-6 -n 4 --proc-type=secondary \
        -- \
-       --client-id 1 -s 127.0.0.1:6666 \
-       -i phy:0 --output /mnt/pcap --limit_file_size 1073741824
+       --client-id 1 -s 192.168.1.100:6666 \
+       -c phy:0
 
-Start capturing
-~~~~~~~~~~~~~~~
-When you want to start capture, then type the following command.
+You can confirm lcores and worker threads running on from ``status`` command.
 
-.. code-block:: console
+.. code-block:: none
 
-    spp > pcap SEC_ID; start
+    # terminal 2
+    spp > pcap 1; status
+      - client-id: 1
+      - status: idle
+      - core:2 receive
+        - rx: phy:0
+      - core:3 write
+        - filename:
+      - core:4 write
+        - filename:
+      - core:5 write
+        - filename:
+      - core:6 write
+        - filename:
 
-In this usecase, spp_pcap is launched with ID=1. Let's start capturing.
 
-.. code-block:: console
+.. _spp_pcap_use_case_start_capture:
 
-    # Start packet capture
-    spp > pcap 1;start
+Start Capture
+~~~~~~~~~~~~~
 
-Stop capturing
-~~~~~~~~~~~~~~
+If you already started to send packets to ``phy:0`` from outside,
+you are ready to start capturing packets.
 
-When you want to stop capture, then type the following command.
+.. code-block:: none
 
-.. code-block:: console
+    # terminal 2
+    spp > pcap 1; start
+    Start packet capture.
 
-    spp > pcap SEC_ID; stop
+As you run ``start`` command, PCAP files are generated for each of
+``writer`` threads for capturing.
 
-In this usecase, spp_pcap is launched with ID=1. Let's stop capturing.
+.. code-block:: none
 
-.. code-block:: console
+    # terminal 2
+    spp > pcap 1; status
+      - client-id: 1
+      - status: running
+      - core:2 receive
+        - rx: phy:0
+      - core:3 write
+        - filename: /tmp/spp_pcap.20190214161550.phy0.1.1.pcap.lz4
+      - core:4 write
+        - filename: /tmp/spp_pcap.20190214161550.phy0.2.1.pcap.lz4
+      - core:5 write
+        - filename: /tmp/spp_pcap.20190214161550.phy0.3.1.pcap.lz4
+      - core:6 write
+        - filename: /tmp/spp_pcap.20190214161550.phy0.4.1.pcap.lz4
 
-    # Stop packet capture
-    spp > pcap 1;stop
 
+.. _spp_pcap_use_case_stop_capture:
 
-Now, you can see capture file written in specified directory.
+Stop Capture
+~~~~~~~~~~~~
 
-.. code-block:: console
+Stop capturing and confirm that compressed PCAP files are generated.
 
-    # show the content of directry
-    $ cd /mnt/pcap
-    $ ls
-      spp_pcap.20181108110600.phy0.1.1.pcap.lz4
-      spp_pcap.20181108110600.phy0.2.1.pcap.lz4
-      spp_pcap.20181108110600.phy0.3.1.pcap.lz4
+.. code-block:: none
 
-Each files are compressed using LZ4, so that to uncompress it,
-use lz4 utils.
+    # terminal 2
+    spp > pcap 1; stop
+    spp > ls /tmp
+    ....
+    spp_pcap.20190214175446.phy0.1.1.pcap.lz4
+    spp_pcap.20190214175446.phy0.1.2.pcap.lz4
+    spp_pcap.20190214175446.phy0.1.3.pcap.lz4
+    spp_pcap.20190214175446.phy0.2.1.pcap.lz4
+    spp_pcap.20190214175446.phy0.2.2.pcap.lz4
+    spp_pcap.20190214175446.phy0.2.3.pcap.lz4
+    ....
 
-.. code-block:: console
-
-    # uncompress lz4 files
-    $ sudo lz4 -d -m spp_pcap.20181108110600.phy0.*
-    $ ls
-      spp_pcap.20181108110600.phy0.1.1.pcap
-      spp_pcap.20181108110600.phy0.2.1.pcap
-      spp_pcap.20181108110600.phy0.3.1.pcap
-      spp_pcap.20181108110600.phy0.1.1.pcap.lz4
-      spp_pcap.20181108110600.phy0.2.1.pcap.lz4
-      spp_pcap.20181108110600.phy0.3.1.pcap.lz4
-
-To combine those divided pcap files using mergecap utility.
-
-.. code-block:: console
+Index in the filename, such as ``1.1`` or ``1.2``, is a combination of
+``writer`` thread ID and sequenceal number.
+In this case, it means each of four threads generate three files.
 
-    # merge pcap files
-    $ sudo mergecap spp_pcap.20181108110600.phy0.1.1.pcap \
-      spp_pcap.20181108110600.phy0.2.1.pcap \
-      spp_pcap.20181108110600.phy0.3.1.pcap \
-      -w test.pcap
-    $ ls
-      spp_pcap.20181108110600.phy0.1.1.pcap
-      spp_pcap.20181108110600.phy0.2.1.pcap
-      spp_pcap.20181108110600.phy0.3.1.pcap
-      spp_pcap.20181108110600.phy0.1.1.pcap.lz4
-      spp_pcap.20181108110600.phy0.2.1.pcap.lz4
-      spp_pcap.20181108110600.phy0.3.1.pcap.lz4
-      test.pcap
 
 .. _spp_pcap_use_case_shutdown:
 
 Shutdown spp_pcap
 ~~~~~~~~~~~~~~~~~
 
-Basically, you can shutdown all of SPP processes with ``bye all``
-command.
+Run ``exit`` or ``bye sec`` command to terminate ``spp_pcap``.
 
-This section describes graceful shutting down for ``spp_pcap``.
+.. code-block:: none
 
-First, stop capturing using the following command if it is not
-already stopped.
+    # terminal 2
+    spp > pcap 1; exit
+
+
+.. _spp_pcap_use_case_inspect_file:
+
+Inspect PCAP Files
+~~~~~~~~~~~~~~~~~~
+
+You can inspect captured PCAP files by using utilities.
+
+Merge PCAP Files
+^^^^^^^^^^^^^^^^
+
+Extract and merge compressed PCAP files.
+
+For extract several LZ4 files at once, use ``-d`` and ``-m`` options.
+``-d`` is for decompression and ``-m`` is for multiple files.
+
+You had better not to merge divided files into single file, but still
+several files because the size of merged file might be huge.
+Each of extracted PCAP file is 1GiB in default, so total size of extracted
+files is 12GiB in this case. To avoid the situation, merge files for each of
+threads and generate four PCAP files of 3GiB.
+
+First, extract LZ4 files of writer thread ID 1.
 
 .. code-block:: console
 
-    # Stop packet capture
-    spp > pcap 1;stop
+    # terminal 4
+    $ lz4 -d -m /tmp/spp_pcap.20190214175446.phy0.1.*
+
+And confirm that the files are extracted.
+
+.. code-block:: console
+
+    # terminal 4
+    $ ls /tmp | grep pcap$
+    spp_pcap.20190214175446.phy0.1.1.pcap
+    spp_pcap.20190214175446.phy0.1.2.pcap
+    spp_pcap.20190214175446.phy0.1.3.pcap
+
+Run ``mergecap`` command to merge extracted files to current directory
+as ``spp_pcap1.pcap``.
+
+.. code-block:: console
+
+    # terminal 4
+    $ mergecap /tmp/spp_pcap.20190214175446.phy0.1.*.pcap -w spp_pcap1.pcap
+
+Inspect PCAP file
+^^^^^^^^^^^^^^^^^
 
-If you want to start capture again then use ``start`` command again.
-Else if you want to quit ``spp_pcap`` itself, type the following command
-and quit application.
+You can use any of applications, for instance ``wireshark`` or ``tcpdump``,
+for inspecting PCAP file.
+To inspect the merged PCAP file, read packet data from ``tcpdump`` command
+in this usecase. ``-r`` option is to dump packet data in human readable format.
 
 .. code-block:: console
 
-    # Exit packet capture
-    spp > pcap 1;exit
+    # terminal 4
+    $ tcpdump -r spp_pcap1.pcap | less
+    17:54:52.559783 IP 192.168.0.100.1234 > 192.168.1.1.5678: Flags [.], ...
+    17:54:52.559784 IP 192.168.0.100.1234 > 192.168.1.1.5678: Flags [.], ...
+    17:54:52.559785 IP 192.168.0.100.1234 > 192.168.1.1.5678: Flags [.], ...
+    17:54:52.559785 IP 192.168.0.100.1234 > 192.168.1.1.5678: Flags [.], ...
-- 
2.17.1