A few months ago, iWave Global lent me a development board based on a Versal VC2302, the IG-G57D, and I used it for several projects, including one where I used the DMA to share data between the PL and the PS: Using the AXI DMA on Versal with the pyxdma driver. In that article, the PS sends a signal through an AXI DMA, the xFFT IP computes its spectrum in the PL, and the result comes back to the DDR. Everything was driven from a Jupyter notebook with pyxdma over UIO. That approach is perfect for bring-up. You iterate fast, you do not rebuild the kernel, and if something goes wrong the worst thing that can happen is that your Python process dies. But it has some limitations that I did not hide in that article: the DDR buffers are reserved by hand in the device tree, they are mapped through /dev/mem, so the notebook has to run as root, and the completion of the transfer is detected by polling a status register.

The proper way to drive a PL peripheral from Linux is a kernel driver. The driver owns the registers, the DMA buffers and the interrupt, and user space is reduced to opening a file and calling write() and read(). In this article I want to show you how I wrote that driver for Linux 6.12 (the kernel shipped with PetaLinux 2025.1) on the iWave iG-G57M Versal AI Edge SOM, how to package it with PetaLinux, and the problem that kept me a good while staring at a /proc/interrupts counter stuck at zero: on Versal, the interrupt number that the device tree generator writes is not necessarily the one you wired.

Table of contents

User space or kernel space

Before writing a single line of C, it is worth being honest about what we gain and what we lose. A user-space driver over UIO is not a bad driver, it is just a different trade-off. The table summarizes the differences I found between the pyxdma flow and the kernel driver of this article.

  User space (UIO / pyxdma) Kernel driver
Completion polling the status register interrupt + wait_for_completion
DMA buffers reserved-memory with no-map, mapped through /dev/mem dma_alloc_coherent at probe time
Concurrency none a mutex in the driver
Access root, /dev/mem exposes all the RAM a narrow /dev/xdma device
Development fast, a crash kills a process kernel module rebuild, a bug is an oops
Kernel version independent tied to the kernel API

My rule is simple: user space to prototype, kernel space to ship. While the hardware changes every day, rebuilding a kernel module is a waste of time; once it is stable, the kernel is the right place for the logic.

The datapath is exactly the same as in the pyxdma article: DDR --MM2S--> AXI DMA --> xFFT --> AXI DMA --S2MM--> DDR, with a 32-bit AXI DMA in direct register mode (no scatter-gather) and a 1024-point scaled FFT. The only change in the hardware is the interrupts.

Wiring the DMA interrupts on Versal

In the previous design the mm2s_introut and s2mm_introut outputs of the AXI DMA were left unconnected, because pyxdma polls the status registers. Now we want the DMA to tell the processor when a transfer is finished, so these two outputs have to reach the GIC of the APU.

On Versal, the PL-to-PS interrupts are enabled in the CIPS configuration, under PS PMC > Interrupts & Errors. There are 16 lines, grouped as IRQ 0 to 7 in the LPD and IRQ 8 to 15 in the FPD. For this design I enabled IRQ 8, which adds the pl_ps_irq8 port to the CIPS.

CIPS PS PMC configuration, Interrupts and Errors page, with the PL to PS interrupt IRQ 8 enabled in the FPD group

The two interrupt outputs of the AXI DMA are combined with an Inline Concat IP, and its dout[1:0] output is connected to pl_ps_irq8. The rest of the block design is the same one we built in the pyxdma article: the CIPS, the AXI NoC with the S06_AXI slave for the DMA data and the M00_AXI master for the register bank, the two AXI SmartConnect and the xFFT.

Versal block design with the AXI DMA interrupt outputs combined by an Inline Concat and connected to the pl_ps_irq8 port of the CIPS

After generating the bitstream and exporting the XSA, the hardware is ready. The interesting part, and the part that hurts, comes in the device tree.

The platform driver

The driver is an out-of-tree platform driver in two files: xdma.h, with the register map of PG021 and the driver state, and xdma_main.c, with the probe, the character device and the interrupt handler. None of the functions of the driver is called by name. Each one is reached through a pointer stored in a kernel structure (xdma_driver, xdma_fops) or passed to a registration function, so the table also shows who calls each one.

