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 2013
  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 pktio.h
  44  *   @brief pktio module main header file for user space transport library
  45  *   @details:  pktio provides an abstraction to H/W queues that are used to transmit and receive packets,
  46  *              IPC messages, etc.  Pktio channels can be created by user but there are also several canned
  47  *              channels available  for NETCP transmit, receive, SA sideband crypto transmit and receive
  48  */
  49
  50
  51
  52 #ifndef __PKTIO__H
  53 #define __PKTIO__H
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59
  60 #include "netapi.h"
  61 #include "ti/drv/nwal/nwal.h"
  62 #include "ti/drv/nwal/nwal_util.h"
  63
  64 /**
  65  * @def NETCP_TX
  66  * @ingroup pktio_constants
  67  *      This defines the default PKTIO NETCP transmit channel name
  68  */
  69 #define NETCP_TX "NETCP_TX"
  70
  71 /**
  72  * @def NETCP_RX
  73  * @ingroup pktio_constants
  74  * @brief This defines the default PKTIO NETCP receive channel name
  75  */
  76 #define NETCP_RX "NETCP_RX"
  77
  78 /**
  79  * @def NETCP_SB_RX
  80  * @ingroup pktio_constants
  81  * @brief This defines the PKTIO NETCP-SA receive SIDEBAND channel name.
  82           This channel is used to receive the results from sideband crypto operations
  83  */
  84 #define NETCP_SB_RX "NETCP_SB_RX"
  85
  86 /**
  87  * @def NETCP_SB_TX
  88  * @ingroup pktio_constants
  89  * @brief This defines the PKTIO NETCP-SA transmit SIDEBAND channel name.
  90           This channel is used to send packets for sideband crypto operations
  91  */
  92 #define NETCP_SB_TX "NETCP_SB_TX"
  93
  94 /**
  95  * @def PKTIO_MAX_NAME
  96  * @ingroup pktio_constants
  97  *      This defines the maximum length of a pktio channel name
  98  */
  99 #define PKTIO_MAX_NAME 19
 100
 101 /**
 102  *  @ingroup pktio_structures
 103  *  @brief PKTIO meta data information .
 104  *
 105  *  @details PKTIO meta data information. meta data is used to convey the results of NETCP pre-processing on receive packets and to tell NETCP what functions to perform on transmitted packets. It is a union of sub-structures (one for TX, one for RX, one for sideband rx, one for sideband tx).
 106  */
 107 typedef struct PKTIO_METADATA_Tag
 108 {
 109
 110     int flags1;     /**< Configuration flags for PKTIO channel, @ref PKTIO_META_RX,
 111                                                                 @ref PKTIO_META_TX,
 112                                                                 @ref PKTIO_META_SB_RX,
 113                                                                 @ref PKTIO_META_SB_TX*/
 114
 115 /**
 116  * @def PKTIO_META_RX
 117  * @ingroup pktio_constants
 118  *      This defines the PKTIO NETCP receive INFLOW channel
 119  */
 120 #define PKTIO_META_RX 0x01
 121
 122 /**
 123  * @def PKTIO_META_TX
 124  * @ingroup pktio_constants
 125  *      This defines the PKTIO NETCP transmit INFLOW channel
 126  */
 127 #define PKTIO_META_TX 0x02
 128
 129 /**
 130  * @def PKTIO_META_SB_RX
 131  * @ingroup pktio_constants
 132  *      This defines the PKTIO NETCP SIDEBAND channel channel
 133  */
 134 #define PKTIO_META_SB_RX 0x4
 135
 136 /**
 137  * @def PKTIO_META_SB_TX
 138  * @ingroup pktio_constants
 139  *      This defines the PKTIO NETCP transmit SIDEBAND channel
 140  */
 141 #define PKTIO_META_SB_TX 0x8
 142
 143
 144 /**
 145  * @def PKTIO_META_IFDMA_TX
 146  * @ingroup pktio_constants
 147  *      This defines the PKTIO NETCP infrastructure DMA transfer channel
 148  */
 149 #define PKTIO_META_IFDMA_TX 0x10
 150
 151 /**
 152  * @def PKTIO_META_APP_DEF
 153  * @ingroup pktio_constants
 154  *      This allows user space application to define custom packet types.
 155  */
 156 #define PKTIO_META_APP_DEF 0x80000000
 157
 158 /**
 159  * @brief NWAL Packet meta data information
 160  */
 161     union
 162     {
 163         nwalRxPktInfo_t*        rx_meta;          /**< NWAL Packet meta data information for incoming packet */
 164         nwalTxPktInfo_t*        tx_meta;          /**< NWAL Packet meta data information for outgoing packet */
 165         nwalDmRxPayloadInfo_t*  rx_sb_meta;       /**<NWAL Data mode meta data payload information from NetCP */
 166         nwalDmTxPayloadInfo_t*  tx_sb_meta;       /**< NWAL Data Mode Payload information for packet to SA */
 167         unsigned int            tx_ifdma_dest;    /**< infrastructure dma destination flow */
 168     } u;                                          /**< union NWAL Packet meta data information  */
 169
 170     void * sa_handle;                       /**< This contains the appplication id associated with created SA.
 171                                             details This is used when crypto is to be performed on the
 172                                             egress packet */
 173 } PKTIO_METADATA_T;
 174
 175 /**
 176  *  @ingroup pktio_structures
 177  *  @brief PKTIO fast path configuration structure.
 178  *
 179  *  @details This strucuture allows user space applications to specify the PKTIO packet send function.
 180  *
 181  *  @note This configuration is not expected at time of @ref netapi_pktioOpen but can be updated via
 182  *        @ref netapi_pktioControl API.
 183  */
 184 typedef struct PKTIO_FAST_PATH_CONFIG_Tag
 185 {
 186     int               fp_send_option;  /**< PKTIO_FP_NONE, @ref PKTIO_FP_NO_CRYPTO_NO_CKSUM_PORT,
 187                                         PKTIO_FP_L4CKSUM_PORT, @ref PKTIO_FP_ESP_L4CKSUM_PORT,
 188                                         @ref PKTIO_FP_AH_L4CKSUM_PORT, @ref PKTIO_FP_ESP_PORT,
 189                                         @ref PKTIO_FP_AH_PORT */
 190
 191 /**
 192  * @def PKTIO_FP_NONE
 193  * @ingroup pktio_constants
 194  *      Use this define to reconfigure the PKTIO channel send function to not use any PKTIO fast path
 195         send functions.
 196  */
 197 #define  PKTIO_FP_NONE 0
 198
 199 /**
 200  * @def PKTIO_FP_NO_CRYPTO_NO_CKSUM_PORT
 201  * @ingroup pktio_constants
 202  *      Use this define to send packet with updates to ENET port, no crypto operation,
 203  *      no L4 checksum to be performed.
 204  */
 205 #define  PKTIO_FP_NO_CRYPTO_NO_CKSUM_PORT 1
 206
 207 /**
 208  * @def PKTIO_FP_L4CKSUM_PORT
 209  * @ingroup pktio_constants
 210  *      Use this define to send packet with updates to L4 checksum, ENET port, no crypto operation
 211  *      to be performed.
 212  */
 213 #define  PKTIO_FP_L4CKSUM_PORT 2
 214
 215 /**
 216  * @def PKTIO_FP_ESP_L4CKSUM_PORT
 217  * @ingroup pktio_constants
 218  *      Use this define to send packet with Crypto ESP, UDP checksum, updates to ENET port
 219  */
 220 #define  PKTIO_FP_ESP_L4CKSUM_PORT 3
 221
 222 /**
 223  * @def PKTIO_FP_AH_L4CKSUM_PORT
 224   * @ingroup pktio_constants
 225  *      Use this define to send packet with Cypto AH, UDP checksum, updates to ENET port
 226  */
 227 #define  PKTIO_FP_AH_L4CKSUM_PORT 4
 228
 229 /**
 230  * @def PKTIO_FP_ESP_PORT
 231  * @ingroup pktio_constants
 232  *      Use this define to send packet with Crypto ESP packet, updates to ENET port
 233  */
 234 #define  PKTIO_FP_ESP_PORT 5
 235
 236 /**
 237  * @def PKTIO_FP_AH_PORT
 238  * @ingroup pktio_constants
 239  *      Use this define to send packet with AH packet
 240  */
 241 #define  PKTIO_FP_AH_PORT 6
 242
 243 /**
 244  * @def PKTIO_FP_AH_PORT
 245  * @ingroup pktio_constants
 246  *      Use this define to send packet with Crypto ESP, IP checksum, updates to ENET port
 247  */
 248 #define  PKTIO_FP_ESP_L3CKSUM_PORT 7
 249
 250     nwalTxPktInfo_t   *txPktInfo;  /** <The parameters in this structure are used to
 251                                          provide additional details for the outgoing packet*/
 252 } PKTIO_FAST_PATH_CONFIG_T;
 253
 254
 255
 256 struct PKTIO_HANDLE_tag;
 257 /**
 258  *  @ingroup pktio_structures
 259  *  @brief PKTIO configuration information
 260  *
 261  *  @details PKTIO :q information
 262  */
 263 typedef struct PKTIO_CFG_Tag
 264 {
 265 /**
 266  * @def PKTIO_RX
 267  * @ingroup pktio_constants
 268  *      This defines the pktio channel as type read, i.e., for ingress
 269  */
 270 #define PKTIO_RX 0x1
 271
 272 /**
 273  * @def PKTIO_TX
 274  * @ingroup pktio_constants
 275  *      This defines the pktio channel as type write, i.e. for egress
 276  */
 277 #define PKTIO_TX 0x2
 278
 279 /**
 280  * @def PKTIO_RX_TX
 281  * @ingroup pktio_constants
 282  *      This defines the pktio channel as type read/write
 283  */
 284 #define PKTIO_RX_TX (PKTIO_RX | PKTIO_TX)
 285
 286 /**
 287  * Flags for PKTIO channel configuration
 288  * <br>
 289  * The following are flags used to configure the pktio channel:
 290  *      @ref PKTIO_RX , @ref PKTIO_TX, @ref PKTIO_RX_TX
 291  */
 292     int flags1;
 293
 294 /**
 295  * @def PKTIO_GLOBAL
 296  * @ingroup pktio_constants
 297  *      This defines the pktio channel as type global.
 298         Type global means that this channel can be used by all worker threads/cores
 299  */
 300 #define PKTIO_GLOBAL 0x1
 301
 302 /**
 303  * @def PKTIO_LOCAL
 304  * @ingroup pktio_constants
 305  *      This defines the pktio channel as type local.
 306         Type local means that thi s channel can only be used by the the thread/core that created it;
 307         its name will not be visible to other threads/cores
 308  */
 309 #define PKTIO_LOCAL  0x2
 310
 311 /**
 312  * @def PKTIO_PKT
 313  * @ingroup pktio_constants
 314  *      This defines the pktio channel is for NETCP
 315  */
 316 #define PKTIO_PKT    0x4
 317
 318 /**
 319  * @def PKTIO_SB
 320  * @ingroup pktio_constants
 321  *      This defines the pktio channel is for sideband crypto
 322  */
 323 #define PKTIO_SB     0x8
 324 #define PKTIO_IFDMA  0x10  //define this if this channel is for ifrastructure dma
 325     int flags2; /**< Flags for PKTIO channel configuration, @ref PKTIO_LOCAL , @ref PKTIO_GLOBAL,
 326                     @ref PKTIO_PKT, @ref PKTIO_SB*/
 327
 328 /**
 329  * @def PKTIO_Q_ANY
 330  * @ingroup pktio_constants
 331  *      This defines the pktio IO queue number to be specified by the transport library.
 332  */
 333 #define PKTIO_Q_ANY QMSS_PARAM_NOT_SPECIFIED
 334
 335     int qnum;       /**< PKTIO channel queue number */
 336     int max_n;      /**< Maximum number of packets read in 1 poll */
 337     PKTIO_FAST_PATH_CONFIG_T fast_path_cfg;  /** < @ref PKTIO_FAST_PATH_CONFIG_T */
 338 } PKTIO_CFG_T;
 339
 340
 341 /**
 342  *  @ingroup pktio_structures
 343  *  @brief PKTIO polling control struct, currently NOT_IMPLEMENTED
 344  *
 345  *  @details PKTIO polling control struct, currently NOT_IMPLEMENTED
 346  */
 347 typedef struct PKTIO_POLL_Tag
 348 {
 349 } PKTIO_POLL_T;
 350
 351 /**
 352  *  @ingroup netapi_cb_functions
 353  *  @brief PKTIO_CB   Callback function to be issued on packet receive
 354  *
 355  *  @details The application provides a callback function that gets invoked on packet receive
 356  *  @param[in]  channel     The PKTIO channel handle, @ref PKTIO_HANDLE_T
 357  *  @param[in]  p_recv      Pointer to the packets received.
 358  *  @param[in]  p_meta      Pointer to meta data associated with packet, @ref PKTIO_METADATA_T
 359  *  @param[in]  n_pkts      Number of packets received.
 360   * @param[in]  ts          Timestamp associted with received packets.
 361  *  @retval     none
 362  *  @pre       @ref netapi_pktioOpen
 363  */
 364 typedef void (*PKTIO_CB)(struct PKTIO_HANDLE_tag* channel,
 365                          Ti_Pkt*                  p_recv[],
 366                          PKTIO_METADATA_T         p_meta[],
 367                          int                      n_pkts,
 368                          uint64_t                 ts);
 369
 370 /**
 371  *  @ingroup pktio_functions
 372  *  @brief PKTIO_SEND   PKTIO specific send function
 373  *
 374  *  @details The application calls this PKTIO specific send function to transmit packet
 375  *  @param[in]  channel         The PKTIO channel handle, @ref PKTIO_HANDLE_T
 376  *  @param[in]  p_send          Pointer to the packet to send
 377  *  @param[in]  p_meta          Pointer to meta data associated with packet, @ref PKTIO_METADATA_T
 378  *  @param[out] p_err             Pointer to error code.
 379  *  @retval     none
 380  *  @pre       @ref netapi_pktioOpen
 381  */
 382 typedef int (*PKTIO_SEND)(struct PKTIO_HANDLE_tag * channel,
 383                           Ti_Pkt*                   p_send,
 384                           PKTIO_METADATA_T*         p_meta,
 385                           int*                      p_err);
 386
 387
 388 /**
 389  *  @ingroup pktio_functions
 390  *  @brief PKTIO_POLL   PKTIO specific poll function
 391  *
 392  *  @details The application calls this PKTIO specific POLL function
 393  *  @param[in]  channel     The PKTIO channel handle, @ref PKTIO_HANDLE_T
 394  *  @param[in]  p_poll_cfg  @ref PKTIO_POLL_T, currently NOT_IMPLEMENTED
 395  *  @param[out] p_err       Pointer to error code.
 396  *  @retval     none
 397  *  @pre       @ref netapi_pktioOpen
 398  */
 399 typedef int (*PKTIO_POLL)(struct PKTIO_HANDLE_tag * channel,
 400                           PKTIO_POLL_T*             p_poll_cfg,
 401                           int*                      p_err);
 402
 403
 404 /**
 405  * @brief This defines an unused packet io channel slot
 406  */
 407 #define PKTIO_NA 0
 408
 409
 410 struct NETAPI_tag;
 411
 412 /**
 413  *  @ingroup pktio_structures
 414  *  @brief PKTIO handle structure definition.
 415  *
 416  *  @details PKTIO handle strucutre which is returned from call to @ref netapi_pktioCreate
 417  */
 418 typedef struct PKTIO_HANDLE_Tag
 419 {
 420 /**
 421  * @def PKTIO_INUSE
 422  * @ingroup pktio_constants
 423  *      This defines whether the pktio channel entry is valid.
 424  */
 425 #define PKTIO_INUSE 0xfeedfeed
 426
 427     int inuse;                      /**<true is pktio channel is in use  */
 428
 429 /**
 430  * Set the "use_nwal" field to one of the defines listed below.
 431  * <br>
 432  * The following defines are used to populate the use_nwal field:
 433  *      @ref PKTIO_4_IPC , @ref PKTIO_4_ADJ_NWAL, @ref PKTIO_DEF_NWAL. @ref PKTIO_4_ADJ_SB., @ref PKTIO_DEF_SB
 434  */
 435     int use_nwal;
 436
 437 /**
 438  * @def PKTIO_4_IPC
 439  * @ingroup pktio_constants
 440  *      This define is for channels used for IPC between cores
 441  */
 442 #define  PKTIO_4_IPC 0
 443
 444 /**
 445  * @def PKTIO_4_ADJ_NWAL
 446  * @ingroup pktio_constants
 447  *      This define is for NETCP (RX) channels whose associated queues are managed by NWAL
 448  */
 449 #define  PKTIO_4_ADJ_NWAL 1
 450
 451 /**
 452  * @def PKTIO_DEF_NWAL
 453  * @ingroup pktio_constants
 454  *      This define is for NETCP channels that are tied to the default NWAL RX/TX queues
 455  */
 456 #define  PKTIO_DEF_NWAL 2
 457
 458 /**
 459  * @def PKTIO_4_ADJ_SB
 460  *      This define is for (RX) channels used to get crypto side band results via application managed queues
 461  * @ingroup pktio_constants
 462  */
 463 #define  PKTIO_4_ADJ_SB 3
 464
 465 /**
 466  * @def PKTIO_DEF_SB
 467  * @ingroup pktio_constants
 468  *      This define is for channels tied to the default crypto side band  queues
 469  */
 470 #define  PKTIO_DEF_SB 4
 471
 472     struct NETAPI_tag * back;           /**< back handle  to NETPAI instance */
 473     void * nwalInstanceHandle;          /**<save here for conveninece  this is the nwal handle set at init time*/
 474     PKTIO_CB cb;                        /**< callback for channel (for Rx) */
 475     PKTIO_CFG_T cfg;                    /**<configuration  of channel */
 476     Qmss_QueueHnd q;                    /**<the associated queue handle for channel */
 477     Qmss_Queue qInfo;                   /**<and its qm#/q# */
 478     int max_n;                          /**<max # of pkts to read in one poll */
 479     void * cookie;                      /**<app specific */
 480     PKTIO_SEND _send;                   /**<pktio type specific send function */
 481     PKTIO_POLL _poll;                   /**<pktio type specific POLL function */
 482     int poll_flags;                     /**< pktio flags to control polling options */
 483     char name[PKTIO_MAX_NAME+1];        /**< Name of pktio channel */
 484     Cppi_Handle             cppiHnd;    /* < cppi handle */
 485     Cppi_ChHnd              rxChHnd;    /* < cppi receive channel handle */
 486     Cppi_ChHnd              txChHnd;    /* < cppi transmit channe handle */
 487     nwalTxPSCmdInfo_t tx_psCmdInfo; /**<Command Label to be sent to NetCP for the packet flow */
 488 }  PKTIO_HANDLE_T;
 489
 490
 491 /**
 492  *  @ingroup pktio_structures
 493  *  @brief PKTIO control structure
 494  *
 495  *  @details PKTIO control stucture for the control API. Allows operations on pktio channel such as CLEAR ,  DIVERT, etc
 496  */
 497 typedef struct PKTIO_CONTROL_Tag
 498 {
 499 /**
 500  * @def PKTIO_CLEAR
 501  *      This defines is used to clear out the pktio channel
 502  */
 503 #define PKTIO_CLEAR 0x1
 504
 505 // @cond NOT_IMPLEMENTED
 506 /**
 507  * @def PKTIO_DIVERT
 508  *      This define is used to divert to a dest pktio channel
 509  */
 510 #define PKTIO_DIVERT 0x2
 511 /// @endcond
 512
 513 /**
 514  * @def PKTIO_SET_POLL_FLAGS
 515  *      This define is used to set poll flags for a pktio channel
 516  */
 517 #define PKTIO_SET_POLL_FLAGS 0x4 //control poll flags (netcp_rx only)
 518 /**
 519  * @def PKTIO_UPDATE_FAST_PATH
 520  *      This define is used to update the command information template for
 521  *      INFLOW mode of operation of a ptktio channel (netcp_tx only)
 522  */
 523 #define PKTIO_UPDATE_FAST_PATH 0x8
 524
 525 /**<max # of pkts to read in one poll */
 526 /**
 527  * @def PKTIO_UPDATE_MAX_PKTS_PER_POLL
 528  *      This define is used to update the maximum number of packets to read in 1 poll
 529  *      period for the pktio channel.
 530  */
 531 #define PKTIO_UPDATE_MAX_PKTS_PER_POLL 0x10
 532
 533     int op;                 /**< Control operation (CLEAR, DIVERT, ..) */
 534     PKTIO_HANDLE_T *dest;   /**< Handle to PKTIO channel (for DIVERT) */
 535     int poll_flags;         /**< Flags to indicate polling options */
 536 } PKTIO_CONTROL_T;
 537
 538 /**
 539  *  @ingroup pktio_functions
 540  *  @brief API creates a NETAPI PKTIO channel
 541  *
 542  *  @details This assigns global resources to a NETAPI pktio channel.
 543  *   Once created, the channel can be used to send and/or receive
 544  *   a Ti_Pkt. This can be used for communication with the
 545  *   the Network co-processor (NETCP) or for internal inter-processor
 546  *   communication. The channel is saved under the assigned name
 547  *   and can be opened by other netapi threads instances.
 548  *  @param[in]  netapi_handle   The NETAPI handle, @ref NETAPI_T
 549  *  @param[in]  name            A pointer to the char string name for channel
 550  *  @param[in]  cb              Callback to be issued on packet receive, @ref PKTIO_CB
 551  *  @param[in]  p_cfg           Pointer to channel configuration, @ref PKTIO_CFG_T
 552  *  @param[out] err             Pointer to error code.
 553  *  @retval     Handle to the pktio instance or NULL on error, @ref PKTIO_HANDLE_T
 554  *  @pre       @ref netapi_init
 555  */
 556 PKTIO_HANDLE_T * netapi_pktioCreate(NETAPI_T        netapi_handle,
 557                                     char*           name,
 558                                     PKTIO_CB        cb,
 559                                     PKTIO_CFG_T*    p_cfg,
 560                                     int*            err);
 561
 562 /**
 563  *  @ingroup pktio_functions
 564  *  @brief API opens an existing  NETAPI PKTIO channel
 565  *
 566  *  @details This opens an NETAPI pktio channel for use. The channel
 567  *  must have already been created via @ref netapi_pktioCreate or may have
 568  *  been created internally during the netapi intialization.
 569  *   Once opened, the channel can be used to send and/or receive
 570  *   a Ti_Pkt. This can be used for communication with the
 571  *   the Network co-processor (NETCP) or for internal inter-processor
 572  *   communication.
 573  *
 574  *  @param[in]  netapi_handle   The NETAPI handle, @ref NETAPI_T
 575  *  @param[in]  name            A pointer to the char string name for channel to open
 576  *  @param[in]  cb              Callback to be issued on packet receive, @ref PKTIO_CB
 577  *  @param[in]  p_cfg           Pointer to channel configuration, @ref PKTIO_CFG_T
 578  *  @param[out] err             Pointer to error code.
 579  *  @retval     Handle to the pktio instance or NULL on error, @ref PKTIO_HANDLE_T
 580  *  @pre       @ref netapi_init, @ref netapi_pktioCreate
 581  */
 582 PKTIO_HANDLE_T * netapi_pktioOpen(NETAPI_T      netapi_handle,
 583                                  char*          name,
 584                                  PKTIO_CB       cb,
 585                                  PKTIO_CFG_T*   p_cfg,
 586                                  int*           err);
 587
 588 /**
 589  *  @ingroup pktio_functions
 590  *  @brief API controls an existing NETAPI PKTIO channel
 591  *
 592  *  @details This controls an opened pktio channel
 593  *
 594  *  @param[in]  handle      The PKTIO channel handle, @ref PKTIO_HANDLE_T
 595  *  @param[in]  cb          Callback to be issued on packet receive, @ref PKTIO_CB
 596  *  @param[in]  p_cfg       Pointer to channel configuration which (optional), @ref PKTIO_CFG_T
 597  *  @param[in]  p_control   Pointer to PKTIO control information (optional), @ref PKTIO_CONTROL_T
 598  *  @param[out] err         Pointer to error code.
 599  *  @retval     none
 600  *  @pre       @ref netapi_init, @ref netapi_pktioCreate, @ref netapi_pktioOpen
 601  */
 602 void netapi_pktioControl(PKTIO_HANDLE_T*    handle,
 603                          PKTIO_CB           cb,
 604                          PKTIO_CFG_T*       p_cfg,
 605                          PKTIO_CONTROL_T*   p_control,
 606                          int*               err);
 607
 608 /**
 609  *  @ingroup pktio_functions
 610  *  @brief API closes a NETAPI PKTIO channel
 611  *
 612  *  @details This closes a PKTIO channel
 613  *
 614  *  @param[in]  handle  The PKTIO channel handle, @ref PKTIO_HANDLE_T
 615  *  @param[out] err    Pointer to error code.
 616  *  @retval     none
 617  *  @pre       @ref netapi_init, @ref netapi_pktioCreate, @ref netapi_pktioOpen
 618  */
 619 void netapi_pktioClose(PKTIO_HANDLE_T*  handle,
 620                        int*             err);
 621
 622 /**
 623  *  @ingroup pktio_functions
 624  *  @brief API deletes a NETAPI PKTIO channel
 625  *
 626  *  @details This deletes a PKTIO channel
 627  *
 628  *  @param[in]  handle  The PKTIO  handle, @ref PKTIO_HANDLE_T
 629  *  @param[out] err     Pointer to error code.
 630  *  @retval     none
 631  *  @pre       @ref netapi_init, @ref netapi_pktioCreate, @ref netapi_pktioOpen
 632  */
 633 void netapi_pktioDelete(PKTIO_HANDLE_T* handle,
 634                         int*            err);
 635
 636 /**
 637  *  @ingroup pktio_functions
 638  *  @brief  API sends a packet to a NETAPI PKTIO channel
 639  *
 640  *  @details This sends a Ti_Pkt and associated meta data,
 641  *  @ref PKTIO_METADATA_T to a channel. The channel
 642  *  must have already been created via @ref netapi_pktioCreate or opened
 643  *  via @ref netapi_pktioOpen.  It  may have
 644  *  been created internally during the netapi intialization.
 645  *  @param[in]  handle  The PKTIO channel handle, @ref PKTIO_HANDLE_T
 646  *  @param[in]  pkt     Pointer to the packet to send
 647  *  @param[in]  m       Pointer to meta data associated with packet, @ref PKTIO_METADATA_T
 648  *  @param[out] err     Pointer to error code.
 649  *  @retval     1 if packet sent, 0 if error
 650  *  @pre       @ref netapi_init, @ref netapi_pktioCreate, @ref netapi_pktioOpen
 651  */
 652 static inline int  netapi_pktioSend(PKTIO_HANDLE_T*   handle,
 653                                     Ti_Pkt*           pkt,
 654                                     PKTIO_METADATA_T* m,
 655                                     int*              err)
 656 {
 657    return handle->_send((struct PKTIO_HANDLE_tag *)handle, pkt, m, err);
 658 }
 659
 660 /**
 661  *  @ingroup pktio_functions
 662  *  @brief API sends multiple packets to a NETAPI PKTIO channel
 663  *
 664  *  @details This sends an array of Ti_Pkt and associated meta data,
 665  *  @ref PKTIO_METADATA_T to a channel. The channel
 666  *  must have already been created via @ref netapi_pktioCreate or opened
 667  *  via @ref netapi_pktioOpen.  It  may have
 668  *  been created internally during the netapi intialization.
 669  *  @param[in]  handle  The PKTIO channel handle, @ref PKTIO_HANDLE_T
 670  *  @param[in]  pkt     Pointer to the packet to send
 671  *  @param[in]  m       Pointer to meta data associated with packet, @ref PKTIO_METADATA_T
 672  *  @param[in]  np      The number of packets in list to send
 673  *  @param[out] err     Pointer to error code.
 674  *  @retval             Number of packets sent, 0 if error
 675  *  @pre       @ref netapi_init, @ref netapi_pktioCreate, @ref netapi_pktioOpen
 676  */
 677 int netapi_pktioSendMulti(PKTIO_HANDLE_T*   handle,
 678                           Ti_Pkt*           pkt[],
 679                           PKTIO_METADATA_T* m[],
 680                           int               np,
 681                           int*              err);
 682
 683 /**
 684  *  @ingroup pktio_functions
 685  *  @brief  API polls a NETAPI PKTIO channel for received packets
 686  *
 687  *  @details This api polls a pktio channel. Any pending data in the channel is
 688  *  passed to the @ref  PKTIO_CB registered when the channel was
 689  *  created or opened. The channel must
 690  *  have already been created via @ref netapi_pktioCreate or opened
 691  *  via @ref netapi_pktioOpen.  It  may have
 692  *  been created internally during the netapi intialization.
 693  *  @param[in]  handle      The PKTIO channel handle, @ref PKTIO_HANDLE_T
 694  *  @param[in]  p_poll_cfg  Pointer to pktio poll configuration. @ref PKTIO_POLL_T
 695  *  @param[out] err         Pointer to error code.
 696  *  @retval                 Number of packets received by poll
 697  *  @pre       @ref netapi_init, @ref netapi_pktioCreate, @ref netapi_pktioOpen
 698  */
 699 static inline int netapi_pktioPoll(PKTIO_HANDLE_T* handle,
 700                                    PKTIO_POLL_T*   p_poll_cfg,
 701                                    int*            err)
 702 {
 703     return handle->_poll((struct PKTIO_HANDLE_tag *) handle, p_poll_cfg, err);
 704 }
 705
 706 /**
 707  *  @ingroup pktio_functions
 708  *  @brief API polls all NETAPI PKTIO channels associated with @ref NETAPI_T instance
 709  *         for received packets
 710  *
 711  *  @details This api polls all pktio channels attached to an instance.
 712  *  Any pending data in these channels are
 713  *  passed to the @ref  PKTIO_CB registered when the channel was
 714  *  created or opened. The channels  must
 715  *  have already been created via @ref netapi_pktioCreate or opened
 716  *  via @ref netapi_pktioOpen.  They may have
 717  *  been created internally during the netapi intialization.
 718  *  @param[in]  handle      The PKTIO channel handle, @ref PKTIO_HANDLE_T
 719  *  @param[in]  p_poll_cfg  Pointer to pktio poll configuration. @ref PKTIO_POLL_T
 720  *  @param[out] err         Pointer to error code.
 721  *  @retval                 Number of packets received by poll
 722  *  @pre       @ref netapi_init, @ref netapi_pktioCreate, @ref netapi_pktioOpen
 723  */
 724 int netapi_pktioPollAll(NETAPI_T        handle,
 725                         PKTIO_POLL_T*   p_poll_cfg,
 726                         int*            err);
 727
 728
 729 /**
 730  * @brief This define sets the max number of pkts to read in one poll in the @ref PKTIO_HANDLE_T
 731  */
 732 #define netapi_pktioSetMaxN(handle,max_n) (handle)->max_n=max_n;
 733
 734 /**
 735  * @brief This define returns NETAPI handle stored in the @ref PKTIO_HANDLE_T
 736  */
 737 #define netapi_pktioGetNetapiHandle(handle) (handle)->back
 738
 739
 740 /**
 741  * @brief This define sets a user space application cookie in the @ref PKTIO_HANDLE_T
 742  */
 743 #define netapi_pktioSetCookie(handle, cookie) (handle)->cookie = cookie
 744
 745 /**
 746  * @brief This define returns a previously set user space application cookie stored in the @ref PKTIO_HANDLE_T
 747  */
 748 #define netapi_pktioGetCookie(handle) (handle)->cookie
 749
 750 /**
 751  * @brief This define returns a associate queue handle stored in the @ref PKTIO_HANDLE_T
 752  */
 753 #define netapi_pktioGetQ(handle) (handle)->q
 754
 755 /*-----------------Extra Fast Path pkt meta data macros--------------------*/
 756 #include "cppi_desc.h"
 757 #include "ti/drv/pa/pa.h"
 758 #include "ti/drv/pa/pasahost.h"
 759
 760
 761 /**
 762  *  @ingroup pktio_functions
 763  *  @brief  API returns default packet queue to poll for netcp RX
 764  *  @note: these are expensive calls, so call once and save
 765  */
 766 static inline Qmss_QueueHnd pktio_mGetDefaultNetCpQ(PKTIO_HANDLE_T *h)
 767 {
 768     nwalGlobCxtInfo_t Info;
 769     nwal_getGlobCxtInfo(h->nwalInstanceHandle,&Info);
 770     return Info.rxDefPktQ;
 771 }
 772
 773
 774 /**
 775  *  @ingroup pktio_functions
 776  *  @brief  API returns L4Queue to poll for netcp RX (L4 classifier queue).
 777  *  @note: these are expensive calls, so call once and save
 778  */
 779 static inline Qmss_QueueHnd pktio_mGetDefaultNetCPL4Q(PKTIO_HANDLE_T *h)
 780 {
 781     nwalLocCxtInfo_t Info;
 782     nwal_getLocCxtInfo(h->nwalInstanceHandle,&Info);
 783     return Info.rxL4PktQ;
 784 }
 785
 786
 787 /**
 788  *  @ingroup pktio_functions
 789  *  @brief  API to perform descriptor push to QMSS Queue
 790  */
 791 static inline void pktio_mQmssQueuePushDescSizeRaw(Qmss_QueueHnd    hnd,
 792                                                    void*            descAddr,
 793                                                    uint32_t         descSize)
 794 {
 795     return(Qmss_queuePushDescSizeRaw(hnd,descAddr,descSize));
 796 }
 797
 798 /**
 799  *  @ingroup pktio_functions
 800  *  @brief  API to perform descriptor pop from QMSS Queue
 801  */
 802 static inline void* pktio_mQmssQueuePopRaw(Qmss_QueueHnd hnd)
 803 {
 804     return(Qmss_queuePopRaw(hnd));
 805 }
 806
 807 /**
 808  *  @ingroup pktio_functions
 809  *  @brief  API to retrieve NWAL global instance handle.
 810  */
 811 static inline nwal_Inst pktio_mGetNwalInstance(PKTIO_HANDLE_T *h)
 812 {
 813     return h->nwalInstanceHandle;
 814 }
 815
 816 #ifdef __cplusplus
 817 }
 818 #endif
 819
 820 #endif