csudma
Xilinx SDK Drivers API Documentation
xcsudma.h File Reference

Overview

The CSU_DMA is present inside CSU (Configuration Security Unit) module which is located within the Low-Power Subsystem (LPS) internal to the PS.

CSU_DMA allows the CSU to move data efficiently between the memory (32 bit AXI interface) and the CSU stream peripherals (SHA, AES and PCAP) via Secure Stream Switch (SSS).

The CSU_DMA is a 2 channel simple DMA, allowing separate control of the SRC (read) channel and DST (write) channel. The DMA is effectively able to transfer data:

  • From PS-side to the SSS-side (SRC DMA only)
  • From SSS-side to the PS-side (DST DMA only)
  • Simultaneous PS-side to SSS_side and SSS-side to the PS-side

Initialization & Configuration

The device driver enables higher layer software (e.g., an application) to communicate to the CSU_DMA core.

XCsuDma_CfgInitialize() API is used to initialize the CSU_DMA core. The user needs to first call the XCsuDma_LookupConfig() API which returns the Configuration structure pointer which is passed as a parameter to the XCsuDma_CfgInitialize() API.

Reset This driver will not support handling of CRP PDMA Reset in case of PMCDMA inorder to support multiple level of handoff's. User needs to call the XCsuDma_PmcReset() API before performing any driver operation to make sure PMCDMA is in proper state.

Interrupts This driver will not support handling of interrupts user should write handler to handle the interrupts.

Virtual Memory

This driver supports Virtual Memory. The RTOS is responsible for calculating the correct device base address in Virtual Memory space.

Threads

This driver is not thread safe. Any needs for threads or thread mutual exclusion must be satisfied by the layer above this driver.

Asserts

Asserts are used within all Xilinx drivers to enforce constraints on argument values. Asserts can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier. By default, asserts are turned on and it is recommended that users leave asserts on during development.

Building the driver

The XCsuDma driver is composed of several source files. This allows the user to build and link only those parts of the driver that are necessary.

Data Structures

struct  XCsuDma_Config
 This typedef contains configuration information for a CSU_DMA core. More...
 
struct  XCsuDma
 The XCsuDma driver instance data structure. More...
 
struct  XCsuDma_Configure
 This typedef contains all the configuration feilds which needs to be set before the start of the data transfer. More...
 

Macros

#define XCSUDMA_H_
 Prevent circular inclusions by using protection macros. More...
 
#define XCsuDma_Reset()
 This function resets the CSU_DMA core. More...
 
#define XCsuDma_WaitForDone(InstancePtr, Channel)
 This function will be in busy while loop until the data transfer is completed. More...
 
#define XCsuDma_GetDoneCount(InstancePtr, Channel)
 This function returns the number of completed SRC/DST DMA transfers that have not been acknowledged by software based on the channel selection. More...
 
#define XCsuDma_GetFIFOLevel(InstancePtr, Channel)
 This function returns the current SRC/DST FIFO level in 32 bit words of the selected channel. More...
 
#define XCsuDma_GetWROutstandCount(InstancePtr, Channel)
 This function returns the current number of read(src)/write(dst) outstanding commands based on the type of channel selected. More...
 
#define XCsuDma_IsBusy(InstancePtr, Channel)
 This function returns the status of Channel either it is busy or not. More...
 
Ranges of Size
#define XCSUDMA_SIZE_MAX   0x07FFFFFFU
 Maximum allowed no of words. More...
 
#define XCSUDMA_DMATYPEIS_CSUDMA   0U
 
#define XCSUDMA_DMATYPEIS_PMCDMA0   1U
 
#define XCSUDMA_DMATYPEIS_PMCDMA1   2U
 

Enumerations

enum  XCsuDma_Channel { XCSUDMA_SRC_CHANNEL = 0U, XCSUDMA_DST_CHANNEL }
 This typedef contains CSU_DMA Channel Types. More...
 
enum  XCsuDma_PauseType { XCSUDMA_PAUSE_MEMORY, XCSUDMA_PAUSE_STREAM }
 This typedef contains CSU_DMA Pause Types. More...
 

