lib/pdump/rte_pdump.h

   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_ */