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