FD.io VPP  v18.11-rc0-18-g2a3fb1a
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 "2.0"
27 /** Default name of application using libmemif. */
28 #define MEMIF_DEFAULT_APP_NAME "libmemif-app"
29 
30 #include <inttypes.h>
31 
32 /*! Error codes */
33 typedef enum
34 {
35  MEMIF_ERR_SUCCESS = 0, /*!< success */
36 /* SYSCALL ERRORS */
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 */
46 /* LIBMEMIF ERRORS */
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 */
78 } memif_err_t;
79 
80 /**
81  * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
82  * @ingroup libmemif
83  * @{
84  */
85 
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)
93 /** update events */
94 #define MEMIF_FD_EVENT_MOD (1 << 4)
95 /** @} */
96 
97 /** \brief Memif connection handle
98  pointer of type void, pointing to internal structure
99 */
100 typedef void *memif_conn_handle_t;
101 
102 /** \brief Memif allocator alloc
103  @param size - requested allocation size
104 
105  custom memory allocator: alloc function template
106 */
107 typedef void *(memif_alloc_t) (size_t size);
108 
109 /** \brief Memif allocator free
110  @param size - requested allocation size
111 
112  custom memory allocator: free function template
113 */
114 typedef void (memif_free_t) (void *ptr);
115 
116 /**
117  * @defgroup CALLBACKS Callback functions definitions
118  * @ingroup libmemif
119  *
120  * @{
121  */
122 
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
126 
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).
129 */
130 typedef int (memif_control_fd_update_t) (int fd, uint8_t events);
131 
132 /** \brief Memif connection status update (callback function)
133  @param conn - memif connection handle
134  @param private_ctx - private context
135 
136  Informs user about connection status connected/disconnected.
137  On connected -> start watching for events on interrupt fd (optional).
138 */
140  void *private_ctx);
141 
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
146 
147  Called when event is received on interrupt fd.
148 */
149 typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
150  uint16_t qid);
151 /** @} */
152 
153 /**
154  * @defgroup ARGS_N_BUFS Connection arguments and buffers
155  * @ingroup libmemif
156  *
157  * @{
158  */
159 
160 #ifndef _MEMIF_H_
161 typedef enum
162 {
167 #endif /* _MEMIF_H_ */
168 
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
180 */
181 typedef struct
182 {
183  uint8_t *socket_filename; /*!< default = /run/vpp/memif.sock */
184  uint8_t secret[24]; /*!< optional (interface authentication) */
185 
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) */
190  uint8_t is_master;
191 
192  uint32_t interface_id;
193  uint8_t interface_name[32];
196 
197 /*! memif receive mode */
198 typedef enum
199 {
200  MEMIF_RX_MODE_INTERRUPT = 0, /*!< interrupt mode */
201  MEMIF_RX_MODE_POLLING /*!< polling mode */
203 
204 /** \brief Memif buffer
205  @param desc_index - ring descriptor index
206  @param ring - pointer to ring containing descriptor for this buffer
207  @param len - available length
208  @param flags - memif buffer flags
209  @param data - pointer to shared memory data
210 */
211 typedef struct
212 {
213  uint16_t desc_index;
214  void *ring;
215  uint32_t len;
216 /** next buffer present (chained buffers) */
217 #define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
218 /** states that buffer is from rx ring */
219 #define MEMIF_BUFFER_FLAG_RX (1 << 1)
220  uint8_t flags;
221  void *data;
223 /** @} */
224 
225 /**
226  * @defgroup MEMIF_DETAILS Memif details structs
227  * @ingroup libmemif
228  *
229  * @{
230  */
231 
232 /** \brief Memif queue details
233  @param qid - queue id
234  @param ring_size - size of ring buffer in sharem memory
235  @param flags - ring flags
236  @param head - ring head pointer
237  @param tail - ring tail pointer
238  @param buffer_size - buffer size on sharem memory
239 */
240 typedef struct
241 {
242  uint8_t qid;
243  uint32_t ring_size;
244 /** if set queue is in polling mode, else in interrupt mode */
245 #define MEMIF_QUEUE_FLAG_POLLING 1
246  uint16_t flags;
247  uint16_t head;
248  uint16_t tail;
249  uint16_t buffer_size;
251 
252 /** \brief Memif details
253  @param if_name - interface name
254  @param inst_name - application name
255  @param remote_if_name - peer interface name
256  @param remote_inst_name - peer application name
257  @param id - connection id
258  @param secret - secret
259  @param role - 0 = master, 1 = slave
260  @param mode - 0 = ethernet, 1 = ip , 2 = punt/inject
261  @param socket_filename = socket filename
262  @param rx_queues_num - number of receive queues
263  @param tx_queues_num - number of transmit queues
264  @param rx_queues - struct containing receive queue details
265  @param tx_queues - struct containing transmit queue details
266  @param link_up_down - 1 = up (connected), 2 = down (disconnected)
267 */
268 typedef struct
269 {
270  uint8_t *if_name;
271  uint8_t *inst_name;
272  uint8_t *remote_if_name;
274 
275  uint32_t id;
276  uint8_t *secret; /* optional */
277  uint8_t role; /* 0 = master, 1 = slave */
278  uint8_t mode; /* 0 = ethernet, 1 = ip, 2 = punt/inject */
279  uint8_t *socket_filename;
280  uint8_t rx_queues_num;
281  uint8_t tx_queues_num;
284 
285  uint8_t link_up_down; /* 1 = up, 0 = down */
287 /** @} */
288 
289 /**
290  * @defgroup API_CALLS Api calls
291  * @ingroup libmemif
292  *
293  * @{
294  */
295 
296 /** \brief Memif get version
297 
298  \return ((MEMIF_VERSION_MAJOR << 8) | MEMIF_VERSION_MINOR)
299 */
300 uint16_t memif_get_version ();
301 
302 /** \biref Memif get queue event file descriptor
303  @param conn - memif connection handle
304  @param qid - queue id
305  @param[out] fd - returns event file descriptor
306 
307  \return memif_err_t
308 */
309 
310 int memif_get_queue_efd (memif_conn_handle_t conn, uint16_t qid, int *fd);
311 
312 /** \brief Memif set rx mode
313  @param conn - memif connection handle
314  @param rx_mode - receive mode
315  @param qid - queue id
316 
317  \return memif_err_t
318 */
320  uint16_t qid);
321 
322 /** \brief Memif strerror
323  @param err_code - error code
324 
325  Converts error code to error message.
326 
327  \return Error string
328 */
329 char *memif_strerror (int err_code);
330 
331 /** \brief Memif get details
332  @param conn - memif conenction handle
333  @param md - pointer to memif details struct
334  @param buf - buffer containing details strings
335  @param buflen - length of buffer
336 
337  \return memif_err_t
338 */
340  char *buf, ssize_t buflen);
341 
342 /** \brief Memif initialization
343  @param on_control_fd_update - if control fd updates inform user to watch new fd
344  @param app_name - application name (will be truncated to 32 chars)
345  @param memif_alloc - cutom memory allocator, NULL = default
346  @param memif_free - custom memory free, NULL = default
347 
348  if param on_control_fd_update is set to NULL,
349  libmemif will handle file descriptor event polling
350  if a valid callback is set, file descriptor event polling needs to be done by
351  user application, all file descriptors and event types will be passed in
352  this callback to user application
353 
354  Initialize internal libmemif structures. Create timerfd (used to periodically request connection by
355  disconnected memifs in slave mode, with no additional API call). This fd is passed to user with memif_control_fd_update_t
356  timer is inactive at this state. It activates with if there is at least one memif in slave mode.
357 
358  \return memif_err_t
359 */
360 int memif_init (memif_control_fd_update_t * on_control_fd_update,
361  char *app_name, memif_alloc_t * memif_alloc,
362  memif_free_t * memif_free);
363 
364 /** \brief Memif cleanup
365 
366  Free libmemif internal allocations.
367 
368  \return 0
369 */
370 int memif_cleanup ();
371 
372 /** \brief Memory interface create function
373  @param conn - connection handle for user app
374  @param args - memory interface connection arguments
375  @param on_connect - inform user about connected status
376  @param on_disconnect - inform user about disconnected status
377  @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
378  @param private_ctx - private contex passed back to user with callback
379 
380  Creates memory interface.
381 
382  SLAVE-MODE -
383  Start timer that will send events to timerfd. If this fd is passed to memif_control_fd_handler
384  every disconnected memif in slave mode will send connection request.
385  On success new fd is passed to user with memif_control_fd_update_t.
386 
387  MASTER-MODE -
388  Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
389  If this fd is passed to memif_control_fd_handler accept will be called and
390  new fd will be passed to user with memif_control_fd_update_t.
391 
392 
393  \return memif_err_t
394 */
398  memif_interrupt_t * on_interrupt, void *private_ctx);
399 
400 /** \brief Memif control file descriptor handler
401  @param fd - file descriptor on which the event occured
402  @param events - event type(s) that occured
403 
404  If event occures on any control fd, call memif_control_fd_handler.
405  Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
406 
407  FD-TYPE -
408  TIMERFD -
409  Every disconnected memif in slave mode will request connection.
410  LISTENER or CONTROL -
411  Handle socket messaging (internal connection establishment).
412  INTERRUPT -
413  Call on_interrupt callback (if set).
414 
415  \return memif_err_t
416 
417 */
418 int memif_control_fd_handler (int fd, uint8_t events);
419 
420 /** \brief Memif delete
421  @param conn - pointer to memif connection handle
422 
423 
424  disconnect session (free queues and regions, close file descriptors, unmap shared memory)
425  set connection handle to NULL, to avoid possible double free
426 
427  \return memif_err_t
428 */
429 int memif_delete (memif_conn_handle_t * conn);
430 
431 /** \brief Memif buffer enq tx
432  @param conn - memif conenction handle
433  @param qid - number indentifying queue
434  @param bufs - memif buffers
435  @param count - number of memif buffers to enque
436  @param count_out - returns number of allocated buffers
437 
438  Slave is producer of buffers.
439  If connection handle points to master returns MEMIF_ERR_INVAL_ARG.
440 
441  \return memif_err_t
442 */
443 int memif_buffer_enq_tx (memif_conn_handle_t conn, uint16_t qid,
444  memif_buffer_t * bufs, uint16_t count,
445  uint16_t * count_out);
446 
447 /** \brief Memif buffer alloc
448  @param conn - memif conenction handle
449  @param qid - number indentifying queue
450  @param bufs - memif buffers
451  @param count - number of memif buffers to allocate
452  @param count_out - returns number of allocated buffers
453  @param size - buffer size, may return chained buffers if size > buffer_size
454 
455  \return memif_err_t
456 */
457 int memif_buffer_alloc (memif_conn_handle_t conn, uint16_t qid,
458  memif_buffer_t * bufs, uint16_t count,
459  uint16_t * count_out, uint16_t size);
460 
461 /** \brief Memif refill ring
462  @param conn - memif conenction handle
463  @param qid - number indentifying queue
464  @param count - number of buffers to be placed on ring
465  @param headroom - offset the buffer by headroom
466 
467  \return memif_err_t
468 */
469 int memif_refill_queue (memif_conn_handle_t conn, uint16_t qid,
470  uint16_t count, uint16_t headroom);
471 
472 /** \brief Memif transmit buffer burst
473  @param conn - memif conenction handle
474  @param qid - number indentifying queue
475  @param bufs - memif buffers
476  @param count - number of memif buffers to transmit
477  @param tx - returns number of transmitted buffers
478 
479  \return memif_err_t
480 */
481 int memif_tx_burst (memif_conn_handle_t conn, uint16_t qid,
482  memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
483 
484 /** \brief Memif receive buffer burst
485  @param conn - memif conenction handle
486  @param qid - number indentifying queue
487  @param bufs - memif buffers
488  @param count - number of memif buffers to receive
489  @param rx - returns number of received buffers
490 
491  \return memif_err_t
492 */
493 int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
494  memif_buffer_t * bufs, uint16_t count, uint16_t * rx);
495 
496 /** \brief Memif poll event
497  @param timeout - timeout in seconds
498 
499  Passive event polling -
500  timeout = 0 - dont wait for event, check event queue if there is an event and return.
501  timeout = -1 - wait until event
502 
503  \return memif_err_t
504 */
505 int memif_poll_event (int timeout);
506 
507 /** \brief Send signal to stop concurrently running memif_poll_event().
508 
509  The function, however, does not wait for memif_poll_event() to stop.
510  memif_poll_event() may still return simply because an event has occured
511  or the timeout has elapsed, but if called repeatedly in an infinite loop,
512  a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
513  in the shortest possible time.
514  This feature was not available in the first release.
515  Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
516 
517  \return memif_err_t
518 */
519 #define MEMIF_HAVE_CANCEL_POLL_EVENT 1
521 /** @} */
522 
523 #endif /* _LIBMEMIF_H_ */
uint8_t * inst_name
Definition: libmemif.h:271
uint8_t * secret
Definition: libmemif.h:276
int on_disconnect(memif_conn_handle_t conn, void *private_ctx)
Definition: main.c:186
void * ring
Definition: libmemif.h:214
uint8_t num_m2s_rings
Definition: libmemif.h:187
uint16_t buffer_size
Definition: libmemif.h:188
memif_interface_mode_t
Definition: memif.h:53
uint32_t interface_id
Definition: libmemif.h:192
int( memif_control_fd_update_t)(int fd, uint8_t events)
Memif control file descriptor update (callback function)
Definition: libmemif.h:130
uint16_t desc_index
Definition: libmemif.h:213
uint8_t * remote_inst_name
Definition: libmemif.h:273
int memif_refill_queue(memif_conn_handle_t conn, uint16_t qid, uint16_t count, uint16_t headroom)
Memif refill ring.
Definition: main.c:1659
int on_connect(memif_conn_handle_t conn, void *private_ctx)
Definition: main.c:177
uint8_t num_s2m_rings
Definition: libmemif.h:186
uint32_t len
Definition: libmemif.h:215
int memif_get_details(memif_conn_handle_t conn, memif_details_t *md, char *buf, ssize_t buflen)
Memif get details.
Definition: main.c:1866
uint8_t mode
Definition: libmemif.h:278
uint8_t link_up_down
Definition: libmemif.h:285
char * memif_strerror(int err_code)
Memif strerror.
Definition: main.c:157
uword size
void * data
Definition: libmemif.h:221
uint16_t buffer_size
Definition: libmemif.h:249
uint8_t * socket_filename
Definition: libmemif.h:279
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:577
int( memif_interrupt_t)(memif_conn_handle_t conn, void *private_ctx, uint16_t qid)
Memif interrupt occured (callback function)
Definition: libmemif.h:149
int( memif_connection_update_t)(memif_conn_handle_t conn, void *private_ctx)
Memif connection status update (callback function)
Definition: libmemif.h:139
uint8_t is_master
Definition: libmemif.h:190
uint8_t rx_queues_num
Definition: libmemif.h:280
int memif_init(memif_control_fd_update_t *on_control_fd_update, char *app_name, memif_alloc_t *memif_alloc, memif_free_t *memif_free)
Memif initialization.
Definition: main.c:429
int memif_get_queue_efd(memif_conn_handle_t conn, uint16_t qid, int *fd)
Memif get queue event file descriptor
Definition: main.c:1993
int memif_buffer_enq_tx(memif_conn_handle_t conn, uint16_t qid, memif_buffer_t *bufs, uint16_t count, uint16_t *count_out)
Memif buffer enq tx.
Definition: main.c:1454
void( memif_free_t)(void *ptr)
Memif allocator free.
Definition: libmemif.h:114
uint8_t flags
Definition: libmemif.h:220
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:1714
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:1533
int memif_poll_event(int timeout)
Memif poll event.
Definition: main.c:1009
memif_queue_details_t * rx_queues
Definition: libmemif.h:282
uint8_t role
Definition: libmemif.h:277
int memif_cleanup()
Memif cleanup.
Definition: main.c:2013
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:595
uint8_t tx_queues_num
Definition: libmemif.h:281
size_t count
Definition: vapi.c:46
memif_err_t
Definition: libmemif.h:33
memif_interface_mode_t
Definition: libmemif.h:161
void * memif_conn_handle_t
Memif connection handle pointer of type void, pointing to internal structure.
Definition: libmemif.h:100
int memif_control_fd_handler(int fd, uint8_t events)
Memif control file descriptor handler.
Definition: main.c:859
uint8_t log2_ring_size
Definition: libmemif.h:189
uint32_t id
Definition: libmemif.h:275
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:1781
memif_rx_mode_t
Definition: libmemif.h:198
int memif_delete(memif_conn_handle_t *conn)
Memif delete.
Definition: main.c:1184
Memif queue details.
Definition: libmemif.h:240
int memif_cancel_poll_event()
Definition: main.c:1050
memif_queue_details_t * tx_queues
Definition: libmemif.h:283
uint8_t * if_name
Definition: libmemif.h:270
Memif buffer.
Definition: libmemif.h:211
uint16_t memif_get_version()
Memif get version.
Definition: main.c:174
Memif connection arguments.
Definition: libmemif.h:181
Memif details.
Definition: libmemif.h:268
uint8_t * remote_if_name
Definition: libmemif.h:272
uint8_t * socket_filename
Definition: libmemif.h:183
void *( memif_alloc_t)(size_t size)
Memif allocator alloc.
Definition: libmemif.h:107