refactor[STM32][DMA]: add common DMA helper layer for HAL drivers

- 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

Author: wdfk-prog

bsp/stm32/libraries/HAL_Drivers/drivers/SConscript

@@ -6,6 +6,9 @@ import os
 cwd = GetCurrentDir()
 group = []
 src = []
+# DMA-capable BSPs are expected to enable HAL_DMA_MODULE_ENABLED in the
+# STM32 HAL configuration, so keep the common DMA helper in the build.
+src += ['drv_dma.c']
 path = [cwd]
 
 if GetDepend(['RT_USING_PIN']):
@@ -35,7 +38,7 @@ if GetDepend('RT_USING_SOFT_SPI'):
 if GetDepend(['RT_USING_I2C', 'RT_USING_I2C_BITOPS']):
     if GetDepend('BSP_USING_I2C1') or GetDepend('BSP_USING_I2C2') or GetDepend('BSP_USING_I2C3') or GetDepend('BSP_USING_I2C4'):
         src += ['drv_soft_i2c.c']
-        
+
 if GetDepend(['RT_USING_I2C']):
     if GetDepend('BSP_USING_HARD_I2C1') or GetDepend('BSP_USING_HARD_I2C2') or GetDepend('BSP_USING_HARD_I2C3') or GetDepend('BSP_USING_HARD_I2C4'):
         src += ['drv_hard_i2c.c']

bsp/stm32/libraries/HAL_Drivers/drivers/drv_config.h

@@ -14,6 +14,7 @@
 
 #include <board.h>
 #include <rtdevice.h>
