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