AXI DMA LOOP模式调试指南：从回环验证到带宽测试

简介：资源是一份AXI DMA Loop SDK代码说明文档，面向FPGA嵌入式开发者，讲解基于Xilinx中断控制器与DMA引擎实现高效数据传输循环的实现要点。内容覆盖XScuGic中断设备、XAxiDma DMA设备及中断向量表等关键结构体，并梳理从main函数开始的代码结构与中断注册流程，适合需要快速理解DMA循环收发机制或进行驱动的开发者参考。压缩包仅含1个docx文件，大小42KB，文档以文字和代码片段为主，便于查看。目前已有161人学习。通过阅读可掌握XAxiDma_LookupConfig、XAxiDma_CfgInitialize、XScuGic_Connect等函数的调用关系，理解BD环管理与中断触发机制，为后续调试与二次开发提供基础。

1. AXI DMA LOOP模式：为什么SDK例程先烧回环

调试AXI DMA数据通路时，最怕的是一数据搬运失败就成了黑匣子，既不知道IP核内部发生了什么，也不知道软件哪一步没写对。LOOP模式解决的就是这个问题：硬件逻辑把DMA的发送通道 MM2S 和接收通道 S2MM 在 FPGA 内部短接，数据不经过真实外设，直接从内存搬到回环里，再收回来。SDK 里的回环程序只负责发起搬运、等待完成、比对数据。它能帮你快速区分是 IP 配置问题还是驱动代码问题。适合刚接手 DMA 模块的逻辑工程师，也适合那些要把一套驱动从同一架构迁到另一颗芯片上的嵌入式工程师。先跑通 LOOP，再谈业务数据，这是最稳的路线。

2. LOOP模式先对准硬件基线：回环接线、地址映射与BSP库来源

2.1 回环在硬件上是哪种接法：两个通道怎么绕成一个圈

LOOP 这个名字本身没有规定硬件接法。你要先确认手里的硬件工程到底做的是哪种回环：第一种是把发送侧的 AXIS 输出直接绑到接收侧的 AXIS 输入，中间不插任何 FIFO 或数据修正逻辑；第二种是 DMA 控制器 IP 内部自带回环模式，通过控制寄存器的某个位来切换。SDK 程序里所谓的 LOOP，通常默认是第一种。第二种往往只用来验证寄存器通路，数据方向单一，掩盖了总线时序问题。

所以在读代码之前，先在硬件工程里找两层连接。上层是 DMA 输出s_axis或m_axis信号，只有两个通道都存在且位宽一致，回环才成立。如果两边数据位宽一个 32 位，一个 128 位，回环代码跑起来大概率出现数据错位。还有一种情况是硬件工程里做了多个外设的 AXI Interconnect，回环路径上多了一段接受转接桥，那么回环的延迟会变大，但软件不应该因此失败。

我一般建议：先不要用内部回环模式，直接在顶层把发送和接收接在一起。这样代码里读回的状态更接近真实外设场景。硬件做好后，再去 SDK 里核对该 DMA 实例的名称和基地址。

2.2 从硬件描述文件到 BSP：地址映射是怎么进到代码里的

SDK 工程并不是凭空能看到 DMA 寄存器的。它依赖一份硬件描述文件，里面保存了 FPGA 工程里所有外设的地址映射、中断号、数据位宽、通道个数。生成 SDK 工程时，这一步叫导入硬件平台。导入后，代码里会自动出现参数头文件，里面定义了类似DMA_DEVICE_ID、DMA_BASE_ADDR这样的宏。你在代码开头用到的查找配置函数，读的就是这些宏。

Dma_Config *cfg = Dma_LookupConfig(DMA_DEVICE_ID); if (cfg == NULL) { printf("lookup config failed\r\n"); return -1; } Dma_CfgInitialize(&dmaInst, cfg);

