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:
9 *
10 * Copyright (c) Texas Instruments Incorporated 2013
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
81 #ifdef __cplusplus
82 extern "C" {
83 #endif
85 #include <stdio.h>
86 #include <stdint.h>
87 #include <stdlib.h>
88 #include <stddef.h>
89 #include <string.h>
91 #include "ti/drv/nwal/nwal.h"
92 #include "ti/runtime/hplib/hplib.h"
93 #include "netapi_types.h"
94 #include "netapi_tune.h"
95 #include "pktio.h"
96 #include "netcp_cfg.h"
97 #include "netapi_sec.h"
98 #include "netapi_sched.h"
99 #include "netapi_util.h"
102 /* Define NETAPI as a master group in Doxygen format and
103 * add all NETAPI
104 * definitions to this group.
105 */
106 /** @defgroup netapi Network API
107 * @{
108 */
109 /** @} */
111 /** @defgroup netapi_gen_functions NETAPI General Functions
112 * @ingroup netapi
113 */
116 /** @defgroup netapi_cfg NETAPI Configuration Interface
117 * @ingroup netapi
118 */
119 /** @defgroup cfg_functions NETAPI Configuration Functions
120 * @ingroup netapi_cfg
121 */
123 /** @defgroup cfg_structures NETAPI Configuration Structures used in API's
124 * @ingroup netapi_cfg
125 */
127 /** @defgroup cfg_constants NETAPI Configuration Constants
128 * @ingroup netapi_cfg
129 */
131 /** @defgroup netapi_security NETAPI Security Interface
132 * @ingroup netapi
133 */
135 /** @defgroup cfg_security_functions NETAPI Security Configuration Functions
136 * @ingroup netapi_security
137 */
139 /** @defgroup cfg_security_structures NETAPI Security Configuration Structures used in API's
140 * @ingroup netapi_security
141 */
144 /** @defgroup security_constants NETAPI Security Constants
145 * @ingroup netapi_security
146 */
148 /** @defgroup netapi_pktio NETAPI PKTIO Interface
149 * @ingroup netapi
150 */
152 /** @defgroup pktio_functions NETAPI PKTIO Functions
153 * @ingroup netapi_pktio
154 */
156 /** @defgroup pktio_structures NETAPI PKTIO Structures used in API's
157 * @ingroup netapi_pktio
158 */
160 /** @defgroup pktio_constants NETAPI PKTIO Constants
161 * @ingroup netapi_pktio
162 */
164 /** @defgroup netapi_scheduler NETAPI Scheduler Interface
165 * @ingroup netapi
166 */
168 /** @defgroup sched_functions NETAPI Scheduler Functions
169 * @ingroup netapi_scheduler
170 */
172 /** @defgroup sched_structures NETAPI Scheduler Structures used in API's
173 * @ingroup netapi_scheduler
174 */
176 /** @defgroup sched_constants NETAPI Scheduler Constants
177 * @ingroup netapi_scheduler
178 */
180 /** @defgroup netapi_cb_functions NETAPI Callback Functions
181 * @ingroup netapi
182 */
184 /** @defgroup tune_parameters NETAPI Tune Parameters
185 * @ingroup netapi
186 */
188 /**
189 * @def NETAPI_PROC_MASTER
190 * This defines the master core/thread for a process
191 */
192 #define NETAPI_PROC_MASTER 3
194 /**
195 * @def NETAPI_SYS_MASTER
196 * This defines the master core for the system
197 * also will be master core/thread of the process
198 */
199 #define NETAPI_SYS_MASTER 2
201 /**
202 * @def NETAPI_CORE_MASTER
203 * This defines the master thread for a particular core
204 */
205 #define NETAPI_CORE_MASTER 1
207 /**
208 * @def NETAPI_NO_MASTER
209 * This defines a non master thread which can be running on any core,, specifically for data only
210 */
211 #define NETAPI_NO_MASTER 0 //data only
216 /**
217 * @ingroup netapi_gen_functions
218 * @brief netapi_init API instantiates the NETAPI and allocated global resources.
219 *
220 * @details The API will allocate global resources valid per system level common
221 * across all ARM cores or per thread based on "master" argument.
222 * Intializes the following substems: pktio pklib qmss cppi nwal
223 *
224 * @param[in] master Can be either @ref NETAPI_SYS_MASTER or @ref NETAPI_NO_MASTER
225 * @param[in] p_cfg (master mode) pointer to @ref NETAPI_CFG_T or NULL to use netapi default configuration.
226 * @retval Handle to the instance or NULL on error, @ref NETAPI_T
227 * @pre none
228 */
229 NETAPI_T netapi_init(int master,
230 NETAPI_CFG_T * p_cfg);
231 /**
232 * @ingroup netapi_gen_functions
233 * @brief netapi_shutdown API de-allocates all global resources allocated as part of @ref netapi_init
234 *
235 * @details De-allocates global resources valid per system level common across all ARM cores
236 * or per thread based on "master" argument passed in at init time.
237 * @param[in] p The NETAPI handle, @ref NETAPI_T
238 * @retval none
239 * @pre @ref netapi_init
240 */
241 void netapi_shutdown(NETAPI_T p);
243 /**
244 * @ingroup netapi_gen_functions
245 * @brief netapi_getPktlibIfTable API returns a Pktlib_HeapIfTable to use when creating
246 * pktlib heaps
247 *
248 * @details Application will need a Pktlib_HeapIfTable in order to create its own heaps. This
249 * function returns a table that can be passed in the call to Pktlib_CreateHeap
250 * The memory used for these heaps is special with the following characteristics:
251 * - Specific alignment.
252 * - Must be contguous.
253 * - Must have a physical to virtual mapping that is known by NETAPI.
254 * Thus it must be completely managed by NETAPI. This interface table provides a
255 * malloc function that the pktlib heap library uses to allocate data for the heap
256 * buffers.
257 * @retval Pktlib_HeapIfTable pointer
258 * @pre @ref netapi_init
259 */
260 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
264 /**
265 * @ingroup netapi_gen_functions
266 * @brief netapi_getDescRemainder API is used to return the amount of free memory available
267 * for allocating descriptors for additonal Pktlib heaps.
268 *
269 * @details The application can use this API to determine how much free memory is
270 * available for heap descriptors if it decides to create its own heap.
271 * @retval Amount of memory available for heap descriptor storage (in bytes)
272 * @pre @ref netapi_init
273 */
274 int netapi_getDescRemainder(void);
276 /**
277 * @ingroup netapi_gen_functions
278 * @brief netapi_netcpPoll API is used to poll for NETCP configuration response messages.
279 *
280 * @details Application, if implementing the scheduler, will need to call this
281 * function periodically to check for NETCP configuration responses (eg
282 * statistics requests).
283 * @param[in] p The NETAPI handle, @ref NETAPI_T
284 * @retval none
285 * @pre @ref netapi_init
286 */
287 void netapi_netcpPoll(NETAPI_T p);
290 /**
291 * @ingroup netapi_gen_functions
292 * @brief netapi_pollHeapGarbage API is used to poll the garbage collection queue for
293 * the internal NETAPI heaps and any application created heaps.
294 *
295 * @details This API is used to poll the netapi internal heaps and any
296 * application-created heaps that have been registered with the netapi instance. The
297 * poll function checks the garbage collection queue associated with the heap and returns
298 * descriptors and buffers when appropriate to the main free queue.
299 * @param[in] p The NETAPI handle, @ref NETAPI_T
300 * @retval none
301 * @pre @ref netapi_init
302 */
303 void netapi_pollHeapGarbage(NETAPI_T p);
305 #ifdef __cplusplus
306 }
307 #endif
308 #endif