Function Called by What it does
xdma_probe() the platform bus, when a device tree node matches controlpaths,xdma-1.0 Takes ownership of the hardware: maps the registers, sets the 32-bit DMA mask, allocates the coherent buffers, requests the interrupts and registers /dev/xdma
xdma_remove() the platform bus, when the device is unbound (for example, on rmmod) Deregisters /dev/xdma; everything else is released automatically by the managed APIs
xdma_open() the VFS, on open("/dev/xdma") Stores a pointer to the xdma_device in the file, so read() and write() can find it
xdma_write() the VFS, on write() Copies the input into the TX buffer, programs S2MM and MM2S, and sleeps until the S2MM interrupt or a 1000 ms timeout
xdma_read() the VFS, on read() Copies the result of the last transfer from the RX buffer to user space
xdma_irq() the kernel IRQ core, when the DMA raises an interrupt line Clears the pending flags of both channels and wakes up the waiting write()
xdma_reset() xdma_write(), before each transfer Soft-resets both channels and waits for the reset bit to self-clear
xdma_ior() / xdma_iow() the rest of the driver Read and write a 32-bit DMA register at a given offset

The VFS (Virtual File System) is the kernel layer that receives the file system calls from user space and forwards them to whoever owns the file. The same write() ends up in ext4 for a file on the SD card and in our driver for /dev/xdma, because misc_register() tells the VFS which file_operations to use for that device.

The driver targets Linux 6.12 LTS, and this is not a detail. Since kernel 6.11, the remove callback of struct platform_driver returns void instead of int. If you are porting an older driver, this is the first thing that breaks the build, and the reason why this one will not compile as is against older kernels.

static void xdma_remove(struct platform_device *pdev)
{
	struct xdma_device *xdev = platform_get_drvdata(pdev);

	misc_deregister(&xdev->misc);
	dev_info(&pdev->dev, "xdma removed\n");
}

static const struct of_device_id xdma_of_match[] = {
	{ .compatible = "controlpaths,xdma-1.0" },
	{ /* sentinel */ }
};
MODULE_DEVICE_TABLE(of, xdma_of_match);

static struct platform_driver xdma_driver = {
	.probe = xdma_probe,
	.remove = xdma_remove,		/* returns void: kernel >= 6.11 */
	.driver = {
		.name = "xdma",
		.of_match_table = xdma_of_match,
	},
};
module_platform_driver(xdma_driver);

If you come from bare-metal, the most confusing part of a Linux driver is that nobody calls it directly. Loading the module does not touch the hardware at all. module_platform_driver() only registers xdma_driver with the platform bus, saying “I know how to handle devices whose compatible is controlpaths,xdma-1.0”. On the other side, during boot the kernel parses the device tree and creates a platform_device for each node, with its registers and interrupts already decoded from reg and interrupts. The bus core is the one that matches both lists, and when the compatible of a device matches an entry of of_match_table, it calls the probe() function of the driver, passing it that platform_device. It does not matter which one appears first; when the module is loaded the kernel checks the existing devices, and when a new device appears it checks the registered drivers.

probe() is where the driver takes ownership of the hardware. In xdma_probe() this means allocating the per-device state (struct xdma_device), mapping the register bank, setting the DMA mask, allocating the coherent buffers, requesting the interrupts, and finally registering /dev/xdma. If it returns 0, the device is bound to the driver. If it returns an error, the kernel considers that the driver could not handle the device and nothing is created, which is why every step of the probe returns as soon as something fails. And since the state is allocated inside the probe and not as a global variable, the function is called once per matching node: with two AXI DMAs in the device tree using the same compatible, the probe would run twice, each one with its own xdma_device. (In this version the character device is always named xdma, so the second probe would fail when registering it; supporting several DMAs would only need a different name per instance.)

remove() is the counterpart of the probe, and it is called when the device is unbound, for example when the module is unloaded. Notice how short it is. Almost everything in the probe uses the managed (devm_ and dmam_) versions of the kernel APIs, so the register mapping, the buffers and the interrupts are released automatically when the device is detached. The only thing left to undo by hand is the character device.

