more cleanup, documentation
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi.h
1 /**************************************************************
2  * FILE PURPOSE :  -----------NETAPI-------------
3  *         user space access to transport resources on SOC
4  **************************************************************
5  * FILE: netapi.h
6  * 
7  * DESCRIPTION:  netapi main header file for user space transport
8  *               library
9  * 
10  * REVISION HISTORY:  rev 0.0.1 
11  *
12  *  Copyright (c) Texas Instruments Incorporated 2010-2011
13  * 
14  *  Redistribution and use in source and binary forms, with or without 
15  *  modification, are permitted provided that the following conditions 
16  *  are met:
17  *
18  *    Redistributions of source code must retain the above copyright 
19  *    notice, this list of conditions and the following disclaimer.
20  *
21  *    Redistributions in binary form must reproduce the above copyright
22  *    notice, this list of conditions and the following disclaimer in the 
23  *    documentation and/or other materials provided with the   
24  *    distribution.
25  *
26  *    Neither the name of Texas Instruments Incorporated nor the names of
27  *    its contributors may be used to endorse or promote products derived
28  *    from this software without specific prior written permission.
29  *
30  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
31  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
32  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
33  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
34  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
35  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
36  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
37  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
38  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
39  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
40  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
41 *****************************************************************************/
43 /**  @mainpage Network API 
44  *
45  *   @section intro  Introduction
46  *
47  *   The network API provides a user space interface to TI SOC transport 
48  *   Resources. The library includes:
49  *      - general startup and setup for user space operations
50  *      - memory heap and packet buffer  management
51  *      - pktio  either to/from network or internal queues
52  *      - timers for network stacks
53  *      - netcp (network co-processor) configuration and control
54  *      - utilities including user space synchronization primitivies
55  *      - sample scheduling event loop
56  *
57  *    NETAPI allows user space transport to configure control the NETCP:
58  *      - Classification of packets based on L2: MAC header fields
59  *      - Classification of packets based on L3: IP header fields
60  *      - Routing of packets to host based on L4 UDP or L5 GTPU ID
61  *      - Unidirectional IPSec SA creation and deletion
62  *      - Unidirectional IPSec Security Policy creation and deletion
63  *
64  *  \par
65  *  NOTE:
66  *      (C) Copyright 2010-2011 Texas Instruments, Inc.
67  *  \par
68  */
70 /* Define NETAPI as a master group in Doxygen format and add all NETAPI 
71    definitions to this group. */
72 /** @defgroup netapi USERSPACE TRANSPORT NETAPI
73  *  @{
74  */
75 /** @} */
78 #ifndef __NETAPI__H
79 #define __NETAPI__H
80 #include <stdint.h>
81 #include <stdlib.h>
82 #include <stddef.h>
83 #include <string.h>
85 /**
86  *   @defgroup netapi_structures  NETAPI data structures
87  */
88 /**  @ingroup netapi */
90 /** @defgroup netapi_api_functions NETAPI API's
91  *  @ingroup netapi
92  */
94 /**  @ingroup netapi_structures */
95 /**
96  * @def NETAPI_T
97  *  netapi handle:  one per thread
98  *  used in most NETAPI calls
99  */
100 typedef void * NETAPI_T;
103 #define NETAPI_SYS_MASTER  2  //master for system
104 #define NETAPI_CORE_MASTER 1  //master for core
105 #define NETAPI_NO_MASTE    0  //data only
108 #include "netapi_err.h"
109 #include "netapi_tune.h"
110 #include "ti/runtime/pktlib/pktlib_osal.h"
111 #include "ti/runtime/pktlib/pktlib.h"
112 #include "pktio.h"
113 #include "ti/drv/pa/pa.h"
114 #include "netcp_cfg.h"
115 #include "netapi_sched.h"
116 #include "src/netapi_vm.h"
117 #include "src/netapi_util.h"
118 #include "netsync.h"
119 #include "ti/drv/nwal/nwal.h"
120 #include "netapi_timer.h"
121 #include "src/netapi_loc.h"
123 /************************************************
124  **********BUILD TIME CONTROLS *****************
125  ***********************************************/
126 /* see netapi_tune.h */
127  
129 /*************************************
130  **************NETAPI****************
131  ************************************/
133 /**  @ingroup netapi_api_functions */
135 /*
136 *  @brief  API instantiates the NETAPI and allocated global resources and is pre-requisite 
137  *
138  *  @details Allocates global resources valid  per system level common across all ARM cores 
139  *   or per thread based on "master" argument.
140  *   Intializes the following substems:
141  *     - pktio
142  *     - pktlib
143  *     - qmss
144  *     - cppi
145  *     - nwal
146  *  @param[in]  master mode: NETAPI_SYS_MASTER or NETAPI_NO_MASTER
147  *  @retval     @ref NETAPI_T: handle to the instance or NULL on error 
148  *  @pre        none 
149  */
150 NETAPI_T  netapi_init(int master);
153 /**  @ingroup netapi_api_functions */
154 /*
155 *  @brief  API shutdowns a previously intialized NETAPI instance 
156  *
157  *  @details de-llocates global resources valid  per system level common across all ARM cores 
158  *   or per thread based on "master" argument passed in at init time.
159  *  @param[in]  @ref NETAPI_T: handle to the instance 
160  *  @retval     none 
161  *  @pre        @ref netapi_init 
162  */
163 void netapi_shutdown(NETAPI_T  p);
165 /**  @ingroup netapi_api_functions */
166 /*
167 *  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps 
168  *
169  *  @details  Application will need a heapIfTable in order to create its own heaps. This
170  *            function returns a table that can be passed in the call to @ref Pktlib_CreateHeap
171 *             The memory used for these heaps is  special: 
172  *               - specific alignment, 
173  *               - must be contguous, 
174  *               - must have a physical to virtual mapping that
175  *               - is known by NETAPI. 
176  *          Thus it must be completely managed by NETAPI. This interfaced table provides a
177  *          malloc function that the pktlib heap library uses to allocate data for the heap
178  *          buffers.
179  *  @param[in]  none 
180  *  @retval     @ref Pktlib_HeapIfTable pointer 
181  *  @pre        @ref netapi_init 
182  */
183 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
185 /** utilities to see how much mem/descriptor space is remaining **/
187 /**  @ingroup netapi_api_functions */
188 /*
189 *  @brief  API is used to return the amount of free memory available for allocating buffers
190  (          for additonal Pktlib heaps.   
191  *  @details  the applicaiton can use this API to determine how much free memory is          .
192  *           available for heap buffers if it decides to create its own.   
193  *  @param[in]  void  
194  *  @retval     int :  amount of memory available for heap buffer storage (in bytes)
195  *  @pre        @ref netapi_init 
196  */
197 int  netapi_getBufmemRemainder(void);
198 /**  @ingroup netapi_api_functions */
200 /*
201 *  @brief  API is used to return the amount of free memory available for allocating Descriptors 
202  (          for additonal Pktlib heaps.   
203  *  @details  the applicaiton can use this API to determine how much free memory is          .
204  *           available for heap descriptors if it decides to create its own heap.   
205  *  @param[in]  void  
206  *  @retval     int :  amount of memory available for heap descriptor storage (in bytes)
207  *  @pre        @ref netapi_init 
208  */
209 int  netapi_getDescRemainder(void);
211 /* utility to get default flow */
212 /**  @ingroup netapi_api_functions */
213 /*
214 *  @brief  API is used to return the default NETCP flow that is to be used for received    
215  (          packets..
216  *  @details  the applicaiton can use this API to return the default NETCP flow that is used  
217  *           for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
218  *           used to supply free packets to the receive DMA function.
219  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
220  *  @retval     NETCP_CFG_FLOW_HANDLE_T  : handle to default flow
221  *  @pre        @ref netapi_init  
222  */
223 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
224 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
225 return pp->def_flow;
228 /* utility to get default route */
229 /**  @ingroup netapi_api_functions */
230 /*
231 *  @brief  API is used to return the default NETCP route
232  *
233  *  @details  this functions returns the default NETCP route created by @ref netapi_init.  
234  *            A netcp route consists of a NETCP flow plus a destination pktio channel 
235  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
236  *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  the handle of the default route. 
237  *  @pre        @ref netapi_init  
238  */
239 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
240 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
241 return pp->def_route;}
243 /* utility to set/get a cookie in the netapi handle */
244 /**  @ingroup netapi_api_functions */
245 /*
246 *  @brief  API is used to return a piece of application-provided opaque data that has been 
247  (          stored in the netapi instance.
248  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
249  *           This APi lets this data be returned to the application.
250  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
251  *  @retval     void * 
252  *  @pre        @ref netapi_init  @ref netapi_setCookie
253  */
254 static inline void * netapi_getCookie(NETAPI_T p)
256 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
257 return pp->cookie;
260 /**  @ingroup netapi_api_functions */
261 /*
262 *  @brief  API is used to set a piece of application-provided opaque data in the
263  (         netapi instance.
264  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
265  *           This APi can be returned later to the application via @ref netapi_getCookie
266  *  @param[in]  @ref NETAPI_T :  handle to NETAPI instance 
267  *  @param[in]  void * : opaque data to be saved
268  *  @retval     void  
269  *  @pre        @ref netapi_init  
270  */
271 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
273 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
274 pp->cookie= cookie;
278 /**  @ingroup netapi_api_functions */
279 /*
280 *  @brief  API is used to poll for NETCP configuration response messages. 
281  *
282  *  @details  Application, if controlling the scheduler,  will need to call this
283  *            function periodically to check for NETCP configuration responses (eg
284  *            statistics requests). 
285  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
286  *  @retval     none 
287  *  @pre        @ref netapi_init 
288  */
289 void netapi_netcpPoll(NETAPI_T  p);
291 //heap registration for polling purposes
293 /**  @ingroup netapi_api_functions */
294 /*
295 *  @brief  API is used to register a heap that is created by application so that
296  *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage(). 
297  *
298  *  @details  this function registers an application-created heap with the netapi instance
299  *            so that it can add that heap's garbage queue to the garbage poll function. 
300  *            NOTE: netapi internal heap is automatically registered
301  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
302  *  @param[in]  @ref Pktlib_HeapHandle:  handle of heap to register
303  *  @retval     int :  1 if OK, 0 on error 
304  *  @pre        @ref netapi_init  @ref Pktlib_CreateHeap
305  */
306 int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h);
308 /**  @ingroup netapi_api_functions */
309 /*
310 *  @brief  API is used to un-register a heap that was created by application and previously
311 *           registerd so that
312  *          it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage(). 
313  *
314  *  @details  this function un-registers an application-created heap with the netapi instance
315  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance 
316  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap 
317  *  @retval     0 if err, 1 if OK
318  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
319  */
320 int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h);
323 /**  @ingroup netapi_api_functions */
324 /*
325 *  @brief  API is used to poll the garbage collection queue for the internal NETAPI heaps and 
326  *         any application created heaps
327  *
328  *  @details  this function is used to poll the netapi internal heaps and any 
329  * application-created heaps    that have been registered with the netapi instance.  The
330  * poll function checks the garbage collection queue associated with the heap and returns
331  * descriptors and buffers when appropriate to the main free queue.
332  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
333  *  @retval     none 
334  *  @pre        @ref netapi_init  @ref pktlib_CreateHeap
335  */
336 void netapi_poll_heapGarbage(NETAPI_T p);
338 #endif