csudma: xcsudma.h File Reference

| csudma Xilinx SDK Drivers API Documentation

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

Data Structures | Macros | Enumerations | Functions
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_Config * | XCsuDma_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)))) & \
(u32)(XCSUDMA_STS_DONE_CNT_MASK)) >> \
(u32)(XCSUDMA_STS_DONE_CNT_SHIFT))
XCSUDMA_STS_OFFSET
#define XCSUDMA_STS_OFFSET
Status Register Offset.
Definition: xcsudma_hw.h:66
XCSUDMA_STS_DONE_CNT_SHIFT
#define XCSUDMA_STS_DONE_CNT_SHIFT
Shift for Count done.
Definition: xcsudma_hw.h:150
XCSUDMA_OFFSET_DIFF
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
XCSUDMA_STS_DONE_CNT_MASK
#define XCSUDMA_STS_DONE_CNT_MASK
Count done mask.
Definition: xcsudma_hw.h:142
XCsuDma_ReadReg
#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

  InstancePtr | is a pointer to XCsuDma instance to be worked on.
  Channel | represents 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)))) & \
(u32)(XCSUDMA_STS_FIFO_LEVEL_MASK)) >> \
(u32)(XCSUDMA_STS_FIFO_LEVEL_SHIFT))
XCSUDMA_STS_OFFSET
#define XCSUDMA_STS_OFFSET
Status Register Offset.
Definition: xcsudma_hw.h:66
XCSUDMA_STS_FIFO_LEVEL_MASK
#define XCSUDMA_STS_FIFO_LEVEL_MASK
FIFO level mask.
Definition: xcsudma_hw.h:143
XCSUDMA_OFFSET_DIFF
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
XCSUDMA_STS_FIFO_LEVEL_SHIFT
#define XCSUDMA_STS_FIFO_LEVEL_SHIFT
Shift for FIFO level.
Definition: xcsudma_hw.h:153
XCsuDma_ReadReg
#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

  InstancePtr | is a pointer to XCsuDma instance to be worked on.
  Channel | represents 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)))) & \
(u32)(XCUSDMA_STS_OUTSTDG_MASK)) >> \
(u32)(XCUSDMA_STS_OUTSTDG_SHIFT))
XCSUDMA_STS_OFFSET
#define XCSUDMA_STS_OFFSET
Status Register Offset.
Definition: xcsudma_hw.h:66
XCUSDMA_STS_OUTSTDG_SHIFT
#define XCUSDMA_STS_OUTSTDG_SHIFT
Shift for No.of outstanding read/write commands.
Definition: xcsudma_hw.h:156
XCUSDMA_STS_OUTSTDG_MASK
#define XCUSDMA_STS_OUTSTDG_MASK
No.of outstanding read/write commands mask.
Definition: xcsudma_hw.h:144
XCSUDMA_OFFSET_DIFF
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
XCsuDma_ReadReg
#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

  InstancePtr | is a pointer to XCsuDma instance to be worked on.
  Channel | represents 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)))) & \
(u32)(XCSUDMA_STS_BUSY_MASK)) == (XCSUDMA_STS_BUSY_MASK)) ? \
(TRUE) : (FALSE)
XCSUDMA_STS_OFFSET
#define XCSUDMA_STS_OFFSET
Status Register Offset.
Definition: xcsudma_hw.h:66
XCSUDMA_OFFSET_DIFF
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
XCSUDMA_STS_BUSY_MASK
#define XCSUDMA_STS_BUSY_MASK
Busy mask.
Definition: xcsudma_hw.h:149
XCsuDma_ReadReg
#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

  InstancePtr | is a pointer to XCsuDma instance to be worked on.
  Channel | represents 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)), \
(u32)(XCSUDMA_RESET_SET_MASK)); \
Xil_Out32(((u32)(XCSU_BASEADDRESS) + (u32)(XCSU_DMA_RESET_OFFSET)), \
(u32)(XCSUDMA_RESET_UNSET_MASK));
XCSUDMA_RESET_UNSET_MASK
#define XCSUDMA_RESET_UNSET_MASK
Reset unset mask.
Definition: xcsudma_hw.h:109
XCSUDMA_RESET_SET_MASK
#define XCSUDMA_RESET_SET_MASK
Reset set mask.
Definition: xcsudma_hw.h:108
XCSU_DMA_RESET_OFFSET
#define XCSU_DMA_RESET_OFFSET
CSU_DMA Reset offset.
Definition: xcsudma_hw.h:92
XCSU_BASEADDRESS
#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)(XCSUDMA_I_STS_OFFSET) + \
((u32)(Channel) * (u32)(XCSUDMA_OFFSET_DIFF)))) & \
(u32)(XCSUDMA_IXR_DONE_MASK)) != (XCSUDMA_IXR_DONE_MASK))
XCSUDMA_IXR_DONE_MASK
#define XCSUDMA_IXR_DONE_MASK
Done mask.
Definition: xcsudma_hw.h:247
XCSUDMA_OFFSET_DIFF
#define XCSUDMA_OFFSET_DIFF
Offset difference for source and destination channels.
Definition: xcsudma_hw.h:115
XCSUDMA_I_STS_OFFSET
#define XCSUDMA_I_STS_OFFSET
Interrupt Status Register Offset.
Definition: xcsudma_hw.h:69
XCsuDma_ReadReg
#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

  InstancePtr | is a pointer to XCsuDma instance to be worked on.
  Channel | represents 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

enum XCsuDma_PauseType

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.