axidma
Xilinx SDK Drivers API Documentation
Axidma_v9_5

Data Structures

struct  XAxiDma
 The XAxiDma driver instance data. More...
 
struct  XAxiDma_Config
 The configuration structure for AXI DMA engine. More...
 

Macros

#define XAxiDma_GetTxRing(InstancePtr)   (&((InstancePtr)->TxBdRing))
 Get Transmit (Tx) Ring ptr. More...
 
#define XAxiDma_GetRxRing(InstancePtr)   (&((InstancePtr)->RxBdRing[0]))
 Get Receive (Rx) Ring ptr. More...
 
#define XAxiDma_GetRxIndexRing(InstancePtr, RingIndex)   (&((InstancePtr)->RxBdRing[RingIndex]))
 Get Receive (Rx) Ring ptr of a Index. More...
 
#define XAxiDma_HasSg(InstancePtr)   ((InstancePtr)->HasSg) ? TRUE : FALSE
 This function checks whether system is configured as Simple or Scatter Gather mode. More...
 
#define XAxiDma_IntrEnable(InstancePtr, Mask, Direction)
 This function enables interrupts specified by the Mask in specified direction, Interrupts that are not in the mask are not affected. More...
 
#define XAxiDma_IntrGetEnabled(InstancePtr, Direction)
 This function gets the mask for the interrupts that are currently enabled. More...
 
#define XAxiDma_IntrDisable(InstancePtr, Mask, Direction)
 This function disables interrupts specified by the Mask. More...
 
#define XAxiDma_IntrGetIrq(InstancePtr, Direction)
 This function gets the interrupts that are asserted. More...
 
#define XAxiDma_IntrAckIrq(InstancePtr, Mask, Direction)
 This function acknowledges the interrupts that are specified in Mask. More...
 

Typedefs

typedef struct XAxiDma XAxiDma
 The XAxiDma driver instance data. More...
 

Functions

XAxiDma_ConfigXAxiDma_LookupConfig (u32 DeviceId)
 Look up the hardware configuration for a device instance. More...
 
XAxiDma_ConfigXAxiDma_LookupConfigBaseAddr (u32 Baseaddr)
 Look up the hardware configuration for a device instance based on base address. More...
 
int XAxiDma_CfgInitialize (XAxiDma *InstancePtr, XAxiDma_Config *Config)
 This function initializes a DMA engine. More...
 
void XAxiDma_Reset (XAxiDma *InstancePtr)
 Reset both TX and RX channels of a DMA engine. More...
 
int XAxiDma_ResetIsDone (XAxiDma *InstancePtr)
 Check whether reset is done. More...
 
int XAxiDma_Pause (XAxiDma *InstancePtr)
 Pause DMA transactions on both channels. More...
 
int XAxiDma_Resume (XAxiDma *InstancePtr)
 Resume DMA transactions on both channels. More...
 
u32 XAxiDma_Busy (XAxiDma *InstancePtr, int Direction)
 This function checks whether specified DMA channel is busy. More...
 
u32 XAxiDma_SimpleTransfer (XAxiDma *InstancePtr, UINTPTR BuffAddr, u32 Length, int Direction)
 This function does one simple transfer submission. More...
 
int XAxiDma_SelectKeyHole (XAxiDma *InstancePtr, int Direction, int Select)
 This function Enable or Disable KeyHole Feature. More...
 
int XAxiDma_SelectCyclicMode (XAxiDma *InstancePtr, int Direction, int Select)
 This function Enable or Disable Cyclic Mode Feature. More...
 
int XAxiDma_Selftest (XAxiDma *InstancePtr)
 Runs a self-test on the driver/device. More...
 

Macro Definition Documentation

◆ XAxiDma_GetRxIndexRing

#define XAxiDma_GetRxIndexRing (   InstancePtr,
  RingIndex 
)    (&((InstancePtr)->RxBdRing[RingIndex]))

#include <xaxidma.h>

Get Receive (Rx) Ring ptr of a Index.

Warning: This has a different API than the LLDMA driver. It now returns the pointer to the BD ring.

