40e748671f818d883e97f259c794a36f748ff86b
[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"
182 #include "ti/drv/sa/salld.h"
183 #define NETAPI_INFLOW_MODE_ACTIVE 1
184 #define NETAPI_SIDEBAND_MODE_ACTIVE 2
185 typedef struct NETAPI_SA_STATS_Tag
187     Sa_IpsecStats_t     saIpsecStats;
188     Sa_DataModeStats_t  dataModeStats;
189     uint8_t mode_active;
190 } NETAPI_SA_STATS_T;
192 /************************************************
193  **********BUILD TIME CONTROLS *****************
194  ***********************************************/
195 /* see netapi_tune.h */
198 /*************************************
199  **************NETAPI****************
200  ************************************/
202 /**  @ingroup netapi_api_functions */
204 /*
205 *  @brief  API instantiates the NETAPI and allocated global resources and is pre-requisite 
206  *
207  *  @details Allocates global resources valid  per system level common across all ARM cores 
208  *   or per thread based on "master" argument.
209  *   Intializes the following substems:
210  *     - pktio
211  *     - pktlib
212  *     - qmss
213  *     - cppi
214  *     - nwal
215  *  @param[in]  master mode: NETAPI_SYS_MASTER or NETAPI_NO_MASTER
216  *  @param[in]  configuration (master mode).  pointer to NETAPI_CFG_T above or NULL
217  *  @retval     @ref NETAPI_T: handle to the instance or NULL on error 
218  *  @pre        none 
219  */
220 NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);
223 /**  @ingroup netapi_api_functions */
224 /*
225 *  @brief  API shutdowns a previously intialized NETAPI instance 
226  *
227  *  @details de-llocates global resources valid  per system level common across all ARM cores 
228  *   or per thread based on "master" argument passed in at init time.
229  *  @param[in]  @ref NETAPI_T: handle to the instance 
230  *  @retval     none 
231  *  @pre        @ref netapi_init 
232  */
233 void netapi_shutdown(NETAPI_T  p);
235 /**  @ingroup netapi_api_functions */
236 /*
238 *  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps 
239  *
240  *  @details  Application will need a heapIfTable in order to create its own heaps. This
241  *            function returns a table that can be passed in the call to @ref Pktlib_CreateHeap
242 *             The memory used for these heaps is  special: 
243  *               - specific alignment, 
244  *               - must be contguous, 
245  *               - must have a physical to virtual mapping that
246  *               - is known by NETAPI. 
247  *          Thus it must be completely managed by NETAPI. This interfaced table provides a
248  *          malloc function that the pktlib heap library uses to allocate data for the heap
249  *          buffers.
250  *  @param[in]  none 
251  *  @retval     @ref Pktlib_HeapIfTable pointer 
252  *  @pre        @ref netapi_init 
253  */
254 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
256 /** utilities to see how much mem/descriptor space is remaining **/
258 /**  @ingroup netapi_api_functions */
259 /*
260 *  @brief  API is used to return the amount of free memory available for allocating buffers
261  (          for additonal Pktlib heaps.   
262  *  @details  the applicaiton can use this API to determine how much free memory is          .
263  *           available for heap buffers if it decides to create its own.   
264  *  @param[in]  void  
265  *  @retval     int :  amount of memory available for heap buffer storage (in bytes)
266  *  @pre        @ref netapi_init 
267  */
268 int  netapi_getBufMemRemainder(void);
269 /**  @ingroup netapi_api_functions */
271 /*
272 *  @brief  API is used to return the amount of free memory available for allocating Descriptors 
273  (          for additonal Pktlib heaps.   
274  *  @details  the applicaiton can use this API to determine how much free memory is          .
275  *           available for heap descriptors if it decides to create its own heap.   
276  *  @param[in]  void  
277  *  @retval     int :  amount of memory available for heap descriptor storage (in bytes)
278  *  @pre        @ref netapi_init 
279  */
280 int  netapi_getDescRemainder(void);
282 /* utility to get default flow */
283 /**  @ingroup netapi_api_functions */
284 /*
285 *  @brief  API is used to return the default NETCP flow that is to be used for received    
286  (          packets..
287  *  @details  the applicaiton can use this API to return the default NETCP flow that is used  
288  *           for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
289  *           used to supply free packets to the receive DMA function.
290  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
291  *  @retval     NETCP_CFG_FLOW_HANDLE_T  : handle to default flow
292  *  @pre        @ref netapi_init  
293  */
294 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
295 return NETCP_DEFAULT_FLOW;
298 /* utility to get default route */
299 /**  @ingroup netapi_api_functions */
300 /*
301 *  @brief  API is used to return the default NETCP route
302  *
303  *  @details  this functions returns the default NETCP route created by @ref netapi_init.  
304  *            A netcp route consists of a NETCP flow plus a destination pktio channel 
305  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
306  *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  the handle of the default route. 
307  *  @pre        @ref netapi_init  
308  */
309 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
310 return NETCP_DEFAULT_ROUTE;
313 /* utility to set/get a cookie in the netapi handle */
314 /**  @ingroup netapi_api_functions */
315 /*
316 *  @brief  API is used to return a piece of application-provided opaque data that has been 
317  (          stored in the netapi instance.
318  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
319  *           This APi lets this data be returned to the application.
320  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
321  *  @retval     void * 
322  *  @pre        @ref netapi_init  @ref netapi_setCookie
323  */
324 static inline void * netapi_getCookie(NETAPI_T p)
326 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
327 return pp->cookie;
330 /**  @ingroup netapi_api_functions */
331 /*
332 *  @brief  API is used to set a piece of application-provided opaque data in the
333  (         netapi instance.
334  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
335  *           This APi can be returned later to the application via @ref netapi_getCookie
336  *  @param[in]  @ref NETAPI_T :  handle to NETAPI instance 
337  *  @param[in]  void * : opaque data to be saved
338  *  @retval     void  
339  *  @pre        @ref netapi_init  
340  */
341 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
343 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
344 pp->cookie= cookie;
348 /**  @ingroup netapi_api_functions */
349 /*
350 *  @brief  API is used to poll for NETCP configuration response messages. 
351  *
352  *  @details  Application, if controlling the scheduler,  will need to call this
353  *            function periodically to check for NETCP configuration responses (eg
354  *            statistics requests). 
355  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
356  *  @retval     none 
357  *  @pre        @ref netapi_init 
358  */
359 void netapi_netcpPoll(NETAPI_T  p);
361 //heap registration for polling purposes
363 /**  @ingroup netapi_api_functions */
364 /*
365 *  @brief  API is used to register a heap that is created by application so that
366  *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage(). 
367  *
368  *  @details  this function registers an application-created heap with the netapi instance
369  *            so that it can add that heap's garbage queue to the garbage poll function. 
370  *            NOTE: netapi internal heap is automatically registered
371  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
372  *  @param[in]  @ref Pktlib_HeapHandle:  handle of heap to register
373  *  @retval     int :  1 if OK, <0 on error 
374  *  @pre        @ref netapi_init  @ref Pktlib_CreateHeap
375  */
376 static inline int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h)
378 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
379 int i;
380 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
382         if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}
384 return -1;  //no room
387 /**  @ingroup netapi_api_functions */
388 /*
389 *  @brief  API is used to un-register a heap that was created by application and previously
390 *           registerd so that
391  *          it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage(). 
392  *
393  *  @details  this function un-registers an application-created heap with the netapi instance
394  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance 
395  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap 
396  *  @retval     <0 if err, 1 if OK
397  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
398  */
399 static inline int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h)
401 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
402 int i;
403 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
405         if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
407 return -1;  //not found
410 /**  @ingroup netapi_api_functions */
411 /*
412 *  @brief  API is used to remove a created pktlib heap
413  *
414  *  @details  this function removes anapplication-created heap with the netapi instance
415  *             [note -> descriptors are zapped and cannot be reused]
416  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance 
417  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap 
418  *  @retval     <0 if err, 1 if OK
419  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
420  */
422 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
424 /**  @ingroup netapi_api_functions */
425 /*
426 *  @brief  API is used to poll the garbage collection queue for the internal NETAPI heaps and 
427  *         any application created heaps
428  *
429  *  @details  this function is used to poll the netapi internal heaps and any 
430  * application-created heaps    that have been registered with the netapi instance.  The
431  * poll function checks the garbage collection queue associated with the heap and returns
432  * descriptors and buffers when appropriate to the main free queue.
433  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
434  *  @retval     none 
435  *  @pre        @ref netapi_init  @ref pktlib_CreateHeap
436  */
437 void netapi_poll_heapGarbage(NETAPI_T p);
439 static inline int netapi_get_version(void) {return NETAPI_VERSION_ID;}
440 static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}
442 #endif