*/
/** @file
- * @defgroup libmemif
+ * @defgroup libmemif Example libmemif App
*/
#ifndef _LIBMEMIF_H_
MEMIF_ERR_MAXREG, /*!< max region limit reached */
MEMIF_ERR_MAXRING, /*!< max ring limit reached */
MEMIF_ERR_NO_INTFD, /*!< missing interrupt fd */
- MEMIF_ERR_DISCONNECT, /*!< disconenct received */
+ MEMIF_ERR_DISCONNECT, /*!< disconnect received */
MEMIF_ERR_DISCONNECTED, /*!< peer interface disconnected */
MEMIF_ERR_UNKNOWN_MSG, /*!< unknown message type */
MEMIF_ERR_POLL_CANCEL, /*!< memif_poll_event() was cancelled */
* @{
*/
-/** user needs to set events that occured on fd and pass them to memif_control_fd_handler */
+/** user needs to set events that occurred on fd and pass them to memif_control_fd_handler */
#define MEMIF_FD_EVENT_READ (1 << 0)
#define MEMIF_FD_EVENT_WRITE (1 << 1)
-/** inform libmemif that error occured on fd */
+/** inform libmemif that error occurred on fd */
#define MEMIF_FD_EVENT_ERROR (1 << 2)
/** if set, informs that fd is going to be closed (user may want to stop watching for events on this fd) */
#define MEMIF_FD_EVENT_DEL (1 << 3)
typedef int (memif_connection_update_t) (memif_conn_handle_t conn,
void *private_ctx);
-/** \brief Memif interrupt occured (callback function)
+/** \brief Memif interrupt occurred (callback function)
@param conn - memif connection handle
@param private_ctx - private context
- @param qid - queue id on which interrupt occured
+ @param qid - queue id on which interrupt occurred
Called when event is received on interrupt fd.
*/
@param gr - get external region addr callback
@param dr - delete external region callback
@param go - get external buffer offset callback (optional)
-*/
+
void memif_per_thread_register_external_region (memif_per_thread_main_handle_t
pt_main,
memif_add_external_region_t *
memif_get_external_buffer_offset_t
* go);
-/** @} */
+ @} */
/**
* @defgroup ARGS_N_BUFS Connection arguments and buffers
Custom database does not create a default socket
(see memif_per_thread_init).
Memif connection is stored in the same database as the socket.
- @param secret - otional parameter used as interface autenthication
+ @param secret - optional parameter used as interface authentication
@param num_s2m_rings - number of slave to master rings
@param num_m2s_rings - number of master to slave rings
@param buffer_size - size of buffer in shared memory
typedef struct
{
uint16_t desc_index;
- void *ring;
+ void *queue;
uint32_t len;
/** next buffer present (chained buffers) */
#define MEMIF_BUFFER_FLAG_NEXT (1 << 0)
-/** states that buffer is from rx ring */
-#define MEMIF_BUFFER_FLAG_RX (1 << 1)
uint8_t flags;
void *data;
} memif_buffer_t;
/** \brief Memif queue details
@param region - region index
@param qid - queue id
- @param ring_size - size of ring buffer in sharem memory
+ @param ring_size - size of ring buffer in shared memory
@param flags - ring flags
@param head - ring head pointer
@param tail - ring tail pointer
- @param buffer_size - buffer size on sharem memory
+ @param buffer_size - buffer size on shared memory
*/
typedef struct
{
*/
uint16_t memif_get_version ();
-/** \biref Memif get queue event file descriptor
+/** \brief Memif get queue event file descriptor
@param conn - memif connection handle
@param qid - queue id
@param[out] fd - returns event file descriptor
char *memif_strerror (int err_code);
/** \brief Memif get details
- @param conn - memif conenction handle
+ @param conn - memif connection handle
@param md - pointer to memif details struct
@param buf - buffer containing details strings
@param buflen - length of buffer
/** \brief Memif initialization
@param on_control_fd_update - if control fd updates inform user to watch new fd
@param app_name - application name (will be truncated to 32 chars)
- @param memif_alloc - cutom memory allocator, NULL = default
+ @param memif_alloc - custom memory allocator, NULL = default
@param memif_realloc - custom memory reallocation, NULL = default
@param memif_free - custom memory free, NULL = default
@param private_ctx - private context
@param on_control_fd_update - if control fd updates inform user to watch new fd
@param app_name - application name (will be truncated to 32 chars)
- @param memif_alloc - cutom memory allocator, NULL = default
+ @param memif_alloc - custom memory allocator, NULL = default
@param memif_realloc - custom memory reallocation, NULL = default
@param memif_free - custom memory free, NULL = default
@param on_connect - inform user about connected status
@param on_disconnect - inform user about disconnected status
@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
- @param private_ctx - private contex passed back to user with callback
+ @param private_ctx - private context passed back to user with callback
Creates memory interface.
On success new fd is passed to user with memif_control_fd_update_t.
MASTER-MODE -
- Create listener socket and pass fd to user with memif_cntrol_fd_update_t.
+ Create listener socket and pass fd to user with memif_control_fd_update_t.
If this fd is passed to memif_control_fd_handler accept will be called and
new fd will be passed to user with memif_control_fd_update_t.
memif_interrupt_t * on_interrupt, void *private_ctx);
/** \brief Memif control file descriptor handler
- @param fd - file descriptor on which the event occured
- @param events - event type(s) that occured
+ @param fd - file descriptor on which the event occurred
+ @param events - event type(s) that occurred
- If event occures on any control fd, call memif_control_fd_handler.
- Internal - lib will "identify" fd (timerfd, lsitener, control) and handle event accordingly.
+ If event occurs on any control fd, call memif_control_fd_handler.
+ Internal - lib will "identify" fd (timerfd, listener, control) and handle event accordingly.
FD-TYPE -
TIMERFD -
/** \brief Memif per thread control file descriptor handler
@param pt_main - per thread main handle
- @param fd - file descriptor on which the event occured
- @param events - event type(s) that occured
+ @param fd - file descriptor on which the event occurred
+ @param events - event type(s) that occurred
Per thread version of memif_control_fd_handler.
int memif_delete (memif_conn_handle_t * conn);
/** \brief Memif buffer enq tx
- @param conn - memif conenction handle
- @param qid - number indentifying queue
+ @param conn - memif connection handle
+ @param qid - number identifying queue
@param bufs - memif buffers
- @param count - number of memif buffers to enque
+ @param count - number of memif buffers to enqueue
@param count_out - returns number of allocated buffers
- Slave is producer of buffers.
+ Enqueue buffers to specified tx queue. Can only be used by slave.
+ Updates desc_index field for each memif buffer.
If connection handle points to master returns MEMIF_ERR_INVAL_ARG.
\return memif_err_t
memif_buffer_t * bufs, uint16_t count,
uint16_t * count_out);
+/** \brief Memif buffer enq tx at idx
+ @param conn - memif connection handle
+ @param buf_a - memif buffer
+ @param buf_b - memif buffer
+
+ Swap descriptors for provided buffers and update the buffers
+*/
+int memif_buffer_requeue (memif_conn_handle_t conn, memif_buffer_t *buf_a,
+ memif_buffer_t *buf_b);
+
/** \brief Memif buffer alloc
- @param conn - memif conenction handle
- @param qid - number indentifying queue
+ @param conn - memif connection handle
+ @param qid - number identifying queue
@param bufs - memif buffers
@param count - number of memif buffers to allocate
@param count_out - returns number of allocated buffers
memif_buffer_t * bufs, uint16_t count,
uint16_t * count_out, uint16_t size);
-/** \brief Memif refill ring
- @param conn - memif conenction handle
- @param qid - number indentifying queue
+/** \brief Memif set next free buffer
+ @param conn - memif connection handle
+ @param qid - number identifying queue
+ @param buf - next free buffer
+
+ Sets next free descriptor pointer for specified tx queue.
+ The next allocation will happen at this buffer.
+*/
+int memif_set_next_free_buffer (memif_conn_handle_t conn, uint16_t qid,
+ memif_buffer_t *buf);
+
+/** \brief Memif refill queue
+ @param conn - memif connection handle
+ @param qid - number identifying queue
@param count - number of buffers to be placed on ring
@param headroom - offset the buffer by headroom
uint16_t count, uint16_t headroom);
/** \brief Memif transmit buffer burst
- @param conn - memif conenction handle
- @param qid - number indentifying queue
+ @param conn - memif connection handle
+ @param qid - number identifying queue
@param bufs - memif buffers
@param count - number of memif buffers to transmit
@param tx - returns number of transmitted buffers
memif_buffer_t * bufs, uint16_t count, uint16_t * tx);
/** \brief Memif receive buffer burst
- @param conn - memif conenction handle
- @param qid - number indentifying queue
+ @param conn - memif connection handle
+ @param qid - number identifying queue
@param bufs - memif buffers
@param count - number of memif buffers to receive
@param rx - returns number of received buffers
+ Consume interrupt event for receive queue.
+ The event is not consumed, if memif_rx_burst fails.
+
\return memif_err_t
*/
int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
*/
int memif_poll_event (int timeout);
-/** \brief Memif poll event
+/** \brief Memif per thread poll event
@param pt_main - per thread main handle
@param timeout - timeout in seconds
/** \brief Send signal to stop concurrently running memif_poll_event().
The function, however, does not wait for memif_poll_event() to stop.
- memif_poll_event() may still return simply because an event has occured
+ memif_poll_event() may still return simply because an event has occurred
or the timeout has elapsed, but if called repeatedly in an infinite loop,
- a canceled memif_poll_event() is guaranted to return MEMIF_ERR_POLL_CANCEL
+ a canceled memif_poll_event() is guaranteed to return MEMIF_ERR_POLL_CANCEL
in the shortest possible time.
This feature was not available in the first release.
Use macro MEMIF_HAVE_CANCEL_POLL_EVENT to check if the feature is present.
The first time an interface is assigned a socket, its type is determined.
For master role it's 'listener', for slave role it's 'client'. Each interface
- requires socket of its respective type. Default socket is creted if no
+ requires socket of its respective type. Default socket is created if no
socket handle is passed to memif_create(). It's private context is NULL.
If all interfaces using this socket are deleted, the socket returns
to its default state.
@param filename - path to socket file
@param private_ctx - private context
- Per thread version of memif_create_sopcket.
+ Per thread version of memif_create_socket.
\return memif_err_t
*/
Return constant pointer to socket filename.
- \return cosnt char *
+ \return const char *
*/
const char *memif_get_socket_filename (memif_socket_handle_t sock);