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  *  @defgroup libmemif
  20  */
  21
  22 #ifndef _LIBMEMIF_H_
  23 #define _LIBMEMIF_H_
  24
  25 /** Libmemif version. */
  26 #define LIBMEMIF_VERSION "2.0"
  27 /** Default name of application using libmemif. */
  28 #define MEMIF_DEFAULT_APP_NAME "libmemif-app"
  29
  30 #include <inttypes.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  * @ingroup libmemif
  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 /** \brief Memif allocator alloc
 102     @param size - requested allocation size
 103
 104     custom memory allocator: alloc function template
 105 */
 106 typedef void *(memif_alloc_t) (size_t size);
 107
 108 /** \brief Memif allocator free
 109     @param size - requested allocation size
 110
 111     custom memory allocator: free function template
 112 */
 113 typedef void (memif_free_t) (void *ptr);
 114
 115 /**
 116  * @defgroup CALLBACKS Callback functions definitions
 117  * @ingroup libmemif
 118  *
 119  * @{
 120  */
 121
 122 /** \brief Memif control file descriptor update (callback function)
 123     @param fd - new file descriptor to watch
 124     @param events - event type(s) to watch for
 125
 126     This callback is called when there is new fd to watch for events on
 127     or if fd is about to be closed (user mey want to stop watching for events on this fd).
 128 */
 129 typedef int (memif_control_fd_update_t) (int fd, uint8_t events);
 130
 131 /** \brief Memif connection status update (callback function)
 132     @param conn - memif connection handle
 133     @param private_ctx - private context
 134
 135     Informs user about connection status connected/disconnected.
 136     On connected -> start watching for events on interrupt fd (optional).
 137 */
 138 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
 139                                          void *private_ctx);
 140
 141 /** \brief Memif interrupt occured (callback function)
 142     @param conn - memif connection handle
 143     @param private_ctx - private context
 144     @param qid - queue id on which interrupt occured
 145
 146     Called when event is received on interrupt fd.
 147 */
 148 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
 149                                  uint16_t qid);
 150 /** @} */
 151
 152 /**
 153  * @defgroup ARGS_N_BUFS Connection arguments and buffers
 154  * @ingroup libmemif
 155  *
 156  * @{
 157  */
 158
 159 #ifndef _MEMIF_H_
 160 typedef enum
 161 {
 162   MEMIF_INTERFACE_MODE_ETHERNET = 0,
 163   MEMIF_INTERFACE_MODE_IP = 1,
 164   MEMIF_INTERFACE_MODE_PUNT_INJECT = 2,
 165 } memif_interface_mode_t;
 166 #endif /* _MEMIF_H_ */
 167
 168 /** \brief Memif connection arguments
 169     @param socket_filename - socket filename
 170     @param secret - otional parameter used as interface autenthication
 171     @param num_s2m_rings - number of slave to master rings
 172     @param num_m2s_rings - number of master to slave rings
 173     @param buffer_size - size of buffer in shared memory
 174     @param log2_ring_size - logarithm base 2 of ring size
 175     @param is_master - 0 == master, 1 == slave
 176     @param interface_id - id used to identify peer connection
 177     @param interface_name - interface name
 178     @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
 179 */
 180 typedef struct
 181 {
 182   uint8_t *socket_filename;     /*!< default = /run/vpp/memif.sock */
 183   uint8_t secret[24];           /*!< optional (interface authentication) */
 184
 185   uint8_t num_s2m_rings;        /*!< default = 1 */
 186   uint8_t num_m2s_rings;        /*!< default = 1 */
 187   uint16_t buffer_size;         /*!< default = 2048 */
 188   uint8_t log2_ring_size;       /*!< default = 10 (1024) */
 189   uint8_t is_master;
 190
 191   uint32_t interface_id;
 192   uint8_t interface_name[32];
 193   memif_interface_mode_t mode:8;
 194 } memif_conn_args_t;
 195
 196 /*! memif receive mode */
 197 typedef enum
 198 {
 199   MEMIF_RX_MODE_INTERRUPT = 0,  /*!< interrupt mode */
 200   MEMIF_RX_MODE_POLLING         /*!< polling mode */
 201 } memif_rx_mode_t;
 202
 203 /** \brief Memif buffer
 204     @param desc_index - ring descriptor index
 205     @param len - buffer length
 206     @param flags - memif buffer flags
 207     @param data - pointer to shared memory data
 208 */
 209 typedef struct
 210 {
 211   uint16_t desc_index;
 212   uint32_t len;
 213 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
 214   uint8_t flags;
 215   void *data;
 216 } memif_buffer_t;
 217 /** @} */
 218
 219 /**
 220  * @defgroup MEMIF_DETAILS Memif details structs
 221  * @ingroup libmemif
 222  *
 223  * @{
 224  */
 225
 226 /** \brief Memif queue details
 227     @param qid - queue id
 228     @param ring_size - size of ring buffer in sharem memory
 229     @param flags - ring flags
 230     @param head - ring head pointer
 231     @param tail - ring tail pointer
 232     @param buffer_size - buffer size on sharem memory
 233 */
 234 typedef struct
 235 {
 236   uint8_t qid;
 237   uint32_t ring_size;
 238 /** if set queue is in polling mode, else in interrupt mode */
 239 #define MEMIF_QUEUE_FLAG_POLLING 1
 240   uint16_t flags;
 241   uint16_t head;
 242   uint16_t tail;
 243   uint16_t buffer_size;
 244 } memif_queue_details_t;
 245
 246 /** \brief Memif details
 247     @param if_name - interface name
 248     @param inst_name - application name
 249     @param remote_if_name - peer interface name
 250     @param remote_inst_name - peer application name
 251     @param id - connection id
 252     @param secret - secret
 253     @param role - 0 = master, 1 = slave
 254     @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
 255     @param socket_filename = socket filename
 256     @param rx_queues_num - number of receive queues
 257     @param tx_queues_num - number of transmit queues
 258     @param rx_queues - struct containing receive queue details
 259     @param tx_queues - struct containing transmit queue details
 260     @param link_up_down - 1 = up (connected), 2 = down (disconnected)
 261 */
 262 typedef struct
 263 {
 264   uint8_t *if_name;
 265   uint8_t *inst_name;
 266   uint8_t *remote_if_name;
 267   uint8_t *remote_inst_name;
 268
 269   uint32_t id;
 270   uint8_t *secret;              /* optional */
 271   uint8_t role;                 /* 0 = master, 1 = slave */
 272   uint8_t mode;                 /* 0 = ethernet, 1 = ip, 2 = punt/inject */
 273   uint8_t *socket_filename;
 274   uint8_t rx_queues_num;
 275   uint8_t tx_queues_num;
 276   memif_queue_details_t *rx_queues;
 277   memif_queue_details_t *tx_queues;
 278
 279   uint8_t link_up_down;         /* 1 = up, 0 = down */
 280 } memif_details_t;
 281 /** @} */
 282
 283 /**
 284  * @defgroup API_CALLS Api calls
 285  * @ingroup libmemif
 286  *
 287  * @{
 288  */
 289
 290 /** \brief Memif get version
 291
 292     \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR)
 293 */
 294 uint16_t memif_get_version ();
 295
 296 /** \biref Memif get queue event file descriptor
 297     @param conn - memif connection handle
 298     @param qid - queue id
 299     @param[out] fd - returns event file descriptor
 300
 301     \return memif_err_t
 302 */
 303
 304 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
 305
 306 /** \brief Memif set rx mode
 307     @param conn - memif connection handle
 308     @param rx_mode - receive mode
 309     @param qid - queue id
 310
 311     \return memif_err_t
 312 */
 313 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
 314                        uint16_t qid);
 315
 316 /** \brief Memif strerror
 317     @param err_code - error code
 318
 319     Converts error code to error message.
 320
 321     \return Error string
 322 */
 323 char *memif_strerror (int err_code);
 324
 325 /** \brief Memif get details
 326     @param conn - memif conenction handle
 327     @param md - pointer to memif details struct
 328     @param buf - buffer containing details strings
 329     @param buflen - length of buffer
 330
 331     \return memif_err_t
 332 */
 333 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
 334                        char *buf, ssize_t buflen);
 335
 336 /** \brief Memif initialization
 337     @param on_control_fd_update - if control fd updates inform user to watch new fd
 338     @param app_name - application name (will be truncated to 32 chars)
 339     @param memif_alloc - cutom memory allocator, NULL = default
 340     @param memif_free - custom memory free, NULL = default
 341
 342     if param on_control_fd_update is set to NULL,
 343     libmemif will handle file descriptor event polling
 344     if a valid callback is set, file descriptor event polling needs to be done by
 345     user application, all file descriptors and event types will be passed in
 346     this callback to user application
 347
 348     Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
 349     disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
 350     timer is inactive at this state. It activates with if there is at least one memif in slave mode.
 351
 352     \return memif_err_t
 353 */
 354 int memif_init (memif_control_fd_update_t * on_control_fd_update,
 355                 char *app_name, memif_alloc_t * memif_alloc,
 356                 memif_free_t * memif_free);
 357
 358 /** \brief Memif cleanup
 359
 360     Free libmemif internal allocations.
 361
 362     \return 0
 363 */
 364 int memif_cleanup ();
 365
 366 /** \brief Memory interface create function
 367     @param conn - connection handle for user app
 368     @param args - memory interface connection arguments
 369     @param on_connect - inform user about connected status
 370     @param on_disconnect - inform user about disconnected status
 371     @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
 372     @param private_ctx - private contex passed back to user with callback
 373
 374     Creates memory interface.
 375
 376     SLAVE-MODE -
 377         Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
 378         every disconnected memif in slave mode will send connection request.
 379         On success new fd is passed to user with memif_control_fd_update_t.
 380
 381     MASTER-MODE -
 382         Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
 383         If this fd is passed to memif_control_fd_handler accept will be called and
 384         new fd will be passed to user with memif_control_fd_update_t.
 385
 386
 387     \return memif_err_t
 388 */
 389 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
 390                   memif_connection_update_t * on_connect,
 391                   memif_connection_update_t * on_disconnect,
 392                   memif_interrupt_t * on_interrupt, void *private_ctx);
 393
 394 /** \brief Memif control file descriptor handler
 395     @param fd - file descriptor on which the event occured
 396     @param events - event type(s) that occured
 397
 398     If event occures on any control fd, call memif_control_fd_handler.
 399     Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
 400
 401     FD-TYPE -
 402         TIMERFD -
 403             Every disconnected memif in slave mode will request connection.
 404         LISTENER or CONTROL -
 405             Handle socket messaging (internal connection establishment).
 406         INTERRUPT -
 407             Call on_interrupt callback (if set).
 408
 409     \return memif_err_t
 410
 411 */
 412 int memif_control_fd_handler (int fd, uint8_t events);
 413
 414 /** \brief Memif delete
 415     @param conn - pointer to memif connection handle
 416
 417
 418     disconnect session (free queues and regions, close file descriptors, unmap shared memory)
 419     set connection handle to NULL, to avoid possible double free
 420
 421     \return memif_err_t
 422 */
 423 int memif_delete (memif_conn_handle_t * conn);
 424
 425 /** \brief Memif buffer alloc
 426     @param conn - memif conenction handle
 427     @param qid - number indentifying queue
 428     @param bufs - memif buffers
 429     @param count - number of memif buffers to allocate
 430     @param count_out - returns number of allocated buffers
 431     @param size - buffer size, may return chained buffers if size > buffer_size
 432
 433     \return memif_err_t
 434 */
 435 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
 436                         memif_buffer_t * bufs, uint16_t count,
 437                         uint16_t * count_out, uint16_t size);
 438
 439 /** \brief Memif refill ring
 440     @param conn - memif conenction handle
 441     @param qid - number indentifying queue
 442     @param count - number of buffers to be placed on ring
 443
 444     \return memif_err_t
 445 */
 446 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
 447                         uint16_t count);
 448
 449 /** \brief Memif transmit buffer burst
 450     @param conn - memif conenction handle
 451     @param qid - number indentifying queue
 452     @param bufs - memif buffers
 453     @param count - number of memif buffers to transmit
 454     @param tx - returns number of transmitted buffers
 455
 456     \return memif_err_t
 457 */
 458 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
 459                     memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
 460
 461 /** \brief Memif receive buffer burst
 462     @param conn - memif conenction handle
 463     @param qid - number indentifying queue
 464     @param bufs - memif buffers
 465     @param count - number of memif buffers to receive
 466     @param rx - returns number of received buffers
 467
 468     \return memif_err_t
 469 */
 470 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
 471                     memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
 472
 473 /** \brief Memif poll event
 474     @param timeout - timeout in seconds
 475
 476     Passive event polling -
 477     timeout = 0 - dont wait for event, check event queue if there is an event and return.
 478     timeout = -1 - wait until event
 479
 480     \return memif_err_t
 481 */
 482 int memif_poll_event (int timeout);
 483
 484 /** \brief Send signal to stop concurrently running memif_poll_event().
 485
 486     The function, however, does not wait for memif_poll_event() to stop.
 487     memif_poll_event() may still return simply because an event has occured
 488     or the timeout has elapsed, but if called repeatedly in an infinite loop,
 489     a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
 490     in the shortest possible time.
 491     This feature was not available in the first release.
 492     Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
 493
 494     \return memif_err_t
 495 */
 496 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
 497 int memif_cancel_poll_event ();
 498 /** @} */
 499
 500 #endif /* _LIBMEMIF_H_ */