简介面向Zynq SoC与Petalinux开发者的AXIDMA驱动移植资源包围绕PS与PL间高效DMA数据传输场景提供驱动源码、编译脚本及示例应用适合有Linux驱动与AXI总线基础的中高级嵌入式开发者。压缩包共25个文件以C源码、H头文件、MK编译配置为主并含Makefile、Kbuild、许可证与说明文档整体仅84KB结构精简。已有1635人学习下载。资源除驱动核心代码外还附带设备树节点配置参考、基于libaxidma库的传输测试程序以及用于组织编译的模块拆分说明覆盖从内核驱动到用户态接口的完整链路通过对照源码与示例可系统理解AXIDMA驱动框架、中断处理、内存映射及数据对齐等关键点减少在Petalinux环境中自行摸索的时间快速完成驱动移植与功能验证进而提升PS与PL间数据传输性能。1. 从 xilinx_axidma-master.zip 看 AXI DMA 驱动这套代码能帮你省掉哪些事搞过 FPGA 加速卡或者片上系统SoC的人都有体会逻辑写好了数据要跟 CPU 交互DMA 驱动就是那个绕不开的坎。AXI DMA 是 Xilinx 平台上的标准高速数据传输 IP但这套 IP 的驱动并不像普通串口或 GPIO 那样开箱即用寄存器初始化顺序、描述符环管理、中断处理、缓存一致性每一处都能让人翻车。xilinx_axidma-master.zip 这套资源不是官方参考驱动的简单拷贝它把 AXI DMA 的通用驱动框架拆成了可以照搬的工程文件覆盖了从设备树配置到用户态读写接口的完整链路。适合正在做 Zynq、MPSoC 或 FPGA 加 PCIe 的开发者尤其是那种被 DMA 中断、缓存同步和描述符错误折磨到怀疑人生的场景。2. AXI DMA 驱动的工作原理寄存器映射与描述符环怎么配合2.1 先弄懂 AXI DMA IP 的寄存器视图AXI DMA 对外暴露的寄存器不多但每个寄存器的位定义都直接决定后续驱动代码怎么写。首先要记住它有两个独立通道MM2SMemory-Mapped to Stream负责把内存数据发给逻辑S2MMStream to Memory-Mapped负责把逻辑数据写回内存。两个通道的控制寄存器偏移不同但结构对称驱动里一般用同一种结构体分别管理。拿常用的 SGScatter-Gather模式来说寄存器主要集中在几个关键偏移控制/状态寄存器区地址偏移 0x00–0x0C、当前描述符指针0x08、0x18、尾描述符指针0x04、0x14等。这里最需要注意的是MM2S_DMACR和S2MM_DMACR这两个控制寄存器bit0 是通道使能bit1 是 SG 模式使能bit6 是中断使能。很多移植失败的案例都是因为没按顺序先把 SG 使能打开导致描述符环跑不起来。我一般调试时会先读一下MM2S_DMASR状态寄存器的 bit12SG 内部错误和 bit10接收错误这两个位是定位问题的第一入口。状态寄存器是只读的但中断标志位需要通过写 1 来清除这一点和很多普通外设不一样驱动里如果用了writel直接写 0 去清中断中断会一直挂在那里不释放后续所有中断都进不来。下面的表格整理了常用寄存器的偏移和用途实际写驱动时建议对照硬件手册逐位核对寄存器名称偏移功能摘要关键标志MM2S_DMACR0x00MM2S 通道控制bit0 使能bit1 SG模式bit6 IRQ使能MM2S_DMASR0x04MM2S 通道状态bit0 haltedbit12 SG错误MM2S_CURDESC0x08当前描述符指针必须指向对齐地址MM2S_TAILDESC0x0C尾描述符指针写这里触发硬件搬运S2MM_DMACR0x10S2MM 通道控制同上S2MM_DMASR0x14S2MM 通道状态bit0 haltedbit12 SG错误S2MM_CURDESC0x18S2MM 当前描述符硬件会更新S2MM_TAILDESC0x1CS2MM 尾描述符写这里触发搬运2.2 SG 模式与描述符环地址、长度、控制字怎么编排SG 模式的核心是描述符Descriptor。每个描述符在内存里是一个固定大小的结构由驱动软件维护硬件通过CURDESC指向第一个描述符然后不断读取下一个描述符的地址跳转。描述符必须组织成环形链表最后一跳的NEXT指回第一个这样才能连续传输大块数据。描述符的编排顺序很重要我习惯在分配时就把每个描述符的物理地址固定下来因为 AXI DMA 访问的是物理地址不能像普通驱动那样用内核虚拟地址直接传。描述符结构里通常有三个关键字段下一跳地址、缓冲区地址、控制字。控制字里包含传输长度、TX 报错中止、实际传输字节数等信息注意读取结果时要等硬件更新完这个字段再读长度。下面是一个典型的描述符结构体定义在内核驱动里常见写法如下struct axidma_desc { u32 next_desc; /* 下一个描述符的物理地址 */ u32 buf_addr; /* 数据缓冲区的物理地址 */ u32 control; /* 控制字长度、起始位、结束位 */ u32 status; /* 状态字硬件填写实际传输字节数 */ u32 reserved[2]; /* 保留字段必须清零 */ u32 app0; /* 应用字段可用于标记用户数据 */ u32 app1; }; #define AXIDMA_DESC_NEXT_MSK 0xFFFFFFC0 /* 地址低6位必须为0 */ #define AXIDMA_DESC_CTRL_LEN 0x007FFFFF /* 长度位 */ #define AXIDMA_DESC_CTRL_TXEOF BIT(31) /* 传输结束标志 */代码逻辑说明该结构体定义了 8 个 32 位字共 32 字节。next_desc和buf_addr保存的是物理地址低 6 位清零是因为描述符和缓冲区地址都必须 64 字节对齐。control的低 23 位是传输长度TXEOF是发送结束标记在多包连续传输时这个位必须由驱动按需置位。status由硬件在完成传输后写入实际传输字节数和错误标志软件读这个字段前最好加dma_rmb()内存屏障防止编译器或 CPU 乱序读到旧值。参数说明AXIDMA_DESC_NEXT_MSK用于对下一跳地址做掩码校验如果硬件回读地址时带了一些状态位可以先把高 26 位取出来做指针跳转。AXIDMA_DESC_CTRL_LEN是 23 位长度掩码所以单次传输最大长度被限制在 8MB-1超过这个值必须拆成多个描述符。这也是很多初学驱动的人踩坑的地方——想一次传 16MB硬件直接不响应最后只能拆包。环结构的管理也不复杂但有一处容易忽略驱动往里写TAILDESC时写入的地址必须和CURDESC一致并不是TAILDESC表示软件已经准备好的最后一个描述符地址硬件会从CURDESC开始一直处理到TAILDESC停下来。如果写错成第一个描述符地址硬件会认为环里只有一个描述符传输完就停后面的描述符永远不会被处理。我一般会在每次传输完成后把CURDESC读回来和预期地址做对比用这个来验证环指针是否正确。3. 驱动代码的骨架从 probe 函数到 read/write 的完整路径3.1 代码目录与关键文件哪些文件决定能不能跑起来打开xilinx_axidma-master.zip之后不要急着编译先看目录结构。这套代码的布局和常见内核驱动模块类似核心文件是axidma.c它包含了主要的设备驱动逻辑。另外几个不能忽略的文件axidma_dma.c或类似命名的文件处理 DMA 通道申请和描述符分配axidma_of.c负责解析设备树节点axidma_ioctl.c处理用户态命令还有头文件axidma.h定义接口和结构体。从实用角度看真正决定你能不能跑起来的是三个文件设备树.dtsi片段通常放在资源包的dts/目录、axidma.c里的平台驱动注册部分、还有Makefile中的内核版本适配逻辑。很多移植问题都出在设备树节点上例如中断号没有与 IP 核的interrupt-parent对齐或者dma-coherent属性漏写导致驱动 probe 成功但 DMA 传输数据乱码。我用表格整理了一份建议的阅读顺序方便按依赖关系去读代码文件核心作用建议阅读时机axidma.h结构体、ioctl 命令定义先看建立整体印象axidma_dma.c描述符环初始化与分配第二理解内存管理axidma_of.c设备树解析与资源获取第三对照你的硬件设置axidma.cprobe、open、read、write第四跟踪数据流axidma_ioctl.c用户态控制命令处理最后按需调整阅读时留意代码中是否有条件编译选项对应内核版本。常见情况是dma_alloc_coherent在旧内核需要传struct device *新内核则要求先dma_set_mask_and_coherent。这套资源里如果已经做了兼容处理那么直接迁移到你的环境问题不大如果没有需要自己补上。3.2 probe 阶段请求寄存器、申请中断、创建字符设备设备驱动初始化第一步是拿到平台资源。AXI DMA IP 在设备树里通常以xlnx,axi-dma-1.00.a为 compatible 字符串节点下包含reg寄存器地址、interrupts两个中断分别对应 MM2S 和 S2MM、dma-channels等属性。probe 函数里先读取这些资源再做寄存器映射、中断注册、DMA 内存池初始化最后创建字符设备节点。以下是一段简化但结构完整的 probe 代码基于常见内核风格static int axidma_probe(struct platform_device *pdev) { struct axidma_dev *adev; struct resource *res; int ret; adev devm_kzalloc(pdev-dev, sizeof(*adev), GFP_KERNEL); if (!adev) return -ENOMEM; res platform_get_resource(pdev, IORESOURCE_MEM, 0); adev-regs devm_ioremap_resource(pdev-dev, res); if (IS_ERR(adev-regs)) return PTR_ERR(adev-regs); adev-irq_mm2s platform_get_irq(pdev, 0); ret devm_request_irq(pdev-dev, adev-irq_mm2s, axidma_mm2s_irq_handler, 0, axidma-mm2s, adev); if (ret) return ret; adev-dma_dev axidma_dma_init(adev); if (IS_ERR(adev-dma_dev)) return PTR_ERR(adev-dma_dev); ret alloc_chrdev_region(adev-devno, 0, 1, axidma); if (ret 0) goto err_dma; cdev_init(adev-cdev, axidma_fops); adev-cdev.owner THIS_MODULE; cdev_add(adev-cdev, adev-devno, 1); platform_set_drvdata(pdev, adev); return 0; err_dma: axidma_dma_deinit(adev-dma_dev); return ret; }代码逻辑说明这段代码做了四件关键事。第一用devm_ioremap_resource把设备树中的寄存器物理地址映射成内核虚拟地址这个函数会自动检查资源是否已经被占用返回ERR_PTR时要反向判断。第二通过platform_get_irq(pdev, 0)拿到 MM2S 中断号注意第二个参数 0 不能在设备树里随便写它对应中断属性中第一个 cell也就是interrupts 0 29 4中的 29。第三调用axidma_dma_init初始化描述符环和 DMA 缓冲区池这个函数里通常会申请一块一致内存用于描述符。第四注册字符设备并绑定axidma_fops这样用户态才能通过/dev/axidma访问。参数说明devm_kzalloc是 managed 版本的内存分配不需要手动kfree但要注意它只能在remove函数之前生效如果 probe 中途失败内核会自动释放。alloc_chrdev_region会动态分配主设备号如果希望固定主设备号可以在调用前通过register_chrdev_region指定。实际调试时如果probe返回-EBUSY大概率是中断号冲突或者寄存器区域被其他驱动占用用ioremap失败时看dmesg里的地址冲突提示最直接。中断处理函数里最容易被忽略的是读状态寄存器并清中断的时序。下面是一段常见的中断处理代码static irqreturn_t axidma_mm2s_irq_handler(int irq, void *data) { struct axidma_dev *adev data; u32 status; status ioread32(adev-regs MM2S_DMASR); if (!(status AXIDMA_IRQ_ALL_MASK)) return IRQ_NONE; /* 清中断标志向状态寄存器写1对应位 */ iowrite32(status AXIDMA_IRQ_ALL_MASK, adev-regs MM2S_DMASR); if (status AXIDMA_IRQ_TOG_COMPLETE) /* 传输完成 */ complete(adev-mm2s_done); return IRQ_HANDLED; }代码逻辑说明这段代码先读状态寄存器然后判断是否有我们关心的中断位。注意清中断的方式是“写 1 清 0”写 0 不会清除任何标志这是 AXI DMA IP 的固定行为。complete(adev-mm2s_done)用于唤醒等待在wait_for_completion_interruptible上的 read/write 线程。如果忘了清中断中断会一直触发内核会打印“nobody cared”并禁用该中断线之后所有 DMA 传输都无法完成。3.3 read/write 与用户态交互整包传输还是流式处理字符设备层的 read/write 函数是用户态和 DMA 引擎之间的桥梁。read 函数通常把用户传入的 buf 地址映射到内核页然后提交一个 S2MM 传输等待完成后把数据拷贝到用户空间write 函数则相反先把用户数据拷贝到 DMA 缓冲区再发起 MM2S 传输。一个高效的实现是直接用dma_map_single映射用户 buffer绕过拷贝但需要处理缓存同步和生命周期问题。对于初学者我更推荐先用copy_from_user到预先分配的 DMA 一致缓冲区虽然多一次拷贝但调试起来方便很多。下面这段代码展示了一个保守但稳定的 read 实现static ssize_t axidma_read(struct file *filp, char __user *buf, size_t count, loff_t *off) { struct axidma_dev *adev filp-private_data; unsigned long timeout msecs_to_jiffies(5000); u32 len; int ret; if (count AXIDMA_MAX_TRANSFER) count AXIDMA_MAX_TRANSFER; mutex_lock(adev-lock); ret axidma_submit_s2mm(adev, adev-rd_buf, count); if (ret) goto out; if (!wait_for_completion_interruptible_timeout(adev-s2mm_done, timeout)) { ret -ETIMEDOUT; goto out; } len axidma_get_transfer_len(adev, adev-rd_buf); ret copy_to_user(buf, adev-rd_buf, len); if (ret) ret -EFAULT; out: mutex_unlock(adev-lock); return ret ? ret : len; }代码逻辑说明read 的流程是先加锁然后提交一个 S2MM 传输。axidma_submit_s2mm内部会往尾描述符寄存器写入新描述符地址触发硬件开始搬运。等待完成用了超时机制避免硬件异常时进程永远睡死。搬运完成后从描述符状态字里读取实际传输字节数最后用copy_to_user把数据交给用户态。这里的rd_buf是在 DMA 初始化时申请的一致内存缓冲虚拟地址和物理地址都可用。参数说明count被限制在AXIDMA_MAX_TRANSFER以内这个宏通常定义成 8MB 或者根据描述符环深度计算。如果传更大的值驱动会静默截断用户态可能因此读到不完整的数据。msecs_to_jiffies(5000)设置了 5 秒超时实际项目里要根据系统调度延迟调整对实时性要求高的场景可以减少到 100ms 并配合wait_for_completion_timeout。很多玄学问题就出现在这里DMA 传输本身完成了但用户态进程被优先级更高的任务抢占了导致超时误报这时应该先查 dmesg 再决定是调超时还是调实时优先级。4. DMA 传输常见问题与排查缓存一致与中断丢失的五个坑4.1 现象数据错乱逻辑读到的和内存里的完全对不上开发者在调试 PCIe 或 SoC 上的 DMA 驱动时最常遇到的现象就是内存中明明写入了一串0x12345678但 FPGA 逻辑收到的却是乱码或全零。更诡异的是有时候用小数据量传输一切正常数据量超过某个阈值就出错。这种情况几乎都是缓存一致性问题。原因CPU 读到的是缓存里的旧数据而 DMA 引擎访问的是物理内存。如果驱动使用普通kmalloc分配缓冲区地址落在缓存页中CPU 写数据后只更新了 cache line还没有写回到物理内存DMA 引擎自然读不到最新内容。反过来S2MM 传输时 DMA 把数据写进了物理内存但 CPU 缓存里还留着旧数据读的时候命中缓存读出来的就是脏数据。解决对于 DMA 缓冲区一定要使用dma_alloc_coherent分配或者对已有缓冲区调用dma_map_single后再做dma_sync_single_for_device和dma_sync_single_for_cpu。使用一致内存分配时驱动里要确保在每次 DMA 提交前用memset或dma_sync把数据刷回内存。我习惯在axidma_dma_init里一次性分配所有 DMA 缓冲区并把dma_handle保存到结构体中这样 read/write 里可以直接用避免频繁映射开销。4.2 现象中断触发了但处理函数里读不到任何有效标志有段时间我在调 S2MM 中断明明逻辑已经在发送数据设备树中断号也确定正确但中断处理函数一进来读状态寄存器发现所有标志位都是 0返回IRQ_NONE数据传输却确实完成了。后来查了半天才发现问题出在中断共享和清除时序上。原因AXI DMA 的中断是电平敏感还是边沿敏感取决于硬件配置。多数情况下中断信号是电平触发。如果驱动只读取状态寄存器没有主动写状态寄存器清中断中断线会一直保持有效导致中断处理函数反复被调用最终内核认为这是假中断并禁用该 IRQ。另一种常见情况是设备树里配了两个中断MM2S 和 S2MM但platform_get_irq(pdev, 1)拿到的中断号顺序和实际连接次序不一致导致 S2MM 的中断处理函数绑到了 MM2S 中断线上收到中断后读到的状态里只有 MM2S 的标志。解决中断处理函数里一定要读两次状态寄存器。第一次读标志判断是否是我们的中断第二次写回状态值清中断。清中断时必须保留硬件的错误位不能把所有位都清零。另外核对设备树interrupt-parent和interrupts属性确保第一个 cell 是 0SPI 中断还是 1PPI 中断在 Zynq 上 SPI 中断号还需要加 32 偏移。建议在 probe 阶段把两个中断号都打印出来和逻辑连接图一一对照。4.3 现象传输到一半卡死描述符环明明还有剩余位置大数据量传输时时而出现 DMA 停在某个地址不动CURDESC一直指向一个无效描述符。我遇到过最典型的场景是在一个循环内不断提交描述符但没有等上次传输完成就覆盖了描述符内容导致硬件读到的下一个描述符地址是 0产生总线错误通道直接 halted。原因描述符环的管理存在竞态条件。驱动在更新TAILDESC时硬件可能已经读过了某些描述符如果此时软件修改了这些描述符的NEXT或BUF_ADDR硬件就会拿到不一致的跳转地址。另外描述符个数不足时环末端的NEXT没有指回环头硬件跑完一个循环就停下来但驱动以为还能继续插入。解决对描述符环的访问必须加锁而且插入新描述符前要检查环中已完成的数量。我一般会在一个描述符完成中断里记录已完成计数在上层提交描述符时比较已提交数和已完成数之间的差值如果差值达到环深度减一就阻塞等待。环深度建议设置为 64 或 128描述符个数要多于实际在途传输的数量否则驱动会频繁等待中断吞吐量上不去。4.4 现象提交地址时总是报-EINVAL或者传输结果全是错位驱动里用dma_map_single映射缓冲区后返回的 DMA 地址低位如果不是 0提交给寄存器时会被 AXIDMA 的地址掩码直接丢弃。例如物理地址是0x10000001掩码后变成0x10000000实际传输就从错误的边界开始了数据错位 1 字节。原因AXI DMA 要求描述符地址和缓冲区地址必须按 64 字节对齐。普通的kmalloc只保证 8 字节对齐dma_alloc_coherent虽然对齐到页但如果分配大小不是地址对齐的倍数也可能出现高位对齐但低位不对的情况。另一种原因是用户态传下来的 buffer 本身没有对齐copy_from_user到一致内存时还好如果直接对用户 buffer 做dma_map_scatter就很容易踩中这个坑。解决在分配 DMA 缓冲区时用dma_alloc_coherent并显式ALIGN(size, 64)。如果一定要映射用户 buffer则先检查地址(unsigned long)buf 0x3f是否为零不为零就退回到拷贝路径。描述符本身的分配也要对齐到 64 字节我见过有人把多个描述符连续分配在一个 4KB 页里首地址对齐了但第 5 个描述符起始地址是 32 字节对齐而不是 64 字节对齐结果硬件跳到那个描述符时直接行为异常。4.5 现象status寄存器里明明有完成标志但长度字段还是 0最后一种常见问题是传输完成了中断也进出来了但描述符的status字段读出来仍然只有第 31 位完成标志实际传输字节数全是 0。用示波器和逻辑分析仪看 AXI 总线数据确实已经写入了内存但长度信息丢了。原因硬件更新描述符的时机和驱动读取的时机没有同步。AXI DMA 在写描述符status字段时是先写长度位、再写完成位但由于内存乱序或编译器优化驱动读到完成位为 1 时长度位可能还没被写出来或者读入到了乱序的旧值。解决在读取长度字段前先调用dma_rmb()内存屏障确保完成位的读取和长度位的读取顺序正确。如果问题依旧可以改成读两次第一次读 status等待 1 微秒或一个udelay(1)第二次再读 status以第二次的值为准。这个方法虽然不优雅但在调试时确实能解决大量诡异问题。最终的正确做法是在硬件侧开启描述符状态更新时的“写同步”功能让完成位和长度位在同一个 AXI 突发事务里完成写入避免交错出现。5. 一个验证 AXI DMA 驱动的小技巧在用户态用 mmap 做回环测试驱动写好了编译安装后怎么快速验证正确性我的习惯是先跑一个“裸奔”回环测试用户态分配一块大内存然后把驱动通过mmap暴露的 DMA 缓冲区映射到用户程序里一次write发起 MM2S 传输一次read发起 S2MM 传输两者在 FPGA 内部通过 AXI Stream FIFO 对接。如果数据完全一致说明驱动链路基本通顺。具体操作分三步。第一步在驱动里增加一个mmap操作映射一个 DMA 一致缓冲区。第二步用户态用open打开/dev/axidma然后mmap这个缓冲区到进程地址空间。第三步往缓冲区填充随机数调用ioctl或write启动 MM2S再调用read把 S2MM 数据收回来最后memcmp比对。驱动端mmap的代码片段如下static int axidma_mmap(struct file *filp, struct vm_area_struct *vma) { struct axidma_dev *adev filp-private_data; unsigned long size vma-vm_end - vma-vm_start; unsigned long pfn; if (size adev-buf_size) return -EINVAL; pfn virt_to_phys(adev-buf_virt) PAGE_SHIFT; vma-vm_page_prot pgprot_noncached(vma-vm_page_prot); return remap_pfn_range(vma, vma-vm_start, pfn, size, vma-vm_page_prot); }代码逻辑说明这段代码将 DMA 缓冲区的物理页重新映射到用户空间。pgprot_noncached关掉了该区域上的 CPU 缓存这样做虽然会影响读写性能但能避免缓存一致性问题让回环测试结果更清晰。remap_pfn_range把物理页框号映射到用户地址。注意这里adev-buf_virt必须是dma_alloc_coherent返回的虚拟地址不能是普通kmalloc否则virt_to_phys得到的不一定是真实物理地址。参数说明size是用户请求的映射长度不能超过驱动预先分配的buf_size否则映射越界会引发内核 panic。pgprot_noncached在这里是刻意关闭缓存正式项目中如果追求高性能可以把这一行去掉但在用户态mmap后需要自己调用dma_sync来保证一致性。对于 Zynq 这类平台还可以尝试dma_mmap_coherent逻辑更简洁。用户态测试代码核心逻辑如下int fd open(/dev/axidma, O_RDWR); unsigned char *buf mmap(NULL, 0x100000, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0); for (int i 0; i 0x100000; i) buf[i] random() 0xff; ioctl(fd, AXIDMA_START_MM2S, 0x100000); ioctl(fd, AXIDMA_START_S2MM, 0x100000); sleep(1); unsigned char *check malloc(0x100000); memcpy(check, buf, 0x100000); if (memcmp(check, buf, 0x100000) 0) printf(loopback test pass\n);这段代码里的AXIDMA_START_MM2S和AXIDMA_START_S2MM需要驱动在ioctl命令里实现对应的提交和等待逻辑。注意mmap后直接读写 buf如果驱动没有在mmap里清 DMA 完成标志第二次启动传输时可能读到上一次的残留数据。我一般会在每次传输前用memset把 buf 清空再填充测试图案避免误判。这个回环测试的价值在于它同时验证了描述符环管理、中断触发、缓存一致性、字符设备访问路径和用户态 mmap 映射。如果这个测试能连续跑 1000 次不失败那驱动的基本盘就稳了。从那以后我每次在驱动里动了dma_alloc_coherent、描述符个数、中断处理逻辑或者设备树属性都会强制走一遍这个回环测试而且用dd或并行线程把数据传输大小从 1KB 一直拉到 8MB逐个梯度测。这套方法帮我挡掉了至少一半的移植回归问题。希望帮到你。本文还有配套的精品资源点击获取