This is the initial commit.
[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  * 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 "netapi_err.h"
50 /*--------------------defines-----------------------*/
51 #define PKTIO_NOMEM  NETAPI_ERR_NOMEM
52 #define NETCP_TX "NETCP_TX"
53 #define NETCP_RX "NETCP_RX"
54 #define PKTIO_MAX_NAME 19  
56 /*--------------------data structures----------------*/
57 typedef struct PKTIO_METADATA_Tag
58 {
59   int flags1;
60 #define PKTIO_META_RX 0x01
61 #define PKTIO_META_TX 0x02
63   union
64   {
65         nwalRxPktInfo_t * rx_meta;
66         nwalTxPktInfo_t * tx_meta;
67   } u;
68 } PKTIO_METADATA_T;
70 /* the callback function */
71 struct PKTIO_HANDLE_tag;
73 #define PKTIO_MAX_RECV  (TUNE_NETAPI_MAX_BURST_RCV)
74 typedef void (*PKTIO_CB)(struct PKTIO_HANDLE_tag * channel, Ti_Pkt* p_recv[],
75                          PKTIO_METADATA_T p_meta[], int n_pkts,
76                          uint64_t ts );
78 /** channel configuration */
79 #define PKTIO_NA 0
80 typedef struct PKTIO_CFG_Tag
81 {
82 #define PKTIO_R 0x1
83 #define PKTIO_W 0x2
84 #define PKTIO_RW (PKTIO_R | PKTIO_W)
85 int flags1;
87 #define PKTIO_LOCAL  0x2 
88 #define PKTIO_GLOBAL 0x1
89 #define PKTIO_PKT    0x4  //define this if this q is for NETCP RX
90 int flags2;
92 //for create
93 #define PKTIO_Q_ANY -1
94 int qnum;
96 //for poll
97 int max_n;
98 }PKTIO_CFG_T;
100 struct NETAPI_tag;
102 /* a pktio channel .. */
104 typedef struct PKTIO_HANDLE_Tag
106 #define PKTIO_INUSE 0xfeedfeed
107         int inuse;
108         int use_nwal;  /* true if this is managed by nwal */
109 #define  PKTIO_4_IPC 0
110 #define  PKTIO_4_ADJ_RX 1
111 #define  PKTIO_DEF_RX 2
112         struct NETAPI_tag * back;  /* back handle */
113         void * nwalInstanceHandle;      /* save here for conveninece */
114         PKTIO_CB cb;      /* callback for channel */
115         PKTIO_CFG_T cfg; /* configuration */
116         Qmss_QueueHnd q;  /* the associated queue handle */
117         Qmss_Queue qInfo;        /*   and its qm#/q# */
118         int max_n;        /* max # of pkts to read in one poll */
119         void * cookie;    /* app specific */
120         char name[PKTIO_MAX_NAME+1];
121 }  PKTIO_HANDLE_T;
125 typedef struct PKTIO_CONTROL_Tag
127 #define CLEAR 0x1   //clear out the channel
128 #define DIVERT 0x2  //divert, (to dest channel)
129   int op;
130   PKTIO_HANDLE_T *dest;
131 } PKTIO_CONTROL_T;
134 //polling control
135 typedef struct PKTIO_POLL_Tag
137 /* future */
138 } PKTIO_POLL_T;
140 /*---------------------------------------------------*/
141 /*-------------------------API-----------------------*/
142 /*---------------------------------------------------*/
144 /*
145 *  @brief  API creates a NETAPI channel 
146  *
147  *  @details This assigns global resources to a NETAPI pktio channel.
148  *   Once created, the channel can be used to send and/or receive
149  *   a TI @ref Ti_Pkt. This can be used for communication with the 
150  *   the Network co-processor (NETCP) or for internal inter-processor
151  *   communication. The channel is saved under the assigned name 
152  *   and can be opened by other netapi threads instances.
153  *  @param[in]  @ref NETAPI_T: handle to the instance 
154  *  @param[in]  char * name: a pointer to the char string name for channel
155  *  @param[in]  @ref PKTIO_CB : callback to be issued on packet receive
156  *  @param[in]  @ref PKTIO_CFG_T: pointer to channel configuration
157  *  @param[out] int * err:  pointer to error return 
158  *  @retval     @ref PKTIO_HANDLE_T: handle to the pktio instance or NULL on error
159  *  @pre       @ref netapi_init 
160  */
161 PKTIO_HANDLE_T * pktio_create(NETAPI_T netapi_handle, /* netapi instance */
162                                char * name,  /* name of the channel */
163                                PKTIO_CB cb,  /* receive callback */
164                                PKTIO_CFG_T * p_cfg,  /* ptr to config*/
165                                int * err);
167 /*
168 *  @brief  API opens an existing  NETAPI channel
169  *
170  *  @details This opens an NETAPI pktio channel for use. The channel
171  *  must have already been created via @ref pktio_create or may have
172  *  been created internally during the netapi intialization.
173  *   Once opened, the channel can be used to send and/or receive
174  *   a TI @ref Ti_Pkt. This can be used for communication with the 
175  *   the Network co-processor (NETCP) or for internal inter-processor
176  *   communication. 
177  *
178  *  @param[in]  @ref NETAPI_T: handle to the instance 
179  *  @param[in]  char * name: a pointer to the char string name for channel
180  *  @param[in]  @ref PKTIO_CB : callback to be issued on packet receive
181  *  @param[in]  @ref PKTIO_CFG_T: pointer to channel configuration
182  *  @param[out] int * err:  pointer to error return
183  *  @retval     @ref PKTIO_HANDLE_T: handle to the pktio instance or NULL on error
184  *  @pre       @ref netapi_init , @ref pktio_create
185  */
186 PKTIO_HANDLE_T * pktio_open(NETAPI_T netapi_handle, /* netapi instance */
187                             char *name,  /* name of channel to open */
188                             PKTIO_CB cb, /* receive callback */
189                             PKTIO_CFG_T *p_cfg, /* channel configuration */
190                             int * err);
192 /* future: control the channel */
193 void pktio_control(PKTIO_HANDLE_T * channel, //handle from open or create
194                                PKTIO_CB cb,  //change the callback
195                                PKTIO_CFG_T * p_cfg,//optional 
196                                PKTIO_CONTROL_T *p_control,//optional
197                                int *err);
198                              
199 /* future: close or delete a pktio channel */
200 void pktio_close(PKTIO_HANDLE_T * channel, int * err);
201 void pktio_delete(PKTIO_HANDLE_T * channel, int * err);
203 /*
204 *  @brief  API sends data to a pktio channel 
205  *
206  *  @details This sends a @ref Ti_Pkt and associated meta data, 
207  *  @ref PKTIO_METADATA_T to a channel. The channel
208  *  must have already been created via @ref pktio_create or opened
209  *  via @ref pktio_open.  It  may have
210  *  been created internally during the netapi intialization.
211  *  @param[in]  @ref PKTIO_HANDLE_T: handle to the channel
212  *  @param[in]  @ref Ti_Pkt*: pointer to the packet to send
213  *  @param[in]  @ref PKTIO_METADATA_T: pointer to meta data associated with packet 
214  *  @param[out] int * err:  pointer to error return
215  *  @retval      int npkts: 1 if packet sent, 0 if error 
216  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
217  */
218 int  pktio_send(PKTIO_HANDLE_T * channel, /* the channel */
219                 Ti_Pkt *pkt,              /* pointer to packet */
220                 PKTIO_METADATA_T *m,      /* pointer to meta data */
221                 int * err);
223 /*
224 *  @brief  API sends data to a pktio channel
225  *
226  *  @details This sends an array of @ref Ti_Pkt and associated meta data,
227  *  @ref PKTIO_METADATA_T to a channel. The channel
228  *  must have already been created via @ref pktio_create or opened
229  *  via @ref pktio_open.  It  may have
230  *  been created internally during the netapi intialization.
231  *  @param[in]  @ref PKTIO_HANDLE_T: handle to the channel
232  *  @param[in]  @ref Ti_Pkt*: pointer to the packet to send
233  *  @param[in]  @ref PKTIO_METADATA_T: pointer to meta data associated with packet
234  *  @oaran[in[  int np:  the number of packets in list to send
235  *  @param[out] int * err:  pointer to error return
236  *  @retval      int npkts: number of packets sent, 0 if error
237  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
238  */
239 int pktio_sendMulti(PKTIO_HANDLE_T *channel, /* the channel handle */
240                     Ti_Pkt * pkt[], /* array of packets to send */
241                     PKTIO_METADATA_T * m[], /* meta data array */
242                     int np,      /* number of packets to send */
243                     int * err);
245 /***********************************/
246 /************* polling **************/
247 /***********************************/
249 /*
250 *  @brief  API polls a pkto channel for received packets 
251  *
252  *  @details This api polls a pktio channel. Any pending data in the channel is
253  *  passed to the @ref  PKTIO_CB registered when the channel was
254  *  created or opened. The channel must
255  *  have already been created via @ref pktio_create or opened
256  *  via @ref pktio_open.  It  may have
257  *  been created internally during the netapi intialization.
258  *  @param[in]  @ref PKTIO_HANDLE_T: handle to the channel
259  *  @param[in]  @ref PKTIO_POLL_T *: pointer to pktio poll configuration
260  *  @param[out] int * err:  pointer to error return
261  *  @retval      int npkts: number of packets received by poll 
262  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
263  */
264 int pktio_poll(PKTIO_HANDLE_T * handle,   //handle to pktio
265                PKTIO_POLL_T * p_poll_cfg,  //polling configuration
266                int * err);
268 /*
269 *  @brief  API polls all pkto channels associarted with @ref NETAPI_T instance
270  *         for received packets
271  *
272  *  @details This api polls all pktio channels attached to an instance.
273  *  Any pending data in these channels are 
274  *  passed to the @ref  PKTIO_CB registered when the channel was
275  *  created or opened. The channels  must
276  *  have already been created via @ref pktio_create or opened
277  *  via @ref pktio_open.  They may have
278  *  been created internally during the netapi intialization.
279  *  @param[in]  @ref NETAPI_T: handle of the NETAPI instance 
280  *  @param[in]  @ref PKTIO_POLL_T *: pointer to pktio poll configuration
281  *  @param[out] int * err:  pointer to error return
282  *  @retval      int npkts: number of packets received by poll
283  *  @pre       @ref netapi_init, @ref pktio_create, @ref pktio_open
284  */
285 int pktio_pollAll(NETAPI_T handle, PKTIO_POLL_T * p_poll_cfg, int *err);
287 /*----------------- utilities------------------ */
288 /* update max_n for poll */
289 #define pktio_set_max_n(handle,max_n) (handle)->max_n=max_n;
290 #define pktio_get_netapi_handle(handle) (handle)->back
291 #define pktio_set_cookie(handle, cookie) (handle)->cookie = cookie
292 #define pktio_get_cookie(handle) (handle)->cookie
294 #endif