[PATCHv2 5/5] doc: update doc for packet capture framework

[Reshma Pattan <reshma.pattan@intel.com>]

added programmers guide for librte_pdump.
added sample application guide for app/pdump application.
updated release note for packet capture framework changes.

Signed-off-by: Reshma Pattan <reshma.pattan@intel.com>
---
 MAINTAINERS                             |   3 +
 doc/guides/prog_guide/index.rst         |   1 +
 doc/guides/prog_guide/pdump_library.rst | 121 ++++++++++++++++++++++++++++++++
 doc/guides/rel_notes/release_16_07.rst  |   7 ++
 doc/guides/sample_app_ug/index.rst      |   1 +
 doc/guides/sample_app_ug/pdump.rst      | 109 ++++++++++++++++++++++++++++
 6 files changed, 242 insertions(+)
 create mode 100644 doc/guides/prog_guide/pdump_library.rst
 create mode 100644 doc/guides/sample_app_ug/pdump.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index b6a39c7..6ddc818 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -432,6 +432,9 @@ Pdump
 M: Reshma Pattan <reshma.pattan@intel.com>
 F: lib/librte_pdump/
 F: app/pdump/
+F: doc/guides/prog_guide/pdump_library.rst
+F: doc/guides/sample_app_ug/pdump.rst
+
 
 Hierarchical scheduler
 M: Cristian Dumitrescu <cristian.dumitrescu@intel.com>
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index b862d0c..4caf969 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -71,6 +71,7 @@ Programmer's Guide
     writing_efficient_code
     profile_app
     glossary
+    pdump_library
 
 
 **Figures**
diff --git a/doc/guides/prog_guide/pdump_library.rst b/doc/guides/prog_guide/pdump_library.rst
new file mode 100644
index 0000000..6af77b9
--- /dev/null
+++ b/doc/guides/prog_guide/pdump_library.rst
@@ -0,0 +1,121 @@
+..  BSD LICENSE
+    Copyright(c) 2016 Intel Corporation. All rights reserved.
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+    * Neither the name of Intel Corporation nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+.. _Pdump_Library:
+
+pdump Library
+=============
+
+Pdump library provides framework for packet capturing on DPDK.
+
+Operation
+---------
+
+Pdump library provides APIs to support packet capturing on dpdk ethernet devices.
+Library provides APIs to initialize the packet capture framework, enable/disable
+the packet capture and un initialize the packet capture framework.
+
+Pdump library works on server and client based model.
+
+Sever is responsible for enabling/disabling the packet captures.
+Clients are responsible for requesting enable/disable of the
+packet captures.
+
+As part of packet capture framework initialization, pthread and
+the server socket is created. Only one server socket is allowed on the system.
+As part of enabling/disabling the packet capture, client sockets are created
+and multiple client sockets are allowed.
+Who ever calls initialization first they will succeed with the initialization,
+next subsequent calls of initialization are not allowed. So next users can only
+request enabling/disabling the packet capture.
+
+Library provides below APIs
+
+``rte_pdump_init()``
+This API initializes the packet capture framework.
+
+``rte_pdump_enable()``
+This API enables the packet capturing on a given port and queue.
+Note: filter option in the API is place holder for future use.
+
+``rte_pdump_enable_by_deviceid()``
+This API enables the packet capturing on a given device id
+(device name or pci address) and queue.
+Note: filter option in the API is place holder for future use.
+
+``rte_pdump_disable()``
+This API disables the packet capturing on a given port and queue.
+
+``rte_pdump_disable_by_deviceid()``
+This API disables the packet capturing on a given device_id and queue.
+
+``rte_pdump_uninit()``
+This API un initializes the packet capture framework.
+
+
+Implementation Details
+----------------------
+
+On a call to library API ``rte_pdump_init()``, library creates pthread and server socket.
+Server socket in pthread context will be listening to the client requests to enable/disable
+the packet capture.
+
+Who ever calls this API first will have server socket created,
+subsequent calls to this APIs will not create any further server sockets. i.e only one server
+socket is allowed.
+
+On each call to library APIs ``rte_pdump_enable()/rte_pdump_enable_by_deviceid()``
+to enable the packet capture, library creates separate client sockets,
+builds up enable request and sends the request to the server.
+Server listening on the socket will serve the request, enable the packet capture
+by registering ethernet rx/tx callbacks for the given port/device_id and queue combinations.
+Server mirrors the packets to new mempool and enqueue them to the ring that clients has passed
+in these APIs.
+Server sends the response back to the client about the status of the request that was processed.
+After the response is received from the server, client sockets will be closed.
+
+On each call to library APIs ``rte_pdump_disable()/rte_pdump_disable_by_deviceid()``
+to disable packet capture, library creates separate client sockets,
+builds up disable request and sends the request to the server.
+Server listening on the socket will serve the request, disable the packet capture
+by removing the ethernet rx/tx callbacks for the given port/device_id and queue combinations.
+Server sends the response back to the client about the status of the request that was processed.
+After the response is received from the server, client sockets will be closed.
+
+On a call to library API ``rte_pdump_uninit()``, library closes the pthread and the server socket.
+
+
+Use Case: Packet Capturing
+--------------------------
+
+app/pdump tool is developed based on this library to capture the packets
+in DPDK.
+Users can develop their own packet capturing application using new library
+if they wish to do so.
diff --git a/doc/guides/rel_notes/release_16_07.rst b/doc/guides/rel_notes/release_16_07.rst
index 83c841b..4d6ab10 100644
--- a/doc/guides/rel_notes/release_16_07.rst
+++ b/doc/guides/rel_notes/release_16_07.rst
@@ -34,6 +34,10 @@ This section should contain new features added in this release. Sample format:
 
   Refer to the previous release notes for examples.
 
