AXI DMA Standalone Driver

AXI DMA Standalone Driver

• This page gives an overview of

• the bare-metal driver support for the Xilinx® LogiCORE™ IP AXI Direct Memory Access (AXI DMA) soft IP.   

  
  

  Table of Contents

  Table of Contents
  exclude Table of Contents

  Introduction

  
  The AXI DMA core is a soft Xilinx IP core for use with the Xilinx Vivado® Design Suite. The AXI DMA provides high-bandwidth direct memory access between memory and AXI4-Stream target peripherals. Its optional scatter/gather capabilities also offload data movement tasks from the Central Processing Unit (CPU).

How to enable

•  

  For more information, please refer to the AXI DMA product page which includes links to the official documentation and resource utilization. 

  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. 

  <If there are multiple drivers supporting this IP, we should make that statement here and add to the table>

  
  

  Driver Name	Path in Vitis	Path in Github
  axidma	<Vitis Install Directory>/data/embedded/XilinxProcessorIPLib/drivers/axidma_<version>	https://github.com/Xilinx/embeddedsw/tree/master/XilinxProcessorIPLib/drivers/axidma

• 
  

  Info
  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-v2020.1/XilinxProcessorIPLib/drivers/axidma

  
  

  The driver source code is organized into different folders.

•   The table below shows the axidma 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

Features Supported

Controller Features

• AXI4 compliant
• Optional Scatter/Gather Direct Memory Access (DMA) support
• AXI4 data width support of 32, 64, 128, 256,512 and 1,024 bits
• AXI4-Stream data width support of 8, 16, 32, 64, 128, 256, 512 and 1,024 bits
• Supports multichannel operation (up to 16 channels)
• Supports two-dimensional (2-D) transfers in multichannel mode.
• Optional Keyhole support
• Optional Data Re-Alignment support
• Optional AXI Control and Status Streams
• Optional Micro DMA Support
• Support for up to 64-bit addressing
• Support for Cyclic DMA Mode

• Driver Implementation

  For a full list of features supported by this IP, please refer to the AXI DMA product page.  

  
  

  Features
  
  

  The AXI DMA Standalone driver supports the

• Supports
  following features: 
  

  • Simple DMA mode
  Supports
  • Scatter/Gather Direct Memory Access (DMA)
  Support
  • multi-channel operation (up to 16 channels)
  Supports
  • 64-bit Addressing
  Supports
  • Key Hole Feature
  Supports
  • Optional Data Re-Alignment Feature

Test cases

• Refer below pah for testing different examples for each feature of the IP.

• Known Issues and Limitations

  The following is a list of known limitations of the driver and features of the IP that are not currently implemented: 
  
  

  • No Support for Cyclic DMA mode.
  • When H/w is configured without DRE driver will throw an error if the user sends an unaligned error.
  • User application should handle buffer address alignment in case h/w is configured without DRE

  Example Design Architecture 

  The examples assumes AXIDMA is 

  
  

  Image Added

  
  

  Example Applications

  Refer to the driver examples directory for various example applications that exercise the different features of the driver. Each application is linked in the table below. The following sections describe the usage and expected output of the various applications.  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/axidma/examples

  
  

  Test Name	Example Source	Description
  Self Test	xaxidma_example_selftest.c

• 	This example does a basic reset of the core and checks core is coming out of reset or not.
  Scatter Gather DMA with Interrupts	xaxidma_example_sg_intr.c

• 	This example demonstrates how to transfer packets in interrupt mode when the core is configured in Scatter Gather Mode.
  Scatter Gather DMA with Polling	xaxidma_example_sg_poll.c

• 	This example demonstrates how to transfer packets in the scatter gather polled mode.
  Simple DMA with Interrupt	xaxidma_example_simple_intr.c

• 	This example demonstrates how to transfer packets in interrupt mode when the core is configured in Simple DMA Mode.
  Simple DMA with Polling	xaxidma_example_simple_poll.c

• This example demonstrates how to transfer packets in the polled mode when the core is configured in Simple DMA Mode.

• SGDMA Multi-Packet Polled Mode

  xaxidma_poll_multi_pkts.c

• This example demonstrates how to transfer multiple packets in the polled mode when the core is configured in Scatter Gather Mode.

