[spp] [PATCH 1/6] docs: add command reference of spp_pcap

[spp] [PATCH 1/6] docs: add command reference of spp_pcap

[x-fn-spp]

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

Add command reference of spp_pcap.

Signed-off-by: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>
Signed-off-by: Naoki Takada <takada.naoki@lab.ntt.co.jp>
---
 docs/guides/commands/secondary/index.rst    |   1 +
 docs/guides/commands/secondary/spp_pcap.rst | 158 ++++++++++++++++++++
 2 files changed, 159 insertions(+)
 create mode 100644 docs/guides/commands/secondary/spp_pcap.rst

diff --git a/docs/guides/commands/secondary/index.rst b/docs/guides/commands/secondary/index.rst
index 5544aea..006e58d 100644
--- a/docs/guides/commands/secondary/index.rst
+++ b/docs/guides/commands/secondary/index.rst
@@ -10,3 +10,4 @@ Secondary Commands
    spp_nfv
    spp_vf
    spp_mirror
+   spp_pcap
diff --git a/docs/guides/commands/secondary/spp_pcap.rst b/docs/guides/commands/secondary/spp_pcap.rst
new file mode 100644
index 0000000..33882f0
--- /dev/null
+++ b/docs/guides/commands/secondary/spp_pcap.rst
@@ -0,0 +1,158 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2010-2014 Intel Corporation
+
+.. _commands_spp_pcap:
+
+spp_pcap
+========
+
+``spp_pcap`` is a kind of SPP secondary process. It it introduced for
+providing packet capture features.
+
+Each of ``spp_pcap`` processes is managed with ``pcap`` command. It is for
+sending sub commands with specific ID called secondary ID for starting or
+stopping packet capture.
+
+Secondary ID is referred as ``--client-id`` which is given as an argument
+while launching ``spp_pcap``. It should be unique among all of secondary
+processes including ``spp_nfv``, ``spp_vm`` and others.
+
+``pcap`` command takes an secondary ID and one of sub commands. Secondary ID
+and sub command should be separated with delimiter ``;``, or failed to a
+command error.
+
+.. code-block:: console
+
+    spp > pcap SEC_ID; SUB_CMD
+
+In this example, ``SEC_ID`` is a secondary ID and ``SUB_CMD`` is one of the
+following sub commands. Details of each of sub commands are described in the
+next sections.
+
+* exit
+* start
+* status
+* stop
+
+``spp_pcap`` supports TAB completion. You can complete all of the name
+of commands and its arguments. For instance, you find all of sub commands
+by pressing TAB after ``pcap SEC_ID;``.
+
+.. code-block:: console
+
+    spp > pcap 1;  # press TAB key
+    exit  start      status        stop
+
+It tries to complete all of possible arguments.
+
+.. code-block:: console
+
+    spp > pcap 1; component st  # press TAB key to show args starting 'st'
+    start  status  stop
+
+If you are reached to the end of arguments, no candidate keyword is displayed.
+It is a completed statement of ``start`` command, and TAB
+completion does not work after ``start`` because it is ready to run.
+
+.. code-block:: console
+
+    spp > pcap 1; start
+    Succeeded to start capture
+
+It is also completed secondary IDs of ``spp_pcap`` and it is helpful if you run several ``spp_pcap`` processes.
+
+.. code-block:: console
+
+    spp > pcap  # press TAB after space following 'pcap'
+    1;  3;    # you find two spp_pcap processes of sec ID 1, 3
+
+By the way, it is also a case of no candidate keyword is displayed if your
+command statement is wrong. You might be encountered an error if you run the
+wrong command. Please take care.
+
+.. code-block:: console
+
+    spp > pcap 1; ste  # no candidate shown for wrong command
+    Invalid command "ste".
+
+
+.. _commands_spp_pcap_status:
+
+status
+------
+
+Show the information of worker threads and its resources. Status information
+consists of three parts.
+
+.. code-block:: console
+
+    spp > pcap 1; status
+    Basic Information:
+      - client-id: 3
+      - status: running
+      - core:2 'receive'
+        - rx: phy:0
+      - core:3 'write'
+        - file:/tmp/spp_pcap.20181108110600.phy0.1.1.pcap
+      - core:4 'write'
+        - file:/tmp/spp_pcap.20181108110600.phy0.2.1.pcap
+      - core:5 'write'
+        - file:/tmp/spp_pcap.20181108110600.phy0.3.1.pcap
+
+``Basic Information`` is for describing attributes of ``spp_pcap`` itself.
+``client-id`` is a secondary ID of the process and ``status`` shows the
+status of the process.
+
+Then lists of core IDs and its role is shown. There are two types of the role
+``receive`` and ``write``. If the role is ``receive``, port which ``spp_pcap``
+is attached to is shown. Else if the role iw ``write``, file name in absolute
+path is shown.
+
+.. _commands_spp_pcap_start:
+
+start
+-----
+
+Start packet capture. No additional arguments are taken.
+
+.. code-block:: console
+
+    # start capture
+    spp > pcap SEC_ID; start
+
+Here is a example of starting capture with ``start`` command.
+
+.. code-block:: console
+
+    # start capture
+    spp > pcap 2; start
+
+.. _commands_spp_pcap_stop:
+
+stop
+----
+
+Stop packet capture. No additional arguments are taken.
+
+.. code-block:: console
+
+   # start capture
+   spp > pcap SEC_ID; stop
+
+Here is a example of stopping capture with ``stop`` command.
+
+.. code-block:: console
+
+    # stop capture
+    spp > pcap 2; stop
+
+.. _commands_spp_pcap_exit:
+
+exit
+----
+
+Terminate the ``spp_pcap``.
+
+.. code-block:: console
+
+    spp > pcap 1; exit
-- 
2.17.1

