7f2e6e19dc89bb553f2753c62197969846ce949d
[keystone-rtos/netapi.git] / 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  */
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  */
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"
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"
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"
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"
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"
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
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
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*/
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
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
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
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
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
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
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  */
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;
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
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 */
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
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
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
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
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
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
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
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
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;
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
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
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
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)
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; 
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
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
305 /**
306  * @def PKTIO_PKT
307  * @ingroup pktio_constants
308  *      This defines the pktio channel is for NETCP
309  */
310 #define PKTIO_PKT    0x4
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*/
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
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;
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
343 } PKTIO_POLL_T;
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);
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);
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);
398 /**
399  * @brief This defines an unused packet io channel slot
400  */
401 #define PKTIO_NA 0
404 struct NETAPI_tag;
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
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
421     int inuse;                      /**<true is pktio channel is in use  */
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;                  
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
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
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
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
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
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;
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
493 /**
494  * @def PKTIO_CLEAR
495  *      This defines is used to clear out the pktio channel
496  */
497 #define PKTIO_CLEAR 0x1
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
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
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
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;
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);
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);
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);
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);
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);
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)
651    return handle->_send((struct PKTIO_HANDLE_tag *)handle, pkt, m, err);
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);
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)
697     return handle->_poll((struct PKTIO_HANDLE_tag *) handle, p_poll_cfg, err);
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);
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;
728 /**
729  * @brief This define returns NETAPI handle stored in the @ref PKTIO_HANDLE_T
730  */
731 #define netapi_pktioGetNetapiHandle(handle) (handle)->back
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
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
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
749 /*-----------------Extra Fast Path pkt meta data macros--------------------*/
750 #include "cppi_desc.h"
751 #include "ti/drv/pa/pa.h"
752 #include "ti/drv/pa/pasahost.h"
755 /**
756  *  @ingroup pktio_functions
757  *  @brief  API returns default packet queue to poll for netcp RX
758  *  @note: these are expensive calls, so call once and save
759  */
760 static inline Qmss_QueueHnd pktio_mGetDefaultNetCpQ(PKTIO_HANDLE_T *h)
762     nwalGlobCxtInfo_t Info;
763     nwal_getGlobCxtInfo(h->nwalInstanceHandle,&Info);
764     return Info.rxDefPktQ;
768 /**
769  *  @ingroup pktio_functions
770  *  @brief  API returns L4Queue to poll for netcp RX (L4 classifier queue).
771  *  @note: these are expensive calls, so call once and save
772  */
773 static inline Qmss_QueueHnd pktio_mGetDefaultNetCPL4Q(PKTIO_HANDLE_T *h)
775     nwalLocCxtInfo_t Info;
776     nwal_getLocCxtInfo(h->nwalInstanceHandle,&Info);
777     return Info.rxL4PktQ;
781 /**
782  *  @ingroup pktio_functions
783  *  @brief  API to perform descriptor push to QMSS Queue
784  */
785 static inline void pktio_mQmssQueuePushDescSizeRaw(Qmss_QueueHnd    hnd,
786                                                    void*            descAddr,
787                                                    uint32_t         descSize)
789     return(Qmss_queuePushDescSizeRaw(hnd,descAddr,descSize));
792 /**
793  *  @ingroup pktio_functions
794  *  @brief  API to perform descriptor pop from QMSS Queue
795  */
796 static inline void* pktio_mQmssQueuePopRaw(Qmss_QueueHnd hnd)
798     return(Qmss_queuePopRaw(hnd));
801 /**
802  *  @ingroup pktio_functions
803  *  @brief  API to retrieve NWAL global instance handle.
804  */
805 static inline nwal_Inst pktio_mGetNwalInstance(PKTIO_HANDLE_T *h)
807     return h->nwalInstanceHandle;
811 #endif