DMA与mmap映射踩坑实录：从花屏、带宽暴跌到环形缓冲修复

如果一个Linux驱动已经把DMA跑通了，中断里能看到数据，但用户态程序通过mmap映射后读出来却全是乱码，你会先怀疑哪一环？我最近一个图像采集项目又把Linux内存映射机制和mmap的边界完整摸了一遍：DMA缓冲区从分配、映射到同步，每一步都藏着能让你加班好几天的坑。这篇不打算讲理论教科书，就按我自己踩坑的顺序来写——数据花屏、带宽暴跌、帧撕裂、连用户态mmap参数都能补一刀，最后是怎么收场的，全记录如下。想直接抄作业的可以收藏，想搞明白原理的，也可以对照着捋一遍。

1. 项目背景：一个看似简单的高带宽DMA映射需求

1.1 为什么非要mmap，而不是read/write

项目本身是某图像采集板卡，传感器数据通过DMA搬进DDR，应用层要做实时预览和录制。一帧RAW图像大约8MB，30帧/秒就是240MB/s的持续流量。如果用户态用read()去拿数据，每次都要经过内核缓冲到用户缓冲的memcpy拷贝，而且中转过程还夹着一次DMA同步操作。一个240MB/s的memcpy在嵌入式平台上足够吃掉不少CPU预算，更不用说调度延迟、设备节点锁、内核态用户态切换这些零碎开销。所以mmap几乎是这类场景的默认选择——驱动把DMA缓冲区直接映射到用户进程地址空间，应用指针指的是和DMA硬件同一个物理页，绕开拷贝，一次映射长期使用。

但mmap和普通文件映射完全不是一回事。普通文件映射有page cache替你兜底，内核管理读写回写；而驱动的mmap映射的是外设或者驱动自己分配的内存，驱动需要在file_operations->mmap回调里明确告诉内核"这片虚拟地址对应哪一段物理内存"，同时还要自己处理好cache一致性、页对齐、访问权限、同步时序。哪一环掉链子，都表现为"数据不对"。

1.2 最初的实现草图（错误示范）

最初方案很天真：驱动probe里kmalloc一大块缓冲，用virt_to_phys把内核虚拟地址转成物理地址喂给DMA，mmap回调里直接用remap_pfn_range把这块物理内存映射到用户态。

/* 错误路线草图，千万别照着写 */ static int probe(...) { dev->buf = kmalloc(IMG_BUF_SIZE, GFP_KERNEL); dev->buf_phys = virt_to_phys(dev->buf); /* 注册字符设备、ISR等 */ } static int buf_mmap(struct file *filp, struct vm_area_struct *vma) { unsigned long len = vma->vm_end - vma->vm_start; return remap_pfn_range(vma, vma->vm_start, dev->buf_phys >> PAGE_SHIFT, len, vma->vm_page_prot); }

这段代码看起来只干了一件事——把物理地址告诉页表。实际上后面每个环节都在坑我，下面逐个拆。

2. mmap在驱动侧的真实执行路径，比你想的更挑剔

2.1 用户态一个mmap，内核帮你做了三件事

应用调用mmap之后，内核返回一个虚拟地址，这一步只是建立起一份VMA（虚拟内存区域），把"文件fd + 偏移"和一段线性地址绑定。VMA的创建、权限校验、区间合并都由内核管理，驱动管不到。等文件描述符背后的设备驱动被唤醒时，内核会调用它的file_operations->mmap回调，把VMA交给驱动处理。驱动在这个回调里要做的事情，决定了映射是否有效。

VMA里对驱动最重要的几个字段：vm_start和vm_end标定虚拟区间，vm_pgoff保存用户传入偏移的页号，vm_page_prot决定页表项的权限和cache属性。驱动得根据vm_pgoff选择物理缓冲区，按vm_start到vm_end的长度完成映射。

2.2 驱动里的关键：不是"创建映射"，而是"交代物理来源"

在驱动里，映射的本质不是创建虚拟地址，而是把一段物理地址区间和VMA关联起来。经典做法有两种：底层接口remap_pfn_range，以及专门服务DMA缓冲的dma_mmap_coherent。

remap_pfn_range只负责填充页表项，参数里给一个pfn（物理页帧号）就行。它不管cache一致性，不管IOMMU/SMMU，也不管总线地址。你给它什么pfn，它就把什么物理页映射过去。而dma_mmap_coherent是框架层封装，专门用于dma_alloc_coherent这类一致性缓冲，会综合考虑设备IOMMU、映射属性，以及缓冲区本身的一致性要求。

