Linux DMA驱动开发核心：映射机制与cache一致性实践

做Linux下的驱动开发，绕不开DMA。只要涉及数据搬运，特别是大数据量、高吞吐的场景，比如网络收包、存储读写、串口/SPI高速传输，DMA几乎都是标配。但DMA这块的知识点非常零散，接口多、概念绕，还牵扯到cache一致性这类底层细节，很多新手上来就被dma_alloc_coherent、dma_map_single这些API搞晕。这个系列我打算把Linux DMA开发从头到尾捋一遍，第一篇先啃最核心的骨架：DMA是什么、内核里DMA映射机制怎么运作、dmaengine框架怎么用，以及调试DMA问题时最该从哪下手。

写这篇内容之前，我先说下适合谁来读。如果你是做嵌入式Linux驱动开发的，或者正被设备树里的dma属性、驱动里的DMA中断、数据偶尔乱码这些事折磨，这篇内容应该能帮你省不少时间。如果你只是天天写应用层代码，想了解DMA到底是怎么回事，也能看，前提是至少知道物理地址、虚拟地址、内核驱动模块是怎么回事。

1. 从一次数据搬运说起：Linux DMA的核心问题和设计思路

1.1 DMA表面上解决的是CPU占用问题，实际上牵扯出一整套地址转换机制

DMA的字面意思就是直接内存访问。没有DMA的时候，CPU要搬运一块数据，得自己去读源地址、写入目的地址，循环一遍。以串口为例，假设外设每秒产生几万个字节，CPU如果每次都用中断去处理单个字节，那CPU基本什么都干不了了，全在响应中断、搬数据。

有了DMA，事情就变成：CPU把源地址、目的地址、搬运长度告诉DMA控制器，然后DMA控制器自己去搬，搬完了提个中断告诉CPU“我干完了”。这个过程里CPU只负责配置DMA和接收完成中断。在大数据量场景，节省的CPU资源非常可观。

问题在于：Linux下，驱动里拿到的地址不是咱们平时在应用层理解的那个地址。内核里一个缓冲区可能有三种地址属性：

在没有IOMMU的简单平台上，总线地址几乎等价于物理地址。但一旦有IOMMU、有总线桥、或者有复杂的地址映射关系，总线地址和物理地址可以是完全不同的值。设备寄存器里填写的DMA地址，是设备视角的地址，必须通过内核DMA API来获取，而不能直接把物理地址填进去。

这就是Linux DMA开发的第一个核心认知：驱动里不能随便拿物理地址去配置DMA，必须调用内核提供的DMA映射API。这个API系列会帮你处理缓存一致性、IOMMU映射、总线地址转换，而不仅仅是“拿到一个地址”这么简单。

1.2 缓存一致性：DMA开发里最容易出诡异Bug的根源

在ARM、x86这类带高性能CPU的平台上，CPU和DMA控制器看到的内存不是一致的。CPU读写内存，通常会经过cache，读的时候如果cache命中，根本不会访问真正的物理内存。DMA控制器则直接访问物理内存，不经过cache。

举个例子。你在驱动里申请了一块缓冲区，往里面写了一串数据，然后启动DMA发送。如果CPU写入的数据还停留在cache里，没有回写到物理内存，DMA去搬运的时候，搬走的可能是旧数据。反过来，DMA把外设数据放进了内存，CPU去读的时候，如果cache里还留着旧数据，CPU读到的就是垃圾数据。

这个问题处理不好，表现就是数据偶尔错、偶尔对，完全随机，特别难排查。所以Linux内核提供了一致性DMA映射和流式DMA映射两套机制来处理cache问题。我下面会花大篇幅讲这两套机制，因为它们是Linux DMA开发的地基。

2. 两个DMA映射API家族：一致性映射和流式映射

2.1 一致性DMA映射：dma_alloc_coherent

一致性DMA映射，又叫coherent mapping，核心特点是：在映射的生命周期内，CPU和设备看到的数据始终一致。实现机制上，内核会分配一段内存，要么关闭这段内存的cache属性，要么在硬件层面维护cache一致性（比如某些SoC支持硬件自动同步），保证CPU写进去的数据DMA控制器能立刻看到，DMA控制器写进去的数据CPU能立刻读到。

