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 ring - pointer to ring containing descriptor for this buffer
 207     @param len - available length
 208     @param flags - memif buffer flags
 209     @param data - pointer to shared memory data
 210 */
 211 typedef struct
 212 {
 213   uint16_t desc_index;
 214   void *ring;
 215   uint32_t len;
 216 /** next buffer present (chained buffers) */
 217 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
 218 /** states that buffer is from rx ring */
 219 #define MEMIF_BUFFER_FLAG_RX (1 << 1)
 220   uint8_t flags;
 221   void *data;
 222 } memif_buffer_t;
 223 /** @} */
 224
 225 /**
 226  * @defgroup MEMIF_DETAILS Memif details structs
 227  * @ingroup libmemif
 228  *
 229  * @{
 230  */
 231
 232 /** \brief Memif queue details
 233     @param qid - queue id
 234     @param ring_size - size of ring buffer in sharem memory
 235     @param flags - ring flags
 236     @param head - ring head pointer
 237     @param tail - ring tail pointer
 238     @param buffer_size - buffer size on sharem memory
 239 */
 240 typedef struct
 241 {
 242   uint8_t qid;
 243   uint32_t ring_size;
 244 /** if set queue is in polling mode, else in interrupt mode */
 245 #define MEMIF_QUEUE_FLAG_POLLING 1
 246   uint16_t flags;
 247   uint16_t head;
 248   uint16_t tail;
 249   uint16_t buffer_size;
 250 } memif_queue_details_t;
 251
 252 /** \brief Memif details
 253     @param if_name - interface name
 254     @param inst_name - application name
 255     @param remote_if_name - peer interface name
 256     @param remote_inst_name - peer application name
 257     @param id - connection id
 258     @param secret - secret
 259     @param role - 0 = master, 1 = slave
 260     @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
 261     @param socket_filename = socket filename
 262     @param rx_queues_num - number of receive queues
 263     @param tx_queues_num - number of transmit queues
 264     @param rx_queues - struct containing receive queue details
 265     @param tx_queues - struct containing transmit queue details
 266     @param link_up_down - 1 = up (connected), 2 = down (disconnected)
 267 */
 268 typedef struct
 269 {
 270   uint8_t *if_name;
 271   uint8_t *inst_name;
 272   uint8_t *remote_if_name;
 273   uint8_t *remote_inst_name;
 274
 275   uint32_t id;
 276   uint8_t *secret;              /* optional */
 277   uint8_t role;                 /* 0 = master, 1 = slave */
 278   uint8_t mode;                 /* 0 = ethernet, 1 = ip, 2 = punt/inject */
 279   uint8_t *socket_filename;
 280   uint8_t rx_queues_num;
 281   uint8_t tx_queues_num;
 282   memif_queue_details_t *rx_queues;
 283   memif_queue_details_t *tx_queues;
 284
 285   uint8_t link_up_down;         /* 1 = up, 0 = down */
 286 } memif_details_t;
 287 /** @} */
 288
 289 /**
 290  * @defgroup API_CALLS Api calls
 291  * @ingroup libmemif
 292  *
 293  * @{
 294  */
 295
 296 /** \brief Memif get version
 297
 298     \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR)
 299 */
 300 uint16_t memif_get_version ();
 301
 302 /** \biref Memif get queue event file descriptor
 303     @param conn - memif connection handle
 304     @param qid - queue id
 305     @param[out] fd - returns event file descriptor
 306
 307     \return memif_err_t
 308 */
 309
 310 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
 311
 312 /** \brief Memif set rx mode
 313     @param conn - memif connection handle
 314     @param rx_mode - receive mode
 315     @param qid - queue id
 316
 317     \return memif_err_t
 318 */
 319 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
 320                        uint16_t qid);
 321
 322 /** \brief Memif strerror
 323     @param err_code - error code
 324
 325     Converts error code to error message.
 326
 327     \return Error string
 328 */
 329 char *memif_strerror (int err_code);
 330
 331 /** \brief Memif get details
 332     @param conn - memif conenction handle
 333     @param md - pointer to memif details struct
 334     @param buf - buffer containing details strings
 335     @param buflen - length of buffer
 336
 337     \return memif_err_t
 338 */
 339 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
 340                        char *buf, ssize_t buflen);
 341
 342 /** \brief Memif initialization
 343     @param on_control_fd_update - if control fd updates inform user to watch new fd
 344     @param app_name - application name (will be truncated to 32 chars)
 345     @param memif_alloc - cutom memory allocator, NULL = default
 346     @param memif_free - custom memory free, NULL = default
 347
 348     if param on_control_fd_update is set to NULL,
 349     libmemif will handle file descriptor event polling
 350     if a valid callback is set, file descriptor event polling needs to be done by
 351     user application, all file descriptors and event types will be passed in
 352     this callback to user application
 353
 354     Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
 355     disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
 356     timer is inactive at this state. It activates with if there is at least one memif in slave mode.
 357
 358     \return memif_err_t
 359 */
 360 int memif_init (memif_control_fd_update_t * on_control_fd_update,
 361                 char *app_name, memif_alloc_t * memif_alloc,
 362                 memif_free_t * memif_free);
 363
 364 /** \brief Memif cleanup
 365
 366     Free libmemif internal allocations.
 367
 368     \return 0
 369 */
 370 int memif_cleanup ();
 371
 372 /** \brief Memory interface create function
 373     @param conn - connection handle for user app
 374     @param args - memory interface connection arguments
 375     @param on_connect - inform user about connected status
 376     @param on_disconnect - inform user about disconnected status
 377     @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
 378     @param private_ctx - private contex passed back to user with callback
 379
 380     Creates memory interface.
 381
 382     SLAVE-MODE -
 383         Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
 384         every disconnected memif in slave mode will send connection request.
 385         On success new fd is passed to user with memif_control_fd_update_t.
 386
 387     MASTER-MODE -
 388         Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
 389         If this fd is passed to memif_control_fd_handler accept will be called and
 390         new fd will be passed to user with memif_control_fd_update_t.
 391
 392
 393     \return memif_err_t
 394 */
 395 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
 396                   memif_connection_update_t * on_connect,
 397                   memif_connection_update_t * on_disconnect,
 398                   memif_interrupt_t * on_interrupt, void *private_ctx);
 399
 400 /** \brief Memif control file descriptor handler
 401     @param fd - file descriptor on which the event occured
 402     @param events - event type(s) that occured
 403
 404     If event occures on any control fd, call memif_control_fd_handler.
 405     Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
 406
 407     FD-TYPE -
 408         TIMERFD -
 409             Every disconnected memif in slave mode will request connection.
 410         LISTENER or CONTROL -
 411             Handle socket messaging (internal connection establishment).
 412         INTERRUPT -
 413             Call on_interrupt callback (if set).
 414
 415     \return memif_err_t
 416
 417 */
 418 int memif_control_fd_handler (int fd, uint8_t events);
 419
 420 /** \brief Memif delete
 421     @param conn - pointer to memif connection handle
 422
 423
 424     disconnect session (free queues and regions, close file descriptors, unmap shared memory)
 425     set connection handle to NULL, to avoid possible double free
 426
 427     \return memif_err_t
 428 */
 429 int memif_delete (memif_conn_handle_t * conn);
 430
 431 /** \brief Memif buffer enq tx
 432     @param conn - memif conenction handle
 433     @param qid - number indentifying queue
 434     @param bufs - memif buffers
 435     @param count - number of memif buffers to enque
 436     @param count_out - returns number of allocated buffers
 437
 438     Slave is producer of buffers.
 439     If connection handle points to master returns MEMIF_ERR_INVAL_ARG.
 440
 441     \return memif_err_t
 442 */
 443 int memif_buffer_enq_tx (memif_conn_handle_t conn, uint16_t qid,
 444                          memif_buffer_t * bufs, uint16_t count,
 445                          uint16_t * count_out);
 446
 447 /** \brief Memif buffer alloc
 448     @param conn - memif conenction handle
 449     @param qid - number indentifying queue
 450     @param bufs - memif buffers
 451     @param count - number of memif buffers to allocate
 452     @param count_out - returns number of allocated buffers
 453     @param size - buffer size, may return chained buffers if size > buffer_size
 454
 455     \return memif_err_t
 456 */
 457 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
 458                         memif_buffer_t * bufs, uint16_t count,
 459                         uint16_t * count_out, uint16_t size);
 460
 461 /** \brief Memif refill ring
 462     @param conn - memif conenction handle
 463     @param qid - number indentifying queue
 464     @param count - number of buffers to be placed on ring
 465     @param headroom - offset the buffer by headroom
 466
 467     \return memif_err_t
 468 */
 469 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
 470                         uint16_t count, uint16_t headroom);
 471
 472 /** \brief Memif transmit buffer burst
 473     @param conn - memif conenction handle
 474     @param qid - number indentifying queue
 475     @param bufs - memif buffers
 476     @param count - number of memif buffers to transmit
 477     @param tx - returns number of transmitted buffers
 478
 479     \return memif_err_t
 480 */
 481 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
 482                     memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
 483
 484 /** \brief Memif receive buffer burst
 485     @param conn - memif conenction handle
 486     @param qid - number indentifying queue
 487     @param bufs - memif buffers
 488     @param count - number of memif buffers to receive
 489     @param rx - returns number of received buffers
 490
 491     \return memif_err_t
 492 */
 493 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
 494                     memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
 495
 496 /** \brief Memif poll event
 497     @param timeout - timeout in seconds
 498
 499     Passive event polling -
 500     timeout = 0 - dont wait for event, check event queue if there is an event and return.
 501     timeout = -1 - wait until event
 502
 503     \return memif_err_t
 504 */
 505 int memif_poll_event (int timeout);
 506
 507 /** \brief Send signal to stop concurrently running memif_poll_event().
 508
 509     The function, however, does not wait for memif_poll_event() to stop.
 510     memif_poll_event() may still return simply because an event has occured
 511     or the timeout has elapsed, but if called repeatedly in an infinite loop,
 512     a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
 513     in the shortest possible time.
 514     This feature was not available in the first release.
 515     Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
 516
 517     \return memif_err_t
 518 */
 519 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
 520 int memif_cancel_poll_event ();
 521 /** @} */
 522
 523 #endif /* _LIBMEMIF_H_ */