1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2016 Intel Corporation 3 */ 4 5 #ifndef _RTE_PDUMP_H_ 6 #define _RTE_PDUMP_H_ 7 8 /** 9 * @file 10 * RTE pdump 11 * 12 * packet dump library to provide packet capturing support on dpdk. 13 */ 14 15 #include <stdint.h> 16 #include <rte_bpf.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 #define RTE_PDUMP_ALL_QUEUES UINT16_MAX 23 24 enum { 25 RTE_PDUMP_FLAG_RX = 1, /* receive direction */ 26 RTE_PDUMP_FLAG_TX = 2, /* transmit direction */ 27 /* both receive and transmit directions */ 28 RTE_PDUMP_FLAG_RXTX = (RTE_PDUMP_FLAG_RX|RTE_PDUMP_FLAG_TX), 29 30 RTE_PDUMP_FLAG_PCAPNG = 4, /* format for pcapng */ 31 }; 32 33 /** 34 * Initialize packet capturing handling 35 * 36 * Register the IPC action for communication with target (primary) process. 37 * 38 * @return 39 * 0 on success, -1 on error 40 */ 41 int 42 rte_pdump_init(void); 43 44 /** 45 * Un initialize packet capturing handling 46 * 47 * Unregister the IPC action for communication with target (primary) process. 48 * 49 * @return 50 * 0 on success, -1 on error 51 */ 52 int 53 rte_pdump_uninit(void); 54 55 /** 56 * Enables packet capturing on given port and queue. 57 * 58 * @param port 59 * port on which packet capturing should be enabled. 60 * @param queue 61 * queue of a given port on which packet capturing should be enabled. 62 * users should pass on value UINT16_MAX to enable packet capturing on all 63 * queues of a given port. 64 * @param flags 65 * flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX 66 * on which packet capturing should be enabled for a given port and queue. 67 * @param ring 68 * ring on which captured packets will be enqueued for user. 69 * @param mp 70 * mempool on to which original packets will be mirrored or duplicated. 71 * @param filter 72 * Unused should be NULL. 73 * 74 * @return 75 * 0 on success, -1 on error, rte_errno is set accordingly. 76 */ 77 78 int 79 rte_pdump_enable(uint16_t port, uint16_t queue, uint32_t flags, 80 struct rte_ring *ring, 81 struct rte_mempool *mp, 82 void *filter); 83 84 /** 85 * @warning 86 * @b EXPERIMENTAL: this API may change, or be removed, without prior notice 87 * 88 * Enables packet capturing on given port and queue with filtering. 89 * 90 * @param port_id 91 * The Ethernet port on which packet capturing should be enabled. 92 * @param queue 93 * The queue on the Ethernet port which packet capturing 94 * should be enabled. Pass UINT16_MAX to enable packet capturing on all 95 * queues of a given port. 96 * @param flags 97 * Pdump library flags that specify direction and packet format. 98 * @param snaplen 99 * The upper limit on bytes to copy. 100 * Passing UINT32_MAX means capture all the possible data. 101 * @param ring 102 * The ring on which captured packets will be enqueued for user. 103 * @param mp 104 * The mempool on to which original packets will be mirrored or duplicated. 105 * @param prm 106 * Use BPF program to run to filter packes (can be NULL) 107 * 108 * @return 109 * 0 on success, -1 on error, rte_errno is set accordingly. 110 */ 111 __rte_experimental 112 int 113 rte_pdump_enable_bpf(uint16_t port_id, uint16_t queue, 114 uint32_t flags, uint32_t snaplen, 115 struct rte_ring *ring, 116 struct rte_mempool *mp, 117 const struct rte_bpf_prm *prm); 118 119 /** 120 * Disables packet capturing on given port and queue. 121 * 122 * @param port 123 * port on which packet capturing should be disabled. 124 * @param queue 125 * queue of a given port on which packet capturing should be disabled. 126 * users should pass on value UINT16_MAX to disable packet capturing on all 127 * queues of a given port. 128 * @param flags 129 * flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX 130 * on which packet capturing should be enabled for a given port and queue. 131 * 132 * @return 133 * 0 on success, -1 on error, rte_errno is set accordingly. 134 */ 135 136 int 137 rte_pdump_disable(uint16_t port, uint16_t queue, uint32_t flags); 138 139 /** 140 * Enables packet capturing on given device id and queue. 141 * device_id can be name or pci address of device. 142 * 143 * @param device_id 144 * device id on which packet capturing should be enabled. 145 * @param queue 146 * queue of a given device id on which packet capturing should be enabled. 147 * users should pass on value UINT16_MAX to enable packet capturing on all 148 * queues of a given device id. 149 * @param flags 150 * flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX 151 * on which packet capturing should be enabled for a given port and queue. 152 * @param ring 153 * ring on which captured packets will be enqueued for user. 154 * @param mp 155 * mempool on to which original packets will be mirrored or duplicated. 156 * @param filter 157 * unused should be NULL 158 * 159 * @return 160 * 0 on success, -1 on error, rte_errno is set accordingly. 161 */ 162 163 int 164 rte_pdump_enable_by_deviceid(char *device_id, uint16_t queue, 165 uint32_t flags, 166 struct rte_ring *ring, 167 struct rte_mempool *mp, 168 void *filter); 169 170 /** 171 * @warning 172 * @b EXPERIMENTAL: this API may change, or be removed, without prior notice 173 * 174 * Enables packet capturing on given device id and queue with filtering. 175 * device_id can be name or pci address of device. 176 * 177 * @param device_id 178 * device id on which packet capturing should be enabled. 179 * @param queue 180 * The queue on the Ethernet port which packet capturing 181 * should be enabled. Pass UINT16_MAX to enable packet capturing on all 182 * queues of a given port. 183 * @param flags 184 * Pdump library flags that specify direction and packet format. 185 * @param snaplen 186 * The upper limit on bytes to copy. 187 * Passing UINT32_MAX means capture all the possible data. 188 * @param ring 189 * The ring on which captured packets will be enqueued for user. 190 * @param mp 191 * The mempool on to which original packets will be mirrored or duplicated. 192 * @param filter 193 * Use BPF program to run to filter packes (can be NULL) 194 * 195 * @return 196 * 0 on success, -1 on error, rte_errno is set accordingly. 197 */ 198 __rte_experimental 199 int 200 rte_pdump_enable_bpf_by_deviceid(const char *device_id, uint16_t queue, 201 uint32_t flags, uint32_t snaplen, 202 struct rte_ring *ring, 203 struct rte_mempool *mp, 204 const struct rte_bpf_prm *filter); 205 206 207 /** 208 * Disables packet capturing on given device_id and queue. 209 * device_id can be name or pci address of device. 210 * 211 * @param device_id 212 * pci address or name of the device on which packet capturing 213 * should be disabled. 214 * @param queue 215 * queue of a given device on which packet capturing should be disabled. 216 * users should pass on value UINT16_MAX to disable packet capturing on all 217 * queues of a given device id. 218 * @param flags 219 * flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX 220 * on which packet capturing should be enabled for a given port and queue. 221 * 222 * @return 223 * 0 on success, -1 on error, rte_errno is set accordingly. 224 */ 225 int 226 rte_pdump_disable_by_deviceid(char *device_id, uint16_t queue, 227 uint32_t flags); 228 229 230 /** 231 * A structure used to retrieve statistics from packet capture. 232 * The statistics are sum of both receive and transmit queues. 233 */ 234 struct rte_pdump_stats { 235 uint64_t accepted; /**< Number of packets accepted by filter. */ 236 uint64_t filtered; /**< Number of packets rejected by filter. */ 237 uint64_t nombuf; /**< Number of mbuf allocation failures. */ 238 uint64_t ringfull; /**< Number of missed packets due to ring full. */ 239 240 uint64_t reserved[4]; /**< Reserved and pad to cache line */ 241 }; 242 243 /** 244 * @warning 245 * @b EXPERIMENTAL: this API may change, or be removed, without prior notice 246 * 247 * Retrieve the packet capture statistics for a queue. 248 * 249 * @param port_id 250 * The port identifier of the Ethernet device. 251 * @param stats 252 * A pointer to structure of type *rte_pdump_stats* to be filled in. 253 * @return 254 * Zero if successful. -1 on error and rte_errno is set. 255 */ 256 __rte_experimental 257 int 258 rte_pdump_stats(uint16_t port_id, struct rte_pdump_stats *stats); 259 260 261 #ifdef __cplusplus 262 } 263 #endif 264 265 #endif /* _RTE_PDUMP_H_ */ 266