常用API是：

c复制dma_addr_t dma_handle;
void *cpu_addr;

cpu_addr = dma_alloc_coherent(dev, size, &dma_handle, GFP_KERNEL);
if (!cpu_addr) {
    /* 分配失败处理 */
}

这个函数返回两个地址：cpu_addr是CPU侧的虚拟地址，驱动代码里用它来访问缓冲区；dma_handle是设备侧的总线地址，填写到设备寄存器里。这两个地址在函数返回后就已经是合法的映射关系，不需要再做额外的转换。

使用结束后释放：

c复制dma_free_coherent(dev, size, cpu_addr, dma_handle);

使用场景：适合那种CPU和设备会频繁读写同一块内存、且对一致性要求极高的场景，典型的有DMA描述符环（descriptor ring）、网络驱动的RX ring、以及一些共享状态结构体。它的缺点是分配时开销相对较大，而且可能占用较大的连续物理内存，不适合做超大缓冲区的动态分配。

2.2 流式DMA映射：dma_map_single / dma_unmap_single

流式DMA映射，又叫streaming mapping，和一致性映射最大的区别是：它不保证整个生命周期内cache始终一致，而是通过一次性的同步操作来维护一致性。用起来更像是一个“临时借用”的过程：驱动把缓冲区的映射建立好，DMA传输期间CPU不要乱碰这块内存，传输完成后调用sync接口把数据同步过来。

典型流程：

c复制dma_addr_t dma_addr;

dma_addr = dma_map_single(dev, cpu_addr, size, DMA_TO_DEVICE);
if (dma_mapping_error(dev, dma_addr)) {
    /* 映射失败处理 */
}

/* 启动DMA传输... */

dma_unmap_single(dev, dma_addr, size, DMA_TO_DEVICE);

dma_map_single接收CPU虚拟地址，完成地址转换和必要的cache操作，然后返回设备侧的总线地址。DMA_TO_DEVICE表示数据方向是CPU到设备，还有几个方向取值，我下面会细说。

使用场景：典型的是一次性数据传输，比如每接收一笔数据、每发送一个包都动态建立映射、传输完成后解除映射。这些操作通常配合skb、bio这类临时缓冲区来用。它的灵活性高，内存使用效率也高，但需要遵守的约束也更多。

2.3 如何在两套映射之间做选择：三个判断标准

很多新手问到底该用哪一套。我个人的经验，主要看三点：

第一个是数据的生命周期。如果缓冲区是长期存在、反复使用的，比如网络驱动的环形缓冲区，用一致性映射更省心。如果缓冲区是一次性的，比如某个命令的临时数据，用完就释放，用流式映射更合适。

第二个是访问频率和模式。如果CPU和设备会同时、高频地访问这块内存，一致性映射可以减少每次传输都做cache同步的开销。如果数据的访问模式有明显的时间段划分，比如“填数据、启动DMA、等待完成、读结果”，流式映射更高效，因为不需要长期占用一致性映射的稀缺资源。

第三个是中断上下文和内存分配限制。一致性映射在分配时可能进入睡眠，不能用于原子上下文。流式映射的dma_map_single本身不分配内存，只是建立映射，因此更适合某些原子操作场景，但也要注意具体平台实现。

另外还有一个小技巧：在不会频繁动态申请、释放内存的驱动里，可以事先用dma_alloc_coherent分配一个pool，然后在需要时从pool里取一段用，避免每次DMA传输都重复走分配和释放的开销。

这里必须提一个容易忽略的点：不是所有内存都适合做DMA。kmalloc返回的内存可以，但其底层通常来自伙伴系统，即物理内存的页。要确保内存是连续的，且满足设备或IOMMU的地址宽度要求。在高位内存（high memory）存在时，DMA映射还有额外的限制，内核通过dma_set_mask_and_coherent这类接口帮驱动声明设备能处理多大的地址范围。

