Doxygen updates
authorTinku Mannan <tmannan@ti.com>
Fri, 28 Sep 2012 11:44:33 +0000 (07:44 -0400)
committerTinku Mannan <tmannan@ti.com>
Fri, 28 Sep 2012 11:44:33 +0000 (07:44 -0400)
ti/runtime/netapi/build/Makefile
ti/runtime/netapi/build/netapi_doxygen.cfg
ti/runtime/netapi/netapi.h
ti/runtime/netapi/netapi_sec.h
ti/runtime/netapi/netapi_tune.h
ti/runtime/netapi/netcp_cfg.h
ti/runtime/netapi/pktio.h

index 35f2b47d17d641d6e7c7b5e0e2dd371b356cd5a6..d3701f214365d1f9246ac31c424293e4bcff3e62 100755 (executable)
@@ -11,6 +11,8 @@ export ARMV7OBJDIR ?= ../obj
 # Set NETAPI INSTALL PATH to Transport SDK for default
 export NETAPI_INSTALL_PATH ?= $(TRANS_SDK_INSTALL_PATH)
 
+NETAPI_DOCS_DIR := $(NETAPI_INSTALL_PATH)/ti/runtime/netapi/docs
 #NETAPI dirs
 OBJEXT = o
 INTERNALLINKDEFS =
index 51f28176b81f8ee19edb2e16bae3ad2584fd02a5..c94f16569168ec612412ac7e7014a640b7985f8e 100755 (executable)
@@ -574,7 +574,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = ..
+INPUT                  = ../netapi.h ../netcp_cfg.h ../netapi_sec.h ../pktio.h ../netapi_tune.h ../netapi_sched.h
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
index 40e748671f818d883e97f259c794a36f748ff86b..485973868c7038d2423ddb381589262f154cacd3 100755 (executable)
@@ -1,44 +1,52 @@
-/**************************************************************
- * FILE PURPOSE :  -----------NETAPI-------------
- *         user space access to transport resources on SOC
- **************************************************************
- * @file netapi.h
- * 
- * @brief DESCRIPTION:  netapi main header file for user space transport
- *               library
- * 
- * REVISION HISTORY:  rev 0.0.1 
- *
- *  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 
+/******************************************************************************
+ * FILE PURPOSE:  User space access to transport resources on SOC
+ ******************************************************************************
+ * FILE NAME:   netapi.h
+ *
+ * DESCRIPTION: NETAPI definitions and data structures
+ *
+ * REVISION HISTORY: rev 0.0.1 
+ *
+ *  Copyright (c) Texas Instruments Incorporated 2010-2012
+ *
+ *  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  netapi.h
+ *
+ *   path  ti/runtime/netapi/netapi.h
+ *
+ *   @brief  Netapi main header file for user space transport library
+ *
+ */
 
 /**  @mainpage Network API 
  *
  *
  *  \par
  *  NOTE:
- *      (C) Copyright 2010-2011 Texas Instruments, Inc.
+ *      (C) Copyright 2010-2012 Texas Instruments, Inc.
  *  \par
  */
 
-/* Define NETAPI as a master group in Doxygen format and add all NETAPI 
-   definitions to this group. */
-/** @defgroup netapi USERSPACE TRANSPORT NETAPI
- *  @{
- */
-/** @} */
-
-
 #ifndef __NETAPI__H
 #define __NETAPI__H
 #include <stdint.h>
 #include <stddef.h>
 #include <string.h>
 
+
+
+/* Define NETAPI as a master group in Doxygen format and
+ * add all NETAPI
+ * definitions to this group.
+ */
+/** @defgroup netapi Network API
+ *  @{
+ */
+/** @} */
+
+
+/** @defgroup netapi_gen_functions NETAPI General Functions
+ *  @ingroup netapi
+ */
+/** @defgroup netapi_cfg_functions NETAPI Configuration Functions
+ *  @ingroup netapi
+ */
+/** @defgroup netapi_cfg_sec_functions NETAPI Security Configuration Functions
+ *  @ingroup netapi
+ */
+
+/** @defgroup netapi_pktio_functions NETAPI PKTIO Functions
+ *  @ingroup netapi
+ */
+
+/** @defgroup netapi_constants NETAPI Constants
+ *  @ingroup netapi
+ */
+
+/** @defgroup netapi_cb_functions NETAPI  Callback Functions
+ *  @ingroup netapi
+ */
+
+
+/** @defgroup netapi_structures NETAPI Structures used in API's
+ *  @ingroup netapi
+ */
+
+/** @defgroup netapi_tune_parameters NETAPI Tune Parameters
+ *  @ingroup netapi
+ */
+
+
 /**
  * @brief   This is the NWAL LLD Version. Versions numbers are encoded in the following 
  * format:
  *  0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)
  */
-#define NETAPI_VERSION_ID                   (0x01000003)
+#define NETAPI_VERSION_ID                   (0x01000004)
 
 /**
  * @brief   This is the version string which describes the NWAL LLD along with the
  * date and build information.
  */
-#define NETAPI_VERSION_STR      "NETAPI Revision: 01.00.00.03"
+#define NETAPI_VERSION_STR      "NETAPI Revision: 01.00.00.04"
+
 
 
 /**
- *   @defgroup netapi_structures  NETAPI data structures
+ * @ingroup netapi_structures
+ * @brief  One per thread, used in most NETAPI function calls.
  */
-/**  @ingroup netapi */
+typedef void * NETAPI_T;
 
-/** @defgroup netapi_api_functions NETAPI API's
- *  @ingroup netapi_api_functions
- */
 
-/**  @ingroup netapi_structures */
 /**
- * @def NETAPI_T
- * @brief  netapi handle:  one per thread
- *         used in most NETAPI calls
+ * @brief This defines master for system
  */
-typedef void * NETAPI_T;
-
+#define NETAPI_SYS_MASTER  2  
 
-#define NETAPI_SYS_MASTER  2  //master for system
-#define NETAPI_CORE_MASTER 1  //master for core
+/**
+ * @brief This defines master for core
+ */
+#define NETAPI_CORE_MASTER 1  
+/**
+ * @brief This defines no mater, data only
+ */
 #define NETAPI_NO_MASTER   0  //data only
 
