xaxicdma.h File Reference

#include "xaxicdma_bd.h"
#include <string.h>
#include "xil_cache.h"

Classes

struct XAxiCdma_IntrHandlerList

struct XAxiCdma_Config

struct XAxiCdma

Defines

#define XAXICDMA_COALESCE_NO_CHANGE 0xFFFFFFFF

#define XAXICDMA_ALL_BDS 0x7FFFFFFF

#define XAXICDMA_SG_MODE 1

#define XAXICDMA_SIMPLE_MODE 2

#define XAXICDMA_MAXIMUM_MAX_HANDLER 20

#define XAXICDMA_KEYHOLE_READ 0

#define XAXICDMA_KEYHOLE_WRITE 1

#define XAXICDMA_CACHE_FLUSH(BdPtr) Xil_DCacheFlushRange((BdPtr), XAXICDMA_BD_HW_NUM_BYTES);

#define XAXICDMA_CACHE_INVALIDATE(BdPtr) Xil_DCacheInvalidateRange((BdPtr), XAXICDMA_BD_HW_NUM_BYTES)

Typedefs

Call Back function

If interrupt is enabled, and the application wants to be notified about the completion of a transfer, the application should register its call back function to the driver.

The call back function is registered through the transfer submission.

Parameters:

	CallBackRef	is the call back reference passed in by application. A NULL pointer is acceptable.
	IrqMask	is the interrupt mask regarding this completion
	NumBdPtr	is the pointer to number of BDs this handler should handle, for simple transfer, it is ignored.

typedef void(* XAxiCdma_CallBackFn )(void *CallBackRef, u32 IrqMask, int *NumBdPtr)

Functions

XAxiCdma_Config * XAxiCdma_LookupConfig (u32 DeviceId)

int XAxiCdma_CfgInitialize (XAxiCdma *InstancePtr, XAxiCdma_Config *CfgPtr, u32 EffectiveAddr)

void XAxiCdma_Reset (XAxiCdma *InstancePtr)

int XAxiCdma_ResetIsDone (XAxiCdma *InstancePtr)

int XAxiCdma_IsBusy (XAxiCdma *InstancePtr)

int XAxiCdma_SetCoalesce (XAxiCdma *InstancePtr, u32 Counter, u32 Delay)

void XAxiCdma_GetCoalesce (XAxiCdma *InstancePtr, u32 *CounterPtr, u32 *DelayPtr)

u32 XAxiCdma_GetError (XAxiCdma *InstancePtr)

void XAxiCdma_IntrEnable (XAxiCdma *InstancePtr, u32 Mask)

u32 XAxiCdma_IntrGetEnabled (XAxiCdma *InstancePtr)

void XAxiCdma_IntrDisable (XAxiCdma *InstancePtr, u32 Mask)

void XAxiCdma_IntrHandler (void *HandlerRef)

int XAxiCdma_SimpleTransfer (XAxiCdma *InstancePtr, u32 SrcAddr, u32 DstAddr, int Length, XAxiCdma_CallBackFn SimpleCallBack, void *CallbackRef)

int XAxiCdma_SelectKeyHole (XAxiCdma *InstancePtr, u32 Direction, u32 Select)

int XAxiCdma_BdRingCntCalc (u32 Alignment, u32 Bytes, u32 BuffAddr)

int XAxiCdma_BdRingMemCalc (u32 Alignment, int NumBd)

int XAxiCdma_BdRingGetCnt (XAxiCdma *InstancePtr)

int XAxiCdma_BdRingGetFreeCnt (XAxiCdma *InstancePtr)

void XAxiCdma_BdRingSnapShotCurrBd (XAxiCdma *InstancePtr)

XAxiCdma_Bd * XAxiCdma_BdRingGetCurrBd (XAxiCdma *InstancePtr)

XAxiCdma_Bd * XAxiCdma_BdRingNext (XAxiCdma *InstancePtr, XAxiCdma_Bd *BdPtr)

XAxiCdma_Bd * XAxiCdma_BdRingPrev (XAxiCdma *InstancePtr, XAxiCdma_Bd *BdPtr)

int XAxiCdma_BdRingCreate (XAxiCdma *InstancePtr, u32 PhysAddr, u32 VirtAddr, u32 Alignment, int BdCount)

