Additional doxygen updates
[keystone-rtos/netapi.git] / ti / runtime / netapi / pktio.h
index 96ae76e45555b66a30e34e563aeb84fe924f84a2..0ddf435b40db006967b7649e4eaf8452cf7ffa13 100755 (executable)
@@ -43,7 +43,7 @@
 /**
  *   @file pktio.h
  *   @brief pktio module main header file for user space transport library
- *   @detailts:  pktio provides an abstraction to H/W queues that are used to transmit and receive packets, IPC messages, etc.  Pktio channels can be created by user but there are also several canned channels available  for NETCP transmit, receive, SA sideband crypto transmit and receive 
+ *   @details:  pktio provides an abstraction to H/W queues that are used to transmit and receive packets, IPC messages, etc.  Pktio channels can be created by user but there are also several canned channels available  for NETCP transmit, receive, SA sideband crypto transmit and receive 
  */
 
 
 
 /**
  * @def PKTIO_NOMEM
+ * @ingroup pktio_constants
  *      This define is used to indicate out of memory to user space application 
  */
 #define PKTIO_NOMEM  NETAPI_ERR_NOMEM
 
 /**
  * @def NETCP_TX
+ * @ingroup pktio_constants
  *      This defines the pktio NETCP transmit  channel name
  */
 #define NETCP_TX "NETCP_TX"
 
 /**
  * @def NETCP_RX
+ * @ingroup pktio_constants
  *      This defines the pktio NETCP receive channel name
  */
 #define NETCP_RX "NETCP_RX"
 
 /**
  * @def NETCP_SB_RX
+ * @ingroup pktio_constants
  *      This defines the pktio NETCP-SA receive SIDEBAND channel name
  */
 #define NETCP_SB_RX "NETCP_SB_RX"
 
 /**
  * @def NETCP_SB_TX
+ * @ingroup pktio_constants
  *      This defines the pktio NETCP-SA transmit SIDEBAND channel name
  */
 #define NETCP_SB_TX "NETCP_SB_TX"
 
 /**
  * @def PKTIO_MAX_NAME
+ * @ingroup pktio_constants
  *      This defines the maximum length of a pktio channel name
  */
 #define PKTIO_MAX_NAME 19  
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup pktio_structures
  *  @brief PKTIO meta data information .
  *
  *  @details PKTIO meta data information TBD
  */
 typedef struct PKTIO_METADATA_Tag
 {
-    int flags1; /**< Meta Data flag configuration */
+/**
+ * Flags for PKTIO Meta Data configuration
+ * <br>
+ * valid flag1 parameters are as follows:
+ *      @ref PKTIO_META_RX , @ref PKTIO_META_TX, @ref PKTIO_META_SB_RX, @ref PKTIO_META_SB_TX
+ */
+    int flags1; 
+
 /**
  * @def PKTIO_META_RX
+ * @ingroup pktio_constants
  *      This defines the pktio NETCP receive INFLOW channel
  */
 #define PKTIO_META_RX 0x01
 
 /**
  * @def PKTIO_META_TX
+ * @ingroup pktio_constants
  *      This defines the pktio NETCP transmit INFLOW channel
  */
 #define PKTIO_META_TX 0x02
 
 /**
  * @def PKTIO_META_SB_RX
+ * @ingroup pktio_constants
  *      This defines the pktio NETCP SIDEBAND channel channel
  */
 #define PKTIO_META_SB_RX 0x4  /**< SB crypto rx */
 
 /**
  * @def PKTIO_META_SB_TX
+ * @ingroup pktio_constants
  *      This defines the pktio NETCP transmit SIDEBAND channel
  */
 #define PKTIO_META_SB_TX 0x8  /** <SB crypto tx */
 
 /**
  * @def PKTIO_META_APP_DEF
- *      TBD
+ * @ingroup pktio_constants
+ *      TBD- is this part of flags2?
  */
 #define PKTIO_META_APP_DEF 0x80000000
+
+/**
+ * @brief NWAL Packet meta data information
+ */
     union
     {
         nwalRxPktInfo_t * rx_meta;          /**< NWAL Packet meta data information for incoming packet */
@@ -139,17 +161,21 @@ typedef struct PKTIO_METADATA_Tag
         nwalDmRxPayloadInfo_t * rx_sb_meta; /**<NWAL Data mode meta data payload information from NetCP */
         nwalDmTxPayloadInfo_t * tx_sb_meta; /**< NWAL Data Mode Payload information for packet to SA */
     } u;                                    /**< union NWAL Packet meta data information  */
-    void * sa_handle; /**<valid for PKTIO_META_TX with IPSEC inflow or PKTIO_PKTIO_META_SB_TX MUST BE nwal_HANDLE_INVALID otherwise */
+
+/**
+ * @brief valid for PKTIO_META_TX with IPSEC inflow or PKTIO_PKTIO_META_SB_TX MUST BE nwal_HANDLE_INVALID otherwise
+ */
+    void * sa_handle;
 } PKTIO_METADATA_T;
 
 /* the callback function */
 struct PKTIO_HANDLE_tag;
 
 /**
- *  @ingroup netapi_structures
- *  @brief PKTIO polling control struct FUTURE
+ *  @ingroup pktio_structures
+ *  @brief PKTIO polling control struct FUTURE- TBD
  *
- *  @details PKTIO polling control struct FUTURE
+ *  @details PKTIO polling control struct FUTURE- TBD
  */
 typedef struct PKTIO_POLL_Tag
 {
@@ -158,12 +184,12 @@ typedef struct PKTIO_POLL_Tag
 
 /**
  * @def PKTIO_MAX_RECV
+ * @ingroup pktio_constants
  *      This defines the maximum number of packets to receive in one pktio poll, @ref TUNE_NETAPI_MAX_BURST_RCV
  */
 #define PKTIO_MAX_RECV  (TUNE_NETAPI_MAX_BURST_RCV)
 
 
-
 /**
  *  @ingroup netapi_cb_functions
  *  @brief PKTIO_CB   Callback function to be issued on packet receive
@@ -184,7 +210,7 @@ typedef void (*PKTIO_CB)(struct PKTIO_HANDLE_tag * channel,
                          uint64_t ts);
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief PKTIO_SEND   PKTIO specific send function
  * 
  *  @details The application calls this PKTIO specific send function to transmit packet
@@ -202,7 +228,7 @@ typedef int (*PKTIO_SEND)(struct PKTIO_HANDLE_tag * channel,
 
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief PKTIO_POLL   PKTIO specific poll function
  * 
  *  @details The application calls this PKTIO specific POLL function
@@ -222,62 +248,84 @@ typedef int (*PKTIO_POLL)(struct PKTIO_HANDLE_tag * channel,
 #define PKTIO_NA 0
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup pktio_structures
  *  @brief PKTIO configuration information
  *
  *  @details PKTIO :q information
  */
 typedef struct PKTIO_CFG_Tag
 {
+/**
+ * Flags for PKTIO channel configuration
+ * <br>
+ * The following are flags used to configure the pktio channel:
+ *      @ref PKTIO_R , @ref PKTIO_W, @ref PKTIO_RW
+ */
+    int flags1; 
+
 /**
  * @def PKTIO_R
+ * @ingroup pktio_constants
  *      This defines the pktio channel as type read TBD
  */
 #define PKTIO_R 0x1
 
 /**
  * @def PKTIO_W
+ * @ingroup pktio_constants
  *      This defines the pktio channel as type write TBD
  */
 #define PKTIO_W 0x2
 
 /**
  * @def PKTIO_RW
+ * @ingroup pktio_constants
  *      This defines the pktio channel as type read/write TBD
  */
 #define PKTIO_RW (PKTIO_R | PKTIO_W)
 
-int flags1; /**< Flags for PKTIO channel configuration */
+
 
 /**
- * @def PKTIO_LOCAL
- *      This defines the pktio channel as type local TBD
+ * Additional flags  for PKTIO channel configuration
+ * <br>
+ * The following are flags used to configure the pktio channel:
+ *      @ref PKTIO_LOCAL , @ref PKTIO_GLOBAL, @ref PKTIO_RW
  */
-#define PKTIO_LOCAL  0x2
+int flags2; /**< Flags for PKTIO channel configuration */
 
 /**
  * @def PKTIO_GLOBAL
+ * @ingroup pktio_constants
  *      This defines the pktio channel as type global TBD
  */
 #define PKTIO_GLOBAL 0x1
 
+/**
+ * @def PKTIO_LOCAL
+ * @ingroup pktio_constants
+ *      This defines the pktio channel as type local TBD
+ */
+#define PKTIO_LOCAL  0x2
+
 /**
  * @def PKTIO_PKT
+ * @ingroup pktio_constants
  *      This defines the pktio channel is for NETCP
  */
 #define PKTIO_PKT    0x4
 
 /**
  * @def PKTIO_SB
+ * @ingroup pktio_constants
  *      This defines the pktio channel is for sideband crypto
  */
 #define PKTIO_SB     0x8
 
-int flags2; /**< Flags for PKTIO channel configuration */
-
 /**
  * @def PKTIO_Q_ANY
- *      This defines TBD 
+ * @ingroup pktio_constants
+ *      This defines the pktio IO queue number to be TBD 
  */
 #define PKTIO_Q_ANY -1
 
@@ -294,7 +342,7 @@ struct NETAPI_tag;
 
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup pktio_structures
  *  @brief PKTIO handle structure definition.
  *
  *  @details PKTIO handle strucutre which is returned from call to @ref pktio_create
@@ -303,19 +351,58 @@ typedef struct PKTIO_HANDLE_Tag
 {
 /**
  * @def PKTIO_INUSE
+ * @ingroup pktio_constants
  *      This defines is used to TBD
  */
 #define PKTIO_INUSE 0xfeedfeed
 
     int inuse;                      /**<true is pktio channel is in use TBD */
-    int use_nwal;                   /**<true if this is managed by nwal */
-#define  PKTIO_4_IPC 0              /**<For IPC */
-#define  PKTIO_4_ADJ_NWAL 1         /**<(RX)app queues managed by NWAL */
-#define  PKTIO_DEF_NWAL 2           /**<default NWAL RX/TX queues */
-#define  PKTIO_4_ADJ_SB 3           /**<(RX) crypto side band app defined */
-#define  PKTIO_DEF_SB 4             /**<crypto side band default */
+
+/**
+ * Set the "use_nwal" field to one of the defines listed below.
+ * <br>
+ * The following defines are used to populate the use_nwal field TBD:
+ *      @ref PKTIO_4_IPC , @ref PKTIO_4_ADJ_NWAL, @ref PKTIO_DEF_NWAL. @ref PKTIO_4_ADJ_SB., @ref PKTIO_DEF_SB
+ */
+    int use_nwal;                  
+
+/**
+ * @def PKTIO_4_IPC
+ * @ingroup pktio_constants
+ *      This define is for IPC TBD
+ */
+#define  PKTIO_4_IPC 0
+
+/**
+ * @def PKTIO_4_ADJ_NWAL
+ * @ingroup pktio_constants
+ *      This define is for (RX)app queues managed by NWAL
+ */
+#define  PKTIO_4_ADJ_NWAL 1
+
+/**
+ * @def PKTIO_DEF_NWAL
+ * @ingroup pktio_constants
+ *      This define is for default NWAL RX/TX queues
+ */
+#define  PKTIO_DEF_NWAL 2
+
+/**
+ * @def PKTIO_4_ADJ_SB
+ *      This define is for (RX) crypto side band app defined
+ * @ingroup pktio_constants
+ */
+#define  PKTIO_4_ADJ_SB 3
+
+/**
+ * @def PKTIO_DEF_SB
+ * @ingroup pktio_constants
+ *      This define is for crypto side band default
+ */
+#define  PKTIO_DEF_SB 4
+
     struct NETAPI_tag * back;       /**< back handle */
-    void * nwalInstanceHandle;      /**<save here for conveninece */
+    void * nwalInstanceHandle;      /**<save here for conveninece  TBD*/
     PKTIO_CB cb;                    /**< callback for channel */
     PKTIO_CFG_T cfg;                /**<configuration */
     Qmss_QueueHnd q;                /**<the associated queue handle */
@@ -329,7 +416,7 @@ typedef struct PKTIO_HANDLE_Tag
 
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup pktio_structures
  *  @brief PKTIO control TBD
  *
  *  @details PKTIO control RBD
@@ -355,7 +442,7 @@ typedef struct PKTIO_CONTROL_Tag
 
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief API creates a NETAPI PKTIO channel 
  *
  *  @details This assigns global resources to a NETAPI pktio channel.
@@ -379,7 +466,7 @@ PKTIO_HANDLE_T * pktio_create(NETAPI_T netapi_handle,
                                int * err);
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief API opens an existing  NETAPI PKTIO channel
  *
  *  @details This opens an NETAPI pktio channel for use. The channel
@@ -405,7 +492,7 @@ PKTIO_HANDLE_T * pktio_open(NETAPI_T netapi_handle,
                             int * err);
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief API controls an existing NETAPI PKTIO channel
  *
  *  @details This controls an opened pktio channel
@@ -425,7 +512,7 @@ void pktio_control(PKTIO_HANDLE_T * handle,
                     int *err);
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief API closes a PKTIO channel
  *
  *  @details This closes a PKTIO channel
@@ -439,7 +526,7 @@ void pktio_close(PKTIO_HANDLE_T * handle,
                  int * err);
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief API deletes a PKTIO channel
  *
  *  @details This deletes a PKTIO channel
@@ -453,7 +540,7 @@ void pktio_delete(PKTIO_HANDLE_T * handle,
                   int * err);
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief  API sends data to a NETAPI PKTIO channel 
  *
  *  @details This sends a Ti_Pkt and associated meta data, 
@@ -477,7 +564,7 @@ static inline int  pktio_send(PKTIO_HANDLE_T * handle,
 }
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief API sends data to a NETAPI PKTIO channel
  *
  *  @details This sends an array of Ti_Pkt and associated meta data,
@@ -500,7 +587,7 @@ int pktio_sendMulti(PKTIO_HANDLE_T *handle,
                     int * err);
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief  API polls a NETAPI PKTIO channel for received packets 
  *
  *  @details This api polls a pktio channel. Any pending data in the channel is
@@ -523,7 +610,7 @@ static inline int pktio_poll(PKTIO_HANDLE_T * handle,
 }
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief API polls all NETAPI PKTIO channels associarted with @ref NETAPI_T instance
  *         for received packets
  *
@@ -582,7 +669,7 @@ int pktio_pollAll(NETAPI_T handle,
 
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief  API returns default packet queue to poll for netcp RX
  *  @note: these are expensive calls, so call once and save
  */
@@ -595,7 +682,7 @@ static inline Qmss_QueueHnd PKTIO_GET_DEFAULT_NETCP_Q(PKTIO_HANDLE_T *h)
 
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief  API returns L4Queue to poll for netcp RX (L4 classifier queue).
  *  @note: these are expensive calls, so call once and save
  */
@@ -608,7 +695,7 @@ return Info.rxL4PktQ;
 
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief  API to perform descriptor push to QMSS Queue
  */
 static inline void PKTIO_QMSS_QUEUE_PUSH_DESC_SIZE_RAW(Qmss_QueueHnd hnd,
@@ -619,7 +706,7 @@ static inline void PKTIO_QMSS_QUEUE_PUSH_DESC_SIZE_RAW(Qmss_QueueHnd hnd,
 }
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief  API to perform descriptor pop from QMSS Queue
  */
 static inline void* PKTIO_QMSS_QUEUE_POP_RAW(Qmss_QueueHnd hnd)
@@ -628,7 +715,7 @@ static inline void* PKTIO_QMSS_QUEUE_POP_RAW(Qmss_QueueHnd hnd)
 }
 
 /**
- *  @ingroup netapi_pktio_functions
+ *  @ingroup pktio_functions
  *  @brief  API to retrieve NWAL global instance handle.
  */
 static inline nwal_Inst PKTIO_GET_NWAL_INSTANCE(PKTIO_HANDLE_T *h)