Functions

XCsuDma_ConfigXCsuDma_LookupConfig (u16 DeviceId)
 XCsuDma_LookupConfig returns a reference to an XCsuDma_Config structure based on the unique device id, DeviceId. More...
 
s32 XCsuDma_CfgInitialize (XCsuDma *InstancePtr, XCsuDma_Config *CfgPtr, u32 EffectiveAddr)
 This function initializes an CSU_DMA core. More...
 
void XCsuDma_Transfer (XCsuDma *InstancePtr, XCsuDma_Channel Channel, UINTPTR Addr, u32 Size, u8 EnDataLast)
 This function sets the starting address and amount(size) of the data to be transfered from/to the memory through the AXI interface. More...
 
void XCsuDma_64BitTransfer (XCsuDma *InstancePtr, XCsuDma_Channel Channel, u32 AddrLow, u32 AddrHigh, u32 Size, u8 EnDataLast)
 This function sets the starting address and amount(size) of the data to be transfered from/to the memory through the AXI interface. More...
 
u64 XCsuDma_GetAddr (XCsuDma *InstancePtr, XCsuDma_Channel Channel)
 This function returns the current address location of the memory, from where it has to read the data(SRC) or the location where it has to write the data (DST) based on the channel selection. More...
 
u32 XCsuDma_GetSize (XCsuDma *InstancePtr, XCsuDma_Channel Channel)
 This function returns the size of the data yet to be transfered from memory to CSU_DMA or CSU_DMA to memory based on the channel selection. More...
 
void XCsuDma_Pause (XCsuDma *InstancePtr, XCsuDma_Channel Channel, XCsuDma_PauseType Type)
 This function pause the Channel data tranfer to/from memory or to/from stream based on pause type. More...
 
s32 XCsuDma_IsPaused (XCsuDma *InstancePtr, XCsuDma_Channel Channel, XCsuDma_PauseType Type)
 This functions checks whether Channel's memory or stream is paused or not based on the given pause type. More...
 
void XCsuDma_Resume (XCsuDma *InstancePtr, XCsuDma_Channel Channel, XCsuDma_PauseType Type)
 This function resumes the channel if it is in paused state and continues where it has left or no effect if it is not in paused state, based on the type of pause. More...
 
u32 XCsuDma_GetCheckSum (XCsuDma *InstancePtr)
 This function returns the sum of all the data read from AXI memory. More...
 
void XCsuDma_ClearCheckSum (XCsuDma *InstancePtr)
 This function clears the check sum of the data read from AXI memory. More...
 
void XCsuDma_SetConfig (XCsuDma *InstancePtr, XCsuDma_Channel Channel, XCsuDma_Configure *ConfigurValues)
 This function cofigures all the values of CSU_DMA's Channels with the values of updated XCsuDma_Configure structure. More...
 
void XCsuDma_GetConfig (XCsuDma *InstancePtr, XCsuDma_Channel Channel, XCsuDma_Configure *ConfigurValues)
 This function updates XCsuDma_Configure structure members with the cofigured values of CSU_DMA's Channel. More...
 
u32 XCsuDma_WaitForDoneTimeout (XCsuDma *InstancePtr, XCsuDma_Channel Channel)
 This function will poll for completion of data transfer periodically until DMA done bit set or till the timeout occurs. More...
 
u32 XCsuDma_IntrGetStatus (XCsuDma *InstancePtr, XCsuDma_Channel Channel)
 This function returns interrupt status read from Interrupt Status Register. More...
 
void XCsuDma_IntrClear (XCsuDma *InstancePtr, XCsuDma_Channel Channel, u32 Mask)
 This function clears interrupt(s). More...
 
void XCsuDma_EnableIntr (XCsuDma *InstancePtr, XCsuDma_Channel Channel, u32 Mask)
 This function enables the interrupt(s). More...
 
void XCsuDma_DisableIntr (XCsuDma *InstancePtr, XCsuDma_Channel Channel, u32 Mask)
 This function disables the interrupt(s). More...
 
