FD.io VPP  v18.01.2-1-g9b554f3
Vector Packet Processing
libmemif.h
Go to the documentation of this file.
1 /*
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:
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
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  *------------------------------------------------------------------
16  */
17 
18 /** @file
19  * @defgroup libmemif
20  */
21 
22 #ifndef _LIBMEMIF_H_
23 #define _LIBMEMIF_H_
24 
25 /** Libmemif version. */
26 #define LIBMEMIF_VERSION "1.0"
27 /** Default name of application using libmemif. */
28 #define MEMIF_DEFAULT_APP_NAME "libmemif-app"
29 
30 #include <inttypes.h>
31 
32 #include <memif.h>
33 
34 /*! Error codes */
35 typedef enum
36 {
37  MEMIF_ERR_SUCCESS = 0, /*!< success */
38 /* SYSCALL ERRORS */
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 */
48 /* LIBMEMIF ERRORS */
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_t;
80 
81 /**
82  * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
83  * @ingroup libmemif
84  * @{
85  */
86 
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)
94 /** update events */
95 #define MEMIF_FD_EVENT_MOD (1 << 4)
96 /** @} */
97 
98 /** *brief Memif connection handle
99  pointer of type void, pointing to internal structure
100 */
101 typedef void *memif_conn_handle_t;
102 /**
103  * @defgroup CALLBACKS Callback functions definitions
104  * @ingroup libmemif
105  *
106  * @{
107  */
108 
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
112 
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).
115 */
116 typedef int (memif_control_fd_update_t) (int fd, uint8_t events);
117 
118 /** \brief Memif connection status update (callback function)
119  @param conn - memif connection handle
120  @param private_ctx - private context
121 
122  Informs user about connection status connected/disconnected.
123  On connected -> start watching for events on interrupt fd (optional).
124 */
126  void *private_ctx);
127 
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
132 
133  Called when event is received on interrupt fd.
134 */
135 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
136  uint16_t qid);
137 /** @} */
138 
139 /**
140  * @defgroup ARGS_N_BUFS Connection arguments and buffers
141  * @ingroup libmemif
142  *
143  * @{
144  */
145 
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
158 */
159 typedef struct
160 {
161  uint8_t *socket_filename; /*!< default = /run/vpp/memif.sock */
162  uint8_t secret[24]; /*!< optional (interface authentication) */
163 
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) */
168  uint8_t is_master;
169 
171  uint8_t interface_name[32];
172  uint8_t instance_name[32];
175 
176 /*! memif receive mode */
177 typedef enum
178 {
179  MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */
180  MEMIF_RX_MODE_POLLING /*!< polling mode */
182 
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
188 */
189 typedef struct
190 {
191  uint16_t desc_index;
192  uint32_t buffer_len;
193  uint32_t data_len;
194  void *data;
196 /** @} */
197 
198 /**
199  * @defgroup MEMIF_DETAILS Memif details structs
200  * @ingroup libmemif
201  *
202  * @{
203  */
204 
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
212 */
213 typedef struct
214 {
215  uint8_t qid;
216  uint32_t ring_size;
217 /** if set queue is in polling mode, else in interrupt mode */
218 #define MEMIF_QUEUE_FLAG_POLLING 1
219  uint16_t flags;
220  uint16_t head;
221  uint16_t tail;
222  uint16_t buffer_size;
224 
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)
240 */
241 typedef struct
242 {
243  uint8_t *if_name;
244  uint8_t *inst_name;
245  uint8_t *remote_if_name;
247 
248  uint32_t id;
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;
257 
258  uint8_t link_up_down; /* 1 = up, 0 = down */
260 /** @} */
261 
262 /**
263  * @defgroup API_CALLS Api calls
264  * @ingroup libmemif
265  *
266  * @{
267  */
268 
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
273 
274  \return memif_err_t
275 */
276 
277 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
278 
279 /** \brief Memif set rx mode
280  @param conn - memif connection handle
281  @param rx_mode - receive mode
282  @param qid - queue id
283 
284  \return memif_err_t
285 */
287  uint16_t qid);
288 
289 /** \brief Memif strerror
290  @param err_code - error code
291 
292  Converts error code to error message.
293 
294  \return Error string
295 */
296 char *memif_strerror (int err_code);
297 
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
303 
304  \return memif_err_t
305 */
307  char *buf, ssize_t buflen);
308 
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
312 
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
318 
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.
322 
323  \return memif_err_t
324 */
325 int memif_init (memif_control_fd_update_t * on_control_fd_update,
326  char *app_name);
327 
328 /** \brief Memif cleanup
329 
330  Free libmemif internal allocations.
331 
332  \return 0
333 */
334 int memif_cleanup ();
335 
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
343 
344  Creates memory interface.
345 
346  SLAVE-MODE -
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.
350 
351  MASTER-MODE -
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.
355 
356 
357  \return memif_err_t
358 */
362  memif_interrupt_t * on_interrupt, void *private_ctx);
363 
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
367 
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.
370 
371  FD-TYPE -
372  TIMERFD -
373  Every disconnected memif in slave mode will request connection.
374  LISTENER or CONTROL -
375  Handle socket messaging (internal connection establishment).
376  INTERRUPT -
377  Call on_interrupt callback (if set).
378 
379  \return memif_err_t
380 
381 */
382 int memif_control_fd_handler (int fd, uint8_t events);
383 
384 /** \brief Memif delete
385  @param conn - pointer to memif connection handle
386 
387 
388  disconnect session (free queues and regions, close file descriptors, unmap shared memory)
389  set connection handle to NULL, to avoid possible double free
390 
391  \return memif_err_t
392 */
393 int memif_delete (memif_conn_handle_t * conn);
394 
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
402 
403  \return memif_err_t
404 */
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);
408 
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
415 
416  \return memif_err_t
417 */
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);
421 
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
428 
429  \return memif_err_t
430 */
431 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
432  memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
433 
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
440 
441  \return memif_err_t
442 */
443 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
444  memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
445 
446 /** \brief Memif poll event
447  @param timeout - timeout in seconds
448 
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
452 
453  \return memif_err_t
454 */
455 int memif_poll_event (int timeout);
456 
457 /** \brief Send signal to stop concurrently running memif_poll_event().
458 
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.
466 
467  \return memif_err_t
468 */
469 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
471 /** @} */
472 
473 #endif /* _LIBMEMIF_H_ */
memif_log2_ring_size_t log2_ring_size
Definition: libmemif.h:167
uint8_t * inst_name
Definition: libmemif.h:244
uint8_t * secret
Definition: libmemif.h:249
int on_disconnect(memif_conn_handle_t conn, void *private_ctx)
Definition: main.c:186
uint8_t num_m2s_rings
Definition: libmemif.h:165
uint16_t buffer_size
Definition: libmemif.h:166
memif_interface_mode_t
Definition: memif.h:53
memif_interface_id_t interface_id
Definition: libmemif.h:170
int( memif_control_fd_update_t)(int fd, uint8_t events)
Memif control file descriptor update (callback function)
Definition: libmemif.h:116
uint16_t desc_index
Definition: libmemif.h:191
uint8_t * remote_inst_name
Definition: libmemif.h:246
int on_connect(memif_conn_handle_t conn, void *private_ctx)
Definition: main.c:177
uint8_t num_s2m_rings
Definition: libmemif.h:164
int memif_get_details(memif_conn_handle_t conn, memif_details_t *md, char *buf, ssize_t buflen)
Memif get details.
Definition: main.c:1950
int memif_buffer_free(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *bufs, uint16_t count, uint16_t *count_out)
Memif buffer free.
Definition: main.c:1493
uint8_t mode
Definition: libmemif.h:251
uint8_t link_up_down
Definition: libmemif.h:258
char * memif_strerror(int err_code)
Memif strerror.
Definition: main.c:153
void * data
Definition: libmemif.h:194
uint16_t buffer_size
Definition: libmemif.h:222
uint8_t * socket_filename
Definition: libmemif.h:252
int memif_set_rx_mode(memif_conn_handle_t conn, memif_rx_mode_t rx_mode, uint16_t qid)
Memif set rx mode.
Definition: main.c:520
int( memif_interrupt_t)(memif_conn_handle_t conn, void *private_ctx, uint16_t qid)
Memif interrupt occured (callback function)
Definition: libmemif.h:135
uint8_t memif_log2_ring_size_t
Definition: memif.h:66
int( memif_connection_update_t)(memif_conn_handle_t conn, void *private_ctx)
Memif connection status update (callback function)
Definition: libmemif.h:125
uint8_t is_master
Definition: libmemif.h:168
uint8_t rx_queues_num
Definition: libmemif.h:253
int memif_get_queue_efd(memif_conn_handle_t conn, uint16_t qid, int *fd)
Memif get queue event file descriptor
Definition: main.c:2076
int on_interrupt(memif_conn_handle_t conn, void *private_ctx, uint16_t qid)
Definition: main.c:287
int memif_tx_burst(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *bufs, uint16_t count, uint16_t *tx)
Memif transmit buffer burst.
Definition: main.c:1564
int memif_buffer_alloc(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *bufs, uint16_t count, uint16_t *count_out, uint16_t size)
Memif buffer alloc.
Definition: main.c:1380
int memif_poll_event(int timeout)
Memif poll event.
Definition: main.c:936
memif_queue_details_t * rx_queues
Definition: libmemif.h:255
uint32_t memif_interface_id_t
Definition: memif.h:64
uint8_t role
Definition: libmemif.h:250
int memif_cleanup()
Memif cleanup.
Definition: main.c:2096
uint32_t buffer_len
Definition: libmemif.h:192
int memif_create(memif_conn_handle_t *conn, memif_conn_args_t *args, memif_connection_update_t *on_connect, memif_connection_update_t *on_disconnect, memif_interrupt_t *on_interrupt, void *private_ctx)
Memory interface create function.
Definition: main.c:538
u64 size
Definition: vhost-user.h:76
uint8_t tx_queues_num
Definition: libmemif.h:254
size_t count
Definition: vapi.c:42
memif_err_t
Definition: libmemif.h:35
void * memif_conn_handle_t
*brief Memif connection handle pointer of type void, pointing to internal structure ...
Definition: libmemif.h:101
int memif_control_fd_handler(int fd, uint8_t events)
Memif control file descriptor handler.
Definition: main.c:787
int memif_init(memif_control_fd_update_t *on_control_fd_update, char *app_name)
Memif initialization.
Definition: main.c:405
uint32_t id
Definition: libmemif.h:248
int memif_rx_burst(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *bufs, uint16_t count, uint16_t *rx)
Memif receive buffer burst.
Definition: main.c:1787
memif_rx_mode_t
Definition: libmemif.h:177
int memif_delete(memif_conn_handle_t *conn)
Memif delete.
Definition: main.c:1111
Memif queue details.
Definition: libmemif.h:213
int memif_cancel_poll_event()
Definition: main.c:977
memif_queue_details_t * tx_queues
Definition: libmemif.h:256
uint8_t * if_name
Definition: libmemif.h:243
Memif buffer.
Definition: libmemif.h:189
Memif connection arguments.
Definition: libmemif.h:159
Memif details.
Definition: libmemif.h:241
uint8_t * remote_if_name
Definition: libmemif.h:245
uint8_t * socket_filename
Definition: libmemif.h:161
uint32_t data_len
Definition: libmemif.h:193