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 at intel.com>
---
MAINTAINERS | 3 +
doc/guides/prog_guide/index.rst | 1 +
doc/guides/prog_guide/pdump_library.rst | 106 +++++++++++++++++++++++++++++
doc/guides/rel_notes/release_16_07.rst | 11 +++
doc/guides/sample_app_ug/index.rst | 1 +
doc/guides/sample_app_ug/pdump.rst | 115 ++++++++++++++++++++++++++++++++
6 files changed, 237 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 ae706b9..8b00f41 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -437,6 +437,9 @@ Pdump
M: Reshma Pattan <reshma.pattan at 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 at 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..8d9ef29
--- /dev/null
+++ b/doc/guides/prog_guide/pdump_library.rst
@@ -0,0 +1,106 @@
+.. 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
+=============
+
+The ``pdump`` library provides the framework for the packet capturing on DPDK.
+Library provides the below APIs to initialize the packet capture framework, to
enable
+or disable the packet capture and to un initialize the packet capture
framework.
+
+``rte_pdump_init()``:
+This API initializes the packet capture framework.
+
+``rte_pdump_enable()``:
+This API enables the packet capture on a given port and the queue.
+Note: filter option in the API is the place holder for the future enhancements.
+
+``rte_pdump_enable_by_deviceid()``:
+This API enables the packet capture on a given device id(``vdev name or pci
address``) and the queue.
+Note: filter option in the API is the place holder for the future enhancements.
+
+``rte_pdump_disable()``:
+This API disables the packet capture on a given port and the queue.
+
+``rte_pdump_disable_by_deviceid()``:
+This API disables the packet capture on a given device id(``vdev name or pci
address``) and the queue.
+
+``rte_pdump_uninit()``:
+This API un initializes the packet capture framework.
+
+
+Operation
+---------
+
+The ``pdump`` library works on the server and the client based model. The
sever is responsible for enabling or
+disabling the packet capture and the clients are responsible to request enable
or disable the packet capture.
+
+The packet capture framework, as part of it's initialization, creates the
pthread and creates the server socket in
+the pthread. The application who calls the framework initialization first,
will have the server socket created and
+the further calls to the framework initialization by same application or other
applications is not allowed i.e. only
+one server socket is allowed on the system. So the other applications, can
only request for enabling or disabling of
+the packet capture and the client socket is created to send the request to the
server. The server socket will be
+listening to the client requests for enabling or disabling the packet capture.
+
+
+Implementation Details
+----------------------
+
+The library API ``rte_pdump_init()``, initializes the packet capture framework
by creating the pthread and the server
+socket.The server socket in the pthread context will be listening to the
client requests to enable or disable the
+packet capture. Who ever calls this API first will have the server socket
created, the subsequent calls to this APIs
+will not create any further server socket. i.e. only one server socket is
allowed.
+
+These library APIs ``rte_pdump_enable()/rte_pdump_enable_by_deviceid()``
enables the packet capture, on each call to
+these APIs, library creates the separate client socket, creates the pdump
enable request and send the request to the
+server. Server who is listening on the socket will take the request, enable
the packet capture by registering the
+Ethernet rx/tx callbacks for the given port or device_id and queue
combinations. Then server will mirror the packets
+to the new mempool and enqueue them to the ring that clients has passed in to
these APIs, server also 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 socket is closed.
+
+The library APIs ``rte_pdump_disable()/rte_pdump_disable_by_deviceid()``
disables the packet capture, on each call to
+these APIs, library creates the separate client socket, creates the pdump
disable request and send the request to the
+server. Server who is listening on the socket will take the request, disable
the packet capture by removing the
+Ethernet rx/tx callbacks for the given port or 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
+socket is closed.
+
+The library API ``rte_pdump_uninit()``, un initializes the packet capture
framework by closing the pthread and the
+server socket.
+
+
+Use Case: Packet Capturing
+--------------------------
+
+DPDK ``app/pdump`` tool is developed based on this library to capture the
packets in DPDK.
+Users can use this library to develop their own packet capturing application.
diff --git a/doc/guides/rel_notes/release_16_07.rst
b/doc/guides/rel_notes/release_16_07.rst
index 30e78d4..e3cd64a 100644
--- a/doc/guides/rel_notes/release_16_07.rst
+++ b/doc/guides/rel_notes/release_16_07.rst
@@ -47,6 +47,10 @@ New Features
* Dropped specific Xen Dom0 code.
* Dropped specific anonymous mempool code in testpmd.
+* **Added packet capture framework.**
+
+ * The new library ``librte_pdump`` is added to provide packet capture APIs.
+ * The new ``app/pdump`` tool is added to capture packets on DPDK.
Resolved Issues
---------------
@@ -116,6 +120,11 @@ API Changes
ibadcrc, ibadlen, imcasts, fdirmatch, fdirmiss,
tx_pause_xon, rx_pause_xon, tx_pause_xoff, rx_pause_xoff.
+* Function ``rte_eth_dev_get_port_by_name`` changed to public API.
+
+* Function ``rte_eth_dev_info_get`` updated to return new fields
``nb_rx_queues`` and ``nb_tx_queues``
+ in ``rte_eth_dev_info`` object.
+
ABI Changes
-----------
@@ -127,6 +136,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..89b14ec
--- /dev/null
+++ b/doc/guides/sample_app_ug/pdump.rst
@@ -0,0 +1,115 @@
+
+.. 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 capture on dpdk ports.
+
+
+Running the Application
+-----------------------
+
+The application has a ``--pdump`` command line option with various sub
arguments:
+
+.. code-block:: console
+
+ ./build/app/dpdk_pdump --
+ --pdump '(port=<port id> | device_id=<pci id or vdev
name>),
+ (queue=<queue_id>),
+ (rx-dev=<iface or pcap file> |
+ tx-dev=<iface or pcap file>),
+ [ring-size=<ring size>],
+ [mbuf-size=<mbuf data size>],
+ [total-num-mbufs=<number of mbufs>]'
+
+Note:
+
+* Parameters inside the parentheses represents mandatory parameters.
+
+* Parameters inside the square brackets represents optional parameters.
+
+Multiple instances of ``--pdump`` can be passed to capture packets on
different port and queue combinations.
+
+
+Parameters
+~~~~~~~~~~
+
+``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. The user can
pass a queue value of ``*`` to enable
+packet capture on all queues of the eth device.
+
+``rx-dev``:
+Can be either a pcap file name or any Linux iface.
+
+``tx-dev``:
+Can be either a pcap file name or any Linux iface.
+
+ .. 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 ``rx-dev`` and
``tx-dev``
+ should both be passed with the different file names or the Linux iface
names.
+
+ * To receive ingress and egress packets separately ``rx-dev`` and
``tx-dev``
+ should both be passed with the same file names or the the Linux iface
names.
+
+``ring-size``:
+Size of the ring. This value is used internally for ring creation. The ring
will be used to enqueue the packets from
+the primary application to the secondary. This is an optional parameter with
default size 16384.
+
+``mbuf-size``:
+Size of the mbuf data. This is used internally for mempool creation. Ideally
this value must be same as
+the primary application's mempool's mbuf data size which is used for packet
RX. This is an optional parameter with
+default size 2176.
+
+``total-num-mbufs``:
+Total number mbufs in mempool. This is used internally for mempool creation.
This is an optional parameter with default
+value 65535.
+
+
+Example
+-------
+
+.. code-block:: console
+
+ $ sudo ./build/app/dpdk_pdump -- --pdump
'port=0,queue=*,rx-dev=/tmp/rx.pcap'
--
2.5.0