2.3 MAP_SHARED vs MAP_PRIVATE：别在这一步埋线

DMA缓冲区映射必须是MAP_SHARED。如果用户态用MAP_PRIVATE，内核会按写时复制处理，应用写数据先复制页面，写不到真正的物理页上；顺序反过来也一样，DMA写进内存的数据，用户态看到的是旧副本，这种问题排查起来极其隐蔽，因为只有部分写入会丢。所以驱动代码里最好检查vma->vm_flags，发现没有VM_SHARED直接返回-EINVAL，省得后面被各种怪现象折腾。

另外驱动里建议把vma->vm_flags加上VM_DONTEXPAND和VM_DONTDUMP。前者避免mremap擅自扩展这个区域，后者防止进程coredump时把这块特殊内存倒出来生成一个几百MB的core文件。

3. 第一次踩坑：kmalloc大缓冲+remap_pfn_range，花屏和错行只是表象

3.1 现象和第一轮排查

第一版驱动跑起来后，采集出的图像花屏、错行，但ISR里打印缓冲区头部字节却符合预期。这个矛盾最有迷惑性——设备侧数据没问题，用户态读到的不对。我第一反应是DMA描述符配置出错或者id映射问题，查寄存器看不出异常。后来换了个粗暴办法：用户态先把整个mmap区域memset成0xAA，再让设备写几个标志字节进去，读出来只有前半段变了，后半段还是0xAA。这基本锁死了结论：用户态映射的物理区间，和DMA实际写入的内存区间，根本不是同一块。

3.2 根因一：分配器给出的"地址"不一定适合DMA

kmalloc返回的是内核虚拟地址，DMA硬件需要的是物理地址或者总线地址。低端连续RAM上可以virt_to_phys，但大缓冲场景这个假设很脆弱。项目里缓冲区配置的是4MB，kmalloc做大块分配走订单分配，需要找连续物理页，系统长时间运行后四兆连续页并不好找，分配失败的概率很高。更麻烦的是，不少驱动代码会写一个"分配失败就回退vmalloc"的兜底逻辑。vmalloc保证虚拟连续，但物理页是零散的，这时用virt_to_phys取到的只是第一个页的物理地址，DMA搬运后续数据全写到别的页上去，映射却是从第一页开始的，表现就是花屏错行。

就算碰巧分到了连续物理页，kmalloc返回的内存也没有经过一致性处理。CPU的cache里还残留着旧数据，DMA把新数据写进了DDR，CPU读取时命中的是cache里的旧值，图像看起来就像几帧前的残影或者完全没有更新。这是"数据对不上"最经典的原因之一。

3.3 根因二：remap_pfn_range不懂"一致性"

remap_pfn_range把物理页映射到用户空间时，页表属性直接沿用vma->vm_page_prot。如果你没有显式把这段区间设成非cacheable，它默认就是普通可缓存的RAM映射，这本身没问题，但驱动必须在DMA写入前后替CPU和cache做正确的同步操作。而实际代码里往往漏掉了这一步。多核CPU加一个DMA引擎的环境下，用户态读取时命中旧cache几乎必然发生。

3.4 修改：先换dma_alloc_coherent，把"是否同步"这个变量去掉

这轮修复最快的路径是改用dma_alloc_coherent：分配连续内存、返回CPU可用的虚拟地址和DMA可用的总线地址，并把映射属性设置成设备与CPU之间不需要软件同步。对应driver里的mmap也要换成dma_mmap_coherent。换上以后，用户态读取立刻正常了，数据内容全部正确。代价很快暴露——第4节那个性能坑。

4. 第二次踩坑：数据正确了，带宽却对半切，coherent属性成了短板

4.1 新现象：同样的代码，访问mmap区域慢了一截

数据是正确了，但应用遍历整帧图像时的耗时明显上涨。perf一跑，大量data cache load stall，IPC掉得没法看。原因只有一句话：这块内存在CPU侧被映射成了非缓存属性。

4.2 为什么coherent内存CPU访问慢