int XAxiCdma_BdRingClone (XAxiCdma *InstancePtr, XAxiCdma_Bd *TemplateBdPtr)

int XAxiCdma_BdRingAlloc (XAxiCdma *InstancePtr, int NumBd, XAxiCdma_Bd **BdSetPtr)

int XAxiCdma_BdRingUnAlloc (XAxiCdma *InstancePtr, int NumBd, XAxiCdma_Bd *BdSetPtr)

int XAxiCdma_BdRingToHw (XAxiCdma *InstancePtr, int NumBd, XAxiCdma_Bd *BdSetPtr, XAxiCdma_CallBackFn CallBack, void *CallBackRef)

int XAxiCdma_BdRingFromHw (XAxiCdma *InstancePtr, int BdLimit, XAxiCdma_Bd **BdSetPtr)

int XAxiCdma_BdRingFree (XAxiCdma *InstancePtr, int NumBd, XAxiCdma_Bd *BdSetPtr)

void XAxiCdma_DumpRegisters (XAxiCdma *InstancePtr)

Detailed Description

Define Documentation

#define XAXICDMA_ALL_BDS 0x7FFFFFFF

#define XAXICDMA_CACHE_FLUSH ( BdPtr ) Xil_DCacheFlushRange((BdPtr), XAXICDMA_BD_HW_NUM_BYTES);

#define XAXICDMA_CACHE_INVALIDATE ( BdPtr ) Xil_DCacheInvalidateRange((BdPtr), XAXICDMA_BD_HW_NUM_BYTES)

#define XAXICDMA_COALESCE_NO_CHANGE 0xFFFFFFFF

#define XAXICDMA_KEYHOLE_READ 0

#define XAXICDMA_KEYHOLE_WRITE 1

#define XAXICDMA_MAXIMUM_MAX_HANDLER 20

#define XAXICDMA_SG_MODE 1

#define XAXICDMA_SIMPLE_MODE 2

Typedef Documentation

typedef void(* XAxiCdma_CallBackFn)(void *CallBackRef, u32 IrqMask, int *NumBdPtr)

Function Documentation

int XAxiCdma_BdRingAlloc	(	XAxiCdma *	InstancePtr,
		int	NumBd,
		XAxiCdma_Bd **	BdSetPtr
	)

This function requests number of BDs from the BD ring.

Parameters:

	InstancePtr	is the driver instance we are working on
	NumBd	is the number of BDs to request
	BdSetPtr	is the pointer to the set of BDs returned

Returns:

XST_SUCCESS for success
XST_INVALID_PARAM if requests non-positive number of BDs
XST_FAILURE if not enough free BDs available

Note:: None.

int XAxiCdma_BdRingClone	(	XAxiCdma *	InstancePtr,
		XAxiCdma_Bd *	TemplateBdPtr
	)

This function clones all BDs in the BD ring to be the same as the given BD.

Parameters:

	InstancePtr	is the driver instance we are working on
	TemplateBdPtr	is the BD to be copied from

Returns:

XST_SUCCESS for success
XST_DMA_SG_NO_LIST if there is no BD ring
XST_DEVICE_IS_STARTED if the hardware is running
XST_DMA_SG_LIST_ERROR is the BD ring is still in use

Note:: None.

int XAxiCdma_BdRingCntCalc	(	u32	Alignment,
		u32	Bytes,
		u32	BdBuffAddr
	)

This function calculates how many BDs can be built using given number of bytes of memory, according to alignment provided.

Parameters:

	Alignment	is the preferred alignment for the BDs
	Bytes	is the number of bytes of memory to build BDs with
	BdBuffAddr	is the buffer address allocated for the BDs. This is to check the alignment of the buffer to make sure the the buffer is aligned to the BD alignment. An invalid buffer address results in 0.

Returns:: The number of BDs can be built. 0 means buffer address is not valid.

Note:: The application is responsible to align the buffer before pass it to this function.

int XAxiCdma_BdRingCreate	(	XAxiCdma *	InstancePtr,
		u32	PhysAddr,
		u32	VirtAddr,
		u32	Alignment,
		int	BdCount
	)

This function creates the BD ring for the driver instance. If a BD ring pre-exist of this ring, the previous ring is lost.