这段代码的逻辑是：先在 BSP 生成的配置表里按设备 ID 找到对应的硬件配置项，再把配置内容初始化到驱动句柄中。Dma_CfgInitialize不只是记地址，它还会把实例中的数据位宽、地址宽度、通道类型全部缓存到内存里的dmaInst结构。之后所有寄存器操作都用这个句柄，而不是直接操作基地址。

参数说明：DMA_DEVICE_ID不能在代码里随便改。若硬件工程里同一个 DMA IP 被配置成两个实例，那么每个实例的 ID 都不同。最常见的问题是开发者把旧工程里的DMA_DEVICE_ID宏复制到新工程，基地址映射不匹配，导致代码访问到错误的外设，而错误外设寄存器读回全是无效值。所以新建 SDK 工程时，一定确认参数头文件是从当前硬件描述文件重新生成的，而不是沿用旧文件。

2.3 硬件 IP 版本与 BSP 驱动版本：位偏移不一致的坑

SDK 里的 BSP 包含 DMA 控制器驱动库，它由厂商随工具链发布。IP 核版本升级后，寄存器和描述符的位定义可能变化，但 BSP 库如果被其他工程带过来，就可能不对齐。你实际会看到的现象是：Dma_LookupConfig返回的配置正常，复位也正常，但一启动传输就在状态寄存器里看到奇怪的错误位。

因此读代码前，先打开 BSP 中 DMA 驱动头文件里的版本宏，再回到硬件工程看 IP 核版本。这个环节没有办法绕开。我通常会在 SDK 里搜包含VERSION的宏定义，然后打开寄存器视图读 0x800 偏移处的版本寄存器比对。如果版本不一致，优先让 BSP 跟随硬件，不要反过来。修改 BSP 版本后必须重新编译整个工程，否则链接的还是旧库。

另外，BSP 里还依赖中断控制器驱动。如果 LOOP 工程使用了中断，那么初始化顺序是：先初始化中断控制器，再注册 DMA 中断服务函数，最后才打开 DMA 内部的中断掩码。初学者喜欢把 DMA 内部中断掩码写在前，结果中断一直不进。后面第 5 章会专门讲这个现象。

3. SDK代码执行主线：从main()到描述符链的搬运逻辑

3.1 main()里的初始化顺序：复位为何必须放在配置之后

LOOP 例程主函数的骨架并不长，但顺序非常关键。一次标准搬运需要经历：查配置、初始化驱动程序、复位 DMA、关闭两个通道、构造描述符、提交描述符、等待完成、校验数据。下面的代码展示的是裸机环境的示意结构，实际 SDK 生成的接口名可能不同，但主线顺序是通用的。

#include "dma_loop.h" static Dma_Instance dmaInst; int main(void) { Dma_Config *cfg = Dma_LookupConfig(DMA_DEVICE_ID); if (cfg == NULL) { return -1; } Dma_CfgInitialize(&dmaInst, cfg); Dma_Reset(&dmaInst); while (Dma_IsResetDone(&dmaInst) == 0) ; Dma_ChannelDisable(DMA_MM2S, &dmaInst); Dma_ChannelDisable(DMA_S2MM, &dmaInst); BuildTxDescriptor(); BuildRxDescriptor(); Dma_ChannelSubmit(DMA_MM2S, &dmaInst); Dma_ChannelSubmit(DMA_S2MM, &dmaInst); PollUntilDone(); CheckResult(); return 0; }

这个顺序里，最容易错的是先复位再初始化。Dma_Reset要依赖dmaInst里的寄存器基址，而这个基址是在Dma_CfgInitialize里填充的，顺序颠倒会导致复位操作落在未知地址上。接着Dma_ChannelDisable的作用是把两个通道恢复到空转状态，避免上一次运行残留的描述符指针影响这次提交。很多翻车现场都源于这里没关闭通道，硬件还停在旧描述符链的末尾。

