0b6c792db14528ef428ad72de56b441295411703
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 /** @} */
97 /** @defgroup netapi_gen_functions NETAPI General Functions
98 * @ingroup netapi
99 */
100 /** @defgroup netapi_cfg_functions NETAPI Configuration Functions
101 * @ingroup netapi
102 */
104 /** @defgroup netapi_cfg_sec_functions NETAPI Security Configuration Functions
105 * @ingroup netapi
106 */
108 /** @defgroup netapi_sched_functions NETAPI Scheduler Functions
109 * @ingroup netapi
110 */
112 /** @defgroup netapi_pktio_functions NETAPI PKTIO Functions
113 * @ingroup netapi
114 */
116 /** @defgroup netapi_cb_functions NETAPI Callback Functions
117 * @ingroup netapi
118 */
121 /** @defgroup netapi_structures NETAPI Structures used in API's
122 * @ingroup netapi
123 */
125 /** @defgroup netapi_tune_parameters NETAPI Tune Parameters
126 * @ingroup netapi
127 */
130 /**
131 * @def NETAPI_VERSION_ID
132 * This is the NETAPI Version. Versions numbers are encoded in the following
133 * format:
134 * 0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)
135 */
136 #define NETAPI_VERSION_ID (0x01000004)
138 /**
139 * @def NETAPI_VERSION_STR
140 * This is the version string which describes the NETAPI along with the
141 * date and build information.q
142 */
143 #define NETAPI_VERSION_STR "NETAPI Revision: 01.00.00.04"
146 /**
147 * @ingroup netapi_structures
148 * @brief One per thread, used in most NETAPI function calls.
149 */
150 typedef void * NETAPI_T;
153 /**
154 * @def NETAPI_SYS_MASTER
155 * This defines master for system
156 */
157 #define NETAPI_SYS_MASTER 2
159 /**
160 * @def NETAPI_CORE_MASTER
161 * This defines master for core
162 */
163 #define NETAPI_CORE_MASTER 1
165 /**
166 * @def NETAPI_NO_MASTER
167 * This defines no mater, data only
168 */
169 #define NETAPI_NO_MASTER 0 //data only
172 /**
173 * @ingroup netapi_structures
174 * @brief NETAPI configuration information
175 *
176 * @details The parameters in this structure are used to configure NETAPI.
177 */
178 typedef struct NETAPI_CFG_Tag
179 {
180 int def_mem_size; /**< Bytes of CMA memory we have allocated */
181 int def_flow_pkt_rx_offset; /**< Offset in pkt buffer for hw to start RX */
182 int def_max_descriptors; /**< Number of descriptors in system (must be power of 2), 2^14 max */
183 int def_tot_descriptors_for_us; /**< Number of descriptors to create in our region (must be power of 2)*/
184 int def_heap_n_descriptors; /**< Number of descriptor plus buffers in default heap*/
185 int def_heap_n_zdescriptors; /**< Number of zero len descriptors in defaule heap*/
186 int def_heap_buf_size; /**< Size of buffers in default heap, max amount of area for packet data */
187 int def_heap_tailroom_size; /**< Size of tailroom in reserve */
188 int def_heap_extra_size; /**< Size of extra space at end of buffer */
189 } NETAPI_CFG_T;
191 /* @note:
192 each buffer will be allocated: def_heap_buf_size+def_heap_extra_size bytes
193 each descriptor attached to these buffers will have rigBufferLen of:
194 def_heap_buf_size.
195 for default RX flow, for rx packet, the bufptr will be def_flow_pkt_rx_offset.
196 for detault RX flow, threshold (ie max # of bytes in buffer) will be:
197 def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset
200 RX Packet from NetCP
202 Headroom [Application] Packet [HW] Tailroom [Application] Extra Space [Application]
203 <-----------------------><--------------------------><------------------------><----------------------->
205 Cppi_HostDesc->origBufferLen
206 <----------------------------------------------------------------------------->
207 Cppi_HostDesc->origBuffPtr
208 |
209 \/
210 |------------def_heap_buf_size-------------------------------------------------|--def_heap_extra_size--|
211 | def_flow_pkt_rx_offset| max Cppi_HostDesc->buffLen | def_heap_tailroom_size | Extra Size |
212 ^
213 |
214 Cppi_HostDesc->buffPtr
217 */
221 #include "netapi_err.h"
222 #include "netapi_tune.h"
223 #include "ti/runtime/pktlib/pktlib_osal.h"
224 #include "ti/runtime/pktlib/pktlib.h"
225 #include "pktio.h"
226 #include "ti/drv/pa/pa.h"
227 #include "netcp_cfg.h"
228 #include "netapi_sec.h"
229 #include "netapi_sched.h"
230 #include "src/netapi_vm.h"
231 #include "netapi_util.h"
232 #include "netsync.h"
233 #include "ti/drv/nwal/nwal.h"
234 #include "netapi_timer.h"
235 #include "src/netapi_loc.h"
237 /**
238 * @ingroup netapi_gen_functions
239 * @brief netapi_init API instantiates the NETAPI and allocated global resources.
240 *
241 * @details The API will allocate global resources valid per system level common across all ARM cores
242 * or per thread based on "master" argument.
243 * Intializes the following substems: pktio pklib qmss cppi nwal
244 *
245 * @param[in] master Can be either @ref NETAPI_SYS_MASTER or @ref NETAPI_NO_MASTER
246 * @param[in] p_cfg (master mode) pointer to @ref NETAPI_CFG_T or NULL to use netapi default configuration.
247 * @retval Handle to the instance or NULL on error, @ref NETAPI_T
248 * @pre none
249 */
250 NETAPI_T netapi_init(int master, NETAPI_CFG_T * p_cfg);
252 /**
253 * @ingroup netapi_gen_functions
254 * @brief netapi_shutdown API de-allocates all global resources allocated as part of @ref netapi_init
255 *
256 * @details De-allocates global resources valid per system level common across all ARM cores
257 * or per thread based on "master" argument passed in at init time.
258 * @param[in] p The NETAPI handle, @ref NETAPI_T
259 * @retval none
260 * @pre @ref netapi_init
261 */
262 void netapi_shutdown(NETAPI_T p);
264 /**
265 * @ingroup netapi_gen_functions
266 * @brief netapi_getPktlibIfTable API returns a Pktlib_HeapIfTable to use when creating pktlib heaps
267 *
268 * @details Application will need a heapIfTable in order to create its own heaps. This
269 * function returns a table that can be passed in the call to Pktlib_CreateHeap
270 * The memory used for these heaps is special with the following characteristics:
271 * - Specific alignment.
272 * - Must be contguous.
273 * - Must have a physical to virtual mapping that is known by NETAPI.
274 * Thus it must be completely managed by NETAPI. This interfaced table provides a
275 * malloc function that the pktlib heap library uses to allocate data for the heap
276 * buffers.
277 * @retval Pktlib_HeapIfTable pointer
278 * @pre @ref netapi_init
279 */
280 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
282 /**
283 * @ingroup netapi_gen_functions
284 * @brief netapi_getBufMemRemainder API is used to return the amount of free memory available for allocating buffers
285 * for additonal Pktlib heaps
286 *
287 * @details The application can use this API to determine how much free memory is
288 * available for heap buffers if it decides to create its own.
289 * @retval Amount of memory available for heap buffer storage (in bytes)
290 * @pre @ref netapi_init
291 */
292 int netapi_getBufMemRemainder(void);
295 /**
296 * @ingroup netapi_gen_functions
297 * @brief netapi_getDescRemainder API is used to return the amount of free memory available for allocating descriptors
298 * for additonal Pktlib heaps.
299 *
300 * @details The application can use this API to determine how much free memory is
301 * available for heap descriptors if it decides to create its own heap.
302 * @retval Amount of memory available for heap descriptor storage (in bytes)
303 * @pre @ref netapi_init
304 */
305 int netapi_getDescRemainder(void);
307 /**
308 * @ingroup netapi_gen_functions
309 * @brief netapi_getDefaultFlow: API is used to return the default NETCP flow that is to be used for incoming packets.
310 *
311 * @details The application can use this API to return the default NETCP flow that is used
312 * for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
313 * used to supply free packets to the receive DMA function.
314 * @param[in] p The NETAPI handle, @ref NETAPI_T
315 * @retval NETCP_CFG_FLOW_HANDLE_T The handle to default flow
316 * @pre @ref netapi_init
317 */
318 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p)
319 {
320 return NETCP_DEFAULT_FLOW;
321 }
323 /**
324 * @ingroup netapi_gen_functions
325 * @brief netapi_getDefaultRoute: API is used to return the default NETCP route handle.
326 *
327 * @details This API returns the default NETCP route created by @ref netapi_init.
328 * A netcp route consists of a NETCP flow plus a destination pktio channel
329 * @param[in] p The NETAPI handle, @ref NETAPI_T
330 * @retval The handle of the default route, NETCP_CFG_ROUTE_HANDLE_T
331 * @pre @ref netapi_init
332 */
333 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p)
334 {
335 return NETCP_DEFAULT_ROUTE;
336 }
338 /**
339 * @ingroup netapi_gen_functions
340 * @brief netapi_getCookie API is used to return a piece of application-provided opaque data that has been
341 * stored in the netapi instance.
342 *
343 * @details The application can save a pointer to opaque data in the @ref NETAPI_T instance.
344 * This APi lets this data be returned to the application.
345 * @param[in] p The NETAPI handle, @ref NETAPI_T
346 * @retval Data provided in @ref netapi_setCookie
347 * @pre @ref netapi_init, @ref netapi_setCookie
348 */
350 static inline void * netapi_getCookie(NETAPI_T p)
351 {
352 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
353 return pp->cookie;
354 }
356 /**
357 * @ingroup netapi_gen_functions
358 * @brief netapi_setCookie API is used to set a piece of application-provided opaque data t in the netapi instance.
359 *
360 * @details The applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
361 * Pointer to a opaque data can be returned later to the application via @ref netapi_getCookie
362 * @param[in] p The NETAPI handle, @ref NETAPI_T
363 * @param[in] cookie Opaque data to be saved
364 * @retval none
365 * @pre @ref netapi_init
366 */
367 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
368 {
369 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
370 pp->cookie= cookie;
371 }
373 /**
374 * @ingroup netapi_gen_functions
375 * @brief netapi_netcpPoll API is used to poll for NETCP configuration response messages.
376 *
377 * @details Application, if controlling the scheduler, will need to call this
378 * function periodically to check for NETCP configuration responses (eg
379 * statistics requests).
380 * @param[in] p The NETAPI handle, @ref NETAPI_T
381 * @retval none
382 * @pre @ref netapi_init
383 */
384 void netapi_netcpPoll(NETAPI_T p);
386 /**
387 * @ingroup netapi_gen_functions
388 * @brief netapi_registerHeap API is used to register a heap that is created by application so that
389 * it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage().
390 *
391 * @details This API registers an application-created heap with the netapi instance
392 * so that it can add that heap's garbage queue to the garbage poll function.
393 * NOTE: netapi internal heap is automatically registered
394 * @param[in] p The NETAPI handle, @ref NETAPI_T
395 * @param[in] h Handle of pklib heap to register
396 * @retval 1 if OK, <0 on error
397 * @pre @ref netapi_init
398 */
399 static inline int netapi_registerHeap(NETAPI_T p, Pktlib_HeapHandle h)
400 {
401 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
402 int i;
403 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
404 {
405 if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}
406 }
407 return -1; //no room
408 }
410 /**
411 * @ingroup netapi_gen_functions
412 * @brief netapi_unregisterHeap API is used to un-register a heap that was created by application
413 * and previously registerd so that it's garbage queue could be polled
414 * automatically by @ref netapi_poll_heapGarbage().
415 *
416 * @details This API un-registers an application-created heap with the netapi instance.
417 * NOTE: netapi internal heap is automatically registered
418 * @param[in] p The NETAPI handle, @ref NETAPI_T
419 * @param[in] h The pklib handle to heap
420 * @retval <0 if err, 1 if OK
421 * @pre @ref netapi_init , @ref netapi_registerHeap()
422 */
423 static inline int netapi_unregisterHeap(NETAPI_T p, Pktlib_HeapHandle h)
424 {
425 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
426 int i;
427 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
428 {
429 if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
430 }
431 return -1; //not found
432 }
434 /**
435 * @ingroup netapi_gen_functions
436 * @brief netapi_closeHeap API is used to remove a created pktlib heap
437 *
438 * @details This API removes anapplication-created heap with the netapi instance
439 * NOTE: descriptors are zapped and cannot be reused]
440 * @param[in] p The NETAPI handle, @ref NETAPI_T
441 * @param[in] h : handle to pklib heap
442 * @retval <0 if err, 1 if OK
443 * @pre @ref netapi_init @ref netapi_registerHeap
444 */
445 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
447 /**
448 * @ingroup netapi_gen_functions
449 * @brief netapi_poll_heapGarbage API is used to poll the garbage collection queue for
450 * the internal NETAPI heaps and any application created heaps.
451 *
452 * @details This API is used to poll the netapi internal heaps and any
453 * application-created heaps that have been registered with the netapi instance. The
454 * poll function checks the garbage collection queue associated with the heap and returns
455 * descriptors and buffers when appropriate to the main free queue.
456 * @param[in] p The NETAPI handle, @ref NETAPI_T
457 * @retval none
458 * @pre @ref netapi_init
459 */
460 void netapi_poll_heapGarbage(NETAPI_T p);
462 /**
463 * @ingroup netapi_gen_functions
464 * @brief netapi_get_version API used to get version of NETAPI
465 *
466 * @details This API used to get version of netapi
467 * @retval int version of netapi
468 * @pre @ref netapi_init
469 */
470 static inline int netapi_get_version(void)
471 {
472 return NETAPI_VERSION_ID;
473 }
475 /**
476 * @ingroup netapi_gen_functions
477 * @brief netapi_get_version_string API used to get version string of NETAPI
478 *
479 * @details This API used to get version string of netapi
480 * @retval char version string of netapi
481 * @pre @ref netapi_init
482 */
483 static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}
485 #endif