index ab710e4184d88e8148219a2d69264d18ed2b9eb9..1c4d8f986e323a6e7f4bf3f78fc5abd4a64b07eb 100755 (executable)
-/**************************************************************
- * 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
+/******************************************************************************
+ * 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>
+
+
+/* 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 (0x01000003)
+#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.03"
+#define NETAPI_VERSION_STR "NETAPI Revision: 01.00.00.04"
+
/**
- * @defgroup netapi_structures NETAPI data structures
+ * @ingroup netapi_structures
+ * @brief One per thread, used in most NETAPI function calls.
*/
-/** @ingroup netapi */
+typedef void * NETAPI_T;
-/** @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
+ * @brief This defines master for system
*/
-typedef void * NETAPI_T;
+#define NETAPI_SYS_MASTER 2
-
-#define NETAPI_SYS_MASTER 2 //master for system
-#define NETAPI_CORE_MASTER 1 //master for core
+/**
+ * @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
-/***********************************************
-*************RUN TIME CONTROLS*****************
-***********************************************/
+
+/**
+ * @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; //# 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:
+ 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.
#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 and is pre-requisite
*
- * @details Allocates global resources valid per system level common across all ARM cores
+ * @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 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
+ * -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);
-
+ 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
+ * @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
*/
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 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.
+ * 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 @ref Pktlib_HeapIfTable pointer
- * @pre @ref netapi_init
+ * @retval 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
+/**
+ * @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_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
+
+
+/**
+ * @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);
-/* 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.
+/**
+ * @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 : handle to default flow
- * @pre @ref netapi_init
+ * @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 */
-/** @ingroup netapi_api_functions */
-/*
-* @brief API is used to return the default NETCP route
+/**
+ * @ingroup netapi_gen_functions
+ * @brief netapi_getDefaultRoute: API is used to return the default NETCP route handle.
*
- * @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.
+ * @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;
}
-/* 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
+/**
+ * @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_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
+/**
+ * @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 void
- * @pre @ref netapi_init
+ * @retval none
+ * @pre @ref netapi_init
*/
static inline void netapi_setCookie(NETAPI_T p, void * cookie)
{
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
+ * @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
*/
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().
+/**
+ * @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 function registers an application-created heap with the netapi instance
+ * @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
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().
+/**
+ * @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 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
+ * @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()
*/
return -1; //not found
}
-/** @ingroup netapi_api_functions */
-/*
-* @brief API is used to remove a created pktlib heap
+/**
+ * @ingroup netapi_gen_functions
+ * @brief netapi_closeHeap: 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
+ * @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()
+ * @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
+/**
+ * @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 function is used to poll the netapi internal heaps and any
+ * @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.
*/
void netapi_poll_heapGarbage(NETAPI_T p);
-static inline int netapi_get_version(void) {return NETAPI_VERSION_ID;}
+/**
+ * @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