1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2016 Intel Corporation. 3 4Packet Capture Library 5====================== 6 7The DPDK ``pdump`` library provides a framework for packet capturing in DPDK. 8The library does the complete copy of the Rx and Tx mbufs to a new mempool and 9hence it slows down the performance of the applications, so it is recommended 10to use this library for debugging purposes. 11 12The library uses a generic multi process channel to facilitate communication 13between primary and secondary process for enabling/disabling packet capture on 14ports. 15 16The library provides the following APIs to initialize the packet capture framework, to enable 17or disable the packet capture, and to uninitialize it. 18 19* ``rte_pdump_init()``: 20 This API initializes the packet capture framework. 21 22* ``rte_pdump_enable()``: 23 This API enables the packet capture on a given port and queue. 24 25* ``rte_pdump_enable_bpf()`` 26 This API enables the packet capture on a given port and queue. 27 It also allows setting an optional filter using DPDK BPF interpreter 28 and setting the captured packet length. 29 30* ``rte_pdump_enable_by_deviceid()``: 31 This API enables the packet capture on a given device id (``vdev name or pci address``) and queue. 32 33* ``rte_pdump_enable_bpf_by_deviceid()`` 34 This API enables the packet capture on a given device id (``vdev name or pci address``) and queue. 35 It also allows setting an optional filter using DPDK BPF interpreter 36 and setting the captured packet length. 37 38* ``rte_pdump_disable()``: 39 This API disables the packet capture on a given port and queue. 40 41* ``rte_pdump_disable_by_deviceid()``: 42 This API disables the packet capture on a given device id (``vdev name or pci address``) and queue. 43 44* ``rte_pdump_uninit()``: 45 This API uninitializes the packet capture framework. 46 47 48Operation 49--------- 50 51The primary process using ``librte_pdump`` is responsible for initializing the packet 52capture framework. The packet capture framework, as part of its initialization, creates the 53multi process channel to facilitate communication with secondary process, so the 54secondary process ``app/pdump`` tool is responsible for enabling and disabling the packet capture on ports. 55 56Implementation Details 57---------------------- 58 59The library API ``rte_pdump_init()``, initializes the packet capture framework by creating the multi process 60channel using ``rte_mp_action_register()`` API. The primary process will listen to secondary process requests 61to enable or disable the packet capture over the multi process channel. 62 63The library APIs ``rte_pdump_enable()`` and ``rte_pdump_enable_by_deviceid()`` enables the packet capture. 64For the calls to these APIs from secondary process, the library creates the "pdump enable" request and sends 65the request to the primary process over the multi process channel. The primary process takes this request 66and enables the packet capture by registering the Ethernet RX and TX callbacks for the given port or device_id 67and queue combinations. Then the primary process will mirror the packets to the new mempool and enqueue them to 68the rte_ring that secondary process have passed to these APIs. 69 70The packet ring supports one of two formats. 71The default format enqueues copies of the original packets into the rte_ring. 72If the ``RTE_PDUMP_FLAG_PCAPNG`` is set, the mbuf data is extended 73with header and trailer to match the format of Pcapng enhanced packet block. 74The enhanced packet block has meta-data such as the timestamp, port and queue 75the packet was captured on. 76It is up to the application consuming the packets from the ring 77to select the format desired. 78 79The library APIs ``rte_pdump_disable()`` and ``rte_pdump_disable_by_deviceid()`` disables the packet capture. 80For the calls to these APIs from secondary process, the library creates the "pdump disable" request and sends 81the request to the primary process over the multi process channel. The primary process takes this request and 82disables the packet capture by removing the Ethernet RX and TX callbacks for the given port or device_id and 83queue combinations. 84 85The library API ``rte_pdump_uninit()``, uninitializes the packet capture framework by calling ``rte_mp_action_unregister()`` 86function. 87 88 89Use Case: Packet Capturing 90-------------------------- 91 92The DPDK ``app/dpdk-dumpcap`` utility uses this library 93to capture packets in DPDK. 94