« PREV_LECNEXT_LEC »

What Is a DMA Channel Filter Function in Linux?

A DMA channel filter function is a small callback that the DMA engine core calls once for every free channel in the system while it is looking for a channel on your behalf. Your job inside that callback is simple: look at the channel that was handed to you, decide whether it is the one your driver actually needs, and return true or false. The core keeps calling the filter on the next free channel until one returns true, and that channel becomes yours.

This mechanism exists because a capability mask alone (memcpy, slave transfer, cyclic, and so on) is often not specific enough. Two DMA controllers on the same SoC can both support DMA_SLAVE, but only one of them is physically wired to your UART or your audio codec. The filter function is how the driver tells the framework “not just any slave channel — this exact one.”

Why the Kernel Needs Filter Functions for DMA Channel Selection

Before Device Tree became the standard way to describe hardware, board files carried private data structures that told a driver which DMA request line, priority, or peripheral type to use. The filter function was the bridge between that board-specific data and the generic dmaengine core, which knows nothing about individual SoCs. You would pack your private data into a small struct, pass its pointer as the filter_param argument, and let your filter callback compare it against fields stored on the channel’s private data.

Even today, this pattern is useful whenever a board is not fully described through Device Tree, or when a driver still supports legacy non-DT platforms alongside newer DT-based ones. Understanding it also makes the newer, simpler DT-based API easier to appreciate, since dma_request_chan() effectively builds a matching filter for you behind the scenes from the “dmas” and “dma-names” properties in your device node.

dma_request_channel() vs the Modern dma_request_chan() API

Lecture lddch12_4 introduced dma_request_chan() as the preferred, Device-Tree-aware way to obtain a slave channel. The table below places it side by side with the older filter-based interface so you can see exactly where a Linux DMA channel filter function is still relevant.

Writing a Custom DMA Filter Callback

A filter function has a fixed signature defined by the dmaengine core: it takes the candidate channel and an opaque parameter, and returns a boolean. Inside the function you typically stash your matching criteria in the channel’s private field, or compare against something the platform layer already attached to the channel structure. Here is a minimal, original filter callback used purely for teaching:

#include <linux/dmaengine.h>

/* Private data we use to identify "our" channel */
struct ep_dma_filter_param {
	int req_line;   /* logical DMA request line for our peripheral */
};

static bool ep_dma_filter(struct dma_chan *chan, void *param)
{
	struct ep_dma_filter_param *p = param;

	/* chan->private is set by the controller driver to something
	 * it understands (often a request-line or peripheral id).
	 * We just compare the pointer value we were handed. */
	if (chan->private && (long)chan->private == p->req_line)
		return true;

	return false;
}

Notice the function does nothing more than answer a yes/no question. All the heavy lifting — walking the channel list, honoring the capability mask, marking the channel exclusive — is handled by the dmaengine core inside dma_request_channel().

Building a Complete DMA Filter Demo Driver

Let us put the filter function to work inside a small, original platform driver. This example requests a memcpy-capable channel, copies a known pattern from a source buffer to a destination buffer, and confirms completion with a struct completion, exactly the pattern covered in lddch12_3, now combined with filter-based channel selection.

#include <linux/module.h>
#include <linux/platform_device.h>
#include <linux/dmaengine.h>
#include <linux/dma-mapping.h>
#include <linux/completion.h>
#include <linux/slab.h>

#define EP_BUF_SIZE 256

struct ep_dma_filter_param ep_param = { .req_line = 7 };

static struct dma_chan *ep_chan;
static struct completion ep_done;
static void *ep_src, *ep_dst;
static dma_addr_t ep_src_dma, ep_dst_dma;

static void ep_dma_callback(void *arg)
{
	complete(&ep_done);
}

static int ep_dma_run_transfer(struct device *dev)
{
	struct dma_async_tx_descriptor *tx;
	dma_cookie_t cookie;

	tx = dmaengine_prep_dma_memcpy(ep_chan, ep_dst_dma, ep_src_dma,
					EP_BUF_SIZE, DMA_PREP_INTERRUPT);
	if (!tx) {
		dev_err(dev, "ep_dma: failed to get descriptor\n");
		return -EIO;
	}

	tx->callback = ep_dma_callback;
	tx->callback_param = NULL;

	cookie = dmaengine_submit(tx);
	if (dma_submit_error(cookie))
		return -EIO;

	reinit_completion(&ep_done);
	dma_async_issue_pending(ep_chan);

	if (!wait_for_completion_timeout(&ep_done, msecs_to_jiffies(2000))) {
		dev_err(dev, "ep_dma: transfer timed out\n");
		return -ETIMEDOUT;
	}

	dev_info(dev, "ep_dma: transfer completed, cookie=%d\n", cookie);
	return 0;
}