Binding through the device tree

By default, the device tree generator binds the AXI DMA node to the in-kernel xilinx_dma driver, which exposes it through the DMA engine API. In the pyxdma article we replaced its compatible with generic-uio. Now we replace it with our own string, so neither xilinx_dma nor UIO claims the node, and the kernel calls our probe() instead. The override goes into system-user.dtsi:

&axi_dma_0 {
    compatible = "controlpaths,xdma-1.0";
};

(This is not the final version of the node; we will come back to it in a moment.)

The probe gets the register bank with devm_platform_get_and_ioremap_resource(). On Versal, the bank sits at a high NoC address, 0x201_0000_0000 in this design, but the driver does not hardcode it anywhere. It comes from the reg property of the node generated in pl.dtsi, so the same driver works on a Zynq UltraScale+ with the DMA on an HPM port without touching a line.

Coherent buffers

This is where the kernel driver really simplifies things. In the UIO flow we declared two reserved-memory regions with no-map, chose their physical addresses by hand inside the 32-bit window, and mapped them from Python through /dev/mem. In the driver, the buffers are requested from the kernel at probe time:

/* 32-bit AXI DMA: keep coherent buffers in the low 4 GB it can address. */
ret = dma_set_mask_and_coherent(&pdev->dev, DMA_BIT_MASK(32));
if (ret)
	return dev_err_probe(&pdev->dev, ret,
			     "no usable 32-bit DMA mask\n");

xdev->buf_size = XDMA_BUF_SIZE;
xdev->tx_buf = dmam_alloc_coherent(&pdev->dev, xdev->buf_size,
				   &xdev->tx_dma, GFP_KERNEL);
if (!xdev->tx_buf)
	return -ENOMEM;

dmam_alloc_coherent() returns two addresses for the same buffer. tx_buf is a kernel virtual pointer, the one the CPU uses to copy the data from user space. tx_dma is the bus address, the one the M_AXI_MM2S master of the DMA sees, and it is the value that is written into the DMA registers. Never a CPU pointer. The buffer is also coherent, so the CPU and the DMA see the same data without any manual flush or invalidate of the caches, which is exactly what the no-map carve-out was faking by hand.

The DMA mask is the other half of the trick. Our AXI DMA uses 32-bit addresses, so it can only reach the low 4 GB. Telling the kernel the mask with dma_set_mask_and_coherent() makes it choose a valid address for us, instead of us choosing one and hoping nothing else lands there. Each channel gets a buffer of XDMA_BUF_SIZE, 64 KB, which is more than enough for the 4 KB of a 1024-sample frame. No reserved-memory, no /dev/mem, no root, and no cache handling in user space.

The write() and read() interface

The driver registers a misc device, /dev/xdma, and the interface is deliberately minimal. write() runs a complete transfer: it copies the input into the TX buffer, programs the DMA, and blocks until the result has landed in the RX buffer. read() returns that result. All the register handling lives inside write():

ret = xdma_reset(xdev);
if (ret)
	goto out;

reinit_completion(&xdev->s2mm_done);

/* Arm S2MM (receiver) first so it is ready before MM2S emits data. */
xdma_iow(xdev, XDMA_S2MM_DMACR,
	 XDMA_DMACR_RS | XDMA_DMACR_IOC_IRQ_EN | XDMA_DMACR_ERR_IRQ_EN);
xdma_iow(xdev, XDMA_S2MM_DA, lower_32_bits(xdev->rx_dma));
xdma_iow(xdev, XDMA_S2MM_LENGTH, len);

/* Trigger MM2S (transmitter): writing LENGTH starts the transfer. */
xdma_iow(xdev, XDMA_MM2S_DMACR,
	 XDMA_DMACR_RS | XDMA_DMACR_IOC_IRQ_EN | XDMA_DMACR_ERR_IRQ_EN);
xdma_iow(xdev, XDMA_MM2S_SA, lower_32_bits(xdev->tx_dma));
xdma_iow(xdev, XDMA_MM2S_LENGTH, len);