[spp] [PATCH 2/6] docs: add spp_pcap into document of overview

[x-fn-spp]

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

Add spp_pcap into document of overview.

Signed-off-by: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>
Signed-off-by: Naoki Takada <takada.naoki@lab.ntt.co.jp>
---
 docs/guides/spp_vf/overview.rst | 34 ++++++++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/docs/guides/spp_vf/overview.rst b/docs/guides/spp_vf/overview.rst
index 446beb0..09c21af 100644
--- a/docs/guides/spp_vf/overview.rst
+++ b/docs/guides/spp_vf/overview.rst
@@ -1,13 +1,12 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2010-2014 Intel Corporation
+    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
 
 .. _spp_vf_overview:
 
 Overview
 ========
 
-This section describes an overview of SPP's extensions, ``spp_vf`` and
-``spp_mirror``.
+This section describes an overview of SPP's extensions, ``spp_vf`` , ``spp_mirror`` and ``spp_pcap``.
 SPP provides a connectivity between DPDK processes as a virtual patch panel.
 However, It is not sufficient considering more practical usecases.
 For instance, you might need a classification for incoming packets if you have
@@ -24,6 +23,8 @@ packets. This feature is intended to use as a
 <https://docs.openstack.org/dragonflow/latest/specs/tap_as_a_service.html>`_
 feature for port mirroring introduced in OpenStack.
 
+``spp_pcap`` is an another kind of secondary process to capture incoming packets. This feature is intended to capture up to 10Gbps packets.
+
 
 spp_vf
 ------
@@ -77,3 +78,30 @@ destination and a monitor application running on VM3.
    :width: 70%
 
    Overview of spp_mirror
+
+
+spp_pcap
+--------
+
+This section describes an overview of SPP's extensions, ``spp_pcap``.
+SPP provides a connectivity between VM and NIC as a virtual patch panel.
+However, for more practical use, operator and/or developer needs to capture
+packets. For such use, spp_pcap provides packet capturing feature from
+specific port. It is aimed to capture up to 10Gbps packets.
+
+``spp_pcap`` is a SPP secondary process for capturing packets from specific
+``port``. :numref:`figure_spp_pcap_overview` shows an overview of use of
+``spp_pcap`` in which ``spp_pcap`` process receives packets from ``phy:0``
+for capturing.
+
+``spp_pcap`` provides packet capturing capability as a SPP secondary process.
+``spp_pcap`` has one manager thread like spp_vf, and has two types of worker
+threads unlike spp_vf.
+
+
+.. _figure_spp_pcap_overview:
+
+.. figure:: ../images/spp_pcap/spp_pcap_overview.*
+   :width: 55%
+
+   Overview of spp_pcap
-- 
2.17.1

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

