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 "2.0"
27 /** Default name of application using libmemif. */
28 #define MEMIF_DEFAULT_APP_NAME "libmemif-app"
35 MEMIF_ERR_SUCCESS = 0, /*!< success */
37 MEMIF_ERR_SYSCALL, /*!< other syscall error */
38 MEMIF_ERR_CONNREFUSED, /*!< connection refused */
39 MEMIF_ERR_ACCES, /*!< permission denied */
40 MEMIF_ERR_NO_FILE, /*!< file does not exist */
41 MEMIF_ERR_FILE_LIMIT, /*!< system open file limit */
42 MEMIF_ERR_PROC_FILE_LIMIT, /*!< process open file limit */
43 MEMIF_ERR_ALREADY, /*!< connection already requested */
44 MEMIF_ERR_AGAIN, /*!< fd is not socket, or operation would block */
45 MEMIF_ERR_BAD_FD, /*!< invalid fd */
46 MEMIF_ERR_NOMEM, /*!< out of memory */
48 MEMIF_ERR_INVAL_ARG, /*!< invalid argument */
49 MEMIF_ERR_NOCONN, /*!< handle points to no connection */
50 MEMIF_ERR_CONN, /*!< handle points to existing connection */
51 MEMIF_ERR_CB_FDUPDATE, /*!< user defined callback memif_control_fd_update_t error */
52 MEMIF_ERR_FILE_NOT_SOCK, /*!< file specified by socket filename
53 exists, but it's not socket */
54 MEMIF_ERR_NO_SHMFD, /*!< missing shm fd */
55 MEMIF_ERR_COOKIE, /*!< wrong cookie on ring */
56 MEMIF_ERR_NOBUF_RING, /*!< ring buffer full */
57 MEMIF_ERR_NOBUF, /*!< not enough memif buffers */
58 MEMIF_ERR_NOBUF_DET, /*!< memif details needs larger buffer */
59 MEMIF_ERR_INT_WRITE, /*!< send interrupt error */
60 MEMIF_ERR_MFMSG, /*!< malformed msg received */
61 MEMIF_ERR_QID, /*!< invalid queue id */
62 /* MEMIF PROTO ERRORS */
63 MEMIF_ERR_PROTO, /*!< incompatible protocol version */
64 MEMIF_ERR_ID, /*!< unmatched interface id */
65 MEMIF_ERR_ACCSLAVE, /*!< slave cannot accept connection requests */
66 MEMIF_ERR_ALRCONN, /*!< memif is already connected */
67 MEMIF_ERR_MODE, /*!< mode mismatch */
68 MEMIF_ERR_SECRET, /*!< secret mismatch */
69 MEMIF_ERR_NOSECRET, /*!< secret required */
70 MEMIF_ERR_MAXREG, /*!< max region limit reached */
71 MEMIF_ERR_MAXRING, /*!< max ring limit reached */
72 MEMIF_ERR_NO_INTFD, /*!< missing interrupt fd */
73 MEMIF_ERR_DISCONNECT, /*!< disconenct received */
74 MEMIF_ERR_DISCONNECTED, /*!< peer interface disconnected */
75 MEMIF_ERR_UNKNOWN_MSG, /*!< unknown message type */
76 MEMIF_ERR_POLL_CANCEL, /*!< memif_poll_event() was cancelled */
77 MEMIF_ERR_MAX_RING, /*!< too large ring size */
78 MEMIF_ERR_PRIVHDR, /*!< private hdrs not supported */
82 * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
87 /** user needs to set events that occured on fd and pass them to memif_control_fd_handler */
88 #define MEMIF_FD_EVENT_READ (1 << 0)
89 #define MEMIF_FD_EVENT_WRITE (1 << 1)
90 /** inform libmemif that error occured on fd */
91 #define MEMIF_FD_EVENT_ERROR (1 << 2)
92 /** if set, informs that fd is going to be closed (user may want to stop watching for events on this fd) */
93 #define MEMIF_FD_EVENT_DEL (1 << 3)
95 #define MEMIF_FD_EVENT_MOD (1 << 4)
98 /** \brief Memif connection handle
99 pointer of type void, pointing to internal structure
101 typedef void *memif_conn_handle_t;
103 /** \brief Memif allocator alloc
104 @param size - requested allocation size
106 custom memory allocator: alloc function template
108 typedef void *(memif_alloc_t) (size_t size);
111 /** \brief Memif realloc
112 @param ptr - pointer to memory block
113 @param size - requested allocation size
115 custom memory reallocation
117 typedef void *(memif_realloc_t) (void *ptr, size_t size);
119 /** \brief Memif allocator free
120 @param size - requested allocation size
122 custom memory allocator: free function template
124 typedef void (memif_free_t) (void *ptr);
127 * @defgroup CALLBACKS Callback functions definitions
133 /** \brief Memif control file descriptor update (callback function)
134 @param fd - new file descriptor to watch
135 @param events - event type(s) to watch for
137 This callback is called when there is new fd to watch for events on
138 or if fd is about to be closed (user mey want to stop watching for events on this fd).
140 typedef int (memif_control_fd_update_t) (int fd, uint8_t events);
142 /** \brief Memif connection status update (callback function)
143 @param conn - memif connection handle
144 @param private_ctx - private context
146 Informs user about connection status connected/disconnected.
147 On connected -> start watching for events on interrupt fd (optional).
149 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
152 /** \brief Memif interrupt occured (callback function)
153 @param conn - memif connection handle
154 @param private_ctx - private context
155 @param qid - queue id on which interrupt occured
157 Called when event is received on interrupt fd.
159 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
165 * @defgroup EXTERNAL_REGION External region APIs
171 /** \brief Get external buffer offset (optional)
172 @param private_ctx - private context
174 Find unallocated external buffer and return its offset.
176 typedef uint32_t (memif_get_external_buffer_offset_t) (void *private_ctx);
178 /** \brief Add external region
179 @param[out] addr - region address
180 @param size - requested region size
181 @param fd[out] - file descriptor
182 @param private_ctx - private context
184 Called by slave. Add external region created by client.
186 typedef int (memif_add_external_region_t) (void * *addr, uint32_t size,
187 int *fd, void *private_ctx);
189 /** \brief Get external region address
190 @param size - requested region size
191 @param fd - file descriptor
192 @param private_ctx - private context
194 Called by master. Get region address from client.
196 \return region address
198 typedef void *(memif_get_external_region_addr_t) (uint32_t size, int fd,
201 /** \brief Delete external region
202 @param addr - region address
203 @param size - region size
204 @param fd - file descriptor
205 @param private_ctx - private context
207 Delete external region.
209 typedef int (memif_del_external_region_t) (void *addr, uint32_t size, int fd,
212 /** \brief Register external region
213 @param ar - add external region callback
214 @param gr - get external region addr callback
215 @param dr - delete external region callback
216 @param go - get external buffer offset callback (optional)
218 void memif_register_external_region (memif_add_external_region_t * ar,
219 memif_get_external_region_addr_t * gr,
220 memif_del_external_region_t * dr,
221 memif_get_external_buffer_offset_t * go);
226 * @defgroup ARGS_N_BUFS Connection arguments and buffers
235 MEMIF_INTERFACE_MODE_ETHERNET = 0,
236 MEMIF_INTERFACE_MODE_IP = 1,
237 MEMIF_INTERFACE_MODE_PUNT_INJECT = 2,
238 } memif_interface_mode_t;
239 #endif /* _MEMIF_H_ */
241 /** \brief Memif connection arguments
242 @param socket_filename - socket filename
243 @param secret - otional parameter used as interface autenthication
244 @param num_s2m_rings - number of slave to master rings
245 @param num_m2s_rings - number of master to slave rings
246 @param buffer_size - size of buffer in shared memory
247 @param log2_ring_size - logarithm base 2 of ring size
248 @param is_master - 0 == master, 1 == slave
249 @param interface_id - id used to identify peer connection
250 @param interface_name - interface name
251 @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
255 uint8_t *socket_filename; /*!< default = /run/vpp/memif.sock */
256 uint8_t secret[24]; /*!< optional (interface authentication) */
258 uint8_t num_s2m_rings; /*!< default = 1 */
259 uint8_t num_m2s_rings; /*!< default = 1 */
260 uint16_t buffer_size; /*!< default = 2048 */
261 uint8_t log2_ring_size; /*!< default = 10 (1024) */
264 uint32_t interface_id;
265 uint8_t interface_name[32];
266 memif_interface_mode_t mode:8;
269 /*! memif receive mode */
272 MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */
273 MEMIF_RX_MODE_POLLING /*!< polling mode */
276 /** \brief Memif buffer
277 @param desc_index - ring descriptor index
278 @param ring - pointer to ring containing descriptor for this buffer
279 @param len - available length
280 @param flags - memif buffer flags
281 @param data - pointer to shared memory data
288 /** next buffer present (chained buffers) */
289 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
290 /** states that buffer is from rx ring */
291 #define MEMIF_BUFFER_FLAG_RX (1 << 1)
298 * @defgroup MEMIF_DETAILS Memif details structs
304 /** \brief Memif queue details
305 @param region - region index
306 @param qid - queue id
307 @param ring_size - size of ring buffer in sharem memory
308 @param flags - ring flags
309 @param head - ring head pointer
310 @param tail - ring tail pointer
311 @param buffer_size - buffer size on sharem memory
318 /** if set queue is in polling mode, else in interrupt mode */
319 #define MEMIF_QUEUE_FLAG_POLLING 1
323 uint16_t buffer_size;
324 } memif_queue_details_t;
326 /** \brief Memif region details
327 @param index - region index
328 @param addr - region address
329 @param size - region size
330 @param fd - file descriptor
331 @param is_external - if not zero then region is defined by client
340 } memif_region_details_t;
342 /** \brief Memif details
343 @param if_name - interface name
344 @param inst_name - application name
345 @param remote_if_name - peer interface name
346 @param remote_inst_name - peer application name
347 @param id - connection id
348 @param secret - secret
349 @param role - 0 = master, 1 = slave
350 @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
351 @param socket_filename - socket filename
352 @param regions_num - number of regions
353 @param regions - struct containing region details
354 @param rx_queues_num - number of receive queues
355 @param tx_queues_num - number of transmit queues
356 @param rx_queues - struct containing receive queue details
357 @param tx_queues - struct containing transmit queue details
358 @param error - error string
359 @param link_up_down - 1 = up (connected), 2 = down (disconnected)
365 uint8_t *remote_if_name;
366 uint8_t *remote_inst_name;
369 uint8_t *secret; /* optional */
370 uint8_t role; /* 0 = master, 1 = slave */
371 uint8_t mode; /* 0 = ethernet, 1 = ip, 2 = punt/inject */
372 uint8_t *socket_filename;
374 memif_region_details_t *regions;
375 uint8_t rx_queues_num;
376 uint8_t tx_queues_num;
377 memif_queue_details_t *rx_queues;
378 memif_queue_details_t *tx_queues;
381 uint8_t link_up_down; /* 1 = up, 0 = down */
386 * @defgroup API_CALLS Api calls
392 /** \brief Memif get version
394 \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR)
396 uint16_t memif_get_version ();
398 /** \biref Memif get queue event file descriptor
399 @param conn - memif connection handle
400 @param qid - queue id
401 @param[out] fd - returns event file descriptor
406 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
408 /** \brief Memif set rx mode
409 @param conn - memif connection handle
410 @param rx_mode - receive mode
411 @param qid - queue id
415 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
418 /** \brief Memif strerror
419 @param err_code - error code
421 Converts error code to error message.
425 char *memif_strerror (int err_code);
427 /** \brief Memif get details
428 @param conn - memif conenction handle
429 @param md - pointer to memif details struct
430 @param buf - buffer containing details strings
431 @param buflen - length of buffer
435 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
436 char *buf, ssize_t buflen);
438 /** \brief Memif initialization
439 @param on_control_fd_update - if control fd updates inform user to watch new fd
440 @param app_name - application name (will be truncated to 32 chars)
441 @param memif_alloc - cutom memory allocator, NULL = default
442 @param memif_realloc - custom memory reallocation, NULL = default
443 @param memif_free - custom memory free, NULL = default
445 if param on_control_fd_update is set to NULL,
446 libmemif will handle file descriptor event polling
447 if a valid callback is set, file descriptor event polling needs to be done by
448 user application, all file descriptors and event types will be passed in
449 this callback to user application
451 Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
452 disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
453 timer is inactive at this state. It activates with if there is at least one memif in slave mode.
457 int memif_init (memif_control_fd_update_t * on_control_fd_update,
458 char *app_name, memif_alloc_t * memif_alloc,
459 memif_realloc_t * memif_realloc, memif_free_t * memif_free);
461 /** \brief Memif cleanup
463 Free libmemif internal allocations.
467 int memif_cleanup ();
469 /** \brief Memory interface create function
470 @param conn - connection handle for user app
471 @param args - memory interface connection arguments
472 @param on_connect - inform user about connected status
473 @param on_disconnect - inform user about disconnected status
474 @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
475 @param private_ctx - private contex passed back to user with callback
477 Creates memory interface.
480 Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
481 every disconnected memif in slave mode will send connection request.
482 On success new fd is passed to user with memif_control_fd_update_t.
485 Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
486 If this fd is passed to memif_control_fd_handler accept will be called and
487 new fd will be passed to user with memif_control_fd_update_t.
492 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
493 memif_connection_update_t * on_connect,
494 memif_connection_update_t * on_disconnect,
495 memif_interrupt_t * on_interrupt, void *private_ctx);
497 /** \brief Memif control file descriptor handler
498 @param fd - file descriptor on which the event occured
499 @param events - event type(s) that occured
501 If event occures on any control fd, call memif_control_fd_handler.
502 Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
506 Every disconnected memif in slave mode will request connection.
507 LISTENER or CONTROL -
508 Handle socket messaging (internal connection establishment).
510 Call on_interrupt callback (if set).
515 int memif_control_fd_handler (int fd, uint8_t events);
517 /** \brief Memif delete
518 @param conn - pointer to memif connection handle
521 disconnect session (free queues and regions, close file descriptors, unmap shared memory)
522 set connection handle to NULL, to avoid possible double free
526 int memif_delete (memif_conn_handle_t * conn);
528 /** \brief Memif buffer enq tx
529 @param conn - memif conenction handle
530 @param qid - number indentifying queue
531 @param bufs - memif buffers
532 @param count - number of memif buffers to enque
533 @param count_out - returns number of allocated buffers
535 Slave is producer of buffers.
536 If connection handle points to master returns MEMIF_ERR_INVAL_ARG.
540 int memif_buffer_enq_tx (memif_conn_handle_t conn, uint16_t qid,
541 memif_buffer_t * bufs, uint16_t count,
542 uint16_t * count_out);
544 /** \brief Memif buffer alloc
545 @param conn - memif conenction handle
546 @param qid - number indentifying queue
547 @param bufs - memif buffers
548 @param count - number of memif buffers to allocate
549 @param count_out - returns number of allocated buffers
550 @param size - buffer size, may return chained buffers if size > buffer_size
554 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
555 memif_buffer_t * bufs, uint16_t count,
556 uint16_t * count_out, uint16_t size);
558 /** \brief Memif refill ring
559 @param conn - memif conenction handle
560 @param qid - number indentifying queue
561 @param count - number of buffers to be placed on ring
562 @param headroom - offset the buffer by headroom
566 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
567 uint16_t count, uint16_t headroom);
569 /** \brief Memif transmit buffer burst
570 @param conn - memif conenction handle
571 @param qid - number indentifying queue
572 @param bufs - memif buffers
573 @param count - number of memif buffers to transmit
574 @param tx - returns number of transmitted buffers
578 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
579 memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
581 /** \brief Memif receive buffer burst
582 @param conn - memif conenction handle
583 @param qid - number indentifying queue
584 @param bufs - memif buffers
585 @param count - number of memif buffers to receive
586 @param rx - returns number of received buffers
590 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
591 memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
593 /** \brief Memif poll event
594 @param timeout - timeout in seconds
596 Passive event polling -
597 timeout = 0 - dont wait for event, check event queue if there is an event and return.
598 timeout = -1 - wait until event
602 int memif_poll_event (int timeout);
604 /** \brief Send signal to stop concurrently running memif_poll_event().
606 The function, however, does not wait for memif_poll_event() to stop.
607 memif_poll_event() may still return simply because an event has occured
608 or the timeout has elapsed, but if called repeatedly in an infinite loop,
609 a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
610 in the shortest possible time.
611 This feature was not available in the first release.
612 Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
616 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
617 int memif_cancel_poll_event ();
620 #endif /* _LIBMEMIF_H_ */