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