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