dma_alloc_coherent解决的是一致性，代价是"不缓存"。CPU读写直接透过cache访问DDR，绕过cache line。安全是安全了，但每次load/store都走总线，高频逐字节处理时吞吐可以比cacheable访问低一个数量级。在ARM这类平台上尤其明显。控制块、状态区这类低频访问用coherent内存完全没问题，但大数据流、CPU要反复处理的图像缓冲，就不适合了。

4.3 换方案：普通内存 + dma_map_single，保留缓存同时手动同步

后来换成了标准做法：缓冲用普通内存分配，DMA方向用dma_map_single映射，得到dma_handle；DMA启动前和完成后，显式调用dma_sync_single_for_device和dma_sync_single_for_cpu维护cache一致性。这样既保留了CPU侧的高性能缓存访问，又把一致性问题锁在驱动代码的几个固定点里。

/* 分配普通RAM，映射给DMA，方向为DMA_FROM_DEVICE（设备写、CPU读） */ buf->cpu_ptr = kzalloc(buf_size, GFP_KERNEL); buf->dma_handle = dma_map_single(dev, buf->cpu_ptr, buf_size, DMA_FROM_DEVICE); if (dma_mapping_error(dev, buf->dma_handle)) { /* 错误处理 */ } /* 设备启动DMA前：清掉CPU侧脏cache，让设备写入有干净起点 */ dma_sync_single_for_device(dev, buf->dma_handle, buf_size, DMA_FROM_DEVICE);

mmap这段就不能用dma_mmap_coherent了，因为缓冲不是coherent分配来的。简单做法还是remap_pfn_range，pfn取virt_to_phys(buf->cpu_ptr) >> PAGE_SHIFT，保留vma->vm_page_prot里的cacheable属性。如果你的设备有SMMU/IOMMU，这里别自己remap，应该用框架对应的mmap封装，否则映射出去的物理地址和DMA实际访问的总线地址不一定对得上。

5. 第三次踩坑：同步顺序和缓冲所有权，成了"半帧新半帧旧"的元凶

5.1 现象：轮询到flag后，图像还有撕裂

改成手动sync后，大多数帧都正确了，但随机还会出现半帧新半帧旧。问题不在sync API本身，而在"谁在什么时候调用了它"。DMA缓冲是一块内存，由CPU和DMA轮流使用。两边没商量好交接点，就会撕裂。

5.2 sync方向与时机的正确顺序，不是"对称操作"

dma_sync_single_for_cpu和dma_sync_single_for_device不是对称的两个步骤，它们的顺序取决于DMA方向和数据的所有者是谁。以最常用的DMA_FROM_DEVICE（设备写内存、CPU读）为例，完整时序是：

5.3 断裂点：应用读到的flag与缓冲内容之间，没有同步屏障

另一个隐蔽问题是标志位和缓冲区内容的可见性。驱动在ISR里做完sync后更新一个flag，用户态轮询到这个flag后立刻读缓冲。如果flag用的是普通cacheable内存，CPU侧和DMA侧对同一cache line的操作顺序没有任何保证：flag先到，不代表缓冲数据也先到了。更稳的做法，是把控制状态区独立出来，用一页dma_alloc_coherent分配成一致性内存，专门放flag和缓冲区状态。数据区用手动sync的cacheable内存，状态区用不缓存的coherent内存，两边互不干扰。低频访问的状态区慢一点没关系，换来的是同步语义清晰。

5.4 正解：环形多缓冲 + 转移所有权

单缓冲在任何时序下都很难避免CPU和DMA在同一块内存上的竞争。最终方案是缓冲池：驱动维护N个缓冲区（工程上取四个比较顺手），每个缓冲区有状态机：FREE（空闲可交给DMA）、READY（DMA写满、CPU可读）、BUSY（CPU正在读）、EMPTY（读完了等待归还）。

完整流程是这样：驱动把一个FREE缓冲交给DMA，设备写入；DMA完成中断里做dma_sync_single_for_cpu，把缓冲标记READY放入就绪队列；应用申请到READY缓冲后读取，读完通过ioctl归还；驱动收到归还后先做dma_sync_single_for_device，再把缓冲标回FREE，重新入队交给DMA。这个模式把"缓冲所有权"的交接点固化下来，CPU和DMA永远不会同时操作同一个缓冲。

5.5 简化版驱动骨架

