]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | .. BSD LICENSE |
2 | Copyright(c) 2016 Intel Corporation. All rights reserved. | |
3 | All rights reserved. | |
4 | ||
5 | Redistribution and use in source and binary forms, with or without | |
6 | modification, are permitted provided that the following conditions | |
7 | are met: | |
8 | ||
9 | * Redistributions of source code must retain the above copyright | |
10 | notice, this list of conditions and the following disclaimer. | |
11 | * Redistributions in binary form must reproduce the above copyright | |
12 | notice, this list of conditions and the following disclaimer in | |
13 | the documentation and/or other materials provided with the | |
14 | distribution. | |
15 | * Neither the name of Intel Corporation nor the names of its | |
16 | contributors may be used to endorse or promote products derived | |
17 | from this software without specific prior written permission. | |
18 | ||
19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
20 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
21 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
22 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
23 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
24 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
25 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
26 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
27 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
28 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
29 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
30 | ||
31 | .. _pdump_library: | |
32 | ||
33 | The librte_pdump Library | |
34 | ======================== | |
35 | ||
36 | The ``librte_pdump`` library provides a framework for packet capturing in DPDK. | |
37 | The library does the complete copy of the Rx and Tx mbufs to a new mempool and | |
38 | hence it slows down the performance of the applications, so it is recommended | |
39 | to use this library for debugging purposes. | |
40 | ||
41 | The library provides the following APIs to initialize the packet capture framework, to enable | |
42 | or disable the packet capture, and to uninitialize it: | |
43 | ||
44 | * ``rte_pdump_init()``: | |
45 | This API initializes the packet capture framework. | |
46 | ||
47 | * ``rte_pdump_enable()``: | |
48 | This API enables the packet capture on a given port and queue. | |
49 | Note: The filter option in the API is a place holder for future enhancements. | |
50 | ||
51 | * ``rte_pdump_enable_by_deviceid()``: | |
52 | This API enables the packet capture on a given device id (``vdev name or pci address``) and queue. | |
53 | Note: The filter option in the API is a place holder for future enhancements. | |
54 | ||
55 | * ``rte_pdump_disable()``: | |
56 | This API disables the packet capture on a given port and queue. | |
57 | ||
58 | * ``rte_pdump_disable_by_deviceid()``: | |
59 | This API disables the packet capture on a given device id (``vdev name or pci address``) and queue. | |
60 | ||
61 | * ``rte_pdump_uninit()``: | |
62 | This API uninitializes the packet capture framework. | |
63 | ||
64 | * ``rte_pdump_set_socket_dir()``: | |
65 | This API sets the server and client socket paths. | |
66 | Note: This API is not thread-safe. | |
67 | ||
68 | ||
69 | Operation | |
70 | --------- | |
71 | ||
72 | The ``librte_pdump`` library works on a client/server model. The server is responsible for enabling or | |
73 | disabling the packet capture and the clients are responsible for requesting the enabling or disabling of | |
74 | the packet capture. | |
75 | ||
76 | The packet capture framework, as part of its initialization, creates the pthread and the server socket in | |
77 | the pthread. The application that calls the framework initialization will have the server socket created, | |
78 | either under the path that the application has passed or under the default path i.e. either ``/var/run/.dpdk`` for | |
79 | root user or ``~/.dpdk`` for non root user. | |
80 | ||
81 | Applications that request enabling or disabling of the packet capture will have the client socket created either under | |
82 | the path that the application has passed or under the default path i.e. either ``/var/run/.dpdk`` for root user or | |
83 | ``~/.dpdk`` for not root user to send the requests to the server. The server socket will listen for client requests for | |
84 | enabling or disabling the packet capture. | |
85 | ||
86 | ||
87 | Implementation Details | |
88 | ---------------------- | |
89 | ||
90 | The library API ``rte_pdump_init()``, initializes the packet capture framework by creating the pthread and the server | |
91 | socket. The server socket in the pthread context will be listening to the client requests to enable or disable the | |
92 | packet capture. | |
93 | ||
94 | The library APIs ``rte_pdump_enable()`` and ``rte_pdump_enable_by_deviceid()`` enables the packet capture. | |
95 | On each call to these APIs, the library creates a separate client socket, creates the "pdump enable" request and sends | |
96 | the request to the server. The server that is listening on the socket will take the request and enable the packet capture | |
97 | by registering the Ethernet RX and TX callbacks for the given port or device_id and queue combinations. | |
98 | Then the server will mirror the packets to the new mempool and enqueue them to the rte_ring that clients have passed | |
99 | to these APIs. The server also sends the response back to the client about the status of the request that was processed. | |
100 | After the response is received from the server, the client socket is closed. | |
101 | ||
102 | The library APIs ``rte_pdump_disable()`` and ``rte_pdump_disable_by_deviceid()`` disables the packet capture. | |
103 | On each call to these APIs, the library creates a separate client socket, creates the "pdump disable" request and sends | |
104 | the request to the server. The server that is listening on the socket will take the request and disable the packet | |
105 | capture by removing the Ethernet RX and TX callbacks for the given port or device_id and queue combinations. The server | |
106 | also sends the response back to the client about the status of the request that was processed. After the response is | |
107 | received from the server, the client socket is closed. | |
108 | ||
109 | The library API ``rte_pdump_uninit()``, uninitializes the packet capture framework by closing the pthread and the | |
110 | server socket. | |
111 | ||
112 | The library API ``rte_pdump_set_socket_dir()``, sets the given path as either server socket path | |
113 | or client socket path based on the ``type`` argument of the API. | |
114 | If the given path is ``NULL``, default path will be selected, i.e. either ``/var/run/.dpdk`` for root user or ``~/.dpdk`` | |
115 | for non root user. Clients also need to call this API to set their server socket path if the server socket | |
116 | path is different from default path. | |
117 | ||
118 | ||
119 | Use Case: Packet Capturing | |
120 | -------------------------- | |
121 | ||
122 | The DPDK ``app/pdump`` tool is developed based on this library to capture packets in DPDK. | |
123 | Users can use this as an example to develop their own packet capturing tools. |