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  */
  50
  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  */
  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
  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 /** @} */
  95
  96
  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  */
 107
 108 /** @defgroup netapi_sched_functions NETAPI Scheduler Functions
 109  *  @ingroup netapi
 110  */
 111
 112 /** @defgroup netapi_pktio_functions NETAPI PKTIO Functions
 113  *  @ingroup netapi
 114  */
 115
 116 /** @defgroup netapi_cb_functions NETAPI Callback Functions
 117  *  @ingroup netapi
 118  */
 119
 120
 121 /** @defgroup netapi_structures NETAPI Structures used in API's
 122  *  @ingroup netapi
 123  */
 124
 125 /** @defgroup netapi_tune_parameters NETAPI Tune Parameters
 126  *  @ingroup netapi
 127  */
 128
 129
 130 /**
 131  * @def NETAPI_VERSION_ID
 132  *      This is the NETAPI Version. Versions numbers are encoded in the following
 133  *      format:
 134  *              0xAABBCCDD -> Arch (AA); API Changes (BB); Major (CC); Minor (DD)
 135  */
 136 #define NETAPI_VERSION_ID                   (0x01000004)
 137
 138 /**
 139  * @def NETAPI_VERSION_STR
 140  *      This is the version string which describes the NETAPI along with the
 141  *      date and build information.q
 142  */
 143 #define NETAPI_VERSION_STR      "NETAPI Revision: 01.00.00.04"
 144
 145
 146 /**
 147  * @ingroup netapi_structures
 148  * @brief  One per thread, used in most NETAPI function calls.
 149  */
 150 typedef void * NETAPI_T;
 151
 152
 153 /**
 154  * @def NETAPI_SYS_MASTER
 155  *      This defines master for system
 156  */
 157 #define NETAPI_SYS_MASTER  2
 158
 159 /**
 160  * @def NETAPI_CORE_MASTER
 161  *      This defines master for core
 162  */
 163 #define NETAPI_CORE_MASTER 1
 164
 165 /**
 166  * @def  NETAPI_NO_MASTER
 167  *      This defines no mater, data only
 168  */
 169 #define NETAPI_NO_MASTER   0  //data only
 170
 171
 172 /**
 173  *  @ingroup netapi_structures
 174  *  @brief NETAPI configuration information
 175  *
 176  *  @details The parameters in this structure are used to configure NETAPI.
 177  */
 178 typedef struct NETAPI_CFG_Tag
 179 {
 180  int def_mem_size;                  /**<  Bytes of CMA memory we have allocated */
 181  int def_flow_pkt_rx_offset;        /**<  Offset in pkt buffer for hw to start RX */
 182  int def_max_descriptors;           /**<  Number of descriptors in system  (must be power of 2), 2^14 max */
 183  int def_tot_descriptors_for_us;    /**<  Number of descriptors to create in our region (must be power of 2)*/
 184  int def_heap_n_descriptors;        /**<  Number of descriptor plus buffers in default heap*/
 185  int def_heap_n_zdescriptors;       /**<  Number of zero len descriptors in defaule heap*/
 186  int def_heap_buf_size;             /**<  Size of buffers in default heap, max amount of area for packet data */
 187  int def_heap_tailroom_size;        /**<  Size of tailroom in reserve */
 188  int def_heap_extra_size;           /**<  Size of extra space at end of buffer */
 189 }  NETAPI_CFG_T;
 190
 191 /* @note:
 192    each buffer will be allocated:  def_heap_buf_size+def_heap_extra_size bytes
 193    each descriptor attached to these buffers will have rigBufferLen of:
 194       def_heap_buf_size.
 195    for default RX flow,  for rx packet, the bufptr  will be def_flow_pkt_rx_offset.
 196    for detault RX flow,  threshold (ie max # of bytes in buffer) will be:
 197        def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset
 198
 199
 200  RX Packet from NetCP
 201
 202 Headroom [Application]     Packet [HW]                Tailroom [Application]    Extra Space [Application]
 203 <-----------------------><--------------------------><------------------------><----------------------->
 204
 205 Cppi_HostDesc->origBufferLen
 206 <----------------------------------------------------------------------------->
 207 Cppi_HostDesc->origBuffPtr
 208 |
 209 \/
 210 |------------def_heap_buf_size-------------------------------------------------|--def_heap_extra_size--|
 211 | def_flow_pkt_rx_offset| max Cppi_HostDesc->buffLen | def_heap_tailroom_size  |   Extra Size          |
 212                         ^
 213                         |
 214                      Cppi_HostDesc->buffPtr
 215
 216
 217 */
 218
 219
 220
 221 #include "netapi_err.h"
 222 #include "netapi_tune.h"
 223 #include "ti/runtime/pktlib/pktlib_osal.h"
 224 #include "ti/runtime/pktlib/pktlib.h"
 225 #include "pktio.h"
 226 #include "ti/drv/pa/pa.h"
 227 #include "netcp_cfg.h"
 228 #include "netapi_sec.h"
 229 #include "netapi_sched.h"
 230 #include "src/netapi_vm.h"
 231 #include "netapi_util.h"
 232 #include "netsync.h"
 233 #include "ti/drv/nwal/nwal.h"
 234 #include "netapi_timer.h"
 235 #include "src/netapi_loc.h"
 236
 237 /**
 238  *  @ingroup netapi_gen_functions
 239  *  @brief netapi_init  API instantiates the NETAPI and allocated global resources.
 240  *
 241  *  @details The API will allocate global resources valid  per system level common across all ARM cores
 242  *           or per thread based on "master" argument.
 243  *           Intializes the following substems: pktio pklib qmss cppi 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 @ref NETAPI_CFG_T or NULL to use netapi default configuration.
 247  *  @retval     Handle to the instance or NULL on error, @ref NETAPI_T
 248  *  @pre        none
 249  */
 250  NETAPI_T  netapi_init(int master, NETAPI_CFG_T * p_cfg);
 251
 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]  p   The NETAPI handle, @ref NETAPI_T
 259  *  @retval     none
 260  *  @pre        @ref netapi_init
 261  */
 262 void netapi_shutdown(NETAPI_T  p);
 263
 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 Pktlib_CreateHeap
 270  *           The memory used for these heaps is  special with the following characteristics:
 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  *  @retval     Pktlib_HeapIfTable pointer
 278  *  @pre        @ref netapi_init
 279  */
 280 Pktlib_HeapIfTable *netapi_getPktlibIfTable(void) ;
 281
 282 /**
 283  *  @ingroup netapi_gen_functions
 284  *  @brief netapi_getBufMemRemainder  API is used to return the amount of free memory available for allocating buffers
 285  *                                    for additonal Pktlib heaps
 286  *
 287  *  @details The application can use this API to determine how much free memory is
 288  *           available for heap buffers if it decides to create its own.
 289  *  @retval     Amount of memory available for heap buffer storage (in bytes)
 290  *  @pre        @ref netapi_init
 291  */
 292 int  netapi_getBufMemRemainder(void);
 293
 294
 295 /**
 296  *  @ingroup netapi_gen_functions
 297  *  @brief netapi_getDescRemainder  API is used to return the amount of free memory available for allocating descriptors
 298  *                                  for additonal Pktlib heaps.
 299  *
 300  *  @details The application can use this API to determine how much free memory is
 301  *           available for heap descriptors if it decides to create its own heap.
 302  *  @retval     Amount of memory available for heap descriptor storage (in bytes)
 303  *  @pre        @ref netapi_init
 304  */
 305 int  netapi_getDescRemainder(void);
 306
 307 /**
 308  *  @ingroup netapi_gen_functions
 309  *  @brief netapi_getDefaultFlow:  API is used to return the default NETCP flow that is to be used for incoming packets.
 310  *
 311  *  @details   The application can use this API to return the default NETCP flow that is used
 312  *             for received packets. A NETCP flow is a list of PacketLib Heaps that are to be
 313  *             used to supply free packets to the receive DMA function.
 314  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
 315  *  @retval     NETCP_CFG_FLOW_HANDLE_T     The handle to default flow
 316  *  @pre        @ref netapi_init
 317  */
 318 static inline NETCP_CFG_FLOW_HANDLE_T netapi_getDefaultFlow(NETAPI_T p)
 319 {
 320     return NETCP_DEFAULT_FLOW;
 321 }
 322
 323 /**
 324  *  @ingroup netapi_gen_functions
 325  *  @brief netapi_getDefaultRoute:  API is used to return the default NETCP route handle.
 326  *
 327  *  @details This API returns the default NETCP route created by @ref netapi_init.
 328  *           A netcp route consists of a NETCP flow plus a destination pktio channel
 329  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
 330  *  @retval     The handle of the default route, NETCP_CFG_ROUTE_HANDLE_T
 331  *  @pre        @ref netapi_init
 332  */
 333 static inline NETCP_CFG_ROUTE_HANDLE_T netapi_getDefaultRoute(NETAPI_T p)
 334 {
 335     return NETCP_DEFAULT_ROUTE;
 336 }
 337
 338 /**
 339  *  @ingroup netapi_gen_functions
 340  *  @brief netapi_getCookie  API is used to return a piece of application-provided opaque data that has been
 341  *                           stored in the netapi instance.
 342  *
 343  *  @details The application can save a pointer to opaque data in the @ref NETAPI_T instance.
 344  *           This APi lets this data be returned to the application.
 345  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
 346  *  @retval     Data provided in @ref netapi_setCookie
 347  *  @pre        @ref netapi_init, @ref netapi_setCookie
 348  */
 349
 350 static inline void * netapi_getCookie(NETAPI_T p)
 351 {
 352     NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 353     return pp->cookie;
 354 }
 355
 356 /**
 357  *  @ingroup netapi_gen_functions
 358  *  @brief netapi_setCookie  API is used to set a piece of application-provided opaque data t in the netapi instance.
 359  *
 360  *  @details The applicaiton can save a pointer to opaque data in the @ref NETAPI_T instance.
 361  *           Pointer to a opaque data can be returned later to the application via @ref netapi_getCookie
 362  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
 363  *  @param[in]  cookie Opaque data to be saved
 364  *  @retval     none
 365  *  @pre        @ref netapi_init
 366  */
 367 static inline void netapi_setCookie(NETAPI_T p, void * cookie)
 368 {
 369     NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 370     pp->cookie= cookie;
 371 }
 372
 373 /**
 374  *  @ingroup netapi_gen_functions
 375  *  @brief netapi_netcpPoll  API is used to poll for NETCP configuration response messages.
 376  *
 377  *  @details Application, if controlling the scheduler,  will need to call this
 378  *           function periodically to check for NETCP configuration responses (eg
 379  *           statistics requests).
 380  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
 381  *  @retval     none
 382  *  @pre        @ref netapi_init
 383  */
 384 void netapi_netcpPoll(NETAPI_T  p);
 385
 386 /**
 387  *  @ingroup netapi_gen_functions
 388  *  @brief netapi_registerHeap  API is used to register a heap that is created by application so that
 389  *                              it's garbage queue can be polled automatically by @ref netapi_poll_heapGarbage().
 390  *
 391  *  @details This API registers an application-created heap with the netapi instance
 392  *           so that it can add that heap's garbage queue to the garbage poll function.
 393  *           NOTE: netapi internal heap is automatically registered
 394  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
 395  *  @param[in]  h   Handle of pklib heap to register
 396  *  @retval     1 if OK, <0 on error
 397  *  @pre        @ref netapi_init
 398  */
 399 static inline int netapi_registerHeap(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]) {pp->createdHeaps[i]=h; return 1;}
 406 }
 407 return -1;  //no room
 408 }
 409
 410 /**
 411  *  @ingroup netapi_gen_functions
 412  *  @brief netapi_unregisterHeap  API is used to un-register a heap that was created by application
 413  *                                and previously registerd so that it's garbage queue could  be polled
 414  *                                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   The NETAPI handle, @ref NETAPI_T
 419  *  @param[in]  h   The pklib handle to heap
 420  *  @retval     <0 if err, 1 if OK
 421  *  @pre        @ref netapi_init , @ref netapi_registerHeap()
 422  */
 423 static inline int netapi_unregisterHeap(NETAPI_T p,  Pktlib_HeapHandle h)
 424 {
 425 NETAPI_HANDLE_T *pp = (NETAPI_HANDLE_T *) p;
 426 int i;
 427 for(i=0;i<TUNE_NETAPI_MAX_HEAPS;i++)
 428 {
 429         if (pp->createdHeaps[i] == h) {pp->createdHeaps[i]=NULL; return 1;}
 430 }
 431 return -1;  //not found
 432 }
 433
 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   The NETAPI handle, @ref NETAPI_T
 441  *  @param[in]  h :  handle to pklib heap
 442  *  @retval     <0 if err, 1 if OK
 443  *  @pre        @ref netapi_init  @ref netapi_registerHeap
 444  */
 445 int netapi_closeHeap(NETAPI_T p, Pktlib_HeapHandle h);
 446
 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]  p   The NETAPI handle, @ref NETAPI_T
 457  *  @retval     none
 458  *  @pre        @ref netapi_init
 459  */
 460 void netapi_poll_heapGarbage(NETAPI_T p);
 461
 462 /**
 463  *  @ingroup netapi_gen_functions
 464  *  @brief netapi_get_version  API used to get version of NETAPI
 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)
 471 {
 472 return NETAPI_VERSION_ID;
 473 }
 474
 475 /**
 476  *  @ingroup netapi_gen_functions
 477  *  @brief netapi_get_version_string  API used to get version string of NETAPI
 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;}
 484
 485 #endif