-/***********************************************
-*************RUN TIME CONTROLS*****************
-***********************************************/
+
+/**
+ *  @ingroup netapi_structures
+ *  @brief NETAPI configuration information
+ *
+ *  @details The parameters in this structure are used to configure NETAPI.
+ */
 typedef struct NETAPI_CFG_Tag
 {
- int def_mem_size;             //bytes of CMA memory we have allocated 
- int def_flow_pkt_rx_offset;   //offset in pkt buffer for hw to start RX
- int def_max_descriptors;      //# of descriptors in system  (must be power of 2), 2^14 max
- int def_tot_descriptors_for_us;  //#of descriptors to create in our region (must be power of 2)
- int def_heap_n_descriptors;   //# descriptors+buffers in default heap
- int def_heap_n_zdescriptors;  //# zero len descriptors in defaule heap
- int def_heap_buf_size;        //size of buffers in default heap
-                               //=MAX amount of area for packet data
- int def_heap_tailroom_size;   //size of tailroom in reserve 
- int def_heap_extra_size;      //size of extra space at end of buffer
-}NETAPI_CFG_T;
-/* note:
+ int def_mem_size;              /**<  Bytes of CMA memory we have allocated */
+ int def_flow_pkt_rx_offset;   /**<  Offset in pkt buffer for hw to start RX */
+ int def_max_descriptors;      /**<  Number of descriptors in system  (must be power of 2), 2^14 max */
+ int def_tot_descriptors_for_us;   /**<  Number of descriptors to create in our region (must be power of 2)*/
+ int def_heap_n_descriptors;    /**<  Number of descriptor plus buffers in default heap*/
+ int def_heap_n_zdescriptors;   /**<  Number of zero len descriptors in defaule heap*/
+ int def_heap_buf_size;/**<  Size of buffers in default heap, max amount of area for packet data */
+ int def_heap_tailroom_size;   /**<  Size of tailroom in reserve */
+ int def_heap_extra_size;      /**<  Size of extra space at end of buffer */ 
+}  NETAPI_CFG_T;
+
+/* @note:
    each buffer will be allocated:  def_heap_buf_size+def_heap_extra_size bytes
    each descriptor attached to these buffers will have rigBufferLen of:
       def_heap_buf_size.
@@ -179,52 +228,32 @@ Cppi_HostDesc->origBuffPtr
 #include "ti/drv/nwal/nwal.h"
 #include "netapi_timer.h"
 #include "src/netapi_loc.h"
-#include "ti/drv/sa/salld.h"
-#define NETAPI_INFLOW_MODE_ACTIVE 1
-#define NETAPI_SIDEBAND_MODE_ACTIVE 2
-typedef struct NETAPI_SA_STATS_Tag
-{
-    Sa_IpsecStats_t     saIpsecStats;
-    Sa_DataModeStats_t  dataModeStats;
-    uint8_t mode_active;
-} NETAPI_SA_STATS_T;
 
-/************************************************
- **********BUILD TIME CONTROLS *****************
- ***********************************************/
-/* see netapi_tune.h */
-
-
-/*************************************
- **************NETAPI****************
- ************************************/
-
-/**  @ingroup netapi_api_functions */
-
-/*
-*  @brief  API instantiates the NETAPI and allocated global resources and is pre-requisite 
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_init: API instantiates the NETAPI and allocated global resources and is pre-requisite
  *
- *  @details Allocates global resources valid  per system level common across all ARM cores 
+ *  @details The API will allocate global resources valid  per system level common across all ARM cores 
  *   or per thread based on "master" argument.
  *   Intializes the following substems:
- *     - pktio
- *     - pktlib
- *     - qmss
- *     - cppi
- *     - nwal
- *  @param[in]  master mode: NETAPI_SYS_MASTER or NETAPI_NO_MASTER
- *  @param[in]  configuration (master mode).  pointer to NETAPI_CFG_T above or NULL
- *  @retval     @ref NETAPI_T: handle to the instance or NULL on error 
- *  @pre        none 
+ *       -pktio
+ *       -pktlib
+ *       -qmss
+ *       -cppi
+ *       -nwal
+ *
+ *  @param[in]  master  can be either @ref NETAPI_SYS_MASTER or @ref NETAPI_NO_MASTER
+ *  @param[in]  p_cfg   (master mode).  pointer to @refNETAPI_CFG_T or NULL to use netapi default configuration.
+ *  @retval     @ref NETAPI_T: handle to the instance or NULL on error
+ *  @pre        none
  */
-NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);
-
+ NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);
 
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API shutdowns a previously intialized NETAPI instance 
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_shutdown: API De-allocates all global resources allocated as part of @ref netapi_init
  *
- *  @details de-llocates global resources valid  per system level common across all ARM cores 
+ *  @details De-allocates global resources valid  per system level common across all ARM cores 
  *   or per thread based on "master" argument passed in at init time.
  *  @param[in]  @ref NETAPI_T: handle to the instance 
  *  @retval     none 
@@ -232,111 +261,109 @@ NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);
  */
 void netapi_shutdown(NETAPI_T  p);
 
-/**  @ingroup netapi_api_functions */
-/*
-
-*  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps 
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_getPktlibIfTable: API returns a Pktlib_HeapIfTable to use when creating pktlib heaps
  *
  *  @details  Application will need a heapIfTable in order to create its own heaps. This
- *            function returns a table that can be passed in the call to @ref Pktlib_CreateHeap
-*             The memory used for these heaps is  special: 
- *               - specific alignment, 
- *               - must be contguous, 
- *               - must have a physical to virtual mapping that
- *               - is known by NETAPI. 
+ *                  function returns a table that can be passed in the call to @ref Pktlib_CreateHeap
+ *          The memory used for these heaps is  special with the following characteristicsl: 
+ *              - specific alignment, 
+ *              - must be contguous, 
+ *              - must have a physical to virtual mapping that  is known by NETAPI. 
  *          Thus it must be completely managed by NETAPI. This interfaced table provides a
  *          malloc function that the pktlib heap library uses to allocate data for the heap
  *          buffers.
  *  @param[in]  none 
- *  @retval     @ref Pktlib_HeapIfTable pointer 
- *  @pre        @ref netapi_init 
+ *  @retval         Pktlib_HeapIfTable pointer 
+ *  @pre            @ref netapi_init 
  */
 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
 
-/** utilities to see how much mem/descriptor space is remaining **/
-
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to return the amount of free memory available for allocating buffers
- (          for additonal Pktlib heaps.   
- *  @details  the applicaiton can use this API to determine how much free memory is          .
- *           available for heap buffers if it decides to create its own.   
- *  @param[in]  void  
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_getBufMemRemainder:  API is used to return the amount of free memory available for allocating buffers
+ *                                                          for additonal Pktlib heaps
+ *
+ *  @details  The application can use this API to determine how much free memory is
+ *                  available for heap buffers if it decides to create its own.   
+ *  @param[in]  void
  *  @retval     int :  amount of memory available for heap buffer storage (in bytes)
  *  @pre        @ref netapi_init 
  */
 int  netapi_getBufMemRemainder(void);
-/**  @ingroup netapi_api_functions */
-
-/*
-*  @brief  API is used to return the amount of free memory available for allocating Descriptors 
- (          for additonal Pktlib heaps.   
- *  @details  the applicaiton can use this API to determine how much free memory is          .
- *           available for heap descriptors if it decides to create its own heap.   
- *  @param[in]  void  
+
+
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_getDescRemainder:  API is used to return the amount of free memory available for allocating descriptors 
+ *                                                      for additonal Pktlib heaps.
+ *
+ *  @details  The application can use this API to determine how much free memory is
+ *                  available for heap descriptors if it decides to create its own heap.    
+ *  @param[in]  void
  *  @retval     int :  amount of memory available for heap descriptor storage (in bytes)
  *  @pre        @ref netapi_init 
  */
 int  netapi_getDescRemainder(void);
 
-/* utility to get default flow */
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to return the default NETCP flow that is to be used for received    
- (          packets..
- *  @details  the applicaiton can use this API to return the default NETCP flow that is used  
- *           for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
- *           used to supply free packets to the receive DMA function.
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_getDefaultFlow:  API is used to return the default NETCP flow that is to be used for incoming packets.
+ *
+ *  @details  The application can use this API to return the default NETCP flow that is used  
+ *                  for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
+ *                  used to supply free packets to the receive DMA function.
  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
- *  @retval     NETCP_CFG_FLOW_HANDLE_T  : handle to default flow
- *  @pre        @ref netapi_init  
+ *  @retval     NETCP_CFG_FLOW_HANDLE_T  : the handle to default flow
+ *  @pre        @ref netapi_init 
  */
 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
 return NETCP_DEFAULT_FLOW;
 }
 
-/* utility to get default route */
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to return the default NETCP route
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_getDefaultRoute:  API is used to return the default NETCP route handle.
  *
- *  @details  this functions returns the default NETCP route created by @ref netapi_init.  
- *            A netcp route consists of a NETCP flow plus a destination pktio channel 
- *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
- *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  the handle of the default route. 
+ *  @details  This API returns the default NETCP route created by @ref netapi_init.  
+ *                  A netcp route consists of a NETCP flow plus a destination pktio channel 
+ *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
+ *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  The handle of the default route. 
  *  @pre        @ref netapi_init  
  */
 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
 return NETCP_DEFAULT_ROUTE;
 }
 
