Skip to content

Commit b63e7db

Browse files
shemmingertmonjalo
shemminger
authored and
tmonjalo
committed
doc: update pdump guide
The documentation was missing some of the API, and had some awkward wording. With the help of ChatGPT, update it and make it more concise. Signed-off-by: Stephen Hemminger <[email protected]> Acked-by: Bruce Richardson <[email protected]> Acked-by: Khadem Ullah <[email protected]>
1 parent 0dea03e commit b63e7db

File tree

2 files changed

+263
-68
lines changed

2 files changed

+263
-68
lines changed

‎doc/guides/prog_guide/img/pdump_overview.svg‎

Lines changed: 135 additions & 0 deletions
Loading

‎doc/guides/prog_guide/pdump_lib.rst‎

Lines changed: 128 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -4,90 +4,150 @@
44
Packet Capture Library
55
======================
66

7-
The DPDK ``pdump`` library provides a framework for packet capturing in DPDK.
8-
The library does the complete copy of the Rx and Tx mbufs to a new mempool and
9-
hence it slows down the performance of the applications, so it is recommended
10-
to use this library for debugging purposes.
7+
The DPDK ``pdump`` library provides a framework
8+
for capturing packets within DPDK applications.
9+
It enables a **secondary process** to monitor packets
10+
being processed by both **primary** or **secondary** processes.
1111

12-
The library uses a generic multi process channel to facilitate communication
13-
between primary and secondary process for enabling/disabling packet capture on
14-
ports.
1512

16-
The library provides the following APIs to initialize the packet capture framework, to enable
17-
or disable the packet capture, and to uninitialize it.
13+
Overview
14+
--------
1815

19-
* ``rte_pdump_init()``:
20-
This API initializes the packet capture framework.
16+
The library uses a multi-process channel
17+
to facilitate communication between the primary and secondary processes.
18+
This mechanism allows enabling or disabling packet capture
19+
on specific ports or queues.
2120

22-
* ``rte_pdump_enable()``:
23-
This API enables the packet capture on a given port and queue.
21+
.. _figure_pdump_overview:
2422

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.
23+
.. figure:: img/pdump_overview.*
2924

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.
25+
Packet Capture enable and disable sequence
3226

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.
3727

38-
* ``rte_pdump_disable()``:
39-
This API disables the packet capture on a given port and queue.
28+
API Reference
29+
-------------
4030

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.
31+
The library exposes API for:
4332

44-
* ``rte_pdump_uninit()``:
45-
This API uninitializes the packet capture framework.
33+
* Initializing and uninitializing the packet capture framework.
34+
* Enabling and disabling packet capture.
35+
* Applying optional filters and limiting captured packet length.
36+
37+
38+
.. function:: int rte_pdump_init(void)
39+
40+
Initialize the packet capture framework.
41+
42+
.. function:: int rte_pdump_enable(uint16_t port_id, uint16_t queue, uint32_t flags)
43+
44+
Enable packet capture on the specified port and queue.
45+
46+
.. function:: int rte_pdump_enable_bpf(uint16_t port_id, uint16_t queue, const struct rte_bpf_program *bpf, uint32_t snaplen)
47+
48+
Enable packet capture on the specified port and queue
49+
with an optional BPF packet filter
50+
and a limit on the captured packet length.
51+
52+
.. function:: int rte_pdump_enable_by_deviceid(const char *device_id, uint16_t queue, uint32_t flags)
53+
54+
Enable packet capture on the specified device ID (``vdev`` name or PCI address)
55+
and queue.
56+
57+
.. function:: int rte_pdump_enable_bpf_by_deviceid(const char *device_id, uint16_t queue, const struct rte_bpf_program *bpf, uint32_t snaplen)
58+
59+
Enable packet capture on the specified device ID (``vdev`` name or PCI address)
60+
and queue, with optional filtering and captured packet length limit.
61+
62+
.. function:: int rte_pdump_disable(uint16_t port_id, uint16_t queue)
63+
64+
Disable packet capture on the specified port and queue.
65+
This applies to the current process and all other processes.
66+
67+
.. function:: int rte_pdump_disable_by_deviceid(const char *device_id, uint16_t queue)
68+
69+
Disable packet capture on the specified device ID (``vdev`` name or PCI address)
70+
and queue.
71+
72+
.. function:: int rte_pdump_uninit(void)
73+
74+
Uninitialize the packet capture framework for this process.
75+
76+
.. function:: int rte_pdump_stats(uint16_t port_id, struct rte_dump_stats *stats)
77+
78+
Reports the number of packets captured, filtered, and missed.
79+
Packets maybe missed due to mbuf pool being exhausted or the ring being full.
4680

4781

4882
Operation
4983
---------
5084

