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