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 #include <stdint.h>
  45 #include <rte_mempool.h>
  46 #include <rte_ring.h>
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 #define RTE_PDUMP_ALL_QUEUES UINT16_MAX
  53
  54 enum {
  55         RTE_PDUMP_FLAG_RX = 1,  /* receive direction */
  56         RTE_PDUMP_FLAG_TX = 2,  /* transmit direction */
  57         /* both receive and transmit directions */
  58         RTE_PDUMP_FLAG_RXTX = (RTE_PDUMP_FLAG_RX|RTE_PDUMP_FLAG_TX)
  59 };
  60
  61 enum rte_pdump_socktype {
  62         RTE_PDUMP_SOCKET_SERVER = 1,
  63         RTE_PDUMP_SOCKET_CLIENT = 2
  64 };
  65
  66 /**
  67  * Initialize packet capturing handling
  68  *
  69  * Creates pthread and server socket for handling clients
  70  * requests to enable/disable rxtx callbacks.
  71  *
  72  * @param path
  73  * directory path for server socket.
  74  *
  75  * @return
  76  *    0 on success, -1 on error
  77  */
  78 int
  79 rte_pdump_init(const char *path);
  80
  81 /**
  82  * Un initialize packet capturing handling
  83  *
  84  * Cancels pthread, close server socket, removes server socket address.
  85  *
  86  * @return
  87  *    0 on success, -1 on error
  88  */
  89 int
  90 rte_pdump_uninit(void);
  91
  92 /**
  93  * Enables packet capturing on given port and queue.
  94  *
  95  * @param port
  96  *  port on which packet capturing should be enabled.
  97  * @param queue
  98  *  queue of a given port on which packet capturing should be enabled.
  99  *  users should pass on value UINT16_MAX to enable 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  * @param ring
 105  *  ring on which captured packets will be enqueued for user.
 106  * @param mp
 107  *  mempool on to which original packets will be mirrored or duplicated.
 108  * @param filter
 109  *  place holder for packet filtering.
 110  *
 111  * @return
 112  *    0 on success, -1 on error, rte_errno is set accordingly.
 113  */
 114
 115 int
 116 rte_pdump_enable(uint8_t port, uint16_t queue, uint32_t flags,
 117                 struct rte_ring *ring,
 118                 struct rte_mempool *mp,
 119                 void *filter);
 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(uint8_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  *  place holder for packet filtering.
 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  * Disables packet capturing on given device_id and queue.
 174  * device_id can be name or pci address of device.
 175  *
 176  * @param device_id
 177  *  pci address or name of the device on which packet capturing
 178  *  should be disabled.
 179  * @param queue
 180  *  queue of a given device on which packet capturing should be disabled.
 181  *  users should pass on value UINT16_MAX to disable packet capturing on all
 182  *  queues of a given device id.
 183  * @param flags
 184  *  flags specifies RTE_PDUMP_FLAG_RX/RTE_PDUMP_FLAG_TX/RTE_PDUMP_FLAG_RXTX
 185  *  on which packet capturing should be enabled for a given port and queue.
 186  *
 187  * @return
 188  *    0 on success, -1 on error, rte_errno is set accordingly.
 189  */
 190 int
 191 rte_pdump_disable_by_deviceid(char *device_id, uint16_t queue,
 192                                 uint32_t flags);
 193
 194 /**
 195  * Allows applications to set server and client socket paths.
 196  * If specified path is null default path will be selected, i.e.
 197  *"/var/run/" for root user and "$HOME" for non root user.
 198  * Clients also need to call this API to set their server path if the
 199  * server path is different from default path.
 200  * This API is not thread-safe.
 201  *
 202  * @param path
 203  * directory path for server or client socket.
 204  * @param type
 205  * specifies RTE_PDUMP_SOCKET_SERVER if socket path is for server.
 206  * (or)
 207  * specifies RTE_PDUMP_SOCKET_CLIENT if socket path is for client.
 208  *
 209  * @return
 210  * 0 on success, -EINVAL on error
 211  *
 212  */
 213 int
 214 rte_pdump_set_socket_dir(const char *path, enum rte_pdump_socktype type);
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220 #endif /* _RTE_PDUMP_H_ */