static int ep_dma_probe(struct platform_device *pdev)
{
	dma_cap_mask_t mask;
	int ret;

	dma_cap_zero(mask);
	dma_cap_set(DMA_MEMCPY, mask);

	ep_chan = dma_request_channel(mask, ep_dma_filter, &ep_param);
	if (!ep_chan) {
		dev_err(&pdev->dev, "ep_dma: no channel matched the filter\n");
		return -ENODEV;
	}

	dev_info(&pdev->dev, "ep_dma: got channel %s\n",
		 dma_chan_name(ep_chan));

	ep_src = kzalloc(EP_BUF_SIZE, GFP_KERNEL);
	ep_dst = kzalloc(EP_BUF_SIZE, GFP_KERNEL);
	if (!ep_src || !ep_dst) {
		ret = -ENOMEM;
		goto err_release;
	}

	memset(ep_src, 0xAB, EP_BUF_SIZE);

	ep_src_dma = dma_map_single(ep_chan->device->dev, ep_src,
				     EP_BUF_SIZE, DMA_TO_DEVICE);
	ep_dst_dma = dma_map_single(ep_chan->device->dev, ep_dst,
				     EP_BUF_SIZE, DMA_FROM_DEVICE);

	init_completion(&ep_done);

	ret = ep_dma_run_transfer(&pdev->dev);

	dma_unmap_single(ep_chan->device->dev, ep_src_dma,
			  EP_BUF_SIZE, DMA_TO_DEVICE);
	dma_unmap_single(ep_chan->device->dev, ep_dst_dma,
			  EP_BUF_SIZE, DMA_FROM_DEVICE);

	if (!ret && !memcmp(ep_src, ep_dst, EP_BUF_SIZE))
		dev_info(&pdev->dev, "ep_dma: data verified OK\n");
	else
		dev_warn(&pdev->dev, "ep_dma: data mismatch or error\n");

	return 0;

err_release:
	dma_release_channel(ep_chan);
	return ret;
}

static int ep_dma_remove(struct platform_device *pdev)
{
	kfree(ep_src);
	kfree(ep_dst);
	dma_release_channel(ep_chan);
	dev_info(&pdev->dev, "ep_dma: channel released\n");
	return 0;
}

static struct platform_driver ep_dma_driver = {
	.probe = ep_dma_probe,
	.remove = ep_dma_remove,
	.driver = {
		.name = "ep_dma_filter_demo",
	},
};
module_platform_driver(ep_dma_driver);

MODULE_LICENSE("GPL");
MODULE_DESCRIPTION("EmbeddedPathashala DMA filter function demo");

In a real board this driver would be bound through a matching platform device (either registered in board code for legacy setups or matched via Device Tree compatible string). The req_line value inside ep_param is intentionally simple here so you can adapt the comparison to whatever your own DMA controller driver stores in chan->private.

Compiling and Running the Filter Demo on Your Board

Build the module the same way we have throughout this free embedded Linux course, against your target kernel headers:

make -C /lib/modules/$(uname -r)/build M=$(pwd) modules

Load it and register a matching platform device (or bind it through your board’s DT overlay), then watch the kernel log:

sudo insmod ep_dma_filter_demo.ko
dmesg | tail -n 6

On a board that actually has a DMA_MEMCPY-capable channel available, you should see output similar to this:

[  102.114213] ep_dma: got channel dma0chan0
[  102.116502] ep_dma: transfer completed, cookie=1
[  102.116540] ep_dma: data verified OK

If your board has no free memcpy channel, or the filter never returns true, dma_request_channel() returns NULL and you will see the “no channel matched the filter” message instead — that is expected behavior, not a bug, and it is exactly the safety net the filter mechanism is meant to provide.

Common Mistakes When Using DMA Filter Functions

Three mistakes come up again and again when engineers new to the Linux DMA channel filter function mechanism write their first driver:

• Forgetting to zero and set the capability mask with dma_cap_zero()/dma_cap_set() before calling dma_request_channel(), which leaves the mask holding garbage from the stack.
• Comparing against chan->private without first confirming the underlying DMA controller driver actually populates that field — not every driver does.
• Never calling dma_release_channel() on the error and remove paths, which leaves the channel marked exclusive and unusable by any other driver until reboot.

Frequently Asked Questions

« PREV_LECNEXT_LEC »