聊到Linux下的DMA学习，很多人第一反应是：这是内核驱动里最难啃的一块。真去啃过的人都知道，DMA本身的硬件原理并不复杂，真正折磨人的是它在Linux内核里的那一整套抽象、映射和cache一致性规则。这篇文章我想用实际动手的视角，把Linux DMA的学习路径、核心API、驱动写法以及我踩过的坑完整梳理一遍，适合正在入门内核驱动、嵌入式Linux开发，或者被DMA传输问题折磨过的朋友。
1. 先搞清楚DMA到底解决了什么问题
1.1 DMA的本质：把“搬数据”这件事外包出去
DMA的全称是Direct Memory Access，直接内存访问。你可以把它理解成一位专门负责搬运数据的“仓库管理员”：CPU只需要告诉他“把A仓库的货搬到B仓库，数量是N件”，然后这位管理员就自己去搬，搬完了喊一声“完成”。
在没有DMA的年代，CPU要搬运一块数据，需要反复执行load和store指令：先从源地址读一个字节到寄存器，再把它写到目的地址。这种方式的效率很低——CPU的主频高、指令快，但外部设备或低速内存跟不上，CPU就被迫原地等待。
比如常见的外设场景：网卡收到一个数据包，需要把数据从网卡内部FIFO搬到系统内存。如果没有DMA，CPU只能一趟一趟来，包越大、流量越猛，CPU占用率就会直线飙升，甚至超过90%。系统的整体吞吐量也会被严重拖垮。
有了DMA之后，整个过程被彻底改变了：CPU只需初始化一次DMA控制器，把源地址、目标地址、传输长度配置好，然后转身去做别的事。DMA控制器会自己完成数据搬运，并在结束后通过中断报告结果。这就像你只需要交代一次快递员，然后就可以继续开会，快递员自己跑腿、签收、回来向你交付凭证。
1.2 Linux下为什么DMA反而成了难点
硬件上的DMA，说穿了就是三个寄存器：源地址、目的地址、长度。但到了Linux里，事情就变复杂了。我自己的体会是，Linux下的DMA学习有三个真正的门槛：
第一是地址体系。CPU访问内存用的是虚拟地址，DMA控制器访问内存用的是物理地址（在启用SMMU/IOMMU时用的是经过映射的设备地址）。这两套地址体系之间的转换、映射、生命周期管理，才是初学者最容易翻车的关口。
第二是Cache一致性。CPU有L1/L2 Cache，DMA控制器写内存时并不会经过Cache。如果CPU先把数据写进了Cache但还没刷回内存，DMA读到的就是旧数据；反过来，DMA写入了新数据，CPU的Cache里可能还是旧副本。内核为了解决这个问题，提供了一套映射和同步的机制，这也是学习Linux DMA时绕不开的核心内容。
第三是框架抽象。Linux内核已经帮你把各种DMA控制器的共性抽成了一个通用框架——dmaengine。你写驱动时不再直接操作寄存器，而是使用dma_request_channel、dmaengine_prep_slave_single这一套API。这大大提高了驱动代码的移植性，但也要求你理解框架背后的流程。
如果你问我：学习Linux DMA的最终目标是什么？我的答案是：能够写一个使用DMA的驱动程序，并且在遇到底层的地址映射、cache同步、性能瓶颈问题时，有能力自己定位并解决。这篇文章接下来的内容，都是围绕这个目标服务的。
2. 了解掌握Linux DMA的子系统和核心API
2.1 地址映射：DMA引擎看到的不是同一个世界
在写任何DMA代码之前，必须先建立起“多地址空间”的概念。CPU发出的是虚拟地址，内核模块里kmalloc返回的指针本质上也是一个虚拟地址；但DMA控制器要工作，需要的是物理地址。因为DMA控制器直接挂在总线上，它不认MMU，自己不翻译页表。
所以Linux内核提供了一组接口，专门用来完成“虚拟地址 → DMA可用的地址”的转换。核心函数是：
dma_map_single()：把一段内核虚拟地址映射为DMA地址dma_unmap_single()：传输完成后解除映射dma_alloc_coherent()：直接分配一个CPU和DMA都能访问的缓冲区
这里最关键的认知是：DMA地址不等于物理地址。在无IOMMU的普通嵌入式平台上，DMA地址通常就等于物理地址；但在x86等带有SMMU/IOMMU的平台上，DMA地址是经过IOMMU映射的，可能和物理地址完全不同。驱动开发者要做的，是使用统一API，而不是自己假设地址关系。
2.2 一致性映射和流式映射，两种模式的本质差别
Linux DMA子系统把内存使用方式分为两类：一致性映射（Coherent DMA）和流式映射（Streaming DMA）。
一致性映射用dma_alloc_coherent()分配，内核会同时返回CPU虚拟地址和DMA地址。这种映射的特点是：硬件会保证CPU和DMA看到的缓存是一致的，不需要你在软件层面手动做同步。
那它适合什么场景？适合长时间存在且频繁被CPU和DMA共同访问的缓冲区。比如网络驱动的描述符环（descriptor ring）、DMA的源数据缓冲区。因为它分配和释放的开销大，不适合短生命周期的小传输。
流式映射用dma_map_single()完成，服务于单次传输的场景。它要求你按照“映射 → 传输 → 同步/解映射”的流程来管理。流式映射本身不解决缓存一致性问题，而是通过软件在关键时刻做dma_sync_single_for_device()和dma_sync_single_for_cpu()来手工同步。
| 维度 | 一致性映射 | 流式映射 |
|---|---|---|
| 分配接口 | dma_alloc_coherent | kmalloc + dma_map_single |
| 缓存一致性 | 硬件/平台保证，无需手动同步 | 需要软件显式同步 |
| 适用场景 | 周期复用的长生命周期缓冲区 | 单次或低频的传输 |
| 释放接口 | dma_free_coherent | dma_unmap_single |
| 典型用途 | 描述符环、DMA缓冲池 | 网络数据包、块设备IO |
流式映射里方向的概念非常重要，Linux内核定义了枚举类型：
DMA_TO_DEVICE：CPU写、DMA读（比如CPU准备好数据让DMA发送）DMA_FROM_DEVICE：DMA写、CPU读（比如DMA接收外设数据）DMA_BIDIRECTIONAL：双向
方向填错了，后果不只是数据错误，还可能造成cache数据损坏，因为内核要根据方向决定是刷cache还是使cache失效。
2.3 dmaengine：把所有DMA控制器统一起来的抽象层
前面说的是底层的内存映射API，而Linux驱动开发中更常见的是dmaengine框架。它有点像“Linux对DMA控制器的封口机”——无论芯片内部的DMA控制器是哪家厂商的，驱动面对的API都是一样的。
dmaengine框架的几个核心概念：
DMA通道（dma_chan）：一个DMA通道对应一个独立的传输队列。比如某平台有8路DMA，你能申请到其中一个通道来使用。申请通道的接口是dma_request_channel()或者基于设备树的dma_request_slave_channel()。
描述符（dma_async_tx_descriptor）：一次传输任务描述，里面包含了源地址、目的地址、长度、完成回调等信息。你可以把它理解为“一次运输的运单”。
发送接口：dmaengine_prep_slave_single()用于从设备到内存或内存到设备的传输，dmaengine_prep_dma_memcpy()用于内存到内存的拷贝。创建描述符之后，通过dmaengine_submit()提交到通道，再调用dma_async_issue_pending()来激活真正的硬件传输。
dmaengine框架的优势在于：协议层的驱动无需关心底层DMA控制器的寄存器细节，只需按照统一流程走。它不仅适用于SoC内置DMA，还可以对接PCIe设备自带DMA甚至FPGA实现的DMA控制器，只要它们实现了内核的dmaengine接口。
3. 从零开始写一个使用DMA的驱动
3.1 准备环境与目标定义
写DMA驱动和学习理论概念是完全两码事。我建议你不要上来就搞复杂的网络驱动或块设备驱动，而是先写一个精简的“内存到内存”DMA测试驱动，把整个数据通路打通。
这里我以一个常见的嵌入式SoC平台为例，环境如下：
- Linux内核版本：4.19及以上（太老的版本部分API不适用）
- 设备树中已使能DMA控制器，dmaengine框架已配置
- 平台自带DMA控制器支持memcpy传输类型
驱动的目标很明确：用DMA把内核缓冲区A中的数据搬运到缓冲区B，然后通过校验数据判断传输是否正常。整个过程虽然简单，但覆盖了申请通道、配置参数、分配缓冲区、提交传输、等待完成、释放资源这几大关键步骤。
这样一个驱动，就算你换了其他平台、其他DMA控制器，代码结构也基本不用大改。这是dmaengine框架最实用的地方。
3.2 设备树节点配置
在Linux的设备模型中，DMA使用者必须在设备树中声明它需要哪个DMA通道。常见写法如下：
my_dma_test { compatible = "vendor,dma-test"; dmas = <&dma0 0 0>; dma-names = "tx"; };这里dma0是设备树里已定义的DMA控制器节点，后面的数字含义取决于具体平台的dmaengine驱动解析方式。比如在部分平台上，第一个数字代表DMA请求线编号，第二个代表优先级。所以设备树的内容要以你所用的SoC文档为准，而不是照搬某个示例。
如果你不确定参数怎么填，有一个技巧：先去内核源码里看对应DMA控制器的驱动实现了哪些of_xlate逻辑，它怎么解析dmas属性里的字段，你就按它的规则填。这一步理解了，设备树这块就不会被卡住。
驱动侧获取通道的代码很简单：
struct dma_chan *dma_ch; dma_ch = dma_request_chan(dev, "tx"); // "tx"对应 dma-names if (IS_ERR(dma_ch)) { dev_err(dev, "cannot request DMA channel\n"); return PTR_ERR(dma_ch); }提示：
dma_request_chan()比老旧的dma_request_slave_channel()优先推荐使用。它返回错误指针而不是NULL，排查问题时更舒服。
3.3 核心驱动代码框架
下面是驱动中最关键的部分。为了保持代码精简，我隐去了很多错误处理细节，但你实际写的时候一定要做完整检查。
首先是缓冲区分配。我用的是dma_alloc_coherent()，它一次性把虚拟地址和DMA地址都给你，免去手动映射的麻烦：
#define BUF_SIZE 4096 struct dma_test_priv { struct dma_chan *tx_ch; void *virt_src; dma_addr_t dma_src; void *virt_dst; dma_addr_t dma_dst; struct completion done; }; static int dma_test_probe(struct platform_device *pdev) { struct dma_test_priv *priv; struct dma_slave_config cfg = {0}; priv = devm_kzalloc(&pdev->dev, sizeof(*priv), GFP_KERNEL); // 省略 devm_kzalloc 返回值检查 init_completion(&priv->done); priv->tx_ch = dma_request_chan(&pdev->dev, "tx"); if (IS_ERR(priv->tx_ch)) return PTR_ERR(priv->tx_ch); // 一致性分配的缓存区：CPU 和 DMA 都能访问 priv->virt_src = dma_alloc_coherent(&pdev->dev, BUF_SIZE, &priv->dma_src, GFP_KERNEL); priv->virt_dst = dma_alloc_coherent(&pdev->dev, BUF_SIZE, &priv->dma_dst, GFP_KERNEL); // 省略两个 NULL 检查 // memcpy 传输不需要 slave_config 也能工作 memset(priv->virt_src, 0x5A, BUF_SIZE); memset(priv->virt_dst, 0x00, BUF_SIZE); // 发起 DMA 拷贝 dma_test_do_copy(priv); return 0; }传输函数本身是这个驱动的灵魂，我会把每一步拆开解释。
static void dma_test_do_copy(struct dma_test_priv *priv) { struct dma_async_tx_descriptor *desc; struct dma_device *dma_dev; enum dma_ctrl_flags flags = DMA_CTRL_ACK | DMA_PREP_INTERRUPT; dma_dev = priv->tx_ch->device; desc = dma_dev->device_prep_dma_memcpy(priv->tx_ch, priv->dma_dst, priv->dma_src, BUF_SIZE, flags); if (!desc) { dev_err(&pdev->dev, "prep dma memcpy failed\n"); return; } desc->callback = dma_test_callback; desc->callback_param = priv; // 提交并启动传输 dmaengine_submit(desc); dma_async_issue_pending(priv->tx_ch); // 等待完成 wait_for_completion(&priv->done); }完成回调里只需要唤醒等待的进程：
static void dma_test_callback(void *param) { struct dma_test_priv *priv = param; complete(&priv->done); }3.4 关键步骤背后的为什么
这段代码虽然短，但每一步都有讲究。
为什么用dma_alloc_coherent()而不是kmalloc()？因为它是为“长期、高频、DMA和CPU共用”场景设计的。它里面会保证缓冲区的物理连续性（在无IOMMU时DMA要求物理连续），并且成功处理了cache一致性。如果你用kmalloc()再自己dma_map_single()，就需要精确掌握映射时长和同步时机，出错概率非常大。学习阶段直接用一致性分配，能排除掉很多干扰项。
为什么dma_prep_dma_memcpy需要目的地址、源地址和长度三个参数？因为它执行的是纯粹的memcpy语义，和你在C语言里调用的memcpy()是一回事，只不过搬砖的是DMA引擎。
为什么标了DMA_PREP_INTERRUPT？没有这个标志，驱动可能不会在传输完成后触发中断回调，你的complete()就永远不会被调用。有的DMA控制器驱动还会忽略这个标志，那你就要自己查平台驱动逻辑，判断中断是不是必然产生。
为什么最后要wait_for_completion()？因为DMA是异步的，CPU提交任务后不会阻塞等待。你在probe时如果不等待，可能进程退出后缓冲区被释放了，DMA还在传输。这里等待就是确保传输完全结束。
当然，真正做产品的时候不要在probe里像这样同步等待，这只是把流程跑通的教学做法。产品里DMA传输都需要做异步处理，配合工作队列或状态机管理。
3.5 清理与释放资源
有申请就必然有释放，DMA资源尤其要注意释放顺序。正确的顺序应该是：先保证DMA不再工作，再释放缓冲区，最后释放通道。
static void dma_test_remove(struct platform_device *pdev) { struct dma_test_priv *priv = platform_get_drvdata(pdev); // 先终止未完成的传输，避免DMA还在访问缓冲区 dmaengine_terminate_all(priv->tx_ch); dma_free_coherent(&pdev->dev, BUF_SIZE, priv->virt_src, priv->dma_src); dma_free_coherent(&pdev->dev, BUF_SIZE, priv->virt_dst, priv->dma_dst); dma_release_channel(priv->tx_ch); }dmaengine_terminate_all()这一步很容易被忽略。如果驱动卸载时，DMA通道里还有排队未执行的任务，直接在之后释放缓冲区，硬件可能会访问已经释放的内存，轻则数据错乱，重则导致系统崩溃。这也是我在实际调试中亲眼见识过的坑。
4. 调试技巧与常见问题排查实录
4.1 先确认硬件路径，再怀疑软件问题
搞DMA驱动最容易出现的情况是：数据没搬运成功，第一反应就是去查回调触没触发、代码逻辑对不对。但我给你的建议是：先确认DMA控制器自己是否完成了搬运。
怎么做？方法很多。最简单的就是提前在DMA缓冲区里填一个特殊模式（比如0xAA），如果DMA成功把数据拷贝过去，目的缓冲区里就会被覆盖成源数据。你可以在wait_for_completion()之后，直接memcmp()两个缓冲区，比对失败就知道DMA硬件没干活，或者干活的路径配置错了。
还有一种思路是直接查看DMA控制器的状态寄存器。很多SoC的DMA驱动都会在sysfs或debugfs下暴露一些状态节点，比如当前通道的传输计数寄存器。如果传输计数为0，说明描述符根本没有被硬件执行。
如果上面这些都正常，但回调没触发，那问题就锁定在中断路由或驱动未能正确请求中断上。
4.2 用内核自带的dma-debug工具排查映射问题
内核有一个非常实用的调试开关：CONFIG_DMA_API_DEBUG。把它打开之后，内核会对DMA API的调用进行一致性检查。常见包括：有没有从未映射的地址发起DMA？有没有在传输未完成时解映射？方向和cache同步是否匹配？
启用方法是在内核配置里打开：
CONFIG_DMA_API_DEBUG=y CONFIG_DMA_API_DEBUG_SG=y驱动运行出错时，日志里会出现类似这样的信息：
DMA-API: device driver maps memory from process context这条报错的意思是：在进程上下文调用了dma_map_single()但没有使用相应的GFP_*标志，或者映射的地址来自栈空间（栈在x86上常常不是DMA安全的）。这类问题如果不开启dma-debug，极难察觉，因为正常操作过程中不一定立刻崩溃。
还有一个常用接口在debugfs下：
/sys/kernel/debug/dma-api/dump查看当前所有未解映射的DMA映射记录。当你的驱动因为某条映射未解而泄漏时，这里会陈列线索。我遇到过DMA映射没解干净导致系统内存分配逐渐失败的情况，靠这个接口很快锁定了问题函数。
4.3 常见问题速查表
下面这张表收集了我自己在DMA调试中遇到的高频问题，把现象、原因和解决思路整理在一起：
| 现象 | 可能原因 | 排查思路 |
|---|---|---|
| 传输完成回调一直不触发 | 描述符没提交或没启动 | 检查是否调用dmaengine_submit和dma_async_issue_pending |
| 数据搬过去全是0xFF或者旧数据 | cache脏数据未同步，或者DMA根本没写 | 尝试关闭cache或用dma_sync做同步 |
| 模块卸载崩溃 | terminate_all未调用，DMA还在跑 | 先终止传输再释放缓冲区 |
| dma_request_chan返回错误 | 设备树通道配置错误 | 核对dmas属性与dma-names |
| map/unmap不配对 | 某些路径缺失dma_unmap | 开启CONFIG_DMA_API_DEBUG |
| 传输源数据是进程栈空间 | 栈内存不适合DMA | 改为kmalloc或dma_alloc_coherent |
| dma_alloc_coherent失败 | 内存碎片化或者平台限制 | 查看alloc_size是否过大，减少分配块 |
4.4 一个从迷惑到破案的实例
分享一个我实际调试过的场景，帮助你把前面的知识串起来。某次我在一个嵌入式平台上做音频数据传输环节，用DMA搬运麦克风采集的数据。采集出来的前几百个字节一直是0，后面又是正常数据。
我第一反应是DMA的源地址配错了，但反复核对设备和地址都没有问题。后来我想到可能是cache一致性问题：DMA把数据写入了内存，但CPU读的时候命中了它自己的cache——那个cache里还保持着DMA写入之前的旧数据。前几百个字节正好被CPU的cache预取过，所以永远是旧值。
解决方案有两个方向：一是改用dma_alloc_coherent()分配缓冲区，让平台保证一致性；二是在DMA传输结束后，调用dma_sync_single_for_cpu()使cache失效，强制CPU从内存重新读取。我最终采用了第二种，因为音频数据缓冲区是从上层传入的，不方便整体变成一致性地分配。
这类问题的排查思路，值得每一位做DMA驱动的人牢记：数据异常，先想cache；cache没问题，再怀疑流程；流程没问题，最后才怀疑硬件。
5. 进一步拓展方向
5.1 scatter-gather 与环形描述符
你如果掌握了基础的单次DMA传输，下一步我建议研究scatter-gather（SG）。它解决的是一个很实际的问题：当你要发送的数据在内存里不连续分布时（比如网络协议栈的多个skb frag），DMA必须要能把这些不连续的片段串起来。dma_map_sg()就是这套机制的核心。
SG的核心逻辑很简单：将一组不连续的物理内存块，映射出一组dma地址和长度对，然后dmaengine用链表或数组形式的描述符把它们串成一次传输。这样一次提交能搬一块“分散但整体有序”的数据，非常提升效率。
环形描述符则是为了高频持续传输而生的。驱动预先申请一个描述符环，循环填充和提交传输任务，硬件按顺序执行并产生中断。你可以在音频播放、网络收发驱动里看到大量这种设计。
5.2 虚拟化与IOMMU场景下的DMA
以上讨论都基于普通Linux系统。但现代系统里还有一个大话题：当开启了IOMMU/SMMU时，设备看到的地址空间和物理地址空间隔离了，DMA能访问哪个内存由IOMMU页表决定。
这个机制你通常不用自己操心，因为Linux的通用DMA API会透明处理IOMMU映射，但它带来一个额外好处：映射粒度变得灵活，物理连续的限制大大降低。在支持IOMMU的平台上，你甚至可以用vmalloc分配逻辑连续但物理不连续的内存，dma_map_sg也能正常工作。
但如果你的设备驱动直接跳过了DMA API，自己去操作物理地址，遇到IOMMU之后基本就是一场灾难。因此，我的建议一直是：无论平台是否启用IOMMU，都严格使用标准DMA API，把地址管理交给内核。
6. 个人总结与实操经验
通篇写下来，我想最后再分享几条经过多次痛感换来的体会。
第一，DMA驱动的核心不是控制器的寄存器，而是内存管理规则。你如果理解了“虚拟地址、物理地址、DMA地址”三种地址的关系，理解了cache一致性映射的作用边界，那么换任何平台只是换个API参数的事。反之，只会填参数而不明白原理，遇到数据诡异错乱的问题就会彻底失守。
第二，学习阶段一定从最简单场景入手。不必一上来就写复杂的网络驱动或块驱动，可以先做一个memcpy类型的DMA测试驱动，确认本平台的DMA通道、中断、cache一致性，都没问题之后再去接触更复杂的外设数据通路。
第三，调试心态要“分层定位”。先从数据内容判定DMA硬件有没有干活；再用dma-debug排除API调用错误；然后检查cache同步；最后才去看设备树或寄存器配置。这个顺序可以帮你少走非常多弯路。我见过太多人一开始就把问题归咎于芯片BUG，结果折腾几天发现只是自己在传输完成后忘了做cache失效。
最后，多说一句方向上的建议。DMA本身只是一柄工具，它的最终目的是配合外设完成高效数据传输。所以你在学习Linux DMA时，最好带着一个具体场景去学：音频采集、网络收发、块设备或者外设控制。有一个实际项目推着走，API背后的那些看似枯燥的规则，会在你排查一个个真实问题时自然内化成肌肉记忆。
