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 *------------------------------------------------------------------
23 /** Libmemif version. */
24 #define LIBMEMIF_VERSION "1.0"
25 /** Default name of application using libmemif. */
26 #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 */
78 * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
83 /** user needs to set events that occured on fd and pass them to memif_control_fd_handler */
84 #define MEMIF_FD_EVENT_READ (1 << 0)
85 #define MEMIF_FD_EVENT_WRITE (1 << 1)
86 /** inform libmemif that error occured on fd */
87 #define MEMIF_FD_EVENT_ERROR (1 << 2)
88 /** if set, informs that fd is going to be closed (user may want to stop watching for events on this fd) */
89 #define MEMIF_FD_EVENT_DEL (1 << 3)
91 #define MEMIF_FD_EVENT_MOD (1 << 4)
94 /** *brief Memif connection handle
95 pointer of type void, pointing to internal structure
97 typedef void *memif_conn_handle_t;
99 * @defgroup CALLBACKS Callback functions definitions
104 /** \brief Memif control file descriptor update (callback function)
105 @param fd - new file descriptor to watch
106 @param events - event type(s) to watch for
108 This callback is called when there is new fd to watch for events on
109 or if fd is about to be closed (user mey want to stop watching for events on this fd).
111 typedef int (memif_control_fd_update_t) (int fd, uint8_t events);
113 /** \brief Memif connection status update (callback function)
114 @param conn - memif connection handle
115 @param private_ctx - private context
117 Informs user about connection status connected/disconnected.
118 On connected -> start watching for events on interrupt fd (optional).
120 typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
123 /** \brief Memif interrupt occured (callback function)
124 @param conn - memif connection handle
125 @param private_ctx - private context
126 @param qid - queue id on which interrupt occured
128 Called when event is received on interrupt fd.
130 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
135 * @defgroup ARGS_N_BUFS Connection arguments and buffers
140 /** \brief Memif connection arguments
141 @param socket_filename - socket filename
142 @param secret - otional parameter used as interface autenthication
143 @param num_s2m_rings - number of slave to master rings
144 @param num_m2s_rings - number of master to slave rings
145 @param buffer_size - size of buffer in shared memory
146 @param log2_ring_size - logarithm base 2 of ring size
147 @param is_master - 0 == master, 1 == slave
148 @param interface_id - id used to identify peer connection
149 @param interface_name - interface name
150 @param instance_name - application name
151 @param mode - 0 == ethernet, 1 == ip , 2 == punt/inject
155 uint8_t *socket_filename; /*!< default = /run/vpp/memif.sock */
156 uint8_t secret[24]; /*!< optional (interface authentication) */
158 uint8_t num_s2m_rings; /*!< default = 1 */
159 uint8_t num_m2s_rings; /*!< default = 1 */
160 uint16_t buffer_size; /*!< default = 2048 */
161 memif_log2_ring_size_t log2_ring_size; /*!< default = 10 (1024) */
164 memif_interface_id_t interface_id;
165 uint8_t interface_name[32];
166 uint8_t instance_name[32];
167 memif_interface_mode_t mode:8;
170 /*! memif receive mode */
173 MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */
174 MEMIF_RX_MODE_POLLING /*!< polling mode */
177 /** \brief Memif buffer
178 @param desc_index - ring descriptor index
179 @param buffer_len - shared meory buffer length
180 @param data_len - data length
181 @param data - pointer to shared memory data
193 * @defgroup MEMIF_DETAILS Memif details structs
198 /** \brief Memif queue details
199 @param qid - queue id
200 @param ring_size - size of ring buffer in sharem memory
201 @param buffer_size - buffer size on sharem memory
207 uint16_t buffer_size;
208 /* add ring information */
209 } memif_queue_details_t;
211 /** \brief Memif details
212 @param if_name - interface name
213 @param inst_name - application name
214 @param remote_if_name - peer interface name
215 @param remote_inst_name - peer application name
216 @param id - connection id
217 @param secret - secret
218 @param role - 0 = master, 1 = slave
219 @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
220 @param socket_filename = socket filename
221 @param rx_queues_num - number of receive queues
222 @param tx_queues_num - number of transmit queues
223 @param rx_queues - struct containing receive queue details
224 @param tx_queues - struct containing transmit queue details
225 @param link_up_down - 1 = up (connected), 2 = down (disconnected)
231 uint8_t *remote_if_name;
232 uint8_t *remote_inst_name;
235 uint8_t *secret; /* optional */
236 uint8_t role; /* 0 = master, 1 = slave */
237 uint8_t mode; /* 0 = ethernet, 1 = ip, 2 = punt/inject */
238 uint8_t *socket_filename;
239 uint8_t rx_queues_num;
240 uint8_t tx_queues_num;
241 memif_queue_details_t *rx_queues;
242 memif_queue_details_t *tx_queues;
244 uint8_t link_up_down; /* 1 = up, 0 = down */
249 * @defgroup API_CALLS Api calls
254 /** \biref Memif get queue event file descriptor
255 @param conn - memif connection handle
256 @param qid - queue id
257 @param[out] fd - returns event file descriptor
262 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
264 /** \brief Memif set rx mode
265 @param conn - memif connection handle
266 @param rx_mode - receive mode
267 @param qid - queue id
271 int memif_set_rx_mode (memif_conn_handle_t conn, memif_rx_mode_t rx_mode,
274 /** \brief Memif strerror
275 @param err_code - error code
277 Converts error code to error message.
281 char *memif_strerror (int err_code);
283 /** \brief Memif get details
284 @param conn - memif conenction handle
285 @param md - pointer to memif details struct
286 @param buf - buffer containing details strings
287 @param buflen - length of buffer
291 int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
292 char *buf, ssize_t buflen);
294 /** \brief Memif initialization
295 @param on_control_fd_update - if control fd updates inform user to watch new fd
296 @param app_name - application name
298 if param on_control_fd_update is set to NULL,
299 libmemif will handle file descriptor event polling
300 if a valid callback is set, file descriptor event polling needs to be done by
301 user application, all file descriptors and event types will be passed in
302 this callback to user application
304 Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
305 disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
306 timer is inactive at this state. It activates with if there is at least one memif in slave mode.
310 int memif_init (memif_control_fd_update_t * on_control_fd_update,
313 /** \brief Memif cleanup
315 Free libmemif internal allocations.
319 int memif_cleanup ();
321 /** \brief Memory interface create function
322 @param conn - connection handle for user app
323 @param args - memory interface connection arguments
324 @param on_connect - inform user about connected status
325 @param on_disconnect - inform user about disconnected status
326 @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
327 @param private_ctx - private contex passed back to user with callback
329 Creates memory interface.
332 Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
333 every disconnected memif in slave mode will send connection request.
334 On success new fd is passed to user with memif_control_fd_update_t.
337 Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
338 If this fd is passed to memif_control_fd_handler accept will be called and
339 new fd will be passed to user with memif_control_fd_update_t.
344 int memif_create (memif_conn_handle_t * conn, memif_conn_args_t * args,
345 memif_connection_update_t * on_connect,
346 memif_connection_update_t * on_disconnect,
347 memif_interrupt_t * on_interrupt, void *private_ctx);
349 /** \brief Memif control file descriptor handler
350 @param fd - file descriptor on which the event occured
351 @param events - event type(s) that occured
353 If event occures on any control fd, call memif_control_fd_handler.
354 Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
358 Every disconnected memif in slave mode will request connection.
359 LISTENER or CONTROL -
360 Handle socket messaging (internal connection establishment).
362 Call on_interrupt callback (if set).
367 int memif_control_fd_handler (int fd, uint8_t events);
369 /** \brief Memif delete
370 @param conn - pointer to memif connection handle
373 disconnect session (free queues and regions, close file descriptors, unmap shared memory)
374 set connection handle to NULL, to avoid possible double free
378 int memif_delete (memif_conn_handle_t * conn);
380 /** \brief Memif buffer alloc
381 @param conn - memif conenction handle
382 @param qid - number indentifying queue
383 @param bufs - memif buffers
384 @param count - number of memif buffers to allocate
385 @param count_out - returns number of allocated buffers
386 @param size - minimal buffer size, 0 = standard buffer size
390 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
391 memif_buffer_t * bufs, uint16_t count,
392 uint16_t * count_out, uint16_t size);
394 /** \brief Memif buffer free
395 @param conn - memif conenction handle
396 @param qid - number indentifying queue
397 @param bufs - memif buffers
398 @param count - number of memif buffers to free
399 @param count_out - returns number of freed buffers
403 int memif_buffer_free (memif_conn_handle_t conn, uint16_t qid,
404 memif_buffer_t * bufs, uint16_t count,
405 uint16_t * count_out);
407 /** \brief Memif transmit buffer burst
408 @param conn - memif conenction handle
409 @param qid - number indentifying queue
410 @param bufs - memif buffers
411 @param count - number of memif buffers to transmit
412 @param tx - returns number of transmitted buffers
416 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
417 memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
419 /** \brief Memif receive buffer burst
420 @param conn - memif conenction handle
421 @param qid - number indentifying queue
422 @param bufs - memif buffers
423 @param count - number of memif buffers to receive
424 @param rx - returns number of received buffers
428 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
429 memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
431 /** \brief Memif poll event
432 @param timeout - timeout in seconds
434 Passive event polling -
435 timeout = 0 - dont wait for event, check event queue if there is an event and return.
436 timeout = -1 - wait until event
440 int memif_poll_event (int timeout);
443 #endif /* _LIBMEMIF_H_ */