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