From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 1173858F1 for ; Mon, 23 May 2016 23:46:16 +0200 (CEST) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga103.jf.intel.com with ESMTP; 23 May 2016 14:46:16 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.26,357,1459839600"; d="scan'208";a="983166403" Received: from irvmail001.ir.intel.com ([163.33.26.43]) by orsmga002.jf.intel.com with ESMTP; 23 May 2016 14:46:15 -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 u4NLcbhg007469; Mon, 23 May 2016 22:38:37 +0100 Received: from sivswdev02.ir.intel.com (localhost [127.0.0.1]) by sivswdev02.ir.intel.com with ESMTP id u4NLcbsZ002995; Mon, 23 May 2016 22:38:37 +0100 Received: (from reshmapa@localhost) by sivswdev02.ir.intel.com with id u4NLcbs9002934; Mon, 23 May 2016 22:38:37 +0100 From: Reshma Pattan To: dev@dpdk.org Cc: Reshma Pattan Date: Mon, 23 May 2016 22:38:31 +0100 Message-Id: <1464039512-2683-9-git-send-email-reshma.pattan@intel.com> X-Mailer: git-send-email 1.7.4.1 In-Reply-To: <1464039512-2683-1-git-send-email-reshma.pattan@intel.com> References: <1463503030-10318-1-git-send-email-reshma.pattan@intel.com> <1464039512-2683-1-git-send-email-reshma.pattan@intel.com> Subject: [dpdk-dev] [PATCH v4 8/9] doc: update doc for packet 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: Mon, 23 May 2016 21:46:17 -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 | 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 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..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= | device_id=), + (queue=), + (rx-dev= | + tx-dev=), + [ring-size=], + [mbuf-size=], + [total-num-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