doc/guides/prog_guide/pdump_lib.rst

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