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_ACCES, /*!< permission denied */
39 MEMIF_ERR_NO_FILE, /*!< file does not exist */
40 MEMIF_ERR_FILE_LIMIT, /*!< system open file limit */
41 MEMIF_ERR_PROC_FILE_LIMIT, /*!< process open file limit */
42 MEMIF_ERR_ALREADY, /*!< connection already requested */
43 MEMIF_ERR_AGAIN, /*!< fd is not socket, or operation would block */
44 MEMIF_ERR_BAD_FD, /*!< invalid fd */
45 MEMIF_ERR_NOMEM, /*!< out of memory */
47 MEMIF_ERR_INVAL_ARG, /*!< invalid argument */
48 MEMIF_ERR_NOCONN, /*!< handle points to no connection */
49 MEMIF_ERR_CONN, /*!< handle points to existing connection */
50 MEMIF_ERR_CB_FDUPDATE, /*!< user defined callback memif_control_fd_update_t error */
51 MEMIF_ERR_FILE_NOT_SOCK, /*!< file specified by socket filename
52 exists, but it's not socket */
53 MEMIF_ERR_NO_SHMFD, /*!< missing shm fd */
54 MEMIF_ERR_COOKIE, /*!< wrong cookie on ring */
55 MEMIF_ERR_NOBUF_RING, /*!< ring buffer full */
56 MEMIF_ERR_NOBUF, /*!< not enough memif buffers */
57 MEMIF_ERR_NOBUF_DET, /*!< memif details needs larger buffer */
58 MEMIF_ERR_INT_WRITE, /*!< send interrupt error */
59 MEMIF_ERR_MFMSG, /*!< malformed msg received */
60 MEMIF_ERR_QID, /*!< invalid queue id */
61 /* MEMIF PROTO ERRORS */
62 MEMIF_ERR_PROTO, /*!< incompatible protocol version */
63 MEMIF_ERR_ID, /*!< unmatched interface id */
64 MEMIF_ERR_ACCSLAVE, /*!< slave cannot accept connection requests */
65 MEMIF_ERR_ALRCONN, /*!< memif is already connected */
66 MEMIF_ERR_MODE, /*!< mode mismatch */
67 MEMIF_ERR_SECRET, /*!< secret mismatch */
68 MEMIF_ERR_NOSECRET, /*!< secret required */
69 MEMIF_ERR_MAXREG, /*!< max region limit reached */
70 MEMIF_ERR_MAXRING, /*!< max ring limit reached */
71 MEMIF_ERR_NO_INTFD, /*!< missing interrupt fd */
72 MEMIF_ERR_DISCONNECT, /*!< disconenct received */
73 MEMIF_ERR_DISCONNECTED, /*!< peer interface disconnected */
74 MEMIF_ERR_UNKNOWN_MSG, /*!< unknown message type */
75 MEMIF_ERR_POLL_CANCEL, /*!< memif_poll_event() was cancelled */
76 MEMIF_ERR_MAX_RING, /*!< too large ring size */
77 MEMIF_ERR_PRIVHDR, /*!< private hdrs not supported */
81 * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
86 /** user needs to set events that occured on fd and pass them to memif_control_fd_handler */
87 #define MEMIF_FD_EVENT_READ (1 << 0)
88 #define MEMIF_FD_EVENT_WRITE (1 << 1)
89 /** inform libmemif that error occured on fd */
90 #define MEMIF_FD_EVENT_ERROR (1 << 2)
91 /** if set, informs that fd is going to be closed (user may want to stop watching for events on this fd) */
92 #define MEMIF_FD_EVENT_DEL (1 << 3)
94 #define MEMIF_FD_EVENT_MOD (1 << 4)
97 /** \brief Memif connection handle
98 pointer of type void, pointing to internal structure
100 typedef void *memif_conn_handle_t;
102 /** \brief Memif allocator alloc
103 @param size - requested allocation size
105 custom memory allocator: alloc function template
107 typedef void *(memif_alloc_t) (size_t size);
109 /** \brief Memif allocator free
110 @param size - requested allocation size
112 custom memory allocator: free function template
114 typedef void (memif_free_t) (void *ptr);
117 * @defgroup CALLBACKS Callback functions definitions
123 /** \brief Memif control file descriptor update (callback function)
124 @param fd - new file descriptor to watch
125 @param events - event type(s) to watch for
127 This callback is called when there is new fd to watch for events on
128 or if fd is about to be closed (user mey want to stop watching for events on this fd).
130 typedef int (memif_control_fd_update_t) (int fd, uint8_t events);
132 /** \brief Memif connection status update (callback function)
133 @param conn - memif connection handle
134 @param private_ctx - private context
136 Informs user about connection status connected/disconnected.
137 On connected -> start watching for events on interrupt fd (optional).
139 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
142 /** \brief Memif interrupt occured (callback function)
143 @param conn - memif connection handle
144 @param private_ctx - private context
145 @param qid - queue id on which interrupt occured
147 Called when event is received on interrupt fd.
149 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
154 * @defgroup ARGS_N_BUFS Connection arguments and buffers
163 MEMIF_INTERFACE_MODE_ETHERNET = 0,
164 MEMIF_INTERFACE_MODE_IP = 1,
165 MEMIF_INTERFACE_MODE_PUNT_INJECT = 2,
166 } memif_interface_mode_t;
167 #endif /* _MEMIF_H_ */
169 /** \brief Memif connection arguments
170 @param socket_filename - socket filename
171 @param secret - otional parameter used as interface autenthication
172 @param num_s2m_rings - number of slave to master rings
173 @param num_m2s_rings - number of master to slave rings
174 @param buffer_size - size of buffer in shared memory
175 @param log2_ring_size - logarithm base 2 of ring size
176 @param is_master - 0 == master, 1 == slave
177 @param interface_id - id used to identify peer connection
178 @param interface_name - interface name
179 @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
183 uint8_t *socket_filename; /*!< default = /run/vpp/memif.sock */
184 uint8_t secret[24]; /*!< optional (interface authentication) */
186 uint8_t num_s2m_rings; /*!< default = 1 */
187 uint8_t num_m2s_rings; /*!< default = 1 */
188 uint16_t buffer_size; /*!< default = 2048 */
189 uint8_t log2_ring_size; /*!< default = 10 (1024) */
192 uint32_t interface_id;
193 uint8_t interface_name[32];
194 memif_interface_mode_t mode:8;
197 /*! memif receive mode */
200 MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */
201 MEMIF_RX_MODE_POLLING /*!< polling mode */
204 /** \brief Memif buffer
205 @param desc_index - ring descriptor index
206 @param len - buffer length
207 @param flags - memif buffer flags
208 @param data - pointer to shared memory data
214 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
221 * @defgroup MEMIF_DETAILS Memif details structs
227 /** \brief Memif queue details
228 @param qid - queue id
229 @param ring_size - size of ring buffer in sharem memory
230 @param flags - ring flags
231 @param head - ring head pointer
232 @param tail - ring tail pointer
233 @param buffer_size - buffer size on sharem memory
239 /** if set queue is in polling mode, else in interrupt mode */
240 #define MEMIF_QUEUE_FLAG_POLLING 1
244 uint16_t buffer_size;
245 } memif_queue_details_t;
247 /** \brief Memif details
248 @param if_name - interface name
249 @param inst_name - application name
250 @param remote_if_name - peer interface name
251 @param remote_inst_name - peer application name
252 @param id - connection id
253 @param secret - secret
254 @param role - 0 = master, 1 = slave
255 @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
256 @param socket_filename = socket filename
257 @param rx_queues_num - number of receive queues
258 @param tx_queues_num - number of transmit queues
259 @param rx_queues - struct containing receive queue details
260 @param tx_queues - struct containing transmit queue details
261 @param link_up_down - 1 = up (connected), 2 = down (disconnected)
267 uint8_t *remote_if_name;
268 uint8_t *remote_inst_name;
271 uint8_t *secret; /* optional */
272 uint8_t role; /* 0 = master, 1 = slave */
273 uint8_t mode; /* 0 = ethernet, 1 = ip, 2 = punt/inject */
274 uint8_t *socket_filename;
275 uint8_t rx_queues_num;
276 uint8_t tx_queues_num;
277 memif_queue_details_t *rx_queues;
278 memif_queue_details_t *tx_queues;
280 uint8_t link_up_down; /* 1 = up, 0 = down */
285 * @defgroup API_CALLS Api calls
291 /** \brief Memif get version
293 \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR)
295 uint16_t memif_get_version ();
297 /** \biref Memif get queue event file descriptor
298 @param conn - memif connection handle
299 @param qid - queue id
300 @param[out] fd - returns event file descriptor
305 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
307 /** \brief Memif set rx mode
308 @param conn - memif connection handle
309 @param rx_mode - receive mode
310 @param qid - queue id
314 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
317 /** \brief Memif strerror
318 @param err_code - error code
320 Converts error code to error message.
324 char *memif_strerror (int err_code);
326 /** \brief Memif get details
327 @param conn - memif conenction handle
328 @param md - pointer to memif details struct
329 @param buf - buffer containing details strings
330 @param buflen - length of buffer
334 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
335 char *buf, ssize_t buflen);
337 /** \brief Memif initialization
338 @param on_control_fd_update - if control fd updates inform user to watch new fd
339 @param app_name - application name (will be truncated to 32 chars)
340 @param memif_alloc - cutom memory allocator, NULL = default
341 @param memif_free - custom memory free, NULL = default
343 if param on_control_fd_update is set to NULL,
344 libmemif will handle file descriptor event polling
345 if a valid callback is set, file descriptor event polling needs to be done by
346 user application, all file descriptors and event types will be passed in
347 this callback to user application
349 Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
350 disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
351 timer is inactive at this state. It activates with if there is at least one memif in slave mode.
355 int memif_init (memif_control_fd_update_t * on_control_fd_update,
356 char *app_name, memif_alloc_t * memif_alloc,
357 memif_free_t * memif_free);
359 /** \brief Memif cleanup
361 Free libmemif internal allocations.
365 int memif_cleanup ();
367 /** \brief Memory interface create function
368 @param conn - connection handle for user app
369 @param args - memory interface connection arguments
370 @param on_connect - inform user about connected status
371 @param on_disconnect - inform user about disconnected status
372 @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
373 @param private_ctx - private contex passed back to user with callback
375 Creates memory interface.
378 Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
379 every disconnected memif in slave mode will send connection request.
380 On success new fd is passed to user with memif_control_fd_update_t.
383 Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
384 If this fd is passed to memif_control_fd_handler accept will be called and
385 new fd will be passed to user with memif_control_fd_update_t.
390 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
391 memif_connection_update_t * on_connect,
392 memif_connection_update_t * on_disconnect,
393 memif_interrupt_t * on_interrupt, void *private_ctx);
395 /** \brief Memif control file descriptor handler
396 @param fd - file descriptor on which the event occured
397 @param events - event type(s) that occured
399 If event occures on any control fd, call memif_control_fd_handler.
400 Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
404 Every disconnected memif in slave mode will request connection.
405 LISTENER or CONTROL -
406 Handle socket messaging (internal connection establishment).
408 Call on_interrupt callback (if set).
413 int memif_control_fd_handler (int fd, uint8_t events);
415 /** \brief Memif delete
416 @param conn - pointer to memif connection handle
419 disconnect session (free queues and regions, close file descriptors, unmap shared memory)
420 set connection handle to NULL, to avoid possible double free
424 int memif_delete (memif_conn_handle_t * conn);
426 /** \brief Memif buffer alloc
427 @param conn - memif conenction handle
428 @param qid - number indentifying queue
429 @param bufs - memif buffers
430 @param count - number of memif buffers to allocate
431 @param count_out - returns number of allocated buffers
432 @param size - buffer size, may return chained buffers if size > buffer_size
436 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
437 memif_buffer_t * bufs, uint16_t count,
438 uint16_t * count_out, uint16_t size);
440 /** \brief Memif refill ring
441 @param conn - memif conenction handle
442 @param qid - number indentifying queue
443 @param count - number of buffers to be placed on ring
447 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
450 /** \brief Memif transmit buffer burst
451 @param conn - memif conenction handle
452 @param qid - number indentifying queue
453 @param bufs - memif buffers
454 @param count - number of memif buffers to transmit
455 @param tx - returns number of transmitted buffers
459 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
460 memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
462 /** \brief Memif receive buffer burst
463 @param conn - memif conenction handle
464 @param qid - number indentifying queue
465 @param bufs - memif buffers
466 @param count - number of memif buffers to receive
467 @param rx - returns number of received buffers
471 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
472 memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
474 /** \brief Memif poll event
475 @param timeout - timeout in seconds
477 Passive event polling -
478 timeout = 0 - dont wait for event, check event queue if there is an event and return.
479 timeout = -1 - wait until event
483 int memif_poll_event (int timeout);
485 /** \brief Send signal to stop concurrently running memif_poll_event().
487 The function, however, does not wait for memif_poll_event() to stop.
488 memif_poll_event() may still return simply because an event has occured
489 or the timeout has elapsed, but if called repeatedly in an infinite loop,
490 a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
491 in the shortest possible time.
492 This feature was not available in the first release.
493 Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
497 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
498 int memif_cancel_poll_event ();
501 #endif /* _LIBMEMIF_H_ */