避坑指南：HAL库SPI+DMA发送不全/卡busy的5种原因（附CubeMX配置截图）
HAL库SPI+DMA实战避坑手册：从Busy锁死到稳定传输的完整解决方案
第一次在STM32H7上使用SPI+DMA时，我盯着调试器里那个固执的BUSY标志位整整两小时——明明CubeMX配置看起来一切正常，为什么数据传输到一半就卡死？这个经历促使我系统梳理了SPI+DMA的各类"暗坑"。本文将分享五个最易被忽视的配置陷阱，每个问题都配有CubeMX的对比截图和寄存器级分析。
1. 时钟树配置：被忽视的底层隐患
很多开发者会直接使用CubeMX的默认时钟配置，这在普通SPI模式下可能工作正常，但引入DMA后问题就会显现。以STM32H743为例，当APB总线时钟与SPI目标频率比值不当时，会出现微妙的时序错位。
典型错误配置特征：
- APB2时钟设为200MHz时直接使用
SPI_BAUDRATEPRESCALER_2 - 未启用SPI外设的独立时钟门控（
__HAL_RCC_SPI1_CLK_ENABLE()位置不当）
正确的做法是：
// 在SystemClock_Config()后添加时钟校验 if (__HAL_RCC_GET_SPI1_SOURCE() != RCC_SPI1CLKSOURCE_PLL2P) { Error_Handler(); }提示：使用STM32CubeIDE的Clock Configuration界面时，建议开启"Show Expert Parameters"选项，特别检查PLL2P时钟到SPI的路径是否畅通。
2. DMA流与中断优先级冲突
CubeMX自动生成的NVIC配置往往需要手动优化。我们曾遇到一个案例：DMA流中断被USB中断抢占，导致SPI状态机紊乱。
关键配置对比表：
| 参数项 | 错误配置 | 推荐配置 |
|---|---|---|
| DMA中断优先级 | 默认值(0) | 至少比SPI中断高1级 |
| SPI中断类型 | 仅开启TX/RX完成中断 | 同时开启错误中断 |
| DMA双缓冲模式 | 禁用 | 根据吞吐量需求选择启用 |
// 正确的中断初始化示例 HAL_NVIC_SetPriority(DMA1_Stream0_IRQn, 1, 0); // DMA优先级1 HAL_NVIC_SetPriority(SPI1_IRQn, 2, 0); // SPI优先级2 HAL_NVIC_EnableIRQ(DMA1_Stream0_IRQn); HAL_NVIC_EnableIRQ(SPI1_IRQn);3. SPI工作模式与DMA的隐藏关联
CubeMX的SPI模式选择下拉框里有12种选项，但配合DMA使用时需要特别注意：
- 全双工模式：必须同时配置TX和RX DMA，即使不需要接收数据
- 只发送模式：DMA需要设置为
MEMORY_TO_PERIPH，且要手动处理BSY标志 - 主从模式切换：在运行时切换必须调用
HAL_SPI_DeInit()重置外设
一个容易忽略的细节是SPI数据对齐方式对DMA的影响。当使用8位数据宽度时：
hspi1.Init.DataSize = SPI_DATASIZE_8BIT; hdma_spi1_tx.Init.MemDataAlignment = DMA_MDATAALIGN_BYTE; // 必须匹配 hdma_spi1_tx.Init.PeriphDataAlignment = DMA_PDATAALIGN_BYTE;4. 硬件NSS信号与软件控制的抉择
虽然CubeMX默认生成软件NSS控制，但在高速传输场景下（>10MHz），硬件NSS能显著提升稳定性：
- 在Pinout界面将NSS引脚配置为硬件模式
- 在Configuration选项卡启用"NSS Pulse Mode"
- 在DMA设置中增加以下参数：
hdma_spi1_tx.Init.FIFOMode = DMA_FIFOMODE_ENABLE; hdma_spi1_tx.Init.FIFOThreshold = DMA_FIFO_THRESHOLD_1QUARTERFULL;注意：使用硬件NSS时，SPI初始化后需要额外执行
__HAL_SPI_SET_NSS_HIGH(hspi)来释放片选信号。
5. 异常处理与状态恢复机制
当SPI卡在BUSY状态时，仅调用HAL_SPI_Abort()可能不够完整。建议采用以下恢复流程：
- 先停止DMA传输：
HAL_DMA_Abort(hspi->hdmatx); HAL_DMA_Abort(hspi->hdmarx);- 重置SPI外设：
__HAL_RCC_SPI1_FORCE_RESET(); __HAL_RCC_SPI1_RELEASE_RESET();- 重新初始化外设：
HAL_SPI_DeInit(&hspi1); MX_SPI1_Init(); // 重新生成CubeMX初始化代码实测发现，在连续传输场景下，每次DMA传输前添加10us的延时（HAL_Delay(1)）可降低总线冲突概率。这个技巧在驱动OLED屏时特别有效。
6. CubeMX配置实战演示
通过对比正确和错误配置截图，我们可以直观识别关键差异点：
GPIO配置误区：
- 错误：仅配置MOSI/SCK引脚，忽略MISO
- 正确：即使不用接收也要完整配置所有SPI引脚
DMA参数细节：
- 内存突发模式应设为
SINGLE而非INCR4 - FIFO阈值建议设为
1/4而非FULL
在SPI参数配置界面，有两个易错选项：
CRC Calculation必须禁用Master Keep IO State建议启用
最后分享一个调试技巧：当SPI卡死在BUSY状态时，通过读取SPI->SR寄存器可以快速定位问题根源：
- 位4（OVR）：溢出错误
- 位5（MODF）：模式错误
- 位6（CRCERR）：CRC校验错误
掌握这些底层状态标志的解读方法，能大幅缩短故障排查时间。