Migration Guide: QDMA to MDB5 DMA

3. Tools/Pre-requisites for Migration

Before starting the migration, please ensure the following requirements are met:

Software Environment

• OS/Kernel: Ubuntu 24.04 recommended. Kernel 6.8.0+ is required.
• Dependencies: Install development libraries: apt-get install libaio-dev

Kernel Configuration

The MDB5 driver relies on the in-kernel dw-edma driver. Ensure these options are set in your kernel config:

• CONFIG_DMADEVICES=y
• CONFIG_DMA_ENGINE=y
• CONFIG_PCI=y
• CONFIG_PCI_MSI=y
• CONFIG_DW_EDMA=y
• CONFIG_DW_EDMA_PCIE=y

4. The Migration Process

Follow these steps to transition your system and applications.

Step 1: Driver Setup

1. Build Client Driver:

   cd /path/to/mdb5-dmaclient-drv/
   make

2. Load Driver:

   modprobe ./bin/$(uname -p)/mdb5-dmaclient-drv.ko device_dbdf="<BDF>" dma_dev_id="<device id>"

Step 2: Application & Script Migration

A. Device Node Mapping

Once driver is installed, new device nodes will be available:

• Read (C2H):

  QDMA: /dev/qdma<BDF>-MM-<Q>

  MDB5 DMA: /dev/mdb5_read<00-07>

• Write (H2C):

  QDMA: /dev/qdma<BDF>-MM-<Q>

  MDB5 DMA: /dev/mdb5_write<00-07>

• Control:

  MDB5 DMA: /dev/mdb5_ctrl

B. Command Line Userspace Applications

The command line userspace applications have similar names but different options and workflows.

H2C Transfer (dma-to-device)

QDMA - uses device path with BDF and queue number:

dma-to-device -d /dev/qdma06000-MM-0 -s 1024 -f input.bin

MDB5 DMA - uses channel index:

dma-to-device -c 0 -a 0xaa002000 -s 1024 -f input.bin

C2H Transfer (dma-from-device)

QDMA:

dma-from-device -d /dev/qdma01000-MM-1 -s 64

MDB5 DMA:

dma-from-device -c 0 -a 0xaa002000 -s 1024 -w output.bin

Statistics

QDMA - view queue status:

dma-ctl dev list

MDB5 DMA - view channel statistics:

dma-ctl -S -c 0 -d write

Transfer test config based (dma-xfer)

The dma-xfer userspace application uses configuration files to define test parameters, enabling repeatable testing without specifying all options on the command line.

QDMA config file format:

name=mm_sample
pci_bus=08
pci_device=00
function=0
is_vf=0
mode=mm
dir=bi
q_range=0:0
tmr_idx=6
cntr_idx=6
cmptsz=0
trig_mode=cntr_tmr
pfetch_en=0
rngidx=0
pkt_sz=1024
io_type=io_async
inputfile=INPUT
outputfile=OUTPUT

Execute QDMA test:

dma-xfer -c qdma_xfer_config.txt

MDB5 DMA config file format:

name=mm_xfer
chan_mode=mm
num_rd_channels=2
num_wr_channels=2
address=0xaa002000
transfer_mode=sg
pkt_sz=1024
io_type=io_sync
inputfile=in.txt
outputfile=out.txt

Execute MDB5 DMA test:

dma-xfer -c mdb5_dma_xfer_config.txt

Performance Testing (dma-perf)

The dma-perf userspace application measures DMA throughput using configuration files. Both userspace applications are config-file driven and measure sustained DMA throughput over a specified runtime.

QDMA config file format:

name=mm_perf
mode=mm
dir=bi
pf_range=0:0
q_range=0:0
wb_acc=5
tmr_idx=9
cntr_idx=0
trig_mode=usr_cnt
rngidx=9
runtime=30
num_threads=8
bidir_en=1
num_pkt=64
pkt_sz=64
pci_bus=06
pci_device=00

Execute QDMA performance test:

dma-perf -c qdma_perf_config.txt

MDB5 DMA config file format:

name=mm_perf
chan_mode=mm
pci_bus=1
pci_dev=0
pf_range=0:0
ch_start_idx=0
num_rd_channels=0
num_wr_channels=1
address=0xaa002000
runtime=30
num_process=1
num_pkt=64
pkt_sz=64
aperture_sz=0
dump_en=true

Execute MDB5 DMA performance test:

dma-perf -c mdb5_dma_perf_config.txt

5. Feature Comparison

The following table provides a comprehensive comparison of features supported by each driver.

6. Testing and Validation

After migration, use the following diagnostic commands to verify system integrity:

# Check kernel config
cat /boot/config-$(uname -r) | grep -E "CONFIG_DW_EDMA"

# Check device enumeration
lspci | grep -i xilinx

# Check device nodes
ls -la /dev/mdb5*

# Check kernel messages
dmesg | tail -50

# Get channel statistics
dma-ctl -S -c 0 -d write