index bc1d87472cb46fb98f6caeb1767cfb7957630ce0..7fcd8ef2005af43a986d9621e291f9ea1068191f 100755 (executable)
-/*********************************
- *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"
#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
/* 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;
/*-------------------------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
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
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
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
/************* 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
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.
#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;
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;
}
-
+/**
+ * @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;