-/* utility to set/get a cookie in the netapi handle */
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to return a piece of application-provided opaque data that has been 
- (          stored in the netapi instance.
- *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
- *           This APi lets this data be returned to the application.
- *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
- *  @retval     void * 
- *  @pre        @ref netapi_init  @ref netapi_setCookie
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_getCookie:  API is used to return a piece of application-provided opaque data that has been
+ *                                          stored in the netapi instance.
+ *
+ *  @details  The application can save a pointer to opaque data in the @ref NETAPI_T instance.
+ *                  This APi lets this data be returned to the application
+ *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
+ *  @retval     void * : Data provided in @ref netapi_setCookie
+ *  @pre        @ref netapi_init, @ref netapi_setCookie
  */
+
 static inline void * netapi_getCookie(NETAPI_T p)
 {
 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 return pp->cookie;
 }
 
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to set a piece of application-provided opaque data in the
- (         netapi instance.
- *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
- *           This APi can be returned later to the application via @ref netapi_getCookie
- *  @param[in]  @ref NETAPI_T :  handle to NETAPI instance 
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_setCookie:  API is used to set a piece of application-provided opaque data t in the netapi instance.
+ *
+ *  @details  The applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
+ *           This API can be returned later to the application via @ref netapi_getCookie
+ *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
  *  @param[in]  void * : opaque data to be saved
- *  @retval     void  
- *  @pre        @ref netapi_init  
+ *  @retval     none
+ *  @pre        @ref netapi_init
  */
 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
 {
@@ -344,12 +371,11 @@ NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 pp->cookie= cookie;
 }
 
-
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to poll for NETCP configuration response messages. 
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_netcpPoll: API is used to poll for NETCP configuration response messages.
  *
- *  @details  Application, if controlling the scheduler,  will need to call this
+ *  @details Application, if controlling the scheduler,  will need to call this
  *            function periodically to check for NETCP configuration responses (eg
  *            statistics requests). 
  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
@@ -358,14 +384,12 @@ pp->cookie= cookie;
  */
 void netapi_netcpPoll(NETAPI_T  p);
 
-//heap registration for polling purposes
-
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to register a heap that is created by application so that
- *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage(). 
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_registerHeap: API is used to register a heap that is created by application so that
+ *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage().
  *
- *  @details  this function registers an application-created heap with the netapi instance
+ *  @details  This API registers an application-created heap with the netapi instance
  *            so that it can add that heap's garbage queue to the garbage poll function. 
  *            NOTE: netapi internal heap is automatically registered
  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
@@ -384,15 +408,15 @@ for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
 return -1;  //no room
 }
 
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to un-register a heap that was created by application and previously
-*           registerd so that
- *          it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage(). 
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_unregisterHeap:  API is used to un-register a heap that was created by application and previously
+*           registerd so that it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage(). 
  *
- *  @details  this function un-registers an application-created heap with the netapi instance
- *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance 
- *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap 
+ *  @details  This API un-registers an application-created heap with the netapi instance. 
+ *            NOTE: netapi internal heap is automatically registered
+ *  @param[in]  p: handle to NETAPI instance 
+ *  @param[in]  h: handle to heap 
  *  @retval     <0 if err, 1 if OK
  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
  */
@@ -407,26 +431,25 @@ for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
 return -1;  //not found
 }
 
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to remove a created pktlib heap
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_closeHeap:  API is used to remove a created pktlib heap
  *
- *  @details  this function removes anapplication-created heap with the netapi instance
- *             [note -> descriptors are zapped and cannot be reused]
- *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance 
- *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap 
+ *  @details   This API removes anapplication-created heap with the netapi instance
+ *            NOTE: descriptors are zapped and cannot be reused]
+ *  @param[in]  p: handle to NETAPI instance
+ *  @param[in]  h :  handle to heap, @ref Pktlib_HeapHandle
  *  @retval     <0 if err, 1 if OK
- *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
+ *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap
  */
-
 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
 
-/**  @ingroup netapi_api_functions */
-/*
-*  @brief  API is used to poll the garbage collection queue for the internal NETAPI heaps and 
- *         any application created heaps
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_poll_heapGarbage:  API is used to poll the garbage collection queue for 
+ *              the internal NETAPI heaps and any application created heaps
  *
- *  @details  this function is used to poll the netapi internal heaps and any 
+ *  @details  This API is used to poll the netapi internal heaps and any 
  * application-created heaps    that have been registered with the netapi instance.  The
  * poll function checks the garbage collection queue associated with the heap and returns
  * descriptors and buffers when appropriate to the main free queue.
@@ -436,7 +459,27 @@ int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
  */
 void netapi_poll_heapGarbage(NETAPI_T p);
 
-static inline int netapi_get_version(void) {return NETAPI_VERSION_ID;}
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_get_version:  API used to get version of NWAL LLD 
+ *
+ *  @details  This  API used to get version of netapi
+ *  @retval     int version of netapi
+ *  @pre        @ref netapi_init
+ */
+static inline int netapi_get_version(void)
+{
+return NETAPI_VERSION_ID;
+}
+
+/**
+ *  @ingroup netapi_gen_functions
+ *  @brief netapi_get_version_string:  API used to get version string of NWAL LLD 
+ *
+ *  @details  This  API used to get version string of netapi
+ *  @retval     char version string of netapi
+ *  @pre        @ref netapi_init
+ */
 static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}
 
 #endif
index d88473a6810d1037e639bab3aee8855ab3783af0..ac824ec9d8884c4ad0dfad1901a258863c92fb1a 100755 (executable)
@@ -1,44 +1,51 @@
-/**************************************************************
- * FILE PURPOSE :  NETAPI SECURITY CONFIGURATION-
- *         user space access to security transport resources on SOC
- **************************************************************
- * @file netapi_sec.h
- * 
- * @brief DESCRIPTION:  netapi security  header file for user space transport
- *               library
- * 
- * REVISION HISTORY:  rev 0.0.1 
+/******************************************************************************
+ * FILE PURPOSE:  Netapi Security configuration header file
+ ******************************************************************************
+ * FILE NAME:   netapi_sec.h
+ *
+ * DESCRIPTION: netapi security  header file for user space transport library
+ *
+ * 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 netapi_sec.h
+ *   @brief netapi security  header file for user space transport library
+ */
+
 #ifndef __NETAPI_SEC__H
 #define __NETAPI_SEC__H
 #include "netapi.h"
 #include "ti/drv/nwal/nwal.h"
 #include <ti/drv/sa/salld.h>
 
-// To hold SA info */
+
+
+
+/**
+ *  @ingroup netapi_structures
+ *  @brief NETAPI SA Statistics
+ *
+ *  @details Pointer to this strucutre is passed in the call to netapi_getSaStats API.
+ */
+
+
+typedef struct NETAPI_SA_STATS_Tag
+{
+#define NETAPI_IPSEC_STAT_VALID                                 0x0001
+#define NETAPI_SIDEBAND_DATA_MODE_STAT_VALID    0x0002
+    uint16_t            validParams; /** < Bit map indicating the IPSec SA Inflow/Side band data mode stats validity */
+    Sa_IpsecStats_t     saIpsecStats;           /**<  Structure containing IPSEC stats in INFLOW MODE*/
+    Sa_DataModeStats_t  dataModeStats;     /**<  Structure containing IPSEC stats in SIDEBAND MODE */
+} NETAPI_SA_STATS_T;
+
+
+/**
+ *  @ingroup netapi_structures
+ *  @brief NETAPI security SA information
+ *
+ *  @details This structure contains SA information 
+ */
 typedef struct NETAPI_SEC_SA_INFO_tag
 {
-    nwal_SaDir          dir;            /** Direction for the channel. Inbound or Outbound */
-    uint32_t            spi;               /**< IPSec Security Parameter index */
+    nwal_SaDir          dir;            /**< Direction for the channel. Inbound or Outbound */
+    uint32_t            spi;              /**< IPSec Security Parameter index */
     nwal_IpSecProto     proto;              /**< IpSec Proto (ESP/AH) */
     nwal_saMode         saMode;         /**< Tunnel/ Transport mode */
     nwal_IpType         ipType;             /**< IPV4 or V6 */
@@ -64,34 +97,75 @@ typedef struct NETAPI_SEC_SA_INFO_tag
 } NETAPI_SEC_SA_INFO_T;
 
 
