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