| blob | 2df16cbcdad5117de83cbd57bd7d8f270839fabc |
1 /* $Id: */
2 /******************************************************************************
3 *
4 * XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"
5 * AS A COURTESY TO YOU, SOLELY FOR USE IN DEVELOPING PROGRAMS AND
6 * SOLUTIONS FOR XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE,
7 * OR INFORMATION AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE,
8 * APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION
9 * THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,
10 * AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE
11 * FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY
12 * WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE
13 * IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR
14 * REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF
15 * INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
16 * FOR A PARTICULAR PURPOSE.
17 *
18 * (c) Copyright 2005-2008 Xilinx Inc.
19 * All rights reserved.
20 * This program is free software; you can redistribute it and/or modify it
21 * under the terms of the GNU General Public License as published by the
22 * Free Software Foundation; either version 2 of the License, or (at your
23 * option) any later version.
24 *
25 * You should have received a copy of the GNU General Public License
26 * along with this program; if not, write to the Free Software
27 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
28 *
29 ******************************************************************************/
30 /*****************************************************************************/
31 /**
32 *
33 * @file llfifo.h
34 *
35 * The Xilinx Dual Channel Fifo driver component. This driver supports the
36 * Virtex-5(TM) and Virtex-4(TM) XPS_ll_Fifo.
37 *
38 * For a full description of the bridge features, please see the HW spec. This driver
39 * supports the following features:
40 * - Memory mapped access to host interface registers
41 * - API for polled frame transfers
42 * - API for interrupt driven frame transfers
43 * - Virtual memory support
44 * - Full duplex operation
45 *
46 * <h2>Driver Description</h2>
47 *
48 * This driver enables higher layer software to access the XPS_llFifo core
49 * using any alignment in the data buffers.
50 *
51 * This driver supports send and receive channels in the same instance
52 * structure in the same fashion as the hardware core.
53 *
54 * <h2>Initialization</h2>
55 *
56 * An instance of this driver is initialized using a call to Initialize().
57 *
58 * <h2>Usage</h2>
59 *
60 * It is fairly simple to use the API provided by this FIFO driver. The
61 * only somewhat tricky part is that the calling code must correctly call
62 * a couple routines in the right sequence for receive and transmit.
63 *
64 * This sequence is described here. Check the routine functional
65 * descriptions for information on how to use a specific API routine.
66 *
67 * <h3>Receive</h3>
68 *
69 * A frame is received by using the following sequence:<br>
70 * 1) call XLlFifo_RxGetLen() to get the length of the next incoming frame<br>
71 * 2) call XLlFifo_Read() one or more times to read the number of bytes
72 * reported by XLlFifo_RxGetLen().<br>
73 *
74 * For example:
75 * <pre>
76 * frame_len = XLlFifo_RxGetLen(&RxInstance);
77 * while (frame_len) {
78 * unsigned bytes = min(sizeof(buffer), frame_len);
79 * XLlFifo_Read(&RxInstance, buffer, bytes);
80 * // ********
81 * // do something with buffer here
82 * // ********
83 * frame_len -= bytes;
84 * }
85 * </pre>
86 *
87 * This FIFO hardware core does <b>not</b> support a sequence where the
88 * calling code calls RxGetLen() twice in a row and then receive the data
89 * for two frames. Each frame must be read in by calling RxGetLen() just
90 * prior to reading the data.
91 *
92 * <h3>Transmit</h3>
93 * A frame is transmittted by using the following sequence:<br>
94 * 1) call XLlFifo_Write() one or more times to write all the of bytes in
95 * the next frame.<br>
96 * 2) call XLlFifo_TxSetLen() to begin the transmission of frame just
97 * written.<br>
98 *
99 * For example:
100 * <pre>
101 * frame_left = frame_len;
102 * while (frame_left) {
103 * unsigned bytes = min(sizeof(buffer), frame_left);
104 * XLlFifo_Write(&TxInstance, buffer, bytes);
105 * // ********
106 * // do something here to refill buffer
107 * // ********
108 * }
109 * XLlFifo_TxSetLen(&RxInstance, frame_len);
110 * </pre>
111 *
112 * This FIFO hardware core does <b>not</b> support a sequence where the
113 * calling code writes the data for two frames and then calls TxSetLen()
114 * twice in a row. Each frame must be written by writting the data for one
115 * frame and then calling TxSetLen().
116 *
117 * <h2>Interrupts</h2>
118 * This driver does not handle interrupts from the FIFO hardware. The
119 * software layer above may make use of the interrupts by setting up its
120 * own handlers for the interrupts.
121 *
122 * <pre>
123 * MODIFICATION HISTORY:
124 *
125 * Ver Who Date Changes
126 * ----- ---- -------- -------------------------------------------------------
127 * 1.00a jvb 10/12/06 First release
128 * </pre>
129 *
130 *****************************************************************************/
134 /* force C linkage */
135 #ifdef __cplusplus
137 #endif
139 /***************************** Include Files *********************************/
144 /**************************** Type Definitions *******************************/
146 /**
147 * This typedef defines a run-time instance of an XLlFifo device.
148 */
151 * device's registers
152 */
155 * has been initialized.
156 */
158 * instance for the receive channel.
159 */
161 * instance for the transmit channel.
162 */
165 /****************************************************************************/
166 /**
167 *
168 * XLlFifo_Reset resets both the Tx and Rx channels and the local link interface
169 * the FIFO specified by <i>InstancePtr</i>. XLlFifo_TxReset resets also sends a
170 * reset pulse to the downstream device (e.g. TEMAC). XLlFifo_Reset drops any
171 * bytes in the FIFO not yet retrieved. XLlFifo_Reset drops any bytes in the FIFO
172 * not yet transmitted.
173 *
174 * @param InstancePtr references the FIFO on which to operate.
175 *
176 * @return N/A
177 *
178 * @note
179 * C-style signature:
180 * void XLlFifo_Reset(XLlFifo *InstancePtr)
181 *
182 *****************************************************************************/
183 #define XLlFifo_Reset(InstancePtr) \
184 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_LLR_OFFSET, \
185 XLLF_LLR_RESET_MASK)
188 /****************************************************************************/
189 /**
190 *
191 * XLlFifo_Status returns a bit mask of the interrupt status register (ISR)
192 * for the FIFO specified by <i>InstancePtr</i>. XLlFifo_Status can be used
193 * to query the status of the FIFO without having to have interrupts enabled.
194 *
195 * @param InstancePtr references the FIFO on which to operate.
196 *
197 * @return XLlFifo_IntStatus returns a bit mask of the status conditions.
198 * The mask will be a set of bitwise or'd values from the
199 * <code>XLLF_INT_*_MASK</code> preprocessor symbols.
200 *
201 * @note
202 * C-style signature:
203 * u32 XLlFifo_IntStatus(XLlFifo *InstancePtr)
204 *
205 *****************************************************************************/
206 #define XLlFifo_Status(InstancePtr) \
207 XLlFifo_ReadReg((InstancePtr)->BaseAddress, XLLF_ISR_OFFSET)
209 /****************************************************************************/
210 /**
211 *
212 * XLlFifo_IntEnable enables the interrupts specified in <i>Mask</i> for the
213 * FIFO specified by <i>InstancePtr</i>. The corresponding interrupt for each bit
214 * set to 1 in <i>Mask</i>, will be enabled.
215 *
216 * @param InstancePtr references the FIFO on which to operate.
217 *
218 * @param Mask contains a bit mask of the interrupts to enable. The mask
219 * can be formed using a set of bitwise or'd values from the
220 * <code>XLLF_INT_*_MASK</code> preprocessor symbols.
221 *
222 * @return N/A
223 *
224 * @note
225 * C-style signature:
226 * void XLlFifo_IntEnable(XLlFifo *InstancePtr, u32 Mask)
227 *
228 *****************************************************************************/
229 #define XLlFifo_IntEnable(InstancePtr, Mask) \
230 { \
231 u32 Reg = XLlFifo_ReadReg((InstancePtr)->BaseAddress, \
232 XLLF_IER_OFFSET); \
233 Reg |= ((Mask) & XLLF_INT_ALL_MASK); \
234 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_IER_OFFSET, \
235 Reg); \
236 }
238 /****************************************************************************/
239 /**
240 *
241 * XLlFifo_IntDisable disables the interrupts specified in <i>Mask</i> for the
242 * FIFO specified by <i>InstancePtr</i>. The corresponding interrupt for each bit
243 * set to 1 in <i>Mask</i>, will be disabled. In other words, XLlFifo_IntDisable
244 * uses the "set a bit to clear it" scheme.
245 *
246 * @param InstancePtr references the FIFO on which to operate.
247 *
248 * @param Mask contains a bit mask of the interrupts to disable. The mask
249 * can be formed using a set of bitwise or'd values from the
250 * <code>XLLF_INT_*_MASK</code> preprocessor symbols.
251 *
252 * @return N/A
253 *
254 * @note
255 * C-style signature:
256 * void XLlFifo_IntDisable(XLlFifo *InstancePtr, u32 Mask)
257 *
258 *****************************************************************************/
259 #define XLlFifo_IntDisable(InstancePtr, Mask) \
260 { \
261 u32 Reg = XLlFifo_ReadReg((InstancePtr)->BaseAddress, \
262 XLLF_IER_OFFSET); \
263 Reg &= ~((Mask) & XLLF_INT_ALL_MASK); \
264 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_IER_OFFSET, \
265 Reg); \
266 }
268 /****************************************************************************/
269 /**
270 *
271 * XLlFifo_IntPending returns a bit mask of the pending interrupts for the
272 * FIFO specified by <i>InstancePtr</i>. Each bit set to 1 in the return value
273 * represents a pending interrupt.
274 *
275 * @param InstancePtr references the FIFO on which to operate.
276 *
277 * @return XLlFifo_IntPending returns a bit mask of the interrupts that are
278 * pending. The mask will be a set of bitwise or'd values from the
279 * <code>XLLF_INT_*_MASK</code> preprocessor symbols.
280 *
281 * @note
282 * C-style signature:
283 * u32 XLlFifo_IntPending(XLlFifo *InstancePtr)
284 *
285 *****************************************************************************/
286 #ifdef DEBUG
289 #define XLlFifo_IntPending(InstancePtr) \
290 (_xllfifo_ipie_value = XLlFifo_ReadReg( \
291 (InstancePtr)->BaseAddress, XLLF_IER_OFFSET), \
292 _xllfifo_ipis_value = XLlFifo_ReadReg( \
293 (InstancePtr)->BaseAddress, XLLF_ISR_OFFSET), \
294 (_xllfifo_ipie_value & _xllfifo_ipis_value))
295 #else
296 #define XLlFifo_IntPending(InstancePtr) \
297 (XLlFifo_ReadReg((InstancePtr)->BaseAddress, XLLF_IER_OFFSET) & \
298 XLlFifo_ReadReg((InstancePtr)->BaseAddress, XLLF_ISR_OFFSET))
299 #endif
301 /****************************************************************************/
302 /**
303 *
304 * XLlFifo_IntClear clears pending interrupts specified in <i>Mask</i> for the
305 * FIFO specified by <i>InstancePtr</i>. The corresponding pending interrupt for
306 * each bit set to 1 in <i>Mask</i>, will be cleared. In other words,
307 * XLlFifo_IntClear uses the "set a bit to clear it" scheme.
308 *
309 * @param InstancePtr references the FIFO on which to operate.
310 *
311 * @param Mask contains a bit mask of the pending interrupts to clear. The
312 * mask can be formed using a set of bitwise or'd values from the
313 * <code>XLLF_INT_*_MASK</code> preprocessor symbols.
314 *
315 * @note
316 * C-style signature:
317 * void XLlFifo_IntClear(XLlFifo *InstancePtr, u32 Mask)
318 *
319 *****************************************************************************/
320 #define XLlFifo_IntClear(InstancePtr, Mask) \
321 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_ISR_OFFSET, \
322 ((Mask) & XLLF_INT_ALL_MASK))
324 /****************************************************************************/
325 /**
326 *
327 * XLlFifo_RxReset resets the receive channel of the FIFO specified by
328 * <i>InstancePtr</i>. XLlFifo_RxReset drops any bytes in the FIFO not yet
329 * retrieved.
330 *
331 * The calling software may want to test for the completion of the reset by
332 * reading the interrupt status (IS) register and testing for the Rx Reset
333 * complete (RRC) bit.
334 *
335 * @param InstancePtr references the FIFO on which to operate.
336 *
337 * @return N/A
338 *
339 * @note
340 * C-style signature:
341 * void XLlFifo_RxReset(XLlFifo *InstancePtr)
342 *
343 *****************************************************************************/
344 #define XLlFifo_RxReset(InstancePtr) \
345 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_RDFR_OFFSET, \
346 XLLF_RDFR_RESET_MASK)
348 /****************************************************************************/
349 /**
350 *
351 * XLlFifo_IsRxEmpty returns true if the receive channel of the FIFO, specified
352 * by <i>InstancePtr</i>, is empty.
353 *
354 * @param InstancePtr references the FIFO on which to operate.
355 *
356 * @return XLlFifo_IsRxEmpty returns TRUE when the receive channel of the
357 * FIFO is empty. Otherwise, XLlFifo_IsRxEmpty returns FALSE.
358 *
359 * @note
360 * C-style signature:
361 * int XLlFifo_IsRxEmpty(XLlFifo *InstancePtr)
362 *
363 *****************************************************************************/
364 #define XLlFifo_IsRxEmpty(InstancePtr) \
365 ((XStrm_IsRxInternalEmpty(&((InstancePtr)->RxStreamer)) && \
366 ((XLlFifo_ReadReg((InstancePtr)->BaseAddress, \
367 XLLF_RDFO_OFFSET) == 0))) \
368 ? TRUE : FALSE)
371 /*****************************************************************************/
372 /**
373 *
374 * XLlFifo_RxOccupancy returns the number of 32-bit words available (occupancy) to
375 * be read from the receive channel of the FIFO, specified by <i>InstancePtr</i>.
376 *
377 * The xps_ll_fifo core uses the same fifo to store data values and frame length
378 * values. Upon initialization, the XLlFifo_RxOccupancy will give the value of
379 * 1, which means one length value (a reserved fifo location) and no data
380 * values.
381 *
382 * @param InstancePtr references the FIFO on which to operate.
383 *
384 * @return XLlFifo_RxOccupancy returns the occupancy count for the specified
385 * packet FIFO.
386 *
387 * @note
388 *
389 * C Signature: u32 XLlFifo_RxOccupancy(XLlFifo *InstancePtr)
390 *
391 ******************************************************************************/
392 #define XLlFifo_RxOccupancy(InstancePtr) \
393 XStrm_RxOccupancy(&((InstancePtr)->RxStreamer))
395 /*****************************************************************************/
396 /**
397 *
398 * XLlFifo_RxGetLen notifies the hardware that the program is ready to receive
399 * the next frame from the receive channel of the FIFO, specified by
400 * <i>InstancePtr</i>.
401 *
402 * Note that the program must first call XLlFifo_RxGetLen before pulling data
403 * out of the receive channel of the FIFO with XLlFifo_Read.
404 *
405 * @param InstancePtr references the FIFO on which to operate.
406 *
407 * @return XLlFifo_RxGetLen returns the number of bytes available in the next
408 * frame.
409 *
410 * @note
411 *
412 * C Signature: u32 XLlFifo_RxGetLen(XLlFifo *InstancePtr)
413 *
414 ******************************************************************************/
415 #define XLlFifo_RxGetLen(InstancePtr) \
416 XStrm_RxGetLen(&((InstancePtr)->RxStreamer))
418 /*****************************************************************************/
419 /**
420 *
421 * XLlFifo_Read reads <i>Bytes</i> bytes from the receive channel of the FIFO
422 * referenced by <i>InstancePtr</i> to the block of memory, referenced by
423 * <i>BufPtr</i>.
424 *
425 * Care must be taken to ensure that the number of bytes read with one or more
426 * calls to XLlFifo_Read() does not exceed the number of bytes available given
427 * from the last call to XLlFifo_RxGetLen().
428 *
429 * @param InstancePtr references the FIFO on which to operate.
430 *
431 * @param BufPtr specifies the memory address to place the data read.
432 *
433 * @param Bytes specifies the number of bytes to read.
434 *
435 * @return N/A
436 *
437 * @note
438 * Error handling is handled through hardware exceptions and interrupts.
439 *
440 * C Signature: void XLlFifo_Read(XLlFifo *InstancePtr, void *BufPtr, unsigned Bytes)
441 *
442 ******************************************************************************/
443 #define XLlFifo_Read(InstancePtr, BufPtr, Bytes) \
444 XStrm_Read(&((InstancePtr)->RxStreamer), (BufPtr), (Bytes))
446 /****************************************************************************/
447 /**
448 *
449 * XLlFifo_TxReset resets the transmit channel of the FIFO specified by
450 * <i>InstancePtr</i>. XLlFifo_TxReset drops any bytes in the FIFO not yet
451 * transmitted.
452 *
453 * The calling software may want to test for the completion of the reset by
454 * reading the interrupt status (IS) register and testing for the Tx Reset
455 * complete (TRC) bit.
456 *
457 * @param InstancePtr references the FIFO on which to operate.
458 *
459 * @return N/A
460 *
461 * @note
462 * C-style signature:
463 * void XLlFifo_TxReset(XLlFifo *InstancePtr)
464 *
465 *****************************************************************************/
466 #define XLlFifo_TxReset(InstancePtr) \
467 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_TDFR_OFFSET, \
468 XLLF_TDFR_RESET_MASK)
470 /****************************************************************************/
471 /**
472 *
473 * XLlFifo_IsTxDone returns true if the transmission in the transmit channel
474 * of the FIFO, specified by <i>InstancePtr</i>, is complete. XLlFifo_IsTxDone
475 * works only if the TC bit in the IS register is cleared before sending a
476 * frame.
477 *
478 * @param InstancePtr references the FIFO on which to operate.
479 *
480 * @return XLlFifo_IsTxDone returns TRUE when the transmit channel of the
481 * FIFO is complete. Otherwise, XLlFifo_IsTxDone returns FALSE.
482 *
483 * @note
484 * C-style signature:
485 * int XLlFifo_IsTxDone(XLlFifo *InstancePtr)
486 *
487 *****************************************************************************/
488 #define XLlFifo_IsTxDone(InstancePtr) \
489 ((XLlFifo_ReadReg((InstancePtr)->BaseAddress, XLLF_ISR_OFFSET) & \
490 XLLF_INT_TC_MASK) \
491 ? TRUE : FALSE)
493 /****************************************************************************/
494 /**
495 *
496 * XLlFifo_TxVacancy returns the number of unused 32 bit words available
497 * (vacancy) in the send channel of the FIFO specified by <i>InstancePtr</i>.
498 *
499 * The xps_ll_fifo core uses tXLLF_he same fifo to store data values and frame length
500 * values. Upon initialization, the XLlFifo_TxVacancy will give the value of
501 * FIFO_WIDTH - 1, which means one length value used (a reserved fifo location)
502 * and no data values yet present.
503 *
504 * @param InstancePtr references the FIFO on which to operate.
505 *
506 * @return XLlFifo_TxVacancy returns the vacancy count in 32-bit words for
507 * the specified FIFO.
508 *
509 * @note
510 * C-style signature:
511 * u32 XLlFifo_TxVacancy(XLlFifo *InstancePtr)
512 *
513 *****************************************************************************/
514 #define XLlFifo_TxVacancy(InstancePtr) \
515 XStrm_TxVacancy(&((InstancePtr)->TxStreamer))
517 /*****************************************************************************/
518 /**
519 *
520 * XLlFifo_TxSetLen begins a hardware transfer of <i>Bytes</i> bytes out of the
521 * transmit channel of the FIFO specified by <i>InstancePtr</i>.
522 *
523 * @param InstancePtr references the FIFO on which to operate.
524 *
525 * @param Bytes specifies the frame length in bytes.
526 *
527 * @return N/A
528 *
529 * @note
530 *
531 * C Signature: void XLlFifo_TxSetLen(XLlFifo *InstancePtr, u32 Bytes)
532 *
533 ******************************************************************************/
534 #define XLlFifo_TxSetLen(InstancePtr, Bytes) \
535 XStrm_TxSetLen(&((InstancePtr)->TxStreamer), (Bytes))
537 /*****************************************************************************/
538 /**
539 *
540 * XLlFifo_Write writes <i>Bytes</i> bytes of the block of memory, referenced by
541 * <i>BufPtr</i>, to the transmit channel of the FIFO referenced by
542 * <i>InstancePtr</i>.
543 *
544 * Care must be taken to ensure that the number of bytes written with one or
545 * more calls to XLlFifo_Write() matches the number of bytes given in the next
546 * call to XLlFifo_TxSetLen().
547 *
548 * @param InstancePtr references the FIFO on which to operate.
549 *
550 * @param BufPtr specifies the memory address of data to write.
551 *
552 * @param Bytes specifies the number of bytes to write.
553 *
554 * @return N/A
555 *
556 * @note
557 * Error handling is handled through hardware exceptions and interrupts.
558 *
559 * C Signature: void XLlFifo_Write(XLlFifo *InstancePtr, void *BufPtr, unsigned Bytes)
560 *
561 ******************************************************************************/
562 #define XLlFifo_Write(InstancePtr, BufPtr, Bytes) \
563 XStrm_Write(&((InstancePtr)->TxStreamer), (BufPtr), (Bytes))
566 /************************** Function Prototypes ******************************/
567 /*
568 * Initialization functions in xtemac_sinit.c
569 */
572 #ifdef __cplusplus
573 }
574 #endif