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