lib/librte_pdump/rte_pdump.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2016 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef _RTE_PDUMP_H_
  35 #define _RTE_PDUMP_H_
  36
  37 /**
  38  * @file
  39  * RTE pdump
  40  *
  41  * packet dump library to provide packet capturing support on dpdk.
  42  */
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 #define RTE_PDUMP_ALL_QUEUES UINT16_MAX
  49
  50 enum {
  51         RTE_PDUMP_FLAG_RX = 1,  /* receive direction */
  52         RTE_PDUMP_FLAG_TX = 2,  /* transmit direction */
  53         /* both receive and transmit directions */
  54         RTE_PDUMP_FLAG_RXTX = (RTE_PDUMP_FLAG_RX|RTE_PDUMP_FLAG_TX)
  55 };
  56
  57 enum rte_pdump_socktype {
  58         RTE_PDUMP_SOCKET_SERVER = 1,
  59         RTE_PDUMP_SOCKET_CLIENT = 2
  60 };
  61
  62 /**
  63  * Initialize packet capturing handling
  64  *
  65  * Creates pthread and server socket for handling clients
  66  * requests to enable/disable rxtx callbacks.
  67  *
  68  * @param path
  69  * directory path for server socket.
  70  *
  71  * @return
  72  *    0 on success, -1 on error
  73  */
  74 int
  75 rte_pdump_init(const char *path);
  76
  77 /**
  78  * Un initialize packet capturing handling
  79  *
  80  * Cancels pthread, close server socket, removes server socket address.
  81  *
  82  * @return
  83  *    0 on success, -1 on error
  84  */
  85 int
  86 rte_pdump_uninit(void);
  87
  88 /**
  89  * Enables packet capturing on given port and queue.
  90  *
  91  * @param port
  92  *  port on which packet capturing should be enabled.
  93  * @param queue
  94  *  queue of a given port on which packet capturing should be enabled.
  95  *  users should pass on value UINT16_MAX to enable packet capturing on all
  96  *  queues of a given port.
  97  * @param flags
  98  *  flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX
  99  *  on which packet capturing should be enabled for a given port and queue.
 100  * @param ring
 101  *  ring on which captured packets will be enqueued for user.
 102  * @param mp
 103  *  mempool on to which original packets will be mirrored or duplicated.
 104  * @param filter
 105  *  place holder for packet filtering.
 106  *
 107  * @return
 108  *    0 on success, -1 on error, rte_errno is set accordingly.
 109  */
 110
 111 int
 112 rte_pdump_enable(uint8_t port, uint16_t queue, uint32_t flags,
 113                 struct rte_ring *ring,
 114                 struct rte_mempool *mp,
 115                 void *filter);
 116
 117 /**
 118  * Disables packet capturing on given port and queue.
 119  *
 120  * @param port
 121  *  port on which packet capturing should be disabled.
 122  * @param queue
 123  *  queue of a given port on which packet capturing should be disabled.
 124  *  users should pass on value UINT16_MAX to disable packet capturing on all
 125  *  queues of a given port.
 126  * @param flags
 127  *  flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX
 128  *  on which packet capturing should be enabled for a given port and queue.
 129  *
 130  * @return
 131  *    0 on success, -1 on error, rte_errno is set accordingly.
 132  */
 133
 134 int
 135 rte_pdump_disable(uint8_t port, uint16_t queue, uint32_t flags);
 136
 137 /**
 138  * Enables packet capturing on given device id and queue.
 139  * device_id can be name or pci address of device.
 140  *
 141  * @param device_id
 142  *  device id on which packet capturing should be enabled.
 143  * @param queue
 144  *  queue of a given device id on which packet capturing should be enabled.
 145  *  users should pass on value UINT16_MAX to enable packet capturing on all
 146  *  queues of a given device id.
 147  * @param flags
 148  *  flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX
 149  *  on which packet capturing should be enabled for a given port and queue.
 150  * @param ring
 151  *  ring on which captured packets will be enqueued for user.
 152  * @param mp
 153  *  mempool on to which original packets will be mirrored or duplicated.
 154  * @param filter
 155  *  place holder for packet filtering.
 156  *
 157  * @return
 158  *    0 on success, -1 on error, rte_errno is set accordingly.
 159  */
 160
 161 int
 162 rte_pdump_enable_by_deviceid(char *device_id, uint16_t queue,
 163                                 uint32_t flags,
 164                                 struct rte_ring *ring,
 165                                 struct rte_mempool *mp,
 166                                 void *filter);
 167
 168 /**
 169  * Disables packet capturing on given device_id and queue.
 170  * device_id can be name or pci address of device.
 171  *
 172  * @param device_id
 173  *  pci address or name of the device on which packet capturing
 174  *  should be disabled.
 175  * @param queue
 176  *  queue of a given device on which packet capturing should be disabled.
 177  *  users should pass on value UINT16_MAX to disable packet capturing on all
 178  *  queues of a given device id.
 179  * @param flags
 180  *  flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX
 181  *  on which packet capturing should be enabled for a given port and queue.
 182  *
 183  * @return
 184  *    0 on success, -1 on error, rte_errno is set accordingly.
 185  */
 186 int
 187 rte_pdump_disable_by_deviceid(char *device_id, uint16_t queue,
 188                                 uint32_t flags);
 189
 190 /**
 191  * Allows applications to set server and client socket paths.
 192  * If specified path is null default path will be selected, i.e.
 193  *"/var/run/" for root user and "$HOME" for non root user.
 194  * Clients also need to call this API to set their server path if the
 195  * server path is different from default path.
 196  * This API is not thread-safe.
 197  *
 198  * @param path
 199  * directory path for server or client socket.
 200  * @type
 201  * specifies RTE_PDUMP_SOCKET_SERVER if socket path is for server.
 202  * (or)
 203  * specifies RTE_PDUMP_SOCKET_CLIENT if socket path is for client.
 204  *
 205  * @return
 206  * 0 on success, -EINVAL on error
 207  *
 208  */
 209 int
 210 rte_pdump_set_socket_dir(const char *path, enum rte_pdump_socktype type);
 211
 212 #ifdef __cplusplus
 213 }
 214 #endif
 215
 216 #endif /* _RTE_PDUMP_H_ */