SoftIP DMA'S Linux driver for Microblaze and Zynq and Zynq Ultrascale+ MPSoC

Introduction
This page gives an overview of Soft IP's DMA(AXI DMA/CDMA/VDMA) driver, which is available as part of the Xilinx Linux distribution and in open source Linux as drivers/dma/xilinx_dma.c

HW IP features

AXI DMA

The AXI Direct Memory Access (AXI DMA) IP provides high-bandwidth direct memory access between the AXI4 memory mapped and AXI4-Stream-type target peripherals. Its optional scatter-gather capabilities also offload data movement tasks from the Central Processing Unit (CPU) in processor-based systems. Initialization, status, and management registers are accessed through an AXI4-Lite slave interface.
  • AXI4 and AXI4-Stream compliant
  • Optional Scatter/Gather (SG) DMA support. When Scatter/gather mode is not selected the IP operates in Simple DMA mode.
  • Primary AXI4 Memory Map and AXI4-Stream data width support of 32, 64, 128, 256, 512, and 1024 bits
  • Optional Data Re-Alignment Engine
  • Optional AXI Control and Status Streams
  • Optional Keyhole support
  • Optional Micro DMA mode support
  • Support for up to 64-bit Addressing

Features supported in the driver

  • Optional Scatter/Gather (SG) DMA support. When Scatter/gather mode is not selected the IP operates in Simple DMA mode.
  • Primary AXI4 Memory Map and AXI4-Stream data width support of 32, 64, 128, 256, 512, and 1024 bits
  • Optional Data Re-Alignment Engine
  • Optional AXI Control and Status Streams
  • 64-bit Addressing support

Note: multi-channel mode is no longer a supported mode of operation for AXI DMA.

AXI CDMA

The AXI CDMA provides high-bandwidth direct memory access (DMA) between a memory mapped source address and a memory mapped destination address using the AXI4 protocol. An optional Scatter Gather (SG) feature can be used to offload control and sequencing tasks from the System CPU. Initialization, status, and control registers are accessed through an AXI4-Lite slave interface.
  • AXI4 Compliant
  • Primary AXI Memory Map data width support of 32, 64, 128, and 256 bits
  • Primary AXI Stream data width support of 8, 16, 32, 64, 128, and 256 bits
  • Optional Data Re-Alignment Engine
  • Optional Gen-Lock Synchronization
  • Independent, asynchronous channel operation
  • Provides Simple DMA only mode and an optional hybrid mode supporting both Simple DMA and Scatter-Gather automation
  • Optional Store and Forward operation mode with internal Data FIFO (First In First Out)

Features supported in the driver

  • Optional Scatter/Gather (SG) DMA support. When Scatter/gather mode is not selected the IP operates in Simple DMA mode.
  • Primary AXI4 Memory Map and AXI4-Stream data width support of 32, 64, 128, 256, 512, and 1024 bits
  • Optional Data Re-Alignment Engine
  • 64-bit Addressing Support
  • Simple DMA mode
  • Scatter-Gather DMA mode

AXI VDMA

The AXI Video Direct Memory Access (AXI VDMA) core is a soft Xilinx IP core that provides high-bandwidth direct memory access between memory and AXI4-Stream type video target peripherals. The core provides efficient two dimensional DMA operations with independent asynchronous read and write channel operation. Initialization, status, interrupt and management registers are accessed through an AXI4-Lite slave interface.
  • High-bandwidth direct memory access for video streams
  • Efficient two-dimensional DMA operations
  • Independent, asynchronous read and write channel operation
  • Gen-Lock frame buffer synchronization
  • Supports a maximum of 32 frame buffers
  • Supports dynamic video format changes
  • Configurable Burst Size and Line Buffer depth for efficient video streaming
  • Processor accessible initialization, status, interrupt and management registers
  • Primary AXI Stream data width support for multiples of 8-bits: 8, 16, 24, 32, etc. up to 1024 bits
  • 64-bit Addressing

Features supported in the driver

  • 2-D Operations
  • Support for maximum 32 frame buffers
  • 64-bit Addressing
  • Gen-lock frame buffer synchronization

Missing Features and Known Issues/Limitations in Driver

AXI DMA

  • No support for Keyhole feature

AXI CDMA

  • None

AXI VDMA

  • Configurable Burst Size and Line Buffer depth for efficient video streaming

Kernel Configuration