参数说明：DMA_MM2S与DMA_S2MM是通道枚举值，在驱动库里定义。Dma_IsResetDone需要循环等待，因为复位动作要在几个时钟周期后才生效，有些平台甚至需要几百个周期。由于 LOOP 测试的数据量通常不大，轮询等待完全够用，不用在这个阶段引入中断。

3.2 发送描述符链与接收描述符链：两套并行结构

AXI DMA 的搬运单位是描述符，而不是直接给一个地址。发送侧有一条描述符链，接收侧也有一条描述符链。LOOP 最简洁的做法是两边都只挂一个描述符，即单节点链，这样代码容易调试。描述符需要由软件填好，再通过一句刷新指令让硬件能看到。

#define TEST_LEN 0x1000 #define ALIGN_BYTE 64 static uint8_t txBuffer[TEST_LEN] __attribute__((aligned(ALIGN_BYTE))); static uint8_t rxBuffer[TEST_LEN] __attribute__((aligned(ALIGN_BYTE))); static void BuildTxDescriptor(void) { Dma_Descriptor *desc = &txDesc[0]; desc->NextDescAddr = 0; desc->BufferAddr = (uintptr_t)txBuffer; desc->Control = TEST_LEN; desc->Status = 0; Dma_FlushDesc(&dmaInst, desc); }

这段代码的关键在NextDescAddr = 0。0 表示当前描述符就是链的终点，硬件处理完这一帧后不会再取下一段。BufferAddr必须是物理地址，而不是 CPU 的虚拟地址。裸机 SDK 通常直接使用物理地址，但如果你的平台开启了 MMU，就要额外做地址转换，否则 DMA 读到的内容可能是未映射内存。

参数说明：Control字段的低 16 位是帧长度，最大支持 65535 字节。如果你的测试长度超过这个值，就必须把描述符串成多跳链，每一跳一个缓冲区。Dma_FlushDesc理论上只负责刷新描述符本身，但在实际工程里，很多人忘了在修改已有的描述符后再次刷新，导致硬件读到的还是缓存里的旧描述符。这条会在第 5 章展开。

3.3 轮询等待完成：EOC 与 IDLE 要分清

裸机 LOOP 调试阶段我强烈建议用轮询而不是中断。轮询会让代码按顺序执行，每个状态都能用调试器看到，中断则会把问题隔开成异步流程。轮询以接收通道的状态寄存器为准，因为接收通道完成才代表数据真正写回了内存。

static void PollUntilDone(void) { uint32_t ticks = 0; while (1) { uint32_t st = Dma_ReadReg(&dmaInst, S2MM_STATUS_REG_OFFSET); if (st & DMA_STATUS_EOC) { break; } if (st & DMA_STATUS_ERR) { printf("rx error: status=0x%08X\r\n", st); break; } if (++ticks > POLL_TIMEOUT_MAX) { printf("poll timeout, status=0x%08X\r\n", st); break; } } }

这里要注意EOC与IDLE的区别。EOC是 End of Chain，表示硬件遍历完了描述符链，即这一批数据的最后一个字节已经不产生中断或已经被接收通道写回。IDLE只表示通道进入空闲，但在单描述符链上，它可能在描述符提交前就变成空闲，也可能在传输完成后空闲。如果只等 IDLE，数据可能还没落盘，就开始校验，得到错误结果。

参数说明：POLL_TIMEOUT_MAX不能是空转计数。我一般把它换算成实际时间，比如时钟频率 100MHz 时，LOOP 搬运 1KB 数据的耗时在微秒量级，超时阈值放到 1 到 10 毫秒足够。超时设计在回归测试中很重要，否则一次异常会让整个循环卡死。

3.4 数据校验：先校验长度，再校验内容

回环完成后，发送缓冲和接收缓冲的内容理论上必须完全一致。实际工程中，最简单的做法是逐字节比较，但传输长度到几 MB 时，逐字节比较的时间可能比搬运时间还长，而且 CPU 指令流水线的加载延迟会掩盖真正的硬件问题。更推荐先比长度，再对内容做快速校验。