Parameters
InstancePtris a pointer to the DMA engine instance to be worked on.
RingIndexis the channel Index.
Returns
Pointer to the Rx Ring
Note
C-style signature: XAxiDma_BdRing * XAxiDma_GetRxIndexRing(XAxiDma * InstancePtr, int RingIndex) This function is used only when system is configured as SG mode

Referenced by XAxiDma_Reset().

◆ XAxiDma_GetRxRing

#define XAxiDma_GetRxRing (   InstancePtr)    (&((InstancePtr)->RxBdRing[0]))

#include <xaxidma.h>

Get Receive (Rx) Ring ptr.

Warning: This has a different API than the LLDMA driver. It now returns the pointer to the BD ring.

Parameters
InstancePtris a pointer to the DMA engine instance to be worked on.
Returns
Pointer to the Rx Ring
Note
C-style signature: XAxiDma_BdRing * XAxiDma_GetRxRing(XAxiDma * InstancePtr) This function is used only when system is configured as SG mode

Referenced by XAxiDma_ResetIsDone().

◆ XAxiDma_GetTxRing

#define XAxiDma_GetTxRing (   InstancePtr)    (&((InstancePtr)->TxBdRing))

#include <xaxidma.h>

Get Transmit (Tx) Ring ptr.

Warning: This has a different API than the LLDMA driver. It now returns the pointer to the BD ring.

Parameters
InstancePtris a pointer to the DMA engine instance to be worked on.
Returns
Pointer to the Tx Ring
Note
C-style signature: XAxiDma_BdRing * XAxiDma_GetTxRing(XAxiDma * InstancePtr) This function is used only when system is configured as SG mode

Referenced by XAxiDma_Pause(), XAxiDma_Reset(), and XAxiDma_ResetIsDone().

◆ XAxiDma_HasSg

#define XAxiDma_HasSg (   InstancePtr)    ((InstancePtr)->HasSg) ? TRUE : FALSE

#include <xaxidma.h>

This function checks whether system is configured as Simple or Scatter Gather mode.

Parameters
InstancePtris a pointer to the DMA engine instance to be worked on.
Returns
  • TRUE if configured as SG mode
  • FALSE if configured as simple mode
Note
None

Referenced by XAxiDma_Pause(), XAxiDma_Reset(), and XAxiDma_SimpleTransfer().

◆ XAxiDma_IntrAckIrq

#define XAxiDma_IntrAckIrq (   InstancePtr,
  Mask,
  Direction 
)

#include <xaxidma.h>

Value:
XAxiDma_WriteReg((InstancePtr)->RegBase + \
#define XAXIDMA_IRQ_ALL_MASK
All interrupts.
Definition: xaxidma_hw.h:194
#define XAxiDma_WriteReg(BaseAddress, RegOffset, Data)
Write the given register.
Definition: xaxidma_hw.h:349
#define XAXIDMA_SR_OFFSET
Status.
Definition: xaxidma_hw.h:127
#define XAXIDMA_RX_OFFSET
RX channel registers base offset.
Definition: xaxidma_hw.h:118

This function acknowledges the interrupts that are specified in Mask.

Parameters
InstancePtris the driver instance we are working on
Maskis the mask for the interrupts to be acknowledge
Directionis DMA transfer direction, valid values are
  • XAXIDMA_DMA_TO_DEVICE.
  • XAXIDMA_DEVICE_TO_DMA.
Returns
None
Note
None.

◆ XAxiDma_IntrDisable

#define XAxiDma_IntrDisable (   InstancePtr,
  Mask,
  Direction 
)

#include <xaxidma.h>

