2 /******************************************************************************
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.
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.
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
29 ******************************************************************************/
30 /*****************************************************************************/
35 * The Xilinx Dual Channel Fifo driver component. This driver supports the
36 * Virtex-5(TM) and Virtex-4(TM) XPS_ll_Fifo.
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
46 * <h2>Driver Description</h2>
48 * This driver enables higher layer software to access the XPS_llFifo core
49 * using any alignment in the data buffers.
51 * This driver supports send and receive channels in the same instance
52 * structure in the same fashion as the hardware core.
54 * <h2>Initialization</h2>
56 * An instance of this driver is initialized using a call to Initialize().
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.
64 * This sequence is described here. Check the routine functional
65 * descriptions for information on how to use a specific API routine.
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>
76 * frame_len = XLlFifo_RxGetLen(&RxInstance);
78 * unsigned bytes = min(sizeof(buffer), frame_len);
79 * XLlFifo_Read(&RxInstance, buffer, bytes);
81 * // do something with buffer here
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.
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
96 * 2) call XLlFifo_TxSetLen() to begin the transmission of frame just
101 * frame_left = frame_len;
102 * while (frame_left) {
103 * unsigned bytes = min(sizeof(buffer), frame_left);
104 * XLlFifo_Write(&TxInstance, buffer, bytes);
106 * // do something here to refill buffer
109 * XLlFifo_TxSetLen(&RxInstance, frame_len);
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().
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.
123 * MODIFICATION HISTORY:
125 * Ver Who Date Changes
126 * ----- ---- -------- -------------------------------------------------------
127 * 1.00a jvb 10/12/06 First release
130 *****************************************************************************/
131 #ifndef XLLFIFO_H /* prevent circular inclusions */
132 #define XLLFIFO_H /* by using preprocessor symbols */
134 /* force C linkage */
139 /***************************** Include Files *********************************/
141 #include "xllfifo_hw.h"
142 #include "xstreamer.h"
144 /**************************** Type Definitions *******************************/
147 * This typedef defines a run-time instance of an XLlFifo device.
149 typedef struct XLlFifo
{
150 u32 BaseAddress
; /**< BaseAddress is the physical base address of the
154 u32 IsReady
; /**< IsReady is non-zero if the driver instance
155 * has been initialized.
157 XStrm_RxFifoStreamer RxStreamer
; /**< RxStreamer is the byte streamer
158 * instance for the receive channel.
160 XStrm_TxFifoStreamer TxStreamer
; /**< TxStreamer is the byte streamer
161 * instance for the transmit channel.
165 /****************************************************************************/
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.
174 * @param InstancePtr references the FIFO on which to operate.
180 * void XLlFifo_Reset(XLlFifo *InstancePtr)
182 *****************************************************************************/
183 #define XLlFifo_Reset(InstancePtr) \
184 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_LLR_OFFSET, \
188 /****************************************************************************/
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.
195 * @param InstancePtr references the FIFO on which to operate.
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.
203 * u32 XLlFifo_IntStatus(XLlFifo *InstancePtr)
205 *****************************************************************************/
206 #define XLlFifo_Status(InstancePtr) \
207 XLlFifo_ReadReg((InstancePtr)->BaseAddress, XLLF_ISR_OFFSET)
209 /****************************************************************************/
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.
216 * @param InstancePtr references the FIFO on which to operate.
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.
226 * void XLlFifo_IntEnable(XLlFifo *InstancePtr, u32 Mask)
228 *****************************************************************************/
229 #define XLlFifo_IntEnable(InstancePtr, Mask) \
231 u32 Reg = XLlFifo_ReadReg((InstancePtr)->BaseAddress, \
233 Reg |= ((Mask) & XLLF_INT_ALL_MASK); \
234 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_IER_OFFSET, \
238 /****************************************************************************/
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.
246 * @param InstancePtr references the FIFO on which to operate.
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.
256 * void XLlFifo_IntDisable(XLlFifo *InstancePtr, u32 Mask)
258 *****************************************************************************/
259 #define XLlFifo_IntDisable(InstancePtr, Mask) \
261 u32 Reg = XLlFifo_ReadReg((InstancePtr)->BaseAddress, \
263 Reg &= ~((Mask) & XLLF_INT_ALL_MASK); \
264 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_IER_OFFSET, \
268 /****************************************************************************/
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.
275 * @param InstancePtr references the FIFO on which to operate.
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.
283 * u32 XLlFifo_IntPending(XLlFifo *InstancePtr)
285 *****************************************************************************/
287 extern u32 _xllfifo_ipie_value
;
288 extern u32 _xllfifo_ipis_value
;
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))
296 #define XLlFifo_IntPending(InstancePtr) \
297 (XLlFifo_ReadReg((InstancePtr)->BaseAddress, XLLF_IER_OFFSET) & \
298 XLlFifo_ReadReg((InstancePtr)->BaseAddress, XLLF_ISR_OFFSET))
301 /****************************************************************************/
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.
309 * @param InstancePtr references the FIFO on which to operate.
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.
317 * void XLlFifo_IntClear(XLlFifo *InstancePtr, u32 Mask)
319 *****************************************************************************/
320 #define XLlFifo_IntClear(InstancePtr, Mask) \
321 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_ISR_OFFSET, \
322 ((Mask) & XLLF_INT_ALL_MASK))
324 /****************************************************************************/
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
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.
335 * @param InstancePtr references the FIFO on which to operate.
341 * void XLlFifo_RxReset(XLlFifo *InstancePtr)
343 *****************************************************************************/
344 #define XLlFifo_RxReset(InstancePtr) \
345 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_RDFR_OFFSET, \
346 XLLF_RDFR_RESET_MASK)
348 /****************************************************************************/
351 * XLlFifo_IsRxEmpty returns true if the receive channel of the FIFO, specified
352 * by <i>InstancePtr</i>, is empty.
354 * @param InstancePtr references the FIFO on which to operate.
356 * @return XLlFifo_IsRxEmpty returns TRUE when the receive channel of the
357 * FIFO is empty. Otherwise, XLlFifo_IsRxEmpty returns FALSE.
361 * int XLlFifo_IsRxEmpty(XLlFifo *InstancePtr)
363 *****************************************************************************/
364 #define XLlFifo_IsRxEmpty(InstancePtr) \
365 ((XStrm_IsRxInternalEmpty(&((InstancePtr)->RxStreamer)) && \
366 ((XLlFifo_ReadReg((InstancePtr)->BaseAddress, \
367 XLLF_RDFO_OFFSET) == 0))) \
371 /*****************************************************************************/
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>.
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
382 * @param InstancePtr references the FIFO on which to operate.
384 * @return XLlFifo_RxOccupancy returns the occupancy count for the specified
389 * C Signature: u32 XLlFifo_RxOccupancy(XLlFifo *InstancePtr)
391 ******************************************************************************/
392 #define XLlFifo_RxOccupancy(InstancePtr) \
393 XStrm_RxOccupancy(&((InstancePtr)->RxStreamer))
395 /*****************************************************************************/
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>.
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.
405 * @param InstancePtr references the FIFO on which to operate.
407 * @return XLlFifo_RxGetLen returns the number of bytes available in the next
412 * C Signature: u32 XLlFifo_RxGetLen(XLlFifo *InstancePtr)
414 ******************************************************************************/
415 #define XLlFifo_RxGetLen(InstancePtr) \
416 XStrm_RxGetLen(&((InstancePtr)->RxStreamer))
418 /*****************************************************************************/
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
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().
429 * @param InstancePtr references the FIFO on which to operate.
431 * @param BufPtr specifies the memory address to place the data read.
433 * @param Bytes specifies the number of bytes to read.
438 * Error handling is handled through hardware exceptions and interrupts.
440 * C Signature: void XLlFifo_Read(XLlFifo *InstancePtr, void *BufPtr, unsigned Bytes)
442 ******************************************************************************/
443 #define XLlFifo_Read(InstancePtr, BufPtr, Bytes) \
444 XStrm_Read(&((InstancePtr)->RxStreamer), (BufPtr), (Bytes))
446 /****************************************************************************/
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
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.
457 * @param InstancePtr references the FIFO on which to operate.
463 * void XLlFifo_TxReset(XLlFifo *InstancePtr)
465 *****************************************************************************/
466 #define XLlFifo_TxReset(InstancePtr) \
467 XLlFifo_WriteReg((InstancePtr)->BaseAddress, XLLF_TDFR_OFFSET, \
468 XLLF_TDFR_RESET_MASK)
470 /****************************************************************************/
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
478 * @param InstancePtr references the FIFO on which to operate.
480 * @return XLlFifo_IsTxDone returns TRUE when the transmit channel of the
481 * FIFO is complete. Otherwise, XLlFifo_IsTxDone returns FALSE.
485 * int XLlFifo_IsTxDone(XLlFifo *InstancePtr)
487 *****************************************************************************/
488 #define XLlFifo_IsTxDone(InstancePtr) \
489 ((XLlFifo_ReadReg((InstancePtr)->BaseAddress, XLLF_ISR_OFFSET) & \
493 /****************************************************************************/
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>.
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.
504 * @param InstancePtr references the FIFO on which to operate.
506 * @return XLlFifo_TxVacancy returns the vacancy count in 32-bit words for
507 * the specified FIFO.
511 * u32 XLlFifo_TxVacancy(XLlFifo *InstancePtr)
513 *****************************************************************************/
514 #define XLlFifo_TxVacancy(InstancePtr) \
515 XStrm_TxVacancy(&((InstancePtr)->TxStreamer))
517 /*****************************************************************************/
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>.
523 * @param InstancePtr references the FIFO on which to operate.
525 * @param Bytes specifies the frame length in bytes.
531 * C Signature: void XLlFifo_TxSetLen(XLlFifo *InstancePtr, u32 Bytes)
533 ******************************************************************************/
534 #define XLlFifo_TxSetLen(InstancePtr, Bytes) \
535 XStrm_TxSetLen(&((InstancePtr)->TxStreamer), (Bytes))
537 /*****************************************************************************/
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>.
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().
548 * @param InstancePtr references the FIFO on which to operate.
550 * @param BufPtr specifies the memory address of data to write.
552 * @param Bytes specifies the number of bytes to write.
557 * Error handling is handled through hardware exceptions and interrupts.
559 * C Signature: void XLlFifo_Write(XLlFifo *InstancePtr, void *BufPtr, unsigned Bytes)
561 ******************************************************************************/
562 #define XLlFifo_Write(InstancePtr, BufPtr, Bytes) \
563 XStrm_Write(&((InstancePtr)->TxStreamer), (BufPtr), (Bytes))
566 /************************** Function Prototypes ******************************/
568 * Initialization functions in xtemac_sinit.c
570 void XLlFifo_Initialize(XLlFifo
*InstancePtr
, u32 BaseAddress
);
575 #endif /* XLLFIFO_H end of preprocessor protection symbols */