lib/librte_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
  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
  32 enum rte_pdump_socktype {
  33         RTE_PDUMP_SOCKET_SERVER = 1,
  34         RTE_PDUMP_SOCKET_CLIENT = 2
  35 };
  36
  37 /**
  38  * Initialize packet capturing handling
  39  *
  40  * Register the IPC action for communication with target (primary) process.
  41  *
  42  * @param path
  43  * This parameter is going to be deprecated; it was used for specifying the
  44  * directory path for server socket.
  45  *
  46  * @return
  47  *    0 on success, -1 on error
  48  */
  49 int
  50 rte_pdump_init(const char *path);
  51
  52 /**
  53  * Un initialize packet capturing handling
  54  *
  55  * Unregister the IPC action for communication with target (primary) process.
  56  *
  57  * @return
  58  *    0 on success, -1 on error
  59  */
  60 int
  61 rte_pdump_uninit(void);
  62
  63 /**
  64  * Enables packet capturing on given port and queue.
  65  *
  66  * @param port
  67  *  port on which packet capturing should be enabled.
  68  * @param queue
  69  *  queue of a given port on which packet capturing should be enabled.
  70  *  users should pass on value UINT16_MAX to enable packet capturing on all
  71  *  queues of a given port.
  72  * @param flags
  73  *  flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX
  74  *  on which packet capturing should be enabled for a given port and queue.
  75  * @param ring
  76  *  ring on which captured packets will be enqueued for user.
  77  * @param mp
  78  *  mempool on to which original packets will be mirrored or duplicated.
  79  * @param filter
  80  *  place holder for packet filtering.
  81  *
  82  * @return
  83  *    0 on success, -1 on error, rte_errno is set accordingly.
  84  */
  85
  86 int
  87 rte_pdump_enable(uint16_t port, uint16_t queue, uint32_t flags,
  88                 struct rte_ring *ring,
  89                 struct rte_mempool *mp,
  90                 void *filter);
  91
  92 /**
  93  * Disables packet capturing on given port and queue.
  94  *
  95  * @param port
  96  *  port on which packet capturing should be disabled.
  97  * @param queue
  98  *  queue of a given port on which packet capturing should be disabled.
  99  *  users should pass on value UINT16_MAX to disable packet capturing on all
 100  *  queues of a given port.
 101  * @param flags
 102  *  flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX
 103  *  on which packet capturing should be enabled for a given port and queue.
 104  *
 105  * @return
 106  *    0 on success, -1 on error, rte_errno is set accordingly.
 107  */
 108
 109 int
 110 rte_pdump_disable(uint16_t port, uint16_t queue, uint32_t flags);
 111
 112 /**
 113  * Enables packet capturing on given device id and queue.
 114  * device_id can be name or pci address of device.
 115  *
 116  * @param device_id
 117  *  device id on which packet capturing should be enabled.
 118  * @param queue
 119  *  queue of a given device id on which packet capturing should be enabled.
 120  *  users should pass on value UINT16_MAX to enable packet capturing on all
 121  *  queues of a given device id.
 122  * @param flags
 123  *  flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX
 124  *  on which packet capturing should be enabled for a given port and queue.
 125  * @param ring
 126  *  ring on which captured packets will be enqueued for user.
 127  * @param mp
 128  *  mempool on to which original packets will be mirrored or duplicated.
 129  * @param filter
 130  *  place holder for packet filtering.
 131  *
 132  * @return
 133  *    0 on success, -1 on error, rte_errno is set accordingly.
 134  */
 135
 136 int
 137 rte_pdump_enable_by_deviceid(char *device_id, uint16_t queue,
 138                                 uint32_t flags,
 139                                 struct rte_ring *ring,
 140                                 struct rte_mempool *mp,
 141                                 void *filter);
 142
 143 /**
 144  * Disables packet capturing on given device_id and queue.
 145  * device_id can be name or pci address of device.
 146  *
 147  * @param device_id
 148  *  pci address or name of the device on which packet capturing
 149  *  should be disabled.
 150  * @param queue
 151  *  queue of a given device on which packet capturing should be disabled.
 152  *  users should pass on value UINT16_MAX to disable packet capturing on all
 153  *  queues of a given device id.
 154  * @param flags
 155  *  flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX
 156  *  on which packet capturing should be enabled for a given port and queue.
 157  *
 158  * @return
 159  *    0 on success, -1 on error, rte_errno is set accordingly.
 160  */
 161 int
 162 rte_pdump_disable_by_deviceid(char *device_id, uint16_t queue,
 163                                 uint32_t flags);
 164
 165 /**
 166  * @deprecated
 167  * Allows applications to set server and client socket paths.
 168  * If specified path is null default path will be selected, i.e.
 169  *"/var/run/" for root user and "$HOME" for non root user.
 170  * Clients also need to call this API to set their server path if the
 171  * server path is different from default path.
 172  * This API is not thread-safe.
 173  *
 174  * @param path
 175  * directory path for server or client socket.
 176  * @param type
 177  * specifies RTE_PDUMP_SOCKET_SERVER if socket path is for server.
 178  * (or)
 179  * specifies RTE_PDUMP_SOCKET_CLIENT if socket path is for client.
 180  *
 181  * @return
 182  * 0 on success, -EINVAL on error
 183  *
 184  */
 185 __rte_deprecated int
 186 rte_pdump_set_socket_dir(const char *path, enum rte_pdump_socktype type);
 187
 188 #ifdef __cplusplus
 189 }
 190 #endif
 191
 192 #endif /* _RTE_PDUMP_H_ */