libmemif: ubuntu 18.04 build fix

[vpp.git] / extras / libmemif / src / libmemif.h

diff --git a/extras/libmemif/src/libmemif.h b/extras/libmemif/src/libmemif.h
index 3732be6..a14a102 100644 (file)
--- a/extras/libmemif/src/libmemif.h
+++ b/extras/libmemif/src/libmemif.h
@@ -15,7 +15,9 @@
  *------------------------------------------------------------------
  */
 
-/** @file */
+/** @file
+ *  @defgroup libmemif
+ */
 
 #ifndef _LIBMEMIF_H_
 #define _LIBMEMIF_H_
@@ -72,11 +74,13 @@ typedef enum
   MEMIF_ERR_DISCONNECT,                /*!< disconenct received */
   MEMIF_ERR_DISCONNECTED,      /*!< peer interface disconnected */
   MEMIF_ERR_UNKNOWN_MSG,       /*!< unknown message type */
+  MEMIF_ERR_POLL_CANCEL,       /*!< memif_poll_event() was cancelled */
+  MEMIF_ERR_MAX_RING,          /*!< too large ring size */
 } memif_err_t;
 
 /**
  * @defgroup MEMIF_FD_EVENT Types of events that need to be watched for specific fd.
- *
+ * @ingroup libmemif
  * @{
  */
 
@@ -97,6 +101,7 @@ typedef enum
 typedef void *memif_conn_handle_t;
 /**
  * @defgroup CALLBACKS Callback functions definitions
+ * @ingroup libmemif
  *
  * @{
  */
@@ -133,6 +138,7 @@ typedef int (memif_interrupt_t) (memif_conn_handle_t conn, void *private_ctx,
 
 /**
  * @defgroup ARGS_N_BUFS Connection arguments and buffers
+ * @ingroup libmemif
  *
  * @{
  */
@@ -163,7 +169,7 @@ typedef struct
 
   memif_interface_id_t interface_id;
   uint8_t interface_name[32];
-  uint8_t instance_name[32];
+  uint8_t instance_name[32];   /*!< deprecated, will be removed in 2.0 */
   memif_interface_mode_t mode:8;
 } memif_conn_args_t;
 
@@ -191,6 +197,7 @@ typedef struct
 
 /**
  * @defgroup MEMIF_DETAILS Memif details structs
+ * @ingroup libmemif
  *
  * @{
  */
@@ -198,14 +205,21 @@ typedef struct
 /** \brief Memif queue details
     @param qid - queue id
     @param ring_size - size of ring buffer in sharem memory
+    @param flags - ring flags
+    @param head - ring head pointer
+    @param tail - ring tail pointer
     @param buffer_size - buffer size on sharem memory
 */
 typedef struct
 {
   uint8_t qid;
   uint32_t ring_size;
+/** if set queue is in polling mode, else in interrupt mode */
+#define MEMIF_QUEUE_FLAG_POLLING 1
+  uint16_t flags;
+  uint16_t head;
+  uint16_t tail;
   uint16_t buffer_size;
-  /* add ring information */
 } memif_queue_details_t;
 
 /** \brief Memif details
@@ -247,6 +261,7 @@ typedef struct
 
 /**
  * @defgroup API_CALLS Api calls
+ * @ingroup libmemif
  *
  * @{
  */
@@ -293,7 +308,7 @@ int memif_get_details (memif_conn_handle_t conn, memif_details_t * md,
 
 /** \brief Memif initialization
     @param on_control_fd_update - if control fd updates inform user to watch new fd
-    @param app_name - application name
+    @param app_name - application name (will be truncated to 32 chars)
 
     if param on_control_fd_update is set to NULL,
     libmemif will handle file descriptor event polling
@@ -383,12 +398,13 @@ int memif_delete (memif_conn_handle_t * conn);
     @param bufs - memif buffers
     @param count - number of memif buffers to allocate
     @param count_out - returns number of allocated buffers
+    @param size - minimal buffer size, 0 = standard buffer size
 
     \return memif_err_t
 */
 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 * count_out, uint16_t size);
 
 /** \brief Memif buffer free
     @param conn - memif conenction handle
@@ -437,6 +453,21 @@ int memif_rx_burst (memif_conn_handle_t conn, uint16_t qid,
     \return memif_err_t
 */
 int memif_poll_event (int timeout);
+
+/** \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
+    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
+    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.
+
+    \return memif_err_t
+*/
+#define MEMIF_HAVE_CANCEL_POLL_EVENT 1
+int memif_cancel_poll_event ();
 /** @} */
 
 #endif /* _LIBMEMIF_H_ */