/* Block until the ISR (xdma_irq) signals S2MM completion. */
if (!wait_for_completion_timeout(&xdev->s2mm_done,
				 msecs_to_jiffies(XDMA_TIMEOUT_MS))) {
	dev_err(xdev->dev, "transfer timeout (S2MM_DMASR=0x%08x)\n",
		xdma_ior(xdev, XDMA_S2MM_DMASR));
	ret = -ETIMEDOUT;
	goto out;
}

The sequence is the same one pyxdma follows, and it is the one described in PG021 for direct register mode. First, xdma_reset() sets the reset bit in both DMACR registers and waits for it to self-clear. Then the S2MM channel is armed: run/stop bit, interrupt on complete and interrupt on error enabled, destination address and length. Writing S2MM_LENGTH arms the channel. Only after that, the MM2S channel is configured the same way, and writing MM2S_LENGTH starts the transfer. As I explained in the pyxdma article, arming the receiver first is not a detail: if the MM2S starts pushing samples before the S2MM has a length programmed, the xFFT output stalls on tready.

The difference with pyxdma is the last block. Instead of polling S2MM_DMASR, the process sleeps on a completion, and the CPU is free to run anything else until the interrupt handler wakes it up. If the interrupt does not arrive within 1000 ms, write() prints the status register and returns -ETIMEDOUT. Keep that error message in mind. The whole transfer and its read-back are protected by a mutex, so two processes opening /dev/xdma at the same time cannot mix their transfers. The driver also rejects lengths that are zero, not a multiple of 4 bytes, or bigger than the buffer.

On the other side, the user-space code is now almost nothing. Compared with the UIO notebook, where we had the whole pyxdma class, the addresses of the reserved buffers and the configuration calls, the kernel notebook only needs to open the device, write the samples and read the result:

fd = os.open("/dev/xdma", os.O_RDWR)

tx = struct.pack("<%dI" % len(tx_words), *tx_words)
os.write(fd, tx)        # MM2S -> xFFT -> S2MM, waits on the IRQ in the kernel

rx = b""
while len(rx) < len(tx):
    chunk = os.read(fd, len(tx) - len(rx))
    if not chunk:
        break
    rx += chunk

