From mboxrd@z Thu Jan 1 00:00:00 1970 From: Reshma Pattan Subject: =?utf-8?q?=5BPATCH_5/5=5D_doc=3A_update_doc_for_packet?= =?utf-8?q?_capture_framework?= Date: Fri, 6 May 2016 11:55:39 +0100 Message-ID: <1462532139-17848-6-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: quoted-printable Cc: Reshma Pattan To: dev@dpdk.org 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) In-Reply-To: <1462532139-17848-1-git-send-email-reshma.pattan@intel.com> List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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 + =20 Hierarchical scheduler M: Cristian Dumitrescu diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/inde= x.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 =20 =20 **Figures** diff --git a/doc/guides/prog_guide/pdump_library.rst b/doc/guides/prog_gu= ide/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 FO= R + 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 AN= Y + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +.. _Pdump_Library: + +pdump Library +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 s= ystem. +As part of enabling/disabling the packet capture, client sockets are cre= ated +and multiple client sockets are allowed. +Who ever calls initialization first they will succeed with the initializ= ation, +next subsequent calls of initialization are not allowed. So next users c= an 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 a= nd server socket. +Server socket in pthread context will be listening to the client request= s 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_de= viceid()`` +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 t= hat clients has passed +in these APIs. +Server sends the response back to the client about the status of the req= uest that was processed. +After the response is received from the server, client sockets will be c= losed. + +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 packe= t capture +by removing the ethernet rx/tx callbacks for the given port/device_id an= d queue combinations. +Server sends the response back to the client about the status of the req= uest that was processed. +After the response is received from the server, client sockets will be c= losed. + +On a call to library API ``rte_pdump_uninit()``, library closes the pthr= ead 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 libra= ry +if they wish to do so. diff --git a/doc/guides/rel_notes/release_16_07.rst b/doc/guides/rel_note= s/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: =20 Refer to the previous release notes for examples. =20 +* **Added packet capturing support.** + + Now users have facility to capture packets on dpdk ports using librte_= pdump + and app/pdump tool. =20 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. =20 +* Now function ``rte_eth_dev_get_port_by_name`` changed to public API. =20 ABI Changes ----------- @@ -101,6 +106,8 @@ ABI Changes * The ``rte_port_source_params`` structure has new fields to support PCA= P file. It was already in release 16.04 with ``RTE_NEXT_ABI`` flag. =20 +* The ``rte_eth_dev_info`` structure has new fields ``nb_rx_queues`` and= ``nb_tx_queues`` + to support number of queues configured by software. =20 Shared Library Versions ----------------------- diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_u= g/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 =20 **Figures** =20 diff --git a/doc/guides/sample_app_ug/pdump.rst b/doc/guides/sample_app_u= g/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 FO= R + 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 AN= Y + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +dpdk_pdump Application +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +The dpdk_pdump application is a Data Plane Development Kit (DPDK) applic= ation +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 argumen= ts 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 com= binations. + +.. code-block:: console + + ./$(RTE_TARGET)/app/pdump -- --pdump '(port=3D | + device_id=3D), + (queue=3D2), (rx-dev=3D | + tx-dev=3D | + rxtx-dev=3D), + [ring-size=3D1024], [mbuf-size=3D2048], [total-num-mbufs=3D8191]' + +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 captu= red. + +``queue`` +Queue id of the eth device on which packets should be captured. +User can pass on queue value as =E2=80=98*=E2=80=99 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 p= ackets 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 o= nly 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 cre= ation. +Ideally this value must be same as primary application's mempool which i= s used for +packet rx. + +``total-num-mbufs`` +Total number mbufs in mempool. This is used internally for mempool creat= ion. + +Example +------- + +.. code-block:: console + + $ sudo ./x86_64-native-linuxapp-gcc/app/dpdk_pdump -- --pdump 'd= evice_id=3D0000:02:00.0,queue=3D*,rx-dev=3D/tmp/rx-file.pcap,tx-dev=3D/tm= p/tx-file.pcap,ring-size=3D8192,mbuf-size=3D2176,total-num-mbufs=3D16384'= --pdump 'device_id=3D0000:01:00.0,queue=3D*,rx-dev=3D/tmp/rx2-file.pcap,= tx-dev=3D/tmp/tx2-file.pcap,ring-size=3D16384,mbuf-size=3D2176,total-num-= mbufs=3D32768' --=20 2.5.0