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