Known issues and Limitations

• When H/w is configured without DRE driver will throw an error if the user sends an unaligned address.
• User application should handle buffer address alignment in case h/w is configured without DRE.

Change Log

2020.2

• Cleanup debug headers files.
• Support parallel make execution.
• Fix MM2S and S2MM Length for AXIDMA Micro Mode.
• Remove deprecated multichannel SG interrupt example. 

257c0d9e3742 BSP: Consolidate and add the drivers xdebug.h data to common xdebug.h
4dc85994d6fb Makefile: Remove realpath command
d8ec78e72a5c axidma: Update Makefile to support parallel make execution
c7a0c332e55f axidma: Fix MM2S and S2MM Length for AXIDMA Micro Mode
25f16200f490 axidma: Removed deprecated xaxidma_example_multichan_sg_intr.c
62a549a4aa0d drivers: Fix makefiles issue for windows

2020.1

• Fix test failure with smaller packet size
• Clean up old versions for axidma driver
• Removed deprecated xaxidma_example_multichan_sg_intr.c

932b059 examples: Fix test failure with smaller packet size 
783bcfb axidma: Clean up old versions for axidma driver
b563c20 axidma: Removed deprecated xaxidma_example_multichan_sg_intr.c

• Add support for 64MB data transfer.

• Fix multichan_sg_intr example on a53.
• Use UINTPTR type for storing address.
• Use virtual addr for BD access in _UpdateBdRingCDesc().
• Extend AXI DMA examples to support data buffers above 4GB.

• Fixed issue poll_multi_pkt example fails on a53.
• Fixed bug in the XAxiDma_Reset() API
• Added interface to lookup XAxiDma_Config based on base address

• Add support for cyclic DMA mode
• Rename the example files to select individual examples

• None

• None

  
  

  Example Application Usage

  Self Test

  This example does a basic reset of the core and checks core is coming out of reset or not.

  Expected Output

  Code Block
  theme Midnight
  --- Entering main() --- Successfully ran AxiDMASelfTest Example --- Exiting main() --

  Scatter Gather with Interrupts

  This example demonstrates how to transfer packets in interrupt mode when the core is configured in Scatter Gather Mode.

  Expected Output

  Code Block
  theme Midnight
  --- Entering main() --- Successfully ran AXI DMA SG interrupt Example --- Exiting main() ---

  Scatter Gather with Polling

  This example demonstrates how to transfer packets in the scatter gather polled mode.

  Expected Output

  Code Block
  theme Midnight
  --- Entering main() --- Successfully ran AXI DMA SG Polling Example --- Exiting main() ---

  Simple DMA with Interrupts

  This example demonstrates how to transfer packets in interrupt mode when the core is configured in simple DMA mode.

  Expected Output

  Code Block
  theme Midnight
  --- Entering main() --- Successfully ran AXI DMA interrupt Example --- Exiting main() ---

  Simple DMA with Polling

  This example demonstrates how to transfer packets in poll mode when the core is configured in simple DMA mode.

  Expected Output

  Code Block
  theme Midnight
  --- Entering main() --- Successfully ran XAxiDma_SimplePoll Example --- Exiting main() ---

  Scatter Gather Multi-Packet Polled Mode

  This example demonstrates how to transfer multiple packets in poll mode when the core is configured in Scatter Gather Mode.

  Expected Output

  Code Block
  theme Midnight
  --- Entering main() --- Successfully ran AXI DMA poll multi Example --- Exiting main() ---

  
  

  
  

  Change Log

  
  

  2021.1

  https://github.com/Xilinx/embeddedsw/blob/xilinx_v2021.1/doc/ChangeLog#L400

  2020.2

  https://github.com/Xilinx/embeddedsw/blob/xilinx-v2020.2/doc/ChangeLog#L341

  2020.1

  https://github.com/Xilinx/embeddedsw/blob/xilinx-v2020.1/doc/ChangeLog#L285

  2019.2

  https://github.com/Xilinx/embeddedsw/blob/xilinx-v2019.2/doc/ChangeLog#L167

  
  

  Related Links

  • http://www.wiki.xilinx.com/Baremetal+Drivers+and+Libraries