+/**
+ * @brief This defines the SA mode of operation to be INFLOW
+ */
 #define NETAPI_SEC_SA_INFLOW   0x2 
+
+/**
+ * @brief This defines the SA mode of operation to be SIDEBAND
+ */
 #define NETAPI_SEC_SA_SIDEBAND 0x1 
 
-/******************************************************
- ************************API***************************
- *****************************************************/
-
-//**********************************
-//add SA
-//*******************************************
-NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T h, //the  netapi handle
-                                int iface_no, //inteface to attach to
-                                NETAPI_SEC_SA_INFO_T *sa_info   ,//info on the SA
-                                nwalSecKeyParams_t *key_params, //keys,etc
-                                int mode, //SA implementation mode: inflow or sideband or both
-                                NETCP_CFG_ROUTE_HANDLE_T  route,  //Optional route
-                                void ** data_mode_handle, //returned data mode handle for pktio
-                                void ** inflow_mode_handle,//returned inflow mode handle for pktio
+/**
+ *  @ingroup netapi_cfg_sec_functions
+ *  @brief netapi_secAddSA: API to configure an IPSEC SA. 
+ *
+ *  @details  API to configure an  IPSec SA. SAs are IPSec security contexts and define a uni-directional
+ * secure path (tunnel or transport). SAs are attached to Mac interfaces that have already
+ * been created. API allows SA to be configured as either inflow or sideband mode
+ *  @param[in]  @ref NETAPI_T: the NETAPI handle 
+ *  @param[in] iface_no:interface to attach SA to.
+ *  @param[in] sa_info: @ref NETAPI_SEC_SA_INFO_T: information on the SA being added
+ *  @param[in]  key_params: @ref nwalSecKeyParams_t: security key information for the SA.
+ *  @param[in] mode: SA implementation mode @ref NETAPI_SEC_SA_SIDEBAND or @ref NETAPI_SEC_SA_INFLOW
+ *  @param[in] route: @ref NETCP_CFG_ROUTE_HANDLE_T
+ *  @param[in] data_mode_handle: returned data mode handle for PKTIO
+ *  @param[in] inflow_mode_handle: returned inflow mode handle for PKTIO
+ *  @param[out] perr: error codem, zero on sucess, non-zero on failure
+ *  @retval     Aplication id associated with created SA, @ref NETCP_CFG_SA_T
+ *  @pre        @ref netapi_init 
+ */
+NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T h,
+                                int iface_no,
+                                NETAPI_SEC_SA_INFO_T *sa_info   ,
+                                nwalSecKeyParams_t *key_params,
+                                int mode,
+                                NETCP_CFG_ROUTE_HANDLE_T  route,
+                                void ** data_mode_handle,
+                                void ** inflow_mode_handle,
                                 int * perr);
 
-//*****************************************
-//delete SA
-//*****************************************
+/**
+ *  @ingroup netapi_cfg_sec_functions
+ *  @brief netapi_secDelSA: API to delete an IPSEC SA. 
+ *
+ *  @details  API to delete an IPSEC SA
+ *  @param[in]  h   the NETAPI handle, @ref NETAPI_T
+ *  @param[in] iface_no:interface to attach SA to.
+ *  @param[in] sa_app_id: Application id returned from call to @ref netapi_secAddSA
+ *  @param[out] perr: zero on sucess, non-zero on failure
+ *  @retval     none
+ *  @pre        @ref netapi_init @ref netapi_secAddSA
+*/
 void netapi_secDelSA(NETAPI_T h,int iface_no, NETCP_CFG_SA_T  sa_app_id,  int *perr);
 
-//******************************************
-// Add RX Security Policy
-//******************************************
+/**
+ *  @ingroup netapi_cfg_sec_functions
+ *  @brief netapi_secAddRxPolicy: API to add a recieve security policy 
+ *
+ *  @details  API to add a recieve security policy
+ *  @param[in]  h   the NETAPI handle, @ref NETAPI_T
+ *  @param[in] sa: Application id returned from call to @ref netapi_secAddSA
+ *  @param[in] ipType, @ref nwal_IpType
+ *  @param[in] src_ip_addr, @ref nwalIpAddr_t
+ *  @param[in] dst_ip_addr, @ref nwalIpAddr_t
+ *  @param[in] ip_qualifiers @ref nwalIpOpt_t
+ *  @param[in] route: optional route, @ref NETCP_CFG_ROUTE_HANDLE_T
+ *  @param[out] perr: zero on sucess, non-zero on failure
+ *  @retval    Aplication id associated with created receive security policy , @ref NETCP_CFG_IPSEC_POLICY_T
+ *  @pre        @ref netapi_init @ref netapi_secAddSA
+*/
 NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T h, //the  netapi handle
                                 NETCP_CFG_SA_T sa,  //tunnel to attach to
                                 nwal_IpType ipType,     //V4 or V6
@@ -101,14 +175,34 @@ NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T h, //the  netapi handle
                                 NETCP_CFG_ROUTE_HANDLE_T  route,  //Optional route
                                 int * perr);
 
-//******************************************
-// Delete RX Security Policy
-//******************************************
+/**
+ *  @ingroup netapi_cfg_sec_functions
+ *  @brief netapi_secDelRxPolicy: API to add a recieve security policy 
+ *
+ *  @details  API to add a recieve security policy
+ *  @param[in]  h   the NETAPI handle, @ref NETAPI_T
+ *  @param[in] policy_app_id: Application id returned from call to @ref netapi_secAddRxPolicy
+ *  @param[out] perr: zero on sucess, non-zero on failure
+ *  @retval     none
+ *  @pre        @ref netapi_init @ref,  @ref netapi_secAddRxPolicy
+*/
 void netapi_secDelRxPolicy(NETAPI_T h,
                               NETCP_CFG_IPSEC_POLICY_T policy_app_id, 
                               int *perr);
 
 
-
+/**
+ *  @ingroup netapi_cfg_sec_functions
+ *  @brief netapi_getSaStats: API to retrieve SA statistics via NWAL.
+ *
+ *  @details  *  API to retrieve SA statistics via NWAL.
+ *  @param[in]  h   the NETAPI handle, @ref NETAPI_T 
+ *  @param[in] pSaStats: Pointer to NETAPI_SA_STATS_T which will get populated by this API call, @ref NETAPI_SA_STATS_T
+ *  @retval     none
+ *  @pre        @ref netapi_init @ref,  @ref netapi_secAddSA
+*/
+void  netapi_getSaStats (NETAPI_T                   h,
+                         NETCP_CFG_SA_T             handle,
+                         NETAPI_SA_STATS_T*         pSaStats);
 
 #endif
index d02ef127ad2879731e9cb75424866e64b2405e54..fd8113b92739fb0bb7663334617401bb99dccb02 100755 (executable)
@@ -1,74 +1,74 @@
-/**************************************************************
- * FILE: netapi_tune.h
- * Purpose:  hold tunable parameters (build time)
- **************************************************************
- * @file netapi_tune.h
- * 
- * @brief DESCRIPTION:  Tuneable (compile time) parameters  for user space transport
- *               library
- * 
- * REVISION HISTORY:  rev 0.0.1 
+/******************************************************************************
+ * FILE PURPOSE:  netapi tunable parameters (compile time)
+ ******************************************************************************
+ * FILE NAME:   netapi_tune.h
+ *
+ * DESCRIPTION:Tuneable (compile time) parameters for user space transport library
+ *
+ * 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 netapi_tune.h
+ *   @brief Netapi Tuneable (compile time) parameters for user space transport library
+ */
+
 
