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