static int CheckResult(void) { if (rxLen != TEST_LEN) { printf("length mismatch: tx=%d rx=%d\r\n", TEST_LEN, rxLen); return -1; } for (int i = 0; i < TEST_LEN; i++) { if (txBuffer[i] != rxBuffer[i]) { printf("data mismatch at %d: tx=0x%02X rx=0x%02X\r\n", i, txBuffer[i], rxBuffer[i]); return -1; } } return 0; }

如果要用这个函数判断硬件问题，发送缓冲里的内容必须提前填成确定的模式。常见做法是填充递增序列或伪随机序列，这样一旦数据错位，打印的第一个不同位置就能帮你判断是延迟导致还是字节序导致。逐字节比较适合第一次跑通，以后做性能回归时，应当替换成 CRC 或哈希校验，把比较时间从非线性降下来。

4. 想让LOOP稳定跑：描述符参数、地址对齐、中断掩码与缓存一致性

4.1 描述符里四个关键字段的设置逻辑

描述符不是普通内存块，它有固定的字段布局。不同 SDK 里的字段名不一样，含义却很相似。在 LOOP 中，你只需要关注四个关键字段：下一个描述符地址、Buffer 地址、长度控制、状态回写。下面这张表给出了 LOOP 模式下建议的取值。

Control在多数驱动里不只有长度，还包括方向标识、所有权位、中断完成使能位。所有权位表示当前描述符是由软件控制还是硬件使用。软件提交前要把所有权置为硬件所有，硬件处理完最后一拍后自动清除该位。第二次循环开始前必须重新设置，否则硬件认为描述符已经释放，不会触碰它。这是多轮 LOOP 最常见的失败原因。

4.2 地址对齐：64字节对齐背后是突发传输的边界约束

地址对齐这个问题在第一次跑 LOOP 时看起来是玄学。实际上，AXI DMA 在搬运时会发起突发传输，每次突发会连续读取若干拍数据。如果 Buffer 起始地址没有按要求对齐，一次突发可能跨越 DDR 的页边界，导致系统总线上出现分裂事务，轻则性能下降，重则数据错乱。

不同 IP 的对齐要求不完全一样，但我见过的大多数 AXI DMA 驱动都要求 32 字节或 64 字节对齐。SDK 的 BSP 里容易查到BufferAddr的低位必须为 0 的位数检查宏。你在代码里直接声明静态数组并加对齐属性，是最省事的方式：

static uint8_t txBuffer[TEST_LEN] __attribute__((aligned(64))); static uint8_t rxBuffer[TEST_LEN] __attribute__((aligned(64)));

如果你要用malloc动态分配 Buffer，就不能直接依赖这个静态属性，应该把malloc返回地址向上补齐到 64 字节。注意补齐后的尾部空间要预留够，否则给 DMA 的完整数据区会越过分配边界。某开发者曾在这个地方踩过坑，malloc后只补了 64 字节，因为原始地址已经是 32 字节对齐，结果硬件偶尔读取到越界地址，回环测试一小时才复现一次。

4.3 中断掩码：调试阶段只开错误中断，完成位用轮询

LOOP 代码里经常会看到中断初始化代码，但你要想清楚中断到底用来做什么。如果只是搬运完成信号，轮询完全能替代。如果是为了观察错误状态，那就要保留错误中断。我一般建议调试期把IOC_IrqEn关掉，只开Err_IrqEn，完成事件靠主循环轮询。这样中断服务函数只需要处理异常，不会反复触发打断打印。

掩码寄存器通常在通道的 DMA 控制寄存器里。设置方式是与原值做位运算，而不是直接覆盖式写入，否则可能把别的位冲掉：