- ****************************************************/
 #ifndef __NETAPI_TUNE__H
 #define __NETAPI_TUNE__H
 
 
 /**
- *   @defgroup NETAPI_TUNE NETAPI tunable parameters
- */
-/**  @ingroup NETAPI_TUNE */
-
-/**
-*  @def  NETAPI_ENABLE_SECURITY
-* (0) define this to enable securtiy.  Note: libraries being use need to be built with SA enabled also! 
+ * @ingroup netapi_tune_parameters
+* @brief Define this to enable securtiy.  Note: libraries being use need to be built with SA enabled also
 */
 #define NETAPI_ENABLE_SECURITY 
 
 
 /**
-*  @def  NETAPI_USE_DDR
-* (0) define this to enable use of cached DDR for buffers and descriptors 
-*     do not define if USE_MSMC defined below
+ * @ingroup netapi_tune_parameters
+* @brief Define this to enable use of cached DDR for buffers and descriptors. Do not define if USE_MSMC defined below
 */
 #define NETAPI_USE_DDR
 #ifdef NETAPI_USE_DDR
 #define NETAPI_TUNE_USE_CACHE_OPS   //for appleton, no cache coherency with netcp & ARM 
 #endif
+
 /**
-*  @def  NETAPI_USE_MSMC
-* (0) define this to enable use of un-cached MSMC for buffers and descriptors 
-*     do not define if USE_DDR defined above 
+ * @ingroup netapi_tune_parameters
+* @brief Define this to enable use of un-cached MSMC for buffers and descriptors . Do not define if USE_DDR defined above 
 */
 //#define NETAPI_USE_MSMC
 
 #endif
 
 /**
- * @def TUNE_NETAPI_NUM_CORES
- * (0) How many cores (theads) 
+ * @ingroup netapi_tune_parameters
+* @brief Define this to the number of cores (theads) 
  */
 #define TUNE_NETAPI_NUM_CORES 1
 
 /**
- *  @def TUNE_NETAPI_PERM_MEM_SZ
- * (1) how much contiguous memory to grab. This is used for
+ * @ingroup netapi_tune_parameters
+* @brief Define this to how much contiguous memory to grab. This is used for
  * descriptors and buffers in the case of uncached configuration only.  
  * descriptors and buffers.  Can't be bigger than  msmc if
  * MSMC memory is being using uncached .  This can be set at netapi_init via NETAPI_CFG_T
 #define TUNE_NETAPI_PERM_MEM_SZ   (2*1024*1024) 
 
 /**
- * @def TUNE_NETAPI_MAX_PKTIO
- * (2) how many GLOBAL pkt io channels
+ * @ingroup netapi_tune_parameters
+ * @brief Define this to how many GLOBAL pkt io channels
  */
 #define TUNE_NETAPI_MAX_PKTIO 16
 
-//(2a) default TX channel name
-//(2b) default RX channel name
-
-
 /**
- * @def TUNE_NETAPI_DEFAULT_BUFFER_SIZE
- * (3) size of netapi default pktlib heap buffers
-*  This can be set at netapi_init() 
+ * @ingroup netapi_tune_parameters
+ * @brief Define this to the size of netapi default pktlib heap buffers This can be set at @ref netapi_init 
  */
 #define TUNE_NETAPI_DEFAULT_BUFFER_SIZE 1600  
 
-//(3a) default pkt heap name
+
 
 /**
- * @def TUNE_NETAPI_DEFAULT_NUM_BUFFERS
- *(4) number of netapi default pktlib heap buffers (and assoc descriptors)
- * this can be set at netapi_init()
+ * @ingroup netapi_tune_parameters
+ * @brief Define this to number of netapi default pktlib heap buffers (and assoc descriptors)
+ * this can be set at @ref netapi_init
  */
 #define TUNE_NETAPI_DEFAULT_NUM_BUFFERS  200 
 
-/*
- * @def TUNE_NETAPI_DEFAULT_NUM_SOLO_DESCRIPTORS
- * (5) number of netapi default pkt lib heap solo descriptors
- * this can be set at netapi_init
+/**
+ * @ingroup netapi_tune_parameters
+ * @brief Define this to  number of netapi default pkt lib heap solo descriptors
+ * this can be set at @ref netapi_init
  */
 #define TUNE_NETAPI_DEFAULT_NUM_SOLO_DESCRIPTORS  100 
 
 /**
- * @def NETAPI_INCLUDE_SCHED
- * (6) define this to include the scheduler component
+ * @ingroup netapi_tune_parameters
+* @brief  Define this to include the scheduler component
  */
 #define NETAPI_INCLUDE_SCHED 
 
-//(7) # of QM descriptors (total)
-//     this can be set set in netapi_init
-// MUST BE POWER OF 2
+/**
+ * @ingroup netapi_tune_parameters
+* @brief  Define this to the number of of QM descriptors (total). This can be set set in @ref netapi_init
+* @note MUST BE POWER OF 2
+*/
 #define TUNE_NETAPI_QM_CONFIG_MAX_DESC_NUM  2048 /* 16384 is abs max */
 
 //(8) Region info
index 7bc17e4b02cd971ac148696132fa71ecda136f9e..4df07fc41dad8dc8ea84a8f0198844beae62bac6 100755 (executable)
@@ -1,45 +1,51 @@
-/***************************************************
- * File: netcp_cfg.h 
- * Purpose: netcp config API
- **************************************************************
- *@file netcp_cfg.h
- * 
- * @brief DESCRIPTION:  netapi NETCP configuration API header  file 
- *          for user space transport library
- * 
- * REVISION HISTORY:  rev 0.0.1 
+/******************************************************************************
+ * FILE PURPOSE:  netapi NETCP configuration API header file
+ ******************************************************************************
+ * FILE NAME:   netcp_cfg.h
+ *
+ * DESCRIPTION:netapi NETCP configuration API header  file  for user space transport library
+ *
+ * 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 netcp_cfg.h
+ *   @brief Netapi NETCP configuration API header  file for user space transport library
+ */
+
 
- ***************************************************/
 
 #ifndef __NETCP_CFG__H
 #define __NETCP_CFG__H
 #include "ti/runtime/pktlib/pktlib.h"
 
 //NETCP FLOW
+/**
+ *  @ingroup netapi_structures
+ *  @brief CPPI flow ID for default case, use NETCP_DEFAULT_FLOW
+ */
 typedef struct NETCP_CFG_FLOW_Tag
 {
-       int flowid;
+    int flowid;         /**< flow id*/
 } NETCP_CFG_FLOW_T;
+
+
+
+/**
+ * @ingroup netapi_constants
+ * @brief  This defines the handle to NETCP configuration flow.
+ */
 typedef void *  NETCP_CFG_FLOW_HANDLE_T;
+
+/**
+ * @ingroup netapi_constants
+ * @brief  This defines the NETCP default FLOW to be NULL.
+ */
 #define NETCP_DEFAULT_FLOW  (NETCP_CFG_FLOW_HANDLE_T*) NULL
 
-//NETCP ROUTE
-typedef struct NETCP_CFG_ROUTE_Tag
-{
-   NETCP_CFG_FLOW_T * p_flow;  //NULL or NETCP_DEFAULT_FLOW for default flow
-   PKTIO_HANDLE_T * p_dest_q;       //NULL for default destination queue
-} NETCP_CFG_ROUTE_T;
-typedef void * NETCP_CFG_ROUTE_HANDLE_T;  
+
+/**
+ * @ingroup nwal_api_constants
+ * @brief  Handle to the default NETCP route.
+ * @details Application to use this handle to identify default NETCP route.
+ */
+typedef void * NETCP_CFG_ROUTE_HANDLE_T;
+
+/**
+ * @brief This defines the NETCP default ROUTE to be NULL.
+ */
 #define NETCP_DEFAULT_ROUTE  (NETCP_CFG_ROUTE_HANDLE_T*) NULL
 
 
-/*--------------flow management--------*/
-NETCP_CFG_FLOW_HANDLE_T netcp_cfgAddFlow(NETAPI_T ,
-                                            int n, 
-                                            Pktlib_HeapHandle handles[],
-                                           int sizes[], //must be<= heap corresponding heap size-recv_offset-any desired tail room
-                                            int recv_offset,  //bytes to save in front of packet
-                                            int * err );
-void netcp_cfgDelFlow(NETAPI_T , NETCP_CFG_FLOW_HANDLE_T , int * err);
+/**
+ *  @ingroup netapi_structures
+ *  @brief NETCP application defined route information.
+ *
+ */
+typedef struct NETCP_CFG_ROUTE_Tag
+{
+   NETCP_CFG_FLOW_T * p_flow;   /**< NULL or NETCP_DEFAULT_FLOW for default flow, @ref NETCP_CFG_FLOW_T */
+   PKTIO_HANDLE_T * p_dest_q;/**<NULL for default destination queue */
+} NETCP_CFG_ROUTE_T;
 