[x-fn-spp]

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

Add spp_pcap document of design.

Signed-off-by: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>
Signed-off-by: Naoki Takada <takada.naoki@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

[spp] [PATCH 4/6] docs: add spp_pcap into document of usecase

[x-fn-spp]

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

Add spp_pcap into document of usecase.

Signed-off-by: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>
Signed-off-by: Naoki Takada <takada.naoki@lab.ntt.co.jp>
---
 docs/guides/spp_vf/use_cases/index.rst    |   3 +-
 docs/guides/spp_vf/use_cases/usecase3.rst | 164 ++++++++++++++++++++++
 2 files changed, 166 insertions(+), 1 deletion(-)
 create mode 100644 docs/guides/spp_vf/use_cases/usecase3.rst

diff --git a/docs/guides/spp_vf/use_cases/index.rst b/docs/guides/spp_vf/use_cases/index.rst
index 67e8616..0a5aba3 100644
--- a/docs/guides/spp_vf/use_cases/index.rst
+++ b/docs/guides/spp_vf/use_cases/index.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
 
 Use Cases
 =========
@@ -9,3 +9,4 @@ Use Cases
 
    usecase1
    usecase2
+   usecase3
diff --git a/docs/guides/spp_vf/use_cases/usecase3.rst b/docs/guides/spp_vf/use_cases/usecase3.rst
new file mode 100644
index 0000000..146ef06
--- /dev/null
+++ b/docs/guides/spp_vf/use_cases/usecase3.rst
@@ -0,0 +1,164 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
+
+.. _spp_pcap_use_case:
+
+Packet Capture
+==============
+
+
+This section describes a usecase for Packet Capture through ``spp_pcap``.
+
+Incoming packets received by ``phy:0`` is captured by ``spp_pcap``.
+
+.. _figure_simple_capture:
+
+.. figure:: ../../images/spp_pcap/spp_pcap_overview.*
+    :width: 40%
+
+    Simple Packet Capture
+
+Launch spp_pcap
+~~~~~~~~~~~~~~~
+
+Change directory to spp and confirm that it is already compiled.
+
+.. code-block:: console
+
+    $ cd /path/to/spp
+
+As spp, launch spp-ctl and spp.py first.
+
+.. 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
+
+
+Then, run ``spp_primary``.
+
+.. code-block:: console
+
+    $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \
+        -c 0x02 -n 4 \
+        --socket-mem 512,512 \
+        --huge-dir=/run/hugepages/kvm \
+        --proc-type=primary \
+        -- \
+        -p 0x03 -n 8 -s 127.0.0.1:5555
+
+After ``spp_primary`` is launched, run secondary process ``spp_pcap``.
+If not ``--output`` directory is not created, please create it first.
+
+.. code-block:: console
+
+    $ sudo mkdir /mnt/pcap
+    $ sudo ./src/pcap/x86_64-native-linuxapp-gcc/spp_pcap \
+       -l 0-4 -n 4 --proc-type=secondary \
+       -- \
+       --client-id 1 -s 127.0.0.1:6666 \
+       -i phy:0 --output /mnt/pcap --limit_file_size 1073741824
+
+Start capturing
+~~~~~~~~~~~~~~~
+When you want to start capture, then type the following command.
+
+.. code-block:: console
+
+    spp > pcap SEC_ID; start
+
+In this usecase, spp_pcap is launched with ID=1. Let's start capturing.
+
+.. code-block:: console
+
+    # Start packet capture
+    spp > pcap 1;start
+
+Stop capturing
+~~~~~~~~~~~~~~
+
+When you want to stop capture, then type the following command.
+
+.. code-block:: console
+
+    spp > pcap SEC_ID; stop
+
+In this usecase, spp_pcap is launched with ID=1. Let's stop capturing.
+
+.. code-block:: console
+
+    # Stop packet capture
+    spp > pcap 1;stop
+
+
+Now, you can see capture file written in specified directory.
+
+.. code-block:: console
+
+    # 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
+
+Each files are compressed using LZ4, so that to uncompress it,
+use lz4 utils.
+
+.. 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
+
+    # 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.
+
+This section describes graceful shutting down for ``spp_pcap``.
+
+First, stop capturing using the following command if it is not
+already stopped.
+
+.. code-block:: console
+
+    # Stop packet capture
+    spp > pcap 1;stop
+
+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.
+
+.. code-block:: console
+
+    # Exit packet capture
+    spp > pcap 1;exit
-- 
2.17.1