uint32_t regVal = Dma_ReadReg(&dmaInst, S2MM_DMACR_OFFSET); regVal |= S2MM_ERR_IRQ_EN_MASK; // 只开错误中断 regVal &= ~S2MM_IOC_IRQ_EN_MASK; // 关闭完成中断 Dma_WriteReg(&dmaInst, S2MM_DMACR_OFFSET, regVal);

参数说明：错误中断开起来之后，ISR 里要做的第一件事是读取当前状态寄存器，把错误位清掉，再置一个全局错误标志。不要在半中断里打印大段日志，中断上下文打印慢，容易造成后续中断丢失。全局标志在主循环里被轮询到，再打印完整寄存器快照。

4.4 循环次数与超时阈值：回归测试的两个必调参数

把 LOOP 从一次改成连续多轮，才能暴露时序问题。多轮测试需要两个参数：循环次数和超时阈值。

for (int loop = 0; loop < LOOP_COUNT; loop++) { FillPattern(txBuffer, loop); ResetDescOwnership(); Dma_ChannelSubmit(DMA_MM2S, &dmaInst); Dma_ChannelSubmit(DMA_S2MM, &dmaInst); if (WaitDone(POLL_TIMEOUT_MAX) != 0) { DumpRegisters(&dmaInst); break; } if (CheckResult() != 0) { break; } }

关键是需要一个ResetDescOwnership()函数，它把每个描述符的所有权位重新置 1。很多从简单例程改过来的工程，会直接复用第一次提交的描述符，第二次提交时硬件认为所有权不在自己这边，通道不会启动。超时阈值的选取与数据长度有关，常见做法是在测试工程里放一个定时器基准，比如 1ms 的 tick 计数，超时设为 1000 ticks。这样既能避免卡死，也不会把正常慢速回环误判成失败。

4.5 缓存一致性：Flush 在提交前，Invalidate 在完成前

带 CPU 缓存的环境中，缓存一致性是 LOOP 失败率最高的来源。CPU 向发送缓冲写数据后，如果只写到了 Cache 里，DMA 直接读物理内存会读到旧值。同样，DMA 写回接收缓冲后，CPU 又可能从缓存里读到旧值。处理方法是显式的缓存刷新和失效操作。

Dma_FlushBuffer(&dmaInst, txBuffer, TEST_LEN); // 启动 DMA InvalidateBuffer(&dmaInst, rxBuffer, TEST_LEN); // 然后校验数据

顺序非常关键：先刷新发送缓冲，再启动；等接收完成后，先作废接收缓冲的缓存行，再访问数据。如果反了，缓存里还有旧数据，校验一定会失败。尤其是在 LOOP 连续多轮循环时，接收缓冲可能一直驻留在 CPU 缓存里，第二轮如果不作废，收到的永远是第一轮的数据。这也是我建议把缓存操作单独封成函数的原因，出错时只需要检查这三行顺序。

5. LOOP调试避坑：五个现象、根因与解决办法

5.1 现象：状态寄存器一直 Busy，通道启动后没有后续动作

原因：描述符指针没有被正确写入 DMA 的当前描述符寄存器。常见是因为代码里把 MM2S 和 S2MM 的寄存器偏移搞混了，启动的是发送通道，但写入的指针地址属于接收通道。或者描述符写入后没有刷新缓存，硬件读到的指针是旧的。这一步排查看当前描述符寄存器，比对它的值和描述符数组的首地址，两者一致才说明 DMA 拿到了正确的描述符。解决方法是统一用一个SetDescriptorOffset()包装函数，只在包装函数里发生寄存器写入，避免散落多处。

5.2 现象：接收数据前几个字节正确，后面全是 0

原因：这些数据其实是长度字段写错了。描述符Control字段低 16 位是长度，高 16 位还包含一些控制标识。如果把长度写到了高 16 位，比如desc->Control = TEST_LEN << 16，硬件读取长度时得到 0。发送通道按 0 长度处理，接收通道自然只收到一帧空数据。解决方法是回看 BSP 头文件，用驱动提供的宏来设置长度，而不是直接赋值。打印状态寄存器中的传输长度字段，与实际写入值核对。

