ti/runtime/netapi/netapi.h

   1 /**************************************************************
   2  * FILE PURPOSE :  -----------NETAPI-------------
   3  *         user space access to transport resources on SOC
   4  **************************************************************
   5  * @file netapi.h
   6  *
   7  * @brief DESCRIPTION:  netapi main header file for user space transport
   8  *               library
   9  *
  10  * REVISION HISTORY:  rev 0.0.1
  11  *
  12  *  Copyright (c) Texas Instruments Incorporated 2010-2011
  13  *
  14  *  Redistribution and use in source and binary forms, with or without
  15  *  modification, are permitted provided that the following conditions
  16  *  are met:
  17  *
  18  *    Redistributions of source code must retain the above copyright
  19  *    notice, this list of conditions and the following disclaimer.
  20  *
  21  *    Redistributions in binary form must reproduce the above copyright
  22  *    notice, this list of conditions and the following disclaimer in the
  23  *    documentation and/or other materials provided with the
  24  *    distribution.
  25  *
  26  *    Neither the name of Texas Instruments Incorporated nor the names of
  27  *    its contributors may be used to endorse or promote products derived
  28  *    from this software without specific prior written permission.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  31  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  32  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  33  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  34  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  35  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  36  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  37  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  38  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  39  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  40  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  41 *****************************************************************************/
  42
  43 /**  @mainpage Network API
  44  *
  45  *   @section intro  Introduction
  46  *
  47  *   The network API provides a user space interface to TI SOC transport
  48  *   Resources. The library includes:
  49  *      - general startup and setup for user space operations
  50  *      - memory heap and packet buffer  management
  51  *      - pktio  either to/from network or internal queues
  52  *      - timers for network stacks
  53  *      - netcp (network co-processor) configuration and control
  54  *      - utilities including user space synchronization primitivies
  55  *      - sample scheduling event loop
  56  *
  57  *    NETAPI allows user space transport to configure control the NETCP:
  58  *      - Classification of packets based on L2: MAC header fields
  59  *      - Classification of packets based on L3: IP header fields
  60  *      - Routing of packets to host based on L4 UDP or L5 GTPU ID
  61  *      - Unidirectional IPSec SA creation and deletion
  62  *      - Unidirectional IPSec Security Policy creation and deletion
  63  *
  64  *  \par
  65  *  NOTE:
  66  *      (C) Copyright 2010-2011 Texas Instruments, Inc.
  67  *  \par
  68  */
  69
  70 /* Define NETAPI as a master group in Doxygen format and add all NETAPI
  71    definitions to this group. */
  72 /** @defgroup netapi USERSPACE TRANSPORT NETAPI
  73  *  @{
  74  */
  75 /** @} */
  76
  77
  78 #ifndef __NETAPI__H
  79 #define __NETAPI__H
  80 #include <stdint.h>
  81 #include <stdlib.h>
  82 #include <stddef.h>
  83 #include <string.h>
  84
  85 /**
  86  *   @defgroup netapi_structures  NETAPI data structures
  87  */
  88 /**  @ingroup netapi */
  89
  90 /** @defgroup netapi_api_functions NETAPI API's
  91  *  @ingroup netapi_api_functions
  92  */
  93
  94 /**  @ingroup netapi_structures */
  95 /**
  96  * @def NETAPI_T
  97  * @brief  netapi handle:  one per thread
  98  *         used in most NETAPI calls
  99  */
 100 typedef void * NETAPI_T;
 101
 102
 103 #define NETAPI_SYS_MASTER  2  //master for system
 104 #define NETAPI_CORE_MASTER 1  //master for core
 105 #define NETAPI_NO_MASTE    0  //data only
 106
 107
 108 #include "netapi_err.h"
 109 #include "netapi_tune.h"
 110 #include "ti/runtime/pktlib/pktlib_osal.h"
 111 #include "ti/runtime/pktlib/pktlib.h"
 112 #include "pktio.h"
 113 #include "ti/drv/pa/pa.h"
 114 #include "netcp_cfg.h"
 115 #include "netapi_sched.h"
 116 #include "src/netapi_vm.h"
 117 #include "src/netapi_util.h"
 118 #include "netsync.h"
 119 #include "ti/drv/nwal/nwal.h"
 120 #include "netapi_timer.h"
 121 #include "src/netapi_loc.h"
 122
 123 /************************************************
 124  **********BUILD TIME CONTROLS *****************
 125  ***********************************************/
 126 /* see netapi_tune.h */
 127
 128
 129 /*************************************
 130  **************NETAPI****************
 131  ************************************/
 132
 133 /**  @ingroup netapi_api_functions */
 134
 135 /*
 136 *  @brief  API instantiates the NETAPI and allocated global resources and is pre-requisite
 137  *
 138  *  @details Allocates global resources valid  per system level common across all ARM cores
 139  *   or per thread based on "master" argument.
 140  *   Intializes the following substems:
 141  *     - pktio
 142  *     - pktlib
 143  *     - qmss
 144  *     - cppi
 145  *     - nwal
 146  *  @param[in]  master mode: NETAPI_SYS_MASTER or NETAPI_NO_MASTER
 147  *  @retval     @ref NETAPI_T: handle to the instance or NULL on error
 148  *  @pre        none
 149  */
 150 NETAPI_T  netapi_init(int master);
 151
 152
 153 /**  @ingroup netapi_api_functions */
 154 /*
 155 *  @brief  API shutdowns a previously intialized NETAPI instance
 156  *
 157  *  @details de-llocates global resources valid  per system level common across all ARM cores
 158  *   or per thread based on "master" argument passed in at init time.
 159  *  @param[in]  @ref NETAPI_T: handle to the instance
 160  *  @retval     none
 161  *  @pre        @ref netapi_init
 162  */
 163 void netapi_shutdown(NETAPI_T  p);
 164
 165 /**  @ingroup netapi_api_functions */
 166 /*
 167
 168 *  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps
 169  *
 170  *  @details  Application will need a heapIfTable in order to create its own heaps. This
 171  *            function returns a table that can be passed in the call to @ref Pktlib_CreateHeap
 172 *             The memory used for these heaps is  special:
 173  *               - specific alignment,
 174  *               - must be contguous,
 175  *               - must have a physical to virtual mapping that
 176  *               - is known by NETAPI.
 177  *          Thus it must be completely managed by NETAPI. This interfaced table provides a
 178  *          malloc function that the pktlib heap library uses to allocate data for the heap
 179  *          buffers.
 180  *  @param[in]  none
 181  *  @retval     @ref Pktlib_HeapIfTable pointer
 182  *  @pre        @ref netapi_init
 183  */
 184 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
 185
 186 /** utilities to see how much mem/descriptor space is remaining **/
 187
 188 /**  @ingroup netapi_api_functions */
 189 /*
 190 *  @brief  API is used to return the amount of free memory available for allocating buffers
 191  (          for additonal Pktlib heaps.
 192  *  @details  the applicaiton can use this API to determine how much free memory is          .
 193  *           available for heap buffers if it decides to create its own.
 194  *  @param[in]  void
 195  *  @retval     int :  amount of memory available for heap buffer storage (in bytes)
 196  *  @pre        @ref netapi_init
 197  */
 198 int  netapi_getBufmemRemainder(void);
 199 /**  @ingroup netapi_api_functions */
 200
 201 /*
 202 *  @brief  API is used to return the amount of free memory available for allocating Descriptors
 203  (          for additonal Pktlib heaps.
 204  *  @details  the applicaiton can use this API to determine how much free memory is          .
 205  *           available for heap descriptors if it decides to create its own heap.
 206  *  @param[in]  void
 207  *  @retval     int :  amount of memory available for heap descriptor storage (in bytes)
 208  *  @pre        @ref netapi_init
 209  */
 210 int  netapi_getDescRemainder(void);
 211
 212 /* utility to get default flow */
 213 /**  @ingroup netapi_api_functions */
 214 /*
 215 *  @brief  API is used to return the default NETCP flow that is to be used for received
 216  (          packets..
 217  *  @details  the applicaiton can use this API to return the default NETCP flow that is used
 218  *           for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
 219  *           used to supply free packets to the receive DMA function.
 220  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 221  *  @retval     NETCP_CFG_FLOW_HANDLE_T  : handle to default flow
 222  *  @pre        @ref netapi_init
 223  */
 224 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
 225 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 226 return pp->def_flow;
 227 }
 228
 229 /* utility to get default route */
 230 /**  @ingroup netapi_api_functions */
 231 /*
 232 *  @brief  API is used to return the default NETCP route
 233  *
 234  *  @details  this functions returns the default NETCP route created by @ref netapi_init.
 235  *            A netcp route consists of a NETCP flow plus a destination pktio channel
 236  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 237  *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  the handle of the default route.
 238  *  @pre        @ref netapi_init
 239  */
 240 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
 241 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 242 return pp->def_route;}
 243
 244 /* utility to set/get a cookie in the netapi handle */
 245 /**  @ingroup netapi_api_functions */
 246 /*
 247 *  @brief  API is used to return a piece of application-provided opaque data that has been
 248  (          stored in the netapi instance.
 249  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
 250  *           This APi lets this data be returned to the application.
 251  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 252  *  @retval     void *
 253  *  @pre        @ref netapi_init  @ref netapi_setCookie
 254  */
 255 static inline void * netapi_getCookie(NETAPI_T p)
 256 {
 257 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 258 return pp->cookie;
 259 }
 260
 261 /**  @ingroup netapi_api_functions */
 262 /*
 263 *  @brief  API is used to set a piece of application-provided opaque data in the
 264  (         netapi instance.
 265  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
 266  *           This APi can be returned later to the application via @ref netapi_getCookie
 267  *  @param[in]  @ref NETAPI_T :  handle to NETAPI instance
 268  *  @param[in]  void * : opaque data to be saved
 269  *  @retval     void
 270  *  @pre        @ref netapi_init
 271  */
 272 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
 273 {
 274 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 275 pp->cookie= cookie;
 276 }
 277
 278
 279 /**  @ingroup netapi_api_functions */
 280 /*
 281 *  @brief  API is used to poll for NETCP configuration response messages.
 282  *
 283  *  @details  Application, if controlling the scheduler,  will need to call this
 284  *            function periodically to check for NETCP configuration responses (eg
 285  *            statistics requests).
 286  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 287  *  @retval     none
 288  *  @pre        @ref netapi_init
 289  */
 290 void netapi_netcpPoll(NETAPI_T  p);
 291
 292 //heap registration for polling purposes
 293
 294 /**  @ingroup netapi_api_functions */
 295 /*
 296 *  @brief  API is used to register a heap that is created by application so that
 297  *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage().
 298  *
 299  *  @details  this function registers an application-created heap with the netapi instance
 300  *            so that it can add that heap's garbage queue to the garbage poll function.
 301  *            NOTE: netapi internal heap is automatically registered
 302  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 303  *  @param[in]  @ref Pktlib_HeapHandle:  handle of heap to register
 304  *  @retval     int :  1 if OK, 0 on error
 305  *  @pre        @ref netapi_init  @ref Pktlib_CreateHeap
 306  */
 307 int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h);
 308
 309 /**  @ingroup netapi_api_functions */
 310 /*
 311 *  @brief  API is used to un-register a heap that was created by application and previously
 312 *           registerd so that
 313  *          it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage().
 314  *
 315  *  @details  this function un-registers an application-created heap with the netapi instance
 316  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance
 317  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap
 318  *  @retval     0 if err, 1 if OK
 319  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
 320  */
 321 int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h);
 322
 323
 324 /**  @ingroup netapi_api_functions */
 325 /*
 326 *  @brief  API is used to poll the garbage collection queue for the internal NETAPI heaps and
 327  *         any application created heaps
 328  *
 329  *  @details  this function is used to poll the netapi internal heaps and any
 330  * application-created heaps    that have been registered with the netapi instance.  The
 331  * poll function checks the garbage collection queue associated with the heap and returns
 332  * descriptors and buffers when appropriate to the main free queue.
 333  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 334  *  @retval     none
 335  *  @pre        @ref netapi_init  @ref pktlib_CreateHeap
 336  */
 337 void netapi_poll_heapGarbage(NETAPI_T p);
 338
 339 #endif