refactor[STM32][DMA]: unify DMA helpers and descriptors for HAL drivers#11329
refactor[STM32][DMA]: unify DMA helpers and descriptors for HAL drivers#11329wdfk-prog wants to merge 2 commits intoRT-Thread:masterfrom
Conversation
|
👋 感谢您对 RT-Thread 的贡献！Thank you for your contribution to RT-Thread! 为确保代码符合 RT-Thread 的编码规范，请在你的仓库中执行以下步骤运行代码格式化工作流（如果格式化CI运行失败）。 🛠 操作步骤 | Steps
完成后，提交将自动更新至 如有问题欢迎联系我们，再次感谢您的贡献！💐 |
📌 Code Review Assignment🏷️ Tag: bsp_stm32Reviewers: Liang1795 hamburger-os wdfk-prog Changed Files (Click to expand)
📊 Current Review Status (Last Updated: 2026-04-14 16:59 CST)
📝 Review Instructions
|
- add drv_dma common helpers and stm32_dma_config descriptors for STM32 series - refactor i2c, spi, usart, qspi, and sdio DMA setup and deinit paths to reuse the common layer - unify DMA IRQ enable, rollback handling, and const board-level DMA configuration usage
- migrate STM32 HAL driver DMA config macros to shared descriptor init helpers - add overridable DMA priority and NVIC priority fields for board-level configs - align SPI, UART, I2C, SDIO, and QSPI DMA descriptors across visible STM32 series configs - simplify per-series DMA config definitions and reduce duplicated field assignments
There was a problem hiding this comment.
Pull request overview
This PR refactors STM32 HAL_Drivers DMA integration by introducing a shared DMA descriptor (stm32_dma_config) plus common helper APIs, and migrates peripheral/config headers to use the unified descriptors/macros.
本次 PR 通过引入统一的 DMA 描述符（stm32_dma_config）与公共 helper 接口，重构 STM32 HAL_Drivers 中分散的 DMA 初始化/配置逻辑，并将多系列配置头迁移到统一的描述符宏。
Changes:
- Add
drv_dma.c/.hto centralize DMA clock/DMAMUX enable, HAL DMA init, NVIC setup, and deinit/rollback.
新增drv_dma.c/.h，集中 DMA 时钟/DMAMUX、HAL 初始化、NVIC 配置与反初始化/回滚。 - Switch USART/SPI/I2C/SDIO/QSPI drivers and configs to
stm32_dma_config(mostlyconst) and unifiedSTM32_DMA_*_CONFIG_INIT_EXmacros.
将 USART/SPI/I2C/SDIO/QSPI 驱动与配置统一切换到stm32_dma_config（多为const）及统一初始化宏。 - Update build script to compile the new DMA helper module.
更新构建脚本以编译新的 DMA helper 模块。
Reviewed changes
Copilot reviewed 70 out of 70 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| bsp/stm32/libraries/HAL_Drivers/drivers/drv_dma.c | New common DMA helper implementation (init/setup/deinit). |
| bsp/stm32/libraries/HAL_Drivers/drivers/drv_config.h | Includes drv_dma.h so config headers can use unified DMA descriptors. |
| bsp/stm32/libraries/HAL_Drivers/drivers/SConscript | Adds drv_dma.c to build sources. |
| bsp/stm32/libraries/HAL_Drivers/drivers/drv_usart.h | UART config DMA fields switched to const struct stm32_dma_config *; Change Logs line edited. |
| bsp/stm32/libraries/HAL_Drivers/drivers/drv_usart_v2.h | UART v2 config DMA fields switched to const struct stm32_dma_config *. |
| bsp/stm32/libraries/HAL_Drivers/drivers/drv_spi.h | SPI config DMA fields switched to const struct stm32_dma_config *. |
| bsp/stm32/libraries/HAL_Drivers/drivers/drv_hard_i2c.h | I2C config DMA fields switched to const struct stm32_dma_config *. |
| bsp/stm32/libraries/HAL_Drivers/drivers/drv_sdio.h | SDIO config DMA members switched to struct stm32_dma_config. |
| bsp/stm32/libraries/HAL_Drivers/drivers/drv_sdio.c | SDIO DMA (Tx/Rx) paths refactored to use stm32_dma_init/deinit and improved error handling. |
| bsp/stm32/libraries/HAL_Drivers/drivers/drv_qspi.c | QSPI DMA setup refactored to stm32_dma_setup and unified descriptor usage. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/wl/uart_config.h | Migrates WL UART DMA macros to unified STM32_DMA_*_CONFIG_INIT_EX + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/wl/spi_config.h | Migrates WL SPI DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/wb/uart_config.h | Migrates WB UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/wb/spi_config.h | Migrates WB SPI DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/wb/qspi_config.h | Migrates WB QSPI DMA macro to unified init macro + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/u5/uart_config.h | Migrates U5 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/u5/spi_config.h | Migrates U5 SPI DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/u5/sdio_config.h | Migrates U5 SDIO DMA config to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/u5/qspi_config.h | Migrates U5 QSPI DMA macro to unified init macro + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/mp1/qspi_config.h | Migrates MP1 QSPI DMA macro to unified init macro + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l5/uart_config.h | Migrates L5 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l5/spi_config.h | Migrates L5 SPI DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l5/sdio_config.h | Migrates L5 SDIO DMA config to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l5/qspi_config.h | Migrates L5 QSPI DMA macro to unified init macro + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l4/uart_config.h | Migrates L4 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l4/spi_config.h | Migrates L4 SPI DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l4/sdio_config.h | Migrates L4 SDIO DMA config to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l4/qspi_config.h | Migrates L4 QSPI DMA macro to unified init macro + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l1/uart_config.h | Migrates L1 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l1/spi_config.h | Migrates L1 SPI DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l1/sdio_config.h | Migrates L1 SDIO DMA config to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/l0/uart_config.h | Migrates L0 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/g0/uart_config.h | Migrates G0 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/g0/spi_config.h | Migrates G0 SPI DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/g4/sdio_config.h | Migrates G4 SDIO DMA config to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/g4/qspi_config.h | Migrates G4 QSPI DMA macro to unified init macro + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f7/uart_config.h | Migrates F7 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/h7/uart_config.h | Migrates H7 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/h7/sdio_config.h | Migrates H7 SDIO DMA config to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/h7/qspi_config.h | Migrates H7 QSPI DMA macro to unified init macro + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/h5/uart_config.h | Migrates H5 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f4/sdio_config.h | Migrates F4 SDIO DMA config to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f4/qspi_config.h | Migrates F4 QSPI DMA macro to unified init macro + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f3/uart_config.h | Migrates F3 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f2/spi_config.h | Migrates F2 SPI DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f2/sdio_config.h | Migrates F2 SDIO DMA config to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f1/spi_config.h | Migrates F1 SPI DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f1/sdio_config.h | Migrates F1 SDIO DMA config to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f1/i2c_hard_config.h | Migrates F1 I2C DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f0/uart_config.h | Migrates F0 UART DMA macros to unified init macros + priority fields. |
| bsp/stm32/libraries/HAL_Drivers/drivers/config/f0/spi_config.h | Migrates F0 SPI DMA macros to unified init macros + priority fields. |
| * 2018-10-30 SummerGift first version | ||
| * 2019-03-05 whj4674672 add stm32h7 | ||
| * 2020-10-14 PeakRacing Porting for stm32wbxx | ||
| * 2020-10-14 Dozingfiretruck Porting for stm32wbxx |
There was a problem hiding this comment.
[documentation/文档]: Historical Change Logs entry author was altered.
English: This PR changes the 2020-10-14 Change Logs author name from PeakRacing to Dozingfiretruck. Unless there is a verified attribution correction, please avoid modifying historical authorship lines because it breaks traceability and credit. If the intent is to add your own contribution, add a new Change Logs entry instead.
中文：此处将 2020-10-14 的 Change Logs 作者从 PeakRacing 改成了 Dozingfiretruck。除非这是经过确认的署名更正，否则不建议修改历史作者信息，这会影响可追溯性与贡献归属；如果是新增贡献，请新增一条 Change Logs 记录即可。
| #if defined(SOC_SERIES_STM32F2) || defined(SOC_SERIES_STM32F4) || defined(SOC_SERIES_STM32F7) || defined(SOC_SERIES_STM32F3) | ||
| #define STM32_DMA_USES_CHANNEL | ||
| #endif /* defined(SOC_SERIES_STM32F2) || defined(SOC_SERIES_STM32F4) || defined(SOC_SERIES_STM32F7) || defined(SOC_SERIES_STM32F3) */ |
There was a problem hiding this comment.
[bug/缺陷]: STM32_DMA_USES_CHANNEL incorrectly includes SOC_SERIES_STM32F3.
English: In drv_dma.h, SOC_SERIES_STM32F3 is classified as DMA_Channel_TypeDef (channel-based DMA), but it is also included in STM32_DMA_USES_CHANNEL, which makes the helper write dma_handle->Init.Channel. For channel-based DMA (like the DMA_Channel_TypeDef path), HAL DMA_InitTypeDef typically has no Channel member, so this will break builds for STM32F3 or configure a non-existent field. Please remove SOC_SERIES_STM32F3 from STM32_DMA_USES_CHANNEL (keep it only for stream-based families), or gate it on the actual presence of DMA_InitTypeDef.Channel.
中文：在 drv_dma.h 里，SOC_SERIES_STM32F3 被归类为 DMA_Channel_TypeDef（通道式 DMA），但同时又被放进了 STM32_DMA_USES_CHANNEL，这会导致 helper 去写 dma_handle->Init.Channel。对于通道式 DMA（DMA_Channel_TypeDef 路径），HAL 的 DMA_InitTypeDef 通常没有 Channel 成员，这会导致 F3 编译失败或写入不存在的字段。建议把 SOC_SERIES_STM32F3 从 STM32_DMA_USES_CHANNEL 中移除（仅保留给 stream-based 系列），或基于 DMA_InitTypeDef.Channel 是否存在来做条件编译。
拉取/合并请求描述：(PR description)
[
为什么提交这份PR (why to submit this PR)
当前 STM32 HAL_Drivers 中 DMA 相关实现分散在两层：
这种实现方式导致 DMA 接入路径和配置表达方式不统一，增加了维护成本，也不利于后续扩展更多 STM32 系列或外设 DMA 场景。
你的解决方案是什么 (what is your solution)
本次修改统一了驱动侧和配置侧两部分 DMA 逻辑：
在驱动侧新增
drv_dma.c/drv_dma.h，引入stm32_dma_config描述结构以及stm32_dma_init()、stm32_dma_setup()、stm32_dma_deinit()等公共 helper，用于统一处理 DMA 控制器时钟开启、DMAMUX 使能、HAL DMA 参数下发、NVIC 配置和反初始化流程。将
drv_hard_i2c.c、drv_spi.c、drv_usart.c、drv_usart_v2.c、drv_qspi.c、drv_sdio.c中原有分散的 DMA 初始化和回滚逻辑切换为复用公共 helper，并将驱动内部相关 DMA 配置改为const struct stm32_dma_config。在配置侧，将多个 STM32 系列下
SPI/UART/I2C/SDIO/QSPI的 DMA 配置宏迁移为统一的描述符初始化宏，如STM32_DMA_*_CONFIG_INIT_EX和STM32_DMA_CONFIG_INIT_FIFO_EX，并补充可覆写的DMA_PRIORITY、DMA_PREEMPT_PRIORITY、DMA_SUB_PRIORITY字段，以统一不同系列配置头的表达方式。请提供验证的bsp和config (provide the config and bsp)
BSP:
.config:
BSP_SPIx_TX_USING_DMA、BSP_SPIx_RX_USING_DMA、BSP_UARTx_TX_USING_DMA、BSP_UARTx_RX_USING_DMA、BSP_I2Cx_TX_USING_DMA、BSP_I2Cx_RX_USING_DMA、BSP_QSPI_USING_DMA、BSP_USING_SDIOaction:
]
当前拉取/合并请求的状态 Intent for your PR
必须选择一项 Choose one (Mandatory):
代码质量 Code Quality：
我在这个拉取/合并请求中已经考虑了 As part of this pull request, I've considered the following:
#if 0代码，不包含已经被注释了的代码 All redundant code is removed and cleaned up