[dpdk-dev] [PATCH v3 5/5] doc: update doc for tcpdump feature

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

Added tcpdump design changes to proc_info section of
sample application user guide.
Added tcpdump design changes to env abstraction layer section
of programmers guide.
Updated Release notes

Signed-off-by: Reshma Pattan <reshma.pattan@intel.com>
---
 doc/guides/prog_guide/env_abstraction_layer.rst |   43 ++++++++++++++++-
 doc/guides/rel_notes/release_16_04.rst          |    6 ++
 doc/guides/sample_app_ug/proc_info.rst          |   57 +++++++++++++++++++----
 3 files changed, 94 insertions(+), 12 deletions(-)

diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
index 4737dc2..be06764 100644
--- a/doc/guides/prog_guide/env_abstraction_layer.rst
+++ b/doc/guides/prog_guide/env_abstraction_layer.rst
@@ -1,5 +1,5 @@
 ..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+    Copyright(c) 2010-2016 Intel Corporation. All rights reserved.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -169,7 +169,8 @@ The EAL can query the CPU at runtime (using the rte_cpu_get_feature() function)
 User Space Interrupt Event
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-+ User Space Interrupt and Alarm Handling in Host Thread
+User Space Interrupt and Alarm Handling in Host Thread
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The EAL creates a host thread to poll the UIO device file descriptors to detect the interrupts.
 Callbacks can be registered or unregistered by the EAL functions for a specific interrupt event
@@ -182,7 +183,8 @@ The EAL also allows timed callbacks to be used in the same way as for NIC interr
     i.e. link up and link down notification.
 
 
-+ RX Interrupt Event
+RX Interrupt Event
+^^^^^^^^^^^^^^^^^^
 
 The receive and transmit routines provided by each PMD don't limit themselves to execute in polling thread mode.
 To ease the idle polling with tiny throughput, it's useful to pause the polling and wait until the wake-up event happens.
@@ -207,6 +209,41 @@ The eth_dev driver takes responsibility to program the latter mapping.
 The RX interrupt are controlled/enabled/disabled by ethdev APIs - 'rte_eth_dev_rx_intr_*'. They return failure if the PMD
 hasn't support them yet. The intr_conf.rxq flag is used to turn on the capability of RX interrupt per device.
 
+Tcpdump
+^^^^^^^
+
+The EAL thread polls for the tcpdump file descriptor.
+If the polled file descriptor matches the tcpdump file descriptor it will initiate tcpdump processing.
+
+The EAL thread creates the socket for the tcpdump connection with the secondary process and registers the socket with
+the tcpdump epoll event.
+The tcpdump event will be polled as part of the interrupt thread.
+
+The EAL thread also creates the mempool and two rte_rings for packets duplication, and sharing the packet information
+with the secondary process respectively.
+
+Upon receiving the tcpdump event, the EAL thread either receives a "register" or "remove" message for RX/TX callbacks
+on the socket.
+
+For the "register" RX/TX callback message:
+
+* The EAL thread parses the port and queue information of the message and registers the ``rte_eth_rxtx_callbacks``
+  for the given port and queue.
+
+* The Rx callback will apply a src ip filter to the received packets and the matched packets will be duplicated to the
+  new mempool.
+  Duplicated packets will be enqueued to one of the rte_rings for the secondary process to use.
+  If no filter is provided, all the packets will be duplicated to the new mempool.
+
+* The TX callback will apply a src ip filter to the received packets and the reference count of the matched
+  packets will be incremented before enqueuing to the second rte_ring for the secondary process to use.
+  If no filter is provided, the reference count of all the packets will be incremented.
+
+For the "remove" RX/TX callback message:
+
+* The EAL thread parses the port and queue information of the message and removes the ``rte_eth_rxtx_callbacks``
+  for the given port and queue.
+
 Blacklisting
 ~~~~~~~~~~~~
 
diff --git a/doc/guides/rel_notes/release_16_04.rst b/doc/guides/rel_notes/release_16_04.rst
index fd7dd1a..bd6f33b 100644
--- a/doc/guides/rel_notes/release_16_04.rst
+++ b/doc/guides/rel_notes/release_16_04.rst
@@ -51,6 +51,9 @@ This section should contain new features added in this release. Sample format:
 
 * **Added vhost-user live migration support.**
 
+* **Added dpdk packet capturing support for tcpdump.**
+
+  Now users have the facility to capture the packets of dpdk ports using dpdk_proc_info application.
 
 Resolved Issues
 ---------------
