/****************************************************************************** * 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 #include #include #include /* 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 NETAPI Configuration Interface * @ingroup netapi */ /** @defgroup cfg_functions NETAPI Configuration Functions * @ingroup netapi_cfg */ /** @defgroup cfg_structures NETAPI Configuration Structures used in API's * @ingroup netapi_cfg */ /** @defgroup cfg_constants NETAPI Configuration Constants * @ingroup netapi_cfg */ /** @defgroup netapi_security NETAPI Security Interface * @ingroup netapi */ /** @defgroup cfg_security_functions NETAPI Security Configuration Functions * @ingroup netapi_security */ /** @defgroup cfg_security_structures NETAPI Security Configuration Structures used in API's * @ingroup netapi_security */ /** @defgroup security_constants NETAPI Security Constants * @ingroup netapi_security */ /** @defgroup netapi_pktio NETAPI PKTIO Interface * @ingroup netapi */ /** @defgroup pktio_functions NETAPI PKTIO Functions * @ingroup netapi_pktio */ /** @defgroup pktio_structures NETAPI PKTIO Structures used in API's * @ingroup netapi_pktio */ /** @defgroup pktio_constants NETAPI PKTIO Constants * @ingroup netapi_pktio */ /** @defgroup netapi_scheduler NETAPI Scheduler Interface * @ingroup netapi */ /** @defgroup sched_functions NETAPI Scheduler Functions * @ingroup netapi_scheduler */ /** @defgroup sched_structures NETAPI Scheduler Structures used in API's * @ingroup netapi_scheduler */ /** @defgroup sched_constants NETAPI Scheduler Constants * @ingroup netapi_scheduler */ /** @defgroup netapi_cb_functions NETAPI Callback Functions * @ingroup netapi */ /** @defgroup tune_parameters NETAPI Tune Parameters * @ingroup netapi */ /** * @def NETAPI_VERSION_ID * This is the NETAPI Version. Versions numbers are encoded in the following * format: * 0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD) */ #define NETAPI_VERSION_ID (0x01000004) /** * @def NETAPI_VERSION_STR * This is the version string which describes the NETAPI along with the * date and build information. */ #define NETAPI_VERSION_STR "NETAPI Revision: 01.00.00.04" /** * @ingroup cfg_constants * @brief One per thread, used in most NETAPI function calls. */ typedef void * NETAPI_T; /** * @def NETAPI_SYS_MASTER * This defines master for system */ #define NETAPI_SYS_MASTER 2 /** * @def NETAPI_CORE_MASTER * This defines master for core */ #define NETAPI_CORE_MASTER 1 /** * @def NETAPI_NO_MASTER * This defines no mater, data only */ #define NETAPI_NO_MASTER 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_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. * * @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 pklib 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 @ref NETAPI_CFG_T or NULL to use netapi default configuration. * @retval Handle to the instance or NULL on error, @ref NETAPI_T * @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] p The NETAPI handle, @ref NETAPI_T * @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 Pktlib_CreateHeap * The memory used for these heaps is special with the following characteristics: * - 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. * @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. * @retval 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. * @retval 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] p The NETAPI handle, @ref NETAPI_T * @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] p The NETAPI handle, @ref NETAPI_T * @retval The handle of the default route, NETCP_CFG_ROUTE_HANDLE_T * @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] p The NETAPI handle, @ref NETAPI_T * @retval 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. * Pointer to a opaque data can be returned later to the application via @ref netapi_getCookie * @param[in] p The NETAPI handle, @ref NETAPI_T * @param[in] cookie 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] p The NETAPI handle, @ref NETAPI_T * @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] p The NETAPI handle, @ref NETAPI_T * @param[in] h Handle of pklib heap to register * @retval 1 if OK, <0 on error * @pre @ref netapi_init */ static inline int netapi_registerHeap(NETAPI_T p, Pktlib_HeapHandle h) { NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p; int i; for(i=0;icreatedHeaps[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 The NETAPI handle, @ref NETAPI_T * @param[in] h The pklib handle to heap * @retval <0 if err, 1 if OK * @pre @ref netapi_init , @ref netapi_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;icreatedHeaps[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 The NETAPI handle, @ref NETAPI_T * @param[in] h : handle to pklib heap * @retval <0 if err, 1 if OK * @pre @ref netapi_init @ref netapi_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] p The NETAPI handle, @ref NETAPI_T * @retval none * @pre @ref netapi_init */ void netapi_poll_heapGarbage(NETAPI_T p); /** * @ingroup netapi_gen_functions * @brief netapi_get_version API used to get version of NETAPI * * @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 NETAPI * * @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