rx_words = list(struct.unpack("<%dI" % (len(rx) // 4), rx))

The packing of the Q15 samples and the processing of the result are the same as in the pyxdma article. And since the driver only uses standard file operations, any language that can open a file can use it.

The interrupt handler

The AXI DMA has one interrupt output per channel, both active-high level. In the probe, each line is requested by name with platform_get_irq_byname_optional() and devm_request_irq(). They are optional on purpose: if the interrupts are not wired in the block design, the probe still succeeds and prints a warning saying that transfers will time out, which is much easier to debug than a probe that silently fails.

Both lines share the same handler:

static irqreturn_t xdma_irq(int irq, void *data)
{
	struct xdma_device *xdev = data;
	irqreturn_t ret = IRQ_NONE;
	u32 sr;

	sr = xdma_ior(xdev, XDMA_MM2S_DMASR);
	if (sr & XDMA_DMASR_IRQ_MASK) {
		xdma_iow(xdev, XDMA_MM2S_DMASR, sr & XDMA_DMASR_IRQ_MASK);
		if (sr & XDMA_DMASR_ERR_MASK)
			dev_err(xdev->dev, "MM2S error (DMASR=0x%08x)\n", sr);
		complete(&xdev->mm2s_done);
		ret = IRQ_HANDLED;
	}

	sr = xdma_ior(xdev, XDMA_S2MM_DMASR);
	if (sr & XDMA_DMASR_IRQ_MASK) {
		xdma_iow(xdev, XDMA_S2MM_DMASR, sr & XDMA_DMASR_IRQ_MASK);
		if (sr & XDMA_DMASR_ERR_MASK)
			dev_err(xdev->dev, "S2MM error (DMASR=0x%08x)\n", sr);
		complete(&xdev->s2mm_done);
		ret = IRQ_HANDLED;
	}

	return ret;
}

The handler checks the DMASR of both channels, clears the pending flags (interrupt on complete, delay and error, all write-1-to-clear), and signals the matching completion. Since the interrupts are level-sensitive, clearing the flag is mandatory; otherwise the line stays high and the handler is called again and again. The handler returns IRQ_NONE when neither channel had a pending flag, so the kernel can detect a spurious interrupt.

Packaging the module with PetaLinux

The module can be compiled out of tree with the PetaLinux toolchain, but I prefer to have it inside the image, so it is built with the kernel and loaded at boot. PetaLinux creates the recipe skeleton with one command:

petalinux-create -t modules --name xdma --enable

This creates project-spec/meta-user/recipes-modules/xdma/ and adds CONFIG_xdma to the rootfs configuration. The sources go flat into its files/ folder: xdma_main.c, xdma.h, the Makefile and the LICENSE. The recipe lists them, and has one extra line at the end that I strongly recommend:

SUMMARY = "Kernel-space driver for the AMD/Xilinx AXI DMA IP"
LICENSE = "GPL-2.0-only"
LIC_FILES_CHKSUM = "file://LICENSE;md5=db45a792620eddcd7a418868d1e73f29"

inherit module

SRC_URI = "file://Makefile \
           file://xdma_main.c \
           file://xdma.h \
           file://LICENSE \
          "
S = "${WORKDIR}"

KERNEL_MODULE_AUTOLOAD += "xdma"

KERNEL_MODULE_AUTOLOAD creates /etc/modules-load.d/xdma.conf in the root filesystem, so the module is loaded at boot and probe() runs during the startup, with /dev/xdma ready when you log in.

The Makefile has its own trap. A pure kbuild Makefile, with just the obj-m line, works when you build the module with make -C <kernel> M=<dir> modules, but the Yocto module class runs make directly in the source folder with KERNEL_SRC set, and it expects the all, modules_install and clean targets. Without them, the build fails with make: No targets. This version works in both cases:

obj-m := xdma.o
xdma-objs := xdma_main.o

KERNEL_SRC ?= /lib/modules/$(shell uname -r)/build
SRC := $(shell pwd)

all:
	$(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules

modules_install:
	$(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install

clean:
	$(MAKE) -C $(KERNEL_SRC) M=$(SRC) clean

With this, petalinux-build builds the module together with the rest of the image. After booting the board, the driver introduces itself in the kernel log, and the device is there:

root@versal-iwg57m:~# dmesg | grep controlpaths
[    7.112032] xdma 20100000000.dma: controlpaths xdma driver ready - AXI DMA at [mem 0x20100000000-0x2010000ffff] (irq mm2s=38 s2mm=40)
root@versal-iwg57m:~# ls /dev | grep xdma
xdma

The register bank is at the high NoC address, and both interrupts have a valid Linux IRQ number. Everything looks fine. And then the first write() returns -ETIMEDOUT.

The interrupt that never fired

This is the part of the article I would have liked to read before starting. The driver probed correctly, the interrupt handlers were registered, and every transfer timed out after one second. The first thing to check in this situation is /proc/interrupts, and it showed both xdma lines registered, with a counter that stayed at zero no matter how many transfers I launched. The interrupt was described in the device tree, Linux was listening to it, but it was never delivered.

The reason is in the pl.dtsi generated from the XSA. The device tree generator wrote the interrupts of the DMA node as <0 84 4> and <0 85 4>, which correspond to pl_ps_irq0 and pl_ps_irq1. But in this design the DMA is wired to pl_ps_irq8. On Versal the PL-PS interrupts have a fixed mapping to the GIC shared peripheral interrupts:

CIPS pin Device tree SPI GIC interrupt
pl_ps_irq0 84 116
pl_ps_irq1 85 117
… … …
pl_ps_irq8 92 124
pl_ps_irq9 93 125

The device tree number is the SPI index, and the GIC adds 32 to it, which is the number you see in /proc/interrupts. The generator assigned the interrupts starting from the base of the range, without taking into account that the lines enabled in the CIPS start at channel 8. So Linux was listening on GIC 116 and 117 while the DMA was raising GIC 124. The kernel had no reason to complain: SPI 84 is a perfectly valid interrupt, it just has nothing connected.

There are two ways to fix it. The fast one is to override the interrupts of the node in system-user.dtsi, pointing it to the SPIs that are actually wired. The third cell, 4, is IRQ_TYPE_LEVEL_HIGH, and interrupt-names is what platform_get_irq_byname_optional() uses to find each line:

&axi_dma_0 {
    compatible = "controlpaths,xdma-1.0";
    interrupts = <0 92 4>, <0 93 4>;          /* pl_ps_irq8/9 -> GIC 124/125, level-high */
    interrupt-names = "s2mm_introut", "mm2s_introut";
};

The clean one is to fix the root cause in the hardware: enable IRQ 0 in the CIPS instead of IRQ 8 and wire the DMA interrupts there. Then the default numbering of the generator matches the hardware and no override is needed. This is why most reference designs start at pl_ps_irq0, and in a new design I would do exactly that. For this one I kept the override, since it does not require regenerating the hardware, and it leaves the problem documented in the device tree, right next to the node.

The lesson I took from this is that a registered interrupt is not a delivered interrupt. A valid IRQ number in dmesg only means that the kernel parsed the device tree. The proof that the interrupt arrives is the counter in /proc/interrupts, and on Versal the SPI in the device tree must match the pl_ps_irq pin you actually wired. The generated pl.dtsi is a good starting point, but it is not the truth.

Results

With the corrected device tree, after booting the board and before running any transfer, /proc/interrupts shows the two lines of the driver now on GIC 124 and 125:

root@versal-iwg57m:~# cat /proc/interrupts | grep xdma
 38:          0          0     GICv3 125 Level     xdma-mm2s
 40:          0          0     GICv3 124 Level     xdma-s2mm

After running the notebook, which launches one transfer of 1024 samples, the S2MM counter has incremented, which means that the write() was woken up by the interrupt and not by the timeout:

root@versal-iwg57m:~# cat /proc/interrupts | grep xdma
 38:          0          0     GICv3 125 Level     xdma-mm2s
 40:          1          0     GICv3 124 Level     xdma-s2mm

The spectrum computed through /dev/xdma is the same one we got with pyxdma: the four tones of the test signal appear in bins 1, 16, 18 and 34, with amplitudes 0.5, 0.1, 0.05 and 0.02. That confirms that the coherent buffers allocated by the kernel are reachable by the 32-bit DMA through the NoC, and that the CPU and the DMA see the same data without any cache maintenance.

Stem plot of the FFT magnitude showing peaks of 0.5 at bin 1, 0.1 at bin 16, 0.05 at bin 18 and 0.02 at bin 34

Conclusions

Moving the AXI DMA into the kernel did not change a single bit of the datapath, but it changed who is responsible for it, and this is where the power of the DMA really shows up. Without a DMA, the processor would have to read every sample from memory and write it into the PL, and then do the same in the opposite direction, so the CPU would be busy during the whole transfer. With the DMA, the processor only writes three registers per channel, control, address and length, and then it is out of the process. The data goes from the DDR to the xFFT and back without the CPU touching a single sample. And with the interrupt, the processor is not even polling a status register: the process sleeps inside write(), and the CPU is free to run anything else until the S2MM channel says that the result is in memory.

The kernel driver takes the same idea one level up, to the user. In the pyxdma flow, the notebook had to know the physical addresses of the buffers, the register map of the DMA and the order in which the channels have to be armed. Now all of that lives in the driver: the registers, the coherent buffers allocated with dma_alloc_coherent(), the cache coherency and the interrupt. From the point of view of the user, the AXI DMA, the NoC and the xFFT have disappeared, and computing a spectrum is just writing the samples into a peripheral and reading the result back, with the same write() and read() you would use with any file. No reserved-memory, no /dev/mem and no root. In my opinion, this is how an accelerator should be used. The price is the usual one of kernel code: a bug is an oops instead of a Python exception, and the driver is tied to the kernel API, as the remove() returning void since 6.11 shows.

The next natural step is scatter-gather. With the direct register mode used here, each write() is one transfer and one interrupt, which is fine for FFT frames but limits the throughput when the data comes continuously. A descriptor ring in coherent memory, and an interrupt every N descriptors, is where a kernel driver really starts to make the difference over user space.

The code of this article is uploaded to Github, and the driver is available in its own repository, xdma_kernel_driver.