feat(esp_gdma): add hal interface for common operations

GDMA driver will be adapted to more DMA peripherals in the future.
This commit is to extract a minimal interface in the hal layer

components/hal/CMakeLists.txt

@@ -85,7 +85,19 @@ if(NOT BOOTLOADER_BUILD)
     endif()
 
     if(CONFIG_SOC_GDMA_SUPPORTED)
-        list(APPEND srcs "gdma_hal.c")
+        list(APPEND srcs "gdma_hal_top.c")
+    endif()
+
+    if(CONFIG_SOC_AHB_GDMA_VERSION EQUAL 1)
+        list(APPEND srcs "gdma_hal_ahb_v1.c")
+    endif()
+
+    if(CONFIG_SOC_AHB_GDMA_VERSION EQUAL 2)
+        list(APPEND srcs "gdma_hal_ahb_v2.c")
+    endif()
+
+    if(CONFIG_SOC_AXI_GDMA_SUPPORTED)
+        list(APPEND srcs "gdma_hal_axi.c")
     endif()
 
     if(CONFIG_SOC_I2S_SUPPORTED)

components/hal/adc_hal.c

@@ -27,7 +27,7 @@
 /*---------------------------------------------------------------
             Define all ADC DMA required operations here
 ---------------------------------------------------------------*/
-#if SOC_GDMA_SUPPORTED
+#if SOC_AHB_GDMA_VERSION == 1
 #define adc_dma_ll_rx_clear_intr(dev, chan, mask)       gdma_ll_rx_clear_interrupt_status(dev, chan, mask)
 #define adc_dma_ll_rx_enable_intr(dev, chan, mask)      gdma_ll_rx_enable_interrupt(dev, chan, mask, true)
 #define adc_dma_ll_rx_disable_intr(dev, chan, mask)     gdma_ll_rx_enable_interrupt(dev, chan, mask, false)

