Migration Guide: QDMA to MDB5 DMA

arrow_back Software Docs

8. CLI Usage Examples

This section provides side-by-side command-line examples for the most common DMA operations, showing how each userspace application is invoked in QDMA vs. MDB5 DMA.

ℹ Note

C2H (Card-to-Host) maps to the read direction, and H2C (Host-to-Card) maps to the write direction. In MDB5 DMA, the direction flag -d uses read/write accordingly.

⚠ Warning

QDMA and MDB5 DMA userspace applications share the same binary names and many of the same flag letters, but several flags have different meanings. Refer to the Flag Differences section for details.

Flag Differences Between QDMA and MDB5 DMA userspace applications

The following table provides a comprehensive flag-by-flag comparison across both the userspace applications. The same option can carry different meanings depending on the userspace application.

Flag Application(s) QDMA MDB5 DMA
-d dma-to-device
dma-from-device		 --device: device node path (e.g., /dev/qdma06000-MM-0) Not available.
dma-ctl Not available. --dir: channel direction (read / write)
-c dma-to-device
dma-from-device		 --count: number of transfer iterations (default: 1) --channel: channel index (0-7).
dma-ctl Not available. --channel: channel index (0-7).
-f dma-to-device
dma-from-device		 --file: data file, input (dma-to-device) or output (dma-from-device) --data_input_file: input file (dma-to-device only, required).
-w dma-to-device
dma-from-device		 --data outfile: output / verification file. dma-to-device only --data_output_file: output file. Available in both dma-to-device (optional verification) and dma-from-device (primary output)
-a dma-to-device
dma-from-device		 --address: AXI bus starting address. --address: device memory address
dma-ctl Not available. --set_aperture_sz: set aperture window size. Requires -c and -d
-s dma-to-device
dma-from-device		 --size: transfer size in bytes --size: transfer size in bytes
dma-ctl Not available. --bdf: PCI Bus:Device.Function in hex (BB:DD.F).
-o dma-to-device
dma-from-device		 --offset: page offset of transfer --offset: page offset of transfer
-m dma-ctl Not available --set_transfer_mode: simple or sg (Scatter-Gather).
-M dma-ctl Not available. --get_transfer_mode: get current transfer mode.
-S dma-ctl Not available. --stats: channel statistics (transfer counts, success/failure rates, data processed).
-A dma-ctl Not available. --get_aperture_sz: get current aperture window size.
-r dma-ctl Not available. --reg_read: register offset to read. Used with -s (BDF)

For the complete list of options, see the MDB5 DMA User Applications reference and the QDMA User Guide.

8.1 C2H Transfer (dma-from-device)

QDMA MDB5 DMA 
# Step 1: Setup queue
$ dma-ctl qdma06000 q add idx 1 mode mm dir c2h
$ dma-ctl qdma06000 q start idx 1 dir c2h

# Step 2: Perform transfer
$ dma-from-device -d /dev/qdma06000-MM-1 \
    -a 0x0 -s 1024 -f output.bin

Options:

  • -d (--device): device node path
  • -a (--address): start address on AXI bus
  • -s (--size): transfer size in bytes
  • -f (--file): output file to write data to
  • -c (--count): number of transfers (default: 1)
  • -o (--offset): page offset of transfer
 
# No queue setup needed
$ dma-from-device -c 0 -a 0xaa002000 \
    -s 1024 -w output.bin

Options:

  • -c (--channel): channel index (0-7)
  • -a (--address): device memory address
  • -s (--size): transfer size in bytes
  • -w (--data_output_file): output file to write data to
  • -o (--offset): page offset

8.2 H2C Transfer (dma-to-device)

QDMA MDB5 DMA 
# Step 1: Setup queue
$ dma-ctl qdma06000 q add idx 0 mode mm dir h2c
$ dma-ctl qdma06000 q start idx 0 dir h2c

# Step 2: Perform transfer
$ dma-to-device -d /dev/qdma06000-MM-0 \
    -a 0x0 -s 1024 -f input.bin

# Step 3: Cleanup
$ dma-ctl qdma06000 q stop idx 0 dir h2c
$ dma-ctl qdma06000 q del idx 0 dir h2c