51-
The primary process using ``librte_pdump`` is responsible for initializing the packet
52-
capture framework. The packet capture framework, as part of its initialization, creates the
53-
multi process channel to facilitate communication with secondary process, so the
54-
secondary process ``app/pdump`` tool is responsible for enabling and disabling the packet capture on ports.
85+
All processes using ``librte_pdump`` must initialize
86+
the packet capture framework before use.
87+
This initialization is required in both the primary and secondary processes.
88+
89+
DPDK provides the following utilities that use this library:
90+
91+
* ``dpdk-dumpcap``
92+
* ``dpdk-pdump``
93+
5594

5695
Implementation Details
5796
----------------------
5897

59-
The library API ``rte_pdump_init()``, initializes the packet capture framework by creating the multi process
60-
channel using ``rte_mp_action_register()`` API. The primary process will listen to secondary process requests
61-
to enable or disable the packet capture over the multi process channel.
62-
63-
The library APIs ``rte_pdump_enable()`` and ``rte_pdump_enable_by_deviceid()`` enables the packet capture.
64-
For the calls to these APIs from secondary process, the library creates the "pdump enable" request and sends
65-
the request to the primary process over the multi process channel. The primary process takes this request
66-
and enables the packet capture by registering the Ethernet RX and TX callbacks for the given port or device_id
67-
and queue combinations. Then the primary process will mirror the packets to the new mempool and enqueue them to
68-
the rte_ring that secondary process have passed to these APIs.
69-
70-
The packet ring supports one of two formats.
71-
The default format enqueues copies of the original packets into the rte_ring.
72-
If the ``RTE_PDUMP_FLAG_PCAPNG`` is set, the mbuf data is extended
73-
with header and trailer to match the format of Pcapng enhanced packet block.
74-
The enhanced packet block has meta-data such as the timestamp, port and queue
75-
the packet was captured on.
76-
It is up to the application consuming the packets from the ring
77-
to select the format desired.
78-
79-
The library APIs ``rte_pdump_disable()`` and ``rte_pdump_disable_by_deviceid()`` disables the packet capture.
80-
For the calls to these APIs from secondary process, the library creates the "pdump disable" request and sends
81-
the request to the primary process over the multi process channel. The primary process takes this request and
82-
disables the packet capture by removing the Ethernet RX and TX callbacks for the given port or device_id and
83-
queue combinations.
84-
85-
The library API ``rte_pdump_uninit()``, uninitializes the packet capture framework by calling ``rte_mp_action_unregister()``
86-
function.
87-
88-
89-
Use Case: Packet Capturing
90-
--------------------------
91-
92-
The DPDK ``app/dpdk-dumpcap`` utility uses this library
93-
to capture packets in DPDK.
98+
``rte_pdump_init()`` creates the multi-process channel
99+
by calling ``rte_mp_action_register()``.
100+
101+
The primary process listens for requests from secondary processes
102+
to enable or disable packet capture over the multi-process channel.
103+
104+
When a secondary process calls ``rte_pdump_enable()``
105+
or ``rte_pdump_enable_by_deviceid()``,
106+
the library sends a "pdump enable" request
107+
to the primary process.
108+
The primary process then:
109+
110+
#. Receives the request over the multi-process channel.
111+
#. Registers Ethernet Rx and Tx callbacks for the specified port.
112+
#. Forwards the request to other secondary processes (if any).
113+
114+
115+
FAQ
116+
---
117+
118+
What is the performance impact of pdump?
119+
120+
Setting up pdump with ``rte_pdump_init`` has no impact,
121+
there are no changes in the fast path.
122+
When pdump is enabled, the Tx and Rx fast path functions
123+
callbacks make a copy of the mbufs and enqueue them.
124+
This will impact performance.
125+
The effect can be reduced by filtering
126+
to only see the packets of interest
127+
and using the ``snaplen`` parameter to only copy the needed headers.
128+
129+
What happens if process does not call pdump init?
130+
131+
If application does not call ``rte_pdump_init``
132+
then the request to enable (in the capture command)
133+
will timeout and an error is returned.
134+
135+
Where do packets go?
136+
137+
Packets captured are placed in the ring passed in ``rte_pdump_enable``.
138+
The capture application must dequeue these mbuf's and free them.
139+
140+
Why is copy required?
141+
142+
A copy is used instead of incrementing the reference count
143+
because on transmit the device may be using fast free which does not use refcounts;
144+
and on receive the application may modify the incoming packet.
145+
146+
What about offloads?
147+
148+
The offload flags of the original mbuf are copied to the ring.
149+
It is up to the capture application to handle flags like VLAN stripping
150+
as necessary.
151+
Packets are captured before passing to driver and hardware
152+
so the actual packet on the wire may be segmented or encapsulated
153+
based on the offload flags.

0 commit comments

Comments
 (0)