index 82a5d254e8cc8869e51edf9ed284f30050be51de..8a95dfdf648c8a0e702c35164dd50d49fc7800b7 100755 (executable)
-/**************************************************************
- * 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
- * are met:
- *
- * 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
- * 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
- * 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
- * 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
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-*****************************************************************************/
-
-/** @mainpage Network API
- *
- * @section intro Introduction
- *
- * The network API provides a user space interface to TI SOC transport
- * Resources. The library includes:
- * - general startup and setup for user space operations
- * - memory heap and packet buffer management
- * - pktio either to/from network or internal queues
- * - timers for network stacks
- * - netcp (network co-processor) configuration and control
- * - utilities including user space synchronization primitivies
- * - sample scheduling event loop
- *
- * NETAPI allows user space transport to configure control the NETCP:
- * - Classification of packets based on L2: MAC header fields
- * - Classification of packets based on L3: IP header fields
- * - Routing of packets to host based on L4 UDP or L5 GTPU ID
- * - Unidirectional IPSec SA creation and deletion
- * - Unidirectional IPSec Security Policy creation and deletion
- *
- * \par
- * NOTE:
- * (C) Copyright 2010-2011 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 <stdlib.h>
-#include <stddef.h>
-#include <string.h>
-
-/**
- * @defgroup netapi_structures NETAPI data structures
- */
-/** @ingroup netapi */
-
-/** @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
- */
-typedef void * NETAPI_T;
-
-
-#define NETAPI_SYS_MASTER 2 //master for system
-#define NETAPI_CORE_MASTER 1 //master for core
-#define NETAPI_NO_MASTER 0 //data only
-
-/***********************************************
-*************RUN TIME CONTROLS*****************
-***********************************************/
-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
-}NETAPI_CFG_T;
-
-
-
-#include "netapi_err.h"
-#include "netapi_tune.h"
-#include "ti/runtime/pktlib/pktlib_osal.h"
-#include "ti/runtime/pktlib/pktlib.h"
-#include "pktio.h"
-#include "ti/drv/pa/pa.h"
-#include "netcp_cfg.h"
-#include "netapi_sec.h"
-#include "netapi_sched.h"
-#include "src/netapi_vm.h"
-#include "netapi_util.h"
-#include "netsync.h"
-#include "ti/drv/nwal/nwal.h"
-#include "netapi_timer.h"
-#include "src/netapi_loc.h"
-
-/************************************************
- **********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
- *
- * @details Allocates 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
- */
-NETAPI_T netapi_init(int master, NETAPI_CFG_T * p_cfg);
-
-
-/** @ingroup netapi_api_functions */
-/*
-* @brief API shutdowns a previously intialized NETAPI instance
- *
- * @details de-llocates 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
- * @pre @ref netapi_init
- */
-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 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 **/
-
-/** @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) {
-return NETCP_DEFAULT_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) {
-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
- */
-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;
-pp->cookie= cookie;
-}
-
-
-/** @ingroup netapi_api_functions */
-/*
-* @brief API is used to poll for NETCP configuration response messages.
- *
- * @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
- * @retval none
- * @pre @ref netapi_init
- */
-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
- */
-static inline int netapi_registerHeap(NETAPI_T p, Pktlib_HeapHandle h)
-{
-NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
-int i;
-for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
-{
- if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}
-}
-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().
- *
- * @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()
- */
-static inline int netapi_unregisterHeap(NETAPI_T p, Pktlib_HeapHandle h)
-{
-NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
-int i;
-for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
-{
- if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
-}
-return -1; //not found
-}
-
-/** @ingroup netapi_api_functions */
-/*
-* @brief 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
- * @retval <0 if err, 1 if OK
- * @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
- *
- * @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
+/**************************************************************\r
+ * FILE PURPOSE : -----------NETAPI-------------\r
+ * user space access to transport resources on SOC\r
+ **************************************************************\r
+ * @file netapi.h\r
+ * \r
+ * @brief DESCRIPTION: netapi main header file for user space transport\r
+ * library\r
+ * \r
+ * REVISION HISTORY: rev 0.0.1 \r
+ *\r
+ * Copyright (c) Texas Instruments Incorporated 2010-2011\r
+ * \r
+ * Redistribution and use in source and binary forms, with or without \r
+ * modification, are permitted provided that the following conditions \r
+ * are met:\r
+ *\r
+ * Redistributions of source code must retain the above copyright \r
+ * notice, this list of conditions and the following disclaimer.\r
+ *\r
+ * Redistributions in binary form must reproduce the above copyright\r
+ * notice, this list of conditions and the following disclaimer in the \r
+ * documentation and/or other materials provided with the \r
+ * distribution.\r
+ *\r
+ * Neither the name of Texas Instruments Incorporated nor the names of\r
+ * its contributors may be used to endorse or promote products derived\r
+ * from this software without specific prior written permission.\r
+ *\r
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \r
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT \r
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\r
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT \r
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, \r
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT \r
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT \r
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE \r
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
+*****************************************************************************/\r
+\r
+/** @mainpage Network API \r
+ *\r
+ * @section intro Introduction\r
+ *\r
+ * The network API provides a user space interface to TI SOC transport \r
+ * Resources. The library includes:\r
+ * - general startup and setup for user space operations\r
+ * - memory heap and packet buffer management\r
+ * - pktio either to/from network or internal queues\r
+ * - timers for network stacks\r
+ * - netcp (network co-processor) configuration and control\r
+ * - utilities including user space synchronization primitivies\r
+ * - sample scheduling event loop\r
+ *\r
+ * NETAPI allows user space transport to configure control the NETCP:\r
+ * - Classification of packets based on L2: MAC header fields\r
+ * - Classification of packets based on L3: IP header fields\r
+ * - Routing of packets to host based on L4 UDP or L5 GTPU ID\r
+ * - Unidirectional IPSec SA creation and deletion\r
+ * - Unidirectional IPSec Security Policy creation and deletion\r
+ *\r
+ * \par\r
+ * NOTE:\r
+ * (C) Copyright 2010-2011 Texas Instruments, Inc.\r
+ * \par\r
+ */\r
+\r
+/* Define NETAPI as a master group in Doxygen format and add all NETAPI \r
+ definitions to this group. */\r
+/** @defgroup netapi USERSPACE TRANSPORT NETAPI\r
+ * @{\r
+ */\r
+/** @} */\r
+\r
+\r
+#ifndef __NETAPI__H\r
+#define __NETAPI__H\r
+#include <stdint.h>\r
+#include <stdlib.h>\r
+#include <stddef.h>\r
+#include <string.h>\r
+\r
+/**\r
+ * @brief This is the NWAL LLD Version. Versions numbers are encoded in the following \r
+ * format:\r
+ * 0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)\r
+ */\r
+#define NETAPI_VERSION_ID (0x01000002)\r
+\r
+/**\r
+ * @brief This is the version string which describes the NWAL LLD along with the\r
+ * date and build information.\r
+ */\r
+#define NETAPI_VERSION_STR "NETAPI Revision: 01.00.00.02"\r
+\r
+\r
+/**\r
+ * @defgroup netapi_structures NETAPI data structures\r
+ */\r
+/** @ingroup netapi */\r
+\r
+/** @defgroup netapi_api_functions NETAPI API's\r
+ * @ingroup netapi_api_functions\r
+ */\r
+\r
+/** @ingroup netapi_structures */\r
+/**\r
+ * @def NETAPI_T\r
+ * @brief netapi handle: one per thread\r
+ * used in most NETAPI calls\r
+ */\r
+typedef void * NETAPI_T;\r
+\r
+\r
+#define NETAPI_SYS_MASTER 2 //master for system\r
+#define NETAPI_CORE_MASTER 1 //master for core\r
+#define NETAPI_NO_MASTER 0 //data only\r
+\r
+/***********************************************\r
+*************RUN TIME CONTROLS*****************\r
+***********************************************/\r
+typedef struct NETAPI_CFG_Tag\r
+{\r
+ int def_mem_size; //bytes of CMA memory we have allocated \r
+ int def_flow_pkt_rx_offset; //offset in pkt buffer for hw to start RX\r
+ int def_max_descriptors; //# of descriptors in system (must be power of 2), 2^14 max\r
+ int def_tot_descriptors_for_us; //#of descriptors to create in our region (must be power of 2)\r
+ int def_heap_n_descriptors; //# descriptors+buffers in default heap\r
+ int def_heap_n_zdescriptors; //# zero len descriptors in defaule heap\r
+ int def_heap_buf_size; //size of buffers in default heap\r
+ //=MAX amount of area for packet data\r
+ int def_heap_tailroom_size; //size of tailroom in reserve \r
+ int def_heap_extra_size; //size of extra space at end of buffer\r
+}NETAPI_CFG_T;\r
+/* note:\r
+ each buffer will be allocated: def_heap_buf_size+def_heap_extra_size bytes\r
+ each descriptor attached to these buffers will have original_pkt_len of:\r
+ def_heap_buf_size.\r
+ for default RX flow, for rx packet, the bufptr will be def_flow_pkt_rx_offset.\r
+ for detault RX flow, threshold (ie max # of bytes in buffer) will be:\r
+ def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset\r
+*/\r
+\r
+\r
+\r
+#include "netapi_err.h"\r
+#include "netapi_tune.h"\r
+#include "ti/runtime/pktlib/pktlib_osal.h"\r
+#include "ti/runtime/pktlib/pktlib.h"\r
+#include "pktio.h"\r
+#include "ti/drv/pa/pa.h"\r
+#include "netcp_cfg.h"\r
+#include "netapi_sec.h"\r
+#include "netapi_sched.h"\r
+#include "src/netapi_vm.h"\r
+#include "src/netapi_util.h"\r
+#include "netsync.h"\r
+#include "ti/drv/nwal/nwal.h"\r
+#include "netapi_timer.h"\r
+#include "src/netapi_loc.h"\r
+\r
+/************************************************\r
+ **********BUILD TIME CONTROLS *****************\r
+ ***********************************************/\r
+/* see netapi_tune.h */\r
+\r
+\r
+/*************************************\r
+ **************NETAPI****************\r
+ ************************************/\r
+\r
+/** @ingroup netapi_api_functions */\r
+\r
+/*\r
+* @brief API instantiates the NETAPI and allocated global resources and is pre-requisite \r
+ *\r
+ * @details Allocates global resources valid per system level common across all ARM cores \r
+ * or per thread based on "master" argument.\r
+ * Intializes the following substems:\r
+ * - pktio\r
+ * - pktlib\r
+ * - qmss\r
+ * - cppi\r
+ * - nwal\r
+ * @param[in] master mode: NETAPI_SYS_MASTER or NETAPI_NO_MASTER\r
+ * @param[in] configuration (master mode). pointer to NETAPI_CFG_T above or NULL\r
+ * @retval @ref NETAPI_T: handle to the instance or NULL on error \r
+ * @pre none \r
+ */\r
+NETAPI_T netapi_init(int master, NETAPI_CFG_T * p_cfg);\r
+\r
+\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API shutdowns a previously intialized NETAPI instance \r
+ *\r
+ * @details de-llocates global resources valid per system level common across all ARM cores \r
+ * or per thread based on "master" argument passed in at init time.\r
+ * @param[in] @ref NETAPI_T: handle to the instance \r
+ * @retval none \r
+ * @pre @ref netapi_init \r
+ */\r
+void netapi_shutdown(NETAPI_T p);\r
+\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+\r
+* @brief API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps \r
+ *\r
+ * @details Application will need a heapIfTable in order to create its own heaps. This\r
+ * function returns a table that can be passed in the call to @ref Pktlib_CreateHeap\r
+* The memory used for these heaps is special: \r
+ * - specific alignment, \r
+ * - must be contguous, \r
+ * - must have a physical to virtual mapping that\r
+ * - is known by NETAPI. \r
+ * Thus it must be completely managed by NETAPI. This interfaced table provides a\r
+ * malloc function that the pktlib heap library uses to allocate data for the heap\r
+ * buffers.\r
+ * @param[in] none \r
+ * @retval @ref Pktlib_HeapIfTable pointer \r
+ * @pre @ref netapi_init \r
+ */\r
+Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;\r
+\r
+/** utilities to see how much mem/descriptor space is remaining **/\r
+\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to return the amount of free memory available for allocating buffers\r
+ ( for additonal Pktlib heaps. \r
+ * @details the applicaiton can use this API to determine how much free memory is .\r
+ * available for heap buffers if it decides to create its own. \r
+ * @param[in] void \r
+ * @retval int : amount of memory available for heap buffer storage (in bytes)\r
+ * @pre @ref netapi_init \r
+ */\r
+int netapi_getBufMemRemainder(void);\r
+/** @ingroup netapi_api_functions */\r
+\r
+/*\r
+* @brief API is used to return the amount of free memory available for allocating Descriptors \r
+ ( for additonal Pktlib heaps. \r
+ * @details the applicaiton can use this API to determine how much free memory is .\r
+ * available for heap descriptors if it decides to create its own heap. \r
+ * @param[in] void \r
+ * @retval int : amount of memory available for heap descriptor storage (in bytes)\r
+ * @pre @ref netapi_init \r
+ */\r
+int netapi_getDescRemainder(void);\r
+\r
+/* utility to get default flow */\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to return the default NETCP flow that is to be used for received \r
+ ( packets..\r
+ * @details the applicaiton can use this API to return the default NETCP flow that is used \r
+ * for received packets. A NETCP flow is a list of PacketLib Heaps that are to be\r
+ * used to supply free packets to the receive DMA function.\r
+ * @param[in] @ref NETAPI_T handle to NETAPI instance \r
+ * @retval NETCP_CFG_FLOW_HANDLE_T : handle to default flow\r
+ * @pre @ref netapi_init \r
+ */\r
+static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {\r
+return NETCP_DEFAULT_FLOW;\r
+}\r
+\r
+/* utility to get default route */\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to return the default NETCP route\r
+ *\r
+ * @details this functions returns the default NETCP route created by @ref netapi_init. \r
+ * A netcp route consists of a NETCP flow plus a destination pktio channel \r
+ * @param[in] @ref NETAPI_T handle to NETAPI instance \r
+ * @retval NETCP_CFG_ROUTE_HANDLE_T: the handle of the default route. \r
+ * @pre @ref netapi_init \r
+ */\r
+static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {\r
+return NETCP_DEFAULT_ROUTE;\r
+}\r
+\r
+/* utility to set/get a cookie in the netapi handle */\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to return a piece of application-provided opaque data that has been \r
+ ( stored in the netapi instance.\r
+ * @details the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.\r
+ * This APi lets this data be returned to the application.\r
+ * @param[in] @ref NETAPI_T handle to NETAPI instance \r
+ * @retval void * \r
+ * @pre @ref netapi_init @ref netapi_setCookie\r
+ */\r
+static inline void * netapi_getCookie(NETAPI_T p)\r
+{\r
+NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;\r
+return pp->cookie;\r
+}\r
+\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to set a piece of application-provided opaque data in the\r
+ ( netapi instance.\r
+ * @details the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.\r
+ * This APi can be returned later to the application via @ref netapi_getCookie\r
+ * @param[in] @ref NETAPI_T : handle to NETAPI instance \r
+ * @param[in] void * : opaque data to be saved\r
+ * @retval void \r
+ * @pre @ref netapi_init \r
+ */\r
+static inline void netapi_setCookie(NETAPI_T p, void * cookie)\r
+{\r
+NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;\r
+pp->cookie= cookie;\r
+}\r
+\r
+\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to poll for NETCP configuration response messages. \r
+ *\r
+ * @details Application, if controlling the scheduler, will need to call this\r
+ * function periodically to check for NETCP configuration responses (eg\r
+ * statistics requests). \r
+ * @param[in] @ref NETAPI_T handle to NETAPI instance \r
+ * @retval none \r
+ * @pre @ref netapi_init \r
+ */\r
+void netapi_netcpPoll(NETAPI_T p);\r
+\r
+//heap registration for polling purposes\r
+\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to register a heap that is created by application so that\r
+ * it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage(). \r
+ *\r
+ * @details this function registers an application-created heap with the netapi instance\r
+ * so that it can add that heap's garbage queue to the garbage poll function. \r
+ * NOTE: netapi internal heap is automatically registered\r
+ * @param[in] @ref NETAPI_T handle to NETAPI instance\r
+ * @param[in] @ref Pktlib_HeapHandle: handle of heap to register\r
+ * @retval int : 1 if OK, <0 on error \r
+ * @pre @ref netapi_init @ref Pktlib_CreateHeap\r
+ */\r
+static inline int netapi_registerHeap(NETAPI_T p, Pktlib_HeapHandle h)\r
+{\r
+NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;\r
+int i;\r
+for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)\r
+{\r
+ if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}\r
+}\r
+return -1; //no room\r
+}\r
+\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to un-register a heap that was created by application and previously\r
+* registerd so that\r
+ * it's garbage queue could be polled automatically by @ref netapi_poll_heapGarbage(). \r
+ *\r
+ * @details this function un-registers an application-created heap with the netapi instance\r
+ * @param[in] @ref NETAPI_T: handle to NETAPI instance \r
+ * @param[in] @ref Pktlib_HeapHandle : handle to heap \r
+ * @retval <0 if err, 1 if OK\r
+ * @pre @ref netapi_init , @ref Pktlib_CreateHeap, @ref netai_registerHeap()\r
+ */\r
+static inline int netapi_unregisterHeap(NETAPI_T p, Pktlib_HeapHandle h)\r
+{\r
+NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;\r
+int i;\r
+for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)\r
+{\r
+ if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}\r
+}\r
+return -1; //not found\r
+}\r
+\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to remove a created pktlib heap\r
+ *\r
+ * @details this function removes anapplication-created heap with the netapi instance\r
+ * [note -> descriptors are zapped and cannot be reused]\r
+ * @param[in] @ref NETAPI_T: handle to NETAPI instance \r
+ * @param[in] @ref Pktlib_HeapHandle : handle to heap \r
+ * @retval <0 if err, 1 if OK\r
+ * @pre @ref netapi_init , @ref Pktlib_CreateHeap, @ref netai_registerHeap()\r
+ */\r
+\r
+int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);\r
+\r
+/** @ingroup netapi_api_functions */\r
+/*\r
+* @brief API is used to poll the garbage collection queue for the internal NETAPI heaps and \r
+ * any application created heaps\r
+ *\r
+ * @details this function is used to poll the netapi internal heaps and any \r
+ * application-created heaps that have been registered with the netapi instance. The\r
+ * poll function checks the garbage collection queue associated with the heap and returns\r
+ * descriptors and buffers when appropriate to the main free queue.\r
+ * @param[in] @ref NETAPI_T handle to NETAPI instance \r
+ * @retval none \r
+ * @pre @ref netapi_init @ref pktlib_CreateHeap\r
+ */\r
+void netapi_poll_heapGarbage(NETAPI_T p);\r
+\r
+static inline int netapi_get_version(void) {return NETAPI_VERSION_ID;}\r
+static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}\r
+\r
+#endif\r