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 "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,         /*!< disconenct 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 occured 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 occured 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 occured (callback function)
 171     @param conn - memif connection handle
 172     @param private_ctx - private context
 173     @param qid - queue id on which interrupt occured
 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 - otional parameter used as interface autenthication
 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 *ring;
 327   uint32_t len;
 328 /** next buffer present (chained buffers) */
 329 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
 330 /** states that buffer is from rx ring */
 331 #define MEMIF_BUFFER_FLAG_RX (1 << 1)
 332   uint8_t flags;
 333   void *data;
 334 } memif_buffer_t;
 335 /** @} */
 336
 337 /**
 338  * @defgroup MEMIF_DETAILS Memif details structs
 339  * @ingroup libmemif
 340  *
 341  * @{
 342  */
 343
 344 /** \brief Memif queue details
 345     @param region - region index
 346     @param qid - queue id
 347     @param ring_size - size of ring buffer in sharem memory
 348     @param flags - ring flags
 349     @param head - ring head pointer
 350     @param tail - ring tail pointer
 351     @param buffer_size - buffer size on sharem memory
 352 */
 353 typedef struct
 354 {
 355   uint8_t region;
 356   uint8_t qid;
 357   uint32_t ring_size;
 358 /** if set queue is in polling mode, else in interrupt mode */
 359 #define MEMIF_QUEUE_FLAG_POLLING 1
 360   uint16_t flags;
 361   uint16_t head;
 362   uint16_t tail;
 363   uint16_t buffer_size;
 364 } memif_queue_details_t;
 365
 366 /** \brief Memif region details
 367     @param index - region index
 368     @param addr - region address
 369     @param size - region size
 370     @param fd - file descriptor
 371     @param is_external - if not zero then region is defined by client
 372 */
 373 typedef struct
 374 {
 375   uint8_t index;
 376   void *addr;
 377   uint32_t size;
 378   int fd;
 379   uint8_t is_external;
 380 } memif_region_details_t;
 381
 382 /** \brief Memif details
 383     @param if_name - interface name
 384     @param inst_name - application name
 385     @param remote_if_name - peer interface name
 386     @param remote_inst_name - peer application name
 387     @param id - connection id
 388     @param secret - secret
 389     @param role - 0 = master, 1 = slave
 390     @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
 391     @param socket_filename - socket filename
 392     @param regions_num - number of regions
 393     @param regions - struct containing region details
 394     @param rx_queues_num - number of receive queues
 395     @param tx_queues_num - number of transmit queues
 396     @param rx_queues - struct containing receive queue details
 397     @param tx_queues - struct containing transmit queue details
 398     @param error - error string
 399     @param link_up_down - 1 = up (connected), 2 = down (disconnected)
 400 */
 401 typedef struct
 402 {
 403   uint8_t *if_name;
 404   uint8_t *inst_name;
 405   uint8_t *remote_if_name;
 406   uint8_t *remote_inst_name;
 407
 408   uint32_t id;
 409   uint8_t *secret;              /* optional */
 410   uint8_t role;                 /* 0 = master, 1 = slave */
 411   uint8_t mode;                 /* 0 = ethernet, 1 = ip, 2 = punt/inject */
 412   uint8_t *socket_filename;
 413   uint8_t regions_num;
 414   memif_region_details_t *regions;
 415   uint8_t rx_queues_num;
 416   uint8_t tx_queues_num;
 417   memif_queue_details_t *rx_queues;
 418   memif_queue_details_t *tx_queues;
 419
 420   uint8_t *error;
 421   uint8_t link_up_down;         /* 1 = up, 0 = down */
 422 } memif_details_t;
 423 /** @} */
 424
 425 /**
 426  * @defgroup API_CALLS Api calls
 427  * @ingroup libmemif
 428  *
 429  * @{
 430  */
 431
 432 /** \brief Memif get version
 433
 434     \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR)
 435 */
 436 uint16_t memif_get_version ();
 437
 438 /** \biref Memif get queue event file descriptor
 439     @param conn - memif connection handle
 440     @param qid - queue id
 441     @param[out] fd - returns event file descriptor
 442
 443     \return memif_err_t
 444 */
 445
 446 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
 447
 448 /** \brief Memif set rx mode
 449     @param conn - memif connection handle
 450     @param rx_mode - receive mode
 451     @param qid - queue id
 452
 453     \return memif_err_t
 454 */
 455 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
 456                        uint16_t qid);
 457
 458 /** \brief Memif strerror
 459     @param err_code - error code
 460
 461     Converts error code to error message.
 462
 463     \return Error string
 464 */
 465 char *memif_strerror (int err_code);
 466
 467 /** \brief Memif get details
 468     @param conn - memif conenction handle
 469     @param md - pointer to memif details struct
 470     @param buf - buffer containing details strings
 471     @param buflen - length of buffer
 472
 473     \return memif_err_t
 474 */
 475 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
 476                        char *buf, ssize_t buflen);
 477
 478 /** \brief Memif initialization
 479     @param on_control_fd_update - if control fd updates inform user to watch new fd
 480     @param app_name - application name (will be truncated to 32 chars)
 481     @param memif_alloc - cutom memory allocator, NULL = default
 482     @param memif_realloc - custom memory reallocation, NULL = default
 483     @param memif_free - custom memory free, NULL = default
 484
 485     if param on_control_fd_update is set to NULL,
 486     libmemif will handle file descriptor event polling
 487     if a valid callback is set, file descriptor event polling needs to be done by
 488     user application, all file descriptors and event types will be passed in
 489     this callback to user application
 490
 491     Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
 492     disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
 493     timer is inactive at this state. It activates with if there is at least one memif in slave mode.
 494
 495     \return memif_err_t
 496 */
 497 int memif_init (memif_control_fd_update_t * on_control_fd_update,
 498                 char *app_name, memif_alloc_t * memif_alloc,
 499                 memif_realloc_t * memif_realloc, memif_free_t * memif_free);
 500
 501 /** \brief Memif per thread initialization
 502     @param pt_main - per thread main handle
 503     @param private_ctx - private context
 504     @param on_control_fd_update - if control fd updates inform user to watch new fd
 505     @param app_name - application name (will be truncated to 32 chars)
 506     @param memif_alloc - cutom memory allocator, NULL = default
 507     @param memif_realloc - custom memory reallocation, NULL = default
 508     @param memif_free - custom memory free, NULL = default
 509
 510     Per thread version of memif_init ().
 511     Instead of using global database, creates and initializes unique database,
 512     identified by 'memif_per_thread_main_handle_t'.
 513
 514     \return memif_err_t
 515 */
 516 int memif_per_thread_init (memif_per_thread_main_handle_t * pt_main,
 517                            void *private_ctx,
 518                            memif_control_fd_update_t * on_control_fd_update,
 519                            char *app_name, memif_alloc_t * memif_alloc,
 520                            memif_realloc_t * memif_realloc,
 521                            memif_free_t * memif_free);
 522
 523 /** \brief Memif cleanup
 524
 525     Free libmemif internal allocations.
 526
 527     \return 0
 528 */
 529 int memif_cleanup ();
 530
 531 /** \brief Memif per thread cleanup
 532     @param pt_main - per thread main handle
 533
 534     Free libmemif internal allocations and sets the handle to NULL.
 535
 536     \return memif_err_t
 537 */
 538 int memif_per_thread_cleanup (memif_per_thread_main_handle_t * pt_main);
 539
 540 /** \brief Memory interface create function
 541     @param conn - connection handle for client app
 542     @param args - memory interface connection arguments
 543     @param on_connect - inform user about connected status
 544     @param on_disconnect - inform user about disconnected status
 545     @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
 546     @param private_ctx - private contex passed back to user with callback
 547
 548     Creates memory interface.
 549
 550     SLAVE-MODE -
 551         Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
 552         every disconnected memif in slave mode will send connection request.
 553         On success new fd is passed to user with memif_control_fd_update_t.
 554
 555     MASTER-MODE -
 556         Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
 557         If this fd is passed to memif_control_fd_handler accept will be called and
 558         new fd will be passed to user with memif_control_fd_update_t.
 559
 560
 561     \return memif_err_t
 562 */
 563 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
 564                   memif_connection_update_t * on_connect,
 565                   memif_connection_update_t * on_disconnect,
 566                   memif_interrupt_t * on_interrupt, void *private_ctx);
 567
 568 /** \brief Memif control file descriptor handler
 569     @param fd - file descriptor on which the event occured
 570     @param events - event type(s) that occured
 571
 572     If event occures on any control fd, call memif_control_fd_handler.
 573     Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
 574
 575     FD-TYPE -
 576         TIMERFD -
 577             Every disconnected memif in slave mode will request connection.
 578         LISTENER or CONTROL -
 579             Handle socket messaging (internal connection establishment).
 580         INTERRUPT -
 581             Call on_interrupt callback (if set).
 582
 583     \return memif_err_t
 584
 585 */
 586 int memif_control_fd_handler (int fd, uint8_t events);
 587
 588 /** \brief Memif per thread control file descriptor handler
 589     @param pt_main - per thread main handle
 590     @param fd - file descriptor on which the event occured
 591     @param events - event type(s) that occured
 592
 593     Per thread version of memif_control_fd_handler.
 594
 595     \return memif_err_t
 596
 597 */
 598 int memif_per_thread_control_fd_handler (memif_per_thread_main_handle_t
 599                                          pt_main, int fd, uint8_t events);
 600
 601 /** \brief Memif delete
 602     @param conn - pointer to memif connection handle
 603
 604
 605     disconnect session (free queues and regions, close file descriptors, unmap shared memory)
 606     set connection handle to NULL, to avoid possible double free
 607
 608     \return memif_err_t
 609 */
 610 int memif_delete (memif_conn_handle_t * conn);
 611
 612 /** \brief Memif buffer enq tx
 613     @param conn - memif conenction handle
 614     @param qid - number indentifying queue
 615     @param bufs - memif buffers
 616     @param count - number of memif buffers to enque
 617     @param count_out - returns number of allocated buffers
 618
 619     Slave is producer of buffers.
 620     If connection handle points to master returns MEMIF_ERR_INVAL_ARG.
 621
 622     \return memif_err_t
 623 */
 624 int memif_buffer_enq_tx (memif_conn_handle_t conn, uint16_t qid,
 625                          memif_buffer_t * bufs, uint16_t count,
 626                          uint16_t * count_out);
 627
 628 /** \brief Memif buffer alloc
 629     @param conn - memif conenction handle
 630     @param qid - number indentifying queue
 631     @param bufs - memif buffers
 632     @param count - number of memif buffers to allocate
 633     @param count_out - returns number of allocated buffers
 634     @param size - buffer size, may return chained buffers if size > buffer_size
 635
 636     \return memif_err_t
 637 */
 638 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
 639                         memif_buffer_t * bufs, uint16_t count,
 640                         uint16_t * count_out, uint16_t size);
 641
 642 /** \brief Memif refill ring
 643     @param conn - memif conenction handle
 644     @param qid - number indentifying queue
 645     @param count - number of buffers to be placed on ring
 646     @param headroom - offset the buffer by headroom
 647
 648     \return memif_err_t
 649 */
 650 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
 651                         uint16_t count, uint16_t headroom);
 652
 653 /** \brief Memif transmit buffer burst
 654     @param conn - memif conenction handle
 655     @param qid - number indentifying queue
 656     @param bufs - memif buffers
 657     @param count - number of memif buffers to transmit
 658     @param tx - returns number of transmitted buffers
 659
 660     \return memif_err_t
 661 */
 662 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
 663                     memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
 664
 665 /** \brief Memif receive buffer burst
 666     @param conn - memif conenction handle
 667     @param qid - number indentifying queue
 668     @param bufs - memif buffers
 669     @param count - number of memif buffers to receive
 670     @param rx - returns number of received buffers
 671
 672     \return memif_err_t
 673 */
 674 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
 675                     memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
 676
 677 /** \brief Memif poll event
 678     @param timeout - timeout in seconds
 679
 680     Passive event polling -
 681     timeout = 0 - dont wait for event, check event queue if there is an event and return.
 682     timeout = -1 - wait until event
 683
 684     \return memif_err_t
 685 */
 686 int memif_poll_event (int timeout);
 687
 688 /** \brief Memif poll event
 689     @param pt_main - per thread main handle
 690     @param timeout - timeout in seconds
 691
 692     Per thread version of memif_poll_event.
 693
 694     \return memif_err_t
 695 */
 696 int memif_per_thread_poll_event (memif_per_thread_main_handle_t pt_main,
 697                                  int timeout);
 698
 699 /** \brief Send signal to stop concurrently running memif_poll_event().
 700
 701     The function, however, does not wait for memif_poll_event() to stop.
 702     memif_poll_event() may still return simply because an event has occured
 703     or the timeout has elapsed, but if called repeatedly in an infinite loop,
 704     a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
 705     in the shortest possible time.
 706     This feature was not available in the first release.
 707     Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
 708
 709     \return memif_err_t
 710 */
 711 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
 712 int memif_cancel_poll_event ();
 713 /** \brief Send signal to stop concurrently running memif_poll_event().
 714     @param pt_main - per thread main handle
 715
 716     Per thread version of memif_cancel_poll_event.
 717
 718     \return memif_err_t
 719 */
 720 int memif_per_thread_cancel_poll_event (memif_per_thread_main_handle_t
 721                                         pt_main);
 722
 723 /** \brief Set connection request timer value
 724     @param timer - new timer value
 725
 726     Timer on which all disconnected slaves request connection.
 727     See system call 'timer_settime' man-page.
 728
 729     \return memif_err_t
 730 */
 731 int memif_set_connection_request_timer (struct itimerspec timer);
 732
 733 /** \brief Set connection request timer value
 734     @param pt_main - per thread main handle
 735     @param timer - new timer value
 736
 737     Per thread version of memif_set_connection_request_timer
 738
 739     \return memif_err_t
 740 */
 741 int
 742 memif_per_thread_set_connection_request_timer (memif_per_thread_main_handle_t
 743                                                pt_main,
 744                                                struct itimerspec timer);
 745
 746 /** \brief Send connection request
 747     @param conn - memif connection handle
 748
 749     Only slave interface can request connection.
 750
 751     \return memif_err_t
 752 */
 753 int memif_request_connection (memif_conn_handle_t conn);
 754
 755 /** \brief Create memif socket
 756     @param sock - socket handle for client app
 757     @param filename - path to socket file
 758     @param private_ctx - private context
 759
 760     The first time an interface is assigned a socket, its type is determined.
 761     For master role it's 'listener', for slave role it's 'client'. Each interface
 762     requires socket of its respective type. Default socket is creted if no
 763     socket handle is passed to memif_create(). It's private context is NULL.
 764     If all interfaces using this socket are deleted, the socket returns
 765     to its default state.
 766
 767     \return memif_err_t
 768 */
 769 int memif_create_socket (memif_socket_handle_t * sock, const char *filename,
 770                          void *private_ctx);
 771
 772 /** \brief Create memif socket
 773     @param pt_main - per thread main handle
 774     @param sock - socket handle for client app
 775     @param filename - path to socket file
 776     @param private_ctx - private context
 777
 778     Per thread version of memif_create_sopcket.
 779
 780     \return memif_err_t
 781 */
 782 int memif_per_thread_create_socket (memif_per_thread_main_handle_t pt_main,
 783                                     memif_socket_handle_t * sock,
 784                                     const char *filename, void *private_ctx);
 785
 786 /** \brief Delete memif socket
 787     @param sock - socket handle for client app
 788
 789     When trying to free socket in use, socket will not be freed and
 790     MEMIF_ERR_INVAL_ARG is returned.
 791
 792     \return memif_err_t
 793 */
 794 int memif_delete_socket (memif_socket_handle_t * sock);
 795
 796 /** \brief Get socket filename
 797     @param sock - socket handle for client app
 798
 799     Return constant pointer to socket filename.
 800
 801     \return cosnt char *
 802 */
 803 const char *memif_get_socket_filename (memif_socket_handle_t sock);
 804
 805 /** @} */
 806
 807 #endif /* _LIBMEMIF_H_ */