The following config options should be enabled in order to build SoftIP DMA'S(AXI DMA/CDMA/VDMA) driver
CONFIG_DMADEVICES
CONFIG_XILINX_DMA

softdmas_config.PNG


The driver is available at,
https://github.com/Xilinx/linux-xlnx/blob/master/drivers/dma/xilinx/xilinx_dma.c

Devicetree

The device tree node for AXI DMA/CDMA/VDMA will be automatically generated, if the core is configured in the HW design, using the Device Tree BSP.

Steps to generate device-tree is documented here,
http://www.wiki.xilinx.com/Build+Device+Tree+Blob

And a sample binding is shown below and the description of DT property is documented here

AXI DMA
 axi_dma_1: dma@40400000 {
                        #dma-cells = <1>;
                        clock-names = "s_axi_lite_aclk", "m_axi_sg_aclk", "m_axi_mm2s_aclk", "m_axi_s2mm_aclk";
                        clocks = <&clkc 15>, <&clkc 15>, <&clkc 15>, <&clkc 15>;
                        compatible = "xlnx,axi-dma-1.00.a";
                        interrupt-parent = <&intc>;
                        interrupts = <0 29 4 0 30 4>;
                        reg = <0x40400000 0x10000>;
                        xlnx,addrwidth = <0x20>;
                        xlnx,include-sg ;
                        dma-channel@40400000 {
                                compatible = "xlnx,axi-dma-mm2s-channel";
                                dma-channels = <0x1>;
                                interrupts = <0 29 4>;
                                xlnx,datawidth = <0x20>;
                                xlnx,device-id = <0x0>;
                                xlnx,include-dre ;
                        };
                        dma-channel@40400030 {
                                compatible = "xlnx,axi-dma-s2mm-channel";
                                dma-channels = <0x1>;
                                interrupts = <0 30 4>;
                                xlnx,datawidth = <0x20>;
                                xlnx,device-id = <0x0>;
                                xlnx,include-dre ;
                        };
                };
 


AXI CDMA
axi_cdma_0: dma@4e200000 {
                        #dma-cells = <1>;
                        clock-names = "s_axi_lite_aclk", "m_axi_aclk";
                        clocks = <&clkc 15>, <&clkc 15>;
                        compatible = "xlnx,axi-cdma-1.00.a";
                        interrupt-parent = <&intc>;
                        interrupts = <0 31 4>;
                        reg = <0x4e200000 0x10000>;
                        xlnx,addrwidth = <0x20>;
                        xlnx,include-sg ;
                        dma-channel@4e200000 {
                                compatible = "xlnx,axi-cdma-channel";
                                interrupts = <0 31 4>;
                                xlnx,datawidth = <0x20>;
                                xlnx,device-id = <0x0>;
                                xlnx,include-dre ;
                                xlnx,max-burst-len = <0x10>;
                        };
                };
 

AXI VDMA
axi_vdma_0: dma@43000000 {
                        #dma-cells = <1>;
                        clock-names = "s_axi_lite_aclk", "m_axi_mm2s_aclk", "m_axi_mm2s_aclk", "m_axi_s2mm_aclk", "m_axi_s2mm_aclk";
                        clocks = <&clkc 15>, <&clkc 15>, <&clkc 15>, <&clkc 15>, <&clkc 15>;
                        compatible = "xlnx,axi-vdma-1.00.a";
                        interrupt-parent = <&intc>;
                        interrupts = <0 32 4 0 33 4>;
                        reg = <0x43000000 0x10000>;
                        xlnx,addrwidth = <0x20>;
                        xlnx,flush-fsync = <0x1>;
                        xlnx,num-fstores = <0x1>;
                        dma-channel@43000000 {
                                compatible = "xlnx,axi-vdma-mm2s-channel";
                                interrupts = <0 32 4>;
                                xlnx,datawidth = <0x20>;
                                xlnx,device-id = <0x0>;
                                xlnx,genlock-mode ;
                                xlnx,include-dre ;
                        };
                        dma-channel@43000030 {
                                compatible = "xlnx,axi-vdma-s2mm-channel";
                                interrupts = <0 33 4>;
                                xlnx,datawidth = <0x20>;
                                xlnx,device-id = <0x0>;
                                xlnx,genlock-mode ;
                                xlnx,include-dre ;
                        };
                };
 

Test Procedure

AXI DMA

