[spp] [PATCH 3/6] docs: add spp_pcap document of design

[x-fn-spp at sl.ntt-tx.co.jp]

From: Hideyuki Yamashita <yamashita.hideyuki at po.ntt-tx.co.jp>

Add spp_pcap document of design.

Signed-off-by: Hideyuki Yamashita <yamashita.hideyuki at po.ntt-tx.co.jp>
Signed-off-by: Naoki Takada <takada.naoki at lab.ntt.co.jp>
---
 docs/guides/spp_vf/design.rst        | 98 +++++++++++++++++++++++++++-
 docs/guides/spp_vf/gsg/howto_use.rst | 39 +++++++++--
 2 files changed, 129 insertions(+), 8 deletions(-)

diff --git a/docs/guides/spp_vf/design.rst b/docs/guides/spp_vf/design.rst
index 8b9e7f3..0f3e5c8 100644
--- a/docs/guides/spp_vf/design.rst
+++ b/docs/guides/spp_vf/design.rst
@@ -1,5 +1,5 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2010-2014 Intel Corporation
+    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
 
 .. _spp_vf_design:
 
@@ -98,3 +98,99 @@ than ``deepcopy``, but it should be used for read only for the packet.
 
 You should choose ``deepcopy`` if you use VLAN feature to make no change for
 original packet while copied packet is modified.
+
+.. _spp_vf_design_spp_pcap:
+
+spp_pcap
+--------
+``spp_pcap`` cosisits of main thread, ``receiver`` thread runs on a core of
+the second smallest ID and ``wirter`` threads on the rest of cores. You should
+have enough cores if you need to capture large amount of packets.
+
+``spp_pcap`` has 4 types of command. ``start``,``stop``,``exit`` and ``status``
+to control behavior of ``spp_pcap``.
+
+With ``start`` command, you can start capturing.
+Incoming packets are received by ``receiver`` thread and it is transferred to
+``writer`` thread(s) via multi-producer/multi-consumer ring.
+Multi-producer/multi-consumer ring is the ring which multiple producers
+can enqueue and multiple consumers can dequeue. When those packets are
+received by ``writer`` thread(s), it will be compressed using LZ4 library and
+then be written to storage. In case more than 1 cores are assigned,
+incoming packets are written into storage per core basis so packet capture file
+will be divided per core.
+When ``spp_pcap`` has already been started, ``start`` command cannot
+be accepted.
+
+With ``stop`` command, capture will be stopped. When spp_pcap has already
+been stopped, ``stop`` command cannot be accepted.
+
+With ``exit`` command, ``spp_pcap`` exits the program. ``exit`` command
+during started state, stops capturing and then exits the program.
+
+With ``status`` command, status related to ``spp_pcap`` is shown.
+
+In :numref:`figure_spp_pcap_design`,
+the internal structure of ``spp_pcap`` is shown.
+
+.. _figure_spp_pcap_design:
+
+.. figure:: ../images/spp_pcap/spp_pcap_design.*
+    :width: 55%
+
+    spp_pcap internal structure
+
+.. _spp_pcap_design_output_file_format:
+
+:numref:`figure_spp_pcap_design` shows the case when ``spp_pcap`` is connected
+with ``phy:0``.
+There is only one ``receiver`` thread and multiple ``writer`` threads.
+Each ``writer`` writes packets into file.
+Once exceeds maximum file size ,
+it creates new file so that multiple output files are created.
+
+
+Apptication option
+^^^^^^^^^^^^^^^^^^
+
+``spp_pcap`` specific options are:
+
+ * -client-id: client id which can be seen as secondary ID from spp.py.
+ * -s: IPv4 address and port for spp-ctl.
+ * -i: port to which spp_pcap attached with.
+ * --output: Output file path
+   where capture files are written.\
+   When this parameter is omitted,
+   ``/tmp`` is used.
+ * --port_name: port_name which can be specified as
+   either of phy:N or \
+   ring:N.
+   When used as part of file name ``:`` is removed to avoid misconversion.
+ * --limit_file_option: Maximum size of a capture file.
+   Default value is ``1GiB``.Captured files are not deleted automatically
+   because file rotation is not supported.
+
+The output file format is as following:
+
+.. code-block:: none
+
+    spp_pcap.YYYYMMDDhhmmss.[port_name].[wcore_num]
+    wcore_num is write core number which starts with 1
+
+Each ``writer`` thread has
+unique integer number which is used to determine the name of capture file.
+YYYYMMDDhhmmss is the time when ``spp_pcap`` receives ``start`` command.
+
+.. code-block:: none
+
+    /tmp/spp_pcap.20181108110600.ring0.1.2.pcap.lz4.tmp
+This example shows that ``receiver`` thread receives ``start`` command at
+20181108110600.  Port is ring:0, wcore_num is 1 and sequential number is 2.
+
+
+Until writing is finished, packets are stored into temporary file.
+The example is as following:
+
+.. code-block:: none
+
+    /tmp/spp_pcap.20181108110600.ring0.1.2.pcap.lz4.tmp
diff --git a/docs/guides/spp_vf/gsg/howto_use.rst b/docs/guides/spp_vf/gsg/howto_use.rst
index 750de13..dc1a7bb 100644
--- a/docs/guides/spp_vf/gsg/howto_use.rst
+++ b/docs/guides/spp_vf/gsg/howto_use.rst
@@ -1,5 +1,5 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2010-2014 Intel Corporation
+    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
 
 .. _spp_vf_gsg_howto_use:
 
@@ -80,9 +80,12 @@ DPDK, the other is ``spp_vf``.
 .. code-block:: console
 
     $ sudo ./src/vf/x86_64-native-linuxapp-gcc/spp_vf \
-    -l 0,2-13 -n 4 --proc-type=secondary \
-    -- \
-    --client-id 1 -s 127.0.0.1:6666 --vhost-client
+      -l 0,2-13 -n 4 \
+      --proc-type=secondary \
+      -- \
+      --client-id 1 \
+      -s 127.0.0.1:6666 \
+      --vhost-client
 
 If ``--vhost-client`` option is specified, then ``vhost-user`` act as
 the client, otherwise the server.
@@ -102,9 +105,31 @@ spp_mirror
 .. code-block:: console
 
     $ sudo ./src/mirror/x86_64-native-linuxapp-gcc/spp_mirror \
-    -l 2 -n 4 --proc-type=secondary \
-    -- \
-    --client-id 1 -s 127.0.0.1:6666 --vhost-client
+      -l 2 -n 4 \
+      --proc-type=secondary \
+      -- \
+      --client-id 1 \
+      -s 127.0.0.1:6666 \
+      -vhost-client
+
+.. _spp_vf_gsg_howto_use_spp_pcap:
+
+spp_pcap
+--------
+
+After run ``spp_primary`` is launched, run secondary process ``spp_pcap``.
+
+.. code-block:: console
+
+    $ sudo ./src/pcap/x86_64-native-linuxapp-gcc/spp_pcap \
+      -l 0-3 -n 4 \
+      --proc-type=secondary \
+      -- \
+      --client-id 1 \
+      -s 127.0.0.1:6666 \
+      -i phy:0 \
+      --output /mnt/pcap \
+      --limit_file_size 107374182
 
 VM
 --
-- 
2.17.1