ti/runtime/netapi/pktio.h

   1 /*********************************
   2  *FILE:  pktio.h
   3  *PURPOSE:  pktio library header
   4  **************************************************************
   5  * @file  pktio.h
   6  *
   7  * @bried DESCRIPTION:  pktio module  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 #ifndef __PKTIO__H
  44 #define __PKTIO__H
  45 #include "netapi.h"
  46 #include "ti/runtime/pktlib/pktlib.h"
  47 #include "ti/drv/nwal/nwal.h"
  48 #include "ti/drv/nwal/nwal_util.h"
  49 #include "netapi_err.h"
  50
  51 /*--------------------defines-----------------------*/
  52 #define PKTIO_NOMEM  NETAPI_ERR_NOMEM
  53 //default pktio channels
  54 #define NETCP_TX "NETCP_TX"
  55 #define NETCP_RX "NETCP_RX"
  56 #define NETCP_SB_RX "NETCP_SB_RX"
  57 #define NETCP_SB_TX "NETCP_SB_TX"
  58 #define PKTIO_MAX_NAME 19
  59
  60 /*--------------------data structures----------------*/
  61 typedef struct PKTIO_METADATA_Tag
  62 {
  63   int flags1;
  64 #define PKTIO_META_RX 0x01
  65 #define PKTIO_META_TX 0x02
  66 #define PKTIO_META_SB_RX 0x4  //SB crypto rx
  67 #define PKTIO_META_SB_TX 0x8  //SB crypto tx
  68 #define PKTIO_META_APP_DEF 0x80000000
  69   union
  70   {
  71         nwalRxPktInfo_t * rx_meta;
  72         nwalTxPktInfo_t * tx_meta;
  73         nwalDmRxPayloadInfo_t * rx_sb_meta;
  74         nwalDmTxPayloadInfo_t * tx_sb_meta;
  75   } u;
  76   void * sa_handle; //valid for PKTIO_META_TX with IPSEC inflow  or PKTIO_PKTIO_META_SB_TX .
  77                     // MUST BE nwal_HANDLE_INVALID otherwise
  78 } PKTIO_METADATA_T;
  79
  80 /* the callback function */
  81 struct PKTIO_HANDLE_tag;
  82
  83 //polling control
  84 typedef struct PKTIO_POLL_Tag
  85 {
  86 /* future */
  87 } PKTIO_POLL_T;
  88
  89 #define PKTIO_MAX_RECV  (TUNE_NETAPI_MAX_BURST_RCV)
  90 typedef void (*PKTIO_CB)(struct PKTIO_HANDLE_tag * channel, Ti_Pkt* p_recv[],
  91                          PKTIO_METADATA_T p_meta[], int n_pkts,
  92                          uint64_t ts );
  93
  94 typedef int (*PKTIO_SEND)(struct PKTIO_HANDLE_tag * channel, Ti_Pkt* p_send,
  95                          PKTIO_METADATA_T *p_meta, int * p_err);
  96
  97 typedef int (*PKTIO_POLL)(struct PKTIO_HANDLE_tag * channel,PKTIO_POLL_T * p_poll_cfg ,
  98                           int * p_err);
  99
 100 /** channel configuration */
 101 #define PKTIO_NA 0
 102 typedef struct PKTIO_CFG_Tag
 103 {
 104 #define PKTIO_R 0x1
 105 #define PKTIO_W 0x2
 106 #define PKTIO_RW (PKTIO_R | PKTIO_W)
 107 int flags1;
 108
 109 #define PKTIO_LOCAL  0x2
 110 #define PKTIO_GLOBAL 0x1
 111 #define PKTIO_PKT    0x4  //define this if this channel is for NETCP
 112 #define PKTIO_SB     0x8  //define this if this channel is for sideband crypto
 113 int flags2;
 114
 115 //for create
 116 #define PKTIO_Q_ANY -1
 117 int qnum;
 118
 119 //for poll
 120 int max_n;
 121 }PKTIO_CFG_T;
 122
 123 struct NETAPI_tag;
 124
 125 /* a pktio channel .. */
 126
 127 typedef struct PKTIO_HANDLE_Tag
 128 {
 129 #define PKTIO_INUSE 0xfeedfeed
 130         int inuse;
 131         int use_nwal;  /* true if this is managed by nwal */
 132 #define  PKTIO_4_IPC 0   //For IPC
 133 #define  PKTIO_4_ADJ_NWAL 1 //(RX)app queues managed by NWAL
 134 #define  PKTIO_DEF_NWAL 2  // default NWAL RX/TX queues
 135 #define  PKTIO_4_ADJ_SB 3  //(RX) crypto side band app defined
 136 #define  PKTIO_DEF_SB 4  //crypto side band default
 137         struct NETAPI_tag * back;  /* back handle */
 138         void * nwalInstanceHandle;      /* save here for conveninece */
 139         PKTIO_CB cb;      /* callback for channel */
 140         PKTIO_CFG_T cfg; /* configuration */
 141         Qmss_QueueHnd q;  /* the associated queue handle */
 142         Qmss_Queue qInfo;        /*   and its qm#/q# */
 143         int max_n;        /* max # of pkts to read in one poll */
 144         void * cookie;    /* app specific */
 145         PKTIO_SEND _send;  /* pktio type specific send function */
 146         PKTIO_POLL _poll;  /* pktio type specific POLL function */
 147         char name[PKTIO_MAX_NAME+1];
 148 }  PKTIO_HANDLE_T;
 149
 150
 151
 152 typedef struct PKTIO_CONTROL_Tag
 153 {
 154 #define PKTIO_CLEAR 0x1   //clear out the channel
 155 #define PKTIO_DIVERT 0x2  //divert, (to dest channel)
 156   int op;
 157   PKTIO_HANDLE_T *dest;
 158 } PKTIO_CONTROL_T;
 159
 160
 161
 162 /*---------------------------------------------------*/
 163 /*-------------------------API-----------------------*/
 164 /*---------------------------------------------------*/
 165
 166 /*
 167 *  @brief  API creates a NETAPI channel
 168  *
 169  *  @details This assigns global resources to a NETAPI pktio channel.
 170  *   Once created, the channel can be used to send and/or receive
 171  *   a TI @ref Ti_Pkt. This can be used for communication with the
 172  *   the Network co-processor (NETCP) or for internal inter-processor
 173  *   communication. The channel is saved under the assigned name
 174  *   and can be opened by other netapi threads instances.
 175  *  @param[in]  @ref NETAPI_T: handle to the instance
 176  *  @param[in]  char * name: a pointer to the char string name for channel
 177  *  @param[in]  @ref PKTIO_CB : callback to be issued on packet receive
 178  *  @param[in]  @ref PKTIO_CFG_T: pointer to channel configuration
 179  *  @param[out] int * err:  pointer to error return
 180  *  @retval     @ref PKTIO_HANDLE_T: handle to the pktio instance or NULL on error
 181  *  @pre       @ref netapi_init
 182  */
 183 PKTIO_HANDLE_T * pktio_create(NETAPI_T netapi_handle, /* netapi instance */
 184                                char * name,  /* name of the channel */
 185                                PKTIO_CB cb,  /* receive callback */
 186                                PKTIO_CFG_T * p_cfg,  /* ptr to config*/
 187                                int * err);
 188
 189 /*
 190 *  @brief  API opens an existing  NETAPI channel
 191  *
 192  *  @details This opens an NETAPI pktio channel for use. The channel
 193  *  must have already been created via @ref pktio_create or may have
 194  *  been created internally during the netapi intialization.
 195  *   Once opened, the channel can be used to send and/or receive
 196  *   a TI @ref Ti_Pkt. This can be used for communication with the
 197  *   the Network co-processor (NETCP) or for internal inter-processor
 198  *   communication.
 199  *
 200  *  @param[in]  @ref NETAPI_T: handle to the instance
 201  *  @param[in]  char * name: a pointer to the char string name for channel
 202  *  @param[in]  @ref PKTIO_CB : callback to be issued on packet receive
 203  *  @param[in]  @ref PKTIO_CFG_T: pointer to channel configuration
 204  *  @param[out] int * err:  pointer to error return
 205  *  @retval     @ref PKTIO_HANDLE_T: handle to the pktio instance or NULL on error
 206  *  @pre       @ref netapi_init , @ref pktio_create
 207  */
 208 PKTIO_HANDLE_T * pktio_open(NETAPI_T netapi_handle, /* netapi instance */
 209                             char *name,  /* name of channel to open */
 210                             PKTIO_CB cb, /* receive callback */
 211                             PKTIO_CFG_T *p_cfg, /* channel configuration */
 212                             int * err);
 213
 214 /* future: control the channel */
 215 void pktio_control(PKTIO_HANDLE_T * channel, //handle from open or create
 216                                PKTIO_CB cb,  //change the callback
 217                                PKTIO_CFG_T * p_cfg,//optional
 218                                PKTIO_CONTROL_T *p_control,//optional
 219                                int *err);
 220
 221 /* future: close or delete a pktio channel */
 222 void pktio_close(PKTIO_HANDLE_T * channel, int * err);
 223 void pktio_delete(PKTIO_HANDLE_T * channel, int * err);
 224
 225 /*
 226 *  @brief  API sends data to a pktio channel
 227  *
 228  *  @details This sends a @ref Ti_Pkt and associated meta data,
 229  *  @ref PKTIO_METADATA_T to a channel. The channel
 230  *  must have already been created via @ref pktio_create or opened
 231  *  via @ref pktio_open.  It  may have
 232  *  been created internally during the netapi intialization.
 233  *  @param[in]  @ref PKTIO_HANDLE_T: handle to the channel
 234  *  @param[in]  @ref Ti_Pkt*: pointer to the packet to send
 235  *  @param[in]  @ref PKTIO_METADATA_T: pointer to meta data associated with packet
 236  *  @param[out] int * err:  pointer to error return
 237  *  @retval      int npkts: 1 if packet sent, 0 if error
 238  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
 239  */
 240 static inline int  pktio_send(PKTIO_HANDLE_T * channel, /* the channel */
 241                 Ti_Pkt *pkt,              /* pointer to packet */
 242                 PKTIO_METADATA_T *m,      /* pointer to meta data */
 243                 int * err)
 244 {
 245    return channel->_send((struct PKTIO_HANDLE_tag *)channel, pkt, m, err);
 246 }
 247
 248 /*
 249 *  @brief  API sends data to a pktio channel
 250  *
 251  *  @details This sends an array of @ref Ti_Pkt and associated meta data,
 252  *  @ref PKTIO_METADATA_T to a channel. The channel
 253  *  must have already been created via @ref pktio_create or opened
 254  *  via @ref pktio_open.  It  may have
 255  *  been created internally during the netapi intialization.
 256  *  @param[in]  @ref PKTIO_HANDLE_T: handle to the channel
 257  *  @param[in]  @ref Ti_Pkt*: pointer to the packet to send
 258  *  @param[in]  @ref PKTIO_METADATA_T: pointer to meta data associated with packet
 259  *  @oaran[in[  int np:  the number of packets in list to send
 260  *  @param[out] int * err:  pointer to error return
 261  *  @retval      int npkts: number of packets sent, 0 if error
 262  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
 263  */
 264 int pktio_sendMulti(PKTIO_HANDLE_T *channel, /* the channel handle */
 265                     Ti_Pkt * pkt[], /* array of packets to send */
 266                     PKTIO_METADATA_T * m[], /* meta data array */
 267                     int np,      /* number of packets to send */
 268                     int * err);
 269
 270 /***********************************/
 271 /************* polling **************/
 272 /***********************************/
 273
 274 /*
 275 *  @brief  API polls a pkto channel for received packets
 276  *
 277  *  @details This api polls a pktio channel. Any pending data in the channel is
 278  *  passed to the @ref  PKTIO_CB registered when the channel was
 279  *  created or opened. The channel must
 280  *  have already been created via @ref pktio_create or opened
 281  *  via @ref pktio_open.  It  may have
 282  *  been created internally during the netapi intialization.
 283  *  @param[in]  @ref PKTIO_HANDLE_T: handle to the channel
 284  *  @param[in]  @ref PKTIO_POLL_T *: pointer to pktio poll configuration
 285  *  @param[out] int * err:  pointer to error return
 286  *  @retval      int npkts: number of packets received by poll
 287  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
 288  */
 289 static inline int pktio_poll(PKTIO_HANDLE_T * handle,   //handle to pktio
 290                PKTIO_POLL_T * p_poll_cfg,  //polling configuration
 291                int * err)
 292 {
 293         return handle->_poll((struct PKTIO_HANDLE_tag *) handle, p_poll_cfg, err);
 294 }
 295
 296 /*
 297 *  @brief  API polls all pkto channels associarted with @ref NETAPI_T instance
 298  *         for received packets
 299  *
 300  *  @details This api polls all pktio channels attached to an instance.
 301  *  Any pending data in these channels are
 302  *  passed to the @ref  PKTIO_CB registered when the channel was
 303  *  created or opened. The channels  must
 304  *  have already been created via @ref pktio_create or opened
 305  *  via @ref pktio_open.  They may have
 306  *  been created internally during the netapi intialization.
 307  *  @param[in]  @ref NETAPI_T: handle of the NETAPI instance
 308  *  @param[in]  @ref PKTIO_POLL_T *: pointer to pktio poll configuration
 309  *  @param[out] int * err:  pointer to error return
 310  *  @retval      int npkts: number of packets received by poll
 311  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
 312  */
 313 int pktio_pollAll(NETAPI_T handle, PKTIO_POLL_T * p_poll_cfg, int *err);
 314
 315 /*----------------- utilities------------------ */
 316 /* update max_n for poll */
 317 #define pktio_set_max_n(handle,max_n) (handle)->max_n=max_n;
 318 #define pktio_get_netapi_handle(handle) (handle)->back
 319 #define pktio_set_cookie(handle, cookie) (handle)->cookie = cookie
 320 #define pktio_get_cookie(handle) (handle)->cookie
 321 #define pktio_get_q(handle) (handle)->q
 322
 323 /*-----------------Extra Fast Path pkt meta data macros--------------------*/
 324 #include "cppi_desc.h"
 325 #include "ti/drv/pa/pa.h"
 326 #include "ti/drv/pa/pasahost.h"
 327
 328
 329 //return default packet queue to poll for netcp RX
 330 //these are expensive calls, so call once and save
 331 static inline Qmss_QueueHnd PKTIO_GET_DEFAULT_NETCP_Q(PKTIO_HANDLE_T *h)
 332 {
 333 nwalGlobCxtInfo_t Info;
 334 nwal_getGlobCxtInfo(h->nwalInstanceHandle,&Info);
 335 return Info.rxDefPktQ;
 336 }
 337
 338 //return L4Queue to poll for netcp RX (L4 classifier queue)
 339 //these are expensive calls, so call once and save
 340 static inline Qmss_QueueHnd PKTIO_GET_DEFAULT_NETCP_L4Q(PKTIO_HANDLE_T *h)
 341 {
 342 nwalLocCxtInfo_t Info;
 343 nwal_getLocCxtInfo(h->nwalInstanceHandle,&Info);
 344 return Info.rxL4PktQ;
 345 }
 346
 347
 348
 349 static inline void PKTIO_QMSS_QUEUE_PUSH_DESC_SIZE_RAW(Qmss_QueueHnd hnd, void *descAddr, uint32_t descSize)
 350 {
 351     return(Qmss_queuePushDescSizeRaw(hnd,descAddr,descSize));
 352 }
 353
 354 static inline void* PKTIO_QMSS_QUEUE_POP_RAW(Qmss_QueueHnd hnd)
 355 {
 356     return(Qmss_queuePopRaw(hnd));
 357 }
 358
 359 //Return NWAL Global Instance
 360 static inline nwal_Inst PKTIO_GET_NWAL_INSTANCE(PKTIO_HANDLE_T *h)
 361 {
 362 return h->nwalInstanceHandle;
 363 }
 364
 365
 366 #endif