.. SPDX-License-Identifier: BSD-3-Clause
Copyright(c) 2016 Intel Corporation.
-.. _pdump_library:
+Packet Capture Library
+======================
-The librte_pdump Library
-========================
-
-The ``librte_pdump`` library provides a framework for packet capturing in DPDK.
+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.
* ``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/.dpdk`` for
-root user or ``~/.dpdk`` 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/.dpdk`` for root user or
-``~/.dpdk`` 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/.dpdk`` for root user or ``~/.dpdk``
-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.
git.droids-corp.org / dpdk.git / blobdiff