[spp] [PATCH 5/6] docs: add spp_pcap into document of explanation

[x-fn-spp]

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

Add spp_pcap into document of explanation.

Signed-off-by: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>
Signed-off-by: Naoki Takada <takada.naoki@lab.ntt.co.jp>
---
 docs/guides/spp_vf/explain/functions_pcap.rst | 144 ++++++++++++++++++
 docs/guides/spp_vf/explain/index.rst          |   1 +
 2 files changed, 145 insertions(+)
 create mode 100644 docs/guides/spp_vf/explain/functions_pcap.rst

diff --git a/docs/guides/spp_vf/explain/functions_pcap.rst b/docs/guides/spp_vf/explain/functions_pcap.rst
new file mode 100644
index 0000000..8c3f624
--- /dev/null
+++ b/docs/guides/spp_vf/explain/functions_pcap.rst
@@ -0,0 +1,144 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
+
+.. _spp_pcap_explain:
+
+spp_pcap
+========
+
+The following sections provide some explanation of the code.
+
+Initializing
+------------
+
+A manager thread of ``spp_pcap`` initialize eal by ``rte_eal_init()``.
+Then each of component threads are launched by
+``rte_eal_remote_launch()``.
+
+
+.. code-block:: c
+
+    /* spp_pcap.c */
+    int ret_dpdk = rte_eal_init(argc, argv);
+
+    /* Start worker threads of classifier and forwarder */
+    RTE_LCORE_FOREACH_SLAVE(lcore_id) {
+        g_core_info[lcore_id].core[0].num = 1;
+        g_pcap_info[lcore_id].thread_no = thread_no++;
+        rte_eal_remote_launch(slave_main, NULL, lcore_id);
+    }
+
+
+Main function of slave thread
+-----------------------------
+
+``slave_main()`` is called from ``rte_eal_remote_launch()``.
+It call ``pcap_proc_receive()`` or ``pcap_proc_write()``
+depending on the core assignment.
+``pcap_proc_write();`` provides function for ``receive``,
+and ``pcap_proc_write();`` provides function for ``write``.
+
+.. code-block:: c
+
+    /* spp_pcap.c */
+        int ret = SPP_RET_OK;
+        unsigned int lcore_id = rte_lcore_id();
+        enum spp_core_status status = SPP_CORE_STOP;
+        struct pcap_mng_info *pcap_info = &g_pcap_info[lcore_id];
+
+        if (pcap_info->thread_no == 0) {
+                RTE_LOG(INFO, PCAP, "Core[%d] Start recive.\n", lcore_id);
+                pcap_info->type = TYPE_RECIVE;
+        } else {
+                RTE_LOG(INFO, PCAP, "Core[%d] Start write(%d).\n",
+                                        lcore_id, pcap_info->thread_no);
+                pcap_info->type = TYPE_WRITE;
+        }
+        RTE_LOG(INFO, PCAP, "Core[%d] Start.\n", lcore_id);
+        set_core_status(lcore_id, SPP_CORE_IDLE);
+
+        while ((status = spp_get_core_status(lcore_id)) !=
+                        SPP_CORE_STOP_REQUEST) {
+
+                if (pcap_info->type == TYPE_RECIVE)
+                        ret = pcap_proc_receive(lcore_id);
+                else
+                        ret = pcap_proc_write(lcore_id);
+                if (unlikely(ret != SPP_RET_OK)) {
+                        RTE_LOG(ERR, PCAP, "Core[%d] Thread Error.\n",
+                                                                lcore_id);
+                        break;
+                }
+        }
+
+Receive Pakcet
+--------------
+
+``pcap_proc_receive()`` is the function to realize
+receiving incoming packets. This function is called in the while loop and
+receive packets. Everytime it receves packet via ``spp_eth_rx_burst()``, then
+it enqueue those packet into the ring using ``rte_ring_enqueue_bulk()``.
+Those packets are trnsfered to ``write`` cores via the ring.
+
+
+.. code-block:: c
+
+        /* spp_pcap.c */
+        /* Receive packets */
+        rx = &g_pcap_option.port_cap;
+
+        nb_rx = spp_eth_rx_burst(rx->dpdk_port, 0, bufs, MAX_PKT_BURST);
+        if (unlikely(nb_rx == 0))
+                return SPP_RET_OK;
+
+        /* Write ring packets */
+
+        nb_tx = rte_ring_enqueue_bulk(write_ring, (void *)bufs, nb_rx, NULL);
+
+        /* Discard remained packets to release mbuf */
+
+        if (unlikely(nb_tx < nb_rx)) {
+                for (buf = nb_tx; buf < nb_rx; buf++)
+                        rte_pktmbuf_free(bufs[buf]);
+        }
+
+        return SPP_RET_OK;
+
+
+Write Packet
+------------
+
+In ``pcap_proc_write()``, it dequeue packets from ring.Then it writes to
+storage after data compression using LZ4 libraries. ``compress_file_packet``
+is the function to write packet with LZ4. LZ4 is lossless compression
+algorithm, providing compression speed > 500 MB/s per core, scalable with
+multi-cores CPU. It features an extremely fast decoder, with speed in multiple
+GB/s per core, typically reaching RAM speed limits on multi-core systems.
+Please see details in
+`LZ4
+<https://github.com/lz4/lz4>`_
+
+.. code-block:: c
+
+        /* Read packets */
+        nb_rx =  rte_ring_dequeue_bulk(read_ring, (void *)bufs, MAX_PKT_BURST,
+                                                                        NULL);
+        if (unlikely(nb_rx == 0))
+                return SPP_RET_OK;
+
+        for (buf = 0; buf < nb_rx; buf++) {
+                mbuf = bufs[buf];
+                rte_prefetch0(rte_pktmbuf_mtod(mbuf, void *));
+                if (compress_file_packet(&g_pcap_info[lcore_id], mbuf)
+                                                        != SPP_RET_OK) {
+                        RTE_LOG(ERR, PCAP, "capture file write error: "
+                                "%d (%s)\n", errno, strerror(errno));
+                        ret = SPP_RET_NG;
+                        info->status = SPP_CAPTURE_IDLE;
+                        compress_file_operation(info, CLOSE_MODE);
+                        break;
+                }
+        }
+        for (buf = nb_rx; buf < nb_rx; buf++)
+                rte_pktmbuf_free(bufs[buf]);
+        return ret;
diff --git a/docs/guides/spp_vf/explain/index.rst b/docs/guides/spp_vf/explain/index.rst
index 3f56936..d5d108f 100644
--- a/docs/guides/spp_vf/explain/index.rst
+++ b/docs/guides/spp_vf/explain/index.rst
@@ -9,3 +9,4 @@ Explanation
 
    functions_vf
    functions_mirror