我常说：理解了两套映射API，Linux DMA开发的地基就算打了一半。因为接下来所有的dmaengine、协议驱动、总线驱动，本质上都避不开这套映射逻辑。

3. DMA方向：一个参数决定整个cache同步策略

3.1 DMA_TO_DEVICE、DMA_FROM_DEVICE、DMA_BIDIRECTIONAL和DMA_NONE

DMA映射API里的direction参数，决定了内核如何做cache同步，也决定了映射时内存屏障的插入方式。四个方向定义在<linux/dma-mapping.h>：

• DMA_TO_DEVICE：数据从CPU内存流向设备。典型场景是DMA发送（外设从内存读数据）。
• DMA_FROM_DEVICE：数据从设备流向CPU内存。典型场景是DMA接收（外设往内存写数据）。
• DMA_BIDIRECTIONAL：数据会在CPU和设备之间双向流动。如果驱动无法严格区分方向，可以用这个。
• DMA_NONE：主要用于校验，真正传输前应该被替换成其他方向。

很多初学驱动的人不重视这个参数，随手填DMA_BIDIRECTIONAL，结果发现性能变差了或者数据偶尔错。原因很简单：DMA_BIDIRECTIONAL会让内核在映射和取消映射时同时做两个方向的cache操作，开销更大，而且如果数据方向其实只是单向的，过度的cache一致性操作反而会引入问题。

3.2 流式映射下必须掌握的sync操作

流式映射的优势在于灵活，但代价是驱动必须在恰当的时机手工调用cache同步接口。这个“恰当的时机”非常考验对DMA流程的理解。

先看发送方向的代码模型：

c复制dma_addr_t dma_addr = dma_map_single(dev, buf, len, DMA_TO_DEVICE);

/* 写数据到buf... */

/* 确保CPU写入的数据能被DMA控制器看到 */
dma_sync_single_for_device(dev, dma_addr, len, DMA_TO_DEVICE);

/* 启动DMA传输，等待完成... */

dma_unmap_single(dev, dma_addr, len, DMA_TO_DEVICE);

接收方向的代码模型：

c复制dma_addr_t dma_addr = dma_map_single(dev, buf, len, DMA_FROM_DEVICE);

/* 启动DMA接收，等待完成... */

/* DMA写完数据后，CPU读之前必须先同步 */
dma_sync_single_for_cpu(dev, dma_addr, len, DMA_FROM_DEVICE);

/* 现在可以安全读取buf中的数据 */

dma_unmap_single(dev, dma_addr, len, DMA_FROM_DEVICE);

这里我写的是简化的流程，实际驱动里还要考虑错误处理、传输长度对齐等问题。但核心思路就是：for_device表示把数据所有权交给设备，for_cpu表示把数据所有权拿回给CPU。这两个方向一定不能搞反，搞反了数据就是错的。

3.3 dma_map_single和dma_unmap_single的配对规矩

流式映射的核心纪律是：每次dma_map_single必须对应一次dma_unmap_single。只映射不解除，就是DMA地址泄漏。而且解除映射时用的size和direction必须和映射时保持一致。内核文档里明确说得很清楚，但不匹配的情况在代码审查时非常常见。

我见过一个典型案例：驱动在发送完成中断里调用dma_unmap_single，但它的size是从某个描述符里读出来的，而描述符被错误地提前释放了，导致size变成一个随机值。结果就是DMA控制器访问了错误的地址，系统随机死机。后来排查了很久才定位到是size不一致。

所以说，这两套映射API看着简单，但要写对、写稳，关键是理解背后的cache一致性问题，并且养成严格配对、严格记录size和direction的习惯。

4. dmaengine框架：用统一API操作各种DMA控制器

4.1 为什么Linux要抽出dmaengine中间层

硬件上的DMA控制器千差万别。不同SoC的DMA控制器寄存器布局不同、通道数量不同、传输粒度不同、中断处理方式不同。如果每个驱动都直接操作寄存器，那内核里就会充满重复代码，而且各种板子的DMA驱动风格迥异，维护起来是灾难。

所以内核定义了dmaengine框架，把DMA控制器抽象成一个个dma device，向上提供统一的API。上层驱动只需要关心“我要搬运数据，从A搬到B，长度多少，方向如何”，而不需要知道底层是哪个厂商的DMA控制器。

