DMA 和 CPU 之间的那点“小矛盾”，我是在一次摄像头图像花屏的调试中彻底领教了。当时驱动代码里明明做了 cache 操作，但图像数据就是隔三差五出现错位和撕裂，查了一整天，最后发现问题是设备树里少了一个dma-coherent属性。从那以后我就意识到，这个看上去毫不起眼的属性，其实是 DMA 驱动开发里最容易踩坑、也最容易被人忽视的环节之一。
很多做嵌入式 Linux 的朋友，尤其是从裸机开发转过来的，一开始都会对 DMA 和缓存一致性这个概念感到头大。裸机时代内存属于谁、由谁访问、要不要做缓存同步全都由你自己说了算，但到了 Linux 内核里，CPU 有缓存，DMA 引擎直接访问内存，两边如果不协调好，轻则数据错乱，重则内核崩溃。而dma-coherent这个设备树属性，恰恰就是用来告诉内核“我这套硬件平台，DMA 访问内存时是和 CPU 缓存保持一致的，不需要软件再去做额外的同步”。这篇文章我就想顺着这个属性，把 DMA 一致性的原理、内核里的实现路径、设备树里怎么配、实际调试中怎么用，以及我踩过的几个典型大坑，一次性聊透。
1. 先搞明白 DMA 和 CPU 缓存之间的“各说各话”
1.1 为什么 DMA 天然容易和 cache 打架
要理解dma-coherent，首先得理解 DMA 为什么会和 CPU 缓存产生冲突。CPU 在读写内存的时候，不会每次都直接访问 DDR，而是会先把数据搬到各级 Cache 里，比如 L1、L2，有的平台还有 L3。Cache 的意义在于速度快、命中率高，绝大多数时候 CPU 在缓存里就能完成读写，只有缓存未命中才会真的去触碰 DDR。
问题就出在这里：DMA 控制器是直接访问物理内存的，它不经过 CPU，更看不到 CPU Cache。于是就会出现两种非常典型的冲突场景。
第一种是 CPU 往某块内存写了一段数据，数据其实还躺在 CPU Cache 里没来得及刷回 DDR，DMA 引擎这时候去读这块内存，读到的是一堆陈旧数据。第二种反过来，DMA 往内存里搬进来新的数据，但 CPU Cache 里还保留着旧数据，CPU 去读的时候命中缓存，拿到的还是老数据。
我把这种局面比喻成两个人共用一本笔记本，第一个人在自己脑子里记了三页纸的摘要，说要用的时候直接从脑子里的摘要取，第二个人却直接去翻实体笔记本，两个人看的根本不是同一份内容。裸机环境下，这个问题通常靠程序员手动维护，比如访问外设 DMA 缓冲区之前先clean cache，之后再做invalidate cache。但 Linux 内核里驱动千千万，不可能靠每个驱动开发者都精通缓存操作的时序来保证正确性，所以内核必须提供一套规范的 API 和机制，让驱动开发者不直接碰 cache，也能写出正确的 DMA 驱动。
1.2 没有 dma-coherent 的时候，驱动要额外做哪些事
如果硬件不支持一致性，也没有在系统层面给某个设备声明dma-coherent，那么驱动在使用 DMA 传输数据时，必须按照缓存操作的“套路”来处理。以内核里的 DMA API 为例，最典型的是两种情况的处理：
用dma_map_single()做流式映射时，驱动要根据数据传输方向，在映射之后、传输开始之前，调用dma_sync_single_for_device()，把 CPU Cache 里脏数据刷回内存，或者让 Cache 里的旧数据失效；传输完成后，再用dma_sync_single_for_cpu()做反向操作。这些步骤漏掉任何一次，数据就有可能是错的。而且这种操作本身就是有性能开销的，每次刷 Cache 都要把几百 KB 甚至几 MB 的数据逐行写回，在高速外设场景下，这种开销非常可观。
而使用dma_alloc_coherent()分配一致性内存时，内核在底层会保证这块内存不会被 Cache 随意缓存，或者通过硬件机制保证 Cache 和内存始终同步，驱动拿到这块内存后不需要再做额外的 cache 操作。但前提是，内核必须知道当前设备是否具备这种“一致性”能力。dma-coherent属性，恰恰就是设备树里用来向上层传递这个关键信息的载体。
所以，理解dma-coherent不是去背一个设备树属性名，而是要明白它在整个 DMA 子系统里扮演的“提示符”角色——它告诉内核：你可以放心大胆地为这个设备走一致性映射路径，不需要为它做多余的缓存同步动作。内核拿到这个信息以后，dma_alloc_coherent()、dma_pool这些接口的行为都会因此发生改变，设备的dma_ops也会被设置成对应的实现。
2. 设备树里的 dma-coherent：声明、语义与内核实现路径
2.1 设备树里怎么配：一个最小实例
设备树是硬件描述语言，对驱动来说最重要的还是它最终能转换成内核能识别的资源信息。dma-coherent是一个布尔属性，不需要写值，只要在设备节点里出现，就代表这个设备的 DMA 操作具备缓存一致性能力。一个典型的配置长这样：
&soc { usb_controller: usb@31d00000 { compatible = "vendor,usb-xhci"; reg = <0x0 0x31d00000 0x0 0x100000>; interrupts = <GIC_SPI 76 IRQ_TYPE_LEVEL_HIGH>; dma-coherent; }; };就这么一行，没有值，没有<1>之类的参数，但却能决定xhci-plat驱动在probe阶段绑定到platform_device时，是走一致性映射还是走非一致性映射路径。这个属性对驱动是透明的，驱动本身无法直接通过某个device tree API去查询它，而是由内核框架在设备初始化阶段读取，并写入到struct device内部的标志位里。
2.2 内核里怎么解析的：从 device_node 到 device
设备树解析这块，函数调用链看起来很长，但关键点并不复杂。当平台设备被创建时，内核会调用of_dma_configure()，这个函数负责从device_node里读取 DMA 相关的属性，包括dma-ranges、dma-coherent以及dma-noncoherent。
static int of_dma_configure(struct device *dev, struct device_node *np) { bool coherent; ... coherent = of_property_read_bool(np, "dma-coherent"); ... if (coherent) dev->dma_coherent = true; ... }of_property_read_bool()这个接口，只要设备节点里存在dma-coherent属性，就返回 true，不管它有没有值。所以设备树里那种dma-coherent;的空属性和dma-coherent = <0>;这样的写法，真实的解析结果并没有本质区别，因为内核关心的只是该属性是否存在。因此平时写设备树的时候，遵循规范用空属性就好。
设置完dev->dma_coherent之后，内核在后续 DMA API 的调用中，就会根据这个标志位以及平台相关的dma_ops，来决定实际的内存映射和缓存操作策略。比如在 ARM64 平台上，arch_setup_dma_ops()会根据是否 coherent 来设置对应的dma_ops：一致的设备会走arm_coherent_dma_ops，而不一致的设备则会走到arm_dma_ops。这两个dma_ops里的实现，在是否调用dma_cache_maint这类的缓存维护操作上，有着本质的差别。
2.3 dma-coherent 和 dma-noncoherent 到底是什么关系
有朋友会问，既然有了dma-coherent，为什么又冒出个dma-noncoherent？其实这两个属性是同一个特性的正反面。在老一些的设备树规范中，大家默认设备是不一致的，所以只用dma-coherent来“取反”；但是后来规范发展了，也引入了显式的dma-noncoherent来消除默认值带来的歧义。
这两个属性同时在节点里出现时，以dma-noncoherent为准，因为内核里对这两个属性的解析顺序是固定的，非一致性的判断优先级更高：
if (of_property_read_bool(np, "dma-noncoherent")) { dev->dma_coherent = false; } else if (of_property_read_bool(np, "dma-coherent")) { dev->dma_coherent = true; }从设备树维护的角度来说，我个人的建议是，只要设备确实不具备一致性，就显式地写上dma-noncoherent，这样后续维护设备树的人一眼就能看清设计意图，不用靠猜默认值来推断。凡是涉及 DMA 的设备节点，最好都明确声明这两个属性中的一个，不要留白，因为“留白”意味着你依赖的是内核版本相关的默认行为，升级内核后可能会发现驱动行为变了。
3. 从分配到底层映射：dma-coherent 在驱动里的实际用法
3.1 驱动如何申请一致性内存：dma_alloc_coherent
设备树里声明了dma-coherent，驱动层最直接的受益者就是dma_alloc_coherent()。它的原型是：
void *dma_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle, gfp_t flag);这个接口会返回两个地址：一个虚拟地址void *，是 CPU 用来访问内存的；一个dma_addr_t *，是 DMA 引擎用来发起传输的物理地址（在启用 IOMMU 的设备上也可能是经过 IOMMU 映射后的总线地址）。驱动在使用这块内存时，CPU 侧直接通过虚拟地址读写，然后通知 DMA 控制器用dma_handle里的地址去搬数据，全程不需要显式做 cache 同步。
在内核实现里面，dma_alloc_coherent()会根据设备标志位来决定走哪条路径。如果设备是 coherent 的，ARM64 平台上会直接调用__dma_direct_alloc_pages()，从 CMA 或原子池里分配内存，并且配置页表时将这块内存映射为 Normal Non-Cacheable 或是在硬件支持的情况下映射成 Normal Write-Back Cacheable 但带硬件一致性的属性。如果设备不是 coherent 的，同样的函数会额外执行缓存维护操作，保证分配出来的内存区域在 CPU 侧看起来是“干净”的。
实际编码中，我建议驱动在申请一致性内存之前，先明确设置一次dev->coherent_dma_mask，比如：
dma_set_coherent_mask(dev, DMA_BIT_MASK(32));如果不设置掩码，dma_alloc_coherent()在分配时可能会因为 mask 太小而失败，或者无法满足外设的寻址能力。我在新平台 bring-up 时，见过太多类似“分配失败、返回 NULL”的问题，最后查下来都是掩码没设对。
3.2 一致性映射和流式映射：什么时候用哪个更合理
驱动里并非所有 DMA 场景都适合用dma_alloc_coherent()。因为一致性映射通常意味着被分配的内存不能被 Cache 友好地利用，要么是关闭了 Cache，要么是通过硬件特性保证同步，这在某些场景下会损失性能。与其一把梭全用一致性内存，不如根据传输模式来选择合适的 API。
流式映射（dma_map_single()/dma_map_sg()）适合数据量大、频率高、传输完成后 CPU 不需要长期保留数据的场景，比如网络收发包、USB 数据传输、SD 卡读写。这类场景每次传输前做一次映射，传输完成后做一次反映射，内核会在底层根据设备是否 coherent，来决定是否执行 cache clean/invalidate。做这些操作时，设备是 coherent 的情况下，底层会直接跳过 cache 操作，减少了一次内存同步的额外开销。
一致性映射则适合驱动和硬件需要长期共享一块内存、且 CPU 和 DMA 会频繁交替访问同一个区域的场景，比如采集设备的帧缓冲、显存、硬件加密引擎的输入输出缓冲区。这类场景里，每次传输都做映射和反映射反而得不偿失，直接在初始化阶段分配好一块 consistency 内存，整个生命周期内只用它，反而简洁高效。
拿我调试过的一个 VPU 解码驱动举例，硬件在解码时需要反复从某个 buffer 读数据、写数据，驱动如果在每次解码任务里去做 map/unmap，解码一帧的开销会显著增加，因为 VPU 访问内存的频次极高。最终方案就是 probe 阶段用dma_alloc_coherent()把解码用的帧缓冲全部提前分配好，VPU 跑起来之后不再频繁和 CPU 做缓存同步，性能提升非常明显。
3.3 典型驱动示例：从 probe 到传输
为了让你更直观地看到dma-coherent在驱动里的完整效果，我用一个精简的虚拟 DMA 驱动示例说明整个流程。先看伪代码：
static int my_dma_probe(struct platform_device *pdev) { struct device *dev = &pdev->dev; struct my_dma_dev *dma_dev; dma_addr_t dma_handle; void *cpu_addr; dma_dev = devm_kzalloc(dev, sizeof(*dma_dev), GFP_KERNEL); if (!dma_dev) return -ENOMEM; dma_set_coherent_mask(dev, DMA_BIT_MASK(32)); cpu_addr = dma_alloc_coherent(dev, MY_BUF_SIZE, &dma_handle, GFP_KERNEL); if (!cpu_addr) return -ENOMEM; dma_dev->cpu_addr = cpu_addr; dma_dev->dma_addr = dma_handle; writel(lower_32_bits(dma_handle), dma_dev->base + DMA_SRC_ADDR); writel(MY_BUF_SIZE, dma_dev->base + DMA_XFER_SIZE); ... } static void my_dma_start(struct my_dma_dev *dma_dev) { // 当设备声明了 dma-coherent 时，从这里到传输结束 // 都不需要调用 dma_sync_single_for_device ... writel(1, dma_dev->base + DMA_START); }这段代码如果放在一个非 coherent 的设备上跑，即使内核不报错，数据的正确性也无法保证，因为缺少了dma_sync_single_for_device()。也正因如此，驱动开发者必须清楚地知道当前平台硬件是否表里如一地支持 coherent，否则代码看起来没问题，实际效果却像开盲盒。
4. 硬件视角：什么样才算真正的 cache coherent
4.1 硬件一致性的几种典型实现
设备树里的dma-coherent不是随便加的，它是对硬件能力的描述。只有硬件确实具备一致性访问能力时，这个布尔属性才不是“撒谎”。在我的经验里，常见的一致性实现方式有四种。
第一种是设备本身访问内存时就带有“缓存感知”的能力，典型代表是某些 SoC 内部的总线控制器，比如 ARM 的 ACE/CHI 总线协议下，外设可以通过缓存一致性总线接口直接和其他核共享缓存。这种情况下，DMA 访问内存时，总线会主动查询 CPU 缓存，如果发现数据在缓存里，就直接从缓存拿或推进缓存更新，保证两边看到的数据是同一个版本。
第二种是设备通过 ACP（Accelerator Coherency Port）这样的端口接到互连总线上，和 CPU 的缓存层级直接进行一致性交互。这种设计常见于一些多媒体加速器上，外设访问内存时会通过 ACP 去监听 CPU 的 Cache，本质上也是硬件帮你做了原本软件要做的同步。
第三种，也是最常见的，是设备本身不具备一致性能力，但系统通过 IOMMU/SMMU 的某种特性，比如 DVM（Distributed Virtual Memory）消息或特定的页表属性，把一致性能力“翻译”给外设。这种方式本质上依赖系统级地址转换和控制单元来实现，并不是每个平台都支持，通常与iommu-map、iommus这些属性配合。
第四种最简单粗暴：直接把 DMA 缓冲区所在的物理内存映射成 Non-Cacheable（或 Device 属性），CPU 访问这块内存时完全不经过 Cache，DMA 和 CPU 面对的是同一个物理地址的同一份数据，天然不会不一致。这种方案最古老，也最可靠，唯一的代价就是 CPU 读写这块内存的性能会不如 Cacheable 区域。
4.2 没有硬件一致性时，系统是怎么“伪装”的
当硬件不完全提供一致性支持、但驱动又需要“一致”的效果时，内核就采用我们前面反复提到的软件方案：在适当的时间点做 cache clean / invalidate。这种方案也叫“伪一致性”，因为它是通过软件时序配合来模拟硬件契约。
在内核代码里，这种情况下最核心的函数是dma_cache_maint()，它最终会调用平台相关的arch_sync_dma_for_device()/arch_sync_dma_for_cpu()，在不同指令集架构上实现方式也不一样。比如在 ARM32 上就是outer_cache和dmac_map_area的组合，在 ARM64 上则使用dc civac、dc cvac等缓存操作指令。
这种方案最关键的问题在于时序约定：驱动必须在 DMA 写内存之前，把 CPU Cache 里的脏数据刷下去；在 DMA 读内存之前，把 CPU Cache 里的旧数据失效。一旦时序出错，数据同步就会出现问题。比如一个网络驱动，在ndo_start_xmit()里把 SKB 的物理地址交给 DMA 引擎之前，就必须保证缓存数据已经刷回内存，否则网卡发出去了可能是旧数据。因为这类问题只在特定时序下出现，平时不容易复现，所以调试难度极大。
4.3 与 IOMMU 结合时，coherent 配置怎么配合
很多现代 SoC 上，DMA 传输并不是直接访问物理内存，而是要经过 IOMMU/SMMU 做地址转换。这种情况下，“一致性”能力还要进一步看 IOMMU 如何处理缓存。如果 SMMU 本身不具备或者没有启用与 CPU Cache 的一致性协议，那么即便设备树里写了dma-coherent，实际数据在 SMMU 做转换的过程中，也可能会遇到缓存不同步的问题。
从设备树配置的角度，通常要看两个角度：一是 IOMMU 节点自身是否支持并配置了 coherent 属性，二是终端设备节点是否也要声明 coherent。以 ARM SMMU-v3 为例，SMMU 内部有一组和缓存相关的控制位，在设备树或 ACPI 表中会有相应的描述。如果 SMMU 可以和 CPU Cache 做一致性交互，那么它通常会把这种能力向下传递给经过它做 DMA 的终端设备。换句话说，终端设备节点的dma-coherent只有在整条路径（互连总线、SMMU、内存控制器）都支持一致性时才是真实可靠的。
我在实际项目中遇到过一种情况：同一个外设 IP，在平台 A 上直连总线不经过 SMMU，设备树里写dma-coherent没问题；换到平台 B 上，该外设挂在 SMMU 后面，而 SMMU 配置里缺失了 coherent 相关的固件配置，结果同样一份设备树跑起来就数据错乱。排查到最后才发现，不是外设的驱动变了，而是它背后的“一致性通道”变了。所以跨平台复用设备树时，dma-coherent这个属性一定要重新审视，不能想当然地复制粘贴。
5. 常见坑与排查实录
5.1 现象一：数据偶尔错乱，概率性翻车
这是最让人头疼的问题，没有之一。图像偶发花屏、网络偶发丢包、存储偶发校验失败，而且用示波器和总线分析仪很难抓到规律。这类问题我排查过多次，最常遇到的原因有三种：
第一种，设备树里漏写了dma-coherent，或者驱动里错误地使用了非一致性映射，导致每次传输时缓存同步的时序不完全满足要求。比如在中断上下文里访问 CPU 侧的 buffer，中断返回后驱动和 DMA 之间的同步路径被打断，导致数据不一致。
第二种是中断和轮询并发访问同一块 buffer，软件上没有做好保护。比如一个 eth0 的驱动，发送路径在进程上下文，完成中断在硬中断上下文，两边如果同时去访问dma_alloc_coherent()分配出来的缓冲区，而缓冲区被 CPU 写入了但还没刷 Cache，DMA 引擎提前开始搬运，就会搬出旧数据。
第三种是底层内存类型配置错误，导致 DMA 操作访问的物理内存和 CPU 映射的虚拟内存并不指向同一块物理内存。这种情况在开启 IOMMU 后比较常见，因为 DMA 的“地址”是经过 SMMU 翻译后的地址，如果映射关系配错，DMA 引擎搬的根本就是另一块内存。
遇到概率性问题，我的第一条建议就是先确认设备树属性：cat /sys/kernel/debug/dma-api/dump或者直接在驱动里打印dev->dma_coherent，确认这个设备在运行时到底被内核判成哪种类型。接着检查驱动里有没有正确使用dma_map_single()/dma_alloc_coherent()，如果驱动里用了流式映射却漏掉dma_sync_single_for_device()，问题就很可能出在这里。
5.2 现象二：配置了 dma-coherent 反而性能变差
这个现象比较反直觉，但也真实存在。dma-coherent的本质是让 DMA 和 CPU 共享缓存一致性，但一致性保证是有硬件开销的。比如在一个不支持ACE/CHI总线的平台上，强制给设备声明dma-coherent，内核虽然不会报错，但底层可能会退化成“全 Cache 一致 + 软件兜底”的模式，性能上反而没有“直通非缓存映射”来得好。
更典型的情况是，dma_alloc_coherent()分配的一致性内存，如果底层映射成 Non-Cacheable，CPU 访问这块内存的每一次读写在底层都会触发外设总线上的完整事务，在没有写合并和读组合优化的低端平台上，性能会比 Cacheable 的映射差一截。所以我们才会看到，有些设备驱动明明知道硬件是 coherent 的，也依然选择用dma_pool+ 流式映射的方式来管理其高频访问的缓冲区，就是为了在缓存性能和一致性保证之间找一个平衡点。
遇到性能下降时，建议先用perf看 CPU 侧的 cache miss 率和内存带宽，再对比配置前后的数据。如果发现 DMA 传输本身没变快，但 CPU 访问 DMA buffer 的耗时成了瓶颈，那就要重新评估这个设备是不是真的适合dma-coherent，或者考虑换用流式映射来让 hotspot 数据保留在 Cache 里。
5.3 现象三：dma_alloc_coherent 分配失败
dma_alloc_coherent()返回 NULL 或触发 OOM，这类问题不算少见，尤其是在内存碎片比较严重、或者 CMA 区域被占满的时候。一致性内存通常来自两个池子：一个是一般的 page allocator，另一个是 CMA。当设备掩码是 32 位时，如果系统内存高于 4G，DMA 分配区域会受到限制，能从低端内存拿到的页就非常有限，分配大块内存时很容易失败。
我调试过一个多媒体驱动，需要分配 16MB 的帧缓冲，结果dma_alloc_coherent()在连续运行了几个小时后失败。排查后发现是 CMA 区域被其他设备的大块分配消耗殆尽，而且没有及时回收。解法是在内核启动参数里扩大 CMA 区域，比如cma=64M，并确保设备驱动释放 buffer 时会真的回到 CMA 池而不只是回到 page allocator。
另外，dma_alloc_coherent()使用的掩码是coherent_dma_mask，如果不额外设置，继承默认值可能不满足设备需求。我在驱动里常这样设：
dma_set_mask_and_coherent(dev, DMA_BIT_MASK(30));同时支持dma_set_mask()和dma_set_coherent_mask()，确保绝大部分 DMA API 都能和设备的寻址能力匹配。
5.4 排查工具和方法：让 dma-coherent 问题无所遁形
定位 DMA 一致性问题时，我常用的方法按优先级排列：
第一，确认设备树属性生效情况。挂上 debugfs 或者直接在驱动里dev_info()把dev->dma_coherent打印出来，先确认内核理解的和设备树描述的一致。
第二，使用 DMA API debug 功能。内核开启CONFIG_DMA_API_DEBUG后，可以检测出 DMA API 的不规范调用，比如映射后忘记解映射、同步操作的方向错误等。不过这个选项开启后会对性能有影响，一般只在调试版本里打开。
第三，用 tracepoint 观察实际行为。内核提供了dma:前缀的一系列 trace 事件，比如dma_map_single、dma_unmap_alloc、dma_alloc_consistent等，可以读出映射地址、长度、方向，再结合硬件寄存器的值比对，能较快定位问题是出在 CPU 侧还是设备侧。
第四，物理内存 dump 比对。分配一个固定的 buffer，让 CPU 先写入 pattern，再由 DMA 读回来，如果设备和 CPU 读到的数据不一致，那就说明一致性链路有问题。可以直接在驱动里做一个自检模块，把 0xAA、0x55、随机数等 pattern 反复写入、读回、比对，这种自检代码哪怕上线后也可以留着，方便后续现场定位问题。
5.5 我总结的几条实用经验
调试多了之后，我对dma-coherent这个属性形成了一套自己的使用守则：
- 新板子 bring-up 时，先不要急着接管全部 DMA 功能，写一个最简单的数据回环测试，通过
dma_alloc_coherent()+ 外设自测模式确认一致性链路是否打通。 - 设备树不是“调参”用的，而是描述硬件能力的。
dma-coherent是否能写，要看芯片手册里有没有明确说明设备访问内存时具备一致性能力，或者总线是否提供了这种机制。 - 驱动代码里，不要只依赖设备树的声明，也要在关键路径上做防御性判断，比如统一使用 DMA API 而不是直接操作
phys_to_virt()之类的底层函数，这样即使设备树配置错了，也更容易通过 API 内部逻辑发现异常。 - 尽量保持设备和驱动之间的“能力契约”清晰。如果硬件是 non-coherent 的，驱动开发时就要在初始化阶段明确调用
dma_set_ops()或至少统一走流式映射 API，避免在 probe 之后才暴露问题。
最后再分享一个小技巧：当你在两个硬件平台之间移植同一个外设驱动时，不要直接拷贝设备树里的dma-coherent属性，而是先把两个平台的芯片手册里关于总线连接、SMMU 配置、缓存一致性支持的章节找出来，对照一遍再填属性。我自己就是因为图省事，直接吃了平台 B 的大亏，从那以后，dma-coherent在我心里再也不是一个“可加可不加”的补丁，而是必须从硬件原理上确认的一项关键配置。
