extras/libmemif/src/libmemif.h

   1 /*
   2  *------------------------------------------------------------------
   3  * Copyright (c) 2017 Cisco and/or its affiliates.
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  *------------------------------------------------------------------
  16  */
  17
  18 /** @file */
  19
  20 #ifndef _LIBMEMIF_H_
  21 #define _LIBMEMIF_H_
  22
  23 /** Libmemif version. */
  24 #define LIBMEMIF_VERSION "1.0"
  25 /** Default name of application using libmemif. */
  26 #define MEMIF_DEFAULT_APP_NAME "libmemif-app"
  27
  28 #include <inttypes.h>
  29
  30 #include <memif.h>
  31
  32 /*! Error codes */
  33 typedef enum
  34 {
  35   MEMIF_ERR_SUCCESS = 0,        /*!< success */
  36 /* SYSCALL ERRORS */
  37   MEMIF_ERR_SYSCALL,            /*!< other syscall error */
  38   MEMIF_ERR_ACCES,              /*!< permission denied */
  39   MEMIF_ERR_NO_FILE,            /*!< file does not exist */
  40   MEMIF_ERR_FILE_LIMIT,         /*!< system open file limit */
  41   MEMIF_ERR_PROC_FILE_LIMIT,    /*!< process open file limit */
  42   MEMIF_ERR_ALREADY,            /*!< connection already requested */
  43   MEMIF_ERR_AGAIN,              /*!< fd is not socket, or operation would block */
  44   MEMIF_ERR_BAD_FD,             /*!< invalid fd */
  45   MEMIF_ERR_NOMEM,              /*!< out of memory */
  46 /* LIBMEMIF ERRORS */
  47   MEMIF_ERR_INVAL_ARG,          /*!< invalid argument */
  48   MEMIF_ERR_NOCONN,             /*!< handle points to no connection */
  49   MEMIF_ERR_CONN,               /*!< handle points to existing connection */
  50   MEMIF_ERR_CB_FDUPDATE,        /*!< user defined callback memif_control_fd_update_t error */
  51   MEMIF_ERR_FILE_NOT_SOCK,      /*!< file specified by socket filename
  52                                    exists, but it's not socket */
  53   MEMIF_ERR_NO_SHMFD,           /*!< missing shm fd */
  54   MEMIF_ERR_COOKIE,             /*!< wrong cookie on ring */
  55   MEMIF_ERR_NOBUF_RING,         /*!< ring buffer full */
  56   MEMIF_ERR_NOBUF,              /*!< not enough memif buffers */
  57   MEMIF_ERR_NOBUF_DET,          /*!< memif details needs larger buffer */
  58   MEMIF_ERR_INT_WRITE,          /*!< send interrupt error */
  59   MEMIF_ERR_MFMSG,              /*!< malformed msg received */
  60   MEMIF_ERR_QID,                /*!< invalid queue id */
  61 /* MEMIF PROTO ERRORS */
  62   MEMIF_ERR_PROTO,              /*!< incompatible protocol version */
  63   MEMIF_ERR_ID,                 /*!< unmatched interface id */
  64   MEMIF_ERR_ACCSLAVE,           /*!< slave cannot accept connection requests */
  65   MEMIF_ERR_ALRCONN,            /*!< memif is already connected */
  66   MEMIF_ERR_MODE,               /*!< mode mismatch */
  67   MEMIF_ERR_SECRET,             /*!< secret mismatch */
  68   MEMIF_ERR_NOSECRET,           /*!< secret required */
  69   MEMIF_ERR_MAXREG,             /*!< max region limit reached */
  70   MEMIF_ERR_MAXRING,            /*!< max ring limit reached */
  71   MEMIF_ERR_NO_INTFD,           /*!< missing interrupt fd */
  72   MEMIF_ERR_DISCONNECT,         /*!< disconenct received */
  73   MEMIF_ERR_DISCONNECTED,       /*!< peer interface disconnected */
  74   MEMIF_ERR_UNKNOWN_MSG,        /*!< unknown message type */
  75   MEMIF_ERR_POLL_CANCEL,        /*!< memif_poll_event() was cancelled */
  76   MEMIF_ERR_MAX_RING,           /*!< too large ring size */
  77 } memif_err_t;
  78
  79 /**
  80  * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
  81  *
  82  * @{
  83  */
  84
  85 /** user needs to set events that occured on fd and pass them to memif_control_fd_handler */
  86 #define MEMIF_FD_EVENT_READ  (1 << 0)
  87 #define MEMIF_FD_EVENT_WRITE (1 << 1)
  88 /** inform libmemif that error occured on fd */
  89 #define MEMIF_FD_EVENT_ERROR (1 << 2)
  90 /** if set, informs that fd is going to be closed (user may want to stop watching for events on this fd) */
  91 #define MEMIF_FD_EVENT_DEL   (1 << 3)
  92 /** update events */
  93 #define MEMIF_FD_EVENT_MOD   (1 << 4)
  94 /** @} */
  95
  96 /** *brief Memif connection handle
  97     pointer of type void, pointing to internal structure
  98 */
  99 typedef void *memif_conn_handle_t;
 100 /**
 101  * @defgroup CALLBACKS Callback functions definitions
 102  *
 103  * @{
 104  */
 105
 106 /** \brief Memif control file descriptor update (callback function)
 107     @param fd - new file descriptor to watch
 108     @param events - event type(s) to watch for
 109
 110     This callback is called when there is new fd to watch for events on
 111     or if fd is about to be closed (user mey want to stop watching for events on this fd).
 112 */
 113 typedef int (memif_control_fd_update_t) (int fd, uint8_t events);
 114
 115 /** \brief Memif connection status update (callback function)
 116     @param conn - memif connection handle
 117     @param private_ctx - private context
 118
 119     Informs user about connection status connected/disconnected.
 120     On connected -> start watching for events on interrupt fd (optional).
 121 */
 122 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
 123                                          void *private_ctx);
 124
 125 /** \brief Memif interrupt occured (callback function)
 126     @param conn - memif connection handle
 127     @param private_ctx - private context
 128     @param qid - queue id on which interrupt occured
 129
 130     Called when event is received on interrupt fd.
 131 */
 132 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
 133                                  uint16_t qid);
 134 /** @} */
 135
 136 /**
 137  * @defgroup ARGS_N_BUFS Connection arguments and buffers
 138  *
 139  * @{
 140  */
 141
 142 /** \brief Memif connection arguments
 143     @param socket_filename - socket filename
 144     @param secret - otional parameter used as interface autenthication
 145     @param num_s2m_rings - number of slave to master rings
 146     @param num_m2s_rings - number of master to slave rings
 147     @param buffer_size - size of buffer in shared memory
 148     @param log2_ring_size - logarithm base 2 of ring size
 149     @param is_master - 0 == master, 1 == slave
 150     @param interface_id - id used to identify peer connection
 151     @param interface_name - interface name
 152     @param instance_name - application name
 153     @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
 154 */
 155 typedef struct
 156 {
 157   uint8_t *socket_filename;     /*!< default = /run/vpp/memif.sock */
 158   uint8_t secret[24];           /*!< optional (interface authentication) */
 159
 160   uint8_t num_s2m_rings;        /*!< default = 1 */
 161   uint8_t num_m2s_rings;        /*!< default = 1 */
 162   uint16_t buffer_size;         /*!< default = 2048 */
 163   memif_log2_ring_size_t log2_ring_size;        /*!< default = 10 (1024) */
 164   uint8_t is_master;
 165
 166   memif_interface_id_t interface_id;
 167   uint8_t interface_name[32];
 168   uint8_t instance_name[32];
 169   memif_interface_mode_t mode:8;
 170 } memif_conn_args_t;
 171
 172 /*! memif receive mode */
 173 typedef enum
 174 {
 175   MEMIF_RX_MODE_INTERRUPT = 0,  /*!< interrupt mode */
 176   MEMIF_RX_MODE_POLLING         /*!< polling mode */
 177 } memif_rx_mode_t;
 178
 179 /** \brief Memif buffer
 180     @param desc_index - ring descriptor index
 181     @param buffer_len - shared meory buffer length
 182     @param data_len - data length
 183     @param data - pointer to shared memory data
 184 */
 185 typedef struct
 186 {
 187   uint16_t desc_index;
 188   uint32_t buffer_len;
 189   uint32_t data_len;
 190   void *data;
 191 } memif_buffer_t;
 192 /** @} */
 193
 194 /**
 195  * @defgroup MEMIF_DETAILS Memif details structs
 196  *
 197  * @{
 198  */
 199
 200 /** \brief Memif queue details
 201     @param qid - queue id
 202     @param ring_size - size of ring buffer in sharem memory
 203     @param buffer_size - buffer size on sharem memory
 204 */
 205 typedef struct
 206 {
 207   uint8_t qid;
 208   uint32_t ring_size;
 209   uint16_t buffer_size;
 210   /* add ring information */
 211 } memif_queue_details_t;
 212
 213 /** \brief Memif details
 214     @param if_name - interface name
 215     @param inst_name - application name
 216     @param remote_if_name - peer interface name
 217     @param remote_inst_name - peer application name
 218     @param id - connection id
 219     @param secret - secret
 220     @param role - 0 = master, 1 = slave
 221     @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
 222     @param socket_filename = socket filename
 223     @param rx_queues_num - number of receive queues
 224     @param tx_queues_num - number of transmit queues
 225     @param rx_queues - struct containing receive queue details
 226     @param tx_queues - struct containing transmit queue details
 227     @param link_up_down - 1 = up (connected), 2 = down (disconnected)
 228 */
 229 typedef struct
 230 {
 231   uint8_t *if_name;
 232   uint8_t *inst_name;
 233   uint8_t *remote_if_name;
 234   uint8_t *remote_inst_name;
 235
 236   uint32_t id;
 237   uint8_t *secret;              /* optional */
 238   uint8_t role;                 /* 0 = master, 1 = slave */
 239   uint8_t mode;                 /* 0 = ethernet, 1 = ip, 2 = punt/inject */
 240   uint8_t *socket_filename;
 241   uint8_t rx_queues_num;
 242   uint8_t tx_queues_num;
 243   memif_queue_details_t *rx_queues;
 244   memif_queue_details_t *tx_queues;
 245
 246   uint8_t link_up_down;         /* 1 = up, 0 = down */
 247 } memif_details_t;
 248 /** @} */
 249
 250 /**
 251  * @defgroup API_CALLS Api calls
 252  *
 253  * @{
 254  */
 255
 256 /** \biref Memif get queue event file descriptor
 257     @param conn - memif connection handle
 258     @param qid - queue id
 259     @param[out] fd - returns event file descriptor
 260
 261     \return memif_err_t
 262 */
 263
 264 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
 265
 266 /** \brief Memif set rx mode
 267     @param conn - memif connection handle
 268     @param rx_mode - receive mode
 269     @param qid - queue id
 270
 271     \return memif_err_t
 272 */
 273 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
 274                        uint16_t qid);
 275
 276 /** \brief Memif strerror
 277     @param err_code - error code
 278
 279     Converts error code to error message.
 280
 281     \return Error string
 282 */
 283 char *memif_strerror (int err_code);
 284
 285 /** \brief Memif get details
 286     @param conn - memif conenction handle
 287     @param md - pointer to memif details struct
 288     @param buf - buffer containing details strings
 289     @param buflen - length of buffer
 290
 291     \return memif_err_t
 292 */
 293 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
 294                        char *buf, ssize_t buflen);
 295
 296 /** \brief Memif initialization
 297     @param on_control_fd_update - if control fd updates inform user to watch new fd
 298     @param app_name - application name
 299
 300     if param on_control_fd_update is set to NULL,
 301     libmemif will handle file descriptor event polling
 302     if a valid callback is set, file descriptor event polling needs to be done by
 303     user application, all file descriptors and event types will be passed in
 304     this callback to user application
 305
 306     Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
 307     disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
 308     timer is inactive at this state. It activates with if there is at least one memif in slave mode.
 309
 310     \return memif_err_t
 311 */
 312 int memif_init (memif_control_fd_update_t * on_control_fd_update,
 313                 char *app_name);
 314
 315 /** \brief Memif cleanup
 316
 317     Free libmemif internal allocations.
 318
 319     \return 0
 320 */
 321 int memif_cleanup ();
 322
 323 /** \brief Memory interface create function
 324     @param conn - connection handle for user app
 325     @param args - memory interface connection arguments
 326     @param on_connect - inform user about connected status
 327     @param on_disconnect - inform user about disconnected status
 328     @param on_interrupt - informs user about interrupt, if set to null user will not be notified about interrupt, user can use memif_get_queue_efd call to get interrupt fd to poll for events
 329     @param private_ctx - private contex passed back to user with callback
 330
 331     Creates memory interface.
 332
 333     SLAVE-MODE -
 334         Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
 335         every disconnected memif in slave mode will send connection request.
 336         On success new fd is passed to user with memif_control_fd_update_t.
 337
 338     MASTER-MODE -
 339         Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
 340         If this fd is passed to memif_control_fd_handler accept will be called and
 341         new fd will be passed to user with memif_control_fd_update_t.
 342
 343
 344     \return memif_err_t
 345 */
 346 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
 347                   memif_connection_update_t * on_connect,
 348                   memif_connection_update_t * on_disconnect,
 349                   memif_interrupt_t * on_interrupt, void *private_ctx);
 350
 351 /** \brief Memif control file descriptor handler
 352     @param fd - file descriptor on which the event occured
 353     @param events - event type(s) that occured
 354
 355     If event occures on any control fd, call memif_control_fd_handler.
 356     Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
 357
 358     FD-TYPE -
 359         TIMERFD -
 360             Every disconnected memif in slave mode will request connection.
 361         LISTENER or CONTROL -
 362             Handle socket messaging (internal connection establishment).
 363         INTERRUPT -
 364             Call on_interrupt callback (if set).
 365
 366     \return memif_err_t
 367
 368 */
 369 int memif_control_fd_handler (int fd, uint8_t events);
 370
 371 /** \brief Memif delete
 372     @param conn - pointer to memif connection handle
 373
 374
 375     disconnect session (free queues and regions, close file descriptors, unmap shared memory)
 376     set connection handle to NULL, to avoid possible double free
 377
 378     \return memif_err_t
 379 */
 380 int memif_delete (memif_conn_handle_t * conn);
 381
 382 /** \brief Memif buffer alloc
 383     @param conn - memif conenction handle
 384     @param qid - number indentifying queue
 385     @param bufs - memif buffers
 386     @param count - number of memif buffers to allocate
 387     @param count_out - returns number of allocated buffers
 388     @param size - minimal buffer size, 0 = standard buffer size
 389
 390     \return memif_err_t
 391 */
 392 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
 393                         memif_buffer_t * bufs, uint16_t count,
 394                         uint16_t * count_out, uint16_t size);
 395
 396 /** \brief Memif buffer free
 397     @param conn - memif conenction handle
 398     @param qid - number indentifying queue
 399     @param bufs - memif buffers
 400     @param count - number of memif buffers to free
 401     @param count_out - returns number of freed buffers
 402
 403     \return memif_err_t
 404 */
 405 int memif_buffer_free (memif_conn_handle_t conn, uint16_t qid,
 406                        memif_buffer_t * bufs, uint16_t count,
 407                        uint16_t * count_out);
 408
 409 /** \brief Memif transmit buffer burst
 410     @param conn - memif conenction handle
 411     @param qid - number indentifying queue
 412     @param bufs - memif buffers
 413     @param count - number of memif buffers to transmit
 414     @param tx - returns number of transmitted buffers
 415
 416     \return memif_err_t
 417 */
 418 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
 419                     memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
 420
 421 /** \brief Memif receive buffer burst
 422     @param conn - memif conenction handle
 423     @param qid - number indentifying queue
 424     @param bufs - memif buffers
 425     @param count - number of memif buffers to receive
 426     @param rx - returns number of received buffers
 427
 428     \return memif_err_t
 429 */
 430 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
 431                     memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
 432
 433 /** \brief Memif poll event
 434     @param timeout - timeout in seconds
 435
 436     Passive event polling -
 437     timeout = 0 - dont wait for event, check event queue if there is an event and return.
 438     timeout = -1 - wait until event
 439
 440     \return memif_err_t
 441 */
 442 int memif_poll_event (int timeout);
 443
 444 /** \brief Send signal to stop concurrently running memif_poll_event().
 445
 446     The function, however, does not wait for memif_poll_event() to stop.
 447     memif_poll_event() may still return simply because an event has occured
 448     or the timeout has elapsed, but if called repeatedly in an infinite loop,
 449     a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
 450     in the shortest possible time.
 451     This feature was not available in the first release.
 452     Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
 453
 454     \return memif_err_t
 455 */
 456 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
 457 int memif_cancel_poll_event ();
 458 /** @} */
 459
 460 #endif /* _LIBMEMIF_H_ */