Update of NETAPI Version
[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  * @brief   This is the NWAL LLD Version. Versions numbers are encoded in the following 
87  * format:
88  *  0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)
89  */
90 #define NETAPI_VERSION_ID                   (0x01000003)
92 /**
93  * @brief   This is the version string which describes the NWAL LLD along with the
94  * date and build information.
95  */
96 #define NETAPI_VERSION_STR      "NETAPI Revision: 01.00.00.03"
99 /**
100  *   @defgroup netapi_structures  NETAPI data structures
101  */
102 /**  @ingroup netapi */
104 /** @defgroup netapi_api_functions NETAPI API's
105  *  @ingroup netapi_api_functions
106  */
108 /**  @ingroup netapi_structures */
109 /**
110  * @def NETAPI_T
111  * @brief  netapi handle:  one per thread
112  *         used in most NETAPI calls
113  */
114 typedef void * NETAPI_T;
117 #define NETAPI_SYS_MASTER  2  //master for system
118 #define NETAPI_CORE_MASTER 1  //master for core
119 #define NETAPI_NO_MASTER   0  //data only
121 /***********************************************
122 *************RUN TIME CONTROLS*****************
123 ***********************************************/
124 typedef struct NETAPI_CFG_Tag
126  int def_mem_size;             //bytes of CMA memory we have allocated 
127  int def_flow_pkt_rx_offset;   //offset in pkt buffer for hw to start RX
128  int def_max_descriptors;      //# of descriptors in system  (must be power of 2), 2^14 max
129  int def_tot_descriptors_for_us;  //#of descriptors to create in our region (must be power of 2)
130  int def_heap_n_descriptors;   //# descriptors+buffers in default heap
131  int def_heap_n_zdescriptors;  //# zero len descriptors in defaule heap
132  int def_heap_buf_size;        //size of buffers in default heap
133                                //=MAX amount of area for packet data
134  int def_heap_tailroom_size;   //size of tailroom in reserve 
135  int def_heap_extra_size;      //size of extra space at end of buffer
136 }NETAPI_CFG_T;
137 /* note:
138    each buffer will be allocated:  def_heap_buf_size+def_heap_extra_size bytes
139    each descriptor attached to these buffers will have rigBufferLen of:
140       def_heap_buf_size.
141    for default RX flow,  for rx packet, the bufptr  will be def_flow_pkt_rx_offset.
142    for detault RX flow,  threshold (ie max # of bytes in buffer) will be:
143        def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset
146  RX Packet from NetCP
148 Headroom [Application]     Packet [HW]                Tailroom [Application]    Extra Space [Application]
149 <-----------------------><--------------------------><------------------------><----------------------->
151 Cppi_HostDesc->origBufferLen
152 <----------------------------------------------------------------------------->
153 Cppi_HostDesc->origBuffPtr
155 \/
156 |------------def_heap_buf_size-------------------------------------------------|--def_heap_extra_size--|
157 | def_flow_pkt_rx_offset| max Cppi_HostDesc->buffLen | def_heap_tailroom_size  |   Extra Size          |
158                         ^
159                         |
160                      Cppi_HostDesc->buffPtr
163 */
167 #include "netapi_err.h"
168 #include "netapi_tune.h"
169 #include "ti/runtime/pktlib/pktlib_osal.h"
170 #include "ti/runtime/pktlib/pktlib.h"
171 #include "pktio.h"
172 #include "ti/drv/pa/pa.h"
173 #include "netcp_cfg.h"
174 #include "netapi_sec.h"
175 #include "netapi_sched.h"
176 #include "src/netapi_vm.h"
177 #include "netapi_util.h"
178 #include "netsync.h"
179 #include "ti/drv/nwal/nwal.h"
180 #include "netapi_timer.h"
181 #include "src/netapi_loc.h"
183 /************************************************
184  **********BUILD TIME CONTROLS *****************
185  ***********************************************/
186 /* see netapi_tune.h */
189 /*************************************
190  **************NETAPI****************
191  ************************************/
193 /**  @ingroup netapi_api_functions */
195 /*
196 *  @brief  API instantiates the NETAPI and allocated global resources and is pre-requisite 
197  *
198  *  @details Allocates global resources valid  per system level common across all ARM cores 
199  *   or per thread based on "master" argument.
200  *   Intializes the following substems:
201  *     - pktio
202  *     - pktlib
203  *     - qmss
204  *     - cppi
205  *     - nwal
206  *  @param[in]  master mode: NETAPI_SYS_MASTER or NETAPI_NO_MASTER
207  *  @param[in]  configuration (master mode).  pointer to NETAPI_CFG_T above or NULL
208  *  @retval     @ref NETAPI_T: handle to the instance or NULL on error 
209  *  @pre        none 
210  */
211 NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);
214 /**  @ingroup netapi_api_functions */
215 /*
216 *  @brief  API shutdowns a previously intialized NETAPI instance 
217  *
218  *  @details de-llocates global resources valid  per system level common across all ARM cores 
219  *   or per thread based on "master" argument passed in at init time.
220  *  @param[in]  @ref NETAPI_T: handle to the instance 
221  *  @retval     none 
222  *  @pre        @ref netapi_init 
223  */
224 void netapi_shutdown(NETAPI_T  p);
226 /**  @ingroup netapi_api_functions */
227 /*
229 *  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps 
230  *
231  *  @details  Application will need a heapIfTable in order to create its own heaps. This
232  *            function returns a table that can be passed in the call to @ref Pktlib_CreateHeap
233 *             The memory used for these heaps is  special: 
234  *               - specific alignment, 
235  *               - must be contguous, 
236  *               - must have a physical to virtual mapping that
237  *               - is known by NETAPI. 
238  *          Thus it must be completely managed by NETAPI. This interfaced table provides a
239  *          malloc function that the pktlib heap library uses to allocate data for the heap
240  *          buffers.
241  *  @param[in]  none 
242  *  @retval     @ref Pktlib_HeapIfTable pointer 
243  *  @pre        @ref netapi_init 
244  */
245 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
247 /** utilities to see how much mem/descriptor space is remaining **/
249 /**  @ingroup netapi_api_functions */
250 /*
251 *  @brief  API is used to return the amount of free memory available for allocating buffers
252  (          for additonal Pktlib heaps.   
253  *  @details  the applicaiton can use this API to determine how much free memory is          .
254  *           available for heap buffers if it decides to create its own.   
255  *  @param[in]  void  
256  *  @retval     int :  amount of memory available for heap buffer storage (in bytes)
257  *  @pre        @ref netapi_init 
258  */
259 int  netapi_getBufMemRemainder(void);
260 /**  @ingroup netapi_api_functions */
262 /*
263 *  @brief  API is used to return the amount of free memory available for allocating Descriptors 
264  (          for additonal Pktlib heaps.   
265  *  @details  the applicaiton can use this API to determine how much free memory is          .
266  *           available for heap descriptors if it decides to create its own heap.   
267  *  @param[in]  void  
268  *  @retval     int :  amount of memory available for heap descriptor storage (in bytes)
269  *  @pre        @ref netapi_init 
270  */
271 int  netapi_getDescRemainder(void);
273 /* utility to get default flow */
274 /**  @ingroup netapi_api_functions */
275 /*
276 *  @brief  API is used to return the default NETCP flow that is to be used for received    
277  (          packets..
278  *  @details  the applicaiton can use this API to return the default NETCP flow that is used  
279  *           for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
280  *           used to supply free packets to the receive DMA function.
281  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
282  *  @retval     NETCP_CFG_FLOW_HANDLE_T  : handle to default flow
283  *  @pre        @ref netapi_init  
284  */
285 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
286 return NETCP_DEFAULT_FLOW;
289 /* utility to get default route */
290 /**  @ingroup netapi_api_functions */
291 /*
292 *  @brief  API is used to return the default NETCP route
293  *
294  *  @details  this functions returns the default NETCP route created by @ref netapi_init.  
295  *            A netcp route consists of a NETCP flow plus a destination pktio channel 
296  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
297  *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  the handle of the default route. 
298  *  @pre        @ref netapi_init  
299  */
300 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
301 return NETCP_DEFAULT_ROUTE;
304 /* utility to set/get a cookie in the netapi handle */
305 /**  @ingroup netapi_api_functions */
306 /*
307 *  @brief  API is used to return a piece of application-provided opaque data that has been 
308  (          stored in the netapi instance.
309  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
310  *           This APi lets this data be returned to the application.
311  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
312  *  @retval     void * 
313  *  @pre        @ref netapi_init  @ref netapi_setCookie
314  */
315 static inline void * netapi_getCookie(NETAPI_T p)
317 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
318 return pp->cookie;
321 /**  @ingroup netapi_api_functions */
322 /*
323 *  @brief  API is used to set a piece of application-provided opaque data in the
324  (         netapi instance.
325  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
326  *           This APi can be returned later to the application via @ref netapi_getCookie
327  *  @param[in]  @ref NETAPI_T :  handle to NETAPI instance 
328  *  @param[in]  void * : opaque data to be saved
329  *  @retval     void  
330  *  @pre        @ref netapi_init  
331  */
332 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
334 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
335 pp->cookie= cookie;
339 /**  @ingroup netapi_api_functions */
340 /*
341 *  @brief  API is used to poll for NETCP configuration response messages. 
342  *
343  *  @details  Application, if controlling the scheduler,  will need to call this
344  *            function periodically to check for NETCP configuration responses (eg
345  *            statistics requests). 
346  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
347  *  @retval     none 
348  *  @pre        @ref netapi_init 
349  */
350 void netapi_netcpPoll(NETAPI_T  p);
352 //heap registration for polling purposes
354 /**  @ingroup netapi_api_functions */
355 /*
356 *  @brief  API is used to register a heap that is created by application so that
357  *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage(). 
358  *
359  *  @details  this function registers an application-created heap with the netapi instance
360  *            so that it can add that heap's garbage queue to the garbage poll function. 
361  *            NOTE: netapi internal heap is automatically registered
362  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
363  *  @param[in]  @ref Pktlib_HeapHandle:  handle of heap to register
364  *  @retval     int :  1 if OK, <0 on error 
365  *  @pre        @ref netapi_init  @ref Pktlib_CreateHeap
366  */
367 static inline int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h)
369 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
370 int i;
371 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
373         if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}
375 return -1;  //no room
378 /**  @ingroup netapi_api_functions */
379 /*
380 *  @brief  API is used to un-register a heap that was created by application and previously
381 *           registerd so that
382  *          it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage(). 
383  *
384  *  @details  this function un-registers an application-created heap with the netapi instance
385  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance 
386  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap 
387  *  @retval     <0 if err, 1 if OK
388  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
389  */
390 static inline int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h)
392 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
393 int i;
394 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
396         if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
398 return -1;  //not found
401 /**  @ingroup netapi_api_functions */
402 /*
403 *  @brief  API is used to remove a created pktlib heap
404  *
405  *  @details  this function removes anapplication-created heap with the netapi instance
406  *             [note -> descriptors are zapped and cannot be reused]
407  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance 
408  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap 
409  *  @retval     <0 if err, 1 if OK
410  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
411  */
413 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
415 /**  @ingroup netapi_api_functions */
416 /*
417 *  @brief  API is used to poll the garbage collection queue for the internal NETAPI heaps and 
418  *         any application created heaps
419  *
420  *  @details  this function is used to poll the netapi internal heaps and any 
421  * application-created heaps    that have been registered with the netapi instance.  The
422  * poll function checks the garbage collection queue associated with the heap and returns
423  * descriptors and buffers when appropriate to the main free queue.
424  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
425  *  @retval     none 
426  *  @pre        @ref netapi_init  @ref pktlib_CreateHeap
427  */
428 void netapi_poll_heapGarbage(NETAPI_T p);
430 static inline int netapi_get_version(void) {return NETAPI_VERSION_ID;}
431 static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}
433 #endif