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  * 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
  92  */
  93
  94 /**  @ingroup netapi_structures */
  95 /**
  96  * @def NETAPI_T
  97  *  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 *  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps
 168  *
 169  *  @details  Application will need a heapIfTable in order to create its own heaps. This
 170  *            function returns a table that can be used. The memory used for these heaps is
 171  *            special (alignment, must be contguous, must have a physical2virtual mapping that
 172  *            is known by NETAPI. Thus it must be completely managed by NETAPI.
 173  *  @param[in]  none
 174  *  @retval     @ref Pktlib_HeapIfTable pointer
 175  *  @pre        @ref netapi_init
 176  */
 177 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
 178
 179 /* utilities to see how much mem/descriptor space is remaining */
 180 int  netapi_getBufmemRemainder(void);
 181 int  netapi_getDescRemainder(void);
 182
 183 /* utility to get default flow */
 184 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
 185 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 186 return pp->def_flow;
 187 }
 188
 189 /* utility to get default route */
 190 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
 191 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 192 return pp->def_route;}
 193
 194 /* utility to set/get a cookie in the netapi handle */
 195 static inline void * netapi_getCookie(NETAPI_T p)
 196 {
 197 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 198 return pp->cookie;
 199 }
 200 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
 201 {
 202 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 203 pp->cookie= cookie;
 204 }
 205
 206
 207 /**  @ingroup netapi_api_functions */
 208 /*
 209 *  @brief  API is used to poll for NETCP configuration response messages.
 210  *
 211  *  @details  Application, if controlling the scheduler,  will need to call this
 212  *            function periodically to check for NETCP configuration responses (eg
 213  *            statistics requests).
 214  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 215  *  @retval     none
 216  *  @pre        @ref netapi_init
 217  */
 218 void netapi_netcpPoll(NETAPI_T  p);
 219
 220 //heap registration for polling purposes
 221 int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h);
 222 int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h);
 223 void netapi_poll_heapGarbage(NETAPI_T p);
 224
 225 #endif