/************************************************************** * 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 #include #include #include /** * @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_MASTE 0 //data only #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_sched.h" #include "src/netapi_vm.h" #include "src/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 * @retval @ref NETAPI_T: handle to the instance or NULL on error * @pre none */ NETAPI_T netapi_init(int master); /** @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) { NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p; return pp->def_flow; } /* utility to get default route */ /** @ingroup netapi_api_functions */ /* * @brief API is used to return the default NETCP route * * @details this functions returns the default NETCP route created by @ref netapi_init. * A netcp route consists of a NETCP flow plus a destination pktio channel * @param[in] @ref NETAPI_T handle to NETAPI instance * @retval NETCP_CFG_ROUTE_HANDLE_T: the handle of the default route. * @pre @ref netapi_init */ static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) { NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p; return pp->def_route;} /* utility to set/get a cookie in the netapi handle */ /** @ingroup netapi_api_functions */ /* * @brief API is used to return a piece of application-provided opaque data that has been ( stored in the netapi instance. * @details the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance. * This APi lets this data be returned to the application. * @param[in] @ref NETAPI_T handle to NETAPI instance * @retval void * * @pre @ref netapi_init @ref netapi_setCookie */ static inline void * netapi_getCookie(NETAPI_T p) { NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p; return pp->cookie; } /** @ingroup netapi_api_functions */ /* * @brief API is used to set a piece of application-provided opaque data in the ( netapi instance. * @details the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance. * This APi can be returned later to the application via @ref netapi_getCookie * @param[in] @ref NETAPI_T : handle to NETAPI instance * @param[in] void * : opaque data to be saved * @retval void * @pre @ref netapi_init */ static inline void netapi_setCookie(NETAPI_T p, void * cookie) { NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p; 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 */ int netapi_registerHeap(NETAPI_T p, Pktlib_HeapHandle h); /** @ingroup netapi_api_functions */ /* * @brief API is used to un-register a heap that was created by application and previously * registerd so that * it's garbage queue could be polled automatically by @ref netapi_poll_heapGarbage(). * * @details this function un-registers an application-created heap with the netapi instance * @param[in] @ref NETAPI_T: handle to NETAPI instance * @param[in] @ref Pktlib_HeapHandle : handle to heap * @retval 0 if err, 1 if OK * @pre @ref netapi_init , @ref Pktlib_CreateHeap, @ref netai_registerHeap() */ int netapi_unregisterHeap(NETAPI_T p, Pktlib_HeapHandle h); /** @ingroup netapi_api_functions */ /* * @brief API is used to poll the garbage collection queue for the internal NETAPI heaps and * any application created heaps * * @details this function is used to poll the netapi internal heaps and any * application-created heaps that have been registered with the netapi instance. The * poll function checks the garbage collection queue associated with the heap and returns * descriptors and buffers when appropriate to the main free queue. * @param[in] @ref NETAPI_T handle to NETAPI instance * @retval none * @pre @ref netapi_init @ref pktlib_CreateHeap */ void netapi_poll_heapGarbage(NETAPI_T p); #endif