5.3 现象：第一次 LOOP 成功，第二次以后结果全乱

原因：描述符所有权位没有被重置。硬件处理完一帧后，会清除所有权位并写回状态。第二次启动前，软件必须重新初始化整个描述符结构，不只是改长度。另一个可能是接收缓冲没有作废缓存，第二次校验时读的是缓存里的老数据。解决办法是在每次循环开始前调用一个ResetDescriptorAll()，把所有权位、长度、Buffer 地址都重新赋值，再刷新缓存。

5.4 现象：开启了 Cache 后，接收 Buffer 始终是初始值

原因：DMA 写的是物理内存，CPU 读的是 Cache，Cache 来不及失效或者根本没有失效。有时发送缓冲也有这个问题，CPU 在 Cache 里填数据，DMA 却从 DDR 里读到旧内容。解决办法是在启动前刷新发送缓冲，在接收完成后立即作废接收缓冲。如果工程中既用了 Cache 又要做性能测试，不要试图省掉这两步。

5.5 现象：中断方式跑 LOOP，程序在循环里干等，ISR 却没有触发

原因：中断链路的配置不完整。通常需要三步：中断控制器使能，中断服务函数注册，DMA 内部错误中断或完成中断掩码打开。很多人只做了最后一步，前两步缺失或顺序错误。中断服务函数注册时还可能把通道搞反了。解决办法是在主函数里把中断控制器初始化放到最前面，注册函数参数明确区分DMA_MM2S和DMA_S2MM。调试时可以在 ISR 入口打一个临时的 GPIO 翻转信号，用示波器确认中断是否真的到达处理器。

6. 把LOOP工程改造成带宽基准：定时器、循环与结果打印

6.1 用定时器计算吞吐量

LOOP 跑通后，下一个诉求一般是确认这条回环能跑到多少带宽。做法很简单：在启动 DMA 前记录定时器计数值，完成后再次读取，两者差值乘上定时器周期就是耗时，然后用传输字节数除以耗时。

uint64_t startTick, stopTick; startTick = Timer_GetCount(); Dma_ChannelSubmit(DMA_MM2S, &dmaInst); Dma_ChannelSubmit(DMA_S2MM, &dmaInst); PollUntilDone(); stopTick = Timer_GetCount(); double sec = (double)(stopTick - startTick) / TIMER_FREQ; double mbps = (double)(TEST_LEN) / sec / (1000.0 * 1000.0); printf("bandwidth: %.2f MB/s\r\n", mbps);

不要拿单次结果下结论。回环路径上的突发传输会受 DDR 刷新、总线仲裁、缓存命中率影响，至少要跑 100 次取平均值，记录最小值和最大值，这样才看得出抖动。

6.2 让测试循环在失败时输出寄存器快照

把功能验证和带宽测量放到同一个循环里。每一轮传递不同的递增序列，这样即使第 1000 次才出错，也能通过打印出的序号快速回推当时改了哪些代码。在失败分支里调用寄存器快照打印函数，它会输出当前描述符寄存器、状态寄存器、剩余传输长度和错误码。这样排查时不需要再插点重测。

6.3 保留一组测试参数表

实验室或产线场景下，不同板卡可能使用不同 DDR 频率，导致回环带宽差异很大。建议在工程里保留一张参数表，包含对齐字节、长度、循环次数、缓存开关、超时阈值。每次修改只改表，不直接改函数。长期的调试习惯比一次性的修复更有价值。我后来在每个 DMA 相关的工程里都会保留一个 LOOP 自检函数，换板子、换 DDR 配置后先跑它，再碰业务逻辑。这个习惯帮我节省的定位时间远超过写代码的时间。希望帮到你。

本文还有配套的精品资源，点击获取