这就是典型的“中间层思想”。对DMA开发来说，你写的驱动可能属于两种角色：

• DMA controller driver：负责驱动具体的DMA硬件，实现dmaengine框架定义的回调接口。
• DMA client driver：使用dmaengine API发起DMA传输，比如某个网卡驱动、某个SPI控制器驱动。

绝大多数人的工作集中在client driver，但理解controller driver的职责，对排查问题会有很大帮助。

4.2 dmaengine API核心调用流程

看一段最典型的client驱动调用流程：

第一步，获取DMA channel：

c复制struct dma_chan *chan;

chan = dma_request_chan(dev, "rx");
if (IS_ERR(chan)) {
    /* 申请失败处理 */
}

其中"rx"是设备树里dmas属性对应的通道名。设备树里通常这样描述：

code复制dmas = <&dma0 0 0x40000000>, <&dma0 1 0x40000000>;
dma-names = "rx", "tx";

第一步是准备描述符。dmaengine驱动要描述一次传输，用的是dma_async_tx_descriptor：

c复制struct dma_async_tx_descriptor *desc;
struct dma_slave_config cfg;

memset(&cfg, 0, sizeof(cfg));
cfg.src_addr = (dma_addr_t)phy_src_addr;
cfg.dst_addr = (dma_addr_t)phy_dst_addr;
cfg.src_addr_width = DMA_SLAVE_BUSWIDTH_4_BYTES;
cfg.dst_addr_width = DMA_SLAVE_BUSWIDTH_4_BYTES;
cfg.src_maxburst = 4;
cfg.dst_maxburst = 4;
cfg.direction = DMA_MEM_TO_DEV;
dmaengine_slave_config(chan, &cfg);

desc = dmaengine_prep_slave_single(chan, dma_addr, len, DMA_MEM_TO_DEV, flags);

这里的dma_addr必须是设备侧总线地址，也就是通过前面讲的DMA映射API拿到的地址，不能直接填CPU虚拟地址。

第二步是提交传输并启动：

c复制struct dma_async_tx_descriptor *desc;
dma_cookie_t cookie;

cookie = dmaengine_submit(desc);
dma_async_issue_pending(chan);

dmaengine_submit只是把描述符挂到DMA引擎的队列里，真正激活需要调用dma_async_issue_pending。有些驱动的代码会在这两步之间去做其他操作，但严格说，提交后就应该尽快启动。

第三步是等待完成。可以轮询dma_async_is_tx_complete，也可以在完成回调里处理：

c复制desc->callback = my_dma_callback;
desc->callback_param = my_data;

回调函数的执行上下文可能是在软中断里，也可能是tasklet，取决于底层驱动的实现。在回调里要遵循“快速处理、不能睡眠”的原则，不要在回调里做太多事。如果非要处理大量数据，应该把工作放到工作队列里。

4.3 一个基于dmaengine的DMA发送示例：从申请channel到收尾

我把上面的流程串成一个比较完整的示例，方便你照着写。这个例子模拟一个简单的外设DMA发送，数据从内存缓冲区发送到设备FIFO，每次传输完成之后在回调里做状态标记。

c复制#include <linux/dmaengine.h>
#include <linux/dma-mapping.h>

struct my_dev {
    struct device *dev;
    struct dma_chan *dma_chan;
    void *tx_buf;
    dma_addr_t tx_dma;
    size_t tx_len;
    struct completion tx_done;
};

static void dma_tx_callback(void *param)
{
    struct my_dev *mdev = param;
    complete(&mdev->tx_done);
}