static irqreturn_t dma_irq(int irq, void *arg) { struct buf *b = get_finished_buf(dev); /* 设备写完了，CPU要读，先把cache invalidate掉 */ dma_sync_single_for_cpu(dev, b->dma_handle, b->size, DMA_FROM_DEVICE); b->state = BUF_READY; wake_up(&dev->wq); /* 继续提交下一个空闲缓冲给DMA */ dma_start(get_free_buf(dev)); return IRQ_HANDLED; } static int buf_mmap(struct file *filp, struct vm_area_struct *vma) { struct my_dev *dev = filp->private_data; unsigned long len = vma->vm_end - vma->vm_start; unsigned long buf_offset = vma->vm_pgoff << PAGE_SHIFT; int i; if (buf_offset + len > dev->total_size) return -EINVAL; if (buf_offset % BUF_SIZE) return -EINVAL; i = buf_offset / BUF_SIZE; return remap_pfn_range(vma, vma->vm_start, virt_to_phys(dev->buf[i].cpu_ptr) >> PAGE_SHIFT, len, vma->vm_page_prot); }

6. 内核刚消停，用户态mmap参数又来补刀

6.1 offset是页对齐字节，vm_pgoff是页号——千万别混

用户态mmap的offset参数单位是字节，但必须是页大小的倍数；内核拿到后会右移PAGE_SHIFT存进vma->vm_pgoff，驱动眼里vm_pgoff的单位是页。最容易翻车的是驱动里再做一次"除以页大小"之类的二次换算，或者把vm_pgoff直接当字节偏移用。多缓冲场景驱动常用约定"第i个缓冲的offset = i * BUF_SIZE"，但驱动代码里的换算应该是：

unsigned long buf_offset = vma->vm_pgoff << PAGE_SHIFT; int i = buf_offset / BUF_SIZE; if (buf_offset % BUF_SIZE) return -EINVAL;

应用层有人喜欢把offset强转成int，在64位系统上大偏移一旦溢出，返回MAP_FAILED或者映射到错的位置，这种问题出现在生产环境最难排查。

6.2 长度差一页，踩到SIGBUS

另一种常见错误是映射长度差了一页。驱动分配了BUF_SIZE，用户态mmap传了BUF_SIZE - 1，VMA长度恰好少最后一页，应用访问最后一个字节时，PTE不存在，直接SIGBUS。反过来，如果length超过驱动实际可用大小，而驱动里只检查len <= BUF_SIZE却没检查"当前offset对应的剩余长度"，内核就会去映射驱动根本没准备好的物理区间，随机访问隔壁内存。所以mmap回调里必须组合校验：buf_offset + len <= total_size，且buf_offset按BUF_SIZE对齐。

6.3 应用层的核对技巧

遇到问题先strace一下mmap的返回值，如果MAP_FAILED再去翻dmesg里的驱动日志。更实用的做法是驱动导出一个debugfs节点，把buf_size、mapped_len、vm_pgoff、pgprot属性全部打印出来，应用层拿真实参数一对比，几秒钟就能定位是传参问题还是驱动映射问题。这个调试节点后来一直保留，线上排查比看代码快得多。

7. 复盘：这次DMA缓冲区踩坑，最后沉淀出几条铁律

7.1 排查顺序：先查物理，再查cache，再查时序，最后才查硬件

我把这次排查链路整理成一张表，后面自己遇到类似问题都是按这个顺序走的：

7.2 我后来再遇到DMA+mmap需求时的固定套路

第一步永远是先跑通：dma_alloc_coherent配合dma_mmap_coherent，即使慢一点，先把中断、时序、参数传递这些基础逻辑全部验证掉。数据能正确读到了，再考虑性能，换成普通内存加dma_map_single和手动同步。同步调用全部收口在三个点：DMA启动前、DMA完成中断里、缓冲区归还时，绝不允许散落在应用回调或者随意线程里。

第二步把用户态mmap参数直接用公共封装写死：页对齐长度、按BUF_SIZE计算的offset、强制MAP_SHARED，每个进程只有一种正确用法。这样至少把"用户参数传错"这一类问题从根上掐掉。

最后再分享一个小技巧：验证"映射区域和DMA区域是否同一块物理内存"，最快的方法不是打印地址拍脑袋，而是用户态先对整个mmap区域写一个递增pattern，再让驱动做一次DMA_TO_DEVICE把这块内存搬到另一块内存，然后驱动侧读回对比。能通过，物理链路基本就稳了；再往后卡，一定是cache或时序问题。这个动作我每次都会做，算是给整个DMA缓冲区映射链路建一个最朴素的自检。