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