From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by dpdk.org (Postfix) with ESMTP id 0DFA95A52 for ; Fri, 6 May 2016 12:55:47 +0200 (CEST) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by fmsmga104.fm.intel.com with ESMTP; 06 May 2016 03:55:47 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.24,586,1455004800"; d="scan'208";a="970022681" Received: from irvmail001.ir.intel.com ([163.33.26.43]) by orsmga002.jf.intel.com with ESMTP; 06 May 2016 03:55:46 -0700 Received: from sivswdev02.ir.intel.com (sivswdev02.ir.intel.com [10.237.217.46]) by irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id u46Atj6L010171; Fri, 6 May 2016 11:55:45 +0100 Received: from sivswdev02.ir.intel.com (localhost [127.0.0.1]) by sivswdev02.ir.intel.com with ESMTP id u46AtjFe017934; Fri, 6 May 2016 11:55:45 +0100 Received: (from reshmapa@localhost) by sivswdev02.ir.intel.com with id u46AtjC6017930; Fri, 6 May 2016 11:55:45 +0100 From: Reshma Pattan To: dev@dpdk.org Cc: Reshma Pattan Date: Fri, 6 May 2016 11:55:39 +0100 Message-Id: <1462532139-17848-6-git-send-email-reshma.pattan@intel.com> X-Mailer: git-send-email 1.7.4.1 In-Reply-To: <1462532139-17848-1-git-send-email-reshma.pattan@intel.com> References: <1462532139-17848-1-git-send-email-reshma.pattan@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] =?utf-8?q?=5BPATCH_5/5=5D_doc=3A_update_doc_for_packet?= =?utf-8?q?_capture_framework?= X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 06 May 2016 10:55:48 -0000 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 --- 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 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 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= | + device_id=), + (queue=2), (rx-dev= | + tx-dev= | + rxtx-dev=), + [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