Doxygen updates
[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: rev 0.0.1 
9  *
10  *  Copyright (c) Texas Instruments Incorporated 2010-2012
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
80 #include <stdint.h>
81 #include <stdlib.h>
82 #include <stddef.h>
83 #include <string.h>
87 /* Define NETAPI as a master group in Doxygen format and
88  * add all NETAPI
89  * definitions to this group.
90  */
91 /** @defgroup netapi Network API
92  *  @{
93  */
94 /** @} */
97 /** @defgroup netapi_gen_functions NETAPI General Functions
98  *  @ingroup netapi
99  */
100 /** @defgroup netapi_cfg_functions NETAPI Configuration Functions
101  *  @ingroup netapi
102  */
103  
104 /** @defgroup netapi_cfg_sec_functions NETAPI Security Configuration Functions
105  *  @ingroup netapi
106  */
108 /** @defgroup netapi_pktio_functions NETAPI PKTIO Functions
109  *  @ingroup netapi
110  */
112 /** @defgroup netapi_constants NETAPI Constants
113  *  @ingroup netapi
114  */
116 /** @defgroup netapi_cb_functions NETAPI  Callback Functions
117  *  @ingroup netapi
118  */
121 /** @defgroup netapi_structures NETAPI Structures used in API's
122  *  @ingroup netapi
123  */
125 /** @defgroup netapi_tune_parameters NETAPI Tune Parameters
126  *  @ingroup netapi
127  */
130 /**
131  * @brief   This is the NWAL LLD Version. Versions numbers are encoded in the following 
132  * format:
133  *  0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)
134  */
135 #define NETAPI_VERSION_ID                   (0x01000004)
137 /**
138  * @brief   This is the version string which describes the NWAL LLD along with the
139  * date and build information.
140  */
141 #define NETAPI_VERSION_STR      "NETAPI Revision: 01.00.00.04"
145 /**
146  * @ingroup netapi_structures
147  * @brief  One per thread, used in most NETAPI function calls.
148  */
149 typedef void * NETAPI_T;
152 /**
153  * @brief This defines master for system
154  */
155 #define NETAPI_SYS_MASTER  2  
157 /**
158  * @brief This defines master for core
159  */
160 #define NETAPI_CORE_MASTER 1  
161 /**
162  * @brief This defines no mater, data only
163  */
164 #define NETAPI_NO_MASTER   0  //data only
167 /**
168  *  @ingroup netapi_structures
169  *  @brief NETAPI configuration information
170  *
171  *  @details The parameters in this structure are used to configure NETAPI.
172  */
173 typedef struct NETAPI_CFG_Tag
175  int def_mem_size;              /**<  Bytes of CMA memory we have allocated */
176  int def_flow_pkt_rx_offset;   /**<  Offset in pkt buffer for hw to start RX */
177  int def_max_descriptors;      /**<  Number of descriptors in system  (must be power of 2), 2^14 max */
178  int def_tot_descriptors_for_us;   /**<  Number of descriptors to create in our region (must be power of 2)*/
179  int def_heap_n_descriptors;    /**<  Number of descriptor plus buffers in default heap*/
180  int def_heap_n_zdescriptors;   /**<  Number of zero len descriptors in defaule heap*/
181  int def_heap_buf_size;/**<  Size of buffers in default heap, max amount of area for packet data */
182  int def_heap_tailroom_size;   /**<  Size of tailroom in reserve */
183  int def_heap_extra_size;      /**<  Size of extra space at end of buffer */ 
184 }  NETAPI_CFG_T;
186 /* @note:
187    each buffer will be allocated:  def_heap_buf_size+def_heap_extra_size bytes
188    each descriptor attached to these buffers will have rigBufferLen of:
189       def_heap_buf_size.
190    for default RX flow,  for rx packet, the bufptr  will be def_flow_pkt_rx_offset.
191    for detault RX flow,  threshold (ie max # of bytes in buffer) will be:
192        def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset
195  RX Packet from NetCP
197 Headroom [Application]     Packet [HW]                Tailroom [Application]    Extra Space [Application]
198 <-----------------------><--------------------------><------------------------><----------------------->
200 Cppi_HostDesc->origBufferLen
201 <----------------------------------------------------------------------------->
202 Cppi_HostDesc->origBuffPtr
204 \/
205 |------------def_heap_buf_size-------------------------------------------------|--def_heap_extra_size--|
206 | def_flow_pkt_rx_offset| max Cppi_HostDesc->buffLen | def_heap_tailroom_size  |   Extra Size          |
207                         ^
208                         |
209                      Cppi_HostDesc->buffPtr
212 */
216 #include "netapi_err.h"
217 #include "netapi_tune.h"
218 #include "ti/runtime/pktlib/pktlib_osal.h"
219 #include "ti/runtime/pktlib/pktlib.h"
220 #include "pktio.h"
221 #include "ti/drv/pa/pa.h"
222 #include "netcp_cfg.h"
223 #include "netapi_sec.h"
224 #include "netapi_sched.h"
225 #include "src/netapi_vm.h"
226 #include "netapi_util.h"
227 #include "netsync.h"
228 #include "ti/drv/nwal/nwal.h"
229 #include "netapi_timer.h"
230 #include "src/netapi_loc.h"
232 /**
233  *  @ingroup netapi_gen_functions
234  *  @brief netapi_init: API instantiates the NETAPI and allocated global resources and is pre-requisite
235  *
236  *  @details The API will allocate global resources valid  per system level common across all ARM cores 
237  *   or per thread based on "master" argument.
238  *   Intializes the following substems:
239  *       -pktio
240  *       -pktlib
241  *       -qmss
242  *       -cppi
243  *       -nwal
244  *
245  *  @param[in]  master  can be either @ref NETAPI_SYS_MASTER or @ref NETAPI_NO_MASTER
246  *  @param[in]  p_cfg   (master mode).  pointer to @refNETAPI_CFG_T or NULL to use netapi default configuration.
247  *  @retval     @ref NETAPI_T: handle to the instance or NULL on error
248  *  @pre        none
249  */
250  NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);
252 /**
253  *  @ingroup netapi_gen_functions
254  *  @brief netapi_shutdown: API De-allocates all global resources allocated as part of @ref netapi_init
255  *
256  *  @details De-allocates global resources valid  per system level common across all ARM cores 
257  *   or per thread based on "master" argument passed in at init time.
258  *  @param[in]  @ref NETAPI_T: handle to the instance 
259  *  @retval     none 
260  *  @pre        @ref netapi_init 
261  */
262 void netapi_shutdown(NETAPI_T  p);
264 /**
265  *  @ingroup netapi_gen_functions
266  *  @brief netapi_getPktlibIfTable: API returns a Pktlib_HeapIfTable to use when creating pktlib heaps
267  *
268  *  @details  Application will need a heapIfTable in order to create its own heaps. This
269  *                  function returns a table that can be passed in the call to @ref Pktlib_CreateHeap
270  *          The memory used for these heaps is  special with the following characteristicsl: 
271  *              - specific alignment, 
272  *              - must be contguous, 
273  *              - must have a physical to virtual mapping that  is known by NETAPI. 
274  *          Thus it must be completely managed by NETAPI. This interfaced table provides a
275  *          malloc function that the pktlib heap library uses to allocate data for the heap
276  *          buffers.
277  *  @param[in]  none 
278  *  @retval         Pktlib_HeapIfTable pointer 
279  *  @pre            @ref netapi_init 
280  */
281 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
283 /**
284  *  @ingroup netapi_gen_functions
285  *  @brief netapi_getBufMemRemainder:  API is used to return the amount of free memory available for allocating buffers
286  *                                                          for additonal Pktlib heaps
287  *
288  *  @details  The application can use this API to determine how much free memory is
289  *                  available for heap buffers if it decides to create its own.   
290  *  @param[in]  void
291  *  @retval     int :  amount of memory available for heap buffer storage (in bytes)
292  *  @pre        @ref netapi_init 
293  */
294 int  netapi_getBufMemRemainder(void);
297 /**
298  *  @ingroup netapi_gen_functions
299  *  @brief netapi_getDescRemainder:  API is used to return the amount of free memory available for allocating descriptors 
300  *                                                      for additonal Pktlib heaps.
301  *
302  *  @details  The application can use this API to determine how much free memory is
303  *                  available for heap descriptors if it decides to create its own heap.    
304  *  @param[in]  void
305  *  @retval     int :  amount of memory available for heap descriptor storage (in bytes)
306  *  @pre        @ref netapi_init 
307  */
308 int  netapi_getDescRemainder(void);
310 /**
311  *  @ingroup netapi_gen_functions
312  *  @brief netapi_getDefaultFlow:  API is used to return the default NETCP flow that is to be used for incoming packets.
313  *
314  *  @details  The application can use this API to return the default NETCP flow that is used  
315  *                  for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
316  *                  used to supply free packets to the receive DMA function.
317  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
318  *  @retval     NETCP_CFG_FLOW_HANDLE_T  : the handle to default flow
319  *  @pre        @ref netapi_init 
320  */
321 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
322 return NETCP_DEFAULT_FLOW;
325 /**
326  *  @ingroup netapi_gen_functions
327  *  @brief netapi_getDefaultRoute:  API is used to return the default NETCP route handle.
328  *
329  *  @details  This API returns the default NETCP route created by @ref netapi_init.  
330  *                  A netcp route consists of a NETCP flow plus a destination pktio channel 
331  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
332  *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  The handle of the default route. 
333  *  @pre        @ref netapi_init  
334  */
335 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
336 return NETCP_DEFAULT_ROUTE;
339 /**
340  *  @ingroup netapi_gen_functions
341  *  @brief netapi_getCookie:  API is used to return a piece of application-provided opaque data that has been
342  *                                          stored in the netapi instance.
343  *
344  *  @details  The application can save a pointer to opaque data in the @ref NETAPI_T instance.
345  *                  This APi lets this data be returned to the application
346  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
347  *  @retval     void * : Data provided in @ref netapi_setCookie
348  *  @pre        @ref netapi_init, @ref netapi_setCookie
349  */
351 static inline void * netapi_getCookie(NETAPI_T p)
353 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
354 return pp->cookie;
357 /**
358  *  @ingroup netapi_gen_functions
359  *  @brief netapi_setCookie:  API is used to set a piece of application-provided opaque data t in the netapi instance.
360  *
361  *  @details  The applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
362  *           This API can be returned later to the application via @ref netapi_getCookie
363  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
364  *  @param[in]  void * : opaque data to be saved
365  *  @retval     none
366  *  @pre        @ref netapi_init
367  */
368 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
370 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
371 pp->cookie= cookie;
374 /**
375  *  @ingroup netapi_gen_functions
376  *  @brief netapi_netcpPoll: API is used to poll for NETCP configuration response messages.
377  *
378  *  @details Application, if controlling the scheduler,  will need to call this
379  *            function periodically to check for NETCP configuration responses (eg
380  *            statistics requests). 
381  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
382  *  @retval     none 
383  *  @pre        @ref netapi_init 
384  */
385 void netapi_netcpPoll(NETAPI_T  p);
387 /**
388  *  @ingroup netapi_gen_functions
389  *  @brief netapi_registerHeap: API is used to register a heap that is created by application so that
390  *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage().
391  *
392  *  @details  This API registers an application-created heap with the netapi instance
393  *            so that it can add that heap's garbage queue to the garbage poll function. 
394  *            NOTE: netapi internal heap is automatically registered
395  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
396  *  @param[in]  @ref Pktlib_HeapHandle:  handle of heap to register
397  *  @retval     int :  1 if OK, <0 on error 
398  *  @pre        @ref netapi_init  @ref Pktlib_CreateHeap
399  */
400 static inline int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h)
402 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
403 int i;
404 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
406         if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}
408 return -1;  //no room
411 /**
412  *  @ingroup netapi_gen_functions
413  *  @brief netapi_unregisterHeap:  API is used to un-register a heap that was created by application and previously
414 *           registerd so that it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage(). 
415  *
416  *  @details  This API un-registers an application-created heap with the netapi instance. 
417  *            NOTE: netapi internal heap is automatically registered
418  *  @param[in]  p: handle to NETAPI instance 
419  *  @param[in]  h: handle to heap 
420  *  @retval     <0 if err, 1 if OK
421  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
422  */
423 static inline int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h)
425 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
426 int i;
427 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
429         if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
431 return -1;  //not found
434 /**
435  *  @ingroup netapi_gen_functions
436  *  @brief netapi_closeHeap:  API is used to remove a created pktlib heap
437  *
438  *  @details   This API removes anapplication-created heap with the netapi instance
439  *            NOTE: descriptors are zapped and cannot be reused]
440  *  @param[in]  p: handle to NETAPI instance
441  *  @param[in]  h :  handle to heap, @ref Pktlib_HeapHandle
442  *  @retval     <0 if err, 1 if OK
443  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap
444  */
445 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
447 /**
448  *  @ingroup netapi_gen_functions
449  *  @brief netapi_poll_heapGarbage:  API is used to poll the garbage collection queue for 
450  *              the internal NETAPI heaps and any application created heaps
451  *
452  *  @details  This API is used to poll the netapi internal heaps and any 
453  * application-created heaps    that have been registered with the netapi instance.  The
454  * poll function checks the garbage collection queue associated with the heap and returns
455  * descriptors and buffers when appropriate to the main free queue.
456  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance 
457  *  @retval     none 
458  *  @pre        @ref netapi_init  @ref pktlib_CreateHeap
459  */
460 void netapi_poll_heapGarbage(NETAPI_T p);
462 /**
463  *  @ingroup netapi_gen_functions
464  *  @brief netapi_get_version:  API used to get version of NWAL LLD 
465  *
466  *  @details  This  API used to get version of netapi
467  *  @retval     int version of netapi
468  *  @pre        @ref netapi_init
469  */
470 static inline int netapi_get_version(void)
472 return NETAPI_VERSION_ID;
475 /**
476  *  @ingroup netapi_gen_functions
477  *  @brief netapi_get_version_string:  API used to get version string of NWAL LLD 
478  *
479  *  @details  This  API used to get version string of netapi
480  *  @retval     char version string of netapi
481  *  @pre        @ref netapi_init
482  */
483 static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}
485 #endif