User Applications

This document provides comprehensive usage information for all MDB5 DMA user-space applications. Each application serves a specific purpose in the MDB5 DMA ecosystem for testing various functionalities supported by the controller.

Note

Aperture Size

Provides support of programming over PCIe. MDB5 DMA Software provides a capability to program a pdi file to a specific aperture within a Versal device. This enables the DMA to write data to a fixed size FPGA aperture.

When the end of the user specified aperture size is reached, transactions continue to transfer data by looping back to the start of the aperture window. This is repeated until all data has been programmed into the user specified aperture window.

dma-ctl

Overview

The dma-ctl application is a command-line utility for configuring and controlling MDB5 DMA devices. It provides control capabilities for DMA controllers, channels, and registers.

Usage

dma-ctl [OPTIONS]

-c, --channel <INDEX>            Specify the channel index (0-7 for read/write channels)
-d, --dir <read/write>           Specify channel direction
-s, --bdf <BB:DD.F>              Specify PCI Bus:Device.Function in hexadecimal format
-S, --stats                      Display channel statistics
-m, --set_transfer_mode <MODE>   Set transfer mode (e.g., sg/simple)
-M, --get_transfer_mode          Get current transfer mode
-a, --set_aperture_sz <VALUE>    Set aperture size (SG mode only)
-A, --get_aperture_sz            Get current aperture size
-h, --help                       Display help information
-v, --version                    Display version information
-r, --reg_read <OFFSET>          Read register at specified offset (debug only)
-w, --reg_write <OFFSET> <DATA>  Write data to register at specified offset (debug only)

Commands

Channel statistics

This command displays statistics for a specific DMA channel.

[root@host]# dma-ctl -S -c 1 -d write
INFO: Channel /dev/mdb5_write00 stats:
	Number of packets received = 1
	Number of packets success = 1
	Number of packets failed = 0
	Number of interrupts received = 1
	Read data processed = 0
	Write data processed = 104857600
	Total data processed = 104857600

Set transfer mode

This command configures the transfer mode for a channel. Two available modes are, Scatter-Gather (Linked-list) Mode and Simple (Non Linked-list) Mode.

Note

Channels are set to Scatter-Gather (Linked-list) Mode as default when the driver is initialized.

[root@host]# dma-ctl -m sg -c 0 -d write
INFO: Scatter-Gather mode configured on channel /dev/mdb5_write00

[root@host]# dma-ctl -m simple -c 2 -d read
INFO: Simple mode configured on channel /dev/mdb5_read02

Get transfer mode

This command queries the current transfer mode for a channel.

[root@host]# dma-ctl -M -c 0 -d write
INFO: Scatter-Gather mode configured on channel /dev/mdb5_write00

Set aperture size

This command configures the aperture size for Scatter-Gather (Linked-list) Mode channels.

[root@host]# dma-ctl -a 4096 -c 0 -d write
INFO: Aperture size = 4096 is configured on channel /dev/mdb5_write00

Get aperture size

This command queries the current aperture size for a channel.

[root@host]# dma-ctl -A -c 0 -d write
INFO: Aperture size = 4096 is configured on channel /dev/mdb5_write00

Debug Register Operations

Warning

The register read and write operations are intended for debugging purposes only. These commands provide direct access to hardware registers and should be used with caution. Improper register writes can cause system instability.

Register read

This command reads a register value from the DMA controller.

[root@host]# dma-ctl -r 0x100 -s 01:00.0
INFO: Register read: offset = 0x100, data = 0xDEADBEEF

Register write

This command writes a value to a register in the DMA controller.

[root@host]# dma-ctl -w 0x100 0xFF -s 01:00.0
INFO: Register read back: offset = 0x100, data = 0xFF

dma-xfer

Overview

The dma-xfer application demonstrates DMA transfer operations using configuration files. It provides an interface for performing both synchronous and asynchronous data transfers between files and device memory on both Simple (Non Linked-list) Mode and Scatter-Gather (Linked-list) Mode.

The utility perform a completes test by:

  • Configuration: Reads parameters from a configuration file specifying channel counts, device memory addresses, transfer modes, and file paths

  • Channel Setup: Initializes write channels (host-to-device) and read channels (device-to-host)

  • Write Operation: Transfers data from an input file to a specified address in device memory via write channels

  • Read Operation: Reads the same data back from device memory and writes it to an output file

  • Validation: Enables validation that data written to device memory can be successfully read back

  • Async Transfer Completion: In asynchronous mode, transfer completion is detected by the interrupt generated by the MDB5 DMA Controller.

The application is designed primarily for round-trip validation, automatically performing both write and read operations in sequence. While it’s technically possible to configure write-only or read-only operations by setting channel counts to zero, this breaks the validation workflow and is not the intended use case. For dedicated unidirectional transfers, consider using the specialized dma-to-device or dma-from-device applications instead.

Usage

dma-xfer [OPTIONS]

-c, --config <FILE> Configuration file that defines transfer parameters
-h, --help          Print usage help and exit
-v, --version       Print version information and exit
-V, --verbose       Enable verbose output

Configuration file format

The application requires a configuration file with transfer parameters:

name=mm_xfer			# Configuration name
chan_mode=mm			# <mm>
num_rd_channels=2
num_wr_channels=2
address=0xaa002000		# Device memory address
transfer_mode=sg		# <sg=SCATTER-GATHER DMA / simple=Simple DMA> 
pkt_sz=1024
io_type=io_sync			# <io_async / io_sync>
inputfile=in.txt		# <file name of length up to 127>
outputfile=out.txt		# <file name of length up to 127>

