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
105 {
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
126 {
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
136 {
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);
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