92ed153bf8a1eeedc9555b6a8bb507e04d6bc1a2
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>
84 #include "hplib.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 /** @} */
97 extern hplib_virtualAddrInfo_T netapi_VM_VirtAddr[HPLIB_MAX_MEM_POOLS];
98 extern unsigned char *netapi_VM_SaContextVaddr;
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 "ti/drv/nwal/nwal.h"
229 #include "src/netapi_loc.h"
230 #include "hplib.h"
232 /**
233 * @ingroup netapi_gen_functions
234 * @brief netapi_init API instantiates the NETAPI and allocated global resources.
235 *
236 * @details The API will allocate global resources valid per system level common across all ARM cores
237 * or per thread based on "master" argument.
238 * Intializes the following substems: pktio pklib qmss cppi nwal
239 *
240 * @param[in] master Can be either @ref NETAPI_SYS_MASTER or @ref NETAPI_NO_MASTER
241 * @param[in] p_cfg (master mode) pointer to @ref NETAPI_CFG_T or NULL to use netapi default configuration.
242 * @retval Handle to the instance or NULL on error, @ref NETAPI_T
243 * @pre none
244 */
245 NETAPI_T netapi_init(int master, NETAPI_CFG_T * p_cfg);
247 /**
248 * @ingroup netapi_gen_functions
249 * @brief netapi_shutdown API de-allocates all global resources allocated as part of @ref netapi_init
250 *
251 * @details De-allocates global resources valid per system level common across all ARM cores
252 * or per thread based on "master" argument passed in at init time.
253 * @param[in] p The NETAPI handle, @ref NETAPI_T
254 * @retval none
255 * @pre @ref netapi_init
256 */
257 void netapi_shutdown(NETAPI_T p);
259 /**
260 * @ingroup netapi_gen_functions
261 * @brief netapi_getPktlibIfTable API returns a Pktlib_HeapIfTable to use when creating pktlib heaps
262 *
263 * @details Application will need a heapIfTable in order to create its own heaps. This
264 * function returns a table that can be passed in the call to Pktlib_CreateHeap
265 * The memory used for these heaps is special with the following characteristics:
266 * - Specific alignment.
267 * - Must be contguous.
268 * - Must have a physical to virtual mapping that is known by NETAPI.
269 * Thus it must be completely managed by NETAPI. This interfaced table provides a
270 * malloc function that the pktlib heap library uses to allocate data for the heap
271 * buffers.
272 * @retval Pktlib_HeapIfTable pointer
273 * @pre @ref netapi_init
274 */
275 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
277 /**
278 * @ingroup netapi_gen_functions
279 * @brief netapi_getBufMemRemainder API is used to return the amount of free memory available for allocating buffers
280 * for additonal Pktlib heaps
281 *
282 * @details The application can use this API to determine how much free memory is
283 * available for heap buffers if it decides to create its own.
284 * @retval Amount of memory available for heap buffer storage (in bytes)
285 * @pre @ref netapi_init
286 */
287 int netapi_getBufMemRemainder(void);
290 /**
291 * @ingroup netapi_gen_functions
292 * @brief netapi_getDescRemainder API is used to return the amount of free memory available for allocating descriptors
293 * for additonal Pktlib heaps.
294 *
295 * @details The application can use this API to determine how much free memory is
296 * available for heap descriptors if it decides to create its own heap.
297 * @retval Amount of memory available for heap descriptor storage (in bytes)
298 * @pre @ref netapi_init
299 */
300 int netapi_getDescRemainder(void);
302 /**
303 * @ingroup netapi_gen_functions
304 * @brief netapi_getDefaultFlow: API is used to return the default NETCP flow that is to be used for incoming packets.
305 *
306 * @details The application can use this API to return the default NETCP flow that is used
307 * for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
308 * used to supply free packets to the receive DMA function.
309 * @param[in] p The NETAPI handle, @ref NETAPI_T
310 * @retval NETCP_CFG_FLOW_HANDLE_T The handle to default flow
311 * @pre @ref netapi_init
312 */
313 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p)
314 {
315 return NETCP_DEFAULT_FLOW;
316 }
318 /**
319 * @ingroup netapi_gen_functions
320 * @brief netapi_getDefaultRoute: API is used to return the default NETCP route handle.
321 *
322 * @details This API returns the default NETCP route created by @ref netapi_init.
323 * A netcp route consists of a NETCP flow plus a destination pktio channel
324 * @param[in] p The NETAPI handle, @ref NETAPI_T
325 * @retval The handle of the default route, NETCP_CFG_ROUTE_HANDLE_T
326 * @pre @ref netapi_init
327 */
328 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p)
329 {
330 return NETCP_DEFAULT_ROUTE;
331 }
333 /**
334 * @ingroup netapi_gen_functions
335 * @brief netapi_getCookie API is used to return a piece of application-provided opaque data that has been
336 * stored in the netapi instance.
337 *
338 * @details The application can save a pointer to opaque data in the @ref NETAPI_T instance.
339 * This APi lets this data be returned to the application.
340 * @param[in] p The NETAPI handle, @ref NETAPI_T
341 * @retval Data provided in @ref netapi_setCookie
342 * @pre @ref netapi_init, @ref netapi_setCookie
343 */
345 static inline void * netapi_getCookie(NETAPI_T p)
346 {
347 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
348 return pp->cookie;
349 }
351 /**
352 * @ingroup netapi_gen_functions
353 * @brief netapi_setCookie API is used to set a piece of application-provided opaque data t in the netapi instance.
354 *
355 * @details The applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
356 * Pointer to a opaque data can be returned later to the application via @ref netapi_getCookie
357 * @param[in] p The NETAPI handle, @ref NETAPI_T
358 * @param[in] cookie Opaque data to be saved
359 * @retval none
360 * @pre @ref netapi_init
361 */
362 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
363 {
364 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
365 pp->cookie= cookie;
366 }
368 /**
369 * @ingroup netapi_gen_functions
370 * @brief netapi_netcpPoll API is used to poll for NETCP configuration response messages.
371 *
372 * @details Application, if controlling the scheduler, will need to call this
373 * function periodically to check for NETCP configuration responses (eg
374 * statistics requests).
375 * @param[in] p The NETAPI handle, @ref NETAPI_T
376 * @retval none
377 * @pre @ref netapi_init
378 */
379 void netapi_netcpPoll(NETAPI_T p);
381 /**
382 * @ingroup netapi_gen_functions
383 * @brief netapi_registerHeap API is used to register a heap that is created by application so that
384 * it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage().
385 *
386 * @details This API registers an application-created heap with the netapi instance
387 * so that it can add that heap's garbage queue to the garbage poll function.
388 * NOTE: netapi internal heap is automatically registered
389 * @param[in] p The NETAPI handle, @ref NETAPI_T
390 * @param[in] h Handle of pklib heap to register
391 * @retval 1 if OK, <0 on error
392 * @pre @ref netapi_init
393 */
394 static inline int netapi_registerHeap(NETAPI_T p, Pktlib_HeapHandle h)
395 {
396 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
397 int i;
398 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
399 {
400 if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}
401 }
402 return -1; //no room
403 }
405 /**
406 * @ingroup netapi_gen_functions
407 * @brief netapi_unregisterHeap API is used to un-register a heap that was created by application
408 * and previously registerd so that it's garbage queue could be polled
409 * automatically by @ref netapi_poll_heapGarbage().
410 *
411 * @details This API un-registers an application-created heap with the netapi instance.
412 * NOTE: netapi internal heap is automatically registered
413 * @param[in] p The NETAPI handle, @ref NETAPI_T
414 * @param[in] h The pklib handle to heap
415 * @retval <0 if err, 1 if OK
416 * @pre @ref netapi_init , @ref netapi_registerHeap()
417 */
418 static inline int netapi_unregisterHeap(NETAPI_T p, Pktlib_HeapHandle h)
419 {
420 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
421 int i;
422 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
423 {
424 if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
425 }
426 return -1; //not found
427 }
429 /**
430 * @ingroup netapi_gen_functions
431 * @brief netapi_closeHeap API is used to remove a created pktlib heap
432 *
433 * @details This API removes anapplication-created heap with the netapi instance
434 * NOTE: descriptors are zapped and cannot be reused]
435 * @param[in] p The NETAPI handle, @ref NETAPI_T
436 * @param[in] h : handle to pklib heap
437 * @retval <0 if err, 1 if OK
438 * @pre @ref netapi_init @ref netapi_registerHeap
439 */
440 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
442 /**
443 * @ingroup netapi_gen_functions
444 * @brief netapi_poll_heapGarbage API is used to poll the garbage collection queue for
445 * the internal NETAPI heaps and any application created heaps.
446 *
447 * @details This API is used to poll the netapi internal heaps and any
448 * application-created heaps that have been registered with the netapi instance. The
449 * poll function checks the garbage collection queue associated with the heap and returns
450 * descriptors and buffers when appropriate to the main free queue.
451 * @param[in] p The NETAPI handle, @ref NETAPI_T
452 * @retval none
453 * @pre @ref netapi_init
454 */
455 void netapi_poll_heapGarbage(NETAPI_T p);
457 /**
458 * @ingroup netapi_gen_functions
459 * @brief netapi_get_version API used to get version of NETAPI
460 *
461 * @details This API used to get version of netapi
462 * @retval int version of netapi
463 * @pre @ref netapi_init
464 */
465 static inline int netapi_get_version(void)
466 {
467 return NETAPI_VERSION_ID;
468 }
470 /**
471 * @ingroup netapi_gen_functions
472 * @brief netapi_get_version_string API used to get version string of NETAPI
473 *
474 * @details This API used to get version string of netapi
475 * @retval char version string of netapi
476 * @pre @ref netapi_init
477 */
478 static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}
480 #endif