@@ -83,6 +86,7 @@ Drivers
   This made impossible the creation of more than one aesni_mb device
   from command line.
 
+* **pcap: Added public API support for creating pcap device using pcaps and dumpers.**
 
 Libraries
 ~~~~~~~~~
@@ -92,6 +96,7 @@ Libraries
   Fix crc32c hash functions to return a valid crc32c value for data lengths
   not multiple of 4 bytes.
 
+* **Enhanced eal library to support dpdk packet capturing support for tcpdump.**
 
 Examples
 ~~~~~~~~
@@ -100,6 +105,7 @@ Examples
 Other
 ~~~~~
 
+* **Enhanced app/proc_info to support dpdk packet capturing support for tcpdump.**
 
 Known Issues
 ------------
diff --git a/doc/guides/sample_app_ug/proc_info.rst b/doc/guides/sample_app_ug/proc_info.rst
index 542950b..274c9e0 100644
--- a/doc/guides/sample_app_ug/proc_info.rst
+++ b/doc/guides/sample_app_ug/proc_info.rst
@@ -1,6 +1,6 @@
 
 ..  BSD LICENSE
-    Copyright(c) 2015 Intel Corporation. All rights reserved.
+    Copyright(c) 2015-2016 Intel Corporation. All rights reserved.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -39,33 +39,72 @@ statistics, resetting port statistics and printing DPDK memory information.
 This application extends the original functionality that was supported by
 dump_cfg.
 
+The ``dpdk_proc_info`` application supports the command line options for configuring the packet
+capturing support for tcpdump.
+
+Overview of tcpdump flow
+------------------------
+
+* The ``dpdk_proc_info`` application parses the command line options for the port, queue, src ip filter
+  and other tcpdump options.
+
+* The application creates a socket to communicate with the primary process and sends the "register" RX/TX callback
+  message containing port, queue and src ip filter information.
+
+* Based on the ``--single-tcpdump-file`` command line option, it either creates a single pcap or two pcap devices for
+  writing ingress and egress packets for tcpdump.
+
+* It dequeues the packets sent by the primary process over the rte_rings and writes the packets to the pcap devices.
+
+* Upon an application termination i.e. using ``ctrl+c``, it sends the "remove" RX/TX callbacks message to the primary
+  process containing port, queue information.
+
 Running the Application
 -----------------------
+
 The application has a number of command line options:
 
 .. code-block:: console
 
-   ./$(RTE_TARGET)/app/dpdk_proc_info -- -m | [-p PORTMASK] [--stats | --xstats |
-   --stats-reset | --xstats-reset]
+   ./$(RTE_TARGET)/app/dpdk_proc_info -- -m | [-p PORTMASK] [--tcpdump (port,queue)] \
+                                      [ --src-ip-filter \"A.B.C.D\"] \
+                                      [--single-tcpdump-file] \
+                                      [--stats | --xstats | \
+                                       --stats-reset | --xstats-reset]
 
 Parameters
 ~~~~~~~~~~
-**-p PORTMASK**: Hexadecimal bitmask of ports to configure.
 
-**--stats**
+``-p PORTMASK``: Hexadecimal bitmask of ports to configure.
+
+``--tcpdump (port,queue)``
+The tcpdump (port,queue) parameter controls the packet capturing support on a given port and queue.
+User need to specify either an unique queue id or '*' to capture the packets from specific queue or from all the queues
+of a given port.
+
+``--src-ip-filter "A.B.C.D"``
+The src-ip-filter parameter controls the packet filtering support.
+If the src ip filter option is not specified, all the packets will be captured.
+
+``--single-tcpdump-file``
+The single-tcpdump-file parameter controls packet capturing to a single pcap file.
+If the option is specified both the ingress and egress packets will be captured to a single pcap file otherwise they
+will be captured to two different RX and TX pcap files.
+
+``--stats``
 The stats parameter controls the printing of generic port statistics. If no
 port mask is specified stats are printed for all DPDK ports.
 
-**--xstats**
+``--xstats``
 The stats parameter controls the printing of extended port statistics. If no
 port mask is specified xstats are printed for all DPDK ports.
 
-**--stats-reset**
+``--stats-reset``
 The stats-reset parameter controls the resetting of generic port statistics. If
 no port mask is specified, the generic stats are reset for all DPDK ports.
 
-**--xstats-reset**
+``--xstats-reset``
 The xstats-reset parameter controls the resetting of extended port statistics.
 If no port mask is specified xstats are reset for all DPDK ports.
 
-**-m**: Print DPDK memory information.
+``-m``: Print DPDK memory information.
-- 
1.7.4.1