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