+#include "drv_dma.h"
 
 #ifdef __cplusplus
 extern "C" {

bsp/stm32/libraries/HAL_Drivers/drivers/drv_dma.c

@@ -0,0 +1,357 @@
+/*
+ * Copyright (c) 2006-2026, RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2026-04-13     wdfk-prog    Add STM32 DMA common helpers
+ */
+
+/**
+ * @file drv_dma.c
+ * @brief STM32 DMA common helper layer for peripheral drivers.
+ */
+
+#include "drv_dma.h"
+
+// #define DRV_DEBUG
+#define LOG_TAG             "drv.dma"
+#include <drv_log.h>
+/* 
+ * DMA-capable BSPs are expected to enable HAL_DMA_MODULE_ENABLED in the
+ * STM32 HAL configuration, so keep the common DMA helper in the build.
+ */
+#ifdef HAL_DMA_MODULE_ENABLED
+
+#if defined(STM32_DMA_USES_REQUEST)
+/**
+ * @brief Enable the DMAMUX clock when the current STM32 DMA path needs it.
+ */
+static void stm32_dma_enable_dmamux_clock(void)
+{
+#if defined(DMAMUX1) && defined(__HAL_RCC_DMAMUX1_CLK_ENABLE)
+    __HAL_RCC_DMAMUX1_CLK_ENABLE();
+#elif defined(DMAMUX) && defined(__HAL_RCC_DMAMUX_CLK_ENABLE)
+    __HAL_RCC_DMAMUX_CLK_ENABLE();
+#endif /* defined(DMAMUX1) && defined(__HAL_RCC_DMAMUX1_CLK_ENABLE) */
+}
+#endif /* defined(STM32_DMA_USES_REQUEST) */
+
+/**
+ * @brief Enable the clock of one DMA controller and wait for the write to complete.
+ * @param dma_rcc RCC enable bit of the DMA controller.
+ */
+static void stm32_dma_enable_clock(rt_uint32_t dma_rcc)
+{
+    rt_uint32_t tmpreg = 0x00U;
+
+#if defined(STM32_DMA_USES_RCC_AHBENR)
+    SET_BIT(RCC->AHBENR, dma_rcc);
+    tmpreg = READ_BIT(RCC->AHBENR, dma_rcc);
+#elif defined(STM32_DMA_USES_RCC_MP_AHB2ENSETR)
+    SET_BIT(RCC->MP_AHB2ENSETR, dma_rcc);
+    tmpreg = READ_BIT(RCC->MP_AHB2ENSETR, dma_rcc);
+#elif defined(STM32_DMA_USES_RCC_AHB1ENR)
+    SET_BIT(RCC->AHB1ENR, dma_rcc);
+    tmpreg = READ_BIT(RCC->AHB1ENR, dma_rcc);
+#endif /* defined(STM32_DMA_USES_RCC_AHBENR) || defined(STM32_DMA_USES_RCC_MP_AHB2ENSETR) || defined(STM32_DMA_USES_RCC_AHB1ENR) */
+
+#if defined(STM32_DMA_USES_REQUEST)
+    stm32_dma_enable_dmamux_clock();
+#endif /* defined(STM32_DMA_USES_REQUEST) */
+
+    UNUSED(tmpreg);
+}
+
+/* Only a few STM32 families expose DMA requests on shared NVIC lines.
+ * Use reference counting only for those known shared IRQ numbers so one
+ * DMA client does not disable a line still used by another active client.
+ * All other DMA IRQs keep the direct enable/disable behavior.
+ */
+#if (defined(SOC_SERIES_STM32F1) && defined(DMA2_Channel4_5_IRQn)) \
+ || (defined(SOC_SERIES_STM32L0) && defined(DMA1_Channel4_5_6_7_IRQn)) \
+ || (defined(SOC_SERIES_STM32G0) && defined(DMA1_Channel2_3_IRQn)) \
+ || (defined(SOC_SERIES_STM32F0) && (defined(DMA1_Channel2_3_IRQn) || defined(DMA1_Channel4_5_IRQn) || defined(DMA1_Channel4_5_6_7_IRQn)))
+#define STM32_DMA_HAS_SHARED_IRQ_REFCNT
+#define STM32_DMA_IRQ_SLOT_COUNT    ((rt_uint32_t)(sizeof(NVIC->ISER) / sizeof(NVIC->ISER[0]) * 32U))
+
+/**
+ * @brief Reference count for each shared DMA IRQ line.
+ */
+static rt_uint16_t stm32_dma_irq_ref_count[STM32_DMA_IRQ_SLOT_COUNT];
+
+/**
+ * @brief Check whether one DMA IRQ number can index the local reference table.
+ * @param dma_irq DMA IRQ number to validate.
+ * @retval RT_TRUE The IRQ number maps to one valid table slot.
+ * @retval RT_FALSE The IRQ number is negative or outside the table range.
+ */
+static rt_bool_t stm32_dma_irq_is_valid(IRQn_Type dma_irq)
+{
+    return ((int32_t)dma_irq >= 0) && ((rt_uint32_t)dma_irq < STM32_DMA_IRQ_SLOT_COUNT);
+}
+
+/**
+ * @brief Check whether one DMA IRQ line is shared and needs reference counting.
+ * @param dma_irq DMA IRQ number to inspect.
+ * @retval RT_TRUE The IRQ line is shared by multiple DMA endpoints.
+ * @retval RT_FALSE The IRQ line can use direct enable and disable handling.
+ */
+static rt_bool_t stm32_dma_irq_needs_refcount(IRQn_Type dma_irq)
+{
+#if defined(SOC_SERIES_STM32F1) && defined(DMA2_Channel4_5_IRQn)
+    if (dma_irq == DMA2_Channel4_5_IRQn)
+    {
+        return RT_TRUE;
+    }
+#endif /* defined(SOC_SERIES_STM32F1) && defined(DMA2_Channel4_5_IRQn) */
+
+#if defined(SOC_SERIES_STM32L0) && defined(DMA1_Channel4_5_6_7_IRQn)
+    if (dma_irq == DMA1_Channel4_5_6_7_IRQn)
+    {
+        return RT_TRUE;
+    }
+#endif /* defined(SOC_SERIES_STM32L0) && defined(DMA1_Channel4_5_6_7_IRQn) */
+
+#if defined(SOC_SERIES_STM32G0) && defined(DMA1_Channel2_3_IRQn)
+    if (dma_irq == DMA1_Channel2_3_IRQn)
+    {
+        return RT_TRUE;
+    }
+#endif /* defined(SOC_SERIES_STM32G0) && defined(DMA1_Channel2_3_IRQn) */
+
+#if defined(SOC_SERIES_STM32F0)
+# if defined(DMA1_Channel2_3_IRQn)
+    if (dma_irq == DMA1_Channel2_3_IRQn)
+    {
+        return RT_TRUE;
+    }
+# endif /* defined(DMA1_Channel2_3_IRQn) */
+# if defined(DMA1_Channel4_5_IRQn)
+    if (dma_irq == DMA1_Channel4_5_IRQn)
+    {
+        return RT_TRUE;
+    }
+# endif /* defined(DMA1_Channel4_5_IRQn) */
+# if defined(DMA1_Channel4_5_6_7_IRQn)
+    if (dma_irq == DMA1_Channel4_5_6_7_IRQn)
+    {
+        return RT_TRUE;
+    }
+# endif /* defined(DMA1_Channel4_5_6_7_IRQn) */
+#endif /* defined(SOC_SERIES_STM32F0) */
+
+    return RT_FALSE;
+}
+#endif /* shared DMA IRQ families */
+
+/**
+ * @brief Enable one DMA IRQ line and apply the requested NVIC priority.
+ * @param dma_irq DMA IRQ number to enable.
+ * @param preempt_priority NVIC preempt priority for the DMA IRQ.
+ * @param sub_priority NVIC subpriority for the DMA IRQ.
+ */
+static void stm32_dma_irq_get(IRQn_Type dma_irq,
+                              rt_uint8_t preempt_priority,
+                              rt_uint8_t sub_priority)
+{
+#if defined(STM32_DMA_HAS_SHARED_IRQ_REFCNT)
+    rt_base_t level;
+
+    if (stm32_dma_irq_needs_refcount(dma_irq) && stm32_dma_irq_is_valid(dma_irq))
+    {
+        level = rt_hw_interrupt_disable();
+        if (stm32_dma_irq_ref_count[(rt_uint32_t)dma_irq] == 0U)
+        {
+            HAL_NVIC_SetPriority(dma_irq, preempt_priority, sub_priority);
+            HAL_NVIC_EnableIRQ(dma_irq);
+        }
+        stm32_dma_irq_ref_count[(rt_uint32_t)dma_irq]++;
+        rt_hw_interrupt_enable(level);
+        return;
+    }
+#endif /* defined(STM32_DMA_HAS_SHARED_IRQ_REFCNT) */
+
+    HAL_NVIC_SetPriority(dma_irq, preempt_priority, sub_priority);
+    HAL_NVIC_EnableIRQ(dma_irq);
+}
+
+/**
+ * @brief Release one DMA IRQ line and disable it when no user remains.
+ * @param dma_irq DMA IRQ number to release.
+ */
+static void stm32_dma_irq_put(IRQn_Type dma_irq)
+{
+#if defined(STM32_DMA_HAS_SHARED_IRQ_REFCNT)
+    rt_base_t level;
+
+    if (stm32_dma_irq_needs_refcount(dma_irq) && stm32_dma_irq_is_valid(dma_irq))
+    {
+        level = rt_hw_interrupt_disable();
+        if (stm32_dma_irq_ref_count[(rt_uint32_t)dma_irq] > 0U)
+        {
+            stm32_dma_irq_ref_count[(rt_uint32_t)dma_irq]--;
+            if (stm32_dma_irq_ref_count[(rt_uint32_t)dma_irq] == 0U)
+            {
+                HAL_NVIC_DisableIRQ(dma_irq);
+            }
+        }
+        rt_hw_interrupt_enable(level);
+        return;
+    }
+#endif /* defined(STM32_DMA_HAS_SHARED_IRQ_REFCNT) */
+
+    HAL_NVIC_DisableIRQ(dma_irq);
+}
+
+/**
+ * @brief Copy one static DMA descriptor into one HAL DMA handle.
+ * @param dma_handle DMA handle to update.
+ * @param dma_config Static DMA endpoint description.
+ */
+static void stm32_dma_apply_config(DMA_HandleTypeDef *dma_handle,
+                                   const struct stm32_dma_config *dma_config)
+{
+    dma_handle->Instance = dma_config->Instance;
+#if defined(STM32_DMA_USES_GPDMA)
+    dma_handle->Init.Request = dma_config->request;
+    dma_handle->Init.BlkHWRequest = dma_config->blk_hw_request;
+    dma_handle->Init.Direction = dma_config->direction;
+    dma_handle->Init.SrcInc = dma_config->src_inc;
+    dma_handle->Init.DestInc = dma_config->dest_inc;
+    dma_handle->Init.SrcDataWidth = dma_config->src_data_width;
+    dma_handle->Init.DestDataWidth = dma_config->dest_data_width;
+    dma_handle->Init.Priority = dma_config->priority;
+    dma_handle->Init.SrcBurstLength = dma_config->src_burst_length;
+    dma_handle->Init.DestBurstLength = dma_config->dest_burst_length;
+    dma_handle->Init.TransferAllocatedPort = dma_config->transfer_allocated_port;
+    dma_handle->Init.TransferEventMode = dma_config->transfer_event_mode;
+    dma_handle->Init.Mode = dma_config->mode;
+#else
+#if defined(STM32_DMA_USES_CHANNEL)
+    dma_handle->Init.Channel = dma_config->channel;
+#endif /* defined(STM32_DMA_USES_CHANNEL) */
+#if defined(STM32_DMA_USES_REQUEST)
+    dma_handle->Init.Request = dma_config->request;
+#endif /* defined(STM32_DMA_USES_REQUEST) */
+    dma_handle->Init.Direction = dma_config->direction;
+    dma_handle->Init.PeriphInc = dma_config->periph_inc;
+    dma_handle->Init.MemInc = dma_config->mem_inc;
+    dma_handle->Init.PeriphDataAlignment = dma_config->periph_data_alignment;
+    dma_handle->Init.MemDataAlignment = dma_config->mem_data_alignment;
+    dma_handle->Init.Mode = dma_config->mode;
+    dma_handle->Init.Priority = dma_config->priority;
+#if defined(STM32_DMA_SUPPORTS_FIFO)
+    dma_handle->Init.FIFOMode = dma_config->fifo_mode;
+    dma_handle->Init.FIFOThreshold = dma_config->fifo_threshold;
+    dma_handle->Init.MemBurst = dma_config->mem_burst;
+    dma_handle->Init.PeriphBurst = dma_config->periph_burst;
+#endif /* defined(STM32_DMA_SUPPORTS_FIFO) */
+#endif /* defined(STM32_DMA_USES_GPDMA) */
+}
+
+/**
+ * @brief Enable one DMA controller, apply the static descriptor and initialize HAL state.
+ * @param dma_handle DMA handle owned by one peripheral driver.
+ * @param dma_config Board-level DMA endpoint description.
+ * @retval RT_EOK Initialization succeeded.
+ * @retval -RT_ERROR HAL initialization failed.
+ */
+rt_err_t stm32_dma_init(DMA_HandleTypeDef *dma_handle,
+                        const struct stm32_dma_config *dma_config)
+{
+    RT_ASSERT(dma_handle != RT_NULL);
+    RT_ASSERT(dma_config != RT_NULL);
+
+    stm32_dma_enable_clock(dma_config->dma_rcc);
+    stm32_dma_apply_config(dma_handle, dma_config);
+
+    LOG_D("dma init, dma=%p, irq=%d", dma_handle->Instance, dma_config->dma_irq);
+
+    if (HAL_DMA_DeInit(dma_handle) != HAL_OK)
+    {
+        LOG_E("dma deinit failed, dma=%p, irq=%d", dma_handle->Instance, dma_config->dma_irq);
+        return -RT_ERROR;
+    }
+
+    if (HAL_DMA_Init(dma_handle) != HAL_OK)
+    {
+        LOG_E("dma init failed, dma=%p, irq=%d", dma_handle->Instance, dma_config->dma_irq);
+        return -RT_ERROR;
+    }
+
+    return RT_EOK;
+}
+
+/**
+ * @brief Initialize one DMA handle, attach it to the parent HAL handle and enable the DMA IRQ.
+ * @param dma_handle DMA handle owned by one peripheral driver.
+ * @param parent_handle Parent HAL handle, such as UART_HandleTypeDef or SPI_HandleTypeDef.
+ * @param dma_slot Address of the parent handle DMA slot, such as &huart->hdmarx.
+ * @param dma_config Board-level DMA endpoint description.
+ * @retval RT_EOK Initialization succeeded.
+ * @retval -RT_ERROR HAL initialization failed.
+ */
+rt_err_t stm32_dma_setup(DMA_HandleTypeDef *dma_handle,
+                         void *parent_handle,
+                         DMA_HandleTypeDef **dma_slot,
+                         const struct stm32_dma_config *dma_config)
+{
+    rt_err_t result;
+
+    result = stm32_dma_init(dma_handle, dma_config);
+    if (result != RT_EOK)
+    {
+        return result;
+    }
+
+    if ((parent_handle != RT_NULL) && (dma_slot != RT_NULL))
+    {
+        *dma_slot = dma_handle;
+        dma_handle->Parent = parent_handle;
+    }
+
+    stm32_dma_irq_get(dma_config->dma_irq, dma_config->preempt_priority, dma_config->sub_priority);
+
+    LOG_D("dma setup, dma=%p, irq=%d", dma_handle->Instance, dma_config->dma_irq);
+
+    return RT_EOK;
+}
+
+/**
+ * @brief Disable one DMA IRQ, optionally abort the current transfer and de-initialize HAL state.
+ * @param dma_handle DMA handle owned by one peripheral driver.
+ * @param dma_config Board-level DMA endpoint description.
+ * @param abort_first RT_TRUE aborts the ongoing transfer before HAL_DMA_DeInit().
+ * @retval RT_EOK De-initialization succeeded.
+ * @retval -RT_ERROR HAL de-initialization failed.
+ */
+rt_err_t stm32_dma_deinit(DMA_HandleTypeDef *dma_handle,
+                          const struct stm32_dma_config *dma_config,
+                          rt_bool_t abort_first)
+{
+    RT_ASSERT(dma_handle != RT_NULL);
+    RT_ASSERT(dma_config != RT_NULL);
+
+    stm32_dma_irq_put(dma_config->dma_irq);
+
+    LOG_D("dma deinit, dma=%p, irq=%d", dma_handle->Instance, dma_config->dma_irq);
+
+    if (abort_first)
+    {
+        if (HAL_DMA_Abort(dma_handle) != HAL_OK)
+        {
+            LOG_W("dma abort failed, continue deinit, dma=%p, irq=%d", dma_handle->Instance, dma_config->dma_irq);
+        }
+    }
+
+    if (HAL_DMA_DeInit(dma_handle) != HAL_OK)
+    {
+        LOG_E("dma deinit failed, dma=%p, irq=%d", dma_handle->Instance, dma_config->dma_irq);
+        return -RT_ERROR;
+    }
+
+    return RT_EOK;
+}
+#endif /* HAL_DMA_MODULE_ENABLED */