static int my_dev_dma_tx(struct my_dev *mdev, void *data, size_t len)
{
    struct dma_async_tx_descriptor *desc;
    struct dma_slave_config cfg;
    dma_cookie_t cookie;
    int ret;

    /* 假设tx_buf是之前申请好的DMA缓冲区 */
    memcpy(mdev->tx_buf, data, len);
    mdev->tx_len = len;

    /* 配置slave接口 */
    memset(&cfg, 0, sizeof(cfg));
    cfg.direction = DMA_MEM_TO_DEV;
    cfg.dst_addr = mdev->dst_phys;  /* 设备FIFO的总线地址 */
    cfg.dst_addr_width = DMA_SLAVE_BUSWIDTH_4_BYTES;
    cfg.dst_maxburst = 4;
    ret = dmaengine_slave_config(mdev->dma_chan, &cfg);
    if (ret)
        return ret;

    /* 准备描述符 */
    desc = dmaengine_prep_slave_single(mdev->dma_chan,
                                       mdev->tx_dma,
                                       len,
                                       DMA_MEM_TO_DEV,
                                       DMA_PREP_INTERRUPT);
    if (!desc)
        return -ENOMEM;

    desc->callback = dma_tx_callback;
    desc->callback_param = mdev;

    /* 提交并启动 */
    cookie = dmaengine_submit(desc);
    if (dma_submit_error(cookie))
        return dma_submit_error(cookie);

    dma_async_issue_pending(mdev->dma_chan);

    /* 等待传输完成 */
    if (!wait_for_completion_timeout(&mdev->tx_done, msecs_to_jiffies(1000))) {
        dmaengine_terminate_sync(mdev->dma_chan);
        return -ETIMEDOUT;
    }

    return 0;
}

这段代码里，wait_for_completion_timeout直接睡在进程上下文等结果，实际驱动里有更灵活的异步处理方式，但作为示例，这已经能说明dmaengine的基本调用关系。

注意两个细节：申请channel的时候，要检查DMA方向是否匹配，不是每个channel都支持所有方向。设备树里配了每个通道的序号和传输类型，驱动端必须和设备树保持一致，否则dma_request_chan会失败，或者运行时数据跑偏。

还有一个隐蔽问题：dmaengine_terminate_sync虽然是安全的，但它只能保证后续不会再启动新的传输，无法保证已经被DMA控制器取走的描述符立即停止。如果DMA控制器已经在搬运数据，terminate之后可能还有一个不完整的传输事件。所以设计上要预留足够的错误恢复逻辑。

4.4 任务交接的细节：回调上下文、通道释放和驱动卸载顺序

在驱动卸载（remove函数）时，需要做的事情比想象中多。首先是停止所有正在进行的DMA传输，释放channel，然后解除所有DMA映射缓冲区。顺序不能反：如果先释放了缓冲区，再终止DMA，DMA控制器可能还在访问已经释放的内存，导致非法访问和内核panic。

常见的正确顺序是：

1. 标记设备为卸载状态，阻止新的DMA请求。
2. 调用dmaengine_terminate_sync终止所有正在进行的传输。
3. 等待所有完成回调返回，确认没有传输还在引用缓冲区。
4. 解除所有DMA缓冲区的映射。
5. 释放DMA channel。

这里面的第二步和第三步尤其重要。只terminate不等待回调，可能回调在设备已经卸载后才执行，访问到已经释放的内存。

另外，回调执行上下文里不能调用dmaengine_terminate_sync，因为这个函数可能休眠。如果必须在回调里终止传输，要用dmaengine_terminate_all，但也要注意它的平台差异。这些细节多得很，没有统一的“绝对正确”写法，因为每款DMA控制器的行为都不完全一样。多读具体平台下dmaengine驱动的实现，是非常有用的经验来源。

5. 调试DMA问题：先确认是不是cache一致性惹的祸

5.1 数据随机乱码的黄金排查路径

DMA驱动的问题，最难啃的就是随机性、偶发性Bug。我自己的调试经验，先按以下顺序排查，能省去大量无谓猜测：

第一步，确认DMA缓冲区地址和长度是否正确。在驱动里打印dma_handle、cpu_addr、len，和设备树、寄存器配置逐一对齐。很多时候问题就出在读描述符时长度被截断，或者地址多了一个偏移。

第二步，确认cache同步操作是否到位。如果使用流式映射，检查传输前有没有dma_sync_single_for_device，传输后有没有dma_sync_single_for_cpu。如果使用一致性映射，检查缓冲区是否真的是通过dma_alloc_coherent申请的，而不是kmalloc + 强制关cache这种野路子。

