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 #include <sys/types.h>
  34
  35 /*! Error codes */
  36 typedef enum
  37 {
  38   MEMIF_ERR_SUCCESS = 0,        /*!< success */
  39 /* SYSCALL ERRORS */
  40   MEMIF_ERR_SYSCALL,            /*!< other syscall error */
  41   MEMIF_ERR_CONNREFUSED,        /*!< connection refused */
  42   MEMIF_ERR_ACCES,              /*!< permission denied */
  43   MEMIF_ERR_NO_FILE,            /*!< file does not exist */
  44   MEMIF_ERR_FILE_LIMIT,         /*!< system open file limit */
  45   MEMIF_ERR_PROC_FILE_LIMIT,    /*!< process open file limit */
  46   MEMIF_ERR_ALREADY,            /*!< connection already requested */
  47   MEMIF_ERR_AGAIN,              /*!< fd is not socket, or operation would block */
  48   MEMIF_ERR_BAD_FD,             /*!< invalid fd */
  49   MEMIF_ERR_NOMEM,              /*!< out of memory */
  50 /* LIBMEMIF ERRORS */
  51   MEMIF_ERR_INVAL_ARG,          /*!< invalid argument */
  52   MEMIF_ERR_NOCONN,             /*!< handle points to no connection */
  53   MEMIF_ERR_CONN,               /*!< handle points to existing connection */
  54   MEMIF_ERR_CB_FDUPDATE,        /*!< user defined callback memif_control_fd_update_t error */
  55   MEMIF_ERR_FILE_NOT_SOCK,      /*!< file specified by socket filename
  56                                    exists, but it's not socket */
  57   MEMIF_ERR_NO_SHMFD,           /*!< missing shm fd */
  58   MEMIF_ERR_COOKIE,             /*!< wrong cookie on ring */
  59   MEMIF_ERR_NOBUF_RING,         /*!< ring buffer full */
  60   MEMIF_ERR_NOBUF,              /*!< not enough memif buffers */
  61   MEMIF_ERR_NOBUF_DET,          /*!< memif details needs larger buffer */
  62   MEMIF_ERR_INT_WRITE,          /*!< send interrupt error */
  63   MEMIF_ERR_MFMSG,              /*!< malformed msg received */
  64   MEMIF_ERR_QID,                /*!< invalid queue id */
  65 /* MEMIF PROTO ERRORS */
  66   MEMIF_ERR_PROTO,              /*!< incompatible protocol version */
  67   MEMIF_ERR_ID,                 /*!< unmatched interface id */
  68   MEMIF_ERR_ACCSLAVE,           /*!< slave cannot accept connection requests */
  69   MEMIF_ERR_ALRCONN,            /*!< memif is already connected */
  70   MEMIF_ERR_MODE,               /*!< mode mismatch */
  71   MEMIF_ERR_SECRET,             /*!< secret mismatch */
  72   MEMIF_ERR_NOSECRET,           /*!< secret required */
  73   MEMIF_ERR_MAXREG,             /*!< max region limit reached */
  74   MEMIF_ERR_MAXRING,            /*!< max ring limit reached */
  75   MEMIF_ERR_NO_INTFD,           /*!< missing interrupt fd */
  76   MEMIF_ERR_DISCONNECT,         /*!< disconnect received */
  77   MEMIF_ERR_DISCONNECTED,       /*!< peer interface disconnected */
  78   MEMIF_ERR_UNKNOWN_MSG,        /*!< unknown message type */
  79   MEMIF_ERR_POLL_CANCEL,        /*!< memif_poll_event() was cancelled */
  80   MEMIF_ERR_MAX_RING,           /*!< too large ring size */
  81   MEMIF_ERR_PRIVHDR,            /*!< private hdrs not supported */
  82 } memif_err_t;
  83
  84 /**
  85  * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
  86  * @ingroup libmemif
  87  * @{
  88  */
  89
  90 /** user needs to set events that occurred on fd and pass them to memif_control_fd_handler */
  91 #define MEMIF_FD_EVENT_READ  (1 << 0)
  92 #define MEMIF_FD_EVENT_WRITE (1 << 1)
  93 /** inform libmemif that error occurred on fd */
  94 #define MEMIF_FD_EVENT_ERROR (1 << 2)
  95 /** if set, informs that fd is going to be closed (user may want to stop watching for events on this fd) */
  96 #define MEMIF_FD_EVENT_DEL   (1 << 3)
  97 /** update events */
  98 #define MEMIF_FD_EVENT_MOD   (1 << 4)
  99 /** @} */
 100
 101 /** \brief Memif per thread main handle
 102     Pointer of type void, pointing to internal structure.
 103     Used to identify internal per thread database.
 104 */
 105 typedef void *memif_per_thread_main_handle_t;
 106
 107 /** \brief Memif connection handle
 108     pointer of type void, pointing to internal structure
 109 */
 110 typedef void *memif_conn_handle_t;
 111
 112 /** \brief Memif socket handle
 113     pointer of type void, pointing to internal structure
 114 */
 115 typedef void *memif_socket_handle_t;
 116
 117 /** \brief Memif allocator alloc
 118     @param size - requested allocation size
 119
 120     custom memory allocator: alloc function template
 121 */
 122 typedef void *(memif_alloc_t) (size_t size);
 123
 124
 125 /** \brief Memif realloc
 126     @param ptr - pointer to memory block
 127     @param size - requested allocation size
 128
 129     custom memory reallocation
 130 */
 131 typedef void *(memif_realloc_t) (void *ptr, size_t size);
 132
 133 /** \brief Memif allocator free
 134     @param size - requested allocation size
 135
 136     custom memory allocator: free function template
 137 */
 138 typedef void (memif_free_t) (void *ptr);
 139
 140 /**
 141  * @defgroup CALLBACKS Callback functions definitions
 142  * @ingroup libmemif
 143  *
 144  * @{
 145  */
 146
 147 /** \brief Memif control file descriptor update (callback function)
 148     @param fd - new file descriptor to watch
 149     @param events - event type(s) to watch for
 150     @param private_ctx - libmemif main private context. Is NULL for
 151                          libmemif main created by memif_init()
 152
 153
 154     This callback is called when there is new fd to watch for events on
 155     or if fd is about to be closed (user mey want to stop watching for events on this fd).
 156     Private context is taken from libmemif_main, 'private_ctx' passed to memif_per_thread_init()
 157     or NULL in case of memif_init()
 158 */
 159 typedef int (memif_control_fd_update_t) (int fd, uint8_t events,
 160                                          void *private_ctx);
 161
 162 /** \brief Memif connection status update (callback function)
 163     @param conn - memif connection handle
 164     @param private_ctx - private context
 165
 166     Informs user about connection status connected/disconnected.
 167     On connected -> start watching for events on interrupt fd (optional).
 168 */
 169 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
 170                                          void *private_ctx);
 171
 172 /** \brief Memif interrupt occurred (callback function)
 173     @param conn - memif connection handle
 174     @param private_ctx - private context
 175     @param qid - queue id on which interrupt occurred
 176
 177     Called when event is received on interrupt fd.
 178 */
 179 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
 180                                  uint16_t qid);
 181
 182 /** @} */
 183
 184 /**
 185  * @defgroup EXTERNAL_REGION External region APIs
 186  * @ingroup libmemif
 187  *
 188  * @{
 189  */
 190
 191 /** \brief Get external buffer offset (optional)
 192     @param private_ctx - private context
 193
 194     Find unallocated external buffer and return its offset.
 195 */
 196 typedef uint32_t (memif_get_external_buffer_offset_t) (void *private_ctx);
 197
 198 /** \brief Add external region
 199     @param[out] addr - region address
 200     @param size - requested region size
 201     @param fd[out] - file descriptor
 202     @param private_ctx - private context
 203
 204     Called by slave. Add external region created by client.
 205 */
 206 typedef int (memif_add_external_region_t) (void * *addr, uint32_t size,
 207                                            int *fd, void *private_ctx);
 208
 209 /** \brief Get external region address
 210     @param size - requested region size
 211     @param fd - file descriptor
 212     @param private_ctx - private context
 213
 214     Called by master. Get region address from client.
 215
 216    \return region address
 217 */
 218 typedef void *(memif_get_external_region_addr_t) (uint32_t size, int fd,
 219                                                   void *private_ctx);
 220
 221 /** \brief Delete external region
 222     @param addr - region address
 223     @param size - region size
 224     @param fd - file descriptor
 225     @param private_ctx - private context
 226
 227     Delete external region.
 228 */
 229 typedef int (memif_del_external_region_t) (void *addr, uint32_t size, int fd,
 230                                            void *private_ctx);
 231
 232 /** \brief Register external region
 233     @param ar - add external region callback
 234     @param gr - get external region addr callback
 235     @param dr - delete external region callback
 236     @param go - get external buffer offset callback (optional)
 237 */
 238 void memif_register_external_region (memif_add_external_region_t * ar,
 239                                      memif_get_external_region_addr_t * gr,
 240                                      memif_del_external_region_t * dr,
 241                                      memif_get_external_buffer_offset_t * go);
 242
 243 /** \brief Register external region
 244     @param pt_main - per thread main handle
 245     @param ar - add external region callback
 246     @param gr - get external region addr callback
 247     @param dr - delete external region callback
 248     @param go - get external buffer offset callback (optional)
 249
 250 void memif_per_thread_register_external_region (memif_per_thread_main_handle_t
 251                                                 pt_main,
 252                                                 memif_add_external_region_t *
 253                                                 ar,
 254                                                 memif_get_external_region_addr_t
 255                                                 * gr,
 256                                                 memif_del_external_region_t *
 257                                                 dr,
 258                                                 memif_get_external_buffer_offset_t
 259                                                 * go);
 260
 261  @} */
 262
 263 /**
 264  * @defgroup ARGS_N_BUFS Connection arguments and buffers
 265  * @ingroup libmemif
 266  *
 267  * @{
 268  */
 269
 270 #ifndef _MEMIF_H_
 271 typedef enum
 272 {
 273   MEMIF_INTERFACE_MODE_ETHERNET = 0,
 274   MEMIF_INTERFACE_MODE_IP = 1,
 275   MEMIF_INTERFACE_MODE_PUNT_INJECT = 2,
 276 } memif_interface_mode_t;
 277 #endif /* _MEMIF_H_ */
 278
 279 /** \brief Memif connection arguments
 280     @param socket - Memif socket handle, if NULL default socket will be used.
 281                     Default socket is only supported in global database (see memif_init).
 282                     Custom database does not create a default socket
 283                     (see memif_per_thread_init).
 284                     Memif connection is stored in the same database as the socket.
 285     @param secret - optional parameter used as interface authentication
 286     @param num_s2m_rings - number of slave to master rings
 287     @param num_m2s_rings - number of master to slave rings
 288     @param buffer_size - size of buffer in shared memory
 289     @param log2_ring_size - logarithm base 2 of ring size
 290     @param is_master - 0 == master, 1 == slave
 291     @param interface_id - id used to identify peer connection
 292     @param interface_name - interface name
 293     @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
 294 */
 295 typedef struct
 296 {
 297   memif_socket_handle_t socket; /*!< default = /run/vpp/memif.sock */
 298   uint8_t secret[24];           /*!< optional (interface authentication) */
 299
 300   uint8_t num_s2m_rings;        /*!< default = 1 */
 301   uint8_t num_m2s_rings;        /*!< default = 1 */
 302   uint16_t buffer_size;         /*!< default = 2048 */
 303   uint8_t log2_ring_size;       /*!< default = 10 (1024) */
 304   uint8_t is_master;
 305
 306   uint32_t interface_id;
 307   uint8_t interface_name[32];
 308   memif_interface_mode_t mode:8;
 309 } memif_conn_args_t;
 310
 311 /*! memif receive mode */
 312 typedef enum
 313 {
 314   MEMIF_RX_MODE_INTERRUPT = 0,  /*!< interrupt mode */
 315   MEMIF_RX_MODE_POLLING         /*!< polling mode */
 316 } memif_rx_mode_t;
 317
 318 /** \brief Memif buffer
 319     @param desc_index - ring descriptor index
 320     @param ring - pointer to ring containing descriptor for this buffer
 321     @param len - available length
 322     @param flags - memif buffer flags
 323     @param data - pointer to shared memory data
 324 */
 325 typedef struct
 326 {
 327   uint16_t desc_index;
 328   void *queue;
 329   uint32_t len;
 330 /** next buffer present (chained buffers) */
 331 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
 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 shared 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 shared 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 /** \brief 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 connection 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 - custom 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 - custom 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 context 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_control_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 occurred
 570     @param events - event type(s) that occurred
 571
 572     If event occurs on any control fd, call memif_control_fd_handler.
 573     Internal - lib will "identify" fd (timerfd, listener, 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 occurred
 591     @param events - event type(s) that occurred
 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 connection handle
 614     @param qid - number identifying queue
 615     @param bufs - memif buffers
 616     @param count - number of memif buffers to enqueue
 617     @param count_out - returns number of allocated buffers
 618
 619     Enqueue buffers to specified tx queue. Can only be used by slave.
 620     Updates desc_index field for each memif buffer.
 621     If connection handle points to master returns MEMIF_ERR_INVAL_ARG.
 622
 623     \return memif_err_t
 624 */
 625 int memif_buffer_enq_tx (memif_conn_handle_t conn, uint16_t qid,
 626                          memif_buffer_t * bufs, uint16_t count,
 627                          uint16_t * count_out);
 628
 629 /** \brief Memif buffer enq tx at idx
 630     @param conn - memif connection handle
 631     @param buf_a - memif buffer
 632     @param buf_b - memif buffer
 633
 634     Swap descriptors for provided buffers and update the buffers
 635 */
 636 int memif_buffer_requeue (memif_conn_handle_t conn, memif_buffer_t *buf_a,
 637                           memif_buffer_t *buf_b);
 638
 639 /** \brief Memif buffer alloc
 640     @param conn - memif connection handle
 641     @param qid - number identifying queue
 642     @param bufs - memif buffers
 643     @param count - number of memif buffers to allocate
 644     @param count_out - returns number of allocated buffers
 645     @param size - buffer size, may return chained buffers if size > buffer_size
 646
 647     \return memif_err_t
 648 */
 649 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
 650                         memif_buffer_t * bufs, uint16_t count,
 651                         uint16_t * count_out, uint16_t size);
 652
 653 /** \brief Memif set next free buffer
 654     @param conn - memif connection handle
 655     @param qid - number identifying queue
 656     @param buf - next free buffer
 657
 658     Sets next free descriptor pointer for specified tx queue.
 659     The next allocation will happen at this buffer.
 660 */
 661 int memif_set_next_free_buffer (memif_conn_handle_t conn, uint16_t qid,
 662                                 memif_buffer_t *buf);
 663
 664 /** \brief Memif refill queue
 665     @param conn - memif connection handle
 666     @param qid - number identifying queue
 667     @param count - number of buffers to be placed on ring
 668     @param headroom - offset the buffer by headroom
 669
 670     \return memif_err_t
 671 */
 672 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
 673                         uint16_t count, uint16_t headroom);
 674
 675 /** \brief Memif transmit buffer burst
 676     @param conn - memif connection handle
 677     @param qid - number identifying queue
 678     @param bufs - memif buffers
 679     @param count - number of memif buffers to transmit
 680     @param tx - returns number of transmitted buffers
 681
 682     \return memif_err_t
 683 */
 684 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
 685                     memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
 686
 687 /** \brief Memif receive buffer burst
 688     @param conn - memif connection handle
 689     @param qid - number identifying queue
 690     @param bufs - memif buffers
 691     @param count - number of memif buffers to receive
 692     @param rx - returns number of received buffers
 693
 694     Consume interrupt event for receive queue.
 695     The event is not consumed, if memif_rx_burst fails.
 696
 697     \return memif_err_t
 698 */
 699 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
 700                     memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
 701
 702 /** \brief Memif poll event
 703     @param timeout - timeout in seconds
 704
 705     Passive event polling -
 706     timeout = 0 - dont wait for event, check event queue if there is an event and return.
 707     timeout = -1 - wait until event
 708
 709     \return memif_err_t
 710 */
 711 int memif_poll_event (int timeout);
 712
 713 /** \brief Memif per thread poll event
 714     @param pt_main - per thread main handle
 715     @param timeout - timeout in seconds
 716
 717     Per thread version of memif_poll_event.
 718
 719     \return memif_err_t
 720 */
 721 int memif_per_thread_poll_event (memif_per_thread_main_handle_t pt_main,
 722                                  int timeout);
 723
 724 /** \brief Send signal to stop concurrently running memif_poll_event().
 725
 726     The function, however, does not wait for memif_poll_event() to stop.
 727     memif_poll_event() may still return simply because an event has occurred
 728     or the timeout has elapsed, but if called repeatedly in an infinite loop,
 729     a canceled memif_poll_event() is guaranteed to return MEMIF_ERR_POLL_CANCEL
 730     in the shortest possible time.
 731     This feature was not available in the first release.
 732     Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
 733
 734     \return memif_err_t
 735 */
 736 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
 737 int memif_cancel_poll_event ();
 738 /** \brief Send signal to stop concurrently running memif_poll_event().
 739     @param pt_main - per thread main handle
 740
 741     Per thread version of memif_cancel_poll_event.
 742
 743     \return memif_err_t
 744 */
 745 int memif_per_thread_cancel_poll_event (memif_per_thread_main_handle_t
 746                                         pt_main);
 747
 748 /** \brief Set connection request timer value
 749     @param timer - new timer value
 750
 751     Timer on which all disconnected slaves request connection.
 752     See system call 'timer_settime' man-page.
 753
 754     \return memif_err_t
 755 */
 756 int memif_set_connection_request_timer (struct itimerspec timer);
 757
 758 /** \brief Set connection request timer value
 759     @param pt_main - per thread main handle
 760     @param timer - new timer value
 761
 762     Per thread version of memif_set_connection_request_timer
 763
 764     \return memif_err_t
 765 */
 766 int
 767 memif_per_thread_set_connection_request_timer (memif_per_thread_main_handle_t
 768                                                pt_main,
 769                                                struct itimerspec timer);
 770
 771 /** \brief Send connection request
 772     @param conn - memif connection handle
 773
 774     Only slave interface can request connection.
 775
 776     \return memif_err_t
 777 */
 778 int memif_request_connection (memif_conn_handle_t conn);
 779
 780 /** \brief Create memif socket
 781     @param sock - socket handle for client app
 782     @param filename - path to socket file
 783     @param private_ctx - private context
 784
 785     The first time an interface is assigned a socket, its type is determined.
 786     For master role it's 'listener', for slave role it's 'client'. Each interface
 787     requires socket of its respective type. Default socket is created if no
 788     socket handle is passed to memif_create(). It's private context is NULL.
 789     If all interfaces using this socket are deleted, the socket returns
 790     to its default state.
 791
 792     \return memif_err_t
 793 */
 794 int memif_create_socket (memif_socket_handle_t * sock, const char *filename,
 795                          void *private_ctx);
 796
 797 /** \brief Create memif socket
 798     @param pt_main - per thread main handle
 799     @param sock - socket handle for client app
 800     @param filename - path to socket file
 801     @param private_ctx - private context
 802
 803     Per thread version of memif_create_socket.
 804
 805     \return memif_err_t
 806 */
 807 int memif_per_thread_create_socket (memif_per_thread_main_handle_t pt_main,
 808                                     memif_socket_handle_t * sock,
 809                                     const char *filename, void *private_ctx);
 810
 811 /** \brief Delete memif socket
 812     @param sock - socket handle for client app
 813
 814     When trying to free socket in use, socket will not be freed and
 815     MEMIF_ERR_INVAL_ARG is returned.
 816
 817     \return memif_err_t
 818 */
 819 int memif_delete_socket (memif_socket_handle_t * sock);
 820
 821 /** \brief Get socket filename
 822     @param sock - socket handle for client app
 823
 824     Return constant pointer to socket filename.
 825
 826     \return const char *
 827 */
 828 const char *memif_get_socket_filename (memif_socket_handle_t sock);
 829
 830 /** @} */
 831
 832 #endif /* _LIBMEMIF_H_ */