A separate test case is provided to test the functionality of IP which assumes the IP streaming interfaces are connected back-to-back in the HW design. The test client is designed to transfer the data on the streaming interface (MM2S) and compares the data received on another interface (S2MM) which is loopback'ed. This test client is available in the Linux source at,

https://github.com/Xilinx/linux-xlnx/blob/master/drivers/dma/xilinx/axidmatest.c

NOTE: In ZynqMP vivado design it is mandatory to enable high address=1 (Zynq Ultrsacale+ MPSoC customization-> PS-PL configuration-> Address Fragementation-> High Address) and set AXI DMA adress width=40 bits.
For detail please refer: http://www.wiki.xilinx.com/PL+Masters

The test client can be configured in the ZynqMPSOC/Zynq/Microblaze kernel as either module or in-built,

axidmatestclient.PNG

Device-tree Node for the test client
 axidmatest_1: axidmatest@1 {
                      compatible ="xlnx,axi-dma-test-1.00.a";
                      dmas = <&axi_dma_1 0
                              &axi_dma_1 1>;
                      dma-names = "axidma0", "axidma1";
 } ;

Running the test client will display the message when the test is successful,
dmatest: Started 1 threads using dma0chan0 dma0chan1
dma0chan0-dma0c: terminating after 5 tests, 0 failures (status 0)

AXI CDMA

A separate test case is provided to test the functionality of IP which is designed to read the data from one location of memory and compare the data after copying data to other location of memory. This test client is available in the Linux source at,
https://github.com/Xilinx/linux-xlnx/blob/master/drivers/dma/xilinx/cdmatest.c

The test client can be configured in the Zynq/Microblaze kernel as either module or in-built,

cdma_config.PNG

Device-tree Node for the test client
 cdmatest_1: cdmatest@1 {
                  compatible ="xlnx,axi-cdma-test-1.00.a";
                  dmas = <&axi_cdma_0 0>;
                   dma-names = "cdma";
  } ;
Running the test client will display the message when the test is successful,
cdmatest: Started 1 threads using dma2chan0
dma2chan0-copy0: terminating after 5 tests, 0 failures (status 0)

AXI VDMA

A separate test case is provided to test the functionality of IP which assumes the IP streaming interfaces are connected back-to-back in the HW design. The test client is designed to transfer the data on the streaming interface (MM2S) and compares the data received on another interface (S2MM) which is loopback'ed. This test client is available in the Linux source at,
https://github.com/Xilinx/linux-xlnx/blob/master/drivers/dma/xilinx/vdmatest.c

The test client can be configured in the Zynq/Microblaze kernel as either module or in-built,

vdma_config.PNG

Device-tree Node for the test client
vdmatest_1: vdmatest@1 {
              compatible ="xlnx,axi-vdma-test-1.00.a";
               xlnx,num-fstores = <0x3>;
               dmas = <&axi_vdma_0 0
                          &axi_vdma_0 1>;
                 dma-names = "vdma0", "vdma1";
 } ;
 

Running the test client will display the message when the test is successful,
vdmatest: Started 1 threads using dma0chan0 dma0chan1
dma0chan0-dma0c: terminating after 1 tests, 0 failures (status 0)

Mainline Status

The current driver available in the Xilinx Linux git is in sync with the open source 4.14 kernel driver except for the following
  • Add idle checks across the driver for all the DMA's (AXI DMA/CDMA/VDMA) before submitting the descriptor.
  • Fix bug in multiple frame stores scenario in vdma
  • Fix race condition in the driver for multiple descriptor scenarios for axidma.
  • Vertical flip support in vdma.
  • Read dma max length from IP c_sg_length_width parameter.
  • Trivial code cleanup.
  • Free BD consistent memory in channel free_chan_resources.

Change Log

2018.2
Summary:
  • Add support for 64MB data transfer.
Commits:
f479cb5 dmaengine: xilinx: dma: In axidma add support for 64MB data transfer
2018.1
Summary:
  • Upgrade to 4.14 kernel.
  • Trivial code cleanup i.e Refactor axidma channel allocation
  • Free BD consistent memory in channel free_chan_resources.
  • Fix DMA idle state on terminate_all.
  • Enable VDMA S2MM vertical flip support.
  • Add support for memory sg transactions for CDMA.
  • In AXIDMA program hardware supported buffer length.