第三步，确认DMA方向是否填错。方向填错了，cache同步操作的方向也会错，表现就是数据彻底不对，或者偶发错误。

第四步，检查是否有内存屏障问题。DMA传输完成后，硬件中断会通知CPU，但CPU乱序执行或者编译器重排可能导致一些状态字段没有被正确读取。在回调里需要加dma_rmb()之类的屏障再读共享状态。

我见过最典型的场景是：驱动在DMA完成中断里，先读描述符里的状态字段，再读数据缓冲区。看起来没问题，但实际运行中，CPU可能先读了数据缓冲区，再读状态字段，结果读到的状态是“已完成”，但数据其实还没有完全写入内存。这种Bug极其难查，必须靠内存屏障修正顺序。

5.2 通过dmesg、tracepoint和硬件调试器定位

内核提供了不少DMA调试设施，用好了事半功倍。

首先是CONFIG_DMA_API_DEBUG。这个配置项打开后，会检查DMA API的调用是否合法，比如是否重复unmap、是否存在映射泄漏、方向是否匹配。开发期强烈建议打开，虽然会有性能损耗，但在找Bug阶段很值得。

bash复制echo 1 > /sys/kernel/debug/dma-api/dump
cat /sys/kernel/debug/dma-api/error

如果还没头绪，就用tracepoint看DMA传输的历史记录：

bash复制trace-cmd record -e dma:* -e pool:dma_pool*
trace-cmd report

dmaengine子系统也有自己的trace点，比如dmaengine_submit、dmaengine_issue_pending等。这些trace点能告诉你描述符什么时候被提交、什么时候被完成，帮助判断问题出在提交环节还是完成环节。

当软件手段都用尽还定位不了，只能上硬件调试器。示波器或逻辑分析仪抓DMA控制器的输出信号，确认外设侧到底有没有真实收到数据、数据有没有按预期时序到达。这一步虽然麻烦，但往往能实锤问题在驱动逻辑还是硬件设计。

5.3 常见问题速查表

我把这几年DMA调试中遇到的高频问题整理成一张速查表，方便查对着查：

这个表的每一条，背后都有对应的、大量排障的实际案例。我自己最惨痛的一次，是调试一个串口DMA接收功能，数据一直偶发乱码，查了一整天，结果是设备树里中断号写错了一个bit。这个教训不是DMA API本身的问题，但充分说明DMA开发是软硬件联调的活儿，任何一个环节都可能出问题。

6. IOMMU和S/G表：DMA开发中绕不开的两个进阶话题

6.1 IOMMU对总线地址的再映射

现代SoC里IOMMU（也叫SMMU）已经很普遍了。IOMMU的存在让设备看到的地址空间和CPU物理地址空间分离。驱动通过dma_alloc_coherent或dma_map_single拿到设备侧地址，实际上已经经过了IOMMU的映射，而不是简单的物理地址。

这带来一个好处：即使分配的物理内存不连续，经过IOMMU映射后，设备侧可以把它看成连续的地址。这大大简化了驱动的设计，也让大块DMA缓冲区更容易被分配。

但代价是：驱动必须始终使用DMA API生成设备侧地址，绝对不能自行把物理地址填进设备寄存器。我在某些旧代码里见过直接virt_to_phys算物理地址然后填寄存器的事，在无IOMMU平台上可能侥幸能用，一旦平台开了IOMMU，数据传输直接失败或者随机错误。

6.2 什么时候需要使用S/G表

S/G表（Scatter/Gather）是DMA的另一个重要能力：允许一次DMA传输由多个不连续的内存段组成。网卡收包、块设备IO这类场景经常需要S/G，因为数据天然分散在不同的页、不同的缓冲区里。

使用S/G的核心API是dma_map_sg、dma_unmap_sg、sg_page、sg_dma_address、sg_dma_len。关键点是：dma_map_sg会填充每个scatterlist里的dma_address和dma_length字段，驱动必须用sg_dma_address去取设备侧地址，而不是用sg_phys之类的原始物理地址。