-/*-----------Actions----------*/
+/**
+ * @ingroup netapi_constants
+ * @brief This defines the NETCP action to discard packet.
+ */
 #define NETCP_CFG_ACTION_DISCARD 0
-#define NETCP_CFG_ACTION_CONTINUE 1  //pass packet on to next classifier
+/**
+ * @ingroup netapi_constants
+ * @brief This defines the NETCP action to pass packet ono the next classifier
+ */
+#define NETCP_CFG_ACTION_CONTINUE 1
+/**
+ * @ingroup netapi_constants
+ * @brief This defines the NETCP action to pass packet to User space application
+ */
 #define NETCP_CFG_ACTION_TO_SW    2
 
-/*------------L2----------------------*/
+
+/**
+ * @ingroup nwal_api_constants
+ * @brief  Handle to the default NETCP route.
+ * @details Application to use this handle to identify default NETCP route.
+ */
 typedef void * NETCP_CFG_VLAN_T;
 
-/******************************************************************/
-/***********************APP ids for rx meta data********************/
-/******************************************************************/
-
-/* APPIDs are present in RX packet meta data and tell "how far the packet got
-   through the classification rules of NETCP 
-   APPID is 32 bits:
-      bits 31-24 = MATCH STAGE (NETAPI_NECP_MATCH_xxx below)
-      bits 23-8  = identifier (depends on match stage)
-      bits  7-0  = logical mac interface
-
-   As a cheat sheet:
-If APPID == _NETCP_MATCH_GENERIC_MAC  then
-   packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.  
-   Packet did not match any other rule
-
-If APPID == _NETCP_MATCH_GENERIC_IP  then
-   packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
-   packet matched a generic IP rule attached to that interface.  The IP rule # for the interface
-   is given in Bytes 3,2 of the APPID.   Packet did not match any other rule
-
-If APPID = NETCP_MATCH_CLASS
-   packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
-   packet matched a generic IP rule  attached to that interface OR a general IP rule added as part of
-   the classifier or it matched a combination of ISPEC SA rule and a policy check.  Finally,
-   Packet matched a L4 port rule that was added as part of a classifer.  Bytes 3-2
-   give the ID of the classifier . Packet did not match any other rule
-
-If APPID = NETCP_MATCH_CLASS_L3   (partial classifier match)
-   packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
-   packet matched a general IP rule added as part of a classifier.  But it not match a
-   L4 port or any other rule. We cannout say what classifer partially matched so Bytes 3-2 are
-   not applicable
-
-
-If APPID = NETCP_MATCH_IPSEC
-   packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
-   packet matched an IPSEC SA  rule (matched proto, dest ip and SPI).  The SA id  is in
-   bytes 3-2 of APPID.  Packet did not match any other rule (so may have failed a policy check)
-
-ID APPID = NETCP_MATCH_IPSEC_POLICY   
-   packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
-   packet matched an IPSEC SA rule (matched proto, dest ip and SPI).  Packet matched
-   a POLICY RULE - this is a check of the inner IP.  The IPSEC RX Policy ID  is in
-   bytes 3-2 of APPID.  Packet did not match any other rule 
+/**
+ * @ingroup nwal_api_constants
+ * @brief  AppID for MAC interface
+ */
+typedef uint32_t NETCP_CFG_MACIF_T;
+
+/**
+ * @ingroup nwal_api_constants
+ * @brief AppID for IP interface
+ */
+typedef uint32_t NETCP_CFG_IP_T;
+
+
+
+/**
+ * @ingroup nwal_api_constants
+ * @brief This define is used to identify the application id associated with a created SA
+ */
+typedef uint32_t NETCP_CFG_SA_T;
+
+
+/**
+ * @ingroup nwal_api_constants
+ * @brief AppId used to identify NETCP IPSEC policy
+ */
+typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
+
+
+/**
+ * @ingroup nwal_api_constants
+ * @brief This define is to be used in AddIp, AddClassifier to indicate any MAC address.
+ */
+#define NETCP_CFG_NO_INTERFACE 0xff
+
+
+
+/**
+ * @note  APPIDs are present in RX packet meta data and tell "how far the packet got
+ * through the classification rules of NETCP 
+ * APPID is 32 bits:
+ * bits 31-24 = MATCH STAGE (NETAPI_NECP_MATCH_xxx below)
+ * bits 23-8  = identifier (depends on match stage)
+ * bits  7-0  = logical mac interface
 */
 
-      
-// NWAL "AP ids" for PA Rules that are added
+/**
+ * @ingroup netapi_constants
+ * @brief This define is used to indicate that apacket matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.  
+ * Packet did not match any other rule
+ */
 #define NETAPI_NETCP_MATCH_GENERIC_MAC  0x10000000  //lower byte==interface
+
+/**
+ * @ingroup netapi_constants
+ * @brief This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
+ * packet matched a generic IP rule attached to that interface.  The IP rule # for the interface
+ * is given in Bytes 3,2 of the APPID.   Packet did not match any other rule
+ */
 #define NETAPI_NETCP_MATCH_GENERIC_IP   0x20000000  //lower byte==interface
+
+
+/**
+ * @ingroup netapi_constants
+ * @brief This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
+ * packet matched a generic IP rule  attached to that interface OR a general IP rule added as part of
+ * the classifier or it matched a combination of ISPEC SA rule and a policy check.  Finally,
+ * Packet matched a L4 port rule that was added as part of a classifer.  Bytes 3-2
+ * give the ID of the classifier . Packet did not match any other rule
+ */
 #define NETAPI_NETCP_MATCH_CLASS        0x80000000  //FULL MATCH or' in classifier (16 bits), lower byte==interface
+
+/**
+ * @ingroup netapi_constants
+ * @brief This define is used to indicate that a  packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
+ * packet matched a general IP rule added as part of a classifier.  But it not match a
+ * L4 port or any other rule. We cannout say what classifer partially matched so Bytes 3-2 are
+ * not applicable
+ */
 #define NETAPI_NETCP_MATCH_CLASS_L3     0x40000000  //MATCHED L3 but not L4.  lower byte==interface
+
+/**
+ * @ingroup netapi_constants
+ * @brief This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
+ * packet matched an IPSEC SA  rule (matched proto, dest ip and SPI).  The SA id  is in
+ * bytes 3-2 of APPID.  Packet did not match any other rule (so may have failed a policy check)
+ */
 #define NETAPI_NETCP_MATCH_IPSEC        0x01000000  //lower byte==interface, Or' in SA id (16 bits)
+
+/**
+ * @ingroup netapi_constants
+ * @brief This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
+ * packet matched an IPSEC SA rule (matched proto, dest ip and SPI).  Packet matched
+ * a POLICY RULE - this is a check of the inner IP.  The IPSEC RX Policy ID  is in
+ * bytes 3-2 of APPID.  Packet did not match any other rule 
+ */
 #define NETAPI_NETCP_MATCH_IPSEC_POLICY 0x02000000  //lower byte==interface, Or' in SA id (16 bits)
 
-/*---------MAC APPID------------------*/
-/* Packets just matching MAC rule are tagged with this type (MATCH_GENERIC_MAC) */
-typedef uint32_t NETCP_CFG_MACIF_T;
 
-/*---------------IP APPID-------------------*/
-/* Packets whose final match is an IP rule are tagged with this type (MATCH_GENERIC_IP)*/ 
-typedef uint32_t NETCP_CFG_IP_T;
 
-/*--------------Tunnel APPID------------------*/
-/* Packets whose final match a IPSEC tunnel  are tagged with this type (MATCH_IPSEC)*/ 
-typedef uint32_t NETCP_CFG_SA_T;  
 
