CSUDMA Standalone driver

Table of Contents

Introduction

This page gives an overview of CSUDMA driver which is available as part of the Xilinx Vivado and Vitis distribution. CSUDMA provides an efficient data transfer mechanism between the PSS's Memory and the CSU Stream Peripherals.

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

On Versal it is known as PMCDMA and present in PMC (used for Platform Management). CSUDMA is used interchangeably for PMCDMA in this documentation and driver unless specified.
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

For more information, please refer to CSUDMA chapter in ZynqMP TRM (UG1085) or PMCDMA chapter in Versal TRM (AM011).

Driver Sources

The source code for the driver is included with the Vitis Unified Software Platform installation, as well as being available in the Xilinx Github repository. 

Driver Name

Path in Vitis

Path in Github

emapcs

<Vitis Install Directory>/data/embedded/XilinxProcessorIPLib/drivers/csudma

https://github.com/Xilinx/embeddedsw/tree/master/XilinxProcessorIPLib/drivers/csudma


Note: To view the sources for a particular release, use the rel-version tag in github.  For example, for the 2020.1 release, the proper version of the code is: https://github.com/Xilinx/embeddedsw/tree/xilinx_v2021.1/XilinxProcessorIPLib/drivers/csudma


The driver source code is organized into different folders.  The table below shows the csudma driver source organization. 

Directory

Description

doc

Provides the API and data structure details

data

Driver .tcl and .mdd file

examples

Example applications that show how to use the driver features

src

Driver source files

Driver Implementation

For a full list of features supported by this IP, please refer to CSUDMA chapter in ZynqMP TRM (UG1085) or PMCDMA chapter in Versal TRM (AM011) for respective devices.

Features

Controller/Driver features supported

  • Simple DMA, no scatter-gather

  • Separate read channel (SRC) and write channel(DST) DMA

  • Read channel fetches data from the PS-side(memory) and delivers it to the CSU secure stream switch (SSS) interface

  • Write channel receives data from the CSU secure stream switch (SSS) interface and delivers it to the PS-side (memory).

  • 32-bit AXI 3.0 interface on the PS-side

  • Deep 128x32-bit data FIFOs for both the SRC and DST data paths

  • PS-side AXI Issuing capability up to a maximum of 9 commands per channel, with programmable maximum

  • Single thread (AXI-ID) operation for both read and write channels

  • CSU_DMA operates synchronously in the “csu_main_clk” or PMC clock domain

  • Target CSU_DMA frequency of 400MHz max

  • DST DMA will only issue a write AXI command if the corresponding write data is available in the write data FIFO – Store and Forward.

  • SRC DMA will only issue a read AXI command if there is enough space in the read data FIFO for the entire burst.

  • DMA start address is 32-bit aligned

  • DMA transfer length is in units of 4-byte words

  • DMA can accept only 1 command per channel

  • Timeout mechanisms for both SRC(read) and DST(write) channels

  • Automatic hardware management of 4kbyte boundary crossing on the PS-side (AXI )

  • Dedicated APB interface for CSU_DMA register access

  • Always generates secure (AxPROT[1]=0) AXI commands

  • DMA supports INCR and FIXED (keyhole) AXI burst-types

  • Zero-ization of FIFOs for security purposes achieved via RAM MBIST

  • Byte endianness option available for the SRC DMA

  • Pseudo-CRC option available for the SRC DMA payload

Known Issues and Limitations

  • None

Example Applications

CSUDMA driver supports a few basic polled and interrupt examples describing how its different features can be exercised. These example applications can be imported into the Vitis IDE from the Board Support Package  settings tab. 

Links to Examples

Examples Path:
https://github.com/Xilinx/embeddedsw/tree/master/XilinxProcessorIPLib/drivers/csudma/examples/

Test Name

Example Source

Description

CSUDMA Selftest example

xcsudma_selftest_example.c

Basic CSUDMA selftest example to check sanity and use core APIs.

CSUDMA Polled example

xcsudma_polled_example.c

Polled mode example demonstrating CSUDMA transfer via polling of busy state and local loopback.

CSUDMA Interrupt example

xcsudma_intr_example.c

Interrupt mode example demonstrating CSUDMA transfer via interrupts and local loopback.

Example Application Usage

CSUDMA Selftest example

Basic CSUDMA selftest example to check sanity and use core APIs.

Expected Output

Successfully ran CSU_DMA Selftest Example

CSUDMA Polled example

Polled mode example demonstrating CSUDMA transfer via polling of busy state and local loopback.

Expected Output

Successfully ran CSU_DMA Polled Example

CSUDMA Interrupt example

Interrupt mode example demonstrating CSUDMA transfer via interrupts and local loopback.

Expected Output

Successfully ran CSU_DMA Interrupt Example

Example Design Architecture

NA

Performance

NA

Change Log

2021.2

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2021.2/doc/ChangeLog#L201

2021.1

https://github.com/Xilinx/embeddedsw/commits/xilinx_v2021.1/XilinxProcessorIPLib/drivers/csudma

2020.2

https://github.com/Xilinx/embeddedsw/blob/release-2020.2/doc/ChangeLog#L444

2020.1

https://github.com/Xilinx/embeddedsw/blob/release-2020.1/doc/ChangeLog#L26

2019.2

https://github.com/Xilinx/embeddedsw/blob/release-2019.2/doc/ChangeLog#L32

2019.1

https://github.com/Xilinx/embeddedsw/blob/release-2019.1/doc/ChangeLog#L64

2018.3

https://github.com/Xilinx/embeddedsw/blob/release-2018.3/doc/ChangeLog#L412

2018.2

None

2018.1

https://github.com/Xilinx/embeddedsw/blob/release-2018.1/doc/ChangeLog#L278

Related Links