X-Git-Url: https://git.ti.com/gitweb?p=keystone-rtos%2Fnetapi.git;a=blobdiff_plain;f=ti%2Fruntime%2Fnetapi%2Fpktio.h;h=7fcd8ef2005af43a986d9621e291f9ea1068191f;hp=bc1d87472cb46fb98f6caeb1767cfb7957630ce0;hb=ba05e3b2c1425b7b1bd6a86caead6985afc1f57a;hpb=e4381b93edaf944193938a1504b2ce71fd293324;ds=sidebyside

diff --git a/ti/runtime/netapi/pktio.h b/ti/runtime/netapi/pktio.h
index bc1d874..7fcd8ef 100755
--- a/ti/runtime/netapi/pktio.h
+++ b/ti/runtime/netapi/pktio.h
@@ -1,45 +1,52 @@
-/*********************************
- *FILE:  pktio.h
- *PURPOSE:  pktio library header
- **************************************************************
- * @file  pktio.h
- * 
- * @bried DESCRIPTION:  pktio module  main header file for user space transport
- *               library
- * 
- * REVISION HISTORY:  rev 0.0.1 
+/******************************************************************************
+ * FILE PURPOSE:  Top level interface file for NWAL Module
+ ******************************************************************************
+ * FILE NAME:   pktio.h
+ *
+ * DESCRIPTION: netapi PKTIO module header file
+ *
+ * REVISION HISTORY:
  *
  *  Copyright (c) Texas Instruments Incorporated 2010-2011
- * 
- *  Redistribution and use in source and binary forms, with or without 
- *  modification, are permitted provided that the following conditions 
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions
  *  are met:
  *
- *    Redistributions of source code must retain the above copyright 
+ *    Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  *
  *    Redistributions in binary form must reproduce the above copyright
- *    notice, this list of conditions and the following disclaimer in the 
- *    documentation and/or other materials provided with the   
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the
  *    distribution.
  *
  *    Neither the name of Texas Instruments Incorporated nor the names of
  *    its contributors may be used to endorse or promote products derived
  *    from this software without specific prior written permission.
  *
- *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
- *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
- *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
- *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
+ *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
- *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+ *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+/* ============================================================= */
+
+/**
+ *   @file pktio.h
+ *   @brief pktio module main header file for user space transport library
+ */
+
+
 
- ********************************/
 #ifndef __PKTIO__H
 #define __PKTIO__H
 #include "netapi.h"
@@ -58,23 +65,30 @@
 #define PKTIO_MAX_NAME 19  
 
 /*--------------------data structures----------------*/
