Additional doxygen updates
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi.h
1 /******************************************************************************
2  * FILE PURPOSE:  User space access to transport resources on SOC
3  ******************************************************************************
4  * FILE NAME:   netapi.h
5  *
6  * DESCRIPTION: NETAPI definitions and data structures
7  *
8  * REVISION HISTORY: rev 0.0.1 
9  *
10  *  Copyright (c) Texas Instruments Incorporated 2010-2012
11  *
12  *  Redistribution and use in source and binary forms, with or without
13  *  modification, are permitted provided that the following conditions
14  *  are met:
15  *
16  *    Redistributions of source code must retain the above copyright
17  *    notice, this list of conditions and the following disclaimer.
18  *
19  *    Redistributions in binary form must reproduce the above copyright
20  *    notice, this list of conditions and the following disclaimer in the
21  *    documentation and/or other materials provided with the
22  *    distribution.
23  *
24  *    Neither the name of Texas Instruments Incorporated nor the names of
25  *    its contributors may be used to endorse or promote products derived
26  *    from this software without specific prior written permission.
27  *
28  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
31  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
32  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
33  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
34  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
38  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39  *
40  */
41 /* ============================================================= */
42 /**
43  *   @file  netapi.h
44  *
45  *   path  ti/runtime/netapi/netapi.h
46  *
47  *   @brief  Netapi main header file for user space transport library
48  *
49  */
51 /**  @mainpage Network API 
52  *
53  *   @section intro  Introduction
54  *
55  *   The network API provides a user space interface to TI SOC transport 
56  *   Resources. The library includes:
57  *      - general startup and setup for user space operations
58  *      - memory heap and packet buffer  management
59  *      - pktio  either to/from network or internal queues
60  *      - timers for network stacks
61  *      - netcp (network co-processor) configuration and control
62  *      - utilities including user space synchronization primitivies
63  *      - sample scheduling event loop
64  *
65  *    NETAPI allows user space transport to configure control the NETCP:
66  *      - Classification of packets based on L2: MAC header fields
67  *      - Classification of packets based on L3: IP header fields
68  *      - Routing of packets to host based on L4 UDP or L5 GTPU ID
69  *      - Unidirectional IPSec SA creation and deletion
70  *      - Unidirectional IPSec Security Policy creation and deletion
71  *
72  *  \par
73  *  NOTE:
74  *      (C) Copyright 2010-2012 Texas Instruments, Inc.
75  *  \par
76  */
78 #ifndef __NETAPI__H
79 #define __NETAPI__H
80 #include <stdint.h>
81 #include <stdlib.h>
82 #include <stddef.h>
83 #include <string.h>
87 /* Define NETAPI as a master group in Doxygen format and
88  * add all NETAPI
89  * definitions to this group.
90  */
91 /** @defgroup netapi Network API
92  *  @{
93  */
94 /** @} */
100 /** @defgroup netapi_gen_functions NETAPI General Functions
101  *  @ingroup netapi
102  */
105 /** @defgroup netapi_cfg NETAPI Configuration Interface
106  *  @ingroup netapi
107  */
108 /** @defgroup cfg_functions NETAPI Configuration Functions
109  *  @ingroup netapi_cfg
110  */
112 /** @defgroup cfg_structures NETAPI Configuration Structures used in API's
113  *  @ingroup netapi_cfg
114  */
116 /** @defgroup cfg_constants NETAPI Configuration Constants
117  *  @ingroup netapi_cfg
118  */
120 /** @defgroup netapi_security NETAPI Security Interface
121  *  @ingroup netapi
122  */
124 /** @defgroup cfg_security_functions NETAPI Security Configuration Functions
125  *  @ingroup netapi_security
126  */
128 /** @defgroup cfg_security_structures NETAPI Security Configuration Structures used in API's
129  *  @ingroup netapi_security
130  */
133 /** @defgroup security_constants NETAPI Security Constants
134  *  @ingroup netapi_security
135  */
137 /** @defgroup netapi_pktio NETAPI PKTIO Interface
138  *  @ingroup netapi
139  */
141 /** @defgroup pktio_functions NETAPI PKTIO Functions
142  *  @ingroup netapi_pktio
143  */
145 /** @defgroup pktio_structures NETAPI PKTIO Structures used in API's
146  *  @ingroup netapi_pktio
147  */
149 /** @defgroup pktio_constants NETAPI PKTIO Constants
150  *  @ingroup netapi_pktio
151  */
153 /** @defgroup netapi_scheduler NETAPI Scheduler Interface
154  *  @ingroup netapi
155  */
157 /** @defgroup sched_functions NETAPI Scheduler Functions
158  *  @ingroup netapi_scheduler
159  */
161 /** @defgroup sched_structures NETAPI Scheduler Structures used in API's
162  *  @ingroup netapi_scheduler
163  */
165 /** @defgroup sched_constants NETAPI Scheduler Constants
166  *  @ingroup netapi_scheduler
167  */
169 /** @defgroup netapi_cb_functions NETAPI Callback Functions
170  *  @ingroup netapi
171  */
173 /** @defgroup tune_parameters NETAPI Tune Parameters
174  *  @ingroup netapi
175  */
178 /**
179  * @def NETAPI_VERSION_ID
180  *      This is the NETAPI Version. Versions numbers are encoded in the following 
181  *      format:
182  *              0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)
183  */
184 #define NETAPI_VERSION_ID                   (0x01000004)
186 /**
187  * @def NETAPI_VERSION_STR
188  *      This is the version string which describes the NETAPI along with the
189  *      date and build information.
190  */
191 #define NETAPI_VERSION_STR      "NETAPI Revision: 01.00.00.04"
194 /**
195  * @ingroup cfg_constants
196  * @brief  One per thread, used in most NETAPI function calls.
197  */
198 typedef void * NETAPI_T;
201 /**
202  * @def NETAPI_SYS_MASTER
203  *      This defines master for system
204  */
205 #define NETAPI_SYS_MASTER  2  
207 /**
208  * @def NETAPI_CORE_MASTER
209  *      This defines master for core
210  */
211 #define NETAPI_CORE_MASTER 1  
213 /**
214  * @def  NETAPI_NO_MASTER
215  *      This defines no mater, data only
216  */
217 #define NETAPI_NO_MASTER   0  //data only
219 #include "netapi_err.h"
220 #include "netapi_tune.h"
221 #include "ti/runtime/pktlib/pktlib_osal.h"
222 #include "ti/runtime/pktlib/pktlib.h"
223 #include "pktio.h"
224 #include "ti/drv/pa/pa.h"
225 #include "netcp_cfg.h"
226 #include "netapi_sec.h"
227 #include "netapi_sched.h"
228 #include "src/netapi_vm.h"
229 #include "netapi_util.h"
230 #include "netsync.h"
231 #include "ti/drv/nwal/nwal.h"
232 #include "netapi_timer.h"
233 #include "src/netapi_loc.h"
235 /**
236  *  @ingroup netapi_gen_functions
237  *  @brief netapi_init  API instantiates the NETAPI and allocated global resources.
238  *
239  *  @details The API will allocate global resources valid  per system level common across all ARM cores 
240  *           or per thread based on "master" argument.
241  *           Intializes the following substems: pktio pklib qmss cppi nwal
242  *
243  *  @param[in]  master  Can be either @ref NETAPI_SYS_MASTER or @ref NETAPI_NO_MASTER
244  *  @param[in]  p_cfg   (master mode)  pointer to @ref NETAPI_CFG_T or NULL to use netapi default configuration.
245  *  @retval     Handle to the instance or NULL on error, @ref NETAPI_T
246  *  @pre        none
247  */
248  NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);
250 /**
251  *  @ingroup netapi_gen_functions
252  *  @brief netapi_shutdown  API de-allocates all global resources allocated as part of @ref netapi_init
253  *
254  *  @details De-allocates global resources valid  per system level common across all ARM cores 
255  *           or per thread based on "master" argument passed in at init time.
256  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
257  *  @retval     none 
258  *  @pre        @ref netapi_init 
259  */
260 void netapi_shutdown(NETAPI_T  p);
262 /**
263  *  @ingroup netapi_gen_functions
264  *  @brief netapi_getPktlibIfTable  API returns a Pktlib_HeapIfTable to use when creating pktlib heaps
265  *
266  *  @details Application will need a heapIfTable in order to create its own heaps. This
267  *           function returns a table that can be passed in the call to Pktlib_CreateHeap
268  *           The memory used for these heaps is  special with the following characteristics: 
269  *             - Specific alignment.
270  *             - Must be contguous.
271  *             - Must have a physical to virtual mapping that  is known by NETAPI. 
272  *           Thus it must be completely managed by NETAPI. This interfaced table provides a
273  *           malloc function that the pktlib heap library uses to allocate data for the heap
274  *           buffers.
275  *  @retval     Pktlib_HeapIfTable pointer 
276  *  @pre        @ref netapi_init 
277  */
278 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
280 /**
281  *  @ingroup netapi_gen_functions
282  *  @brief netapi_getBufMemRemainder  API is used to return the amount of free memory available for allocating buffers
283  *                                    for additonal Pktlib heaps
284  *
285  *  @details The application can use this API to determine how much free memory is
286  *           available for heap buffers if it decides to create its own.   
287  *  @retval     Amount of memory available for heap buffer storage (in bytes)
288  *  @pre        @ref netapi_init 
289  */
290 int  netapi_getBufMemRemainder(void);
293 /**
294  *  @ingroup netapi_gen_functions
295  *  @brief netapi_getDescRemainder  API is used to return the amount of free memory available for allocating descriptors 
296  *                                  for additonal Pktlib heaps.
297  *
298  *  @details The application can use this API to determine how much free memory is
299  *           available for heap descriptors if it decides to create its own heap.
300  *  @retval     Amount of memory available for heap descriptor storage (in bytes)
301  *  @pre        @ref netapi_init 
302  */
303 int  netapi_getDescRemainder(void);
305 /**
306  *  @ingroup netapi_gen_functions
307  *  @brief netapi_getDefaultFlow:  API is used to return the default NETCP flow that is to be used for incoming packets.
308  *
309  *  @details   The application can use this API to return the default NETCP flow that is used  
310  *             for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
311  *             used to supply free packets to the receive DMA function.
312  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
313  *  @retval     NETCP_CFG_FLOW_HANDLE_T     The handle to default flow
314  *  @pre        @ref netapi_init 
315  */
316 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p)
318     return NETCP_DEFAULT_FLOW;
321 /**
322  *  @ingroup netapi_gen_functions
323  *  @brief netapi_getDefaultRoute:  API is used to return the default NETCP route handle.
324  *
325  *  @details This API returns the default NETCP route created by @ref netapi_init.
326  *           A netcp route consists of a NETCP flow plus a destination pktio channel 
327  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
328  *  @retval     The handle of the default route, NETCP_CFG_ROUTE_HANDLE_T
329  *  @pre        @ref netapi_init  
330  */
331 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p)
333     return NETCP_DEFAULT_ROUTE;
336 /**
337  *  @ingroup netapi_gen_functions
338  *  @brief netapi_getCookie  API is used to return a piece of application-provided opaque data that has been
339  *                           stored in the netapi instance.
340  *
341  *  @details The application can save a pointer to opaque data in the @ref NETAPI_T instance.
342  *           This APi lets this data be returned to the application.
343  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
344  *  @retval     Data provided in @ref netapi_setCookie
345  *  @pre        @ref netapi_init, @ref netapi_setCookie
346  */
348 static inline void * netapi_getCookie(NETAPI_T p)
350     NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
351     return pp->cookie;
354 /**
355  *  @ingroup netapi_gen_functions
356  *  @brief netapi_setCookie  API is used to set a piece of application-provided opaque data t in the netapi instance.
357  *
358  *  @details The applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
359  *           Pointer to a opaque data can be returned later to the application via @ref netapi_getCookie
360  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
361  *  @param[in]  cookie Opaque data to be saved
362  *  @retval     none
363  *  @pre        @ref netapi_init
364  */
365 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
367     NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
368     pp->cookie= cookie;
371 /**
372  *  @ingroup netapi_gen_functions
373  *  @brief netapi_netcpPoll  API is used to poll for NETCP configuration response messages.
374  *
375  *  @details Application, if controlling the scheduler,  will need to call this
376  *           function periodically to check for NETCP configuration responses (eg
377  *           statistics requests). 
378  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
379  *  @retval     none 
380  *  @pre        @ref netapi_init 
381  */
382 void netapi_netcpPoll(NETAPI_T  p);
384 /**
385  *  @ingroup netapi_gen_functions
386  *  @brief netapi_registerHeap  API is used to register a heap that is created by application so that
387  *                              it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage().
388  *
389  *  @details This API registers an application-created heap with the netapi instance
390  *           so that it can add that heap's garbage queue to the garbage poll function. 
391  *           NOTE: netapi internal heap is automatically registered
392  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
393  *  @param[in]  h   Handle of pklib heap to register
394  *  @retval     1 if OK, <0 on error 
395  *  @pre        @ref netapi_init
396  */
397 static inline int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h)
399 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
400 int i;
401 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
403         if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}
405 return -1;  //no room
408 /**
409  *  @ingroup netapi_gen_functions
410  *  @brief netapi_unregisterHeap  API is used to un-register a heap that was created by application 
411  *                                and previously registerd so that it's garbage queue could  be polled 
412  *                                automatically by @ref netapi_poll_heapGarbage(). 
413  *
414  *  @details This API un-registers an application-created heap with the netapi instance. 
415  *           NOTE: netapi internal heap is automatically registered
416  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
417  *  @param[in]  h   The pklib handle to heap 
418  *  @retval     <0 if err, 1 if OK
419  *  @pre        @ref netapi_init , @ref netapi_registerHeap()
420  */
421 static inline int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h)
423 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
424 int i;
425 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
427         if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
429 return -1;  //not found
432 /**
433  *  @ingroup netapi_gen_functions
434  *  @brief netapi_closeHeap  API is used to remove a created pktlib heap
435  *
436  *  @details This API removes anapplication-created heap with the netapi instance
437  *           NOTE: descriptors are zapped and cannot be reused]
438  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
439  *  @param[in]  h :  handle to pklib heap 
440  *  @retval     <0 if err, 1 if OK
441  *  @pre        @ref netapi_init  @ref netapi_registerHeap
442  */
443 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
445 /**
446  *  @ingroup netapi_gen_functions
447  *  @brief netapi_poll_heapGarbage  API is used to poll the garbage collection queue for 
448  *                                  the internal NETAPI heaps and any application created heaps.
449  *
450  *  @details  This API is used to poll the netapi internal heaps and any 
451  *            application-created heaps    that have been registered with the netapi instance. The
452  *            poll function checks the garbage collection queue associated with the heap and returns
453  *            descriptors and buffers when appropriate to the main free queue.
454  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
455  *  @retval     none 
456  *  @pre        @ref netapi_init
457  */
458 void netapi_poll_heapGarbage(NETAPI_T p);
460 /**
461  *  @ingroup netapi_gen_functions
462  *  @brief netapi_get_version  API used to get version of NETAPI 
463  *
464  *  @details This  API used to get version of netapi
465  *  @retval     int version of netapi
466  *  @pre        @ref netapi_init
467  */
468 static inline int netapi_get_version(void)
470 return NETAPI_VERSION_ID;
473 /**
474  *  @ingroup netapi_gen_functions
475  *  @brief netapi_get_version_string  API used to get version string of NETAPI 
476  *
477  *  @details This  API used to get version string of netapi
478  *  @retval     char version string of netapi
479  *  @pre        @ref netapi_init
480  */
481 static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}
483 #endif