AXI MultiChannel Direct Memory Access (AXI MDMA) IP provides high-bandwidth Direct memory access between the AXI4 memory mapped and AXI4-Stream IP interfaces. Its scatter gather capabilities also offload data Movement tasks from the Central Processing Unit (CPU) in processor-based Systems.

In AXI MCDMA Primary high-speed DMA data movement between system memory and Stream target is through the AXI4 Read Master to AXI4 memory-mapped to Stream (MM2S) Master, and AXI stream to memory-mapped (S2MM) Slave to AXI4 Write Master. AXI DMA enables up to 16 multiple channels of data movement on both MM2S and S2MM paths.

Initialization & Configuration

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

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

Interrupts In single interrupt multiple channels case driver provides interrupt handler XMcdma_TxIntrHandler and XMcdma_IntrHandler for mm2s and s2mm side respectively for handling the interrupt from the MCDMA core. The users of this driver have to register this handler with the interrupt system and provide the callback functions by using XMcdma_SetCallBack API.

Buffer Descriptors(BD) management

BD is shared by the software and the hardware. To use BD for SG DMA transfers, the application needs to use the driver API to do the following:

Setup the BD's for the Channel:
- XMcDma_ChanBdCreate(...)
Submit a DMA transfer for the required length.
- XMcDma_ChanSubmit(...)
Submit all prepared BDs to the hardware:
- XMcDma_ChantoHw(...)
Upon transfer completion, the application can request completed BDs from the hardware:
- XMcdma_BdChainFromHW(...)
After the application has finished using the BDs, it should free the BDs back to the free pool:
- XMcdma_BdChainFree(...)

The driver also provides API functions to get the status of a completed BD, along with get functions for other fields in the BD.

The following diagram shows the correct flow of BDs:

The diagram shows a complete cycle for BDs, starting from requesting the BDs to freeing the BDs.

        XMcDma_ChanSubmit()                   XMcDma_ChanToHw()
Free ------------------------> Pre-process ----------------------> Hardware
                                                                   |
 /|\                                                               |
  |    XMcdma_BdChainFree()                 XMcdma_BdChainFromHW() |
  +--------------------------- Post-process <----------------------+

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 AXI MCDMA driver is composed of several source files. This allows the user to build and link only those parts of the driver that are necessary.

This header file contains identifiers and register-level driver functions (or macros), range macros, structure typedefs that can be used to access the Xilinx AXI MCDMA core instance.

MODIFICATION HISTORY:

Ver Who Date Changes

1.0 adk 18/07/17 Initial version. 1.0 adk 09/02/18 Fixed CR#994435 Changes are made in the driver tcl file. 1.2 mj 05/03/18 Exported APIs XMcdma_BdChainFree() and XMcDma_BdSetAppWord(). 1.2 mus 11/05/18 Support 64 bit DMA addresses for Microblaze-X platform. 1.3 rsp 02/12/19 Add HasRxLength field in config and channel structure. 1.3 rsp 02/11/19 Add top level submit XMcDma_Chan_Sideband_Submit() API to program BD control and sideband information. 1.5 sk 07/13/20 Add XMcDma_BdGetAppWord() function declaration to fix the gcc warning in mcdma integration test suite. 1.7 sa 08/12/22 Updated the examples to use latest MIG cannoical define i.e XPAR_MIG_0_C0_DDR4_MEMORY_MAP_BASEADDR.