FD.io VPP  v21.06-3-gbb25fbf28
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 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 */
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 */
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 */
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 {
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];
310 
311 /*! memif receive mode */
312 typedef enum
313 {
314  MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */
315  MEMIF_RX_MODE_POLLING /*!< polling mode */
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;
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;
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 /** \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 */
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 */
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 */
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 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 */
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 */
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 */
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,
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 */
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
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 */
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
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 */
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 */
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 */
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 */
829 
830 /** @} */
831 
832 #endif /* _LIBMEMIF_H_ */
memif_queue_details_t::head
uint16_t head
Definition: libmemif.h:361
MEMIF_ERR_ALREADY
@ MEMIF_ERR_ALREADY
Definition: libmemif.h:46
memif_register_external_region
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:431
MEMIF_RX_MODE_INTERRUPT
@ MEMIF_RX_MODE_INTERRUPT
Definition: libmemif.h:314
memif_buffer_t::queue
void * queue
Definition: libmemif.h:328
bufs
vlib_buffer_t * bufs[VLIB_FRAME_SIZE]
Definition: nat44_ei_out2in.c:717
memif_queue_details_t::flags
uint16_t flags
Definition: libmemif.h:360
memif_per_thread_create_socket
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:992
rx_mode
rx_mode
Definition: interface_types.api:56
on_connect
int on_connect(memif_conn_handle_t conn, void *private_ctx)
Definition: main.c:177
MEMIF_ERR_NOBUF_DET
@ MEMIF_ERR_NOBUF_DET
Definition: libmemif.h:61
memif_region_details_t::addr
void * addr
Definition: libmemif.h:376
memif_conn_args_t::mode
memif_interface_mode_t mode
Definition: libmemif.h:308
memif_free_t
void() memif_free_t(void *ptr)
Memif allocator free.
Definition: libmemif.h:138
MEMIF_ERR_SUCCESS
@ MEMIF_ERR_SUCCESS
Definition: libmemif.h:38
MEMIF_ERR_CB_FDUPDATE
@ MEMIF_ERR_CB_FDUPDATE
Definition: libmemif.h:54
memif_buffer_t::len
uint32_t len
Definition: libmemif.h:329
MEMIF_ERR_CONNREFUSED
@ MEMIF_ERR_CONNREFUSED
Definition: libmemif.h:41
memif_queue_details_t
Memif queue details.
Definition: libmemif.h:353
MEMIF_ERR_POLL_CANCEL
@ MEMIF_ERR_POLL_CANCEL
Definition: libmemif.h:79
memif_details_t::remote_if_name
uint8_t * remote_if_name
Definition: libmemif.h:405
MEMIF_ERR_NOBUF_RING
@ MEMIF_ERR_NOBUF_RING
Definition: libmemif.h:59
memif_get_socket_filename
const char * memif_get_socket_filename(memif_socket_handle_t sock)
Get socket filename.
Definition: main.c:1753
memif_alloc_t
void *() memif_alloc_t(size_t size)
Memif allocator alloc.
Definition: libmemif.h:122
memif_get_external_buffer_offset_t
uint32_t() memif_get_external_buffer_offset_t(void *private_ctx)
Get external buffer offset (optional)
Definition: libmemif.h:196
memif_per_thread_cleanup
int memif_per_thread_cleanup(memif_per_thread_main_handle_t *pt_main)
Memif per thread cleanup.
Definition: main.c:2849
memif_queue_details_t::tail
uint16_t tail
Definition: libmemif.h:362
memif_per_thread_poll_event
int memif_per_thread_poll_event(memif_per_thread_main_handle_t pt_main, int timeout)
Memif per thread poll event.
Definition: main.c:1545
memif_conn_args_t::buffer_size
uint16_t buffer_size
Definition: libmemif.h:302
memif_queue_details_t::ring_size
uint32_t ring_size
Definition: libmemif.h:357
memif_create
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:1065
MEMIF_INTERFACE_MODE_IP
@ MEMIF_INTERFACE_MODE_IP
Definition: libmemif.h:274
memif_conn_args_t
Memif connection arguments.
Definition: libmemif.h:295
memif_buffer_enq_tx
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:2204
memif_region_details_t::is_external
uint8_t is_external
Definition: libmemif.h:379
memif_region_details_t::fd
int fd
Definition: libmemif.h:378
memif_per_thread_main_handle_t
void * memif_per_thread_main_handle_t
Memif per thread main handle Pointer of type void, pointing to internal structure.
Definition: libmemif.h:105
MEMIF_ERR_ACCES
@ MEMIF_ERR_ACCES
Definition: libmemif.h:42
memif_get_details
int memif_get_details(memif_conn_handle_t conn, memif_details_t *md, char *buf, ssize_t buflen)
Memif get details.
Definition: main.c:2637
MEMIF_ERR_UNKNOWN_MSG
@ MEMIF_ERR_UNKNOWN_MSG
Definition: libmemif.h:78
addr
vhost_vring_addr_t addr
Definition: vhost_user.h:130
memif_buffer_t::data
void * data
Definition: libmemif.h:333
memif_details_t::tx_queues
memif_queue_details_t * tx_queues
Definition: libmemif.h:418
MEMIF_ERR_NO_FILE
@ MEMIF_ERR_NO_FILE
Definition: libmemif.h:43
memif_details_t::rx_queues_num
uint8_t rx_queues_num
Definition: libmemif.h:415
memif_conn_args_t::interface_id
uint32_t interface_id
Definition: libmemif.h:306
memif_rx_mode_t
memif_rx_mode_t
Definition: libmemif.h:312
MEMIF_ERR_ID
@ MEMIF_ERR_ID
Definition: libmemif.h:67
on_disconnect
int on_disconnect(memif_conn_handle_t conn, void *private_ctx)
Definition: main.c:186
memif_request_connection
int memif_request_connection(memif_conn_handle_t conn)
Send connection request.
Definition: main.c:1203
MEMIF_ERR_NO_SHMFD
@ MEMIF_ERR_NO_SHMFD
Definition: libmemif.h:57
memif_details_t::inst_name
uint8_t * inst_name
Definition: libmemif.h:404
MEMIF_ERR_PROTO
@ MEMIF_ERR_PROTO
Definition: libmemif.h:66
memif_queue_details_t::buffer_size
uint16_t buffer_size
Definition: libmemif.h:363
on_interrupt
int on_interrupt(memif_conn_handle_t conn, void *private_ctx, uint16_t qid)
Definition: main.c:287
count
u8 count
Definition: dhcp.api:208
memif_init
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:502
memif_buffer_t::desc_index
uint16_t desc_index
Definition: libmemif.h:327
MEMIF_INTERFACE_MODE_PUNT_INJECT
@ MEMIF_INTERFACE_MODE_PUNT_INJECT
Definition: libmemif.h:275
memif_details_t::id
uint32_t id
Definition: libmemif.h:408
memif_cancel_poll_event
int memif_cancel_poll_event()
Definition: main.c:1588
memif_create_socket
int memif_create_socket(memif_socket_handle_t *sock, const char *filename, void *private_ctx)
Create memif socket.
Definition: main.c:924
memif_delete_socket
int memif_delete_socket(memif_socket_handle_t *sock)
Delete memif socket.
Definition: main.c:1764
memif_add_external_region_t
int() memif_add_external_region_t(void **addr, uint32_t size, int *fd, void *private_ctx)
Add external region.
Definition: libmemif.h:206
memif_details_t
Memif details.
Definition: libmemif.h:401
memif_region_details_t::index
uint8_t index
Definition: libmemif.h:375
memif_socket_handle_t
void * memif_socket_handle_t
Memif socket handle pointer of type void, pointing to internal structure.
Definition: libmemif.h:115
MEMIF_ERR_DISCONNECT
@ MEMIF_ERR_DISCONNECT
Definition: libmemif.h:76
MEMIF_ERR_MAXRING
@ MEMIF_ERR_MAXRING
Definition: libmemif.h:74
MEMIF_ERR_FILE_NOT_SOCK
@ MEMIF_ERR_FILE_NOT_SOCK
Definition: libmemif.h:55
memif_get_version
uint16_t memif_get_version()
Memif get version.
Definition: main.c:171
memif_conn_args_t::num_m2s_rings
uint8_t num_m2s_rings
Definition: libmemif.h:301
memif_per_thread_init
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:650
memif_per_thread_set_connection_request_timer
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:481
memif_queue_details_t::region
uint8_t region
Definition: libmemif.h:355
memif_details_t::remote_inst_name
uint8_t * remote_inst_name
Definition: libmemif.h:406
memif_buffer_alloc
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:2265
memif_details_t::tx_queues_num
uint8_t tx_queues_num
Definition: libmemif.h:416
memif_connection_update_t
int() memif_connection_update_t(memif_conn_handle_t conn, void *private_ctx)
Memif connection status update (callback function)
Definition: libmemif.h:169
memif_realloc_t
void *() memif_realloc_t(void *ptr, size_t size)
Memif realloc.
Definition: libmemif.h:131
MEMIF_ERR_ACCSLAVE
@ MEMIF_ERR_ACCSLAVE
Definition: libmemif.h:68
memif_details_t::secret
uint8_t * secret
Definition: libmemif.h:409
MEMIF_ERR_PRIVHDR
@ MEMIF_ERR_PRIVHDR
Definition: libmemif.h:81
events
static perfmon_event_t events[]
Definition: core.c:21
memif_set_rx_mode
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:833
MEMIF_ERR_QID
@ MEMIF_ERR_QID
Definition: libmemif.h:64
app_name
static char * app_name
Definition: vapi_cpp_test.cpp:33
memif_region_details_t
Memif region details.
Definition: libmemif.h:373
memif_cleanup
int memif_cleanup()
Memif cleanup.
Definition: main.c:2821
memif_per_thread_cancel_poll_event
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:1604
memif_details_t::if_name
uint8_t * if_name
Definition: libmemif.h:403
memif_del_external_region_t
int() memif_del_external_region_t(void *addr, uint32_t size, int fd, void *private_ctx)
Delete external region.
Definition: libmemif.h:229
MEMIF_ERR_SYSCALL
@ MEMIF_ERR_SYSCALL
Definition: libmemif.h:40
MEMIF_ERR_NOBUF
@ MEMIF_ERR_NOBUF
Definition: libmemif.h:60
MEMIF_ERR_NOSECRET
@ MEMIF_ERR_NOSECRET
Definition: libmemif.h:72
memif_conn_args_t::socket
memif_socket_handle_t socket
Definition: libmemif.h:297
memif_details_t::regions_num
uint8_t regions_num
Definition: libmemif.h:413
memif_set_next_free_buffer
int memif_set_next_free_buffer(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *buf)
Memif set next free buffer.
Definition: main.c:2123
memif_conn_handle_t
void * memif_conn_handle_t
Memif connection handle pointer of type void, pointing to internal structure.
Definition: libmemif.h:110
MEMIF_ERR_MFMSG
@ MEMIF_ERR_MFMSG
Definition: libmemif.h:63
memif_get_queue_efd
int memif_get_queue_efd(memif_conn_handle_t conn, uint16_t qid, int *fd)
Memif get queue event file descriptor.
Definition: main.c:2798
memif_control_fd_update_t
int() memif_control_fd_update_t(int fd, uint8_t events, void *private_ctx)
Memif control file descriptor update (callback function)
Definition: libmemif.h:159
memif_details_t::socket_filename
uint8_t * socket_filename
Definition: libmemif.h:412
size
u32 size
Definition: vhost_user.h:125
memif_details_t::regions
memif_region_details_t * regions
Definition: libmemif.h:414
memif_conn_args_t::num_s2m_rings
uint8_t num_s2m_rings
Definition: libmemif.h:300
memif_err_t
memif_err_t
Definition: libmemif.h:36
memif_tx_burst
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:2444
memif_buffer_t
Memif buffer.
Definition: libmemif.h:325
memif_control_fd_handler
int memif_control_fd_handler(int fd, uint8_t events)
Memif control file descriptor handler.
Definition: main.c:1277
MEMIF_ERR_FILE_LIMIT
@ MEMIF_ERR_FILE_LIMIT
Definition: libmemif.h:44
buf
u64 buf
Definition: application.c:493
memif_get_external_region_addr_t
void *() memif_get_external_region_addr_t(uint32_t size, int fd, void *private_ctx)
Get external region address.
Definition: libmemif.h:218
memif_per_thread_control_fd_handler
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:1389
MEMIF_ERR_AGAIN
@ MEMIF_ERR_AGAIN
Definition: libmemif.h:47
memif_set_connection_request_timer
int memif_set_connection_request_timer(struct itimerspec timer)
Set connection request timer value.
Definition: main.c:462
MEMIF_RX_MODE_POLLING
@ MEMIF_RX_MODE_POLLING
Definition: libmemif.h:315
memif_conn_args_t::log2_ring_size
uint8_t log2_ring_size
Definition: libmemif.h:303
memif_interface_mode_t
memif_interface_mode_t
Definition: memif.h:55
memif_details_t::mode
uint8_t mode
Definition: libmemif.h:411
memif_details_t::link_up_down
uint8_t link_up_down
Definition: libmemif.h:421
memif_conn_args_t::is_master
uint8_t is_master
Definition: libmemif.h:304
MEMIF_ERR_INT_WRITE
@ MEMIF_ERR_INT_WRITE
Definition: libmemif.h:62
memif_delete
int memif_delete(memif_conn_handle_t *conn)
Memif delete.
Definition: main.c:1784
MEMIF_ERR_DISCONNECTED
@ MEMIF_ERR_DISCONNECTED
Definition: libmemif.h:77
MEMIF_ERR_PROC_FILE_LIMIT
@ MEMIF_ERR_PROC_FILE_LIMIT
Definition: libmemif.h:45
MEMIF_ERR_MAX_RING
@ MEMIF_ERR_MAX_RING
Definition: libmemif.h:80
MEMIF_ERR_SECRET
@ MEMIF_ERR_SECRET
Definition: libmemif.h:71
MEMIF_ERR_MAXREG
@ MEMIF_ERR_MAXREG
Definition: libmemif.h:73
MEMIF_ERR_INVAL_ARG
@ MEMIF_ERR_INVAL_ARG
Definition: libmemif.h:51
memif_buffer_t::flags
uint8_t flags
Definition: libmemif.h:332
memif_details_t::role
uint8_t role
Definition: libmemif.h:410
MEMIF_INTERFACE_MODE_ETHERNET
@ MEMIF_INTERFACE_MODE_ETHERNET
Definition: libmemif.h:273
MEMIF_ERR_CONN
@ MEMIF_ERR_CONN
Definition: libmemif.h:53
memif_buffer_requeue
int memif_buffer_requeue(memif_conn_handle_t conn, memif_buffer_t *buf_a, memif_buffer_t *buf_b)
Memif buffer enq tx at idx.
Definition: main.c:2175
memif_interrupt_t
int() memif_interrupt_t(memif_conn_handle_t conn, void *private_ctx, uint16_t qid)
Memif interrupt occurred (callback function)
Definition: libmemif.h:179
memif_details_t::error
uint8_t * error
Definition: libmemif.h:420
memif_strerror
char * memif_strerror(int err_code)
Memif strerror.
Definition: main.c:157
MEMIF_ERR_BAD_FD
@ MEMIF_ERR_BAD_FD
Definition: libmemif.h:48
memif_interface_mode_t
memif_interface_mode_t
Definition: libmemif.h:271
memif_region_details_t::size
uint32_t size
Definition: libmemif.h:377
memif_details_t::rx_queues
memif_queue_details_t * rx_queues
Definition: libmemif.h:417
memif_poll_event
int memif_poll_event(int timeout)
Memif poll event.
Definition: main.c:1503
MEMIF_ERR_ALRCONN
@ MEMIF_ERR_ALRCONN
Definition: libmemif.h:69
MEMIF_ERR_NOCONN
@ MEMIF_ERR_NOCONN
Definition: libmemif.h:52
MEMIF_ERR_NOMEM
@ MEMIF_ERR_NOMEM
Definition: libmemif.h:49
MEMIF_ERR_COOKIE
@ MEMIF_ERR_COOKIE
Definition: libmemif.h:58
memif_refill_queue
int memif_refill_queue(memif_conn_handle_t conn, uint16_t qid, uint16_t count, uint16_t headroom)
Memif refill queue.
Definition: main.c:2389
MEMIF_ERR_MODE
@ MEMIF_ERR_MODE
Definition: libmemif.h:70
memif_rx_burst
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:2545
MEMIF_ERR_NO_INTFD
@ MEMIF_ERR_NO_INTFD
Definition: libmemif.h:75
memif_queue_details_t::qid
uint8_t qid
Definition: libmemif.h:356