X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fprog_guide%2Fpdump_lib.rst;h=07b9f39d0959d6fc60c41e66170c633ef55757ca;hb=6cc51b1293ceac4a77d4bf7ac91a8bbd59e1f78c;hp=580ffcbd690e5a3f4a440be2d500ec86eb7385e8;hpb=278f945402c55497c614de3f46b1a7660782eaf9;p=dpdk.git diff --git a/doc/guides/prog_guide/pdump_lib.rst b/doc/guides/prog_guide/pdump_lib.rst index 580ffcbd69..07b9f39d09 100644 --- a/doc/guides/prog_guide/pdump_lib.rst +++ b/doc/guides/prog_guide/pdump_lib.rst @@ -1,56 +1,39 @@ -.. 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: - -The librte_pdump Library -======================== - -The ``librte_pdump`` library provides a framework for packet capturing in DPDK. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016 Intel Corporation. + +Packet Capture Library +====================== + +The DPDK ``pdump`` library provides a framework for packet capturing in DPDK. The library does the complete copy of the Rx and Tx mbufs to a new mempool and hence it slows down the performance of the applications, so it is recommended to use this library for debugging purposes. +The library uses a generic multi process channel to facilitate communication +between primary and secondary process for enabling/disabling packet capture on +ports. + The library provides the following APIs to initialize the packet capture framework, to enable -or disable the packet capture, and to uninitialize it: +or disable the packet capture, and to uninitialize it. * ``rte_pdump_init()``: This API initializes the packet capture framework. * ``rte_pdump_enable()``: This API enables the packet capture on a given port and queue. - Note: The filter option in the API is a place holder for future enhancements. + +* ``rte_pdump_enable_bpf()`` + This API enables the packet capture on a given port and queue. + It also allows setting an optional filter using DPDK BPF interpreter + and setting the captured packet length. * ``rte_pdump_enable_by_deviceid()``: This API enables the packet capture on a given device id (``vdev name or pci address``) and queue. - Note: The filter option in the API is a place holder for future enhancements. + +* ``rte_pdump_enable_bpf_by_deviceid()`` + This API enables the packet capture on a given device id (``vdev name or pci address``) and queue. + It also allows setting an optional filter using DPDK BPF interpreter + and setting the captured packet length. * ``rte_pdump_disable()``: This API disables the packet capture on a given port and queue. @@ -61,63 +44,50 @@ or disable the packet capture, and to uninitialize it: * ``rte_pdump_uninit()``: This API uninitializes the packet capture framework. -* ``rte_pdump_set_socket_dir()``: - This API sets the server and client socket paths. - Note: This API is not thread-safe. - Operation --------- -The ``librte_pdump`` library works on a client/server model. The server is responsible for enabling or -disabling the packet capture and the clients are responsible for requesting the enabling or disabling of -the packet capture. - -The packet capture framework, as part of its initialization, creates the pthread and the server socket in -the pthread. The application that calls the framework initialization will have the server socket created, -either under the path that the application has passed or under the default path i.e. either ``/var/run`` for -root user or ``$HOME`` for non root user. - -Applications that request enabling or disabling of the packet capture will have the client socket created either under -the path that the application has passed or under the default path i.e. either ``/var/run/`` for root user or ``$HOME`` -for not root user to send the requests to the server. -The server socket will listen for client requests for enabling or disabling the packet capture. - +The primary process using ``librte_pdump`` is responsible for initializing the packet +capture framework. The packet capture framework, as part of its initialization, creates the +multi process channel to facilitate communication with secondary process, so the +secondary process ``app/pdump`` tool is responsible for enabling and disabling the packet capture on ports. 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. +The library API ``rte_pdump_init()``, initializes the packet capture framework by creating the multi process +channel using ``rte_mp_action_register()`` API. The primary process will listen to secondary process requests +to enable or disable the packet capture over the multi process channel. The library APIs ``rte_pdump_enable()`` and ``rte_pdump_enable_by_deviceid()`` enables the packet capture. -On each call to these APIs, the library creates a separate client socket, creates the "pdump enable" request and sends -the request to the server. The server that is listening on the socket will take the request and enable the packet capture -by registering the Ethernet RX and TX callbacks for the given port or device_id and queue combinations. -Then the server will mirror the packets to the new mempool and enqueue them to the rte_ring that clients have passed -to these APIs. The 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, the client socket is closed. +For the calls to these APIs from secondary process, the library creates the "pdump enable" request and sends +the request to the primary process over the multi process channel. The primary process takes this request +and enables the packet capture by registering the Ethernet RX and TX callbacks for the given port or device_id +and queue combinations. Then the primary process will mirror the packets to the new mempool and enqueue them to +the rte_ring that secondary process have passed to these APIs. + +The packet ring supports one of two formats. +The default format enqueues copies of the original packets into the rte_ring. +If the ``RTE_PDUMP_FLAG_PCAPNG`` is set, the mbuf data is extended +with header and trailer to match the format of Pcapng enhanced packet block. +The enhanced packet block has meta-data such as the timestamp, port and queue +the packet was captured on. +It is up to the application consuming the packets from the ring +to select the format desired. The library APIs ``rte_pdump_disable()`` and ``rte_pdump_disable_by_deviceid()`` disables the packet capture. -On each call to these APIs, the library creates a separate client socket, creates the "pdump disable" request and sends -the request to the server. The server that is listening on the socket will take the request and disable the packet -capture by removing the Ethernet RX and TX callbacks for the given port or device_id and queue combinations. The 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, the client socket is closed. - -The library API ``rte_pdump_uninit()``, uninitializes the packet capture framework by closing the pthread and the -server socket. +For the calls to these APIs from secondary process, the library creates the "pdump disable" request and sends +the request to the primary process over the multi process channel. The primary process takes this request and +disables the packet capture by removing the Ethernet RX and TX callbacks for the given port or device_id and +queue combinations. -The library API ``rte_pdump_set_socket_dir()``, sets the given path as either server socket path -or client socket path based on the ``type`` argument of the API. -If the given path is ``NULL``, default path will be selected, i.e. either ``/var/run/`` for root user or ``$HOME`` -for non root user. Clients also need to call this API to set their server socket path if the server socket -path is different from default path. +The library API ``rte_pdump_uninit()``, uninitializes the packet capture framework by calling ``rte_mp_action_unregister()`` +function. Use Case: Packet Capturing -------------------------- -The DPDK ``app/pdump`` tool is developed based on this library to capture packets in DPDK. -Users can use this as an example to develop their own packet capturing tools. +The DPDK ``app/dpdk-dumpcap`` utility uses this library +to capture packets in DPDK.