This is the initial commit.
[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  * 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
92  */
94 /**  @ingroup netapi_structures */
95 /**
96  * @def NETAPI_T
97  *  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 /*
167 *  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps 
168  *
169  *  @details  Application will need a heapIfTable in order to create its own heaps. This
170  *            function returns a table that can be used. The memory used for these heaps is
171  *            special (alignment, must be contguous, must have a physical2virtual mapping that
172  *            is known by NETAPI. Thus it must be completely managed by NETAPI.
173  *  @param[in]  none 
174  *  @retval     @ref Pktlib_HeapIfTable pointer 
175  *  @pre        @ref netapi_init 
176  */
177 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
179 /* utilities to see how much mem/descriptor space is remaining */
180 int  netapi_getBufmemRemainder(void);
181 int  netapi_getDescRemainder(void);
183 /* utility to get default flow */
184 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
185 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
186 return pp->def_flow;
189 /* utility to get default route */
190 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
191 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
192 return pp->def_route;}
194 /* utility to set/get a cookie in the netapi handle */
195 static inline void * netapi_getCookie(NETAPI_T p)
197 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
198 return pp->cookie;
200 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
202 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
203 pp->cookie= cookie;
207 /**  @ingroup netapi_api_functions */
208 /*
209 *  @brief  API is used to poll for NETCP configuration response messages. 
210  *
211  *  @details  Application, if controlling the scheduler,  will need to call this
212  *            function periodically to check for NETCP configuration responses (eg
213  *            statistics requests). 
214  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
215  *  @retval     none 
216  *  @pre        @ref netapi_init 
217  */
218 void netapi_netcpPoll(NETAPI_T  p);
220 //heap registration for polling purposes
221 int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h);
222 int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h);
223 void netapi_poll_heapGarbage(NETAPI_T p);
225 #endif