added version string/id
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi.h
1 /**************************************************************\r
2  * FILE PURPOSE :  -----------NETAPI-------------\r
3  *         user space access to transport resources on SOC\r
4  **************************************************************\r
5  * @file netapi.h\r
6  * \r
7  * @brief DESCRIPTION:  netapi main header file for user space transport\r
8  *               library\r
9  * \r
10  * REVISION HISTORY:  rev 0.0.1 \r
11  *\r
12  *  Copyright (c) Texas Instruments Incorporated 2010-2011\r
13  * \r
14  *  Redistribution and use in source and binary forms, with or without \r
15  *  modification, are permitted provided that the following conditions \r
16  *  are met:\r
17  *\r
18  *    Redistributions of source code must retain the above copyright \r
19  *    notice, this list of conditions and the following disclaimer.\r
20  *\r
21  *    Redistributions in binary form must reproduce the above copyright\r
22  *    notice, this list of conditions and the following disclaimer in the \r
23  *    documentation and/or other materials provided with the   \r
24  *    distribution.\r
25  *\r
26  *    Neither the name of Texas Instruments Incorporated nor the names of\r
27  *    its contributors may be used to endorse or promote products derived\r
28  *    from this software without specific prior written permission.\r
29  *\r
30  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \r
31  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT \r
32  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\r
33  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT \r
34  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, \r
35  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT \r
36  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
37  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
38  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT \r
39  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE \r
40  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
41 *****************************************************************************/\r
42 \r
43 /**  @mainpage Network API \r
44  *\r
45  *   @section intro  Introduction\r
46  *\r
47  *   The network API provides a user space interface to TI SOC transport \r
48  *   Resources. The library includes:\r
49  *      - general startup and setup for user space operations\r
50  *      - memory heap and packet buffer  management\r
51  *      - pktio  either to/from network or internal queues\r
52  *      - timers for network stacks\r
53  *      - netcp (network co-processor) configuration and control\r
54  *      - utilities including user space synchronization primitivies\r
55  *      - sample scheduling event loop\r
56  *\r
57  *    NETAPI allows user space transport to configure control the NETCP:\r
58  *      - Classification of packets based on L2: MAC header fields\r
59  *      - Classification of packets based on L3: IP header fields\r
60  *      - Routing of packets to host based on L4 UDP or L5 GTPU ID\r
61  *      - Unidirectional IPSec SA creation and deletion\r
62  *      - Unidirectional IPSec Security Policy creation and deletion\r
63  *\r
64  *  \par\r
65  *  NOTE:\r
66  *      (C) Copyright 2010-2011 Texas Instruments, Inc.\r
67  *  \par\r
68  */\r
69 \r
70 /* Define NETAPI as a master group in Doxygen format and add all NETAPI \r
71    definitions to this group. */\r
72 /** @defgroup netapi USERSPACE TRANSPORT NETAPI\r
73  *  @{\r
74  */\r
75 /** @} */\r
76 \r
77 \r
78 #ifndef __NETAPI__H\r
79 #define __NETAPI__H\r
80 #include <stdint.h>\r
81 #include <stdlib.h>\r
82 #include <stddef.h>\r
83 #include <string.h>\r
84 \r
85 /**\r
86  * @brief   This is the NWAL LLD Version. Versions numbers are encoded in the following \r
87  * format:\r
88  *  0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)\r
89  */\r
90 #define NETAPI_VERSION_ID                   (0x01000002)\r
91 \r
92 /**\r
93  * @brief   This is the version string which describes the NWAL LLD along with the\r
94  * date and build information.\r
95  */\r
96 #define NETAPI_VERSION_STR      "NETAPI Revision: 01.00.00.02"\r
97 \r
98 \r
99 /**\r
100  *   @defgroup netapi_structures  NETAPI data structures\r
101  */\r
102 /**  @ingroup netapi */\r
103 \r
104 /** @defgroup netapi_api_functions NETAPI API's\r
105  *  @ingroup netapi_api_functions\r
106  */\r
107 \r
108 /**  @ingroup netapi_structures */\r
109 /**\r
110  * @def NETAPI_T\r
111  * @brief  netapi handle:  one per thread\r
112  *         used in most NETAPI calls\r
113  */\r
114 typedef void * NETAPI_T;\r
115 \r
116 \r
117 #define NETAPI_SYS_MASTER  2  //master for system\r
118 #define NETAPI_CORE_MASTER 1  //master for core\r
119 #define NETAPI_NO_MASTER   0  //data only\r
120 \r
121 /***********************************************\r
122 *************RUN TIME CONTROLS*****************\r
123 ***********************************************/\r
124 typedef struct NETAPI_CFG_Tag\r
125 {\r
126  int def_mem_size;             //bytes of CMA memory we have allocated \r
127  int def_flow_pkt_rx_offset;   //offset in pkt buffer for hw to start RX\r
128  int def_max_descriptors;      //# of descriptors in system  (must be power of 2), 2^14 max\r
129  int def_tot_descriptors_for_us;  //#of descriptors to create in our region (must be power of 2)\r
130  int def_heap_n_descriptors;   //# descriptors+buffers in default heap\r
131  int def_heap_n_zdescriptors;  //# zero len descriptors in defaule heap\r
132  int def_heap_buf_size;        //size of buffers in default heap\r
133                                //=MAX amount of area for packet data\r
134  int def_heap_tailroom_size;   //size of tailroom in reserve \r
135  int def_heap_extra_size;      //size of extra space at end of buffer\r
136 }NETAPI_CFG_T;\r
137 /* note:\r
138    each buffer will be allocated:  def_heap_buf_size+def_heap_extra_size bytes\r
139    each descriptor attached to these buffers will have original_pkt_len of:\r
140       def_heap_buf_size.\r
141    for default RX flow,  for rx packet, the bufptr  will be def_flow_pkt_rx_offset.\r
142    for detault RX flow,  threshold (ie max # of bytes in buffer) will be:\r
143        def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset\r
144 */\r
145 \r
146 \r
147 \r
148 #include "netapi_err.h"\r
149 #include "netapi_tune.h"\r
150 #include "ti/runtime/pktlib/pktlib_osal.h"\r
151 #include "ti/runtime/pktlib/pktlib.h"\r
152 #include "pktio.h"\r
153 #include "ti/drv/pa/pa.h"\r
154 #include "netcp_cfg.h"\r
155 #include "netapi_sec.h"\r
156 #include "netapi_sched.h"\r
157 #include "src/netapi_vm.h"\r
158 #include "src/netapi_util.h"\r
159 #include "netsync.h"\r
160 #include "ti/drv/nwal/nwal.h"\r
161 #include "netapi_timer.h"\r
162 #include "src/netapi_loc.h"\r
163 \r
164 /************************************************\r
165  **********BUILD TIME CONTROLS *****************\r
166  ***********************************************/\r
167 /* see netapi_tune.h */\r
168 \r
169 \r
170 /*************************************\r
171  **************NETAPI****************\r
172  ************************************/\r
173 \r
174 /**  @ingroup netapi_api_functions */\r
175 \r
176 /*\r
177 *  @brief  API instantiates the NETAPI and allocated global resources and is pre-requisite \r
178  *\r
179  *  @details Allocates global resources valid  per system level common across all ARM cores \r
180  *   or per thread based on "master" argument.\r
181  *   Intializes the following substems:\r
182  *     - pktio\r
183  *     - pktlib\r
184  *     - qmss\r
185  *     - cppi\r
186  *     - nwal\r
187  *  @param[in]  master mode: NETAPI_SYS_MASTER or NETAPI_NO_MASTER\r
188  *  @param[in]  configuration (master mode).  pointer to NETAPI_CFG_T above or NULL\r
189  *  @retval     @ref NETAPI_T: handle to the instance or NULL on error \r
190  *  @pre        none \r
191  */\r
192 NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);\r
193 \r
194 \r
195 /**  @ingroup netapi_api_functions */\r
196 /*\r
197 *  @brief  API shutdowns a previously intialized NETAPI instance \r
198  *\r
199  *  @details de-llocates global resources valid  per system level common across all ARM cores \r
200  *   or per thread based on "master" argument passed in at init time.\r
201  *  @param[in]  @ref NETAPI_T: handle to the instance \r
202  *  @retval     none \r
203  *  @pre        @ref netapi_init \r
204  */\r
205 void netapi_shutdown(NETAPI_T  p);\r
206 \r
207 /**  @ingroup netapi_api_functions */\r
208 /*\r
209 \r
210 *  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps \r
211  *\r
212  *  @details  Application will need a heapIfTable in order to create its own heaps. This\r
213  *            function returns a table that can be passed in the call to @ref Pktlib_CreateHeap\r
214 *             The memory used for these heaps is  special: \r
215  *               - specific alignment, \r
216  *               - must be contguous, \r
217  *               - must have a physical to virtual mapping that\r
218  *               - is known by NETAPI. \r
219  *          Thus it must be completely managed by NETAPI. This interfaced table provides a\r
220  *          malloc function that the pktlib heap library uses to allocate data for the heap\r
221  *          buffers.\r
222  *  @param[in]  none \r
223  *  @retval     @ref Pktlib_HeapIfTable pointer \r
224  *  @pre        @ref netapi_init \r
225  */\r
226 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;\r
227 \r
228 /** utilities to see how much mem/descriptor space is remaining **/\r
229 \r
230 /**  @ingroup netapi_api_functions */\r
231 /*\r
232 *  @brief  API is used to return the amount of free memory available for allocating buffers\r
233  (          for additonal Pktlib heaps.   \r
234  *  @details  the applicaiton can use this API to determine how much free memory is          .\r
235  *           available for heap buffers if it decides to create its own.   \r
236  *  @param[in]  void  \r
237  *  @retval     int :  amount of memory available for heap buffer storage (in bytes)\r
238  *  @pre        @ref netapi_init \r
239  */\r
240 int  netapi_getBufMemRemainder(void);\r
241 /**  @ingroup netapi_api_functions */\r
242 \r
243 /*\r
244 *  @brief  API is used to return the amount of free memory available for allocating Descriptors \r
245  (          for additonal Pktlib heaps.   \r
246  *  @details  the applicaiton can use this API to determine how much free memory is          .\r
247  *           available for heap descriptors if it decides to create its own heap.   \r
248  *  @param[in]  void  \r
249  *  @retval     int :  amount of memory available for heap descriptor storage (in bytes)\r
250  *  @pre        @ref netapi_init \r
251  */\r
252 int  netapi_getDescRemainder(void);\r
253 \r
254 /* utility to get default flow */\r
255 /**  @ingroup netapi_api_functions */\r
256 /*\r
257 *  @brief  API is used to return the default NETCP flow that is to be used for received    \r
258  (          packets..\r
259  *  @details  the applicaiton can use this API to return the default NETCP flow that is used  \r
260  *           for received packets. A NETCP flow is a list of PacketLib Heaps that are to be\r
261  *           used to supply free packets to the receive DMA function.\r
262  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance \r
263  *  @retval     NETCP_CFG_FLOW_HANDLE_T  : handle to default flow\r
264  *  @pre        @ref netapi_init  \r
265  */\r
266 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {\r
267 return NETCP_DEFAULT_FLOW;\r
268 }\r
269 \r
270 /* utility to get default route */\r
271 /**  @ingroup netapi_api_functions */\r
272 /*\r
273 *  @brief  API is used to return the default NETCP route\r
274  *\r
275  *  @details  this functions returns the default NETCP route created by @ref netapi_init.  \r
276  *            A netcp route consists of a NETCP flow plus a destination pktio channel \r
277  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance \r
278  *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  the handle of the default route. \r
279  *  @pre        @ref netapi_init  \r
280  */\r
281 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {\r
282 return NETCP_DEFAULT_ROUTE;\r
283 }\r
284 \r
285 /* utility to set/get a cookie in the netapi handle */\r
286 /**  @ingroup netapi_api_functions */\r
287 /*\r
288 *  @brief  API is used to return a piece of application-provided opaque data that has been \r
289  (          stored in the netapi instance.\r
290  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.\r
291  *           This APi lets this data be returned to the application.\r
292  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance \r
293  *  @retval     void * \r
294  *  @pre        @ref netapi_init  @ref netapi_setCookie\r
295  */\r
296 static inline void * netapi_getCookie(NETAPI_T p)\r
297 {\r
298 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;\r
299 return pp->cookie;\r
300 }\r
301 \r
302 /**  @ingroup netapi_api_functions */\r
303 /*\r
304 *  @brief  API is used to set a piece of application-provided opaque data in the\r
305  (         netapi instance.\r
306  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.\r
307  *           This APi can be returned later to the application via @ref netapi_getCookie\r
308  *  @param[in]  @ref NETAPI_T :  handle to NETAPI instance \r
309  *  @param[in]  void * : opaque data to be saved\r
310  *  @retval     void  \r
311  *  @pre        @ref netapi_init  \r
312  */\r
313 static inline void netapi_setCookie(NETAPI_T p, void * cookie)\r
314 {\r
315 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;\r
316 pp->cookie= cookie;\r
317 }\r
318 \r
319 \r
320 /**  @ingroup netapi_api_functions */\r
321 /*\r
322 *  @brief  API is used to poll for NETCP configuration response messages. \r
323  *\r
324  *  @details  Application, if controlling the scheduler,  will need to call this\r
325  *            function periodically to check for NETCP configuration responses (eg\r
326  *            statistics requests). \r
327  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance \r
328  *  @retval     none \r
329  *  @pre        @ref netapi_init \r
330  */\r
331 void netapi_netcpPoll(NETAPI_T  p);\r
332 \r
333 //heap registration for polling purposes\r
334 \r
335 /**  @ingroup netapi_api_functions */\r
336 /*\r
337 *  @brief  API is used to register a heap that is created by application so that\r
338  *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage(). \r
339  *\r
340  *  @details  this function registers an application-created heap with the netapi instance\r
341  *            so that it can add that heap's garbage queue to the garbage poll function. \r
342  *            NOTE: netapi internal heap is automatically registered\r
343  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance\r
344  *  @param[in]  @ref Pktlib_HeapHandle:  handle of heap to register\r
345  *  @retval     int :  1 if OK, <0 on error \r
346  *  @pre        @ref netapi_init  @ref Pktlib_CreateHeap\r
347  */\r
348 static inline int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h)\r
349 {\r
350 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;\r
351 int i;\r
352 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)\r
353 {\r
354         if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}\r
355 }\r
356 return -1;  //no room\r
357 }\r
358 \r
359 /**  @ingroup netapi_api_functions */\r
360 /*\r
361 *  @brief  API is used to un-register a heap that was created by application and previously\r
362 *           registerd so that\r
363  *          it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage(). \r
364  *\r
365  *  @details  this function un-registers an application-created heap with the netapi instance\r
366  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance \r
367  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap \r
368  *  @retval     <0 if err, 1 if OK\r
369  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()\r
370  */\r
371 static inline int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h)\r
372 {\r
373 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;\r
374 int i;\r
375 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)\r
376 {\r
377         if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}\r
378 }\r
379 return -1;  //not found\r
380 }\r
381 \r
382 /**  @ingroup netapi_api_functions */\r
383 /*\r
384 *  @brief  API is used to remove a created pktlib heap\r
385  *\r
386  *  @details  this function removes anapplication-created heap with the netapi instance\r
387  *             [note -> descriptors are zapped and cannot be reused]\r
388  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance \r
389  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap \r
390  *  @retval     <0 if err, 1 if OK\r
391  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()\r
392  */\r
393 \r
394 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);\r
395 \r
396 /**  @ingroup netapi_api_functions */\r
397 /*\r
398 *  @brief  API is used to poll the garbage collection queue for the internal NETAPI heaps and \r
399  *         any application created heaps\r
400  *\r
401  *  @details  this function is used to poll the netapi internal heaps and any \r
402  * application-created heaps    that have been registered with the netapi instance.  The\r
403  * poll function checks the garbage collection queue associated with the heap and returns\r
404  * descriptors and buffers when appropriate to the main free queue.\r
405  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance \r
406  *  @retval     none \r
407  *  @pre        @ref netapi_init  @ref pktlib_CreateHeap\r
408  */\r
409 void netapi_poll_heapGarbage(NETAPI_T p);\r
410 \r
411 static inline int netapi_get_version(void) {return NETAPI_VERSION_ID;}\r
412 static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}\r
413 \r
414 #endif\r