Parameters:

	InstancePtr	is the driver instance we are working on
	PhysAddr	is the physical address of the memory for the BD ring
	VirtAddr	is the virtual address of the memory for the BD ring
	Alignment	is the alignment for the BDs
	BdCount	is the number of BDs to create in the ring

Returns:

XST_SUCCESS for success
XST_INVALID_PARAM for invalid parameter
XST_DMA_SG_LIST_ERROR for invalid memory region
XST_FAILURE if the hardware build is simple mode only

Note:: For a system that has flat memory layout, then the PhysAddr and the VirtAddr are the same.

int XAxiCdma_BdRingFree	(	XAxiCdma *	InstancePtr,
		int	NumBd,
		XAxiCdma_Bd *	BdSetPtr
	)

This function returns the BDs back to the free pool of the BD ring.

Parameters:

	InstancePtr	is the driver instance we are working on
	NumBd	is the number of BDs to free
	BdSetPtr	is the set of BDs to be freed

Returns:

XST_SUCCESS for success
XST_INVALID_PARAM if number of BDs is negative
XST_DMA_SG_LIST_ERROR if the BD ring management has a problem

Note:: None.

int XAxiCdma_BdRingFromHw	(	XAxiCdma *	InstancePtr,
		int	BdLimit,
		XAxiCdma_Bd **	BdSetPtr
	)

This function tries to retrieve completed BDs from the hardware.

Parameters:

	InstancePtr	is the driver instance we are working on
	BdLimit	is the maximum number of completed BDs to retrieve
	BdSetPtr	is the set of completed BDs

Returns:: The number of completed BDs.

Note:: None.

int XAxiCdma_BdRingGetCnt ( XAxiCdma * InstancePtr )

This function gets the total number of BDs in the BD ring.

Parameters:

InstancePtr

is the driver instance we are working on

Returns:: The total number of BDs for this instance

Note:: None.

XAxiCdma_Bd* XAxiCdma_BdRingGetCurrBd ( XAxiCdma * InstancePtr )

This function grabs a copy of the current BD pointer from the hardware.

Parameters:

InstancePtr

is the driver instance we are working on

Returns:: The BD pointer in CDESC register

Note:: None.

int XAxiCdma_BdRingGetFreeCnt ( XAxiCdma * InstancePtr )

This function gets the number of free BDs.

Parameters:

InstancePtr

is the driver instance we are working on

Returns:: The total number of free BDs for this instance

Note:: None.

int XAxiCdma_BdRingMemCalc	(	u32	Alignment,
		int	NumBd
	)

This function calculates how much memory is needed to build requested number of BDs.

Parameters:

	Alignment	is the preferred alignment for the BDs
	NumBd	is the number of BDs to be built

Returns:: The number of bytes of memory needed to build the BDs

Note:: None.

XAxiCdma_Bd* XAxiCdma_BdRingNext	(	XAxiCdma *	InstancePtr,
		XAxiCdma_Bd *	BdPtr
	)

This function gets the next BD of the current BD on the BD ring.

Parameters:

	InstancePtr	is the driver instance we are working on
	BdPtr	is the current BD

Returns:: The next BD on the ring from the current BD, NULL if passed in BdPtr not valid.

Note:: None.

XAxiCdma_Bd* XAxiCdma_BdRingPrev	(	XAxiCdma *	InstancePtr,
		XAxiCdma_Bd *	BdPtr
	)

This function gets the previous BD of the current BD on the BD ring.

Parameters:

	InstancePtr	is the driver instance we are working on
	BdPtr	is the current BD

Returns:: The previous BD on the ring from the current BD

Note:: None.

void XAxiCdma_BdRingSnapShotCurrBd ( XAxiCdma * InstancePtr )

This function grabs a copy of the current BD pointer from the hardware. It is normally used to prepare for the hardware reset. The snapshot of the current BD pointer should be reloaded once the reset is done.

Parameters:

InstancePtr

is the driver instance we are working on

Returns:: None

Note:: None.

int XAxiCdma_BdRingToHw	(	XAxiCdma *	InstancePtr,
		int	NumBd,
		XAxiCdma_Bd *	BdSetPtr,
		XAxiCdma_CallBackFn	CallBackFn,
		void *	CallBackRef
	)

