FD.io VPP  v20.01-48-g3e0dafb74
Vector Packet Processing
libmemif.h
Go to the documentation of this file.
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 */
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 */
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 */
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 */
244  pt_main,
246  ar,
248  * gr,
250  dr,
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 {
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];
303 
304 /*! memif receive mode */
305 typedef enum
306 {
307  MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */
308  MEMIF_RX_MODE_POLLING /*!< polling mode */
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;
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;
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;
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;
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;
410  uint8_t rx_queues_num;
411  uint8_t tx_queues_num;
414 
415  uint8_t *error;
416  uint8_t link_up_down; /* 1 = up, 0 = down */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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
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 */
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
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 */
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 */
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 */
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 */
799 
800 /** @} */
801 
802 #endif /* _LIBMEMIF_H_ */
u8 count
Definition: dhcp.api:208
int memif_per_thread_poll_event(memif_per_thread_main_handle_t pt_main, int timeout)
Memif poll event.
Definition: main.c:1574
uint8_t * inst_name
Definition: libmemif.h:399
uint8_t * secret
Definition: libmemif.h:404
Memif region details.
Definition: libmemif.h:368
int on_disconnect(memif_conn_handle_t conn, void *private_ctx)
Definition: main.c:186
void * ring
Definition: libmemif.h:321
uint8_t num_m2s_rings
Definition: libmemif.h:294
uint16_t buffer_size
Definition: libmemif.h:295
memif_interface_mode_t
Definition: memif.h:55
uint32_t interface_id
Definition: libmemif.h:299
memif_socket_handle_t socket
Definition: libmemif.h:290
uint16_t desc_index
Definition: libmemif.h:320
vhost_vring_addr_t addr
Definition: vhost_user.h:147
uint8_t * remote_inst_name
Definition: libmemif.h:401
int memif_refill_queue(memif_conn_handle_t conn, uint16_t qid, uint16_t count, uint16_t headroom)
Memif refill ring.
Definition: main.c:2362
int on_connect(memif_conn_handle_t conn, void *private_ctx)
Definition: main.c:177
uint8_t num_s2m_rings
Definition: libmemif.h:293
const char * memif_get_socket_filename(memif_socket_handle_t sock)
Get socket filename.
Definition: main.c:1782
uint32_t len
Definition: libmemif.h:322
int memif_get_details(memif_conn_handle_t conn, memif_details_t *md, char *buf, ssize_t buflen)
Memif get details.
Definition: main.c:2568
memif_interface_mode_t mode
Definition: libmemif.h:301
uint8_t mode
Definition: libmemif.h:406
int memif_per_thread_init(memif_per_thread_main_handle_t *pt_main, void *private_ctx, memif_control_fd_update_t *on_control_fd_update, char *app_name, memif_alloc_t *memif_alloc, memif_realloc_t *memif_realloc, memif_free_t *memif_free)
Memif per thread initialization.
Definition: main.c:658
uint8_t link_up_down
Definition: libmemif.h:416
char * memif_strerror(int err_code)
Memif strerror.
Definition: main.c:157
void memif_per_thread_register_external_region(memif_per_thread_main_handle_t pt_main, memif_add_external_region_t *ar, memif_get_external_region_addr_t *gr, memif_del_external_region_t *dr, memif_get_external_buffer_offset_t *go)
Register external region.
uint8_t * error
Definition: libmemif.h:415
void * data
Definition: libmemif.h:328
uint16_t buffer_size
Definition: libmemif.h:358
uint8_t * socket_filename
Definition: libmemif.h:407
int() memif_add_external_region_t(void **addr, uint32_t size, int *fd, void *private_ctx)
Add external region.
Definition: libmemif.h:199
int memif_set_rx_mode(memif_conn_handle_t conn, memif_rx_mode_t rx_mode, uint16_t qid)
Memif set rx mode.
Definition: main.c:839
void * memif_socket_handle_t
Memif socket handle pointer of type void, pointing to internal structure.
Definition: libmemif.h:113
int() memif_del_external_region_t(void *addr, uint32_t size, int fd, void *private_ctx)
Delete external region.
Definition: libmemif.h:222
int memif_create_socket(memif_socket_handle_t *sock, const char *filename, void *private_ctx)
Create memif socket.
Definition: main.c:930
u64 size
Definition: vhost_user.h:140
int() memif_interrupt_t(memif_conn_handle_t conn, void *private_ctx, uint16_t qid)
Memif interrupt occured (callback function)
Definition: libmemif.h:172
uint8_t is_master
Definition: libmemif.h:297
uint8_t rx_queues_num
Definition: libmemif.h:410
int memif_init(memif_control_fd_update_t *on_control_fd_update, char *app_name, memif_alloc_t *memif_alloc, memif_realloc_t *memif_realloc, memif_free_t *memif_free)
Memif initialization.
Definition: main.c:508
int() memif_connection_update_t(memif_conn_handle_t conn, void *private_ctx)
Memif connection status update (callback function)
Definition: libmemif.h:162
int memif_get_queue_efd(memif_conn_handle_t conn, uint16_t qid, int *fd)
Memif get queue event file descriptor
Definition: main.c:2729
int memif_buffer_enq_tx(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *bufs, uint16_t count, uint16_t *count_out)
Memif buffer enq tx.
Definition: main.c:2156
uint8_t flags
Definition: libmemif.h:327
int on_interrupt(memif_conn_handle_t conn, void *private_ctx, uint16_t qid)
Definition: main.c:287
uint8_t regions_num
Definition: libmemif.h:408
int memif_per_thread_create_socket(memif_per_thread_main_handle_t pt_main, memif_socket_handle_t *sock, const char *filename, void *private_ctx)
Create memif socket.
Definition: main.c:1009
int memif_tx_burst(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *bufs, uint16_t count, uint16_t *tx)
Memif transmit buffer burst.
Definition: main.c:2416
void() memif_free_t(void *ptr)
Memif allocator free.
Definition: libmemif.h:136
int memif_buffer_alloc(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *bufs, uint16_t count, uint16_t *count_out, uint16_t size)
Memif buffer alloc.
Definition: main.c:2236
int memif_poll_event(int timeout)
Memif poll event.
Definition: main.c:1532
memif_queue_details_t * rx_queues
Definition: libmemif.h:412
int memif_per_thread_control_fd_handler(memif_per_thread_main_handle_t pt_main, int fd, uint8_t events)
Memif per thread control file descriptor handler.
Definition: main.c:1418
uint8_t role
Definition: libmemif.h:405
void *() memif_realloc_t(void *ptr, size_t size)
Memif realloc.
Definition: libmemif.h:129
int memif_cleanup()
Memif cleanup.
Definition: main.c:2752
uint32_t() memif_get_external_buffer_offset_t(void *private_ctx)
Get external buffer offset (optional)
Definition: libmemif.h:189
int memif_create(memif_conn_handle_t *conn, memif_conn_args_t *args, memif_connection_update_t *on_connect, memif_connection_update_t *on_disconnect, memif_interrupt_t *on_interrupt, void *private_ctx)
Memory interface create function.
Definition: main.c:1093
uint8_t tx_queues_num
Definition: libmemif.h:411
void * memif_per_thread_main_handle_t
Memif per thread main handle Pointer of type void, pointing to internal structure.
Definition: libmemif.h:103
memif_err_t
Definition: libmemif.h:34
memif_interface_mode_t
Definition: libmemif.h:264
void * memif_conn_handle_t
Memif connection handle pointer of type void, pointing to internal structure.
Definition: libmemif.h:108
int memif_per_thread_set_connection_request_timer(memif_per_thread_main_handle_t pt_main, struct itimerspec timer)
Set connection request timer value.
Definition: main.c:487
int memif_set_connection_request_timer(struct itimerspec timer)
Set connection request timer value.
Definition: main.c:468
int memif_control_fd_handler(int fd, uint8_t events)
Memif control file descriptor handler.
Definition: main.c:1306
int memif_request_connection(memif_conn_handle_t conn)
Send connection request.
Definition: main.c:1231
uint8_t log2_ring_size
Definition: libmemif.h:296
uint32_t id
Definition: libmemif.h:403
int memif_rx_burst(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *bufs, uint16_t count, uint16_t *rx)
Memif receive buffer burst.
Definition: main.c:2483
memif_rx_mode_t
Definition: libmemif.h:305
void *() memif_alloc_t(size_t size)
Memif allocator alloc.
Definition: libmemif.h:120
void *() memif_get_external_region_addr_t(uint32_t size, int fd, void *private_ctx)
Get external region address.
Definition: libmemif.h:211
int memif_delete(memif_conn_handle_t *conn)
Memif delete.
Definition: main.c:1815
int memif_per_thread_cleanup(memif_per_thread_main_handle_t *pt_main)
Memif per thread cleanup.
Definition: main.c:2780
int memif_per_thread_cancel_poll_event(memif_per_thread_main_handle_t pt_main)
Send signal to stop concurrently running memif_poll_event().
Definition: main.c:1633
Memif queue details.
Definition: libmemif.h:348
memif_region_details_t * regions
Definition: libmemif.h:409
int memif_cancel_poll_event()
Definition: main.c:1617
memif_queue_details_t * tx_queues
Definition: libmemif.h:413
uint8_t * if_name
Definition: libmemif.h:398
int memif_delete_socket(memif_socket_handle_t *sock)
Delete memif socket.
Definition: main.c:1793
Memif buffer.
Definition: libmemif.h:318
uint16_t memif_get_version()
Memif get version.
Definition: main.c:174
Memif connection arguments.
Definition: libmemif.h:288
Memif details.
Definition: libmemif.h:396
void memif_register_external_region(memif_add_external_region_t *ar, memif_get_external_region_addr_t *gr, memif_del_external_region_t *dr, memif_get_external_buffer_offset_t *go)
Register external region.
Definition: main.c:437
int() memif_control_fd_update_t(int fd, uint8_t events, void *private_ctx)
Memif control file descriptor update (callback function)
Definition: libmemif.h:152
uint8_t * remote_if_name
Definition: libmemif.h:400