6.3 dma_pool：管理大量小DMA缓冲区的实用手段

如果你需要在驱动里管理大量相同大小的小DMA缓冲区，比如描述符、状态块、小数据包缓冲区，每次都dma_alloc_coherent和dma_free_coherent，开销大且容易造成碎片。这种情况适合用dma_pool：

c复制struct dma_pool *pool;

pool = dma_pool_create("my_pool", dev, size, align, boundary);
if (!pool)
    return -ENOMEM;

void *cpu_addr;
dma_addr_t dma_addr;

cpu_addr = dma_pool_alloc(pool, GFP_KERNEL, &dma_addr);
/* 使用... */
dma_pool_free(pool, cpu_addr, dma_addr);

dma_pool_destroy(pool);

dma_pool_create的几个参数都有讲究：size是每个对象的大小，align是对齐要求，boundary表示跨越该边界时不能分配。在驱动里用dma_pool管理描述符，比每次动态分配高效得多，而且不容易出现碎片化。

7. 实际项目中的几条硬经验

7.1 设备树里dma属性配置不对，驱动再怎么写都白搭

设备树里描述DMA通道信息的属性是dmas和dma-names。格式一般是：

code复制dmas = <&dma0 0 0x40000000>, <&dma0 1 0x40000000>;
dma-names = "rx", "tx";

dmas里每个条目由三部分组成：DMA控制器phandle、通道号、通道属性。第三个数通常表示请求线编号、传输宽度等额外信息，具体含义由每个厂商的DMA控制器驱动自定义，非常不统一。

很多新手拿到一个设备树模板，直接复制修改，结果通道号和实际外设的DMA请求线对不上，驱动能查到channel，但数据传输始终不工作，甚至系统挂死。解决的办法就是读对应SoC的TRM（Technical Reference Manual），对照DMA控制器的一路一路输入通道确认。

7.2 开启CONFIG_DMA_API_DEBUG是开发期最值得做的一件事

前面提过一次，但这里还要强调。dma_api_debug能自动检测很多DMA API误用情况，包括：

• 重复unmap同一个地址
• unmap用的direction和map不一致
• map了但没有unmap
• 使用了一个不属于当前设备映射的地址

开发期打开它，等于让内核帮你做了一次代码review。生产环境里因为性能原因关掉，但开发调试阶段一定开着。

7.3 DMA缓冲区要避开栈和静态内存

这是很多明明API都写对、但传输出错的常见原因。DMA缓冲区不能是栈上的局部数组，也不能是普通静态内存，因为这些内存不满足DMA映射要求。栈上内存的虚拟地址和物理地址之间的映射很复杂，很可能不连续，DMA控制器无法正常工作。静态内存虽然物理连续，但老代码使用的是__virt_to_phys这类别扭的方式，而且碰上SMP或高内存时容易出错。

正确做法是：如果缓冲区生命周期和驱动一样长，用dma_alloc_coherent申请；如果是一次性的，用kmalloc申请后dma_map_single映射；如果必须接收来自用户态的数据，用get_user_pages或pin_user_pages固定物理页再做S/G映射。

8. 结尾一点个人经验

最后说说我自己对Linux DMA开发的感想。第一次对接DMA驱动的时候，我以为难点在于寄存器配置和中断处理，后来踩过cache一致性的坑、IOMMU映射的坑、设备树通道映射的坑之后，才明白DMA开发的核心其实是对Linux内存模型的理解。dma_alloc_coherent也好，dma_map_single也好，这些API真正在做的事，就是在“CPU视角的内存”和“设备视角的内存”之间架一座规范、可维护的桥。把这层想透了，再看各家SoC的DMA控制器驱动，基本都能一眼看出它的设计意图。

这一篇先把DMA的地基打了，包括基础概念、两套映射API、DMA方向、dmaengine框架和调试手段。下一篇我打算用实际的IPU（图像处理单元）或者网络驱动的例子，把DMA的S/G表、环形缓冲区、以及多队列并发这些更复杂的实操场景拆开讲。到时候再看dmaengine的完整生命周期，你会发现一切都串起来了。