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