u32 XCsuDma_GetIntrMask (XCsuDma *InstancePtr, XCsuDma_Channel Channel)
 This function returns the interrupt mask to know which interrupts are enabled and which of them were disaled. More...
 
s32 XCsuDma_SelfTest (XCsuDma *InstancePtr)
 This function runs a self-test on the driver and hardware device. More...
 

Macro Definition Documentation

#define XCsuDma_GetDoneCount (   InstancePtr,
  Channel 
)
Value:
((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
((u32)(XCSUDMA_STS_OFFSET) + \
((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
#define XCSUDMA_STS_OFFSET
Status Register Offset.
Definition: xcsudma_hw.h:66
#define XCSUDMA_STS_DONE_CNT_SHIFT
Shift for Count done.
Definition: xcsudma_hw.h:150
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
#define XCSUDMA_STS_DONE_CNT_MASK
Count done mask.
Definition: xcsudma_hw.h:142
#define XCsuDma_ReadReg(BaseAddress, RegOffset)
This macro reads the given register.
Definition: xcsudma_hw.h:339

This function returns the number of completed SRC/DST DMA transfers that have not been acknowledged by software based on the channel selection.

Parameters
InstancePtris a pointer to XCsuDma instance to be worked on.
Channelrepresents the type of channel either it is Source or Destination. Source channel - XCSUDMA_SRC_CHANNEL Destination Channel - XCSUDMA_DST_CHANNEL
Returns
Count is number of completed DMA transfers but not acknowledged (Range is 0 to 7).
  • 000 - All finished transfers have been acknowledged.
  • Count - Count number of finished transfers are still outstanding.
Note
None. C-style signature: u8 XCsuDma_GetDoneCount(XCsuDma *InstancePtr, XCsuDma_Channel Channel)
#define XCsuDma_GetFIFOLevel (   InstancePtr,
  Channel 
)
Value:
((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
((u32)(XCSUDMA_STS_OFFSET) + \
((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
#define XCSUDMA_STS_OFFSET
Status Register Offset.
Definition: xcsudma_hw.h:66
#define XCSUDMA_STS_FIFO_LEVEL_MASK
FIFO level mask.
Definition: xcsudma_hw.h:143
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
#define XCSUDMA_STS_FIFO_LEVEL_SHIFT
Shift for FIFO level.
Definition: xcsudma_hw.h:153
#define XCsuDma_ReadReg(BaseAddress, RegOffset)
This macro reads the given register.
Definition: xcsudma_hw.h:339

This function returns the current SRC/DST FIFO level in 32 bit words of the selected channel.

Parameters
InstancePtris a pointer to XCsuDma instance to be worked on.
Channelrepresents the type of channel either it is Source or Destination. Source channel - XCSUDMA_SRC_CHANNEL Destination Channel - XCSUDMA_DST_CHANNEL
Returns
FIFO level. (Range is 0 to 128)
  • 0 Indicates empty
  • Any number 1 to 128 indicates the number of entries in FIFO.
Note
None. C-style signature: u8 XCsuDma_GetFIFOLevel(XCsuDma *InstancePtr, XCsuDma_Channel Channel)
#define XCsuDma_GetWROutstandCount (   InstancePtr,
  Channel 
)
Value:
((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
((u32)(XCSUDMA_STS_OFFSET) + \
((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
#define XCSUDMA_STS_OFFSET
Status Register Offset.
Definition: xcsudma_hw.h:66
#define XCUSDMA_STS_OUTSTDG_SHIFT
Shift for No.of outstanding read/write commands.
Definition: xcsudma_hw.h:156
#define XCUSDMA_STS_OUTSTDG_MASK
No.of outstanding read/write commands mask.
Definition: xcsudma_hw.h:144
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
#define XCsuDma_ReadReg(BaseAddress, RegOffset)
This macro reads the given register.
Definition: xcsudma_hw.h:339

This function returns the current number of read(src)/write(dst) outstanding commands based on the type of channel selected.

Parameters
InstancePtris a pointer to XCsuDma instance to be worked on.
Channelrepresents the type of channel either it is Source or Destination. Source channel - XCSUDMA_SRC_CHANNEL Destination Channel - XCSUDMA_DST_CHANNEL
Returns
Count of outstanding commands. (Range is 0 to 9).
Note
None. C-style signature: u8 XCsuDma_GetWROutstandCount(XCsuDma *InstancePtr, XCsuDma_Channel Channel)
#define XCsuDma_IsBusy (   InstancePtr,
  Channel 
)
Value:
((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
((u32)(XCSUDMA_STS_OFFSET) + \
((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
(TRUE) : (FALSE)
#define XCSUDMA_STS_OFFSET
Status Register Offset.
Definition: xcsudma_hw.h:66
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
#define XCSUDMA_STS_BUSY_MASK
Busy mask.
Definition: xcsudma_hw.h:149
#define XCsuDma_ReadReg(BaseAddress, RegOffset)
This macro reads the given register.
Definition: xcsudma_hw.h:339

This function returns the status of Channel either it is busy or not.

Parameters
InstancePtris a pointer to XCsuDma instance to be worked on.
Channelrepresents the type of channel either it is Source or Destination. Source channel - XCSUDMA_SRC_CHANNEL Destination Channel - XCSUDMA_DST_CHANNEL
Returns
Returns the current status of the core.
  • TRUE represents core is currently busy.
  • FALSE represents core is not involved in any transfers.
Note
None. C-style signature: s32 XCsuDma_IsBusy(XCsuDma *InstancePtr, XCsuDma_Channel Channel)

Referenced by XCsuDma_SetConfig().

#define XCsuDma_Reset ( )
Value:
Xil_Out32(((u32)(XCSU_BASEADDRESS) + (u32)(XCSU_DMA_RESET_OFFSET)), \
Xil_Out32(((u32)(XCSU_BASEADDRESS) + (u32)(XCSU_DMA_RESET_OFFSET)), \
#define XCSUDMA_RESET_UNSET_MASK
Reset unset mask.
Definition: xcsudma_hw.h:109
#define XCSUDMA_RESET_SET_MASK
Reset set mask.
Definition: xcsudma_hw.h:108
#define XCSU_DMA_RESET_OFFSET
CSU_DMA Reset offset.
Definition: xcsudma_hw.h:92
#define XCSU_BASEADDRESS
CSU Base Address.
Definition: xcsudma_hw.h:90

This function resets the CSU_DMA core.

Returns
None.
Note
None. C-style signature: void XCsuDma_Reset()

Referenced by XCsuDma_CfgInitialize().

#define XCSUDMA_SIZE_MAX   0x07FFFFFFU

Maximum allowed no of words.

Referenced by XCsuDma_64BitTransfer(), and XCsuDma_Transfer().

#define XCsuDma_WaitForDone (   InstancePtr,
  Channel 
)
Value:
while((XCsuDma_ReadReg(((InstancePtr)->Config.BaseAddress), \
((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
#define XCSUDMA_IXR_DONE_MASK
Done mask.
Definition: xcsudma_hw.h:247
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
#define XCSUDMA_I_STS_OFFSET
Interrupt Status Register Offset.
Definition: xcsudma_hw.h:69
#define XCsuDma_ReadReg(BaseAddress, RegOffset)
This macro reads the given register.
Definition: xcsudma_hw.h:339

This function will be in busy while loop until the data transfer is completed.

Parameters
InstancePtris a pointer to XCsuDma instance to be worked on.
Channelrepresents the type of channel either it is Source or Destination. Source channel - XCSUDMA_SRC_CHANNEL Destination Channel - XCSUDMA_DST_CHANNEL
Returns
None.
Note
This function should be called after XCsuDma_Transfer in polled mode to wait until the data gets transfered completely. C-style signature: void XCsuDma_WaitForDone(XCsuDma *InstancePtr, XCsuDma_Channel Channel)

Enumeration Type Documentation

This typedef contains CSU_DMA Pause Types.

Enumerator
XCSUDMA_PAUSE_MEMORY 

Pauses memory data transfer to/from CSU_DMA.

XCSUDMA_PAUSE_STREAM 

Pauses stream data transfer to/from CSU_DMA.