Configuration parameters

  • name - Configuration name for identification

  • chan_mode - Channel mode (currently only mm supported)

  • num_rd_channels - Number of read channels to use for C2H transfers, starting from channel 0 (e.g., setting this to 2 will use channels 0 and 1)

  • num_wr_channels - Number of write channels to use for H2C transfers, starting from channel 0 (e.g., setting this to 2 will use channels 0 and 1)

  • address - Device memory address for transfers

  • transfer_mode - Transfer mode (sg for Scatter-Gather (Linked-list) DMA, simple for Simple (Non Linked-list) DMA)

  • pkt_sz - Size of data packets to transfer (in bytes)

  • io_type - Transfer synchronization (io_sync for blocking, io_async for non-blocking)

  • inputfile - Source file for write operations (up to 128 characters)

  • outputfile - Destination file for read operations (up to 128 characters)

Example

[root@host]# dma-xfer --config config_file.txt

dma-to-device

Overview

The dma-to-device application enables Host-to-Card (H2C) data transfers using the MDB5 DMA driver. It provides a simple interface for transferring data from system memory to device memory.

Usage

dma-to-device [OPTIONS]

-c, --channel <INDEX>         Channel index, default 0
-a, --address <ADDRESS>       Address on the device memory
-s, --size <SIZE>             Size of a single transfer in bytes, default 32
-o, --offset <OFFSET>         Page offset of transfer, default 0
-f, --data_input_file <FILE>  Input file to read data from
-w, --data_output_file <FILE> Optional output file to write transfer data
-h, --help                    Print usage help and exit
-v, --verbose                 Verbose output

Examples

Basic transfer

[root@host]# dma-to-device --channel 0 --address 0xaa002000 --size 1024 --data_input_file input.bin

Transfer with offset

[root@host]# dma-to-device --channel 0 --address 0xaa002000 --size 1024 --offset 512 --data_input_file input.bin

dma-from-device

Overview

The dma-from-device application enables Card-to-Host (C2H) data transfers using the MDB5 DMA driver. It provides a simple interface for transferring data from device memory to system memory.

Usage

dma-from-device [OPTIONS]

-c, --channel <INDEX>         Channel index, default 0
-a, --address <ADDRESS>       Address on the device memory
-s, --size <SIZE>             Size of a single transfer in bytes, default 32
-o, --offset <OFFSET>         Page offset of transfer, default 0
-w, --data_output_file <FILE> Optional output file to write transfer data
-h, --help                    Print usage help and exit
-v, --verbose                 Verbose output

Examples

Basic transfer

[root@host]# dma-from-device --channel 0 --address 0xaa002000 --size 1024

Transfer with file output

[root@host]# dma-from-device --channel 0 --address 0xaa002000 --size 4096 --data_output_file output.bin

dma-perf

Overview

The dma-perf application is a performance benchmarking utility designed to measure DMA throughput and performance on MDB5 DMA driver. It executes concurrent DMA transfers using asynchronous I/O (AIO), supports multi-process execution using configuration file.

Key features include:

  • Performance Measurement: Measures data transfer rates and packet throughput (packets per second and bandwidth)

  • Concurrent Operations: Supports simultaneous read and write operations across multiple channels

  • Scalable Testing: Multi-processexecution for comprehensive stress testing

  • Asynchronous I/O: Uses Linux AIO (libaio) for non-blocking operations

  • PCI Device Analysis: Optional PCIe device information dump via lspci for system characterization

Usage

dma-perf [OPTIONS]

-c, --config <FILE>  Configuration file specifying test parameters (REQUIRED)
-h, --help          Display usage help and exit
-v, --version       Display version information and exit

Configuration file format

The application requires a configuration file with performance test parameters:

name=mm_perf
chan_mode=mm             # <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       # Device memory address of PCIe BAR 2
runtime=30               # seconds (0 = unlimited)
num_process=1            # num of processes per channel
num_pkt=4              # count of pkt bursts
pkt_sz=4096
aperture_sz=0            # ignores if aperture_sz=0
dump_en=true             # <true / false> dumps lspci and stats at the end

Configuration parameters

  • name - Human-readable name for the test configuration

  • chan_mode - Channel mode (currently only mm supported)

  • pci_bus - PCIe bus number of the target device

  • pci_dev - PCIe device number on the bus

  • pf_range - PCI function range in format start:end (e.g., 0:0 for PF0 only, 0:3 for PF0-PF3)

  • ch_start_idx - Starting DMA channel index for this test

  • num_rd_channels - Number of read (C2H) channels to use for device-to-host transfers

  • num_wr_channels - Number of write (H2C) channels to use for host-to-device transfers

  • address - Device memory base address (PCIe BAR 2 register address)

  • runtime - Test duration in seconds (0 for unlimited runtime)

  • num_process - Number of worker processes per channel

  • num_pkt - Number of packet bursts submitted per I/O operation

  • pkt_sz - Size of each packet in bytes

  • aperture_sz - Aperture size for Scatter-Gather DMA mode (0 = disabled)

  • dump_en - Enable lspci dump and detailed performance statistics at test completion

For Write Operations (Host-to-Device):

WRITE: total pps = <packets_per_second> <bandwidth>

For Read Operations (Device-to-Host):

READ: total pps = <packets_per_second> <bandwidth>

Bandwidth is automatically displayed in the most appropriate unit (GB/sec, MB/sec, KB/sec, or Bytes/sec).

Example

[root@host]# dma-perf --config sample_mdb5_dma_perf_config.txt
...
dma transfer initiated
INFO: WRITE: total pps = 6678 INFO: BW = 14.005620 GB/sec