30cbc48a60b5fdda32d412f6d389e7fcc39f9dd4
[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  * @brief 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_api_functions
92  */
94 /**  @ingroup netapi_structures */
95 /**
96  * @def NETAPI_T
97  * @brief  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 /*
168 *  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps 
169  *
170  *  @details  Application will need a heapIfTable in order to create its own heaps. This
171  *            function returns a table that can be passed in the call to @ref Pktlib_CreateHeap
172 *             The memory used for these heaps is  special: 
173  *               - specific alignment, 
174  *               - must be contguous, 
175  *               - must have a physical to virtual mapping that
176  *               - is known by NETAPI. 
177  *          Thus it must be completely managed by NETAPI. This interfaced table provides a
178  *          malloc function that the pktlib heap library uses to allocate data for the heap
179  *          buffers.
180  *  @param[in]  none 
181  *  @retval     @ref Pktlib_HeapIfTable pointer 
182  *  @pre        @ref netapi_init 
183  */
184 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
186 /** utilities to see how much mem/descriptor space is remaining **/
188 /**  @ingroup netapi_api_functions */
189 /*
190 *  @brief  API is used to return the amount of free memory available for allocating buffers
191  (          for additonal Pktlib heaps.   
192  *  @details  the applicaiton can use this API to determine how much free memory is          .
193  *           available for heap buffers if it decides to create its own.   
194  *  @param[in]  void  
195  *  @retval     int :  amount of memory available for heap buffer storage (in bytes)
196  *  @pre        @ref netapi_init 
197  */
198 int  netapi_getBufmemRemainder(void);
199 /**  @ingroup netapi_api_functions */
201 /*
202 *  @brief  API is used to return the amount of free memory available for allocating Descriptors 
203  (          for additonal Pktlib heaps.   
204  *  @details  the applicaiton can use this API to determine how much free memory is          .
205  *           available for heap descriptors if it decides to create its own heap.   
206  *  @param[in]  void  
207  *  @retval     int :  amount of memory available for heap descriptor storage (in bytes)
208  *  @pre        @ref netapi_init 
209  */
210 int  netapi_getDescRemainder(void);
212 /* utility to get default flow */
213 /**  @ingroup netapi_api_functions */
214 /*
215 *  @brief  API is used to return the default NETCP flow that is to be used for received    
216  (          packets..
217  *  @details  the applicaiton can use this API to return the default NETCP flow that is used  
218  *           for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
219  *           used to supply free packets to the receive DMA function.
220  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
221  *  @retval     NETCP_CFG_FLOW_HANDLE_T  : handle to default flow
222  *  @pre        @ref netapi_init  
223  */
224 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
225 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
226 return pp->def_flow;
229 /* utility to get default route */
230 /**  @ingroup netapi_api_functions */
231 /*
232 *  @brief  API is used to return the default NETCP route
233  *
234  *  @details  this functions returns the default NETCP route created by @ref netapi_init.  
235  *            A netcp route consists of a NETCP flow plus a destination pktio channel 
236  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
237  *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  the handle of the default route. 
238  *  @pre        @ref netapi_init  
239  */
240 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
241 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
242 return pp->def_route;}
244 /* utility to set/get a cookie in the netapi handle */
245 /**  @ingroup netapi_api_functions */
246 /*
247 *  @brief  API is used to return a piece of application-provided opaque data that has been 
248  (          stored in the netapi instance.
249  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
250  *           This APi lets this data be returned to the application.
251  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
252  *  @retval     void * 
253  *  @pre        @ref netapi_init  @ref netapi_setCookie
254  */
255 static inline void * netapi_getCookie(NETAPI_T p)
257 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
258 return pp->cookie;
261 /**  @ingroup netapi_api_functions */
262 /*
263 *  @brief  API is used to set a piece of application-provided opaque data in the
264  (         netapi instance.
265  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
266  *           This APi can be returned later to the application via @ref netapi_getCookie
267  *  @param[in]  @ref NETAPI_T :  handle to NETAPI instance 
268  *  @param[in]  void * : opaque data to be saved
269  *  @retval     void  
270  *  @pre        @ref netapi_init  
271  */
272 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
274 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
275 pp->cookie= cookie;
279 /**  @ingroup netapi_api_functions */
280 /*
281 *  @brief  API is used to poll for NETCP configuration response messages. 
282  *
283  *  @details  Application, if controlling the scheduler,  will need to call this
284  *            function periodically to check for NETCP configuration responses (eg
285  *            statistics requests). 
286  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
287  *  @retval     none 
288  *  @pre        @ref netapi_init 
289  */
290 void netapi_netcpPoll(NETAPI_T  p);
292 //heap registration for polling purposes
294 /**  @ingroup netapi_api_functions */
295 /*
296 *  @brief  API is used to register a heap that is created by application so that
297  *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage(). 
298  *
299  *  @details  this function registers an application-created heap with the netapi instance
300  *            so that it can add that heap's garbage queue to the garbage poll function. 
301  *            NOTE: netapi internal heap is automatically registered
302  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
303  *  @param[in]  @ref Pktlib_HeapHandle:  handle of heap to register
304  *  @retval     int :  1 if OK, 0 on error 
305  *  @pre        @ref netapi_init  @ref Pktlib_CreateHeap
306  */
307 int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h);
309 /**  @ingroup netapi_api_functions */
310 /*
311 *  @brief  API is used to un-register a heap that was created by application and previously
312 *           registerd so that
313  *          it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage(). 
314  *
315  *  @details  this function un-registers an application-created heap with the netapi instance
316  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance 
317  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap 
318  *  @retval     0 if err, 1 if OK
319  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
320  */
321 int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h);
324 /**  @ingroup netapi_api_functions */
325 /*
326 *  @brief  API is used to poll the garbage collection queue for the internal NETAPI heaps and 
327  *         any application created heaps
328  *
329  *  @details  this function is used to poll the netapi internal heaps and any 
330  * application-created heaps    that have been registered with the netapi instance.  The
331  * poll function checks the garbage collection queue associated with the heap and returns
332  * descriptors and buffers when appropriate to the main free queue.
333  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
334  *  @retval     none 
335  *  @pre        @ref netapi_init  @ref pktlib_CreateHeap
336  */
337 void netapi_poll_heapGarbage(NETAPI_T p);
339 #endif