-/**************************************************************
- * FILE PURPOSE : -----------NETAPI-------------
- * user space access to transport resources on SOC
- **************************************************************
- * FILE: netapi.h
- *
- * 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
+/******************************************************************************
+ * 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
+ * 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
+ * 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
+ * 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
+ * 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
+ * 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
*
*
* \par
* NOTE:
- * (C) Copyright 2010-2011 Texas Instruments, Inc.
+ * (C) Copyright 2010-2012 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 <stddef.h>
#include <string.h>
-/**
- * @defgroup netapi_structures NETAPI data structures
+
+
+/* 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
*/
-/** @ingroup netapi */
-/** @defgroup netapi_api_functions NETAPI API's
+/** @defgroup cfg_constants NETAPI Configuration Constants
+ * @ingroup netapi_cfg
+ */
+
+/** @defgroup netapi_security NETAPI Security Interface
* @ingroup netapi
*/
-/** @ingroup netapi_structures */
+/** @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"
+
+
/**
- * @def NETAPI_T
- * netapi handle: one per thread
- * used in most NETAPI calls
+ * @ingroup cfg_constants
+ * @brief One per thread, used in most NETAPI function 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
+/**
+ * @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 "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 "src/netapi_util.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
+/**
+ * @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
*
- * @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
+ * @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_T netapi_init(int master, NETAPI_CFG_T * p_cfg);
-/** @ingroup netapi_api_functions */
-/*
-* @brief API shutdowns a previously intialized NETAPI instance
+/**
+ * @ingroup netapi_gen_functions
+ * @brief netapi_shutdown API de-allocates all global resources allocated as part of @ref netapi_init
*
- * @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
+ * @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_api_functions */
-/*
-* @brief API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps
+/**
+ * @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 used. The memory used for these heaps is
- * special (alignment, must be contguous, must have a physical2virtual mapping that
- * is known by NETAPI. Thus it must be completely managed by NETAPI.
- * @param[in] none
- * @retval @ref Pktlib_HeapIfTable pointer
+ * @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) ;
-/* utilities to see how much mem/descriptor space is remaining */
-int netapi_getBufmemRemainder(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);
-/* utility to get default flow */
-static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
-NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
-return pp->def_flow;
+/**
+ * @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;
}
-/* utility to get default route */
-static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
-NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
-return pp->def_route;}
+/**
+ * @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
+ */
-/* utility to set/get a cookie in the netapi handle */
static inline void * netapi_getCookie(NETAPI_T p)
{
-NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
-return pp->cookie;
+ 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;
+ 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.
+/**
+ * @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
+ * @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);
-//heap registration for polling purposes
-int netapi_registerHeap(NETAPI_T p, Pktlib_HeapHandle h);
-int netapi_unregisterHeap(NETAPI_T p, Pktlib_HeapHandle h);
+/**
+ * @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;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 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;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 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