1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2016 Intel Corporation. 3 4.. _pdump_library: 5 6The librte_pdump Library 7======================== 8 9The ``librte_pdump`` library provides a framework for packet capturing in DPDK. 10The library does the complete copy of the Rx and Tx mbufs to a new mempool and 11hence it slows down the performance of the applications, so it is recommended 12to use this library for debugging purposes. 13 14The library uses a generic multi process channel to facilitate communication 15between primary and secondary process for enabling/disabling packet capture on 16ports. 17 18The library provides the following APIs to initialize the packet capture framework, to enable 19or disable the packet capture, and to uninitialize it. 20 21* ``rte_pdump_init()``: 22 This API initializes the packet capture framework. 23 24* ``rte_pdump_enable()``: 25 This API enables the packet capture on a given port and queue. 26 Note: The filter option in the API is a place holder for future enhancements. 27 28* ``rte_pdump_enable_by_deviceid()``: 29 This API enables the packet capture on a given device id (``vdev name or pci address``) and queue. 30 Note: The filter option in the API is a place holder for future enhancements. 31 32* ``rte_pdump_disable()``: 33 This API disables the packet capture on a given port and queue. 34 35* ``rte_pdump_disable_by_deviceid()``: 36 This API disables the packet capture on a given device id (``vdev name or pci address``) and queue. 37 38* ``rte_pdump_uninit()``: 39 This API uninitializes the packet capture framework. 40 41 42Operation 43--------- 44 45The primary process using ``librte_pdump`` is responsible for initializing the packet 46capture framework. The packet capture framework, as part of its initialization, creates the 47multi process channel to facilitate communication with secondary process, so the 48secondary process ``app/pdump`` tool is responsible for enabling and disabling the packet capture on ports. 49 50Implementation Details 51---------------------- 52 53The library API ``rte_pdump_init()``, initializes the packet capture framework by creating the multi process 54channel using ``rte_mp_action_register()`` API. The primary process will listen to secondary process requests 55to enable or disable the packet capture over the multi process channel. 56 57The library APIs ``rte_pdump_enable()`` and ``rte_pdump_enable_by_deviceid()`` enables the packet capture. 58For the calls to these APIs from secondary process, the library creates the "pdump enable" request and sends 59the request to the primary process over the multi process channel. The primary process takes this request 60and enables the packet capture by registering the Ethernet RX and TX callbacks for the given port or device_id 61and queue combinations. Then the primary process will mirror the packets to the new mempool and enqueue them to 62the rte_ring that secondary process have passed to these APIs. 63 64The library APIs ``rte_pdump_disable()`` and ``rte_pdump_disable_by_deviceid()`` disables the packet capture. 65For the calls to these APIs from secondary process, the library creates the "pdump disable" request and sends 66the request to the primary process over the multi process channel. The primary process takes this request and 67disables the packet capture by removing the Ethernet RX and TX callbacks for the given port or device_id and 68queue combinations. 69 70The library API ``rte_pdump_uninit()``, uninitializes the packet capture framework by calling ``rte_mp_action_unregister()`` 71function. 72 73 74Use Case: Packet Capturing 75-------------------------- 76 77The DPDK ``app/pdump`` tool is developed based on this library to capture packets in DPDK. 78Users can use this as an example to develop their own packet capturing tools. 79