| llfifo Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

llfifo Documentation

The Xilinx Dual Channel Fifo driver component. This driver supports the Virtex-5(TM) and Virtex-4(TM) XPS_ll_Fifo and the AxiFifo.

For a full description of the bridge features, please see the HW spec. This driver supports the following features:

- Memory mapped access to host interface registers
- API for polled frame transfers
- API for interrupt driven frame transfers
- Virtual memory support
- Full duplex operation

## Driver Description

This driver enables higher layer software to access the XPS_llFifo core using any alignment in the data buffers.

This driver supports send and receive channels in the same instance structure in the same fashion as the hardware core.

## Initialization

An instance of this driver is initialized using a call to Initialize().

## Usage

It is fairly simple to use the API provided by this FIFO driver. The only somewhat tricky part is that the calling code must correctly call a couple routines in the right sequence for receive and transmit.

This sequence is described here. Check the routine functional descriptions for information on how to use a specific API routine.

### Receive

A frame is received by using the following sequence:
1) call XLlFifo_iRxGetLen() to get the length of the incoming frame
2) call XLlFifo_RxGetWord() one or more times to read the number of bytes reported by the hardware
3) call XLlFifo_iRxOccupancy() to know the availability of the data in the FIFO.

For example:

            ReceiveLength = (XLlFifo_iRxGetLen(InstancePtr))/WORD_SIZE;
            for ( i=0; i < ReceiveLength; i++){
                    RxWord = XLlFifo_RxGetWord(InstancePtr);
                    // ********
                    // do something here with the data
                    // ********
                    if(XLlFifo_iRxOccupancy(InstancePtr)){
                            RxWord = XLlFifo_RxGetWord(InstancePtr);
                    }
            }

This FIFO hardware core does not support a sequence where the calling code calls iRxGetLen() twice in a row and then receive the data for two frames. Each frame must be read in by calling iRxGetLen() just prior to reading the data.

### Transmit

A frame is transmittted by using the following sequence:
1) XLlFifo_iTxVacancy() one or more times to know the availability of unused 32-bit words in the FIFO channel.
2) call XLlFifo_TxPutWord() one or more times to write all the of bytes in the next frame.
3) call XLlFifo_iTxSetLen() to begin the transmission of frame just written.

For example:

            for (j=0 ; j < MAX_PACKET_LEN ; j++){
                    if( XLlFifo_iTxVacancy(InstancePtr) ){
                            XLlFifo_TxPutWord(InstancePtr,
                                    *(SourceAddr+(i*MAX_PACKET_LEN)+j));
                    }
            }
            XLlFifo_iTxSetLen(InstancePtr, (MAX_DATA_BUFFER_SIZE * WORD_SIZE));

This FIFO hardware core does not support a sequence where the calling code writes the data for two frames and then calls iTxSetLen() twice in a row. Each frame must be written by writing the data for one frame and then calling iTxSetLen().

## Interrupts

This driver does not handle interrupts from the FIFO hardware. The software layer above may make use of the interrupts by setting up its own handlers for the interrupts.

     MODIFICATION HISTORY:

     Ver   Who  Date     Changes

     1.00a jvb  10/12/06 First release
     1.01a sdm  08/22/08 Removed support for static interrupt handlers from the
                           MDD file
     1.02a jz   12/04/09 Hal phase 1 support
     2.01a asa  09/17/10 Added code for resetting Local Link/AXI Streaming
                           interface for CR574868
     2.02a asa  12/27/11 Changed the function XStrm_Read in xtreamer.c to reset
                           HeadIndex to zero when all bytes have been read.
                           Changed the macro XStrm_IsRxInternalEmpty in file
                           xtreamer.h to use FrmByteCnt instead of HeadIndex.
                           When FrmByteCnt is zero, this means all internal buffers
                           in streamer are empty. Earlier implementation using
                           HeadIndex was not very clear and could give improper
                           results for some cases.
                           Changed the macro XLlFifo_IsRxEmpty in file xllfifo.h
                           These changes are done to fix the CR 604650.
      2.03a asa  14/08/12  Added XLLF_TDR_OFFSET, XLLF_RDR_OFFSET
                             defines for the new registers, and XLLF_INT_TFPF_MASK,
                             XLLF_INT_TFPE_MASK, XLLF_INT_RFPF_MASK and
                             XLLF_INT_RFPE_MASK for the new version of the
                             AXI4-Stream FIFO core (v2.01a and later)

     3.00a adk 08/10/13 Added support for AXI4 Datainterface.Changes are
                          In Xllfifo.c file XLlFifo_RxGetWord,XLlFifo_TxPutword.
                          In XLlfifo.h file updated XLlfifo structure for
                          Axi4BaseAddress and for Datainterface type provided
                          polling and interrupt examples. XLlfifo_IsRxDone Macro
                          Is added in the XLlfifo.h file for polledmode example.
                          Added Static initialization for the driver.
                          XLlFifo_Initialize is still used to make the driver
                          backward compatible.
     4.0   adk  19/12/13 Updated as per the New Tcl API's
     5.0   adk  15/05/15 Updated the register offsets in the AXI4 data path
                           as per latest IP version(v4.1)(CR:860254).
     5.1   sk   11/10/15 Used UINTPTR instead of u32 for Baseaddress CR# 867425.
                         Changed the prototypes of XLlFifo_CfgInitialize,
                         XLlFifo_Initialize APIs.
     5.1  adk   01/02/15 CR#885653 Fix Incorrect AXI4 Base address being
                         Exported to the xparameters.h file.
          ms    01/23/17 Modified xil_printf statement in main function for all
                         examples to ensure that "Successfully ran" and "Failed"
                         strings are available in all examples. This is a fix
                         for CR-965028.
          ms    03/17/17 Added readme.txt file in examples folder for doxygen
                         generation.
          ms    04/05/17  Added tabspace for return statements in functions for
                          proper documentation and Modified Comment lines
                          to consider it as a documentation block while
                          generating doxygen for llfifo examples.
     5.2  ms    04/18/17 Modified tcl file to add suffix U for all macros
                         definitions of llfifo in xparameters.h
     5.2 adk    03/07/17 CR#978769 Fix doxygen issues in the driver.
                           Updated comments in the usage section as per example code.
                           Fix doxygen warnings in the driver.
     5.5 sd     09/04/20  Makefile update for parallel execution.
     5.6 sd     07/7/23  Add system devicetree support.