This function tries to enqueue the number of BDs to the hardware.

Parameters:

	InstancePtr	is the driver instance we are working on
	NumBd	is the number of BDs to enqueue
	BdSetPtr	is the set of BDs to be enqueued
	CallBackFn	is the callback function for this transfer, NULL is fine
	CallBackRef	is the callback reference pointer

Returns:

XST_SUCCESS for success
XST_INVALID_PARAM if enqueues negative number of BDs or zero transfer len
XST_DMA_SG_LIST_ERROR if BD ring management has a problem
XST_FIFO_NO_ROOM if the interrupt handler array is full
XST_FAILURE for: Hardware is in invalid state, for example, reset failed Or, the hardware build is simple mode only

Note:: None.

int XAxiCdma_BdRingUnAlloc	(	XAxiCdma *	InstancePtr,
		int	NumBd,
		XAxiCdma_Bd *	BdSetPtr
	)

This function tries to free the number of BDs back to the ring.

Parameters:

	InstancePtr	is the driver instance we are working on
	NumBd	is the number of BDs to return
	BdSetPtr	is the set of BDs to be returned

Returns:

XST_SUCCESS for success
XST_INVALID_PARAM if to free non-positive number of BDs
XST_FAILURE if BD ring management shows an error

Note:: None.

int XAxiCdma_CfgInitialize	(	XAxiCdma *	InstancePtr,
		XAxiCdma_Config *	CfgPtr,
		u32	EffectiveAddr
	)

This function initializes the driver. It should be called before any other function calls to the driver.

It sets up the driver according to the hardware build. It resets the hardware at the end.

Parameters:

	InstancePtr	is the driver instance that is working on
	CfgPtr	is the pointer to the hardware configuration structure
	EffectiveAddr	is the virtual address of the hardware instance. If address translation is not in use, please use the physical address

Returns:

XST_SUCCESS for success
XST_INVALID_PARAM if word length is less than 4
XST_FAILURE for reset failure

Note:: None.

void XAxiCdma_DumpRegisters ( XAxiCdma * InstancePtr )

This function dumps the registers of this DMA instance

Parameters:

InstancePtr

is the driver instance we are working on

Returns:: None

Note:: None.

void XAxiCdma_GetCoalesce	(	XAxiCdma *	InstancePtr,
		u32 *	CounterPtr,
		u32 *	DelayPtr
	)

This function gets the current setting of the interrupt coalescing threshold counter and the delay counter.

Parameters:

	InstancePtr	is the driver instance we are working on
	CounterPtr	is the return value for the coalescing counter setting
	DelayPtr	is the return value for the delay counter setting

Returns:: A zero coalescing threshold indicates invalid results

Note:: None.

u32 XAxiCdma_GetError ( XAxiCdma * InstancePtr )

This function gets the status on error bits.

Parameters:

InstancePtr

is the driver instance we are working on

Returns:: The error bits in the status register. Zero indicates no errors.

Note:: None.

void XAxiCdma_IntrDisable	(	XAxiCdma *	InstancePtr,
		u32	Mask
	)

This function disables interrupts specified by the Mask. Interrupts that are not in the mask are not affected.

Parameters:

	InstancePtr	is the driver instance we are working on
	Mask	is the mask for the interrupts to be disabled

Returns:: None

Note:: None.

void XAxiCdma_IntrEnable	(	XAxiCdma *	InstancePtr,
		u32	Mask
	)

This function enables interrupts specified by the Mask. Interrupts that are not in the mask are not affected.

Parameters:

	InstancePtr	is the driver instance we are working on
	Mask	is the mask for the interrupts to be enabled

Returns:: None

Note:: None.

u32 XAxiCdma_IntrGetEnabled ( XAxiCdma * InstancePtr )

This function gets the mask for the interrupts that are currently enabled

Parameters:

InstancePtr

is the driver instance we are working on

Returns:: The bit mask for the interrupts that are currently enabled

Note:: None.

void XAxiCdma_IntrHandler ( void * HandlerRef )

This function is the interrupt handler for the driver, it handles all the interrupts. For the completion of a transfer that has a callback function, the callback function is called.