Commits:
818f168 Merge tag 'v4.14' into master
62515d5 dma: xilinx: xilinx_dma: Refactor axidma channel allocation
b0d0ec6 dma: xilinx: xilinx_dma: Free BD consistent memory
a9aeecb dma: xilinx: making dma state as idle on terminating all
1eb7c59 dmaengine: xilinx: dma: Enable VDMA S2MM vertical flip support
d5b6e8d dma: xilinx: xilinx_dma: Move open brace '{' to function definition next line
2eee108 dma: xilinx: xilinx_dma: Document functions return value
ff238b0 dma: xilinx: Add support for memory sg transactions for cdma
86b2c03 vdmatest: xilinx: Add hsize and vsize module parameter
b78597b vdmatest: xilinx: Fix VDMA hang reported in certain resolutions
01a61a2 vdmatest: xilinx: Use octal permissions '0444'
dcee02c dmaengine: xilinx: dma: Program hardware supported buffer length

2017.4
Summary:
  • Added support for memory sg transactions for cdma
  • Fixed race conditions in the driver for cdma
  • Differentiate probe based on IP type.
  • Fix compiler warning.
Commits:
9e8f5fc dma: xilinx: Add support for memory sg transactions for cdma
b3fe111 dma: xilinx: Fix race conditions in the driver for cdma.
61a18fd dma: xilinx: Differentiate probe based on the IP type.
322bd63dma: xilinx: xilinx_dma: Fix compilation warning.

2017.3
Summary:
  • Fix issues with dma_get_slave_caps API for AXI DMA configuration.
  • Fix issues with vdma mulit fstore configuration.
Commits:
ed2ee32 dma: xilinx: Fix issues with vdma mulit fstore configuration
54c8b75dma: xilinx: Fix dma_get_slave_caps gaps

2017.2
  • None

2017.1
Summary:
  • Add idle checks across the driver for all the DMA's (AXI DMA/CDMA/VDMA) before submitting the descriptor.
  • Fix bug in multiple frame stores scenario in vdma
  • Fix race condition in the driver for multiple descriptor scenario for axidma.
Commits:
d4df1d5 dma: xilinx_dma: check for channel idle state before submitting the dma descriptor.
05ce73d dma: xilinx_dma: Fix bug in multiple frame stores scenario in vdma
3794829 dma: xilinx_dma: Fix race condition in the driver for multiple descriptor scenario for axidma.

2016.4
  • None

2016.3
Summary:
  • Mainlined the driver
  • Fixed the issues as per the commit ID
  • Deleted the AXI DMA/CDMA driver and Merged the AXI DMA/CDMA code with the VDMA driver
  • Merged all the 3 DMA's drivers into a single driver
Commits:
f4cd973 dma: xilinx: axidma: Fix race condition in the cyclic dma mode
853502d vdma: sync driver with mainline
52619f dma: xilinx: Delete AXI DMA driver
97833b1 dma: xilinx: Delete AXI CDMA driver
d78c414 dmaengine: vdma: Use dma_pool_zalloc
7531bdc dmaengine: vdma: Rename xilinx_vdma_ prefix to xilinx_dma
0cc811a dmaengine: vdma: Add Support for Xilinx AXI Direct Memory Access Engine
90b6146 dmaengine: vdma: Add Support for Xilinx AXI Central Direct Memory Acc… …ess Engine
300f90b dmaengine: vdma: Add config structure to differentiate dmas
cc28fc1 dmaengine: vdma: Add clock support
0717493 dmaengine: vdma: don't crash when bad channel is requested
60c30ad dmaengine: vdma: Add support for cyclic dma mode
d0509b1 dmaengine: vdma: Use dma_pool_zalloc
d7cb73e dmaengine: vdma: Fix compilation warning in cyclic dma mode
18ef650 dmaengine: vdma: Add 64 bit addressing support for the axi dma
ab182b3 dmaengine: vdma: Add 64 bit addressing support for the axi cdma
aa32340 dmaengine: vdma: Add support for mulit-channel dma mode
fb5fb40 dmaengine: xilinx: Rename driver and config
c41a863 dmaengine: xilinx: Use different channel names for each dma
ebccb5e dmaengine: xilinx: Fix race condition in axi dma cyclic dma mode
6300822 dma: xilinx: Update test clients depends config option
8408c14 dma: xilinx: Check for channel idle state before submitting dma descr…

Related Links