index fdce74ccc3be2e3220463fbed1cc3a353deb3230..485973868c7038d2423ddb381589262f154cacd3 100755 (executable)
-/**************************************************************\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
- * @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_MASTE 0 //data only\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
- * @retval @ref NETAPI_T: handle to the instance or NULL on error \r
- * @pre none \r
- */\r
-NETAPI_T netapi_init(int master);\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
-#endif\r
+/******************************************************************************
+ * 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
+ * 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.
+ *
+ */
+/* ============================================================= */
+/**
+ * @file netapi.h
+ *
+ * path ti/runtime/netapi/netapi.h
+ *
+ * @brief Netapi main header file for user space transport library
+ *
+ */
+
+/** @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-2012 Texas Instruments, Inc.
+ * \par
+ */
+
+#ifndef __NETAPI__H
+#define __NETAPI__H
+#include <stdint.h>
+#include <stdlib.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 (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.04"
+
+
+
+/**
+ * @ingroup netapi_structures
+ * @brief One per thread, used in most NETAPI function calls.
+ */
+typedef void * NETAPI_T;
+
+
+/**
+ * @brief This defines master for system
+ */
+#define NETAPI_SYS_MASTER 2
+
+/**
+ * @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
+
+
+/**
+ * @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; /**< 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.
+ for default RX flow, for rx packet, the bufptr will be def_flow_pkt_rx_offset.
+ for detault RX flow, threshold (ie max # of bytes in buffer) will be:
+ def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset
+
+
+ RX Packet from NetCP
+
+Headroom [Application] Packet [HW] Tailroom [Application] Extra Space [Application]
+<-----------------------><--------------------------><------------------------><----------------------->
+
+Cppi_HostDesc->origBufferLen
+<----------------------------------------------------------------------------->
+Cppi_HostDesc->origBuffPtr
+|
+\/
+|------------def_heap_buf_size-------------------------------------------------|--def_heap_extra_size--|
+| def_flow_pkt_rx_offset| max Cppi_HostDesc->buffLen | def_heap_tailroom_size | Extra Size |
+ ^
+ |
+ Cppi_HostDesc->buffPtr
+
+
+*/
+
+
+
+#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"
+
+/**
+ * @ingroup netapi_gen_functions
+ * @brief netapi_init: API instantiates the NETAPI and allocated global resources and is pre-requisite
+ *
+ * @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 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);
+
+/**
+ * @ingroup netapi_gen_functions
+ * @brief netapi_shutdown: API De-allocates all global resources allocated as part of @ref netapi_init
+ *
+ * @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
+ * @pre @ref netapi_init
+ */
+void netapi_shutdown(NETAPI_T p);
+
+/**
+ * @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 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 Pktlib_HeapIfTable pointer
+ * @pre @ref netapi_init
+ */
+Pktlib_HeapIfTable *netapi_getPktlibIfTable(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_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);
+
+/**
+ * @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 : 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;
+}
+
+/**
+ * @ingroup netapi_gen_functions
+ * @brief netapi_getDefaultRoute: API is used to return the default NETCP route handle.
+ *
+ * @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;
+}
+
+/**
+ * @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_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 none
+ * @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_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
+ * 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);
+
+/**
+ * @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 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
+ * @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_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 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()
+ */
+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_gen_functions
+ * @brief netapi_closeHeap: API is used to remove a created pktlib 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
+ */
+int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
+
+/**
+ * @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 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.
+ * @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);
+
+/**
+ * @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