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  * @brief   This is the NWAL LLD Version. Versions numbers are encoded in the following
  87  * format:
  88  *  0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)
  89  */
  90 #define NETAPI_VERSION_ID                   (0x01000003)
  91
  92 /**
  93  * @brief   This is the version string which describes the NWAL LLD along with the
  94  * date and build information.
  95  */
  96 #define NETAPI_VERSION_STR      "NETAPI Revision: 01.00.00.03"
  97
  98
  99 /**
 100  *   @defgroup netapi_structures  NETAPI data structures
 101  */
 102 /**  @ingroup netapi */
 103
 104 /** @defgroup netapi_api_functions NETAPI API's
 105  *  @ingroup netapi_api_functions
 106  */
 107
 108 /**  @ingroup netapi_structures */
 109 /**
 110  * @def NETAPI_T
 111  * @brief  netapi handle:  one per thread
 112  *         used in most NETAPI calls
 113  */
 114 typedef void * NETAPI_T;
 115
 116
 117 #define NETAPI_SYS_MASTER  2  //master for system
 118 #define NETAPI_CORE_MASTER 1  //master for core
 119 #define NETAPI_NO_MASTER   0  //data only
 120
 121 /***********************************************
 122 *************RUN TIME CONTROLS*****************
 123 ***********************************************/
 124 typedef struct NETAPI_CFG_Tag
 125 {
 126  int def_mem_size;             //bytes of CMA memory we have allocated
 127  int def_flow_pkt_rx_offset;   //offset in pkt buffer for hw to start RX
 128  int def_max_descriptors;      //# of descriptors in system  (must be power of 2), 2^14 max
 129  int def_tot_descriptors_for_us;  //#of descriptors to create in our region (must be power of 2)
 130  int def_heap_n_descriptors;   //# descriptors+buffers in default heap
 131  int def_heap_n_zdescriptors;  //# zero len descriptors in defaule heap
 132  int def_heap_buf_size;        //size of buffers in default heap
 133                                //=MAX amount of area for packet data
 134  int def_heap_tailroom_size;   //size of tailroom in reserve
 135  int def_heap_extra_size;      //size of extra space at end of buffer
 136 }NETAPI_CFG_T;
 137 /* note:
 138    each buffer will be allocated:  def_heap_buf_size+def_heap_extra_size bytes
 139    each descriptor attached to these buffers will have rigBufferLen of:
 140       def_heap_buf_size.
 141    for default RX flow,  for rx packet, the bufptr  will be def_flow_pkt_rx_offset.
 142    for detault RX flow,  threshold (ie max # of bytes in buffer) will be:
 143        def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset
 144
 145
 146  RX Packet from NetCP
 147
 148 Headroom [Application]     Packet [HW]                Tailroom [Application]    Extra Space [Application]
 149 <-----------------------><--------------------------><------------------------><----------------------->
 150
 151 Cppi_HostDesc->origBufferLen
 152 <----------------------------------------------------------------------------->
 153 Cppi_HostDesc->origBuffPtr
 154 |
 155 \/
 156 |------------def_heap_buf_size-------------------------------------------------|--def_heap_extra_size--|
 157 | def_flow_pkt_rx_offset| max Cppi_HostDesc->buffLen | def_heap_tailroom_size  |   Extra Size          |
 158                         ^
 159                         |
 160                      Cppi_HostDesc->buffPtr
 161
 162
 163 */
 164
 165
 166
 167 #include "netapi_err.h"
 168 #include "netapi_tune.h"
 169 #include "ti/runtime/pktlib/pktlib_osal.h"
 170 #include "ti/runtime/pktlib/pktlib.h"
 171 #include "pktio.h"
 172 #include "ti/drv/pa/pa.h"
 173 #include "netcp_cfg.h"
 174 #include "netapi_sec.h"
 175 #include "netapi_sched.h"
 176 #include "src/netapi_vm.h"
 177 #include "netapi_util.h"
 178 #include "netsync.h"
 179 #include "ti/drv/nwal/nwal.h"
 180 #include "netapi_timer.h"
 181 #include "src/netapi_loc.h"
 182 #include "ti/drv/sa/salld.h"
 183 #define NETAPI_INFLOW_MODE_ACTIVE 1
 184 #define NETAPI_SIDEBAND_MODE_ACTIVE 2
 185 typedef struct NETAPI_SA_STATS_Tag
 186 {
 187     Sa_IpsecStats_t     saIpsecStats;
 188     Sa_DataModeStats_t  dataModeStats;
 189     uint8_t mode_active;
 190 } NETAPI_SA_STATS_T;
 191
 192 /************************************************
 193  **********BUILD TIME CONTROLS *****************
 194  ***********************************************/
 195 /* see netapi_tune.h */
 196
 197
 198 /*************************************
 199  **************NETAPI****************
 200  ************************************/
 201
 202 /**  @ingroup netapi_api_functions */
 203
 204 /*
 205 *  @brief  API instantiates the NETAPI and allocated global resources and is pre-requisite
 206  *
 207  *  @details Allocates global resources valid  per system level common across all ARM cores
 208  *   or per thread based on "master" argument.
 209  *   Intializes the following substems:
 210  *     - pktio
 211  *     - pktlib
 212  *     - qmss
 213  *     - cppi
 214  *     - nwal
 215  *  @param[in]  master mode: NETAPI_SYS_MASTER or NETAPI_NO_MASTER
 216  *  @param[in]  configuration (master mode).  pointer to NETAPI_CFG_T above or NULL
 217  *  @retval     @ref NETAPI_T: handle to the instance or NULL on error
 218  *  @pre        none
 219  */
 220 NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);
 221
 222
 223 /**  @ingroup netapi_api_functions */
 224 /*
 225 *  @brief  API shutdowns a previously intialized NETAPI instance
 226  *
 227  *  @details de-llocates global resources valid  per system level common across all ARM cores
 228  *   or per thread based on "master" argument passed in at init time.
 229  *  @param[in]  @ref NETAPI_T: handle to the instance
 230  *  @retval     none
 231  *  @pre        @ref netapi_init
 232  */
 233 void netapi_shutdown(NETAPI_T  p);
 234
 235 /**  @ingroup netapi_api_functions */
 236 /*
 237
 238 *  @brief  API returns a @ref Pktlib_HeapIfTable to use when creating pktlib heaps
 239  *
 240  *  @details  Application will need a heapIfTable in order to create its own heaps. This
 241  *            function returns a table that can be passed in the call to @ref Pktlib_CreateHeap
 242 *             The memory used for these heaps is  special:
 243  *               - specific alignment,
 244  *               - must be contguous,
 245  *               - must have a physical to virtual mapping that
 246  *               - is known by NETAPI.
 247  *          Thus it must be completely managed by NETAPI. This interfaced table provides a
 248  *          malloc function that the pktlib heap library uses to allocate data for the heap
 249  *          buffers.
 250  *  @param[in]  none
 251  *  @retval     @ref Pktlib_HeapIfTable pointer
 252  *  @pre        @ref netapi_init
 253  */
 254 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
 255
 256 /** utilities to see how much mem/descriptor space is remaining **/
 257
 258 /**  @ingroup netapi_api_functions */
 259 /*
 260 *  @brief  API is used to return the amount of free memory available for allocating buffers
 261  (          for additonal Pktlib heaps.
 262  *  @details  the applicaiton can use this API to determine how much free memory is          .
 263  *           available for heap buffers if it decides to create its own.
 264  *  @param[in]  void
 265  *  @retval     int :  amount of memory available for heap buffer storage (in bytes)
 266  *  @pre        @ref netapi_init
 267  */
 268 int  netapi_getBufMemRemainder(void);
 269 /**  @ingroup netapi_api_functions */
 270
 271 /*
 272 *  @brief  API is used to return the amount of free memory available for allocating Descriptors
 273  (          for additonal Pktlib heaps.
 274  *  @details  the applicaiton can use this API to determine how much free memory is          .
 275  *           available for heap descriptors if it decides to create its own heap.
 276  *  @param[in]  void
 277  *  @retval     int :  amount of memory available for heap descriptor storage (in bytes)
 278  *  @pre        @ref netapi_init
 279  */
 280 int  netapi_getDescRemainder(void);
 281
 282 /* utility to get default flow */
 283 /**  @ingroup netapi_api_functions */
 284 /*
 285 *  @brief  API is used to return the default NETCP flow that is to be used for received
 286  (          packets..
 287  *  @details  the applicaiton can use this API to return the default NETCP flow that is used
 288  *           for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
 289  *           used to supply free packets to the receive DMA function.
 290  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 291  *  @retval     NETCP_CFG_FLOW_HANDLE_T  : handle to default flow
 292  *  @pre        @ref netapi_init
 293  */
 294 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p) {
 295 return NETCP_DEFAULT_FLOW;
 296 }
 297
 298 /* utility to get default route */
 299 /**  @ingroup netapi_api_functions */
 300 /*
 301 *  @brief  API is used to return the default NETCP route
 302  *
 303  *  @details  this functions returns the default NETCP route created by @ref netapi_init.
 304  *            A netcp route consists of a NETCP flow plus a destination pktio channel
 305  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 306  *  @retval     NETCP_CFG_ROUTE_HANDLE_T:  the handle of the default route.
 307  *  @pre        @ref netapi_init
 308  */
 309 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p) {
 310 return NETCP_DEFAULT_ROUTE;
 311 }
 312
 313 /* utility to set/get a cookie in the netapi handle */
 314 /**  @ingroup netapi_api_functions */
 315 /*
 316 *  @brief  API is used to return a piece of application-provided opaque data that has been
 317  (          stored in the netapi instance.
 318  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
 319  *           This APi lets this data be returned to the application.
 320  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 321  *  @retval     void *
 322  *  @pre        @ref netapi_init  @ref netapi_setCookie
 323  */
 324 static inline void * netapi_getCookie(NETAPI_T p)
 325 {
 326 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 327 return pp->cookie;
 328 }
 329
 330 /**  @ingroup netapi_api_functions */
 331 /*
 332 *  @brief  API is used to set a piece of application-provided opaque data in the
 333  (         netapi instance.
 334  *  @details  the applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
 335  *           This APi can be returned later to the application via @ref netapi_getCookie
 336  *  @param[in]  @ref NETAPI_T :  handle to NETAPI instance
 337  *  @param[in]  void * : opaque data to be saved
 338  *  @retval     void
 339  *  @pre        @ref netapi_init
 340  */
 341 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
 342 {
 343 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 344 pp->cookie= cookie;
 345 }
 346
 347
 348 /**  @ingroup netapi_api_functions */
 349 /*
 350 *  @brief  API is used to poll for NETCP configuration response messages.
 351  *
 352  *  @details  Application, if controlling the scheduler,  will need to call this
 353  *            function periodically to check for NETCP configuration responses (eg
 354  *            statistics requests).
 355  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 356  *  @retval     none
 357  *  @pre        @ref netapi_init
 358  */
 359 void netapi_netcpPoll(NETAPI_T  p);
 360
 361 //heap registration for polling purposes
 362
 363 /**  @ingroup netapi_api_functions */
 364 /*
 365 *  @brief  API is used to register a heap that is created by application so that
 366  *          it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage().
 367  *
 368  *  @details  this function registers an application-created heap with the netapi instance
 369  *            so that it can add that heap's garbage queue to the garbage poll function.
 370  *            NOTE: netapi internal heap is automatically registered
 371  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 372  *  @param[in]  @ref Pktlib_HeapHandle:  handle of heap to register
 373  *  @retval     int :  1 if OK, <0 on error
 374  *  @pre        @ref netapi_init  @ref Pktlib_CreateHeap
 375  */
 376 static inline int netapi_registerHeap(NETAPI_T p,  Pktlib_HeapHandle h)
 377 {
 378 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 379 int i;
 380 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
 381 {
 382         if (!pp->createdHeaps[i]) {pp->createdHeaps[i]=h; return 1;}
 383 }
 384 return -1;  //no room
 385 }
 386
 387 /**  @ingroup netapi_api_functions */
 388 /*
 389 *  @brief  API is used to un-register a heap that was created by application and previously
 390 *           registerd so that
 391  *          it's garbage queue could  be polled automatically by @ref netapi_poll_heapGarbage().
 392  *
 393  *  @details  this function un-registers an application-created heap with the netapi instance
 394  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance
 395  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap
 396  *  @retval     <0 if err, 1 if OK
 397  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
 398  */
 399 static inline int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h)
 400 {
 401 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 402 int i;
 403 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
 404 {
 405         if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
 406 }
 407 return -1;  //not found
 408 }
 409
 410 /**  @ingroup netapi_api_functions */
 411 /*
 412 *  @brief  API is used to remove a created pktlib heap
 413  *
 414  *  @details  this function removes anapplication-created heap with the netapi instance
 415  *             [note -> descriptors are zapped and cannot be reused]
 416  *  @param[in]  @ref NETAPI_T:  handle to NETAPI instance
 417  *  @param[in]  @ref Pktlib_HeapHandle :  handle to heap
 418  *  @retval     <0 if err, 1 if OK
 419  *  @pre        @ref netapi_init ,  @ref Pktlib_CreateHeap, @ref netai_registerHeap()
 420  */
 421
 422 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
 423
 424 /**  @ingroup netapi_api_functions */
 425 /*
 426 *  @brief  API is used to poll the garbage collection queue for the internal NETAPI heaps and
 427  *         any application created heaps
 428  *
 429  *  @details  this function is used to poll the netapi internal heaps and any
 430  * application-created heaps    that have been registered with the netapi instance.  The
 431  * poll function checks the garbage collection queue associated with the heap and returns
 432  * descriptors and buffers when appropriate to the main free queue.
 433  *  @param[in]  @ref NETAPI_T  handle to NETAPI instance
 434  *  @retval     none
 435  *  @pre        @ref netapi_init  @ref pktlib_CreateHeap
 436  */
 437 void netapi_poll_heapGarbage(NETAPI_T p);
 438
 439 static inline int netapi_get_version(void) {return NETAPI_VERSION_ID;}
 440 static inline char * netapi_get_version_string(void) { return NETAPI_VERSION_STR;}
 441
 442 #endif