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 "1.0"
27 /** Default name of application using libmemif. */
28 #define MEMIF_DEFAULT_APP_NAME "libmemif-app"
37 MEMIF_ERR_SUCCESS = 0, /*!< success */
39 MEMIF_ERR_SYSCALL, /*!< other syscall error */
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 */
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 * @defgroup CALLBACKS Callback functions definitions
109 /** \brief Memif control file descriptor update (callback function)
110 @param fd - new file descriptor to watch
111 @param events - event type(s) to watch for
113 This callback is called when there is new fd to watch for events on
114 or if fd is about to be closed (user mey want to stop watching for events on this fd).
116 typedef int (memif_control_fd_update_t) (int fd, uint8_t events);
118 /** \brief Memif connection status update (callback function)
119 @param conn - memif connection handle
120 @param private_ctx - private context
122 Informs user about connection status connected/disconnected.
123 On connected -> start watching for events on interrupt fd (optional).
125 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
128 /** \brief Memif interrupt occured (callback function)
129 @param conn - memif connection handle
130 @param private_ctx - private context
131 @param qid - queue id on which interrupt occured
133 Called when event is received on interrupt fd.
135 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
140 * @defgroup ARGS_N_BUFS Connection arguments and buffers
146 /** \brief Memif connection arguments
147 @param socket_filename - socket filename
148 @param secret - otional parameter used as interface autenthication
149 @param num_s2m_rings - number of slave to master rings
150 @param num_m2s_rings - number of master to slave rings
151 @param buffer_size - size of buffer in shared memory
152 @param log2_ring_size - logarithm base 2 of ring size
153 @param is_master - 0 == master, 1 == slave
154 @param interface_id - id used to identify peer connection
155 @param interface_name - interface name
156 @param instance_name - application name
157 @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
161 uint8_t *socket_filename; /*!< default = /run/vpp/memif.sock */
162 uint8_t secret[24]; /*!< optional (interface authentication) */
164 uint8_t num_s2m_rings; /*!< default = 1 */
165 uint8_t num_m2s_rings; /*!< default = 1 */
166 uint16_t buffer_size; /*!< default = 2048 */
167 memif_log2_ring_size_t log2_ring_size; /*!< default = 10 (1024) */
170 memif_interface_id_t interface_id;
171 uint8_t interface_name[32];
172 uint8_t instance_name[32]; /*!< deprecated, will be removed in 2.0 */
173 memif_interface_mode_t mode:8;
176 /*! memif receive mode */
179 MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */
180 MEMIF_RX_MODE_POLLING /*!< polling mode */
183 /** \brief Memif buffer
184 @param desc_index - ring descriptor index
185 @param buffer_len - shared meory buffer length
186 @param data_len - data length
187 @param data - pointer to shared memory data
199 * @defgroup MEMIF_DETAILS Memif details structs
205 /** \brief Memif queue details
206 @param qid - queue id
207 @param ring_size - size of ring buffer in sharem memory
208 @param flags - ring flags
209 @param head - ring head pointer
210 @param tail - ring tail pointer
211 @param buffer_size - buffer size on sharem memory
217 /** if set queue is in polling mode, else in interrupt mode */
218 #define MEMIF_QUEUE_FLAG_POLLING 1
222 uint16_t buffer_size;
223 } memif_queue_details_t;
225 /** \brief Memif details
226 @param if_name - interface name
227 @param inst_name - application name
228 @param remote_if_name - peer interface name
229 @param remote_inst_name - peer application name
230 @param id - connection id
231 @param secret - secret
232 @param role - 0 = master, 1 = slave
233 @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
234 @param socket_filename = socket filename
235 @param rx_queues_num - number of receive queues
236 @param tx_queues_num - number of transmit queues
237 @param rx_queues - struct containing receive queue details
238 @param tx_queues - struct containing transmit queue details
239 @param link_up_down - 1 = up (connected), 2 = down (disconnected)
245 uint8_t *remote_if_name;
246 uint8_t *remote_inst_name;
249 uint8_t *secret; /* optional */
250 uint8_t role; /* 0 = master, 1 = slave */
251 uint8_t mode; /* 0 = ethernet, 1 = ip, 2 = punt/inject */
252 uint8_t *socket_filename;
253 uint8_t rx_queues_num;
254 uint8_t tx_queues_num;
255 memif_queue_details_t *rx_queues;
256 memif_queue_details_t *tx_queues;
258 uint8_t link_up_down; /* 1 = up, 0 = down */
263 * @defgroup API_CALLS Api calls
269 /** \biref Memif get queue event file descriptor
270 @param conn - memif connection handle
271 @param qid - queue id
272 @param[out] fd - returns event file descriptor
277 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
279 /** \brief Memif set rx mode
280 @param conn - memif connection handle
281 @param rx_mode - receive mode
282 @param qid - queue id
286 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
289 /** \brief Memif strerror
290 @param err_code - error code
292 Converts error code to error message.
296 char *memif_strerror (int err_code);
298 /** \brief Memif get details
299 @param conn - memif conenction handle
300 @param md - pointer to memif details struct
301 @param buf - buffer containing details strings
302 @param buflen - length of buffer
306 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
307 char *buf, ssize_t buflen);
309 /** \brief Memif initialization
310 @param on_control_fd_update - if control fd updates inform user to watch new fd
311 @param app_name - application name (will be truncated to 32 chars)
313 if param on_control_fd_update is set to NULL,
314 libmemif will handle file descriptor event polling
315 if a valid callback is set, file descriptor event polling needs to be done by
316 user application, all file descriptors and event types will be passed in
317 this callback to user application
319 Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
320 disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
321 timer is inactive at this state. It activates with if there is at least one memif in slave mode.
325 int memif_init (memif_control_fd_update_t * on_control_fd_update,
328 /** \brief Memif cleanup
330 Free libmemif internal allocations.
334 int memif_cleanup ();
336 /** \brief Memory interface create function
337 @param conn - connection handle for user app
338 @param args - memory interface connection arguments
339 @param on_connect - inform user about connected status
340 @param on_disconnect - inform user about disconnected status
341 @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
342 @param private_ctx - private contex passed back to user with callback
344 Creates memory interface.
347 Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
348 every disconnected memif in slave mode will send connection request.
349 On success new fd is passed to user with memif_control_fd_update_t.
352 Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
353 If this fd is passed to memif_control_fd_handler accept will be called and
354 new fd will be passed to user with memif_control_fd_update_t.
359 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
360 memif_connection_update_t * on_connect,
361 memif_connection_update_t * on_disconnect,
362 memif_interrupt_t * on_interrupt, void *private_ctx);
364 /** \brief Memif control file descriptor handler
365 @param fd - file descriptor on which the event occured
366 @param events - event type(s) that occured
368 If event occures on any control fd, call memif_control_fd_handler.
369 Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
373 Every disconnected memif in slave mode will request connection.
374 LISTENER or CONTROL -
375 Handle socket messaging (internal connection establishment).
377 Call on_interrupt callback (if set).
382 int memif_control_fd_handler (int fd, uint8_t events);
384 /** \brief Memif delete
385 @param conn - pointer to memif connection handle
388 disconnect session (free queues and regions, close file descriptors, unmap shared memory)
389 set connection handle to NULL, to avoid possible double free
393 int memif_delete (memif_conn_handle_t * conn);
395 /** \brief Memif buffer alloc
396 @param conn - memif conenction handle
397 @param qid - number indentifying queue
398 @param bufs - memif buffers
399 @param count - number of memif buffers to allocate
400 @param count_out - returns number of allocated buffers
401 @param size - minimal buffer size, 0 = standard buffer size
405 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
406 memif_buffer_t * bufs, uint16_t count,
407 uint16_t * count_out, uint16_t size);
409 /** \brief Memif buffer free
410 @param conn - memif conenction handle
411 @param qid - number indentifying queue
412 @param bufs - memif buffers
413 @param count - number of memif buffers to free
414 @param count_out - returns number of freed buffers
418 int memif_buffer_free (memif_conn_handle_t conn, uint16_t qid,
419 memif_buffer_t * bufs, uint16_t count,
420 uint16_t * count_out);
422 /** \brief Memif transmit buffer burst
423 @param conn - memif conenction handle
424 @param qid - number indentifying queue
425 @param bufs - memif buffers
426 @param count - number of memif buffers to transmit
427 @param tx - returns number of transmitted buffers
431 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
432 memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
434 /** \brief Memif receive buffer burst
435 @param conn - memif conenction handle
436 @param qid - number indentifying queue
437 @param bufs - memif buffers
438 @param count - number of memif buffers to receive
439 @param rx - returns number of received buffers
443 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
444 memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
446 /** \brief Memif poll event
447 @param timeout - timeout in seconds
449 Passive event polling -
450 timeout = 0 - dont wait for event, check event queue if there is an event and return.
451 timeout = -1 - wait until event
455 int memif_poll_event (int timeout);
457 /** \brief Send signal to stop concurrently running memif_poll_event().
459 The function, however, does not wait for memif_poll_event() to stop.
460 memif_poll_event() may still return simply because an event has occured
461 or the timeout has elapsed, but if called repeatedly in an infinite loop,
462 a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
463 in the shortest possible time.
464 This feature was not available in the first release.
465 Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
469 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
470 int memif_cancel_poll_event ();
473 #endif /* _LIBMEMIF_H_ */