Getting Started

System Requirements

Host Platform

x86_64 host system with at least one Gen5 x4 PCIe slot
libaio must be installed to compile client apps

Host System Configuration

The MDB5-DMA driver release is verified on the following host system configuration:

Host System	Configuration Details
Operating System	Ubuntu 26.04 LTS
Linux Kernel	v7.0.6
PCIe Slot	Gen5 x4
RAM	8GB

Note

For optimal performance with 8 Read/Write Channels, it is recommended to have at least 8GB RAM on the same CPU node and a Gen5 x4 PCIe slot. However, the driver should function on any Linux distribution with the appropriate kernel version and required kernel configuration options enabled.

Build and Install

Controller Driver Setup

The AMD MDB5 support patches were merged into mainline Linux in v7.1-rc3. The setup path depends on the kernel version:

Current Kernel	Action Required
v7.1 or above	No patching needed. AMD MDB5 support is already built in.
Below v7.1	Build and install kernel v7.0.6 from source. Follow the steps below.

Kernel v7.1 or above

The MDB5-DMA sources are already part of the Linux kernel. so user does not need to patch the kernel separately. However, user must enable certain configurations in Linux kernel otherwise MDB5-DMA will not function. Verify the kernel configurations using the steps below.

Required Configuration Options

The following kernel configuration options must be enabled for MDB5-DMA to function properly:

CONFIG_DMA_ENGINE=y
CONFIG_PCI=y
CONFIG_PCI_MSI=y
CONFIG_DW_EDMA=y
CONFIG_DW_EDMA_PCIE=y

Checking Current Kernel Configuration

Check if the mentioned options are enabled in the current kernel configuration as follows:

$ cat /boot/config-`uname -r` | grep -E "^(CONFIG_DMA_ENGINE|CONFIG_PCI|CONFIG_PCI_MSI|CONFIG_DW_EDMA|CONFIG_DW_EDMA_PCIE)="
CONFIG_PCI=y
CONFIG_PCI_MSI=y
CONFIG_DMA_ENGINE=y
CONFIG_DW_EDMA=y
CONFIG_DW_EDMA_PCIE=y

If the output of the command matches as shown above (all options showing =y), the kernel is correctly configured. If any of the options are missing or show =n or =m from the output, those options must be enabled and the kernel recompiled to enable AMD-MDB5 functionality.

Configuration Options Explained

The following table describes each configuration option:

Configuration Option	Purpose
`CONFIG_DMA_ENGINE`	Enables the Linux DMA Engine framework for managing DMA controllers
`CONFIG_PCI`	Enables PCI bus support required for PCIe devices
`CONFIG_PCI_MSI`	Enables Message Signaled Interrupts support for PCIe devices
`CONFIG_DW_EDMA`	Enables DesignWare Enhanced DMA controller support
`CONFIG_DW_EDMA_PCIE`	Enables DesignWare Enhanced DMA PCIe endpoint support

Warning

MDB5-DMA will not function unless all required configuration options are enabled in the kernel. If any options are missing or disabled, the kernel must be recompiled and reinstalled with these options enabled.

Kernel Build from Source (Below v7.1)

On kernel versions below v7.1, the user must patch, build, and install kernel v7.0.6 from source. The patches are compiled directly into the kernel image. No out-of-tree module build is needed after rebooting.

Prerequisites

Install the tools required to build the kernel:

$ sudo apt-get install -y build-essential libncurses-dev bison flex libssl-dev libelf-dev dwarves zstd bc

Step 1: Download Kernel v7.0.6 Source

$ wget https://cdn.kernel.org/pub/linux/kernel/v7.x/linux-7.0.6.tar.xz
$ tar -xf linux-7.0.6.tar.xz
$ cd linux-7.0.6/

Step 2: Configure the Kernel

Use the current running kernel’s config as the base to preserve all existing settings:

$ cp /boot/config-$(uname -r) .config
$ make olddefconfig

Run the below steps to ensure the required DMA options are enabled:

$ scripts/config --enable CONFIG_DMA_ENGINE
$ scripts/config --enable CONFIG_DW_EDMA
$ scripts/config --enable CONFIG_DW_EDMA_PCIE
$ make olddefconfig

Run this command to verify the enabled options in config file:

$ grep -E "^(CONFIG_DMA_ENGINE|CONFIG_PCI|CONFIG_PCI_MSI|CONFIG_DW_EDMA|CONFIG_DW_EDMA_PCIE)=" .config
CONFIG_PCI=y
CONFIG_PCI_MSI=y
CONFIG_DMA_ENGINE=y
CONFIG_DW_EDMA=y
CONFIG_DW_EDMA_PCIE=y

Step 3: Apply AMD MDB5 Patches

$ wget -O 0001-dw-edma-add-amd-mdb-endpoint-support.patch https://lore.kernel.org/all/20260318070403.1634706-2-devendra.verma@amd.com/raw
$ wget -O 0002-dw-edma-add-non-ll-mode.patch https://lore.kernel.org/all/20260318070403.1634706-3-devendra.verma@amd.com/raw
$ patch -p1 -i 0001-dw-edma-add-amd-mdb-endpoint-support.patch
$ patch -p1 -i 0002-dw-edma-add-non-ll-mode.patch

Step 4: Build and Install the Kernel

$ make olddefconfig
$ make -j$(nproc)
$ sudo make modules_install
$ sudo make install

Step 5: Update GRUB and Reboot

$ sudo update-grub
$ sudo reboot

After reboot, verify the new kernel is running:

$ uname -r
# Should show: 7.0.6

The AMD MDB5 patches are now built into the kernel.

Client Driver Setup

The MDB5-DMA client driver must be compiled and installed to provide user-space applications with access to the DMA controller. This driver creates character device nodes that enable communication between user applications and the kernel-space controller driver.

To compile the client driver, navigate to the client driver directory and build the loadable kernel module:

$ cd <path-to-mdb5-ep-drivers>/client-driver
$ make

This command generates the client-driver loadable module, mdb5-dmaclient-drv.ko, which can be found in $(pwd)/bin/`uname -p`/mdb5-dmaclient-drv.ko and can be installed as follows:

$ modprobe ./bin/`uname -p`/mdb5-dmaclient-drv.ko device_dbdf="0000:01:00.0" dma_dev_id=1

device_dbdf = “Domain:Bus:Device.Function”
dma_dev_id = Unique index the Linux kernel uses to register DMA channels in the format dma<dma_dev_id>chan<index>

The dma_dev_id can be found using the following command:

find /sys -name "dma*" | grep "Domain:Bus:Device.Function"

Client Apps Setup

The MDB5-DMA client applications provide command-line utilities for configuring, testing, and managing DMA transfers. These applications require compilation and have dependencies that must be satisfied before building.

First, ensure that libaio development libraries are installed on Ubuntu-based systems:

$ apt -y install libaio-dev

Then compile the client applications:

$ cd <path-to-mdb5-ep-drivers>/client-apps
$ make

This command generates the DMA user-space applications in the following directory:

$ ls <path-to-mdb5-ep-drivers>/client-apps/bin
  dma-ctl dma-from-device dma-to-device dma-xfer