[spp] [PATCH 12/20] docs: move usecase of spp_pcap

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

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

This update is to move usecase of spp_pcap from `SPP VF`.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/spp_vf/index.rst                 |   3 +-
 docs/guides/spp_vf/use_cases/index.rst       |  10 --
 docs/guides/spp_vf/use_cases/pcap_simple.rst | 235 --------------------------
 docs/guides/use_cases/index.rst              |   1 +
 docs/guides/use_cases/spp_pcap.rst           | 238 +++++++++++++++++++++++++++
 5 files changed, 240 insertions(+), 247 deletions(-)
 delete mode 100644 docs/guides/spp_vf/use_cases/index.rst
 delete mode 100644 docs/guides/spp_vf/use_cases/pcap_simple.rst
 create mode 100644 docs/guides/use_cases/spp_pcap.rst

diff --git a/docs/guides/spp_vf/index.rst b/docs/guides/spp_vf/index.rst
index 412952c..27ab16b 100644
--- a/docs/guides/spp_vf/index.rst
+++ b/docs/guides/spp_vf/index.rst
@@ -5,8 +5,7 @@ SPP VF
 ===========
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :numbered:
 
-   use_cases/index
    explain/index
diff --git a/docs/guides/spp_vf/use_cases/index.rst b/docs/guides/spp_vf/use_cases/index.rst
deleted file mode 100644
index 59125f4..0000000
--- a/docs/guides/spp_vf/use_cases/index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
-
-Use Cases
-=========
-
-.. toctree::
-   :maxdepth: 2
-
-   pcap_simple
diff --git a/docs/guides/spp_vf/use_cases/pcap_simple.rst b/docs/guides/spp_vf/use_cases/pcap_simple.rst
deleted file mode 100644
index 34efce3..0000000
--- a/docs/guides/spp_vf/use_cases/pcap_simple.rst
+++ /dev/null
@@ -1,235 +0,0 @@
-..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
-
-
-.. _spp_pcap_use_case:
-
-Packet Capture with 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%
-
-    Packet capture with spp_pcap
-
-
-.. _spp_pcap_use_case_launch_pcap:
-
-Launch spp_pcap
-~~~~~~~~~~~~~~~
-
-Change directory if you are not in SPP's directory,
-and compile if not done yet.
-
-.. code-block:: console
-
-    $ cd /path/to/spp
-
-Launch spp-ctl and SPP CLI in different terminals.
-
-.. code-block:: console
-
-    # 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`` with one physical port.
-
-.. code-block:: console
-
-    # terminal 3
-    $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \
-        -l 0 -n 4 \
-        --socket-mem 512,512 \
-        --huge-dir /run/hugepages/kvm \
-        --proc-type primary \
-        -- \
-        -p 0x01 \
-        -n 8 -s 192.168.1.100:5555
-
-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
-
-    # terminal 4
-    $ sudo ./src/pcap/x86_64-native-linuxapp-gcc/spp_pcap \
-       -l 1-6 -n 4 --proc-type=secondary \
-       -- \
-       --client-id 1 -s 192.168.1.100:6666 \
-       -c phy:0
-
-You can confirm lcores and worker threads running on from ``status`` command.
-
-.. code-block:: none
-
-    # 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:
-
-
-.. _spp_pcap_use_case_start_capture:
-
-Start Capture
-~~~~~~~~~~~~~
-
-If you already started to send packets to ``phy:0`` from outside,
-you are ready to start capturing packets.
-
-.. code-block:: none
-
-    # terminal 2
-    spp > pcap 1; start
-    Start packet capture.
-
-As you run ``start`` command, PCAP files are generated for each of
-``writer`` threads for capturing.
-
-.. code-block:: none
-
-    # 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
-
-
-.. _spp_pcap_use_case_stop_capture:
-
-Stop Capture
-~~~~~~~~~~~~
-
-Stop capturing and confirm that compressed PCAP files are generated.
-
-.. code-block:: none
-
-    # 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
-    ....
-
-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.
-
-
-.. _spp_pcap_use_case_shutdown:
-
-Shutdown spp_pcap
-~~~~~~~~~~~~~~~~~
-
-Run ``exit`` or ``bye sec`` command to terminate ``spp_pcap``.
-
-.. code-block:: none
-
-    # 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
-
-    # 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
-^^^^^^^^^^^^^^^^^
-
-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
-
-    # 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 [.], ...
diff --git a/docs/guides/use_cases/index.rst b/docs/guides/use_cases/index.rst
index 1422045..f67ea5d 100644
--- a/docs/guides/use_cases/index.rst
+++ b/docs/guides/use_cases/index.rst
@@ -11,4 +11,5 @@ Use Cases
    spp_nfv
    spp_vf
    spp_mirror
+   spp_pcap
    multi_nodes
diff --git a/docs/guides/use_cases/spp_pcap.rst b/docs/guides/use_cases/spp_pcap.rst
new file mode 100644
index 0000000..cfc1fea
--- /dev/null
+++ b/docs/guides/use_cases/spp_pcap.rst
@@ -0,0 +1,238 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
+
+
+.. _spp_usecases_pcap:
+
+spp_pcap
+========
+
+Packet Capture
+--------------
+
+This section describes a usecase for capturing packets with ``spp_pcap``.
+See 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%
+
+    Packet capture with spp_pcap
+
+
+.. _spp_pcap_use_case_launch_pcap:
+
+Launch spp_pcap
+~~~~~~~~~~~~~~~
+
+Change directory if you are not in SPP's directory,
+and compile if not done yet.
+
+.. code-block:: console
+
+    $ cd /path/to/spp
+
+Launch spp-ctl and SPP CLI in different terminals.
+
+.. code-block:: console
+
+    # 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`` with one physical port.
+
+.. code-block:: console
+
+    # terminal 3
+    $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \
+        -l 0 -n 4 \
+        --socket-mem 512,512 \
+        --huge-dir /run/hugepages/kvm \
+        --proc-type primary \
+        -- \
+        -p 0x01 \
+        -n 8 -s 192.168.1.100:5555
+
+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
+
+    # terminal 4
+    $ sudo ./src/pcap/x86_64-native-linuxapp-gcc/spp_pcap \
+       -l 1-6 -n 4 --proc-type=secondary \
+       -- \
+       --client-id 1 -s 192.168.1.100:6666 \
+       -c phy:0
+
+You can confirm lcores and worker threads running on from ``status`` command.
+
+.. code-block:: none
+
+    # 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:
+
+
+.. _spp_pcap_use_case_start_capture:
+
+Start Capture
+~~~~~~~~~~~~~
+
+If you already started to send packets to ``phy:0`` from outside,
+you are ready to start capturing packets.
+
+.. code-block:: none
+
+    # terminal 2
+    spp > pcap 1; start
+    Start packet capture.
+
+As you run ``start`` command, PCAP files are generated for each of
+``writer`` threads for capturing.
+
+.. code-block:: none
+
+    # 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
+
+
+.. _spp_pcap_use_case_stop_capture:
+
+Stop Capture
+~~~~~~~~~~~~
+
+Stop capturing and confirm that compressed PCAP files are generated.
+
+.. code-block:: none
+
+    # 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
+    ....
+
+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.
+
+
+.. _spp_pcap_use_case_shutdown:
+
+Shutdown spp_pcap
+~~~~~~~~~~~~~~~~~
+
+Run ``exit`` or ``bye sec`` command to terminate ``spp_pcap``.
+
+.. code-block:: none
+
+    # 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
+
+    # 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
+^^^^^^^^^^^^^^^^^
+
+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
+
+    # 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.7.4