+   functions_pcap
-- 
2.17.1

[spp] [PATCH 6/6] docs: add spp_pcap into document of setup

[x-fn-spp]

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

Add spp_pcap into setup document.

Signed-off-by: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>
Signed-off-by: Naoki Takada <takada.naoki@lab.ntt.co.jp>
---
 docs/guides/spp_vf/gsg/setup.rst | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/docs/guides/spp_vf/gsg/setup.rst b/docs/guides/spp_vf/gsg/setup.rst
index 9053519..af45d28 100644
--- a/docs/guides/spp_vf/gsg/setup.rst
+++ b/docs/guides/spp_vf/gsg/setup.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_setup:
 
@@ -348,6 +348,20 @@ Then, run make command to compile ``spp_mirror``.
 
    $ make
 
+Setup spp_pcap
+--------------
+
+Setup of ``spp_pcap`` is almost the same as :ref:`SPP VF<spp_vf_gsg_setup>`.
+``libpcap-dev`` is  are used by ``spp_pcap`` when capturing and packet,
+so you need to install ``libpcap-dev`` .
+``liblz4-dev`` and ``liblz4-tool`` are used for compression and decompression
+respectively, so you need to install ``liblz4-dev`` and ``liblz4-tool`` .
+
+.. code-block:: console
+
+   $ sudo apt install libpcap-dev
+   $ sudo apt install liblz4-dev
+   $ sudo apt install liblz4-tool
 
 Trouble Shooting Guide
 ----------------------
-- 
2.17.1