components/hal/esp32c2/include/hal/gdma_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -41,11 +41,16 @@ extern "C" {
 #define GDMA_LL_EVENT_RX_SUC_EOF    (1<<1)
 #define GDMA_LL_EVENT_RX_DONE       (1<<0)
 
+#define GDMA_LL_AHB_GROUP_START_ID    0       // AHB GDMA group ID starts from 0
+#define GDMA_LL_AHB_NUM_GROUPS        1       // Number of AHB GDMA groups
+#define GDMA_LL_AHB_PAIRS_PER_GROUP   1       // Number of GDMA pairs in each AHB group
+#define GDMA_LL_AHB_TX_RX_SHARE_INTERRUPT  1  // TX and RX channel in the same pair will share the same interrupt source number
+
 ///////////////////////////////////// Common /////////////////////////////////////////
 /**
- * @brief Enable DMA clock gating
+ * @brief Force enable register clock
  */
-static inline void gdma_ll_enable_clock(gdma_dev_t *dev, bool enable)
+static inline void gdma_ll_force_enable_reg_clock(gdma_dev_t *dev, bool enable)
 {
     dev->misc_conf.clk_en = enable;
 }

components/hal/esp32c3/include/hal/gdma_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -41,11 +41,16 @@ extern "C" {
 #define GDMA_LL_EVENT_RX_SUC_EOF    (1<<1)
 #define GDMA_LL_EVENT_RX_DONE       (1<<0)
 
+#define GDMA_LL_AHB_GROUP_START_ID         0 // AHB GDMA group ID starts from 0
+#define GDMA_LL_AHB_NUM_GROUPS             1 // Number of AHB GDMA groups
+#define GDMA_LL_AHB_PAIRS_PER_GROUP        3 // Number of GDMA pairs in each AHB group
+#define GDMA_LL_AHB_TX_RX_SHARE_INTERRUPT  1  // TX and RX channel in the same pair will share the same interrupt source number
+
 ///////////////////////////////////// Common /////////////////////////////////////////
 /**
- * @brief Enable DMA clock gating
+ * @brief Force enable register clock
  */
-static inline void gdma_ll_enable_clock(gdma_dev_t *dev, bool enable)
+static inline void gdma_ll_force_enable_reg_clock(gdma_dev_t *dev, bool enable)
 {
     dev->misc_conf.clk_en = enable;
 }

components/hal/esp32c6/include/hal/gdma_ll.h

@@ -42,6 +42,10 @@ extern "C" {
 #define GDMA_LL_EVENT_RX_SUC_EOF    (1<<1)
 #define GDMA_LL_EVENT_RX_DONE       (1<<0)
 
+#define GDMA_LL_AHB_GROUP_START_ID    0 // AHB GDMA group ID starts from 0
+#define GDMA_LL_AHB_NUM_GROUPS        1 // Number of AHB GDMA groups
+#define GDMA_LL_AHB_PAIRS_PER_GROUP   3 // Number of GDMA pairs in each AHB group
+
 #define GDMA_LL_TX_ETM_EVENT_TABLE(group, chan, event)                                     \
     (uint32_t[1][3][GDMA_ETM_EVENT_MAX]){{{                                                \
                                               [GDMA_ETM_EVENT_EOF] = GDMA_EVT_OUT_EOF_CH0, \
@@ -88,9 +92,9 @@ extern "C" {
 
 ///////////////////////////////////// Common /////////////////////////////////////////
 /**
- * @brief Enable DMA clock gating
+ * @brief Force enable register clock
  */
-static inline void gdma_ll_enable_clock(gdma_dev_t *dev, bool enable)
+static inline void gdma_ll_force_enable_reg_clock(gdma_dev_t *dev, bool enable)
 {
     dev->misc_conf.clk_en = enable;
 }
@@ -102,7 +106,7 @@ static inline void gdma_ll_enable_clock(gdma_dev_t *dev, bool enable)
 __attribute__((always_inline))
 static inline uint32_t gdma_ll_rx_get_interrupt_status(gdma_dev_t *dev, uint32_t channel)
 {
-    return dev->in_intr[channel].st.val & GDMA_LL_RX_EVENT_MASK;
+    return dev->in_intr[channel].st.val;
 }
 
 /**
@@ -111,9 +115,9 @@ static inline uint32_t gdma_ll_rx_get_interrupt_status(gdma_dev_t *dev, uint32_t
 static inline void gdma_ll_rx_enable_interrupt(gdma_dev_t *dev, uint32_t channel, uint32_t mask, bool enable)
 {
     if (enable) {
-        dev->in_intr[channel].ena.val |= (mask & GDMA_LL_RX_EVENT_MASK);
+        dev->in_intr[channel].ena.val |= mask;
     } else {
-        dev->in_intr[channel].ena.val &= ~(mask & GDMA_LL_RX_EVENT_MASK);
+        dev->in_intr[channel].ena.val &= ~mask;
     }
 }
 
@@ -123,7 +127,7 @@ static inline void gdma_ll_rx_enable_interrupt(gdma_dev_t *dev, uint32_t channel
 __attribute__((always_inline))
 static inline void gdma_ll_rx_clear_interrupt_status(gdma_dev_t *dev, uint32_t channel, uint32_t mask)
 {
-    dev->in_intr[channel].clr.val = (mask & GDMA_LL_RX_EVENT_MASK);
+    dev->in_intr[channel].clr.val = mask;
 }
 
 /**
@@ -326,7 +330,7 @@ static inline void gdma_ll_rx_enable_etm_task(gdma_dev_t *dev, uint32_t channel,
 __attribute__((always_inline))
 static inline uint32_t gdma_ll_tx_get_interrupt_status(gdma_dev_t *dev, uint32_t channel)
 {
-    return dev->out_intr[channel].st.val & GDMA_LL_TX_EVENT_MASK;
+    return dev->out_intr[channel].st.val;
 }
 
 /**
@@ -335,9 +339,9 @@ static inline uint32_t gdma_ll_tx_get_interrupt_status(gdma_dev_t *dev, uint32_t
 static inline void gdma_ll_tx_enable_interrupt(gdma_dev_t *dev, uint32_t channel, uint32_t mask, bool enable)
 {
     if (enable) {
-        dev->out_intr[channel].ena.val |= (mask & GDMA_LL_TX_EVENT_MASK);
+        dev->out_intr[channel].ena.val |= mask;
     } else {
-        dev->out_intr[channel].ena.val &= ~(mask & GDMA_LL_TX_EVENT_MASK);
+        dev->out_intr[channel].ena.val &= ~mask;
     }
 }
 
@@ -347,7 +351,7 @@ static inline void gdma_ll_tx_enable_interrupt(gdma_dev_t *dev, uint32_t channel
 __attribute__((always_inline))
 static inline void gdma_ll_tx_clear_interrupt_status(gdma_dev_t *dev, uint32_t channel, uint32_t mask)
 {
-    dev->out_intr[channel].clr.val = (mask & GDMA_LL_TX_EVENT_MASK);
+    dev->out_intr[channel].clr.val = mask;
 }
 
 /**

components/hal/esp32h2/include/hal/gdma_ll.h

@@ -42,6 +42,10 @@ extern "C" {
 #define GDMA_LL_EVENT_RX_SUC_EOF    (1<<1)
 #define GDMA_LL_EVENT_RX_DONE       (1<<0)
 
+#define GDMA_LL_AHB_GROUP_START_ID    0 // AHB GDMA group ID starts from 0
+#define GDMA_LL_AHB_NUM_GROUPS        1 // Number of AHB GDMA groups
+#define GDMA_LL_AHB_PAIRS_PER_GROUP   3 // Number of GDMA pairs in each AHB group
+
 #define GDMA_LL_TX_ETM_EVENT_TABLE(group, chan, event)                                     \
     (uint32_t[1][3][GDMA_ETM_EVENT_MAX]){{{                                                \
                                               [GDMA_ETM_EVENT_EOF] = GDMA_EVT_OUT_EOF_CH0, \
@@ -88,9 +92,9 @@ extern "C" {
 
 ///////////////////////////////////// Common /////////////////////////////////////////
 /**
- * @brief Enable DMA clock gating
+ * @brief Force enable register clock
  */
-static inline void gdma_ll_enable_clock(gdma_dev_t *dev, bool enable)
+static inline void gdma_ll_force_enable_reg_clock(gdma_dev_t *dev, bool enable)
 {
     dev->misc_conf.clk_en = enable;
 }
@@ -102,7 +106,7 @@ static inline void gdma_ll_enable_clock(gdma_dev_t *dev, bool enable)
 __attribute__((always_inline))
 static inline uint32_t gdma_ll_rx_get_interrupt_status(gdma_dev_t *dev, uint32_t channel)
 {
-    return dev->in_intr[channel].st.val & GDMA_LL_RX_EVENT_MASK;
+    return dev->in_intr[channel].st.val;
 }
 
 /**
@@ -111,9 +115,9 @@ static inline uint32_t gdma_ll_rx_get_interrupt_status(gdma_dev_t *dev, uint32_t
 static inline void gdma_ll_rx_enable_interrupt(gdma_dev_t *dev, uint32_t channel, uint32_t mask, bool enable)
 {
     if (enable) {
-        dev->in_intr[channel].ena.val |= (mask & GDMA_LL_RX_EVENT_MASK);
+        dev->in_intr[channel].ena.val |= mask;
     } else {
-        dev->in_intr[channel].ena.val &= ~(mask & GDMA_LL_RX_EVENT_MASK);
+        dev->in_intr[channel].ena.val &= ~mask;
     }
 }
 
@@ -123,7 +127,7 @@ static inline void gdma_ll_rx_enable_interrupt(gdma_dev_t *dev, uint32_t channel
 __attribute__((always_inline))
 static inline void gdma_ll_rx_clear_interrupt_status(gdma_dev_t *dev, uint32_t channel, uint32_t mask)
 {
-    dev->in_intr[channel].clr.val = (mask & GDMA_LL_RX_EVENT_MASK);
+    dev->in_intr[channel].clr.val = mask;
 }
 
 /**
@@ -326,7 +330,7 @@ static inline void gdma_ll_rx_enable_etm_task(gdma_dev_t *dev, uint32_t channel,
 __attribute__((always_inline))
 static inline uint32_t gdma_ll_tx_get_interrupt_status(gdma_dev_t *dev, uint32_t channel)
 {
-    return dev->out_intr[channel].st.val & GDMA_LL_TX_EVENT_MASK;
+    return dev->out_intr[channel].st.val;
 }
 
 /**
@@ -335,9 +339,9 @@ static inline uint32_t gdma_ll_tx_get_interrupt_status(gdma_dev_t *dev, uint32_t
 static inline void gdma_ll_tx_enable_interrupt(gdma_dev_t *dev, uint32_t channel, uint32_t mask, bool enable)
 {
     if (enable) {
-        dev->out_intr[channel].ena.val |= (mask & GDMA_LL_TX_EVENT_MASK);
+        dev->out_intr[channel].ena.val |= mask;
     } else {
-        dev->out_intr[channel].ena.val &= ~(mask & GDMA_LL_TX_EVENT_MASK);
+        dev->out_intr[channel].ena.val &= ~mask;
     }
 }
 
@@ -347,7 +351,7 @@ static inline void gdma_ll_tx_enable_interrupt(gdma_dev_t *dev, uint32_t channel
 __attribute__((always_inline))
 static inline void gdma_ll_tx_clear_interrupt_status(gdma_dev_t *dev, uint32_t channel, uint32_t mask)
 {
-    dev->out_intr[channel].clr.val = (mask & GDMA_LL_TX_EVENT_MASK);
+    dev->out_intr[channel].clr.val = mask;
 }
 
 /**

components/hal/esp32s3/include/hal/gdma_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -8,6 +8,7 @@
 #include <stddef.h> /* For NULL declaration */
 #include <stdint.h>
 #include <stdbool.h>
+#include "hal/assert.h"
 #include "hal/gdma_types.h"
 #include "soc/gdma_struct.h"
 #include "soc/gdma_reg.h"
@@ -47,18 +48,22 @@ extern "C" {
 #define GDMA_LL_EVENT_RX_SUC_EOF     (1<<1)
 #define GDMA_LL_EVENT_RX_DONE        (1<<0)
 
-#define GDMA_LL_L2FIFO_BASE_SIZE (16) // Basic size of GDMA Level 2 FIFO
+#define GDMA_LL_L2FIFO_BASE_SIZE     16 // Basic size of GDMA Level 2 FIFO
 
 /* Memory block size value supported by channel */
-#define GDMA_LL_EXT_MEM_BK_SIZE_16B (0)
-#define GDMA_LL_EXT_MEM_BK_SIZE_32B (1)
-#define GDMA_LL_EXT_MEM_BK_SIZE_64B (2)
+#define GDMA_LL_EXT_MEM_BK_SIZE_16B   0
+#define GDMA_LL_EXT_MEM_BK_SIZE_32B   1
+#define GDMA_LL_EXT_MEM_BK_SIZE_64B   2
+
+#define GDMA_LL_AHB_GROUP_START_ID    0 // AHB GDMA group ID starts from 0
+#define GDMA_LL_AHB_NUM_GROUPS        1 // Number of AHB GDMA groups
+#define GDMA_LL_AHB_PAIRS_PER_GROUP   5 // Number of GDMA pairs in each AHB group
 
 ///////////////////////////////////// Common /////////////////////////////////////////
 /**
- * @brief Enable DMA clock gating
+ * @brief Force enable register clock
  */
-static inline void gdma_ll_enable_clock(gdma_dev_t *dev, bool enable)
+static inline void gdma_ll_force_enable_reg_clock(gdma_dev_t *dev, bool enable)
 {
     dev->misc_conf.clk_en = enable;
 }
@@ -137,12 +142,28 @@ static inline void gdma_ll_rx_reset_channel(gdma_dev_t *dev, uint32_t channel)
 }
 
 /**
- * @brief Set DMA RX channel memory block size
- * @param size_index Supported value: GDMA_LL_EXT_MEM_BK_SIZE_16B/32B/64B
+ * @brief Set DMA RX channel memory block size based on the alignment requirement
+ * @param align Supported value: 16/32/64
  */
-static inline void gdma_ll_rx_set_block_size_psram(gdma_dev_t *dev, uint32_t channel, uint32_t size_index)
+static inline void gdma_ll_rx_set_ext_mem_block_size(gdma_dev_t *dev, uint32_t channel, uint8_t align)
 {
-    dev->channel[channel].in.conf1.in_ext_mem_bk_size = size_index;
+    uint32_t block_size = 0;
+    switch (align) {
+    case 64: // 64 Bytes alignment
+        block_size = GDMA_LL_EXT_MEM_BK_SIZE_64B;
+        break;
+    case 32: // 32 Bytes alignment
+        block_size = GDMA_LL_EXT_MEM_BK_SIZE_32B;
+        break;
+    case 16: // 16 Bytes alignment
+        block_size = GDMA_LL_EXT_MEM_BK_SIZE_16B;
+        break;
+    default:
+        HAL_ASSERT(false);
+        break;
+    }
+
+    dev->channel[channel].in.conf1.in_ext_mem_bk_size = block_size;
 }
 
 /**
@@ -401,12 +422,28 @@ static inline void gdma_ll_tx_reset_channel(gdma_dev_t *dev, uint32_t channel)
 }
 
 /**
- * @brief Set DMA TX channel memory block size
- * @param size_index Supported value: GDMA_LL_EXT_MEM_BK_SIZE_16B/32B/64B
+ * @brief Set DMA TX channel memory block size based on the alignment requirement
+ * @param align Supported value: 16/32/64
  */
-static inline void gdma_ll_tx_set_block_size_psram(gdma_dev_t *dev, uint32_t channel, uint32_t size_index)
+static inline void gdma_ll_tx_set_ext_mem_block_size(gdma_dev_t *dev, uint32_t channel, uint8_t align)
 {
-    dev->channel[channel].out.conf1.out_ext_mem_bk_size = size_index;
+    uint32_t block_size = 0;
+    switch (align) {
+    case 64: // 64 Bytes alignment
+        block_size = GDMA_LL_EXT_MEM_BK_SIZE_64B;
+        break;
+    case 32: // 32 Bytes alignment
+        block_size = GDMA_LL_EXT_MEM_BK_SIZE_32B;
+        break;
+    case 16: // 16 Bytes alignment
+        block_size = GDMA_LL_EXT_MEM_BK_SIZE_16B;
+        break;
+    default:
+        HAL_ASSERT(false);
+        break;
+    }
+
+    dev->channel[channel].out.conf1.out_ext_mem_bk_size = block_size;
 }
 
 /**

components/hal/gdma_hal.c

@@ -1,13 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-
-#include "hal/gdma_hal.h"
-#include "hal/gdma_ll.h"
-
-void gdma_hal_init(gdma_hal_context_t *hal, int group_id)
-{
-    hal->dev = GDMA_LL_GET_HW(group_id);
-}

components/hal/gdma_hal_ahb_v1.c

@@ -0,0 +1,181 @@
+/*
+ * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "soc/soc_caps.h"
+#include "hal/assert.h"
+#include "hal/gdma_hal_ahb.h"
+#include "hal/gdma_ll.h"
+
+static gdma_hal_priv_data_t gdma_ahb_hal_priv_data = {
+    .m2m_free_periph_mask = GDMA_LL_M2M_FREE_PERIPH_ID_MASK,
+};
+
+void gdma_ahb_hal_start_with_desc(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, intptr_t desc_base_addr)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_set_desc_addr(hal->dev, chan_id, desc_base_addr);
+        gdma_ll_rx_start(hal->dev, chan_id);
+    } else {
+        gdma_ll_tx_set_desc_addr(hal->dev, chan_id, desc_base_addr);
+        gdma_ll_tx_start(hal->dev, chan_id);
+    }
+}
+
+void gdma_ahb_hal_stop(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_stop(hal->dev, chan_id);
+    } else {
+        gdma_ll_tx_stop(hal->dev, chan_id);
+    }
+}
+
+void gdma_ahb_hal_append(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_restart(hal->dev, chan_id);
+    } else {
+        gdma_ll_tx_restart(hal->dev, chan_id);
+    }
+}
+
+void gdma_ahb_hal_reset(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_reset_channel(hal->dev, chan_id);
+    } else {
+        gdma_ll_tx_reset_channel(hal->dev, chan_id);
+    }
+}
+
+void gdma_ahb_hal_set_priority(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t priority)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_set_priority(hal->dev, chan_id, priority);
+    } else {
+        gdma_ll_tx_set_priority(hal->dev, chan_id, priority);
+    }
+}
+
+void gdma_ahb_hal_connect_peri(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, gdma_trigger_peripheral_t periph, int periph_sub_id)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_reset_channel(hal->dev, chan_id); // reset channel
+        gdma_ll_rx_connect_to_periph(hal->dev, chan_id, periph, periph_sub_id);
+    } else {
+        gdma_ll_tx_reset_channel(hal->dev, chan_id); // reset channel
+        gdma_ll_tx_connect_to_periph(hal->dev, chan_id, periph, periph_sub_id);
+    }
+}
+
+void gdma_ahb_hal_disconnect_peri(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_disconnect_from_periph(hal->dev, chan_id);
+    } else {
+        gdma_ll_tx_disconnect_from_periph(hal->dev, chan_id);
+    }
+}
+
+void gdma_ahb_hal_enable_burst(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_data_burst, bool en_desc_burst)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_enable_data_burst(hal->dev, chan_id, en_data_burst);
+        gdma_ll_rx_enable_descriptor_burst(hal->dev, chan_id, en_desc_burst);
+    } else {
+        gdma_ll_tx_enable_data_burst(hal->dev, chan_id, en_data_burst);
+        gdma_ll_tx_enable_descriptor_burst(hal->dev, chan_id, en_desc_burst);
+    }
+}
+
+#if SOC_AHB_GDMA_SUPPORT_PSRAM
+void gdma_ahb_hal_set_ext_mem_align(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint8_t align)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_set_ext_mem_block_size(hal->dev, chan_id, align);
+    } else {
+        gdma_ll_tx_set_ext_mem_block_size(hal->dev, chan_id, align);
+    }
+}
+#endif
+
+void gdma_ahb_hal_set_strategy(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_owner_check, bool en_desc_write_back)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_enable_owner_check(hal->dev, chan_id, en_owner_check);
+    } else {
+        gdma_ll_tx_enable_owner_check(hal->dev, chan_id, en_owner_check);
+        gdma_ll_tx_enable_auto_write_back(hal->dev, chan_id, en_desc_write_back);
+    }
+}
+
+void gdma_ahb_hal_enable_intr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask, bool en_or_dis)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_enable_interrupt(hal->dev, chan_id, intr_event_mask, en_or_dis);
+    } else {
+        gdma_ll_tx_enable_interrupt(hal->dev, chan_id, intr_event_mask, en_or_dis);
+    }
+}
+
+void gdma_ahb_hal_clear_intr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        gdma_ll_rx_clear_interrupt_status(hal->dev, chan_id, intr_event_mask);
+    } else {
+        gdma_ll_tx_clear_interrupt_status(hal->dev, chan_id, intr_event_mask);
+    }
+}
+
+uint32_t gdma_ahb_hal_read_intr_status(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        return gdma_ll_rx_get_interrupt_status(hal->dev, chan_id);
+    } else {
+        return gdma_ll_tx_get_interrupt_status(hal->dev, chan_id);
+    }
+}
+
+uint32_t gdma_ahb_hal_get_intr_status_reg(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        return (uint32_t)gdma_ll_rx_get_interrupt_status_reg(hal->dev, chan_id);
+    } else {
+        return (uint32_t)gdma_ll_tx_get_interrupt_status_reg(hal->dev, chan_id);
+    }
+}
+
+uint32_t gdma_ahb_hal_get_eof_desc_addr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    if (dir == GDMA_CHANNEL_DIRECTION_RX) {
+        return gdma_ll_rx_get_success_eof_desc_addr(hal->dev, chan_id);
+    } else {
+        return gdma_ll_tx_get_eof_desc_addr(hal->dev, chan_id);
+    }
+}
+
+void gdma_ahb_hal_init(gdma_hal_context_t *hal, const gdma_hal_config_t *config)
+{
+    hal->dev = GDMA_LL_GET_HW(config->group_id - GDMA_LL_AHB_GROUP_START_ID);
+    hal->start_with_desc = gdma_ahb_hal_start_with_desc;
+    hal->stop = gdma_ahb_hal_stop;
+    hal->append = gdma_ahb_hal_append;
+    hal->reset = gdma_ahb_hal_reset;
+    hal->set_priority = gdma_ahb_hal_set_priority;
+    hal->connect_peri = gdma_ahb_hal_connect_peri;
+    hal->disconnect_peri = gdma_ahb_hal_disconnect_peri;
+    hal->enable_burst = gdma_ahb_hal_enable_burst;
+    hal->set_strategy = gdma_ahb_hal_set_strategy;
+    hal->enable_intr = gdma_ahb_hal_enable_intr;
+    hal->clear_intr = gdma_ahb_hal_clear_intr;
+    hal->read_intr_status = gdma_ahb_hal_read_intr_status;
+    hal->get_intr_status_reg = gdma_ahb_hal_get_intr_status_reg;
+    hal->get_eof_desc_addr = gdma_ahb_hal_get_eof_desc_addr;
+#if SOC_AHB_GDMA_SUPPORT_PSRAM
+    hal->set_ext_mem_align = gdma_ahb_hal_set_ext_mem_align;
+#endif // SOC_AHB_GDMA_SUPPORT_PSRAM
+    hal->priv_data = &gdma_ahb_hal_priv_data;
+}

components/hal/gdma_hal_top.c

@@ -0,0 +1,91 @@
+/*
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdlib.h>
+#include "hal/assert.h"
+#include "hal/gdma_hal.h"
+
+void gdma_hal_deinit(gdma_hal_context_t *hal)
+{
+    hal->generic_dev = NULL;
+}
+
+void gdma_hal_start_with_desc(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, intptr_t desc_base_addr)
+{
+    hal->start_with_desc(hal, chan_id, dir, desc_base_addr);
+}
+
+void gdma_hal_stop(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    hal->stop(hal, chan_id, dir);
+}
+
+void gdma_hal_append(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    hal->append(hal, chan_id, dir);
+}
+
+void gdma_hal_reset(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    hal->reset(hal, chan_id, dir);
+}
+
+void gdma_hal_set_priority(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t priority)
+{
+    hal->set_priority(hal, chan_id, dir, priority);
+}
+
+void gdma_hal_connect_peri(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, gdma_trigger_peripheral_t periph, int periph_sub_id)
+{
+    hal->connect_peri(hal, chan_id, dir, periph, periph_sub_id);
+}
+
+void gdma_hal_disconnect_peri(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    hal->disconnect_peri(hal, chan_id, dir);
+}
+
+void gdma_hal_enable_burst(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_data_burst, bool en_desc_burst)
+{
+    hal->enable_burst(hal, chan_id, dir, en_data_burst, en_desc_burst);
+}
+
+void gdma_hal_set_ext_mem_align(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint8_t align)
+{
+    if (hal->set_ext_mem_align) {
+        hal->set_ext_mem_align(hal, chan_id, dir, align);
+    }
+}
+
+void gdma_hal_set_strategy(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_owner_check, bool en_desc_write_back)
+{
+    hal->set_strategy(hal, chan_id, dir, en_owner_check, en_desc_write_back);
+}
+
+void gdma_hal_enable_intr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask, bool en_or_dis)
+{
+    hal->enable_intr(hal, chan_id, dir, intr_event_mask, en_or_dis);
+}
+
+void gdma_hal_clear_intr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask)
+{
+    hal->clear_intr(hal, chan_id, dir, intr_event_mask);
+}
+
+uint32_t gdma_hal_read_intr_status(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    return hal->read_intr_status(hal, chan_id, dir);
+}
+
+uint32_t gdma_hal_get_intr_status_reg(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    return hal->get_intr_status_reg(hal, chan_id, dir);
+}
+
+uint32_t gdma_hal_get_eof_desc_addr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir)
+{
+    return hal->get_eof_desc_addr(hal, chan_id, dir);
+}

components/hal/include/hal/gdma_hal.h

@@ -1,34 +1,118 @@
 /*
- * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/*******************************************************************************
- * NOTICE
- * The HAL is not public api, don't use in application code.
- * See readme.md in soc/README.md
- ******************************************************************************/
-
 #pragma once
 
+#include <stdbool.h>
+#include <stdint.h>
+#include "soc/soc_caps.h"
+#include "hal/gdma_types.h"
+
+// TODO: don't expose the SOC header files, we can typedef a new type for the register dev pointer
+#if SOC_AHB_GDMA_VERSION == 1
+#include "soc/gdma_struct.h"
+#endif
+#if SOC_AHB_GDMA_VERSION == 2
+#include "soc/ahb_dma_struct.h"
+#endif
+#if SOC_AXI_GDMA_SUPPORTED
+#include "soc/axi_dma_struct.h"
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-#include "soc/soc_caps.h"
-
-#if SOC_GDMA_SUPPORTED
-
-#include "soc/gdma_struct.h"
+/// forward declaration of the HAL context
+typedef struct gdma_hal_context_t gdma_hal_context_t;
 
+/**
+ * @brief GDMA HAL configuration
+ */
 typedef struct {
-    gdma_dev_t *dev;
-} gdma_hal_context_t;
+    int group_id;  /*!< GDMA group ID */
+} gdma_hal_config_t;
 
-void gdma_hal_init(gdma_hal_context_t *hal, int group_id);
+/**
+ * @brief GDMA HAL private data
+ */
+typedef struct {
+    // The bitmap of the IDs that can be used by M2M are different between AXI DMA and AHB DMA, so we need to save a copy for each of them
+    uint32_t m2m_free_periph_mask;
+    // TODO: we can add more private data here, e.g. the interrupt event mask of interest
+    // for now, the AXI DMA and AHB DMA are sharing the same interrupt mask, so we don't need to store it here
+    // If one day they become incompatible, we shall save a copy for each of them as a private data
+} gdma_hal_priv_data_t;
 
+/**
+ * @brief HAL context definition
+ */
+struct gdma_hal_context_t {
+    /// the underlying hardware can be different
+    union {
+#if SOC_AHB_GDMA_VERSION == 1
+        gdma_dev_t *dev;
 #endif
+#if SOC_AHB_GDMA_VERSION == 2
+        ahb_dma_dev_t *ahb_dma_dev;
+#endif
+#if SOC_AXI_GDMA_SUPPORTED
+        axi_dma_dev_t *axi_dma_dev;
+#endif
+        void *generic_dev;
+    };
+    gdma_hal_priv_data_t *priv_data; /// private data for the HAL
+    void (*start_with_desc)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, intptr_t desc_base_addr); /// start the channel with the start address of the descriptor
+    void (*stop)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir); /// stop the channel
+    void (*append)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir); /// Append a descriptor to the channel
+    void (*reset)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir); /// Reset the channel
+    void (*set_priority)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t priority); /// Set the channel priority
+    void (*connect_peri)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, gdma_trigger_peripheral_t periph, int periph_sub_id); /// Connect the channel to a peripheral
+    void (*disconnect_peri)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir); /// Disconnect the channel from a peripheral
+    void (*enable_burst)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_data_burst, bool en_desc_burst); /// Enable burst mode
+    void (*set_ext_mem_align)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint8_t align); /// Set the alignment of the external memory
+    void (*set_strategy)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_owner_check, bool en_desc_write_back); /// Set some misc strategy of the channel behaviour
+    uint32_t (*get_intr_status_reg)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir); // Get the interrupt status register address
+    void (*enable_intr)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask, bool en_or_dis); /// Enable the channel interrupt
+    void (*clear_intr)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask); /// Clear the channel interrupt
+    uint32_t (*read_intr_status)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir); /// Read the channel interrupt status
+    uint32_t (*get_eof_desc_addr)(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir); /// Get the address of the descriptor with EOF flag set
+};
+
+void gdma_hal_deinit(gdma_hal_context_t *hal);
+
+void gdma_hal_start_with_desc(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, intptr_t desc_base_addr);
+
+void gdma_hal_stop(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+void gdma_hal_append(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+void gdma_hal_reset(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+void gdma_hal_set_priority(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t priority);
+
+void gdma_hal_connect_peri(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, gdma_trigger_peripheral_t periph, int periph_sub_id);
+
+void gdma_hal_disconnect_peri(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+void gdma_hal_enable_burst(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_data_burst, bool en_desc_burst);
+
+void gdma_hal_set_ext_mem_align(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint8_t align);
+
+void gdma_hal_set_strategy(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_owner_check, bool en_desc_write_back);
+
+void gdma_hal_enable_intr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask, bool en_or_dis);
+
+void gdma_hal_clear_intr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask);
+
+uint32_t gdma_hal_get_intr_status_reg(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+uint32_t gdma_hal_read_intr_status(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+uint32_t gdma_hal_get_eof_desc_addr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
 
 #ifdef __cplusplus
 }

components/hal/include/hal/gdma_hal_ahb.h

@@ -0,0 +1,49 @@
+/*
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "hal/gdma_hal.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+void gdma_ahb_hal_start_with_desc(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, intptr_t desc_base_addr);
+
+void gdma_ahb_hal_stop(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+void gdma_ahb_hal_append(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+void gdma_ahb_hal_reset(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+void gdma_ahb_hal_set_priority(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t priority);
+
+void gdma_ahb_hal_connect_peri(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, gdma_trigger_peripheral_t periph, int periph_sub_id);
+
+void gdma_ahb_hal_disconnect_peri(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+void gdma_ahb_hal_enable_burst(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_data_burst, bool en_desc_burst);
+
+void gdma_ahb_hal_set_ext_mem_align(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint8_t align);
+
+void gdma_ahb_hal_set_strategy(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, bool en_owner_check, bool en_desc_write_back);
+
+void gdma_ahb_hal_enable_intr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask, bool en_or_dis);
+
+void gdma_ahb_hal_clear_intr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir, uint32_t intr_event_mask);
+
+uint32_t gdma_ahb_hal_read_intr_status(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+uint32_t gdma_ahb_hal_get_intr_status_reg(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+uint32_t gdma_ahb_hal_get_eof_desc_addr(gdma_hal_context_t *hal, int chan_id, gdma_channel_direction_t dir);
+
+void gdma_ahb_hal_init(gdma_hal_context_t *hal, const gdma_hal_config_t *config);
+
+#ifdef __cplusplus
+}
+#endif

components/hal/include/hal/gdma_types.h

@@ -13,7 +13,6 @@ extern "C" {
 /**
  * @brief Enumeration of peripherals which have the DMA capability
  * @note Some peripheral might not be available on certain chip, please refer to `soc_caps.h` for detail.
- *
  */
 typedef enum {
     GDMA_TRIG_PERIPH_M2M,  /*!< GDMA trigger peripheral: M2M */
@@ -32,7 +31,6 @@ typedef enum {
 
 /**
  * @brief Enumeration of GDMA channel direction
- *
  */
 typedef enum {
     GDMA_CHANNEL_DIRECTION_TX, /*!< GDMA channel direction: TX */

components/hal/spi_hal.c

@@ -13,7 +13,7 @@
 #include "soc/clk_tree_defs.h"
 
 //This GDMA related part will be introduced by GDMA dedicated APIs in the future. Here we temporarily use macros.
-#if SOC_GDMA_SUPPORTED
+#if SOC_AHB_GDMA_VERSION == 1
 #include "soc/gdma_struct.h"
 #include "hal/gdma_ll.h"
 

components/hal/spi_hal_iram.c

@@ -12,7 +12,7 @@
 #include "soc/soc_caps.h"
 
 //This GDMA related part will be introduced by GDMA dedicated APIs in the future. Here we temporarily use macros.
-#if SOC_GDMA_SUPPORTED
+#if SOC_AHB_GDMA_VERSION == 1
 #include "soc/gdma_struct.h"
 #include "hal/gdma_ll.h"
 

components/hal/spi_slave_hal.c

@@ -3,7 +3,7 @@
 #include "soc/soc_caps.h"
 
 //This GDMA related part will be introduced by GDMA dedicated APIs in the future. Here we temporarily use macros.
-#if SOC_GDMA_SUPPORTED
+#if SOC_AHB_GDMA_VERSION == 1
 #include "soc/gdma_struct.h"
 #include "hal/gdma_ll.h"
 

components/hal/spi_slave_hal_iram.c

@@ -3,7 +3,7 @@
 #include "soc/soc_caps.h"
 
 //This GDMA related part will be introduced by GDMA dedicated APIs in the future. Here we temporarily use macros.
-#if SOC_GDMA_SUPPORTED
+#if SOC_AHB_GDMA_VERSION == 1
 #include "soc/gdma_struct.h"
 #include "hal/gdma_ll.h"
 

components/hal/spi_slave_hd_hal.c

@@ -18,7 +18,7 @@
 #include "hal/assert.h"
 
 //This GDMA related part will be introduced by GDMA dedicated APIs in the future. Here we temporarily use macros.
-#if SOC_GDMA_SUPPORTED
+#if SOC_AHB_GDMA_VERSION == 1
 #include "soc/gdma_struct.h"
 #include "hal/gdma_ll.h"
 #define spi_dma_ll_tx_restart(dev, chan)                           gdma_ll_tx_restart(&GDMA, chan)