]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright(c) 2016 Intel Corporation. | |
7c673cae FG |
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 provides the following APIs to initialize the packet capture framework, to enable | |
15 | or disable the packet capture, and to uninitialize it: | |
16 | ||
17 | * ``rte_pdump_init()``: | |
18 | This API initializes the packet capture framework. | |
19 | ||
20 | * ``rte_pdump_enable()``: | |
21 | This API enables the packet capture on a given port and queue. | |
22 | Note: The filter option in the API is a place holder for future enhancements. | |
23 | ||
24 | * ``rte_pdump_enable_by_deviceid()``: | |
25 | This API enables the packet capture on a given device id (``vdev name or pci address``) and queue. | |
26 | Note: The filter option in the API is a place holder for future enhancements. | |
27 | ||
28 | * ``rte_pdump_disable()``: | |
29 | This API disables the packet capture on a given port and queue. | |
30 | ||
31 | * ``rte_pdump_disable_by_deviceid()``: | |
32 | This API disables the packet capture on a given device id (``vdev name or pci address``) and queue. | |
33 | ||
34 | * ``rte_pdump_uninit()``: | |
35 | This API uninitializes the packet capture framework. | |
36 | ||
7c673cae FG |
37 | |
38 | Operation | |
39 | --------- | |
40 | ||
41 | The ``librte_pdump`` library works on a client/server model. The server is responsible for enabling or | |
42 | disabling the packet capture and the clients are responsible for requesting the enabling or disabling of | |
43 | the packet capture. | |
44 | ||
45 | The packet capture framework, as part of its initialization, creates the pthread and the server socket in | |
46 | the pthread. The application that calls the framework initialization will have the server socket created, | |
47 | either under the path that the application has passed or under the default path i.e. either ``/var/run/.dpdk`` for | |
48 | root user or ``~/.dpdk`` for non root user. | |
49 | ||
50 | Applications that request enabling or disabling of the packet capture will have the client socket created either under | |
51 | the path that the application has passed or under the default path i.e. either ``/var/run/.dpdk`` for root user or | |
52 | ``~/.dpdk`` for not root user to send the requests to the server. The server socket will listen for client requests for | |
53 | enabling or disabling the packet capture. | |
54 | ||
55 | ||
56 | Implementation Details | |
57 | ---------------------- | |
58 | ||
9f95a23c TL |
59 | The library API ``rte_pdump_init()``, initializes the packet capture framework by creating the pdump server by calling |
60 | ``rte_mp_action_register()`` function. The server will listen to the client requests to enable or disable the | |
7c673cae FG |
61 | packet capture. |
62 | ||
63 | The library APIs ``rte_pdump_enable()`` and ``rte_pdump_enable_by_deviceid()`` enables the packet capture. | |
64 | On each call to these APIs, the library creates a separate client socket, creates the "pdump enable" request and sends | |
65 | the request to the server. The server that is listening on the socket will take the request and enable the packet capture | |
66 | by registering the Ethernet RX and TX callbacks for the given port or device_id and queue combinations. | |
67 | Then the server will mirror the packets to the new mempool and enqueue them to the rte_ring that clients have passed | |
68 | to these APIs. The server also sends the response back to the client about the status of the request that was processed. | |
69 | After the response is received from the server, the client socket is closed. | |
70 | ||
71 | The library APIs ``rte_pdump_disable()`` and ``rte_pdump_disable_by_deviceid()`` disables the packet capture. | |
72 | On each call to these APIs, the library creates a separate client socket, creates the "pdump disable" request and sends | |
73 | the request to the server. The server that is listening on the socket will take the request and disable the packet | |
74 | capture by removing the Ethernet RX and TX callbacks for the given port or device_id and queue combinations. The server | |
75 | also sends the response back to the client about the status of the request that was processed. After the response is | |
76 | received from the server, the client socket is closed. | |
77 | ||
9f95a23c TL |
78 | The library API ``rte_pdump_uninit()``, uninitializes the packet capture framework by calling ``rte_mp_action_unregister()`` |
79 | function. | |
7c673cae FG |
80 | |
81 | ||
82 | Use Case: Packet Capturing | |
83 | -------------------------- | |
84 | ||
85 | The DPDK ``app/pdump`` tool is developed based on this library to capture packets in DPDK. | |
86 | Users can use this as an example to develop their own packet capturing tools. |