e8cbd7d6abda512a6d74af3da9b42bd11c78b7d6
[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 #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