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:
8 * http://www.apache.org/licenses/LICENSE-2.0
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 *------------------------------------------------------------------
25 /** Libmemif version. */
26 #define LIBMEMIF_VERSION "3.0"
27 /** Default name of application using libmemif. */
28 #define MEMIF_DEFAULT_APP_NAME "libmemif-app"
31 #include <sys/timerfd.h>
36 MEMIF_ERR_SUCCESS = 0, /*!< success */
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 */
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 */
83 * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
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)
96 #define MEMIF_FD_EVENT_MOD (1 << 4)
99 /** \brief Memif connection handle
100 pointer of type void, pointing to internal structure
102 typedef void *memif_conn_handle_t;
104 /** \brief Memif socket handle
105 pointer of type void, pointing to internal structure
107 typedef void *memif_socket_handle_t;
109 /** \brief Memif allocator alloc
110 @param size - requested allocation size
112 custom memory allocator: alloc function template
114 typedef void *(memif_alloc_t) (size_t size);
117 /** \brief Memif realloc
118 @param ptr - pointer to memory block
119 @param size - requested allocation size
121 custom memory reallocation
123 typedef void *(memif_realloc_t) (void *ptr, size_t size);
125 /** \brief Memif allocator free
126 @param size - requested allocation size
128 custom memory allocator: free function template
130 typedef void (memif_free_t) (void *ptr);
133 * @defgroup CALLBACKS Callback functions definitions
139 /** \brief Memif control file descriptor update (callback function)
140 @param fd - new file descriptor to watch
141 @param events - event type(s) to watch for
143 This callback is called when there is new fd to watch for events on
144 or if fd is about to be closed (user mey want to stop watching for events on this fd).
146 typedef int (memif_control_fd_update_t) (int fd, uint8_t events,
149 /** \brief Memif connection status update (callback function)
150 @param conn - memif connection handle
151 @param private_ctx - private context
153 Informs user about connection status connected/disconnected.
154 On connected -> start watching for events on interrupt fd (optional).
156 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
159 /** \brief Memif interrupt occured (callback function)
160 @param conn - memif connection handle
161 @param private_ctx - private context
162 @param qid - queue id on which interrupt occured
164 Called when event is received on interrupt fd.
166 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
172 * @defgroup EXTERNAL_REGION External region APIs
178 /** \brief Get external buffer offset (optional)
179 @param private_ctx - private context
181 Find unallocated external buffer and return its offset.
183 typedef uint32_t (memif_get_external_buffer_offset_t) (void *private_ctx);
185 /** \brief Add external region
186 @param[out] addr - region address
187 @param size - requested region size
188 @param fd[out] - file descriptor
189 @param private_ctx - private context
191 Called by slave. Add external region created by client.
193 typedef int (memif_add_external_region_t) (void * *addr, uint32_t size,
194 int *fd, void *private_ctx);
196 /** \brief Get external region address
197 @param size - requested region size
198 @param fd - file descriptor
199 @param private_ctx - private context
201 Called by master. Get region address from client.
203 \return region address
205 typedef void *(memif_get_external_region_addr_t) (uint32_t size, int fd,
208 /** \brief Delete external region
209 @param addr - region address
210 @param size - region size
211 @param fd - file descriptor
212 @param private_ctx - private context
214 Delete external region.
216 typedef int (memif_del_external_region_t) (void *addr, uint32_t size, int fd,
219 /** \brief Register external region
220 @param ar - add external region callback
221 @param gr - get external region addr callback
222 @param dr - delete external region callback
223 @param go - get external buffer offset callback (optional)
225 void memif_register_external_region (memif_add_external_region_t * ar,
226 memif_get_external_region_addr_t * gr,
227 memif_del_external_region_t * dr,
228 memif_get_external_buffer_offset_t * go);
233 * @defgroup ARGS_N_BUFS Connection arguments and buffers
242 MEMIF_INTERFACE_MODE_ETHERNET = 0,
243 MEMIF_INTERFACE_MODE_IP = 1,
244 MEMIF_INTERFACE_MODE_PUNT_INJECT = 2,
245 } memif_interface_mode_t;
246 #endif /* _MEMIF_H_ */
248 /** \brief Memif connection arguments
249 @param socket - memif socket handle, if NULL default socket will be used
250 @param secret - otional parameter used as interface autenthication
251 @param num_s2m_rings - number of slave to master rings
252 @param num_m2s_rings - number of master to slave rings
253 @param buffer_size - size of buffer in shared memory
254 @param log2_ring_size - logarithm base 2 of ring size
255 @param is_master - 0 == master, 1 == slave
256 @param interface_id - id used to identify peer connection
257 @param interface_name - interface name
258 @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
262 memif_socket_handle_t socket; /*!< default = /run/vpp/memif.sock */
263 uint8_t secret[24]; /*!< optional (interface authentication) */
265 uint8_t num_s2m_rings; /*!< default = 1 */
266 uint8_t num_m2s_rings; /*!< default = 1 */
267 uint16_t buffer_size; /*!< default = 2048 */
268 uint8_t log2_ring_size; /*!< default = 10 (1024) */
271 uint32_t interface_id;
272 uint8_t interface_name[32];
273 memif_interface_mode_t mode:8;
276 /*! memif receive mode */
279 MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */
280 MEMIF_RX_MODE_POLLING /*!< polling mode */
283 /** \brief Memif buffer
284 @param desc_index - ring descriptor index
285 @param ring - pointer to ring containing descriptor for this buffer
286 @param len - available length
287 @param flags - memif buffer flags
288 @param data - pointer to shared memory data
295 /** next buffer present (chained buffers) */
296 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
297 /** states that buffer is from rx ring */
298 #define MEMIF_BUFFER_FLAG_RX (1 << 1)
305 * @defgroup MEMIF_DETAILS Memif details structs
311 /** \brief Memif queue details
312 @param region - region index
313 @param qid - queue id
314 @param ring_size - size of ring buffer in sharem memory
315 @param flags - ring flags
316 @param head - ring head pointer
317 @param tail - ring tail pointer
318 @param buffer_size - buffer size on sharem memory
325 /** if set queue is in polling mode, else in interrupt mode */
326 #define MEMIF_QUEUE_FLAG_POLLING 1
330 uint16_t buffer_size;
331 } memif_queue_details_t;
333 /** \brief Memif region details
334 @param index - region index
335 @param addr - region address
336 @param size - region size
337 @param fd - file descriptor
338 @param is_external - if not zero then region is defined by client
347 } memif_region_details_t;
349 /** \brief Memif details
350 @param if_name - interface name
351 @param inst_name - application name
352 @param remote_if_name - peer interface name
353 @param remote_inst_name - peer application name
354 @param id - connection id
355 @param secret - secret
356 @param role - 0 = master, 1 = slave
357 @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
358 @param socket_filename - socket filename
359 @param regions_num - number of regions
360 @param regions - struct containing region details
361 @param rx_queues_num - number of receive queues
362 @param tx_queues_num - number of transmit queues
363 @param rx_queues - struct containing receive queue details
364 @param tx_queues - struct containing transmit queue details
365 @param error - error string
366 @param link_up_down - 1 = up (connected), 2 = down (disconnected)
372 uint8_t *remote_if_name;
373 uint8_t *remote_inst_name;
376 uint8_t *secret; /* optional */
377 uint8_t role; /* 0 = master, 1 = slave */
378 uint8_t mode; /* 0 = ethernet, 1 = ip, 2 = punt/inject */
379 uint8_t *socket_filename;
381 memif_region_details_t *regions;
382 uint8_t rx_queues_num;
383 uint8_t tx_queues_num;
384 memif_queue_details_t *rx_queues;
385 memif_queue_details_t *tx_queues;
388 uint8_t link_up_down; /* 1 = up, 0 = down */
393 * @defgroup API_CALLS Api calls
399 /** \brief Memif get version
401 \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR)
403 uint16_t memif_get_version ();
405 /** \biref Memif get queue event file descriptor
406 @param conn - memif connection handle
407 @param qid - queue id
408 @param[out] fd - returns event file descriptor
413 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
415 /** \brief Memif set rx mode
416 @param conn - memif connection handle
417 @param rx_mode - receive mode
418 @param qid - queue id
422 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
425 /** \brief Memif strerror
426 @param err_code - error code
428 Converts error code to error message.
432 char *memif_strerror (int err_code);
434 /** \brief Memif get details
435 @param conn - memif conenction handle
436 @param md - pointer to memif details struct
437 @param buf - buffer containing details strings
438 @param buflen - length of buffer
442 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
443 char *buf, ssize_t buflen);
445 /** \brief Memif initialization
446 @param on_control_fd_update - if control fd updates inform user to watch new fd
447 @param app_name - application name (will be truncated to 32 chars)
448 @param memif_alloc - cutom memory allocator, NULL = default
449 @param memif_realloc - custom memory reallocation, NULL = default
450 @param memif_free - custom memory free, NULL = default
452 if param on_control_fd_update is set to NULL,
453 libmemif will handle file descriptor event polling
454 if a valid callback is set, file descriptor event polling needs to be done by
455 user application, all file descriptors and event types will be passed in
456 this callback to user application
458 Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
459 disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
460 timer is inactive at this state. It activates with if there is at least one memif in slave mode.
464 int memif_init (memif_control_fd_update_t * on_control_fd_update,
465 char *app_name, memif_alloc_t * memif_alloc,
466 memif_realloc_t * memif_realloc, memif_free_t * memif_free);
468 /** \brief Memif cleanup
470 Free libmemif internal allocations.
474 int memif_cleanup ();
476 /** \brief Memory interface create function
477 @param conn - connection handle for client app
478 @param args - memory interface connection arguments
479 @param on_connect - inform user about connected status
480 @param on_disconnect - inform user about disconnected status
481 @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
482 @param private_ctx - private contex passed back to user with callback
484 Creates memory interface.
487 Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
488 every disconnected memif in slave mode will send connection request.
489 On success new fd is passed to user with memif_control_fd_update_t.
492 Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
493 If this fd is passed to memif_control_fd_handler accept will be called and
494 new fd will be passed to user with memif_control_fd_update_t.
499 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
500 memif_connection_update_t * on_connect,
501 memif_connection_update_t * on_disconnect,
502 memif_interrupt_t * on_interrupt, void *private_ctx);
504 /** \brief Memif control file descriptor handler
505 @param fd - file descriptor on which the event occured
506 @param events - event type(s) that occured
508 If event occures on any control fd, call memif_control_fd_handler.
509 Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
513 Every disconnected memif in slave mode will request connection.
514 LISTENER or CONTROL -
515 Handle socket messaging (internal connection establishment).
517 Call on_interrupt callback (if set).
522 int memif_control_fd_handler (int fd, uint8_t events);
524 /** \brief Memif delete
525 @param conn - pointer to memif connection handle
528 disconnect session (free queues and regions, close file descriptors, unmap shared memory)
529 set connection handle to NULL, to avoid possible double free
533 int memif_delete (memif_conn_handle_t * conn);
535 /** \brief Memif buffer enq tx
536 @param conn - memif conenction handle
537 @param qid - number indentifying queue
538 @param bufs - memif buffers
539 @param count - number of memif buffers to enque
540 @param count_out - returns number of allocated buffers
542 Slave is producer of buffers.
543 If connection handle points to master returns MEMIF_ERR_INVAL_ARG.
547 int memif_buffer_enq_tx (memif_conn_handle_t conn, uint16_t qid,
548 memif_buffer_t * bufs, uint16_t count,
549 uint16_t * count_out);
551 /** \brief Memif buffer alloc
552 @param conn - memif conenction handle
553 @param qid - number indentifying queue
554 @param bufs - memif buffers
555 @param count - number of memif buffers to allocate
556 @param count_out - returns number of allocated buffers
557 @param size - buffer size, may return chained buffers if size > buffer_size
561 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
562 memif_buffer_t * bufs, uint16_t count,
563 uint16_t * count_out, uint16_t size);
565 /** \brief Memif refill ring
566 @param conn - memif conenction handle
567 @param qid - number indentifying queue
568 @param count - number of buffers to be placed on ring
569 @param headroom - offset the buffer by headroom
573 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
574 uint16_t count, uint16_t headroom);
576 /** \brief Memif transmit buffer burst
577 @param conn - memif conenction handle
578 @param qid - number indentifying queue
579 @param bufs - memif buffers
580 @param count - number of memif buffers to transmit
581 @param tx - returns number of transmitted buffers
585 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
586 memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
588 /** \brief Memif receive buffer burst
589 @param conn - memif conenction handle
590 @param qid - number indentifying queue
591 @param bufs - memif buffers
592 @param count - number of memif buffers to receive
593 @param rx - returns number of received buffers
597 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
598 memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
600 /** \brief Memif poll event
601 @param timeout - timeout in seconds
603 Passive event polling -
604 timeout = 0 - dont wait for event, check event queue if there is an event and return.
605 timeout = -1 - wait until event
609 int memif_poll_event (int timeout);
611 /** \brief Send signal to stop concurrently running memif_poll_event().
613 The function, however, does not wait for memif_poll_event() to stop.
614 memif_poll_event() may still return simply because an event has occured
615 or the timeout has elapsed, but if called repeatedly in an infinite loop,
616 a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
617 in the shortest possible time.
618 This feature was not available in the first release.
619 Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
623 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
624 int memif_cancel_poll_event ();
626 /** \brief Set connection request timer value
627 @param timer - new timer value
629 Timer on which all disconnected slaves request connection.
630 See system call 'timer_settime' man-page.
634 int memif_set_connection_request_timer (struct itimerspec timer);
636 /** \brief Send connection request
637 @param conn - memif connection handle
639 Only slave interface can request connection.
643 int memif_request_connection (memif_conn_handle_t conn);
645 /** \brief Create memif socket
646 @param sock - socket handle for client app
647 @param filename - path to socket file
648 @param private_ctx - private context
650 The first time an interface is assigned a socket, its type is determined.
651 For master role it's 'listener', for slave role it's 'client'. Each interface
652 requires socket of its respective type. Default socket is creted if no
653 socket handle is passed to memif_create(). It's private context is NULL.
654 If all interfaces using this socket are deleted, the socket returns
655 to its default state.
659 int memif_create_socket (memif_socket_handle_t * sock, const char * filename,
662 /** \brief Delete memif socket
663 @param sock - socket handle for client app
665 When trying to free socket in use, socket will not be freed and
666 MEMIF_ERR_INVAL_ARG is returned.
670 int memif_delete_socket (memif_socket_handle_t * sock);
674 #endif /* _LIBMEMIF_H_ */