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