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
 149     This callback is called when there is new fd to watch for events on
 150     or if fd is about to be closed (user mey want to stop watching for events on this fd).
 151 */
 152 typedef int (memif_control_fd_update_t) (int fd, uint8_t events,
 153                                          void *private_ctx);
 154
 155 /** \brief Memif connection status update (callback function)
 156     @param conn - memif connection handle
 157     @param private_ctx - private context
 158
 159     Informs user about connection status connected/disconnected.
 160     On connected -> start watching for events on interrupt fd (optional).
 161 */
 162 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
 163                                          void *private_ctx);
 164
 165 /** \brief Memif interrupt occured (callback function)
 166     @param conn - memif connection handle
 167     @param private_ctx - private context
 168     @param qid - queue id on which interrupt occured
 169
 170     Called when event is received on interrupt fd.
 171 */
 172 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
 173                                  uint16_t qid);
 174
 175 /** @} */
 176
 177 /**
 178  * @defgroup EXTERNAL_REGION External region APIs
 179  * @ingroup libmemif
 180  *
 181  * @{
 182  */
 183
 184 /** \brief Get external buffer offset (optional)
 185     @param private_ctx - private context
 186
 187     Find unallocated external buffer and return its offset.
 188 */
 189 typedef uint32_t (memif_get_external_buffer_offset_t) (void *private_ctx);
 190
 191 /** \brief Add external region
 192     @param[out] addr - region address
 193     @param size - requested region size
 194     @param fd[out] - file descriptor
 195     @param private_ctx - private context
 196
 197     Called by slave. Add external region created by client.
 198 */
 199 typedef int (memif_add_external_region_t) (void * *addr, uint32_t size,
 200                                            int *fd, void *private_ctx);
 201
 202 /** \brief Get external region address
 203     @param size - requested region size
 204     @param fd - file descriptor
 205     @param private_ctx - private context
 206
 207     Called by master. Get region address from client.
 208
 209    \return region address
 210 */
 211 typedef void *(memif_get_external_region_addr_t) (uint32_t size, int fd,
 212                                                   void *private_ctx);
 213
 214 /** \brief Delete external region
 215     @param addr - region address
 216     @param size - region size
 217     @param fd - file descriptor
 218     @param private_ctx - private context
 219
 220     Delete external region.
 221 */
 222 typedef int (memif_del_external_region_t) (void *addr, uint32_t size, int fd,
 223                                            void *private_ctx);
 224
 225 /** \brief Register external region
 226     @param ar - add external region callback
 227     @param gr - get external region addr callback
 228     @param dr - delete external region callback
 229     @param go - get external buffer offset callback (optional)
 230 */
 231 void memif_register_external_region (memif_add_external_region_t * ar,
 232                                      memif_get_external_region_addr_t * gr,
 233                                      memif_del_external_region_t * dr,
 234                                      memif_get_external_buffer_offset_t * go);
 235
 236 /** \brief Register external region
 237     @param pt_main - per thread main handle
 238     @param ar - add external region callback
 239     @param gr - get external region addr callback
 240     @param dr - delete external region callback
 241     @param go - get external buffer offset callback (optional)
 242 */
 243 void memif_per_thread_register_external_region (memif_per_thread_main_handle_t
 244                                                 pt_main,
 245                                                 memif_add_external_region_t *
 246                                                 ar,
 247                                                 memif_get_external_region_addr_t
 248                                                 * gr,
 249                                                 memif_del_external_region_t *
 250                                                 dr,
 251                                                 memif_get_external_buffer_offset_t
 252                                                 * go);
 253
 254 /** @} */
 255
 256 /**
 257  * @defgroup ARGS_N_BUFS Connection arguments and buffers
 258  * @ingroup libmemif
 259  *
 260  * @{
 261  */
 262
 263 #ifndef _MEMIF_H_
 264 typedef enum
 265 {
 266   MEMIF_INTERFACE_MODE_ETHERNET = 0,
 267   MEMIF_INTERFACE_MODE_IP = 1,
 268   MEMIF_INTERFACE_MODE_PUNT_INJECT = 2,
 269 } memif_interface_mode_t;
 270 #endif /* _MEMIF_H_ */
 271
 272 /** \brief Memif connection arguments
 273     @param socket - Memif socket handle, if NULL default socket will be used.
 274                     Default socket is only supported in global database (see memif_init).
 275                     Custom database does not create a default socket
 276                     (see memif_per_thread_init).
 277                     Memif connection is stored in the same database as the socket.
 278     @param secret - otional parameter used as interface autenthication
 279     @param num_s2m_rings - number of slave to master rings
 280     @param num_m2s_rings - number of master to slave rings
 281     @param buffer_size - size of buffer in shared memory
 282     @param log2_ring_size - logarithm base 2 of ring size
 283     @param is_master - 0 == master, 1 == slave
 284     @param interface_id - id used to identify peer connection
 285     @param interface_name - interface name
 286     @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
 287 */
 288 typedef struct
 289 {
 290   memif_socket_handle_t socket; /*!< default = /run/vpp/memif.sock */
 291   uint8_t secret[24];           /*!< optional (interface authentication) */
 292
 293   uint8_t num_s2m_rings;        /*!< default = 1 */
 294   uint8_t num_m2s_rings;        /*!< default = 1 */
 295   uint16_t buffer_size;         /*!< default = 2048 */
 296   uint8_t log2_ring_size;       /*!< default = 10 (1024) */
 297   uint8_t is_master;
 298
 299   uint32_t interface_id;
 300   uint8_t interface_name[32];
 301   memif_interface_mode_t mode:8;
 302 } memif_conn_args_t;
 303
 304 /*! memif receive mode */
 305 typedef enum
 306 {
 307   MEMIF_RX_MODE_INTERRUPT = 0,  /*!< interrupt mode */
 308   MEMIF_RX_MODE_POLLING         /*!< polling mode */
 309 } memif_rx_mode_t;
 310
 311 /** \brief Memif buffer
 312     @param desc_index - ring descriptor index
 313     @param ring - pointer to ring containing descriptor for this buffer
 314     @param len - available length
 315     @param flags - memif buffer flags
 316     @param data - pointer to shared memory data
 317 */
 318 typedef struct
 319 {
 320   uint16_t desc_index;
 321   void *ring;
 322   uint32_t len;
 323 /** next buffer present (chained buffers) */
 324 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
 325 /** states that buffer is from rx ring */
 326 #define MEMIF_BUFFER_FLAG_RX (1 << 1)
 327   uint8_t flags;
 328   void *data;
 329 } memif_buffer_t;
 330 /** @} */
 331
 332 /**
 333  * @defgroup MEMIF_DETAILS Memif details structs
 334  * @ingroup libmemif
 335  *
 336  * @{
 337  */
 338
 339 /** \brief Memif queue details
 340     @param region - region index
 341     @param qid - queue id
 342     @param ring_size - size of ring buffer in sharem memory
 343     @param flags - ring flags
 344     @param head - ring head pointer
 345     @param tail - ring tail pointer
 346     @param buffer_size - buffer size on sharem memory
 347 */
 348 typedef struct
 349 {
 350   uint8_t region;
 351   uint8_t qid;
 352   uint32_t ring_size;
 353 /** if set queue is in polling mode, else in interrupt mode */
 354 #define MEMIF_QUEUE_FLAG_POLLING 1
 355   uint16_t flags;
 356   uint16_t head;
 357   uint16_t tail;
 358   uint16_t buffer_size;
 359 } memif_queue_details_t;
 360
 361 /** \brief Memif region details
 362     @param index - region index
 363     @param addr - region address
 364     @param size - region size
 365     @param fd - file descriptor
 366     @param is_external - if not zero then region is defined by client
 367 */
 368 typedef struct
 369 {
 370   uint8_t index;
 371   void *addr;
 372   uint32_t size;
 373   int fd;
 374   uint8_t is_external;
 375 } memif_region_details_t;
 376
 377 /** \brief Memif details
 378     @param if_name - interface name
 379     @param inst_name - application name
 380     @param remote_if_name - peer interface name
 381     @param remote_inst_name - peer application name
 382     @param id - connection id
 383     @param secret - secret
 384     @param role - 0 = master, 1 = slave
 385     @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
 386     @param socket_filename - socket filename
 387     @param regions_num - number of regions
 388     @param regions - struct containing region details
 389     @param rx_queues_num - number of receive queues
 390     @param tx_queues_num - number of transmit queues
 391     @param rx_queues - struct containing receive queue details
 392     @param tx_queues - struct containing transmit queue details
 393     @param error - error string
 394     @param link_up_down - 1 = up (connected), 2 = down (disconnected)
 395 */
 396 typedef struct
 397 {
 398   uint8_t *if_name;
 399   uint8_t *inst_name;
 400   uint8_t *remote_if_name;
 401   uint8_t *remote_inst_name;
 402
 403   uint32_t id;
 404   uint8_t *secret;              /* optional */
 405   uint8_t role;                 /* 0 = master, 1 = slave */
 406   uint8_t mode;                 /* 0 = ethernet, 1 = ip, 2 = punt/inject */
 407   uint8_t *socket_filename;
 408   uint8_t regions_num;
 409   memif_region_details_t *regions;
 410   uint8_t rx_queues_num;
 411   uint8_t tx_queues_num;
 412   memif_queue_details_t *rx_queues;
 413   memif_queue_details_t *tx_queues;
 414
 415   uint8_t *error;
 416   uint8_t link_up_down;         /* 1 = up, 0 = down */
 417 } memif_details_t;
 418 /** @} */
 419
 420 /**
 421  * @defgroup API_CALLS Api calls
 422  * @ingroup libmemif
 423  *
 424  * @{
 425  */
 426
 427 /** \brief Memif get version
 428
 429     \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR)
 430 */
 431 uint16_t memif_get_version ();
 432
 433 /** \biref Memif get queue event file descriptor
 434     @param conn - memif connection handle
 435     @param qid - queue id
 436     @param[out] fd - returns event file descriptor
 437
 438     \return memif_err_t
 439 */
 440
 441 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
 442
 443 /** \brief Memif set rx mode
 444     @param conn - memif connection handle
 445     @param rx_mode - receive mode
 446     @param qid - queue id
 447
 448     \return memif_err_t
 449 */
 450 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
 451                        uint16_t qid);
 452
 453 /** \brief Memif strerror
 454     @param err_code - error code
 455
 456     Converts error code to error message.
 457
 458     \return Error string
 459 */
 460 char *memif_strerror (int err_code);
 461
 462 /** \brief Memif get details
 463     @param conn - memif conenction handle
 464     @param md - pointer to memif details struct
 465     @param buf - buffer containing details strings
 466     @param buflen - length of buffer
 467
 468     \return memif_err_t
 469 */
 470 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
 471                        char *buf, ssize_t buflen);
 472
 473 /** \brief Memif initialization
 474     @param on_control_fd_update - if control fd updates inform user to watch new fd
 475     @param app_name - application name (will be truncated to 32 chars)
 476     @param memif_alloc - cutom memory allocator, NULL = default
 477     @param memif_realloc - custom memory reallocation, NULL = default
 478     @param memif_free - custom memory free, NULL = default
 479
 480     if param on_control_fd_update is set to NULL,
 481     libmemif will handle file descriptor event polling
 482     if a valid callback is set, file descriptor event polling needs to be done by
 483     user application, all file descriptors and event types will be passed in
 484     this callback to user application
 485
 486     Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
 487     disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
 488     timer is inactive at this state. It activates with if there is at least one memif in slave mode.
 489
 490     \return memif_err_t
 491 */
 492 int memif_init (memif_control_fd_update_t * on_control_fd_update,
 493                 char *app_name, memif_alloc_t * memif_alloc,
 494                 memif_realloc_t * memif_realloc, memif_free_t * memif_free);
 495
 496 /** \brief Memif per thread initialization
 497     @param pt_main - per thread main handle
 498     @param private_ctx - private context
 499     @param on_control_fd_update - if control fd updates inform user to watch new fd
 500     @param app_name - application name (will be truncated to 32 chars)
 501     @param memif_alloc - cutom memory allocator, NULL = default
 502     @param memif_realloc - custom memory reallocation, NULL = default
 503     @param memif_free - custom memory free, NULL = default
 504
 505     Per thread version of memif_init ().
 506     Instead of using global database, creates and initializes unique database,
 507     identified by 'memif_per_thread_main_handle_t'.
 508
 509     \return memif_err_t
 510 */
 511 int memif_per_thread_init (memif_per_thread_main_handle_t * pt_main,
 512                            void *private_ctx,
 513                            memif_control_fd_update_t * on_control_fd_update,
 514                            char *app_name, memif_alloc_t * memif_alloc,
 515                            memif_realloc_t * memif_realloc,
 516                            memif_free_t * memif_free);
 517
 518 /** \brief Memif cleanup
 519
 520     Free libmemif internal allocations.
 521
 522     \return 0
 523 */
 524 int memif_cleanup ();
 525
 526 /** \brief Memif per thread cleanup
 527     @param pt_main - per thread main handle
 528
 529     Free libmemif internal allocations and sets the handle to NULL.
 530
 531     \return memif_err_t
 532 */
 533 int memif_per_thread_cleanup (memif_per_thread_main_handle_t * pt_main);
 534
 535 /** \brief Memory interface create function
 536     @param conn - connection handle for client app
 537     @param args - memory interface connection arguments
 538     @param on_connect - inform user about connected status
 539     @param on_disconnect - inform user about disconnected status
 540     @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
 541     @param private_ctx - private contex passed back to user with callback
 542
 543     Creates memory interface.
 544
 545     SLAVE-MODE -
 546         Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
 547         every disconnected memif in slave mode will send connection request.
 548         On success new fd is passed to user with memif_control_fd_update_t.
 549
 550     MASTER-MODE -
 551         Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
 552         If this fd is passed to memif_control_fd_handler accept will be called and
 553         new fd will be passed to user with memif_control_fd_update_t.
 554
 555
 556     \return memif_err_t
 557 */
 558 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
 559                   memif_connection_update_t * on_connect,
 560                   memif_connection_update_t * on_disconnect,
 561                   memif_interrupt_t * on_interrupt, void *private_ctx);
 562
 563 /** \brief Memif control file descriptor handler
 564     @param fd - file descriptor on which the event occured
 565     @param events - event type(s) that occured
 566
 567     If event occures on any control fd, call memif_control_fd_handler.
 568     Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
 569
 570     FD-TYPE -
 571         TIMERFD -
 572             Every disconnected memif in slave mode will request connection.
 573         LISTENER or CONTROL -
 574             Handle socket messaging (internal connection establishment).
 575         INTERRUPT -
 576             Call on_interrupt callback (if set).
 577
 578     \return memif_err_t
 579
 580 */
 581 int memif_control_fd_handler (int fd, uint8_t events);
 582
 583 /** \brief Memif per thread control file descriptor handler
 584     @param pt_main - per thread main handle
 585     @param fd - file descriptor on which the event occured
 586     @param events - event type(s) that occured
 587
 588     Per thread version of memif_control_fd_handler.
 589
 590     \return memif_err_t
 591
 592 */
 593 int memif_per_thread_control_fd_handler (memif_per_thread_main_handle_t
 594                                          pt_main, int fd, uint8_t events);
 595
 596 /** \brief Memif delete
 597     @param conn - pointer to memif connection handle
 598
 599
 600     disconnect session (free queues and regions, close file descriptors, unmap shared memory)
 601     set connection handle to NULL, to avoid possible double free
 602
 603     \return memif_err_t
 604 */
 605 int memif_delete (memif_conn_handle_t * conn);
 606
 607 /** \brief Memif buffer enq tx
 608     @param conn - memif conenction handle
 609     @param qid - number indentifying queue
 610     @param bufs - memif buffers
 611     @param count - number of memif buffers to enque
 612     @param count_out - returns number of allocated buffers
 613
 614     Slave is producer of buffers.
 615     If connection handle points to master returns MEMIF_ERR_INVAL_ARG.
 616
 617     \return memif_err_t
 618 */
 619 int memif_buffer_enq_tx (memif_conn_handle_t conn, uint16_t qid,
 620                          memif_buffer_t * bufs, uint16_t count,
 621                          uint16_t * count_out);
 622
 623 /** \brief Memif buffer alloc
 624     @param conn - memif conenction handle
 625     @param qid - number indentifying queue
 626     @param bufs - memif buffers
 627     @param count - number of memif buffers to allocate
 628     @param count_out - returns number of allocated buffers
 629     @param size - buffer size, may return chained buffers if size > buffer_size
 630
 631     \return memif_err_t
 632 */
 633 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
 634                         memif_buffer_t * bufs, uint16_t count,
 635                         uint16_t * count_out, uint16_t size);
 636
 637 /** \brief Memif refill ring
 638     @param conn - memif conenction handle
 639     @param qid - number indentifying queue
 640     @param count - number of buffers to be placed on ring
 641     @param headroom - offset the buffer by headroom
 642
 643     \return memif_err_t
 644 */
 645 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
 646                         uint16_t count, uint16_t headroom);
 647
 648 /** \brief Memif transmit buffer burst
 649     @param conn - memif conenction handle
 650     @param qid - number indentifying queue
 651     @param bufs - memif buffers
 652     @param count - number of memif buffers to transmit
 653     @param tx - returns number of transmitted buffers
 654
 655     \return memif_err_t
 656 */
 657 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
 658                     memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
 659
 660 /** \brief Memif receive buffer burst
 661     @param conn - memif conenction handle
 662     @param qid - number indentifying queue
 663     @param bufs - memif buffers
 664     @param count - number of memif buffers to receive
 665     @param rx - returns number of received buffers
 666
 667     \return memif_err_t
 668 */
 669 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
 670                     memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
 671
 672 /** \brief Memif poll event
 673     @param timeout - timeout in seconds
 674
 675     Passive event polling -
 676     timeout = 0 - dont wait for event, check event queue if there is an event and return.
 677     timeout = -1 - wait until event
 678
 679     \return memif_err_t
 680 */
 681 int memif_poll_event (int timeout);
 682
 683 /** \brief Memif poll event
 684     @param pt_main - per thread main handle
 685     @param timeout - timeout in seconds
 686
 687     Per thread version of memif_poll_event.
 688
 689     \return memif_err_t
 690 */
 691 int memif_per_thread_poll_event (memif_per_thread_main_handle_t pt_main,
 692                                  int timeout);
 693
 694 /** \brief Send signal to stop concurrently running memif_poll_event().
 695
 696     The function, however, does not wait for memif_poll_event() to stop.
 697     memif_poll_event() may still return simply because an event has occured
 698     or the timeout has elapsed, but if called repeatedly in an infinite loop,
 699     a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
 700     in the shortest possible time.
 701     This feature was not available in the first release.
 702     Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
 703
 704     \return memif_err_t
 705 */
 706 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
 707 int memif_cancel_poll_event ();
 708 /** \brief Send signal to stop concurrently running memif_poll_event().
 709     @param pt_main - per thread main handle
 710
 711     Per thread version of memif_cancel_poll_event.
 712
 713     \return memif_err_t
 714 */
 715 int memif_per_thread_cancel_poll_event (memif_per_thread_main_handle_t
 716                                         pt_main);
 717
 718 /** \brief Set connection request timer value
 719     @param timer - new timer value
 720
 721     Timer on which all disconnected slaves request connection.
 722     See system call 'timer_settime' man-page.
 723
 724     \return memif_err_t
 725 */
 726 int memif_set_connection_request_timer (struct itimerspec timer);
 727
 728 /** \brief Set connection request timer value
 729     @param pt_main - per thread main handle
 730     @param timer - new timer value
 731
 732     Per thread version of memif_set_connection_request_timer
 733
 734     \return memif_err_t
 735 */
 736 int
 737 memif_per_thread_set_connection_request_timer (memif_per_thread_main_handle_t
 738                                                pt_main,
 739                                                struct itimerspec timer);
 740
 741 /** \brief Send connection request
 742     @param conn - memif connection handle
 743
 744     Only slave interface can request connection.
 745
 746     \return memif_err_t
 747 */
 748 int memif_request_connection (memif_conn_handle_t conn);
 749
 750 /** \brief Create memif socket
 751     @param sock - socket handle for client app
 752     @param filename - path to socket file
 753     @param private_ctx - private context
 754
 755     The first time an interface is assigned a socket, its type is determined.
 756     For master role it's 'listener', for slave role it's 'client'. Each interface
 757     requires socket of its respective type. Default socket is creted if no
 758     socket handle is passed to memif_create(). It's private context is NULL.
 759     If all interfaces using this socket are deleted, the socket returns
 760     to its default state.
 761
 762     \return memif_err_t
 763 */
 764 int memif_create_socket (memif_socket_handle_t * sock, const char *filename,
 765                          void *private_ctx);
 766
 767 /** \brief Create memif socket
 768     @param pt_main - per thread main handle
 769     @param sock - socket handle for client app
 770     @param filename - path to socket file
 771     @param private_ctx - private context
 772
 773     Per thread version of memif_create_sopcket.
 774
 775     \return memif_err_t
 776 */
 777 int memif_per_thread_create_socket (memif_per_thread_main_handle_t pt_main,
 778                                     memif_socket_handle_t * sock,
 779                                     const char *filename, void *private_ctx);
 780
 781 /** \brief Delete memif socket
 782     @param sock - socket handle for client app
 783
 784     When trying to free socket in use, socket will not be freed and
 785     MEMIF_ERR_INVAL_ARG is returned.
 786
 787     \return memif_err_t
 788 */
 789 int memif_delete_socket (memif_socket_handle_t * sock);
 790
 791 /** \brief Get socket filename
 792     @param sock - socket handle for client app
 793
 794     Return constant pointer to socket filename.
 795
 796     \return cosnt char *
 797 */
 798 const char *memif_get_socket_filename (memif_socket_handle_t sock);
 799
 800 /** @} */
 801
 802 #endif /* _LIBMEMIF_H_ */