+
+
+/**
+ *  @ingroup netapi_structures
+ *  @brief PKTIO meta data information .
+ *
+ *  @details PKTIO meta data information TBD
+ */
 typedef struct PKTIO_METADATA_Tag
 {
   int flags1;
 #define PKTIO_META_RX 0x01
 #define PKTIO_META_TX 0x02
-#define PKTIO_META_SB_RX 0x4  //SB crypto rx 
-#define PKTIO_META_SB_TX 0x8  //SB crypto tx
+#define PKTIO_META_SB_RX 0x4  /**< SB crypto rx */
+#define PKTIO_META_SB_TX 0x8  /** <SB crypto tx */
 #define PKTIO_META_APP_DEF 0x80000000
-  union
-  {
-	nwalRxPktInfo_t * rx_meta;
-        nwalTxPktInfo_t * tx_meta;
-        nwalDmRxPayloadInfo_t * rx_sb_meta;
-        nwalDmTxPayloadInfo_t * tx_sb_meta;
-  } u;
-  void * sa_handle; //valid for PKTIO_META_TX with IPSEC inflow  or PKTIO_PKTIO_META_SB_TX . 
-                    // MUST BE nwal_HANDLE_INVALID otherwise
+    union
+    {
+        nwalRxPktInfo_t * rx_meta;  /**< NWAL Packet meta data information for incoming packet */
+        nwalTxPktInfo_t * tx_meta;  /**< NWAL Packet meta data information for outgoing packet */
+        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;
+    void * sa_handle; /**<valid for PKTIO_META_TX with IPSEC inflow  or PKTIO_PKTIO_META_SB_TX MUST BE nwal_HANDLE_INVALID otherwise */
 } PKTIO_METADATA_T;
 
 /* the callback function */
@@ -99,6 +113,14 @@ typedef int (*PKTIO_POLL)(struct PKTIO_HANDLE_tag * channel,PKTIO_POLL_T * p_pol
 
 /** channel configuration */
 #define PKTIO_NA 0
+
+
+/**
+ *  @ingroup netapi_structures
+ *  @brief PKTIO configuration information .
+ *
+ *  @details PKTIO configuration information 
+ */
 typedef struct PKTIO_CFG_Tag
 {
 #define PKTIO_R 0x1
@@ -124,27 +146,35 @@ struct NETAPI_tag;
 
 /* a pktio channel .. */
 
+
+
+/**
+ *  @ingroup netapi_structures
+ *  @brief PKTIO handle structure definition.
+ *
+ *  @details PKTIO handle strucutre which is returned from call to @ref pktio_create
+ */
 typedef struct PKTIO_HANDLE_Tag
 {
 #define PKTIO_INUSE 0xfeedfeed
-	int inuse;
-	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
-        struct NETAPI_tag * back;  /* back handle */
-	void * nwalInstanceHandle;      /* save here for conveninece */
-        PKTIO_CB cb;      /* callback for channel */
-        PKTIO_CFG_T cfg; /* configuration */
-	Qmss_QueueHnd q;  /* the associated queue handle */
-	Qmss_Queue qInfo;        /*   and its qm#/q# */
-	int max_n;        /* max # of pkts to read in one poll */
-	void * cookie;    /* app specific */
-        PKTIO_SEND _send;  /* pktio type specific send function */
-        PKTIO_POLL _poll;  /* pktio type specific POLL function */
-        char name[PKTIO_MAX_NAME+1];
+    int inuse;
+    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 */
+    struct NETAPI_tag * back;       /**< back handle */
+    void * nwalInstanceHandle;      /**<save here for conveninece */
+    PKTIO_CB cb;                    /**< callback for channel */
+    PKTIO_CFG_T cfg;            /**<configuration */
+    Qmss_QueueHnd q;        /**<the associated queue handle */
+    Qmss_Queue qInfo;       /**<and its qm#/q# */
+    int max_n;                      /**<max # of pkts to read in one poll */
+    void * cookie;              /**<app specific */
+    PKTIO_SEND _send;   /**<pktio type specific send function */
+    PKTIO_POLL _poll;       /**<pktio type specific POLL function */
+    char name[PKTIO_MAX_NAME+1];
 }  PKTIO_HANDLE_T;
 
 
@@ -163,8 +193,9 @@ typedef struct PKTIO_CONTROL_Tag
 /*-------------------------API-----------------------*/
 /*---------------------------------------------------*/
 
-/*
-*  @brief  API creates a NETAPI channel 
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API creates a NETAPI PKTIO channel 
  *
  *  @details This assigns global resources to a NETAPI pktio channel.
  *   Once created, the channel can be used to send and/or receive
@@ -186,8 +217,9 @@ PKTIO_HANDLE_T * pktio_create(NETAPI_T netapi_handle, /* netapi instance */
                                PKTIO_CFG_T * p_cfg,  /* ptr to config*/
                                int * err);
 
-/*
-*  @brief  API opens an existing  NETAPI channel
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API opens an existing  NETAPI PKTIO channel
  *
  *  @details This opens an NETAPI pktio channel for use. The channel
  *  must have already been created via @ref pktio_create or may have
@@ -222,8 +254,9 @@ void pktio_control(PKTIO_HANDLE_T * channel, //handle from open or create
 void pktio_close(PKTIO_HANDLE_T * channel, int * err);
 void pktio_delete(PKTIO_HANDLE_T * channel, int * err);
 
-/*
-*  @brief  API sends data to a pktio channel 
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API sends data to a NETAPI PKTIO channel 
  *
  *  @details This sends a @ref Ti_Pkt and associated meta data, 
  *  @ref PKTIO_METADATA_T to a channel. The channel
@@ -245,8 +278,9 @@ static inline int  pktio_send(PKTIO_HANDLE_T * channel, /* the channel */
    return channel->_send((struct PKTIO_HANDLE_tag *)channel, pkt, m, err);
 }
 
-/*
-*  @brief  API sends data to a pktio channel
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API sends data to a NETAPI PKTIO channel
  *
  *  @details This sends an array of @ref Ti_Pkt and associated meta data,
  *  @ref PKTIO_METADATA_T to a channel. The channel
@@ -271,8 +305,9 @@ int pktio_sendMulti(PKTIO_HANDLE_T *channel, /* the channel handle */
 /************* polling **************/
 /***********************************/
 
-/*
-*  @brief  API polls a pkto channel for received packets 
+/**
+ *  @ingroup netapi_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
  *  passed to the @ref  PKTIO_CB registered when the channel was
@@ -293,8 +328,9 @@ static inline int pktio_poll(PKTIO_HANDLE_T * handle,   //handle to pktio
 	return handle->_poll((struct PKTIO_HANDLE_tag *) handle, p_poll_cfg, err);
 }
 
-/*
-*  @brief  API polls all pkto channels associarted with @ref NETAPI_T instance
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API polls all NETAPI PKTIO channels associarted with @ref NETAPI_T instance
  *         for received packets
  *
  *  @details This api polls all pktio channels attached to an instance.
@@ -326,8 +362,11 @@ int pktio_pollAll(NETAPI_T handle, PKTIO_POLL_T * p_poll_cfg, int *err);
 #include "ti/drv/pa/pasahost.h"
 
 
-//return default packet queue to poll for netcp RX
-//these are expensive calls, so call once and save
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API returns default packet queue to poll for netcp RX
+ *  @note: these are expensive calls, so call once and save
+ */
 static inline Qmss_QueueHnd PKTIO_GET_DEFAULT_NETCP_Q(PKTIO_HANDLE_T *h)
 {
 nwalGlobCxtInfo_t Info;
@@ -335,8 +374,12 @@ nwal_getGlobCxtInfo(h->nwalInstanceHandle,&Info);
 return Info.rxDefPktQ;
 }
 
-//return L4Queue to poll for netcp RX (L4 classifier queue)
-//these are expensive calls, so call once and save
+
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API returns L4Queue to poll for netcp RX (L4 classifier queue).
+ *  @note: these are expensive calls, so call once and save
+ */
 static inline Qmss_QueueHnd PKTIO_GET_DEFAULT_NETCP_L4Q(PKTIO_HANDLE_T *h)
 {
 nwalLocCxtInfo_t Info;
@@ -345,18 +388,28 @@ return Info.rxL4PktQ;
 }
 
 
-
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API to perform descriptor push to QMSS Queue
+ */
 static inline void PKTIO_QMSS_QUEUE_PUSH_DESC_SIZE_RAW(Qmss_QueueHnd hnd, void *descAddr, uint32_t descSize)
 {
     return(Qmss_queuePushDescSizeRaw(hnd,descAddr,descSize));
 }
 
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API to perform descriptor pop from QMSS Queue
+ */
 static inline void* PKTIO_QMSS_QUEUE_POP_RAW(Qmss_QueueHnd hnd)
 {
     return(Qmss_queuePopRaw(hnd));
 }
 
-//Return NWAL Global Instance
+/**
+ *  @ingroup netapi_pktio_functions
+ *  @brief  API to retrieve NWAL global instance handle.
+ */
 static inline nwal_Inst PKTIO_GET_NWAL_INSTANCE(PKTIO_HANDLE_T *h)
 {
 return h->nwalInstanceHandle;