@@ -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>
@@ -71,6 +71,7 @@ Programmer's Guide
writing_efficient_code
profile_app
glossary
+ pdump_library
**Figures**
new file mode 100644
@@ -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.
@@ -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
-----------------------
@@ -76,6 +76,7 @@ Sample Applications User Guide
ptpclient
performance_thread
ipsec_secgw
+ pdump
**Figures**
new file mode 100644
@@ -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'