Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/13375/?format=api
{ "id": 13375, "url": "https://patches.dpdk.org/api/patches/13375/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/1465393107-32587-9-git-send-email-reshma.pattan@intel.com/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<1465393107-32587-9-git-send-email-reshma.pattan@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/1465393107-32587-9-git-send-email-reshma.pattan@intel.com", "date": "2016-06-08T13:38:26", "name": "[dpdk-dev,v5,8/9] doc: update doc for packet capture framework", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "70db7ac047b608b77490f691f246a45bdc79c155", "submitter": { "id": 70, "url": "https://patches.dpdk.org/api/people/70/?format=api", "name": "Pattan, Reshma", "email": "reshma.pattan@intel.com" }, "delegate": { "id": 1, "url": "https://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/1465393107-32587-9-git-send-email-reshma.pattan@intel.com/mbox/", "series": [], "comments": "https://patches.dpdk.org/api/patches/13375/comments/", "check": "pending", "checks": "https://patches.dpdk.org/api/patches/13375/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@dpdk.org", "Delivered-To": "patchwork@dpdk.org", "Received": [ "from [92.243.14.124] (localhost [IPv6:::1])\n\tby dpdk.org (Postfix) with ESMTP id 0B420B41B;\n\tWed, 8 Jun 2016 15:38:40 +0200 (CEST)", "from mga01.intel.com (mga01.intel.com [192.55.52.88])\n\tby dpdk.org (Postfix) with ESMTP id 9BEC2AF82\n\tfor <dev@dpdk.org>; Wed, 8 Jun 2016 15:38:34 +0200 (CEST)", "from fmsmga002.fm.intel.com ([10.253.24.26])\n\tby fmsmga101.fm.intel.com with ESMTP; 08 Jun 2016 06:38:32 -0700", "from irvmail001.ir.intel.com ([163.33.26.43])\n\tby fmsmga002.fm.intel.com with ESMTP; 08 Jun 2016 06:38:31 -0700", "from sivswdev02.ir.intel.com (sivswdev02.ir.intel.com\n\t[10.237.217.46])\n\tby irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id\n\tu58DcU5k026951; Wed, 8 Jun 2016 14:38:30 +0100", "from sivswdev02.ir.intel.com (localhost [127.0.0.1])\n\tby sivswdev02.ir.intel.com with ESMTP id u58DcU5p032697;\n\tWed, 8 Jun 2016 14:38:30 +0100", "(from reshmapa@localhost)\n\tby sivswdev02.ir.intel.com with id u58DcUfY032693;\n\tWed, 8 Jun 2016 14:38:30 +0100" ], "X-ExtLoop1": "1", "X-IronPort-AV": "E=Sophos;i=\"5.26,439,1459839600\"; d=\"scan'208\";a=\"997801330\"", "From": "Reshma Pattan <reshma.pattan@intel.com>", "To": "dev@dpdk.org", "Cc": "Reshma Pattan <reshma.pattan@intel.com>", "Date": "Wed, 8 Jun 2016 14:38:26 +0100", "Message-Id": "<1465393107-32587-9-git-send-email-reshma.pattan@intel.com>", "X-Mailer": "git-send-email 1.7.4.1", "In-Reply-To": "<1465393107-32587-1-git-send-email-reshma.pattan@intel.com>", "References": "<1464039512-2683-1-git-send-email-reshma.pattan@intel.com>\n\t<1465393107-32587-1-git-send-email-reshma.pattan@intel.com>", "Subject": "[dpdk-dev] [PATCH v5 8/9] doc: update doc for packet capture\n\tframework", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "patches and discussions about DPDK <dev.dpdk.org>", "List-Unsubscribe": "<http://dpdk.org/ml/options/dev>,\n\t<mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://dpdk.org/ml/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<http://dpdk.org/ml/listinfo/dev>,\n\t<mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Added programmers guide for librte_pdump.\nAdded sample application guide for app/pdump application.\nUpdated release note for packet capture framework changes.\n\nSigned-off-by: Reshma Pattan <reshma.pattan@intel.com>\n---\n MAINTAINERS | 3 +\n doc/guides/prog_guide/index.rst | 1 +\n doc/guides/prog_guide/pdump_library.rst | 107 ++++++++++++++++++++++++++++\n doc/guides/rel_notes/release_16_07.rst | 13 ++++\n doc/guides/sample_app_ug/index.rst | 1 +\n doc/guides/sample_app_ug/pdump.rst | 122 ++++++++++++++++++++++++++++++++\n 6 files changed, 247 insertions(+)\n create mode 100644 doc/guides/prog_guide/pdump_library.rst\n create mode 100644 doc/guides/sample_app_ug/pdump.rst", "diff": "diff --git a/MAINTAINERS b/MAINTAINERS\nindex a48c8de..ce7c941 100644\n--- a/MAINTAINERS\n+++ b/MAINTAINERS\n@@ -436,6 +436,9 @@ Pdump\n M: Reshma Pattan <reshma.pattan@intel.com>\n F: lib/librte_pdump/\n F: app/pdump/\n+F: doc/guides/prog_guide/pdump_library.rst\n+F: doc/guides/sample_app_ug/pdump.rst\n+\n \n Hierarchical scheduler\n M: Cristian Dumitrescu <cristian.dumitrescu@intel.com>\ndiff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst\nindex b862d0c..4caf969 100644\n--- a/doc/guides/prog_guide/index.rst\n+++ b/doc/guides/prog_guide/index.rst\n@@ -71,6 +71,7 @@ Programmer's Guide\n writing_efficient_code\n profile_app\n glossary\n+ pdump_library\n \n \n **Figures**\ndiff --git a/doc/guides/prog_guide/pdump_library.rst b/doc/guides/prog_guide/pdump_library.rst\nnew file mode 100644\nindex 0000000..1809234\n--- /dev/null\n+++ b/doc/guides/prog_guide/pdump_library.rst\n@@ -0,0 +1,107 @@\n+.. BSD LICENSE\n+ Copyright(c) 2016 Intel Corporation. All rights reserved.\n+ All rights reserved.\n+\n+ Redistribution and use in source and binary forms, with or without\n+ modification, are permitted provided that the following conditions\n+ are met:\n+\n+ * Redistributions of source code must retain the above copyright\n+ notice, this list of conditions and the following disclaimer.\n+ * Redistributions in binary form must reproduce the above copyright\n+ notice, this list of conditions and the following disclaimer in\n+ the documentation and/or other materials provided with the\n+ distribution.\n+ * Neither the name of Intel Corporation nor the names of its\n+ contributors may be used to endorse or promote products derived\n+ from this software without specific prior written permission.\n+\n+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n+ \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\n+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\n+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\n+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\n+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT\n+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\n+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\n+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\n+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n+\n+.. _pdump_library:\n+\n+The librte_pdump Library\n+========================\n+\n+The ``librte_pdump`` library provides a framework for packet capturing in DPDK.\n+The library provides the following APIs to initialize the packet capture framework, to enable\n+or disable the packet capture, and to uninitialize it:\n+\n+* ``rte_pdump_init()``:\n+ This API initializes the packet capture framework.\n+\n+* ``rte_pdump_enable()``:\n+ This API enables the packet capture on a given port and queue.\n+ Note: The filter option in the API is a place holder for future enhancements.\n+\n+* ``rte_pdump_enable_by_deviceid()``:\n+ This API enables the packet capture on a given device id (``vdev name or pci address``) and queue.\n+ Note: The filter option in the API is a place holder for future enhancements.\n+\n+* ``rte_pdump_disable()``:\n+ This API disables the packet capture on a given port and queue.\n+\n+* ``rte_pdump_disable_by_deviceid()``:\n+ This API disables the packet capture on a given device id (``vdev name or pci address``) and queue.\n+\n+* ``rte_pdump_uninit()``:\n+ This API uninitializes the packet capture framework.\n+\n+\n+Operation\n+---------\n+\n+The ``librte_pdump`` library works on a client/server model. The server is responsible for enabling or\n+disabling the packet capture and the clients are responsible for requesting the enabling or disabling of\n+the packet capture.\n+\n+The packet capture framework, as part of its initialization, creates the pthread and the server socket in\n+the pthread. The application that calls the framework initialization first will have the server socket created.\n+Further calls to the framework initialization by the same application or other applications is not allowed i.e., only\n+one server socket is allowed on the system. So the other applications can only request enabling or disabling of\n+the packet capture at which point the client socket is created for them to send the request to the server.\n+The server socket will listen for client requests for enabling or disabling the packet capture.\n+\n+\n+Implementation Details\n+----------------------\n+\n+The library API ``rte_pdump_init()``, initializes the packet capture framework by creating the pthread and the server\n+socket. The server socket in the pthread context will be listening to the client requests to enable or disable the\n+packet capture. Whoever calls this API first will have the server socket created, the subsequent calls to this APIs\n+will not create any further server socket. i.e. only one server socket is allowed.\n+\n+The library APIs ``rte_pdump_enable()`` and ``rte_pdump_enable_by_deviceid()`` enables the packet capture.\n+On each call to these APIs, the library creates a separate client socket, creates the \"pdump enable\" request and sends\n+the request to the server. The server that is listening on the socket will take the request and enable the packet capture\n+by registering the Ethernet RX and TX callbacks for the given port or device_id and queue combinations.\n+Then the server will mirror the packets to the new mempool and enqueue them to the rte_ring that clients have passed\n+to these APIs. The server also sends the response back to the client about the status of the request that was processed.\n+After the response is received from the server, the client socket is closed.\n+\n+The library APIs ``rte_pdump_disable()`` and ``rte_pdump_disable_by_deviceid()`` disables the packet capture.\n+On each call to these APIs, the library creates a separate client socket, creates the \"pdump disable\" request and sends\n+the request to the server. The server that is listening on the socket will take the request and disable the packet\n+capture by removing the Ethernet RX and TX callbacks for the given port or device_id and queue combinations. The server\n+also sends the response back to the client about the status of the request that was processed. After the response is\n+received from the server, the client socket is closed.\n+\n+The library API ``rte_pdump_uninit()``, uninitializes the packet capture framework by closing the pthread and the\n+server socket.\n+\n+\n+Use Case: Packet Capturing\n+--------------------------\n+\n+The DPDK ``app/pdump`` tool is developed based on this library to capture packets in DPDK.\n+Users can use this as an example to develop their own packet capturing application.\ndiff --git a/doc/guides/rel_notes/release_16_07.rst b/doc/guides/rel_notes/release_16_07.rst\nindex 307e7c4..438b705 100644\n--- a/doc/guides/rel_notes/release_16_07.rst\n+++ b/doc/guides/rel_notes/release_16_07.rst\n@@ -57,6 +57,11 @@ New Features\n Enabled support for the AES CTR algorithm for Intel QuickAssist devices.\n Provided support for algorithm-chaining operations.\n \n+* **Added packet capture framework.**\n+\n+ * A new library ``librte_pdump`` is added to provide packet capture APIs.\n+ * A new ``app/pdump`` tool is added to capture packets in DPDK.\n+\n \n Resolved Issues\n ---------------\n@@ -126,6 +131,11 @@ API Changes\n ibadcrc, ibadlen, imcasts, fdirmatch, fdirmiss,\n tx_pause_xon, rx_pause_xon, tx_pause_xoff, rx_pause_xoff.\n \n+* Function ``rte_eth_dev_get_port_by_name`` changed to a public API.\n+\n+* Function ``rte_eth_dev_info_get`` updated to return new fields ``nb_rx_queues`` and ``nb_tx_queues``\n+ in the ``rte_eth_dev_info`` object.\n+\n \n ABI Changes\n -----------\n@@ -137,6 +147,9 @@ ABI Changes\n * The ``rte_port_source_params`` structure has new fields to support PCAP file.\n It was already in release 16.04 with ``RTE_NEXT_ABI`` flag.\n \n+* The ``rte_eth_dev_info`` structure has new fields ``nb_rx_queues`` and ``nb_tx_queues``\n+ to support number of queues configured by software.\n+\n \n Shared Library Versions\n -----------------------\ndiff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst\nindex 930f68c..96bb317 100644\n--- a/doc/guides/sample_app_ug/index.rst\n+++ b/doc/guides/sample_app_ug/index.rst\n@@ -76,6 +76,7 @@ Sample Applications User Guide\n ptpclient\n performance_thread\n ipsec_secgw\n+ pdump\n \n **Figures**\n \ndiff --git a/doc/guides/sample_app_ug/pdump.rst b/doc/guides/sample_app_ug/pdump.rst\nnew file mode 100644\nindex 0000000..96c8709\n--- /dev/null\n+++ b/doc/guides/sample_app_ug/pdump.rst\n@@ -0,0 +1,122 @@\n+\n+.. BSD LICENSE\n+ Copyright(c) 2016 Intel Corporation. All rights reserved.\n+ All rights reserved.\n+\n+ Redistribution and use in source and binary forms, with or without\n+ modification, are permitted provided that the following conditions\n+ are met:\n+\n+ * Redistributions of source code must retain the above copyright\n+ notice, this list of conditions and the following disclaimer.\n+ * Redistributions in binary form must reproduce the above copyright\n+ notice, this list of conditions and the following disclaimer in\n+ the documentation and/or other materials provided with the\n+ distribution.\n+ * Neither the name of Intel Corporation nor the names of its\n+ contributors may be used to endorse or promote products derived\n+ from this software without specific prior written permission.\n+\n+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n+ \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\n+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\n+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\n+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\n+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT\n+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\n+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\n+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\n+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n+\n+\n+dpdk_pdump Application\n+======================\n+\n+The ``dpdk_pdump`` application is a Data Plane Development Kit (DPDK) application that runs as a DPDK secondary process and\n+is capable of enabling packet capture on dpdk ports.\n+\n+\n+Running the Application\n+-----------------------\n+\n+The application has a ``--pdump`` command line option with various sub arguments:\n+\n+.. code-block:: console\n+\n+ ./build/app/dpdk_pdump --\n+ --pdump '(port=<port id> | device_id=<pci id or vdev name>),\n+ (queue=<queue_id>),\n+ (rx-dev=<iface or pcap file> |\n+ tx-dev=<iface or pcap file>),\n+ [ring-size=<ring size>],\n+ [mbuf-size=<mbuf data size>],\n+ [total-num-mbufs=<number of mbufs>]'\n+\n+Note:\n+\n+* Parameters inside the parentheses represents mandatory parameters.\n+\n+* Parameters inside the square brackets represents optional parameters.\n+\n+Multiple instances of ``--pdump`` can be passed to capture packets on different port and queue combinations.\n+\n+\n+Parameters\n+~~~~~~~~~~\n+\n+``port``:\n+Port id of the eth device on which packets should be captured.\n+\n+``device_id``:\n+PCI address (or) name of the eth device on which packets should be captured.\n+\n+ .. Note::\n+\n+ * As of now the ``dpdk_pdump`` tool cannot capture the packets of virtual devices\n+ in the primary process due to a bug in the ethdev library. Due to this bug, in a multi process context,\n+ when the primary and secondary have different ports set, then the secondary process\n+ (here the ``dpdk_pdump`` tool) overwrites the ``rte_eth_devices[]`` entries of the primary process.\n+\n+``queue``:\n+Queue id of the eth device on which packets should be captured. The user can pass a queue value of ``*`` to enable\n+packet capture on all queues of the eth device.\n+\n+``rx-dev``:\n+Can be either a pcap file name or any Linux iface.\n+\n+``tx-dev``:\n+Can be either a pcap file name or any Linux iface.\n+\n+ .. Note::\n+\n+ * To receive ingress packets only, ``rx-dev`` should be passed.\n+\n+ * To receive egress packets only, ``tx-dev`` should be passed.\n+\n+ * To receive ingress and egress packets separately ``rx-dev`` and ``tx-dev``\n+ should both be passed with the different file names or the Linux iface names.\n+\n+ * To receive ingress and egress packets separately ``rx-dev`` and ``tx-dev``\n+ should both be passed with the same file names or the the Linux iface names.\n+\n+``ring-size``:\n+Size of the ring. This value is used internally for ring creation. The ring will be used to enqueue the packets from\n+the primary application to the secondary. This is an optional parameter with default size 16384.\n+\n+``mbuf-size``:\n+Size of the mbuf data. This is used internally for mempool creation. Ideally this value must be same as\n+the primary application's mempool's mbuf data size which is used for packet RX. This is an optional parameter with\n+default size 2176.\n+\n+``total-num-mbufs``:\n+Total number mbufs in mempool. This is used internally for mempool creation. This is an optional parameter with default\n+value 65535.\n+\n+\n+Example\n+-------\n+\n+.. code-block:: console\n+\n+ $ sudo ./build/app/dpdk_pdump -- --pdump 'port=0,queue=*,rx-dev=/tmp/rx.pcap'\n", "prefixes": [ "dpdk-dev", "v5", "8/9" ] }