ti/runtime/netapi/pktio.h

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