minor cleanup
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi.h
index a23cbc2ef4afb4172fca724873f02618b72040f7..f7a8bac0350c1a65497dc436f36c9bd12e79edf7 100644 (file)
@@ -2,9 +2,9 @@
  * FILE PURPOSE :  -----------NETAPI-------------
  *         user space access to transport resources on SOC
  **************************************************************
- * FILE: netapi.h
+ * @file netapi.h
  * 
- * DESCRIPTION:  netapi main header file for user space transport
+ * @brief DESCRIPTION:  netapi main header file for user space transport
  *               library
  * 
  * REVISION HISTORY:  rev 0.0.1 
 /**  @ingroup netapi */
 
 /** @defgroup netapi_api_functions NETAPI API's
- *  @ingroup netapi
+ *  @ingroup netapi_api_functions
  */
 
 /**  @ingroup netapi_structures */
 /**
  * @def NETAPI_T
- *  netapi handle:  one per thread
- *  used in most NETAPI calls
+ * @brief  netapi handle:  one per thread
+ *         used in most NETAPI calls
  */
 typedef void * NETAPI_T;
 
@@ -164,39 +164,111 @@ void netapi_shutdown(NETAPI_T  p);
 
 /**  @ingroup netapi_api_functions */
 /*
+
 *  @brief  API returns a @ref 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 used. The memory used for these heaps is
- *            special (alignment, must be contguous, must have a physical2virtual mapping that
- *            is known by NETAPI. Thus it must be completely managed 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: 
+ *               - 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 
  */
 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
 
-/* utilities to see how much mem/descriptor space is remaining */
-int  netapi_getBufmemRemainder(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  
+ *  @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  
+ *  @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.
+ *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
+ *  @retval     NETCP_CFG_FLOW_HANDLE_T  : handle to default flow
+ *  @pre        @ref netapi_init  
+ */
 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 return pp->def_flow;
 }
 
 /* utility to get default route */
+/**  @ingroup netapi_api_functions */
+/*
+*  @brief  API is used to return the default NETCP route
+ *
+ *  @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. 
+ *  @pre        @ref netapi_init  
+ */
 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 return pp->def_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
+ */
 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 
+ *  @param[in]  void * : opaque data to be saved
+ *  @retval     void  
+ *  @pre        @ref netapi_init  
+ */
 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
 {
 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
@@ -218,8 +290,50 @@ 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(). 
+ *
+ *  @details  this function 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
+ *  @param[in]  @ref Pktlib_HeapHandle:  handle of heap to register
+ *  @retval     int :  1 if OK, 0 on error 
+ *  @pre        @ref netapi_init  @ref Pktlib_CreateHeap
+ */
 int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h);
+
+/**  @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(). 
+ *
+ *  @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 
+ *  @retval     0 if err, 1 if OK
+ *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
+ */
 int netapi_unregisterHeap(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
+ *
+ *  @details  this function 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.
+ *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
+ *  @retval     none 
+ *  @pre        @ref netapi_init  @ref pktlib_CreateHeap
+ */
 void netapi_poll_heapGarbage(NETAPI_T p);
 
 #endif