index 8a95dfdf648c8a0e702c35164dd50d49fc7800b7..ab710e4184d88e8148219a2d69264d18ed2b9eb9 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
- * @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
+/**************************************************************
+ * 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>
+
+/**
+ * @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)
+
+/**
+ * @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"
+
+
+/**
+ * @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
+ //=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"
+
+/************************************************
+ **********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);
+
+static inline int netapi_get_version(void) {return NETAPI_VERSION_ID;}
+static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}
+
+#endif