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

Note

The current release of the MDB5-DMA client driver does not support the APIs for performance related measurements.