+* **Added packet capturing support.**
+
+  Now users have facility to capture packets on dpdk ports using librte_pdump
+  and app/pdump tool.
 
 Resolved Issues
 ---------------
@@ -90,6 +94,7 @@ This section should contain API changes. Sample format:
   ibadcrc, ibadlen, imcasts, fdirmatch, fdirmiss,
   tx_pause_xon, rx_pause_xon, tx_pause_xoff, rx_pause_xoff.
 
+* Now function ``rte_eth_dev_get_port_by_name`` changed to public API.
 
 ABI Changes
 -----------
@@ -101,6 +106,8 @@ ABI Changes
 * The ``rte_port_source_params`` structure has new fields to support PCAP file.
   It was already in release 16.04 with ``RTE_NEXT_ABI`` flag.
 
+* The ``rte_eth_dev_info`` structure has new fields ``nb_rx_queues`` and ``nb_tx_queues``
+  to support number of queues configured by software.
 
 Shared Library Versions
 -----------------------
diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
index 930f68c..96bb317 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -76,6 +76,7 @@ Sample Applications User Guide
     ptpclient
     performance_thread
     ipsec_secgw
+    pdump
 
 **Figures**
 
diff --git a/doc/guides/sample_app_ug/pdump.rst b/doc/guides/sample_app_ug/pdump.rst
new file mode 100644
index 0000000..c185550
--- /dev/null
+++ b/doc/guides/sample_app_ug/pdump.rst
@@ -0,0 +1,109 @@
+
+..  BSD LICENSE
+    Copyright(c) 2016 Intel Corporation. All rights reserved.
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+    * Neither the name of Intel Corporation nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+dpdk_pdump Application
+======================
+The dpdk_pdump application is a Data Plane Development Kit (DPDK) application
+that runs as a DPDK secondary process and is capable of enabling packet capturing
+on dpdk ports and capturing the packets.
+
+Running the Application
+-----------------------
+The application has a pdump command line option with various sub arguments inside:
+Parameters inside the parenthesis represents the mandatory parameters.
+Parameters inside the square brackets represents optional parameters.
+User has to pass on packet capture parameters under --pdump parameters, multiples of
+--pdump can be passed to capture packets on different port and queue combinations.
+
+.. code-block:: console
+
+   ./$(RTE_TARGET)/app/pdump -- --pdump '(port=<port_id> |
+   device_id=<pci address or device name>),
+   (queue=2), (rx-dev=<iface/path to pcap file> |
+   tx-dev=<iface/path to pcap file> |
+   rxtx-dev=<iface/path to pcap file>),
+   [ring-size=1024], [mbuf-size=2048], [total-num-mbufs=8191]'
+
+Parameters
+~~~~~~~~~~
+``--pdump``: Specifies arguments needed for packet capturing.
+
+``port``
+Port id of the eth device on which packets should be captured.
+
+``device_id``
+PCI address (or) name of the eth device on which packets should be captured.
+
+``queue``
+Queue id of the eth device on which packets should be captured.
+User can pass on queue value as ‘*’ if packets capturing has to be enabled
+on all queues of the eth device.
+
+``rx-dev``
+Can be either pcap file name or any linux iface onto which ingress side packets of
+dpdk eth device will be sent on for users to view.
+
+``tx-dev``
+Can be either pcap file name or any linux iface onto which egress side packets of
+dpdk eth device will be sent on for users to view.
+
+``rxtx-dev``
+Can be either pcap file name or any linux iface onto which both ingress &
+egress side packets of dpdk eth device will be sent on for users to view.
+
+Note:
+To receive ingress packets only, rx-dev should be passed.
+To receive egress packets only, tx-dev should be passed.
+To receive ingress and egress packets separately should pass on both rx-dev and tx-dev.
+To receive both ingress and egress packets on same device, should pass only rxtx-dev.
+
+Pdump tool uses these devices internally to create PCAPPMD vdev having ``tx_stream``
+as either of these devices.
+
+``ring-size``
+Size of the ring. This value is used internally for ring creation.
+The ring will be used to enqueue the packets from primary application to secondary.
+
+``mbuf-size``
+Size of the mbuf data room size. This is used internally for mempool creation.
+Ideally this value must be same as primary application's mempool which is used for
+packet rx.
+
+``total-num-mbufs``
+Total number mbufs in mempool. This is used internally for mempool creation.
+
+Example
+-------
+
+.. code-block:: console
+
+        $ sudo ./x86_64-native-linuxapp-gcc/app/dpdk_pdump -- --pdump 'device_id=0000:02:00.0,queue=*,rx-dev=/tmp/rx-file.pcap,tx-dev=/tmp/tx-file.pcap,ring-size=8192,mbuf-size=2176,total-num-mbufs=16384' --pdump 'device_id=0000:01:00.0,queue=*,rx-dev=/tmp/rx2-file.pcap,tx-dev=/tmp/tx2-file.pcap,ring-size=16384,mbuf-size=2176,total-num-mbufs=32768'
-- 
2.5.0