Value:
XAxiDma_WriteReg((InstancePtr)->RegBase + \
(XAxiDma_ReadReg((InstancePtr)->RegBase + \
& ~(Mask & XAXIDMA_IRQ_ALL_MASK))
#define XAXIDMA_IRQ_ALL_MASK
All interrupts.
Definition: xaxidma_hw.h:194
#define XAxiDma_WriteReg(BaseAddress, RegOffset, Data)
Write the given register.
Definition: xaxidma_hw.h:349
#define XAXIDMA_CR_OFFSET
Channel control.
Definition: xaxidma_hw.h:126
#define XAxiDma_ReadReg(BaseAddress, RegOffset)
Read the given register.
Definition: xaxidma_hw.h:330
#define XAXIDMA_RX_OFFSET
RX channel registers base offset.
Definition: xaxidma_hw.h:118

This function disables interrupts specified by the Mask.

Interrupts that are not in the mask are not affected.

Parameters
InstancePtris the driver instance we are working on
Maskis the mask for the interrupts to be disabled
Directionis DMA transfer direction, valid values are
  • XAXIDMA_DMA_TO_DEVICE.
  • XAXIDMA_DEVICE_TO_DMA.
Returns
None
Note
None

◆ XAxiDma_IntrEnable

#define XAxiDma_IntrEnable (   InstancePtr,
  Mask,
  Direction 
)

#include <xaxidma.h>

Value:
XAxiDma_WriteReg((InstancePtr)->RegBase + \
(XAxiDma_ReadReg((InstancePtr)->RegBase + \
#define XAXIDMA_IRQ_ALL_MASK
All interrupts.
Definition: xaxidma_hw.h:194
#define XAxiDma_WriteReg(BaseAddress, RegOffset, Data)
Write the given register.
Definition: xaxidma_hw.h:349
#define XAXIDMA_CR_OFFSET
Channel control.
Definition: xaxidma_hw.h:126
#define XAxiDma_ReadReg(BaseAddress, RegOffset)
Read the given register.
Definition: xaxidma_hw.h:330
#define XAXIDMA_RX_OFFSET
RX channel registers base offset.
Definition: xaxidma_hw.h:118

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

Parameters
InstancePtris the driver instance we are working on
Maskis the mask for the interrupts to be enabled
Directionis DMA transfer direction, valid values are
  • XAXIDMA_DMA_TO_DEVICE.
  • XAXIDMA_DEVICE_TO_DMA.
Returns
None
Note
None

◆ XAxiDma_IntrGetEnabled

#define XAxiDma_IntrGetEnabled (   InstancePtr,
  Direction 
)

#include <xaxidma.h>

Value:
XAxiDma_ReadReg((InstancePtr)->RegBase + \
XAXIDMA_IRQ_ALL_MASK)
#define XAXIDMA_CR_OFFSET
Channel control.
Definition: xaxidma_hw.h:126
#define XAxiDma_ReadReg(BaseAddress, RegOffset)
Read the given register.
Definition: xaxidma_hw.h:330
#define XAXIDMA_RX_OFFSET
RX channel registers base offset.
Definition: xaxidma_hw.h:118

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

Parameters
InstancePtris the driver instance we are working on
Directionis DMA transfer direction, valid values are
  • XAXIDMA_DMA_TO_DEVICE.
  • XAXIDMA_DEVICE_TO_DMA.
Returns
The bit mask for the interrupts that are currently enabled
Note
None

◆ XAxiDma_IntrGetIrq

#define XAxiDma_IntrGetIrq (   InstancePtr,
  Direction 
)

#include <xaxidma.h>

Value:
(XAxiDma_ReadReg((InstancePtr)->RegBase + \
XAXIDMA_IRQ_ALL_MASK)
#define XAXIDMA_SR_OFFSET
Status.
Definition: xaxidma_hw.h:127
#define XAxiDma_ReadReg(BaseAddress, RegOffset)
Read the given register.
Definition: xaxidma_hw.h:330
#define XAXIDMA_RX_OFFSET
RX channel registers base offset.
Definition: xaxidma_hw.h:118

This function gets the interrupts that are asserted.

Parameters
InstancePtris the driver instance we are working on
Directionis DMA transfer direction, valid values are
  • XAXIDMA_DMA_TO_DEVICE.
  • XAXIDMA_DEVICE_TO_DMA.
Returns
The bit mask for the interrupts asserted.
Note
None

Typedef Documentation

◆ XAxiDma

typedef struct XAxiDma XAxiDma

#include <xaxidma.h>

The XAxiDma driver instance data.

An instance must be allocated for each DMA engine in use.

Function Documentation

◆ XAxiDma_Busy()

u32 XAxiDma_Busy ( XAxiDma InstancePtr,
int  Direction 
)

#include <xaxidma.h>

This function checks whether specified DMA channel is busy.

Parameters
InstancePtris the driver instance we are working on
Directionis DMA transfer direction, valid values are
  • XAXIDMA_DMA_TO_DEVICE.
  • XAXIDMA_DEVICE_TO_DMA.
Returns
- TRUE if channel is busy
  • FALSE if channel is idle
Note
None.

References XAXIDMA_IDLE_MASK, XAxiDma_ReadReg, XAXIDMA_RX_OFFSET, and XAXIDMA_SR_OFFSET.

◆ XAxiDma_CfgInitialize()

int XAxiDma_CfgInitialize ( XAxiDma InstancePtr,
XAxiDma_Config Config 
)

#include <xaxidma.h>

This function initializes a DMA engine.

This function must be called prior to using a DMA engine. Initializing a engine includes setting up the register base address, setting up the instance data, and ensuring the hardware is in a quiescent state.

Parameters
InstancePtris a pointer to the DMA engine instance to be worked on.
Configis a pointer to an XAxiDma_Config structure. It contains the information about the hardware build, including base address,and whether status control stream (StsCntrlStrm), MM2S and S2MM are included in the build.
Returns
  • XST_SUCCESS for successful initialization
  • XST_INVALID_PARAM if pointer to the configuration structure is NULL
  • XST_DMA_ERROR if reset operation failed at the end of initialization
Note
We assume the hardware building tool will check and error out for a hardware build that has no transfer channels.

References XAxiDma::AddrWidth, and XAxiDma_Config::AddrWidth.

Referenced by AxiDMASelfTestExample().

◆ XAxiDma_LookupConfig()

XAxiDma_Config* XAxiDma_LookupConfig ( u32  DeviceId)

#include <xaxidma.h>

Look up the hardware configuration for a device instance.

Parameters
DeviceIdis 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

Referenced by AxiDMASelfTestExample().

◆ XAxiDma_LookupConfigBaseAddr()

XAxiDma_Config* XAxiDma_LookupConfigBaseAddr ( u32  Baseaddr)

#include <xaxidma.h>

Look up the hardware configuration for a device instance based on base address.

Parameters
Baseaddris the base address of the device to lookup for
Returns
The configuration structure for the device. If the device base address is not found,a NULL pointer is returned.
Note
None

◆ XAxiDma_Pause()

int XAxiDma_Pause ( XAxiDma InstancePtr)

#include <xaxidma.h>

Pause DMA transactions on both channels.

If the engine is running and doing transfers, this function does not stop the DMA transactions immediately, because then hardware will throw away our previously queued transfers. All submitted transfers will finish. Transfers submitted after this function will not start until XAxiDma_BdRingStart() or XAxiDma_Resume() is called.

Parameters
InstancePtris a pointer to the DMA engine instance to be worked on.
Returns
  • XST_SUCCESS if successful
  • XST_NOT_SGDMA, if the driver instance is not initialized
Note
None

References XAxiDma_BdRing::ChanBase, XAxiDma_BdRing::RunState, XAXIDMA_CR_OFFSET, XAXIDMA_CR_RUNSTOP_MASK, XAxiDma_GetTxRing, XAxiDma_HasSg, XAxiDma_ReadReg, and XAxiDma_WriteReg.

◆ XAxiDma_Reset()

void XAxiDma_Reset ( XAxiDma InstancePtr)

#include <xaxidma.h>

Reset both TX and RX channels of a DMA engine.

Reset one channel resets the whole AXI DMA engine.

Any DMA transaction in progress will finish gracefully before engine starts reset. Any other transactions that have been submitted to hardware will be discarded by the hardware.

Parameters
InstancePtris a pointer to the DMA engine instance to be worked on.
Returns
None
Note
After the reset:
  • All interrupts are disabled.
  • Engine is halted

References XAxiDma_BdRing::RunState, XAxiDma_BdRingSnapShotCurrBd, XAXIDMA_CR_OFFSET, XAXIDMA_CR_RESET_MASK, XAxiDma_GetRxIndexRing, XAxiDma_GetTxRing, XAxiDma_HasSg, XAXIDMA_RX_OFFSET, XAXIDMA_TX_OFFSET, and XAxiDma_WriteReg.

Referenced by XAxiDma_Selftest().

◆ XAxiDma_ResetIsDone()

int XAxiDma_ResetIsDone ( XAxiDma InstancePtr)

#include <xaxidma.h>

Check whether reset is done.

Parameters
InstancePtris a pointer to the DMA engine instance to be worked on.
Returns
  • 1 if reset is done.
  • 0 if reset is not done
Note
None

References XAxiDma_BdRing::ChanBase, XAXIDMA_CR_OFFSET, XAXIDMA_CR_RESET_MASK, XAxiDma_GetRxRing, XAxiDma_GetTxRing, and XAxiDma_ReadReg.

◆ XAxiDma_Resume()

int XAxiDma_Resume ( XAxiDma InstancePtr)

#include <xaxidma.h>

Resume DMA transactions on both channels.

Parameters
InstancePtris a pointer to the DMA engine instance to be worked on.
Returns
  • XST_SUCCESS for success
  • XST_NOT_SGDMA if the driver instance has not been initialized
  • XST_DMA_ERROR if one of the channels fails to start
Note
None

◆ XAxiDma_SelectCyclicMode()

int XAxiDma_SelectCyclicMode ( XAxiDma InstancePtr,
int  Direction,
int  Select 
)

#include <xaxidma.h>

This function Enable or Disable Cyclic Mode Feature.

Parameters
InstancePtris the driver instance we are working on
Directionis DMA transfer direction, valid values are
  • XAXIDMA_DMA_TO_DEVICE.
  • XAXIDMA_DEVICE_TO_DMA. Select is the option to enable (TRUE) or disable (FALSE).
Returns
- XST_SUCCESS for success
Note
None.

References XAXIDMA_CR_CYCLIC_MASK, XAXIDMA_CR_OFFSET, XAxiDma_ReadReg, XAXIDMA_RX_OFFSET, and XAxiDma_WriteReg.

◆ XAxiDma_SelectKeyHole()

int XAxiDma_SelectKeyHole ( XAxiDma InstancePtr,
int  Direction,
int  Select 
)

#include <xaxidma.h>

This function Enable or Disable KeyHole Feature.

Parameters
InstancePtris the driver instance we are working on
Directionis DMA transfer direction, valid values are
  • XAXIDMA_DMA_TO_DEVICE.
  • XAXIDMA_DEVICE_TO_DMA. Select is the option to enable (TRUE) or disable (FALSE).
Returns
- XST_SUCCESS for success
Note
None.

References XAXIDMA_CR_KEYHOLE_MASK, XAXIDMA_CR_OFFSET, XAxiDma_ReadReg, XAXIDMA_RX_OFFSET, and XAxiDma_WriteReg.

◆ XAxiDma_Selftest()

int XAxiDma_Selftest ( XAxiDma InstancePtr)

#include <xaxidma.h>

Runs a self-test on the driver/device.

This test perform a reset of the DMA device and checks the device is coming out of reset or not

Parameters
InstancePtris a pointer to the XAxiDma instance.
Returns
  • XST_SUCCESS if self-test was successful
  • XST_FAILURE if the device is not coming out of reset.
Note
None.

References XAxiDma_Reset().

Referenced by AxiDMASelfTestExample().

◆ XAxiDma_SimpleTransfer()

u32 XAxiDma_SimpleTransfer ( XAxiDma InstancePtr,
UINTPTR  BuffAddr,
u32  Length,
int  Direction 
)

#include <xaxidma.h>

This function does one simple transfer submission.

It checks in the following sequence:

  • if engine is busy, cannot submit
  • if engine is in SG mode , cannot submit
Parameters
InstancePtris the pointer to the driver instance
BuffAddris the address of the source/destination buffer
Lengthis the length of the transfer
Directionis DMA transfer direction, valid values are
  • XAXIDMA_DMA_TO_DEVICE.
  • XAXIDMA_DEVICE_TO_DMA.
Returns
  • XST_SUCCESS for success of submission
  • XST_FAILURE for submission failure, maybe caused by: Another simple 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
This function is used only when system is configured as Simple mode.

References XAxiDma_HasSg.