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)
317 {
318 return NETCP_DEFAULT_FLOW;
319 }
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)
332 {
333 return NETCP_DEFAULT_ROUTE;
334 }
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)
349 {
350 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
351 return pp->cookie;
352 }
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)
366 {
367 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
368 pp->cookie= cookie;
369 }
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)
398 {
399 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
400 int i;
401 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
402 {
403 if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}
404 }
405 return -1; //no room
406 }
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)
422 {
423 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
424 int i;
425 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
426 {
427 if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
428 }
429 return -1; //not found
430 }
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)
469 {
470 return NETAPI_VERSION_ID;
471 }
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