-/*---------------IPSEc RX Policy APPID------------*/
-/* Packets whose final match is a IPSEC RX Policy  are tagged with this type (MATCH_IPSEC_POLICY)*/ 
-typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;  
+
+/**
+ *  @ingroup netapi_cfg_functions
+ *  @brief netcp_cfgAddFlow   API to add a flow
+ * 
+ *  @details This api is used to add a flow
+ *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
+ *  @param[in]  n    number of Pktlib_HeapHandle
+ *  @param[in]  handles[]   handles to Pktlib_HeapHandle
+ *  @param[in]  sizes[]     must be<= heap corresponding heap size-recv_offset-any desired tail room
+ *  @param[in]  recv_offset   bytes to save in front of packet
+ *  @param[out] err     pointer to error return
+ *  @retval     NETCP flow handle, @ref NETCP_CFG_FLOW_HANDLE_T
+ *  @pre       @ref netapi_init
+ */
+NETCP_CFG_FLOW_HANDLE_T netcp_cfgAddFlow(NETAPI_T h,
+                                            int n, 
+                                            Pktlib_HeapHandle handles[],
+                                            int sizes[],
+                                            int recv_offset,
+                                            int * err );
 
 
-//use this in AddIp, AddClassifier to indicate any MAC address
-#define NETCP_CFG_NO_INTERFACE 0xff
+/**
+ *  @ingroup netapi_cfg_functions
+ *  @brief netcp_cfgDelFlow   API to delete a flow
+ * 
+ *  @details This api is used to delete a flow
+ *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
+ *  @param[in]  p    handle to NETCP  flow
+ *  @param[out] err     pointer to error return
+ *  @retval     none
+ *  @pre       @ref netapi_init, netcp_cfgAddFlow
+ */
+void netcp_cfgDelFlow(NETAPI_T h ,
+                                            NETCP_CFG_FLOW_HANDLE_T p ,
+                                            int * err);
 
-/* del mac i/f */
+/**
+ *  @ingroup netapi_cfg_functions
+ *  @brief netcp_cfgDelMac   API to delete MAC  interface
+ * 
+ *  @details This api is used to delete a MAC interface
+ *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
+ *  @param[in]  iface_no    interface number (0,1,..)
+ *  @param[out] err     pointer to error return
+ *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
+ *  @pre       @ref netapi_init , @ref netcp_cfgAddMac 
+ */
 void netcp_cfgDelMac(NETAPI_T h,int iface_no,  int *err);
 
-/* del attached IP*/
+
+
+/**
+ *  @ingroup netapi_cfg_functions
+ *  @brief  API attaches an IP adderess and qualifier to a MAC interface
+ * 
+ *  @details This api is used to add an IP address to a MAC interface along
+ *            with optional IP qualifier. A route, @ref NETCP_CFG_ROUTE_HANDLE_T,or NULL for default 
+ *            may be specified to indicate where to send packets matching the MAC interface MAC address, the
+ *            supplied IP address and any qualifier.  This API adds a rule to the NETCP level 1 lookup tables
+ *            Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_IP
+ *            Note: An IP address must be attached to enable NETCP receive Checksum offload feature
+ *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
+ *  @param[in]  iface_no    interface number (0,1,..)
+ *  @param[in]  ipType  type of IP address (V4 for V6), @ref nwal_IpType
+ *  @param[in]  ip_addr      ip_address, @ref nwalIpAddr_t
+ *  @param[in]  ip_qualifiers   ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
+ *                  diffserv category for example. @ref nwalIpOpt_t
+ *  @param[in]  route   [future] handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
+ *  @param[out] err     pointer to error return
+ *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
+ *  @pre       @ref netapi_init , @ref netcp_cfgAddMac 
+ */
+NETCP_CFG_IP_T  netcp_cfgAddIp(
+                  NETAPI_T  h,
+                  int  iface_no,
+                  nwal_IpType ipType,
+                  nwalIpAddr_t  * ip_addr,
+                  nwalIpOpt_t * ip_qualifiers,
+                  NETCP_CFG_ROUTE_HANDLE_T  route,
+                  int * err
+                  );
+
+#define netcp_addIp netcp_cfgAddIp //oops
+
+/**
+ *  @ingroup netapi_cfg_functions
+ *  @brief netcp_cfgDelIp   API to delete IP interface
+ * 
+ *  @details This api is used to delete an IP interface
+ *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
+ *  @param[in]  iface_no    interface number (0,1,..)
+ *  @param[in]  ipType  type of IP address (V4 for V6), @ref nwal_IpType
+ *  @param[in]  ip_addr      ip_address, @ref nwalIpAddr_t
+ *  @param[in]  ip_qualifiers   ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
+ *                  diffserv category for example. @ref nwalIpOpt_t
+ *  @param[in]  ip_rule_id      @ref NETCP_CFG_IP_T
+ *  @param[out] err     pointer to error return
+ *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
+ *  @pre       @ref netapi_init , @ref netcp_cfgAddIp
+ */
 void netcp_cfgDelIp(NETAPI_T h, int iface_no,  nwal_IpType ipType,
                   nwalIpAddr_t  * ip_addr,
                   nwalIpOpt_t * ip_qualifiers, 
-                  NETCP_CFG_IP_T
+                  NETCP_CFG_IP_T  ip_rule_id,
                   int *err);
 
-/*****************************************************************
- * Create a  MAC interface 
- ****************************************************************/
-/*
-*  @brief  API Creates a MAC interface  
- *
+
+
+/**
+ *  @ingroup netapi_cfg_functions
+ *  @brief netcp_cfgCreateMacInterface  API to create a MAC interface
+ * 
  *  @details This api is used to create a MAC interface.
  *      Once it is created, the MAC interface can be used to receive packets. The API
  *      adds a rule to the NETCP 1st level lookup tables to route all packets with destination
  *      MAC matching supplied argument and not matching any other lookup entry (see @ref netcp_cfgAddIp) to
  *      the supplied route, @ref NETCP_CFG_ROUTE_T, (or default route).
  *      Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_MAC
- *  Note: The internal SOC switch must be "taught" that this mac
+ *      Note: The internal SOC switch must be "taught" that this mac
  *      address is present by transmitting a packet with destination mac = this interface mac address.
- *  @param[in]  @ref NETAPI_T: NETAPI instance 
- *  @param[in]  char *: pointer to 6 byte MAC address for interface
- *  @param[in]  int : interface number (0,1,..) 
- *  @param[in]  int : switch port (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported] 
- *  @param[in]  @ref NETCP_CFG_ROUTE_HANDLE_T : [future] handle of a created route or NULL to use internal default route 
- *  @oaram[in]  @ref NETCP_CFG_VLAN_T : [future[ vlan configuration . Set to NULL
- *  @param[in]  int : [future] interface state (0=down, 1= up)
- *  @param[out] int * err:  pointer to error return
- *  @retval     @ref NETCP_CFG_MACIF_T : returned AppID for interface (this is returned in meta data for
- *                 received packets matching this rule an no others)
+ *  @param[in]  h   NETAPI instance handle, @ref NETAPI_T
+ *  @param[in]  p_mac   pointer to 6 byte MAC address for interface
+ *  @param[in]  iface_no    interface number (0,1,..) 
+ *  @param[in]  switch_port     (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported] 
+ *  @param[in]  route   [future] handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
+ *  @param[in]  vlan    [future[ vlan configuration . Set to NULL, @ref NETCP_CFG_VLAN_T
+ *  @param[in]  state   [future] interface state (0=down, 1= up)
+ *  @param[out] err     pointer to error return
+ *  @retval     returns AppID for interface (this is returned in meta data for received packets matching this rule an no others) @ref @ref NETCP_CFG_MACIF_T
  *  @pre       @ref netapi_init 
  */
 NETCP_CFG_MACIF_T  netcp_cfgCreateMacInterface(
-                  NETAPI_T  h,     //
-                  uint8_t *p_mac, //mac address associated with interface
-                 int iface_no, //0,1, ..
-                  int switch_port,//0=don't care, 1=switch port 1, 2=switch port 2 , ..
-                  NETCP_CFG_ROUTE_HANDLE_T  route, //NULL to use default
-                  NETCP_CFG_VLAN_T  vlan,  //future
-                  int state,  //0=down, 1=up  //FUTURE
+                  NETAPI_T  h,     
+                  uint8_t *p_mac, 
+                 int iface_no,
+                  int switch_port,
+                  NETCP_CFG_ROUTE_HANDLE_T  route,
+                  NETCP_CFG_VLAN_T  vlan,
+                  int state,
                   int * err
                   );
 
