bc1d87472cb46fb98f6caeb1767cfb7957630ce0
[keystone-rtos/netapi.git] / ti / runtime / netapi / pktio.h
1 /*********************************
2  *FILE:  pktio.h
3  *PURPOSE:  pktio library header
4  **************************************************************
5  * @file  pktio.h
6  * 
7  * @bried DESCRIPTION:  pktio module  main header file for user space transport
8  *               library
9  * 
10  * REVISION HISTORY:  rev 0.0.1 
11  *
12  *  Copyright (c) Texas Instruments Incorporated 2010-2011
13  * 
14  *  Redistribution and use in source and binary forms, with or without 
15  *  modification, are permitted provided that the following conditions 
16  *  are met:
17  *
18  *    Redistributions of source code must retain the above copyright 
19  *    notice, this list of conditions and the following disclaimer.
20  *
21  *    Redistributions in binary form must reproduce the above copyright
22  *    notice, this list of conditions and the following disclaimer in the 
23  *    documentation and/or other materials provided with the   
24  *    distribution.
25  *
26  *    Neither the name of Texas Instruments Incorporated nor the names of
27  *    its contributors may be used to endorse or promote products derived
28  *    from this software without specific prior written permission.
29  *
30  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
31  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
32  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
33  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
34  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
35  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
36  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
37  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
38  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
39  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
40  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42  ********************************/
43 #ifndef __PKTIO__H
44 #define __PKTIO__H
45 #include "netapi.h"
46 #include "ti/runtime/pktlib/pktlib.h"
47 #include "ti/drv/nwal/nwal.h"
48 #include "ti/drv/nwal/nwal_util.h"
49 #include "netapi_err.h"
51 /*--------------------defines-----------------------*/
52 #define PKTIO_NOMEM  NETAPI_ERR_NOMEM
53 //default pktio channels 
54 #define NETCP_TX "NETCP_TX"
55 #define NETCP_RX "NETCP_RX"
56 #define NETCP_SB_RX "NETCP_SB_RX"
57 #define NETCP_SB_TX "NETCP_SB_TX"
58 #define PKTIO_MAX_NAME 19  
60 /*--------------------data structures----------------*/
61 typedef struct PKTIO_METADATA_Tag
62 {
63   int flags1;
64 #define PKTIO_META_RX 0x01
65 #define PKTIO_META_TX 0x02
66 #define PKTIO_META_SB_RX 0x4  //SB crypto rx 
67 #define PKTIO_META_SB_TX 0x8  //SB crypto tx
68 #define PKTIO_META_APP_DEF 0x80000000
69   union
70   {
71         nwalRxPktInfo_t * rx_meta;
72         nwalTxPktInfo_t * tx_meta;
73         nwalDmRxPayloadInfo_t * rx_sb_meta;
74         nwalDmTxPayloadInfo_t * tx_sb_meta;
75   } u;
76   void * sa_handle; //valid for PKTIO_META_TX with IPSEC inflow  or PKTIO_PKTIO_META_SB_TX . 
77                     // MUST BE nwal_HANDLE_INVALID otherwise
78 } PKTIO_METADATA_T;
80 /* the callback function */
81 struct PKTIO_HANDLE_tag;
83 //polling control
84 typedef struct PKTIO_POLL_Tag
85 {
86 /* future */
87 } PKTIO_POLL_T;
89 #define PKTIO_MAX_RECV  (TUNE_NETAPI_MAX_BURST_RCV)
90 typedef void (*PKTIO_CB)(struct PKTIO_HANDLE_tag * channel, Ti_Pkt* p_recv[],
91                          PKTIO_METADATA_T p_meta[], int n_pkts,
92                          uint64_t ts );
94 typedef int (*PKTIO_SEND)(struct PKTIO_HANDLE_tag * channel, Ti_Pkt* p_send,
95                          PKTIO_METADATA_T *p_meta, int * p_err);
97 typedef int (*PKTIO_POLL)(struct PKTIO_HANDLE_tag * channel,PKTIO_POLL_T * p_poll_cfg ,
98                           int * p_err);
100 /** channel configuration */
101 #define PKTIO_NA 0
102 typedef struct PKTIO_CFG_Tag
104 #define PKTIO_R 0x1
105 #define PKTIO_W 0x2
106 #define PKTIO_RW (PKTIO_R | PKTIO_W)
107 int flags1;
109 #define PKTIO_LOCAL  0x2 
110 #define PKTIO_GLOBAL 0x1
111 #define PKTIO_PKT    0x4  //define this if this channel is for NETCP 
112 #define PKTIO_SB     0x8  //define this if this channel is for sideband crypto  
113 int flags2;
115 //for create
116 #define PKTIO_Q_ANY -1
117 int qnum;
119 //for poll
120 int max_n;
121 }PKTIO_CFG_T;
123 struct NETAPI_tag;
125 /* a pktio channel .. */
127 typedef struct PKTIO_HANDLE_Tag
129 #define PKTIO_INUSE 0xfeedfeed
130         int inuse;
131         int use_nwal;  /* true if this is managed by nwal */
132 #define  PKTIO_4_IPC 0   //For IPC
133 #define  PKTIO_4_ADJ_NWAL 1 //(RX)app queues managed by NWAL
134 #define  PKTIO_DEF_NWAL 2  // default NWAL RX/TX queues
135 #define  PKTIO_4_ADJ_SB 3  //(RX) crypto side band app defined
136 #define  PKTIO_DEF_SB 4  //crypto side band default
137         struct NETAPI_tag * back;  /* back handle */
138         void * nwalInstanceHandle;      /* save here for conveninece */
139         PKTIO_CB cb;      /* callback for channel */
140         PKTIO_CFG_T cfg; /* configuration */
141         Qmss_QueueHnd q;  /* the associated queue handle */
142         Qmss_Queue qInfo;        /*   and its qm#/q# */
143         int max_n;        /* max # of pkts to read in one poll */
144         void * cookie;    /* app specific */
145         PKTIO_SEND _send;  /* pktio type specific send function */
146         PKTIO_POLL _poll;  /* pktio type specific POLL function */
147         char name[PKTIO_MAX_NAME+1];
148 }  PKTIO_HANDLE_T;
152 typedef struct PKTIO_CONTROL_Tag
154 #define PKTIO_CLEAR 0x1   //clear out the channel
155 #define PKTIO_DIVERT 0x2  //divert, (to dest channel)
156   int op;
157   PKTIO_HANDLE_T *dest;
158 } PKTIO_CONTROL_T;
162 /*---------------------------------------------------*/
163 /*-------------------------API-----------------------*/
164 /*---------------------------------------------------*/
166 /*
167 *  @brief  API creates a NETAPI channel 
168  *
169  *  @details This assigns global resources to a NETAPI pktio channel.
170  *   Once created, the channel can be used to send and/or receive
171  *   a TI @ref Ti_Pkt. This can be used for communication with the 
172  *   the Network co-processor (NETCP) or for internal inter-processor
173  *   communication. The channel is saved under the assigned name 
174  *   and can be opened by other netapi threads instances.
175  *  @param[in]  @ref NETAPI_T: handle to the instance 
176  *  @param[in]  char * name: a pointer to the char string name for channel
177  *  @param[in]  @ref PKTIO_CB : callback to be issued on packet receive
178  *  @param[in]  @ref PKTIO_CFG_T: pointer to channel configuration
179  *  @param[out] int * err:  pointer to error return 
180  *  @retval     @ref PKTIO_HANDLE_T: handle to the pktio instance or NULL on error
181  *  @pre       @ref netapi_init 
182  */
183 PKTIO_HANDLE_T * pktio_create(NETAPI_T netapi_handle, /* netapi instance */
184                                char * name,  /* name of the channel */
185                                PKTIO_CB cb,  /* receive callback */
186                                PKTIO_CFG_T * p_cfg,  /* ptr to config*/
187                                int * err);
189 /*
190 *  @brief  API opens an existing  NETAPI channel
191  *
192  *  @details This opens an NETAPI pktio channel for use. The channel
193  *  must have already been created via @ref pktio_create or may have
194  *  been created internally during the netapi intialization.
195  *   Once opened, the channel can be used to send and/or receive
196  *   a TI @ref Ti_Pkt. This can be used for communication with the 
197  *   the Network co-processor (NETCP) or for internal inter-processor
198  *   communication. 
199  *
200  *  @param[in]  @ref NETAPI_T: handle to the instance 
201  *  @param[in]  char * name: a pointer to the char string name for channel
202  *  @param[in]  @ref PKTIO_CB : callback to be issued on packet receive
203  *  @param[in]  @ref PKTIO_CFG_T: pointer to channel configuration
204  *  @param[out] int * err:  pointer to error return
205  *  @retval     @ref PKTIO_HANDLE_T: handle to the pktio instance or NULL on error
206  *  @pre       @ref netapi_init , @ref pktio_create
207  */
208 PKTIO_HANDLE_T * pktio_open(NETAPI_T netapi_handle, /* netapi instance */
209                             char *name,  /* name of channel to open */
210                             PKTIO_CB cb, /* receive callback */
211                             PKTIO_CFG_T *p_cfg, /* channel configuration */
212                             int * err);
214 /* future: control the channel */
215 void pktio_control(PKTIO_HANDLE_T * channel, //handle from open or create
216                                PKTIO_CB cb,  //change the callback
217                                PKTIO_CFG_T * p_cfg,//optional 
218                                PKTIO_CONTROL_T *p_control,//optional
219                                int *err);
220                              
221 /* future: close or delete a pktio channel */
222 void pktio_close(PKTIO_HANDLE_T * channel, int * err);
223 void pktio_delete(PKTIO_HANDLE_T * channel, int * err);
225 /*
226 *  @brief  API sends data to a pktio channel 
227  *
228  *  @details This sends a @ref Ti_Pkt and associated meta data, 
229  *  @ref PKTIO_METADATA_T to a channel. The channel
230  *  must have already been created via @ref pktio_create or opened
231  *  via @ref pktio_open.  It  may have
232  *  been created internally during the netapi intialization.
233  *  @param[in]  @ref PKTIO_HANDLE_T: handle to the channel
234  *  @param[in]  @ref Ti_Pkt*: pointer to the packet to send
235  *  @param[in]  @ref PKTIO_METADATA_T: pointer to meta data associated with packet 
236  *  @param[out] int * err:  pointer to error return
237  *  @retval      int npkts: 1 if packet sent, 0 if error 
238  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
239  */
240 static inline int  pktio_send(PKTIO_HANDLE_T * channel, /* the channel */
241                 Ti_Pkt *pkt,              /* pointer to packet */
242                 PKTIO_METADATA_T *m,      /* pointer to meta data */
243                 int * err)
245    return channel->_send((struct PKTIO_HANDLE_tag *)channel, pkt, m, err);
248 /*
249 *  @brief  API sends data to a pktio channel
250  *
251  *  @details This sends an array of @ref Ti_Pkt and associated meta data,
252  *  @ref PKTIO_METADATA_T to a channel. The channel
253  *  must have already been created via @ref pktio_create or opened
254  *  via @ref pktio_open.  It  may have
255  *  been created internally during the netapi intialization.
256  *  @param[in]  @ref PKTIO_HANDLE_T: handle to the channel
257  *  @param[in]  @ref Ti_Pkt*: pointer to the packet to send
258  *  @param[in]  @ref PKTIO_METADATA_T: pointer to meta data associated with packet
259  *  @oaran[in[  int np:  the number of packets in list to send
260  *  @param[out] int * err:  pointer to error return
261  *  @retval      int npkts: number of packets sent, 0 if error
262  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
263  */
264 int pktio_sendMulti(PKTIO_HANDLE_T *channel, /* the channel handle */
265                     Ti_Pkt * pkt[], /* array of packets to send */
266                     PKTIO_METADATA_T * m[], /* meta data array */
267                     int np,      /* number of packets to send */
268                     int * err);
270 /***********************************/
271 /************* polling **************/
272 /***********************************/
274 /*
275 *  @brief  API polls a pkto channel for received packets 
276  *
277  *  @details This api polls a pktio channel. Any pending data in the channel is
278  *  passed to the @ref  PKTIO_CB registered when the channel was
279  *  created or opened. The channel must
280  *  have already been created via @ref pktio_create or opened
281  *  via @ref pktio_open.  It  may have
282  *  been created internally during the netapi intialization.
283  *  @param[in]  @ref PKTIO_HANDLE_T: handle to the channel
284  *  @param[in]  @ref PKTIO_POLL_T *: pointer to pktio poll configuration
285  *  @param[out] int * err:  pointer to error return
286  *  @retval      int npkts: number of packets received by poll 
287  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
288  */
289 static inline int pktio_poll(PKTIO_HANDLE_T * handle,   //handle to pktio
290                PKTIO_POLL_T * p_poll_cfg,  //polling configuration
291                int * err)
293         return handle->_poll((struct PKTIO_HANDLE_tag *) handle, p_poll_cfg, err);
296 /*
297 *  @brief  API polls all pkto channels associarted with @ref NETAPI_T instance
298  *         for received packets
299  *
300  *  @details This api polls all pktio channels attached to an instance.
301  *  Any pending data in these channels are 
302  *  passed to the @ref  PKTIO_CB registered when the channel was
303  *  created or opened. The channels  must
304  *  have already been created via @ref pktio_create or opened
305  *  via @ref pktio_open.  They may have
306  *  been created internally during the netapi intialization.
307  *  @param[in]  @ref NETAPI_T: handle of the NETAPI instance 
308  *  @param[in]  @ref PKTIO_POLL_T *: pointer to pktio poll configuration
309  *  @param[out] int * err:  pointer to error return
310  *  @retval      int npkts: number of packets received by poll
311  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
312  */
313 int pktio_pollAll(NETAPI_T handle, PKTIO_POLL_T * p_poll_cfg, int *err);
315 /*----------------- utilities------------------ */
316 /* update max_n for poll */
317 #define pktio_set_max_n(handle,max_n) (handle)->max_n=max_n;
318 #define pktio_get_netapi_handle(handle) (handle)->back
319 #define pktio_set_cookie(handle, cookie) (handle)->cookie = cookie
320 #define pktio_get_cookie(handle) (handle)->cookie
321 #define pktio_get_q(handle) (handle)->q
323 /*-----------------Extra Fast Path pkt meta data macros--------------------*/
324 #include "cppi_desc.h"
325 #include "ti/drv/pa/pa.h"
326 #include "ti/drv/pa/pasahost.h"
329 //return default packet queue to poll for netcp RX
330 //these are expensive calls, so call once and save
331 static inline Qmss_QueueHnd PKTIO_GET_DEFAULT_NETCP_Q(PKTIO_HANDLE_T *h)
333 nwalGlobCxtInfo_t Info;
334 nwal_getGlobCxtInfo(h->nwalInstanceHandle,&Info);
335 return Info.rxDefPktQ;
338 //return L4Queue to poll for netcp RX (L4 classifier queue)
339 //these are expensive calls, so call once and save
340 static inline Qmss_QueueHnd PKTIO_GET_DEFAULT_NETCP_L4Q(PKTIO_HANDLE_T *h)
342 nwalLocCxtInfo_t Info;
343 nwal_getLocCxtInfo(h->nwalInstanceHandle,&Info);
344 return Info.rxL4PktQ;
349 static inline void PKTIO_QMSS_QUEUE_PUSH_DESC_SIZE_RAW(Qmss_QueueHnd hnd, void *descAddr, uint32_t descSize)
351     return(Qmss_queuePushDescSizeRaw(hnd,descAddr,descSize));
354 static inline void* PKTIO_QMSS_QUEUE_POP_RAW(Qmss_QueueHnd hnd)
356     return(Qmss_queuePopRaw(hnd));
359 //Return NWAL Global Instance
360 static inline nwal_Inst PKTIO_GET_NWAL_INSTANCE(PKTIO_HANDLE_T *h)
362 return h->nwalInstanceHandle;
366 #endif