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