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 Example libmemif App
  20  */
  21
  22 #ifndef _LIBMEMIF_H_
  23 #define _LIBMEMIF_H_
  24
  25 /** Libmemif version. */
  26 #define LIBMEMIF_VERSION "3.1"
  27 /** Default name of application using libmemif. */
  28 #define MEMIF_DEFAULT_APP_NAME "libmemif-app"
  29
  30 #include <inttypes.h>
  31 #include <sys/timerfd.h>
  32
  33 /*! Error codes */
  34 typedef enum
  35 {
  36   MEMIF_ERR_SUCCESS = 0,        /*!< success */
  37 /* SYSCALL ERRORS */
  38   MEMIF_ERR_SYSCALL,            /*!< other syscall error */
  39   MEMIF_ERR_CONNREFUSED,        /*!< connection refused */
  40   MEMIF_ERR_ACCES,              /*!< permission denied */
  41   MEMIF_ERR_NO_FILE,            /*!< file does not exist */
  42   MEMIF_ERR_FILE_LIMIT,         /*!< system open file limit */
  43   MEMIF_ERR_PROC_FILE_LIMIT,    /*!< process open file limit */
  44   MEMIF_ERR_ALREADY,            /*!< connection already requested */
  45   MEMIF_ERR_AGAIN,              /*!< fd is not socket, or operation would block */
  46   MEMIF_ERR_BAD_FD,             /*!< invalid fd */
  47   MEMIF_ERR_NOMEM,              /*!< out of memory */
  48 /* LIBMEMIF ERRORS */
  49   MEMIF_ERR_INVAL_ARG,          /*!< invalid argument */
  50   MEMIF_ERR_NOCONN,             /*!< handle points to no connection */
  51   MEMIF_ERR_CONN,               /*!< handle points to existing connection */
  52   MEMIF_ERR_CB_FDUPDATE,        /*!< user defined callback memif_control_fd_update_t error */
  53   MEMIF_ERR_FILE_NOT_SOCK,      /*!< file specified by socket filename
  54                                    exists, but it's not socket */
  55   MEMIF_ERR_NO_SHMFD,           /*!< missing shm fd */
  56   MEMIF_ERR_COOKIE,             /*!< wrong cookie on ring */
  57   MEMIF_ERR_NOBUF_RING,         /*!< ring buffer full */
  58   MEMIF_ERR_NOBUF,              /*!< not enough memif buffers */
  59   MEMIF_ERR_NOBUF_DET,          /*!< memif details needs larger buffer */
  60   MEMIF_ERR_INT_WRITE,          /*!< send interrupt error */
  61   MEMIF_ERR_MFMSG,              /*!< malformed msg received */
  62   MEMIF_ERR_QID,                /*!< invalid queue id */
  63 /* MEMIF PROTO ERRORS */
  64   MEMIF_ERR_PROTO,              /*!< incompatible protocol version */
  65   MEMIF_ERR_ID,                 /*!< unmatched interface id */
  66   MEMIF_ERR_ACCSLAVE,           /*!< slave cannot accept connection requests */
  67   MEMIF_ERR_ALRCONN,            /*!< memif is already connected */
  68   MEMIF_ERR_MODE,               /*!< mode mismatch */
  69   MEMIF_ERR_SECRET,             /*!< secret mismatch */
  70   MEMIF_ERR_NOSECRET,           /*!< secret required */
  71   MEMIF_ERR_MAXREG,             /*!< max region limit reached */
  72   MEMIF_ERR_MAXRING,            /*!< max ring limit reached */
  73   MEMIF_ERR_NO_INTFD,           /*!< missing interrupt fd */
  74   MEMIF_ERR_DISCONNECT,         /*!< disconnect received */
  75   MEMIF_ERR_DISCONNECTED,       /*!< peer interface disconnected */
  76   MEMIF_ERR_UNKNOWN_MSG,        /*!< unknown message type */
  77   MEMIF_ERR_POLL_CANCEL,        /*!< memif_poll_event() was cancelled */
  78   MEMIF_ERR_MAX_RING,           /*!< too large ring size */
  79   MEMIF_ERR_PRIVHDR,            /*!< private hdrs not supported */
  80 } memif_err_t;
  81
  82 /**
  83  * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
  84  * @ingroup libmemif
  85  * @{
  86  */
  87
  88 /** user needs to set events that occurred on fd and pass them to memif_control_fd_handler */
  89 #define MEMIF_FD_EVENT_READ  (1 << 0)
  90 #define MEMIF_FD_EVENT_WRITE (1 << 1)
  91 /** inform libmemif that error occurred on fd */
  92 #define MEMIF_FD_EVENT_ERROR (1 << 2)
  93 /** if set, informs that fd is going to be closed (user may want to stop watching for events on this fd) */
  94 #define MEMIF_FD_EVENT_DEL   (1 << 3)
  95 /** update events */
  96 #define MEMIF_FD_EVENT_MOD   (1 << 4)
  97 /** @} */
  98
  99 /** \brief Memif per thread main handle
 100     Pointer of type void, pointing to internal structure.
 101     Used to identify internal per thread database.
 102 */
 103 typedef void *memif_per_thread_main_handle_t;
 104
 105 /** \brief Memif connection handle
 106     pointer of type void, pointing to internal structure
 107 */
 108 typedef void *memif_conn_handle_t;
 109
 110 /** \brief Memif socket handle
 111     pointer of type void, pointing to internal structure
 112 */
 113 typedef void *memif_socket_handle_t;
 114
 115 /** \brief Memif allocator alloc
 116     @param size - requested allocation size
 117
 118     custom memory allocator: alloc function template
 119 */
 120 typedef void *(memif_alloc_t) (size_t size);
 121
 122
 123 /** \brief Memif realloc
 124     @param ptr - pointer to memory block
 125     @param size - requested allocation size
 126
 127     custom memory reallocation
 128 */
 129 typedef void *(memif_realloc_t) (void *ptr, size_t size);
 130
 131 /** \brief Memif allocator free
 132     @param size - requested allocation size
 133
 134     custom memory allocator: free function template
 135 */
 136 typedef void (memif_free_t) (void *ptr);
 137
 138 /**
 139  * @defgroup CALLBACKS Callback functions definitions
 140  * @ingroup libmemif
 141  *
 142  * @{
 143  */
 144
 145 /** \brief Memif control file descriptor update (callback function)
 146     @param fd - new file descriptor to watch
 147     @param events - event type(s) to watch for
 148     @param private_ctx - libmemif main private context. Is NULL for
 149                          libmemif main created by memif_init()
 150
 151
 152     This callback is called when there is new fd to watch for events on
 153     or if fd is about to be closed (user mey want to stop watching for events on this fd).
 154     Private context is taken from libmemif_main, 'private_ctx' passed to memif_per_thread_init()
 155     or NULL in case of memif_init()
 156 */
 157 typedef int (memif_control_fd_update_t) (int fd, uint8_t events,
 158                                          void *private_ctx);
 159
 160 /** \brief Memif connection status update (callback function)
 161     @param conn - memif connection handle
 162     @param private_ctx - private context
 163
 164     Informs user about connection status connected/disconnected.
 165     On connected -> start watching for events on interrupt fd (optional).
 166 */
 167 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
 168                                          void *private_ctx);
 169
 170 /** \brief Memif interrupt occurred (callback function)
 171     @param conn - memif connection handle
 172     @param private_ctx - private context
 173     @param qid - queue id on which interrupt occurred
 174
 175     Called when event is received on interrupt fd.
 176 */
 177 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
 178                                  uint16_t qid);
 179
 180 /** @} */
 181
 182 /**
 183  * @defgroup EXTERNAL_REGION External region APIs
 184  * @ingroup libmemif
 185  *
 186  * @{
 187  */
 188
 189 /** \brief Get external buffer offset (optional)
 190     @param private_ctx - private context
 191
 192     Find unallocated external buffer and return its offset.
 193 */
 194 typedef uint32_t (memif_get_external_buffer_offset_t) (void *private_ctx);
 195
 196 /** \brief Add external region
 197     @param[out] addr - region address
 198     @param size - requested region size
 199     @param fd[out] - file descriptor
 200     @param private_ctx - private context
 201
 202     Called by slave. Add external region created by client.
 203 */
 204 typedef int (memif_add_external_region_t) (void * *addr, uint32_t size,
 205                                            int *fd, void *private_ctx);
 206
 207 /** \brief Get external region address
 208     @param size - requested region size
 209     @param fd - file descriptor
 210     @param private_ctx - private context
 211
 212     Called by master. Get region address from client.
 213
 214    \return region address
 215 */
 216 typedef void *(memif_get_external_region_addr_t) (uint32_t size, int fd,
 217                                                   void *private_ctx);
 218
 219 /** \brief Delete external region
 220     @param addr - region address
 221     @param size - region size
 222     @param fd - file descriptor
 223     @param private_ctx - private context
 224
 225     Delete external region.
 226 */
 227 typedef int (memif_del_external_region_t) (void *addr, uint32_t size, int fd,
 228                                            void *private_ctx);
 229
 230 /** \brief Register external region
 231     @param ar - add external region callback
 232     @param gr - get external region addr callback
 233     @param dr - delete external region callback
 234     @param go - get external buffer offset callback (optional)
 235 */
 236 void memif_register_external_region (memif_add_external_region_t * ar,
 237                                      memif_get_external_region_addr_t * gr,
 238                                      memif_del_external_region_t * dr,
 239                                      memif_get_external_buffer_offset_t * go);
 240
 241 /** \brief Register external region
 242     @param pt_main - per thread main handle
 243     @param ar - add external region callback
 244     @param gr - get external region addr callback
 245     @param dr - delete external region callback
 246     @param go - get external buffer offset callback (optional)
 247
 248 void memif_per_thread_register_external_region (memif_per_thread_main_handle_t
 249                                                 pt_main,
 250                                                 memif_add_external_region_t *
 251                                                 ar,
 252                                                 memif_get_external_region_addr_t
 253                                                 * gr,
 254                                                 memif_del_external_region_t *
 255                                                 dr,
 256                                                 memif_get_external_buffer_offset_t
 257                                                 * go);
 258
 259  @} */
 260
 261 /**
 262  * @defgroup ARGS_N_BUFS Connection arguments and buffers
 263  * @ingroup libmemif
 264  *
 265  * @{
 266  */
 267
 268 #ifndef _MEMIF_H_
 269 typedef enum
 270 {
 271   MEMIF_INTERFACE_MODE_ETHERNET = 0,
 272   MEMIF_INTERFACE_MODE_IP = 1,
 273   MEMIF_INTERFACE_MODE_PUNT_INJECT = 2,
 274 } memif_interface_mode_t;
 275 #endif /* _MEMIF_H_ */
 276
 277 /** \brief Memif connection arguments
 278     @param socket - Memif socket handle, if NULL default socket will be used.
 279                     Default socket is only supported in global database (see memif_init).
 280                     Custom database does not create a default socket
 281                     (see memif_per_thread_init).
 282                     Memif connection is stored in the same database as the socket.
 283     @param secret - optional parameter used as interface authentication
 284     @param num_s2m_rings - number of slave to master rings
 285     @param num_m2s_rings - number of master to slave rings
 286     @param buffer_size - size of buffer in shared memory
 287     @param log2_ring_size - logarithm base 2 of ring size
 288     @param is_master - 0 == master, 1 == slave
 289     @param interface_id - id used to identify peer connection
 290     @param interface_name - interface name
 291     @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
 292 */
 293 typedef struct
 294 {
 295   memif_socket_handle_t socket; /*!< default = /run/vpp/memif.sock */
 296   uint8_t secret[24];           /*!< optional (interface authentication) */
 297
 298   uint8_t num_s2m_rings;        /*!< default = 1 */
 299   uint8_t num_m2s_rings;        /*!< default = 1 */
 300   uint16_t buffer_size;         /*!< default = 2048 */
 301   uint8_t log2_ring_size;       /*!< default = 10 (1024) */
 302   uint8_t is_master;
 303
 304   uint32_t interface_id;
 305   uint8_t interface_name[32];
 306   memif_interface_mode_t mode:8;
 307 } memif_conn_args_t;
 308
 309 /*! memif receive mode */
 310 typedef enum
 311 {
 312   MEMIF_RX_MODE_INTERRUPT = 0,  /*!< interrupt mode */
 313   MEMIF_RX_MODE_POLLING         /*!< polling mode */
 314 } memif_rx_mode_t;
 315
 316 /** \brief Memif buffer
 317     @param desc_index - ring descriptor index
 318     @param ring - pointer to ring containing descriptor for this buffer
 319     @param len - available length
 320     @param flags - memif buffer flags
 321     @param data - pointer to shared memory data
 322 */
 323 typedef struct
 324 {
 325   uint16_t desc_index;
 326   void *queue;
 327   uint32_t len;
 328 /** next buffer present (chained buffers) */
 329 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
 330   uint8_t flags;
 331   void *data;
 332 } memif_buffer_t;
 333 /** @} */
 334
 335 /**
 336  * @defgroup MEMIF_DETAILS Memif details structs
 337  * @ingroup libmemif
 338  *
 339  * @{
 340  */
 341
 342 /** \brief Memif queue details
 343     @param region - region index
 344     @param qid - queue id
 345     @param ring_size - size of ring buffer in shared memory
 346     @param flags - ring flags
 347     @param head - ring head pointer
 348     @param tail - ring tail pointer
 349     @param buffer_size - buffer size on shared memory
 350 */
 351 typedef struct
 352 {
 353   uint8_t region;
 354   uint8_t qid;
 355   uint32_t ring_size;
 356 /** if set queue is in polling mode, else in interrupt mode */
 357 #define MEMIF_QUEUE_FLAG_POLLING 1
 358   uint16_t flags;
 359   uint16_t head;
 360   uint16_t tail;
 361   uint16_t buffer_size;
 362 } memif_queue_details_t;
 363
 364 /** \brief Memif region details
 365     @param index - region index
 366     @param addr - region address
 367     @param size - region size
 368     @param fd - file descriptor
 369     @param is_external - if not zero then region is defined by client
 370 */
 371 typedef struct
 372 {
 373   uint8_t index;
 374   void *addr;
 375   uint32_t size;
 376   int fd;
 377   uint8_t is_external;
 378 } memif_region_details_t;
 379
 380 /** \brief Memif details
 381     @param if_name - interface name
 382     @param inst_name - application name
 383     @param remote_if_name - peer interface name
 384     @param remote_inst_name - peer application name
 385     @param id - connection id
 386     @param secret - secret
 387     @param role - 0 = master, 1 = slave
 388     @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
 389     @param socket_filename - socket filename
 390     @param regions_num - number of regions
 391     @param regions - struct containing region details
 392     @param rx_queues_num - number of receive queues
 393     @param tx_queues_num - number of transmit queues
 394     @param rx_queues - struct containing receive queue details
 395     @param tx_queues - struct containing transmit queue details
 396     @param error - error string
 397     @param link_up_down - 1 = up (connected), 2 = down (disconnected)
 398 */
 399 typedef struct
 400 {
 401   uint8_t *if_name;
 402   uint8_t *inst_name;
 403   uint8_t *remote_if_name;
 404   uint8_t *remote_inst_name;
 405
 406   uint32_t id;
 407   uint8_t *secret;              /* optional */
 408   uint8_t role;                 /* 0 = master, 1 = slave */
 409   uint8_t mode;                 /* 0 = ethernet, 1 = ip, 2 = punt/inject */
 410   uint8_t *socket_filename;
 411   uint8_t regions_num;
 412   memif_region_details_t *regions;
 413   uint8_t rx_queues_num;
 414   uint8_t tx_queues_num;
 415   memif_queue_details_t *rx_queues;
 416   memif_queue_details_t *tx_queues;
 417
 418   uint8_t *error;
 419   uint8_t link_up_down;         /* 1 = up, 0 = down */
 420 } memif_details_t;
 421 /** @} */
 422
 423 /**
 424  * @defgroup API_CALLS Api calls
 425  * @ingroup libmemif
 426  *
 427  * @{
 428  */
 429
 430 /** \brief Memif get version
 431
 432     \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR)
 433 */
 434 uint16_t memif_get_version ();
 435
 436 /** \brief Memif get queue event file descriptor
 437     @param conn - memif connection handle
 438     @param qid - queue id
 439     @param[out] fd - returns event file descriptor
 440
 441     \return memif_err_t
 442 */
 443
 444 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
 445
 446 /** \brief Memif set rx mode
 447     @param conn - memif connection handle
 448     @param rx_mode - receive mode
 449     @param qid - queue id
 450
 451     \return memif_err_t
 452 */
 453 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
 454                        uint16_t qid);
 455
 456 /** \brief Memif strerror
 457     @param err_code - error code
 458
 459     Converts error code to error message.
 460
 461     \return Error string
 462 */
 463 char *memif_strerror (int err_code);
 464
 465 /** \brief Memif get details
 466     @param conn - memif connection handle
 467     @param md - pointer to memif details struct
 468     @param buf - buffer containing details strings
 469     @param buflen - length of buffer
 470
 471     \return memif_err_t
 472 */
 473 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
 474                        char *buf, ssize_t buflen);
 475
 476 /** \brief Memif initialization
 477     @param on_control_fd_update - if control fd updates inform user to watch new fd
 478     @param app_name - application name (will be truncated to 32 chars)
 479     @param memif_alloc - custom memory allocator, NULL = default
 480     @param memif_realloc - custom memory reallocation, NULL = default
 481     @param memif_free - custom memory free, NULL = default
 482
 483     if param on_control_fd_update is set to NULL,
 484     libmemif will handle file descriptor event polling
 485     if a valid callback is set, file descriptor event polling needs to be done by
 486     user application, all file descriptors and event types will be passed in
 487     this callback to user application
 488
 489     Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
 490     disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
 491     timer is inactive at this state. It activates with if there is at least one memif in slave mode.
 492
 493     \return memif_err_t
 494 */
 495 int memif_init (memif_control_fd_update_t * on_control_fd_update,
 496                 char *app_name, memif_alloc_t * memif_alloc,
 497                 memif_realloc_t * memif_realloc, memif_free_t * memif_free);
 498
 499 /** \brief Memif per thread initialization
 500     @param pt_main - per thread main handle
 501     @param private_ctx - private context
 502     @param on_control_fd_update - if control fd updates inform user to watch new fd
 503     @param app_name - application name (will be truncated to 32 chars)
 504     @param memif_alloc - custom memory allocator, NULL = default
 505     @param memif_realloc - custom memory reallocation, NULL = default
 506     @param memif_free - custom memory free, NULL = default
 507
 508     Per thread version of memif_init ().
 509     Instead of using global database, creates and initializes unique database,
 510     identified by 'memif_per_thread_main_handle_t'.
 511
 512     \return memif_err_t
 513 */
 514 int memif_per_thread_init (memif_per_thread_main_handle_t * pt_main,
 515                            void *private_ctx,
 516                            memif_control_fd_update_t * on_control_fd_update,
 517                            char *app_name, memif_alloc_t * memif_alloc,
 518                            memif_realloc_t * memif_realloc,
 519                            memif_free_t * memif_free);
 520
 521 /** \brief Memif cleanup
 522
 523     Free libmemif internal allocations.
 524
 525     \return 0
 526 */
 527 int memif_cleanup ();
 528
 529 /** \brief Memif per thread cleanup
 530     @param pt_main - per thread main handle
 531
 532     Free libmemif internal allocations and sets the handle to NULL.
 533
 534     \return memif_err_t
 535 */
 536 int memif_per_thread_cleanup (memif_per_thread_main_handle_t * pt_main);
 537
 538 /** \brief Memory interface create function
 539     @param conn - connection handle for client app
 540     @param args - memory interface connection arguments
 541     @param on_connect - inform user about connected status
 542     @param on_disconnect - inform user about disconnected status
 543     @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
 544     @param private_ctx - private context passed back to user with callback
 545
 546     Creates memory interface.
 547
 548     SLAVE-MODE -
 549         Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
 550         every disconnected memif in slave mode will send connection request.
 551         On success new fd is passed to user with memif_control_fd_update_t.
 552
 553     MASTER-MODE -
 554         Create listener socket and pass fd to user with memif_control_fd_update_t.
 555         If this fd is passed to memif_control_fd_handler accept will be called and
 556         new fd will be passed to user with memif_control_fd_update_t.
 557
 558
 559     \return memif_err_t
 560 */
 561 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
 562                   memif_connection_update_t * on_connect,
 563                   memif_connection_update_t * on_disconnect,
 564                   memif_interrupt_t * on_interrupt, void *private_ctx);
 565
 566 /** \brief Memif control file descriptor handler
 567     @param fd - file descriptor on which the event occurred
 568     @param events - event type(s) that occurred
 569
 570     If event occurs on any control fd, call memif_control_fd_handler.
 571     Internal - lib will "identify" fd (timerfd, listener, control) and handle event accordingly.
 572
 573     FD-TYPE -
 574         TIMERFD -
 575             Every disconnected memif in slave mode will request connection.
 576         LISTENER or CONTROL -
 577             Handle socket messaging (internal connection establishment).
 578         INTERRUPT -
 579             Call on_interrupt callback (if set).
 580
 581     \return memif_err_t
 582
 583 */
 584 int memif_control_fd_handler (int fd, uint8_t events);
 585
 586 /** \brief Memif per thread control file descriptor handler
 587     @param pt_main - per thread main handle
 588     @param fd - file descriptor on which the event occurred
 589     @param events - event type(s) that occurred
 590
 591     Per thread version of memif_control_fd_handler.
 592
 593     \return memif_err_t
 594
 595 */
 596 int memif_per_thread_control_fd_handler (memif_per_thread_main_handle_t
 597                                          pt_main, int fd, uint8_t events);
 598
 599 /** \brief Memif delete
 600     @param conn - pointer to memif connection handle
 601
 602
 603     disconnect session (free queues and regions, close file descriptors, unmap shared memory)
 604     set connection handle to NULL, to avoid possible double free
 605
 606     \return memif_err_t
 607 */
 608 int memif_delete (memif_conn_handle_t * conn);
 609
 610 /** \brief Memif buffer enq tx
 611     @param conn - memif connection handle
 612     @param qid - number identifying queue
 613     @param bufs - memif buffers
 614     @param count - number of memif buffers to enqueue
 615     @param count_out - returns number of allocated buffers
 616
 617     Enqueue buffers to specified tx queue. Can only be used by slave.
 618     Updates desc_index field for each memif buffer.
 619     If connection handle points to master returns MEMIF_ERR_INVAL_ARG.
 620
 621     \return memif_err_t
 622 */
 623 int memif_buffer_enq_tx (memif_conn_handle_t conn, uint16_t qid,
 624                          memif_buffer_t * bufs, uint16_t count,
 625                          uint16_t * count_out);
 626
 627 /** \brief Memif buffer enq tx at idx
 628     @param conn - memif connection handle
 629     @param buf_a - memif buffer
 630     @param buf_b - memif buffer
 631
 632     Swap descriptors for provided buffers and update the buffers
 633 */
 634 int memif_buffer_requeue (memif_conn_handle_t conn, memif_buffer_t *buf_a,
 635                           memif_buffer_t *buf_b);
 636
 637 /** \brief Memif buffer alloc
 638     @param conn - memif connection handle
 639     @param qid - number identifying queue
 640     @param bufs - memif buffers
 641     @param count - number of memif buffers to allocate
 642     @param count_out - returns number of allocated buffers
 643     @param size - buffer size, may return chained buffers if size > buffer_size
 644
 645     \return memif_err_t
 646 */
 647 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
 648                         memif_buffer_t * bufs, uint16_t count,
 649                         uint16_t * count_out, uint16_t size);
 650
 651 /** \brief Memif refill queue
 652     @param conn - memif connection handle
 653     @param qid - number identifying queue
 654     @param count - number of buffers to be placed on ring
 655     @param headroom - offset the buffer by headroom
 656
 657     \return memif_err_t
 658 */
 659 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
 660                         uint16_t count, uint16_t headroom);
 661
 662 /** \brief Memif transmit buffer burst
 663     @param conn - memif connection handle
 664     @param qid - number identifying queue
 665     @param bufs - memif buffers
 666     @param count - number of memif buffers to transmit
 667     @param tx - returns number of transmitted buffers
 668
 669     \return memif_err_t
 670 */
 671 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
 672                     memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
 673
 674 /** \brief Memif receive buffer burst
 675     @param conn - memif connection handle
 676     @param qid - number identifying queue
 677     @param bufs - memif buffers
 678     @param count - number of memif buffers to receive
 679     @param rx - returns number of received buffers
 680
 681     Consume interrupt event for receive queue.
 682     The event is not consumed, if memif_rx_burst fails.
 683
 684     \return memif_err_t
 685 */
 686 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
 687                     memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
 688
 689 /** \brief Memif poll event
 690     @param timeout - timeout in seconds
 691
 692     Passive event polling -
 693     timeout = 0 - dont wait for event, check event queue if there is an event and return.
 694     timeout = -1 - wait until event
 695
 696     \return memif_err_t
 697 */
 698 int memif_poll_event (int timeout);
 699
 700 /** \brief Memif per thread poll event
 701     @param pt_main - per thread main handle
 702     @param timeout - timeout in seconds
 703
 704     Per thread version of memif_poll_event.
 705
 706     \return memif_err_t
 707 */
 708 int memif_per_thread_poll_event (memif_per_thread_main_handle_t pt_main,
 709                                  int timeout);
 710
 711 /** \brief Send signal to stop concurrently running memif_poll_event().
 712
 713     The function, however, does not wait for memif_poll_event() to stop.
 714     memif_poll_event() may still return simply because an event has occurred
 715     or the timeout has elapsed, but if called repeatedly in an infinite loop,
 716     a canceled memif_poll_event() is guaranteed to return MEMIF_ERR_POLL_CANCEL
 717     in the shortest possible time.
 718     This feature was not available in the first release.
 719     Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
 720
 721     \return memif_err_t
 722 */
 723 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
 724 int memif_cancel_poll_event ();
 725 /** \brief Send signal to stop concurrently running memif_poll_event().
 726     @param pt_main - per thread main handle
 727
 728     Per thread version of memif_cancel_poll_event.
 729
 730     \return memif_err_t
 731 */
 732 int memif_per_thread_cancel_poll_event (memif_per_thread_main_handle_t
 733                                         pt_main);
 734
 735 /** \brief Set connection request timer value
 736     @param timer - new timer value
 737
 738     Timer on which all disconnected slaves request connection.
 739     See system call 'timer_settime' man-page.
 740
 741     \return memif_err_t
 742 */
 743 int memif_set_connection_request_timer (struct itimerspec timer);
 744
 745 /** \brief Set connection request timer value
 746     @param pt_main - per thread main handle
 747     @param timer - new timer value
 748
 749     Per thread version of memif_set_connection_request_timer
 750
 751     \return memif_err_t
 752 */
 753 int
 754 memif_per_thread_set_connection_request_timer (memif_per_thread_main_handle_t
 755                                                pt_main,
 756                                                struct itimerspec timer);
 757
 758 /** \brief Send connection request
 759     @param conn - memif connection handle
 760
 761     Only slave interface can request connection.
 762
 763     \return memif_err_t
 764 */
 765 int memif_request_connection (memif_conn_handle_t conn);
 766
 767 /** \brief Create memif socket
 768     @param sock - socket handle for client app
 769     @param filename - path to socket file
 770     @param private_ctx - private context
 771
 772     The first time an interface is assigned a socket, its type is determined.
 773     For master role it's 'listener', for slave role it's 'client'. Each interface
 774     requires socket of its respective type. Default socket is created if no
 775     socket handle is passed to memif_create(). It's private context is NULL.
 776     If all interfaces using this socket are deleted, the socket returns
 777     to its default state.
 778
 779     \return memif_err_t
 780 */
 781 int memif_create_socket (memif_socket_handle_t * sock, const char *filename,
 782                          void *private_ctx);
 783
 784 /** \brief Create memif socket
 785     @param pt_main - per thread main handle
 786     @param sock - socket handle for client app
 787     @param filename - path to socket file
 788     @param private_ctx - private context
 789
 790     Per thread version of memif_create_socket.
 791
 792     \return memif_err_t
 793 */
 794 int memif_per_thread_create_socket (memif_per_thread_main_handle_t pt_main,
 795                                     memif_socket_handle_t * sock,
 796                                     const char *filename, void *private_ctx);
 797
 798 /** \brief Delete memif socket
 799     @param sock - socket handle for client app
 800
 801     When trying to free socket in use, socket will not be freed and
 802     MEMIF_ERR_INVAL_ARG is returned.
 803
 804     \return memif_err_t
 805 */
 806 int memif_delete_socket (memif_socket_handle_t * sock);
 807
 808 /** \brief Get socket filename
 809     @param sock - socket handle for client app
 810
 811     Return constant pointer to socket filename.
 812
 813     \return const char *
 814 */
 815 const char *memif_get_socket_filename (memif_socket_handle_t sock);
 816
 817 /** @} */
 818
 819 #endif /* _LIBMEMIF_H_ */