Options:

  • -d (--device): device node path
  • -a (--address): start address on AXI bus
  • -s (--size): transfer size in bytes
  • -f (--data infile): input file to read data from
  • -w (--data outfile): output file to write transfer data
  • -c (--count): number of transfers (default: 1)
  • -o (--offset): page offset of transfer
 
# No queue setup needed
$ dma-to-device -c 0 -a 0xaa002000 \
    -s 1024 -f input.bin

Options:

  • -c (--channel): channel index (0-7)
  • -a (--address): device memory address
  • -s (--size): transfer size in bytes
  • -f (--data_input_file): input file to read data from
  • -w (--data_output_file): output file to write transfer data
  • -o (--offset): page offset

8.3 Register Read/Write (dma-ctl)

QDMA MDB5 DMA 
# Read a register
$ dma-ctl qdma06000 reg read bar 0 0x100

# Write a register
$ dma-ctl qdma06000 reg write bar 0 0x100 0x1

# Dump all registers
$ dma-ctl qdma06000 reg dump

Syntax:

  • reg read [bar <N>] <addr>
  • reg write [bar <N>] <addr> <val>
  • reg dump [dmap <Q> <N>]
 
# Read a register
$ dma-ctl -r 0x100 -s 06:00.0

# Write a register
$ dma-ctl -w 0x100 0x1 -s 06:00.0

Options:

  • -r (--reg_read): register offset to read
  • -w (--reg_write): register offset and data to write
  • -s (--bdf): PCI BDF in hex (BB:DD.F)

8.4 Channel/Queue Management (dma-ctl)

QDMA MDB5 DMA 
# List devices
$ dma-ctl dev list

# Device info & capabilities
$ dma-ctl qdma06000 cap
$ dma-ctl qdma06000 stat

# Queue lifecycle (add → start → stop → del)
$ dma-ctl qdma06000 q add idx 0 mode mm dir bi
$ dma-ctl qdma06000 q start idx 0 dir bi
$ dma-ctl qdma06000 q stop idx 0 dir bi
$ dma-ctl qdma06000 q del idx 0 dir bi

# Queue info
$ dma-ctl qdma06000 q dump idx 0 dir bi

Key difference: QDMA requires explicit queue lifecycle management via netlink commands.

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

# Get current transfer mode
$ dma-ctl -M -c 0 -d write

# Set transfer mode to Scatter-Gather
$ dma-ctl -m sg -c 0 -d write

# Set transfer mode to Simple DMA
$ dma-ctl -m simple -c 0 -d read

# Get aperture size
$ dma-ctl -A -c 0 -d write

# Set aperture size
$ dma-ctl -a 4096 -c 0 -d write

Options:

  • -c (--channel): channel index
  • -d (--dir): channel direction (read/write)
  • -m (--set_transfer_mode): set mode (sg/simple)
  • -M (--get_transfer_mode): get current mode
  • -S (--stats): show channel statistics
  • -a (--set_aperture_sz): set aperture size
  • -A (--get_aperture_sz): get aperture size

Key difference: No queue lifecycle — channels are always available. Configuration is done via ioctl.

8.5 Transfer test config based (dma-xfer)

Both userspace applications use a configuration file. QDMA's config specifies queue parameters and netlink-based queue setup; MDB5 DMA's config specifies channel parameters and transfer mode.

QDMA MDB5 DMA 
# Run with config file
$ dma-xfer -c qdma_xfer_config.txt

Sample config (qdma_xfer_config.txt):

name=mm_sample
pci_bus=d8
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
 
# Run with config file
$ dma-xfer -c mdb5_dma_xfer_config.txt

Sample config (mdb5_dma_xfer_config.txt):

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

8.6 Performance Testing (dma-perf)

Both performance userspace applications are config-file driven and measure sustained DMA throughput over a specified runtime.

QDMA MDB5 DMA 
# Run performance test
$ dma-perf -c qdma_perf_config.txt

Sample config (qdma_perf_config.txt):

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
 
# Run performance test
$ dma-perf -c mdb5_dma_perf_config.txt

Sample config (mdb5_dma_perf_config.txt):

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