-/*****************************************************************
- * Add IP address/qualifier to MAC interface 
- ****************************************************************/
-/*
-*  @brief  API attaches an IP adderess and qualifier to a MAC interface 
- *
- *  @details This api is used to add an IP address to a MAC interface along
- *           with optional IP qualifier. A route, @ref NETCP_CFG_ROUTE_HANDLE_T,or NULL for default 
- *            may be specified to indicate where to send packets matching the MAC interface MAC address, the
- *            supplied IP address and any qualifier.  This API adds a rule to the NETCP level 1 lookup tables
- *            Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_IP
- * Note: An IP address must be attached to enable NETCP Recevie Checksum offload feature
- *  @param[in]  @ref NETAPI_T: NETAPI instance
- *  @param[in]  int : interface number (0,1,..)
- *  @param[in]  @ref nwal_IpType : type of IP address (V4 for V6) 
- *  @oaram[in]  @ref nwalIpAddr_t : ip_address
- *  @param[in]  @ref nwalIpOpt_t : ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
- *                  diffserv category for example
- *  @param[in]  @ref NETCP_CFG_ROUTE_HANDLE_T : [future] handle of a created route or NULL to use internal default route 
- *  @param[out] int * err:  pointer to error return
- *  @retval     @ref NETCP_CFG_IP_T : returned AppID for attached rule. This is returned in RX meta data for
- *              packets matching this rule and no other.
- *  @pre       @ref netapi_init , @ref netcp_cfgAddMac 
+
+/**
+ * @brief This defines handle to installed classifier returned by API.  Pkts matching this classifier will have meta data with this tag.
+ *  Also used to delete classifier
  */
-NETCP_CFG_IP_T  netcp_cfgAddIp(
-                  NETAPI_T  h,
-                  int  iface_no,
-                  nwal_IpType ipType,
-                  nwalIpAddr_t  * ip_addr,
-                  nwalIpOpt_t * ip_qualifiers,
-                  NETCP_CFG_ROUTE_HANDLE_T  route,  //NULL for default
-                  int * err
-                  );
-#define netcp_addIp netcp_cfgAddIp //oops
+typedef uint32_t NETCP_CFG_CLASS_T;  
 
-/*------------------classification API-------------------*/
 
-//handle to installed classifier returned by API.  Pkts matching
-//this classifier will have meta data with this tag.  Also used
-//to delete classifier
-typedef uint32_t NETCP_CFG_CLASS_T;  
 
 //classifier L4 type  (L2,L3 implied by iface, ip)
 typedef struct NETCP_CFG_CLASS_L4_Tag
@@ -311,48 +442,72 @@ typedef struct NETCP_CFG_CLASSIFIER_Tag
 
 } NETCP_CFG_CLASSIFIER_T;
 
-//Instert a classifier.
-NETCP_CFG_CLASS_T netcp_cfgAddClass(NETAPI_T h,
+
+
+/**
+ *  @ingroup netapi_cfg_functions
+ *  @brief netcp_cfgAddClass   API can be used to route a packet flow to a specific PKTIO channel
+ * 
+ *  @details This api can be used to route a packet flow to a particular PktIO channel, use a specific
+ *  pktLib heap, and/or have NetCP attach a tag (classifier id) to the incoming packet.
+ *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
+ *  @param[in]  p_class
+  *  @param[in]  p_route
+ *  @param[out] err     pointer to error return
+ *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
+ *  @pre       @ref netapi_init
+ */NETCP_CFG_CLASS_T netcp_cfgAddClass(NETAPI_T h,
                                     NETCP_CFG_CLASSIFIER_T *p_class,
                                     NETCP_CFG_ROUTE_HANDLE_T p_route,
                                     int action, int * err);
-//delete classifier
+
+
+
+/**
+ *  @ingroup netapi_cfg_functions
+ *  @brief netcp_cfgDelClass   API can be used to delete a preconfigured classifier
+ * 
+ *  @details This API can be used to delete a preconfigured classifier
+ *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
+ *  @param[in]  classId
+ *  @param[out] err     pointer to error return
+ *  @retval     none
+ *  @pre       @ref netapi_init, @ref netcp_cfgAddClass
+ */
 void netcp_cfgDelClass(NETAPI_T h,
                          NETCP_CFG_CLASS_T classId,
                          int *err);
 
 
 
-/***************************************************************************
-********************************STATS**************************************
-**************************************************************************/
-
-/*
- *  @brief  This is the callback function that is used to return statistics from NETCP 
- *
+/**
+ *  @ingroup netapi_cb_functions
+ *  @brief NETCP_CFG_STATS_CB   Callback function that is used to return statistics from NETCP
+ * 
  *  @details The application provides a callback function that NETAPI  uses to report statistics.
-*    The request for stats is generated from the @ref netcp_cfgReqStats API.
- *   Note: to receive ths stats callback, the @ref netapi_netcpPoll funcition must be called
- *  @param[in]  @ref NETAPI_T: NETAPI instance
- *  @param[in]  @ref paSysStats_t * : the PA (NETCP packet accelerator subsystem) statistics block 
+ *  The request for stats is generated from the @ref netcp_cfgReqStats API.
+ *  Note: to receive ths stats callback, the @ref netapi_netcpPoll funcition must be called
+ *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
+ *  @param[out]  pPaStats    the PA (NETCP packet accelerator subsystem) statistics block 
  *  @retval     none 
  *  @pre       @ref netapi_init , @ref netapi_cfgReqStats, @ref netapi_netcpPoll
  */
-//stats CB
 typedef void (*NETCP_CFG_STATS_CB)( NETAPI_T h, paSysStats_t* pPaStats);
 
 
-//stats request
-/*
- *  @brief  API request statistics from NETCP 
- *
- *  @details This api is used to request a statistics from NETCP.  This will generate a stats request
- *           command to NETCP. Sometime later, the statistics result will arrive and will be passed to 
- *           the caller via the asynchronus callback @ref NETCP_CFG_STATS_CB that is registered in this call.
- *       Note: to receive the stats callback, the @ref netapi_netcpPoll funcition must be called
- *  @param[in]  @ref NETAPI_T: NETAPI instance
- *  @param[in]  @ref NETCP_CFG_STATS_CB : the function to call with the resulting statistics block
- *  @param[in]  int :  clear the stats in NETCP after the report (0=no, 1=yes)                                          
+
+
+/**
+ *  @ingroup netapi_cfg_functions
+ *  @brief netcp_cfgReqStats   API to request statistics from NETCP
+ * 
+*  @details This api is used to request a statistics from NETCP.  This will generate a stats request
+ *  command to NETCP. Sometime later, the statistics result will arrive and will be passed to 
+ *  the caller via the asynchronus callback @ref NETCP_CFG_STATS_CB that is registered in this call.
+ *  Note: to receive the stats callback, the @ref netapi_netcpPoll funcition must be called
+ *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
+ *  @param[in]  c   the callback function to invoke with the resulting statistics block, @ref NETCP_CFG_STATS_CB
+ *  @param[in]  doClear     clear the stats in NETCP after the report (0=no, 1=yes) 
  *  @param[out] int * err:  pointer to error return
  *  @retval     none 
  *  @pre       @ref netapi_init 
index bc1d87472cb46fb98f6caeb1767cfb7957630ce0..7fcd8ef2005af43a986d9621e291f9ea1068191f 100755 (executable)
@@ -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"
 #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;