Parameters:

HandlerRef

is a reference pointer passed to the interrupt registration function. It will be a pointer to the driver instance we are working on

Returns:: None

Note:: If one transfer does not have all its submitted BDs completed successfully,then a reset is needed to clean up the mess left by that transfer.Otherwise, the wrong interrupt callback maybe called for the following transfers. However, if you always use the same interrupt callback for all the transfers, and you are the only user of the DMA engine, then you do not have to worry about this.

int XAxiCdma_IsBusy ( XAxiCdma * InstancePtr )

This function checks whether the hardware is doing transfer

Parameters:

InstancePtr

is the driver instance we are working on

Returns:

1 if the hardware is doing a transfer
0 if the hardware is idle

Note:: None.

XAxiCdma_Config* XAxiCdma_LookupConfig ( u32 DeviceId )

Look up the hardware configuration for a device instance

Parameters:

DeviceId

is the unique device ID of the device to lookup for

Returns:: The configuration structure for the device. If the device ID is not found,a NULL pointer is returned.

Note:: None.

void XAxiCdma_Reset ( XAxiCdma * InstancePtr )

This function conducts hardware reset

Current transfer will finish gracefully. However, all queued SG transfers that have not started will be flushed from the hardware.

Parameters:

InstancePtr

is the driver instance we are working on

Returns:: None

Note:: None.

int XAxiCdma_ResetIsDone ( XAxiCdma * InstancePtr )

This function checks whether the hardware reset is done

Parameters:

InstancePtr

is the driver instance we are working on

Returns:

1 if the reset has finished successfully
0 if the reset is not done

Note:: None.

int XAxiCdma_SelectKeyHole	(	XAxiCdma *	InstancePtr,
		u32	Direction,
		u32	Select
	)

This function configures KeyHole Write/Read Feature

Parameters:

	InstancePtr	is the driver instance we are working on
	Direction	is WRITE/READ Select is the option to enable (TRUE) or disable (FALSE).

Returns:

- XST_SUCCESS for success

XST_DEVICE_BUSY when transfer is in progress
XST_NO_FEATURE when not configured with feature

Note:: None.

int XAxiCdma_SetCoalesce	(	XAxiCdma *	InstancePtr,
		u32	Counter,
		u32	Delay
	)

This function tries to set the interrupt coalescing threshold counter and the delay counter. If to set only one of the counters, set the value of the other counter to be XAXICDMA_COALESCE_NO_CHANGE.

Parameters:

	InstancePtr	is the driver instance we are working on
	Counter	is the coalescing threshold to set to, the valid range is 1 to XAXICDMA_COALESCE_MAX.
	Delay	is the delay timeout counter to set to, the valid range is 0 to XAXICDMA_DELAY_MAX. Setting a value of 0 disables the delay interrupt.

Returns:

XST_SUCCESS for success
XST_FAILURE if hardware is in invalid state, for example, reset failed
XST_INVALID_PARAM if one of the counters is not in the valid range

Note:: None.

int XAxiCdma_SimpleTransfer	(	XAxiCdma *	InstancePtr,
		u32	SrcAddr,
		u32	DstAddr,
		int	Length,
		XAxiCdma_CallBackFn	SimpleCallBack,
		void *	CallBackRef
	)

This function does one simple transfer submission

It checks in the following sequence:

if engine is busy, cannot submit
if software is still handling the completion of the previous simple transfer, cannot submit
if engine is in SG mode and cannot switch to simple mode, cannot submit

Parameters:

	InstancePtr	is the pointer to the driver instance
	SrcAddr	is the address of the source buffer
	DstAddr	is the address of the destination buffer
	Length	is the length of the transfer
	SimpleCallBack	is the callback function for the simple transfer
	CallBackRef	is the callback reference pointer

Returns:

XST_SUCCESS for success of submission
XST_FAILURE for submission failure, maybe caused by: Another simple transfer is still going . Another SG transfer is still going
XST_INVALID_PARAM if: Length out of valid range [1:8M] Or, address not aligned when DRE is not built in

Note:: Only set the callback function if using interrupt to signal the completion.If used in polling mode, please set the callback function to be NULL.

Xilinx Processor IP Library

xaxicdma.h File Reference

Classes

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation