Merge branch 'feat/support_lp_dma_on_s31' into 'master'

feat(gdma): support lp ahb dma on esp32s31

Closes IDF-14761

See merge request espressif/esp-idf!45229

Author: suda-morris

components/esp_driver_dma/include/esp_async_memcpy.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -97,6 +97,21 @@ esp_err_t esp_async_memcpy_install_gdma_ahb(const async_memcpy_config_t *config,
 esp_err_t esp_async_memcpy_install_gdma_axi(const async_memcpy_config_t *config, async_memcpy_handle_t *mcp);
 #endif // SOC_HAS(AXI_GDMA)
 
+#if SOC_HAS(LP_AHB_GDMA)
+/**
+ * @brief Install async memcpy driver, with LP AHB-GDMA as the backend
+ *
+ * @param[in] config Configuration of async memcpy
+ * @param[out] mcp Returned driver handle
+ * @return
+ *      - ESP_OK: Install async memcpy driver successfully
+ *      - ESP_ERR_INVALID_ARG: Install async memcpy driver failed because of invalid argument
+ *      - ESP_ERR_NO_MEM: Install async memcpy driver failed because out of memory
+ *      - ESP_FAIL: Install async memcpy driver failed because of other error
+ */
+esp_err_t esp_async_memcpy_install_gdma_lp_ahb(const async_memcpy_config_t *config, async_memcpy_handle_t *mcp);
+#endif // SOC_HAS(LP_AHB_GDMA)
+
 #if SOC_CP_DMA_SUPPORTED
 /**
  * @brief Install async memcpy driver, with CPDMA as the backend

components/esp_driver_dma/include/esp_private/gdma.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -143,6 +143,26 @@ esp_err_t gdma_new_ahb_channel(const gdma_channel_alloc_config_t *config, gdma_c
  */
 esp_err_t gdma_new_axi_channel(const gdma_channel_alloc_config_t *config, gdma_channel_handle_t *ret_tx_chan, gdma_channel_handle_t *ret_rx_chan);
 
+/**
+ * @brief Create LP-AHB-GDMA channel(s)
+ * @note This API won't install interrupt service for the allocated channel.
+ *       If interrupt service is needed, user has to register GDMA event callback by `gdma_register_tx_event_callbacks` or `gdma_register_rx_event_callbacks`.
+ * @note To allocate both TX and RX channels in a pair, pass non-NULL pointers for both ret_tx_chan and ret_rx_chan.
+ *       To allocate only one direction, pass NULL for the unwanted direction.
+ * @note Allocation is atomic: if any channel fails to allocate, all partially allocated resources are cleaned up automatically.
+ *       Either all requested channels are successfully allocated, or the function fails with no channels allocated.
+ *
+ * @param[in] config Pointer to a collection of configurations for allocating GDMA channel
+ * @param[out] ret_tx_chan Returned TX channel handle. Pass NULL if TX channel is not needed. Must not be NULL if ret_rx_chan is also NULL.
+ * @param[out] ret_rx_chan Returned RX channel handle. Pass NULL if RX channel is not needed. Must not be NULL if ret_tx_chan is also NULL.
+ * @return
+ *      - ESP_OK: Create DMA channel(s) successfully
+ *      - ESP_ERR_INVALID_ARG: Create DMA channel failed because both ret_tx_chan and ret_rx_chan are NULL
+ *      - ESP_ERR_NO_MEM: Create DMA channel failed because out of memory
+ *      - ESP_FAIL: Create DMA channel failed because of other error
+ */
+esp_err_t gdma_new_lp_ahb_channel(const gdma_channel_alloc_config_t *config, gdma_channel_handle_t *ret_tx_chan, gdma_channel_handle_t *ret_rx_chan);
+
 /**
  * @brief Connect GDMA channel to trigger peripheral
  *

components/esp_driver_dma/src/async_memcpy_gdma.c

@@ -207,6 +207,13 @@ esp_err_t esp_async_memcpy_install_gdma_axi(const async_memcpy_config_t *config,
 }
 #endif // SOC_HAS(AXI_GDMA)
 
+#if SOC_HAS(LP_AHB_GDMA)
+esp_err_t esp_async_memcpy_install_gdma_lp_ahb(const async_memcpy_config_t *config, async_memcpy_handle_t *mcp)
+{
+    return esp_async_memcpy_install_gdma_template(config, mcp, gdma_new_lp_ahb_channel, SOC_GDMA_BUS_LP);
+}
+#endif // SOC_HAS(LP_AHB_GDMA)
+
 #if SOC_HAS(AHB_GDMA)
 /// default installation falls back to use the AHB GDMA
 esp_err_t esp_async_memcpy_install(const async_memcpy_config_t *config, async_memcpy_handle_t *asmcp)
@@ -320,6 +327,14 @@ static esp_err_t mcp_gdma_memcpy(async_memcpy_context_t *ctx, void *dst, void *s
         dma_link_item_alignment = GDMA_LL_AXI_DESC_ALIGNMENT;
     }
 #endif // SOC_HAS(AXI_GDMA)
+#if SOC_HAS(LP_AHB_GDMA)
+    if (mcp_gdma->gdma_bus_id == SOC_GDMA_BUS_LP) {
+#if !GDMA_LL_GET(LP_AHB_PSRAM_CAPABLE)
+        ESP_RETURN_ON_FALSE(esp_ptr_internal(src) && esp_ptr_internal(dst), ESP_ERR_INVALID_ARG, TAG, "LP AHB GDMA can only access SRAM");
+#endif // !GDMA_LL_GET(LP_AHB_PSRAM_CAPABLE)
+        dma_link_item_alignment = GDMA_LL_AHB_DESC_ALIGNMENT;
+    }
+#endif // SOC_HAS(LP_AHB_GDMA)
     // alignment check
     ESP_RETURN_ON_FALSE(check_buffer_alignment(mcp_gdma, src, dst, n), ESP_ERR_INVALID_ARG, TAG, "address|size not aligned: %p -> %p, sz=%zu", src, dst, n);
 

components/esp_driver_dma/src/gdma.c

@@ -264,6 +264,21 @@ esp_err_t gdma_new_axi_channel(const gdma_channel_alloc_config_t *config, gdma_c
 }
 #endif // SOC_HAS(AXI_GDMA)
 
+#if SOC_HAS(LP_AHB_GDMA)
+esp_err_t gdma_new_lp_ahb_channel(const gdma_channel_alloc_config_t *config, gdma_channel_handle_t *ret_tx_chan, gdma_channel_handle_t *ret_rx_chan)
+{
+    gdma_channel_search_info_t search_info = {
+        .bus_id = SOC_GDMA_BUS_LP,
+        .start_group_id = GDMA_LL_LP_AHB_GROUP_START_ID,
+        .end_group_id = GDMA_LL_LP_AHB_GROUP_START_ID + GDMA_LL_LP_AHB_NUM_GROUPS,
+        .pairs_per_group = GDMA_LL_LP_AHB_PAIRS_PER_GROUP,
+        .m2m_capable_mask = GDMA_LL_LP_AHB_M2M_CAPABLE_PAIR_MASK,
+        .hal_init = gdma_lp_ahb_hal_init,
+    };
+    return do_allocate_gdma_channel(&search_info, config, ret_tx_chan, ret_rx_chan);
+}
+#endif // SOC_HAS(LP_AHB_GDMA)
+
 esp_err_t gdma_del_channel(gdma_channel_handle_t dma_chan)
 {
     if (!dma_chan) {
@@ -400,7 +415,7 @@ esp_err_t gdma_config_transfer(gdma_channel_handle_t dma_chan, const gdma_transf
         // burst size must be power of 2
         ESP_RETURN_ON_FALSE((max_data_burst_size & (max_data_burst_size - 1)) == 0, ESP_ERR_INVALID_ARG,
                             TAG, "invalid max_data_burst_size: %"PRIu32, max_data_burst_size);
-#if GDMA_LL_GET(AHB_PSRAM_CAPABLE) || GDMA_LL_GET(AXI_PSRAM_CAPABLE)
+#if GDMA_LL_GET(AHB_PSRAM_CAPABLE) || GDMA_LL_GET(AXI_PSRAM_CAPABLE) || GDMA_LL_GET(LP_AHB_PSRAM_CAPABLE)
         if (config->access_ext_mem) {
             ESP_RETURN_ON_FALSE(max_data_burst_size <= GDMA_LL_MAX_BURST_SIZE_PSRAM, ESP_ERR_INVALID_ARG,
                                 TAG, "max_data_burst_size must not exceed %d when accessing external memory", GDMA_LL_MAX_BURST_SIZE_PSRAM);

components/esp_driver_dma/test_apps/dma/main/test_async_memcpy.c

@@ -141,6 +141,13 @@ TEST_CASE("memory copy the same buffer with different content", "[async mcp]")
     test_memory_copy_with_same_buffer(driver, &config);
     TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
 #endif // SOC_CP_DMA_SUPPORTED
+
+#if SOC_HAS(LP_AHB_GDMA)
+    printf("Testing memcpy by LP AHB GDMA\r\n");
+    TEST_ESP_OK(esp_async_memcpy_install_gdma_lp_ahb(&config, &driver));
+    test_memory_copy_with_same_buffer(driver, &config);
+    TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
+#endif // SOC_HAS(LP_AHB_GDMA)
 }
 
 static bool test_async_memcpy_cb_v1(async_memcpy_handle_t mcp_hdl, async_memcpy_event_t *event, void *cb_args)
@@ -206,6 +213,13 @@ TEST_CASE("memory copy by DMA (blocking)", "[async mcp]")
     test_memory_copy_blocking(driver);
     TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
 #endif // SOC_CP_DMA_SUPPORTED
+
+#if SOC_HAS(LP_AHB_GDMA)
+    printf("Testing memcpy by LP AHB GDMA\r\n");
+    TEST_ESP_OK(esp_async_memcpy_install_gdma_lp_ahb(&config, &driver));
+    test_memory_copy_blocking(driver);
+    TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
+#endif // SOC_HAS(LP_AHB_GDMA)
 }
 
 [[maybe_unused]] static void test_memcpy_with_dest_addr_unaligned(async_memcpy_handle_t driver, bool src_in_psram, bool dst_in_psram)
@@ -273,6 +287,16 @@ TEST_CASE("memory copy with dest address unaligned", "[async mcp]")
 #endif // GDMA_LL_GET(AXI_PSRAM_CAPABLE) && SOC_HAS(SPIRAM)
     TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
 #endif // SOC_HAS(AXI_GDMA)
+
+#if SOC_HAS(LP_AHB_GDMA) && !CONFIG_GDMA_ENABLE_WEIGHTED_ARBITRATION
+    printf("Testing memcpy by LP AHB GDMA\r\n");
+    TEST_ESP_OK(esp_async_memcpy_install_gdma_lp_ahb(&driver_config, &driver));
+    test_memcpy_with_dest_addr_unaligned(driver, false, false);
+#if GDMA_LL_GET(LP_AHB_PSRAM_CAPABLE) && SOC_HAS(SPIRAM)
+    test_memcpy_with_dest_addr_unaligned(driver, true, true);
+#endif // GDMA_LL_GET(LP_AHB_PSRAM_CAPABLE) && SOC_HAS(SPIRAM)
+    TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
+#endif // SOC_HAS(LP_AHB_GDMA)
 }
 
 #define TEST_ASYNC_MEMCPY_BENCH_COUNTS 16
@@ -362,6 +386,13 @@ TEST_CASE("memory copy performance 40KB: SRAM->SRAM", "[async mcp]")
     test_memcpy_performance(driver, 40 * 1024, false, false);
     TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
 #endif // SOC_CP_DMA_SUPPORTED
+
+#if SOC_HAS(LP_AHB_GDMA)
+    printf("Testing memcpy by LP AHB GDMA\r\n");
+    TEST_ESP_OK(esp_async_memcpy_install_gdma_lp_ahb(&driver_config, &driver));
+    test_memcpy_performance(driver, 40 * 1024, false, false);
+    TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
+#endif // SOC_HAS(LP_AHB_GDMA)
 }
 
 #if SOC_SPIRAM_SUPPORTED
@@ -390,6 +421,15 @@ TEST_CASE("memory copy performance 40KB: PSRAM->PSRAM", "[async mcp]")
     TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
 #endif
 #endif // SOC_HAS(AXI_GDMA)
+
+#if SOC_HAS(LP_AHB_GDMA)
+#if GDMA_LL_GET(LP_AHB_PSRAM_CAPABLE)
+    printf("Testing memcpy by LP AHB GDMA\r\n");
+    TEST_ESP_OK(esp_async_memcpy_install_gdma_lp_ahb(&driver_config, &driver));
+    test_memcpy_performance(driver, 40 * 1024, true, true);
+    TEST_ESP_OK(esp_async_memcpy_uninstall(driver));
+#endif // GDMA_LL_GET(LP_AHB_PSRAM_CAPABLE)
+#endif // SOC_HAS(LP_AHB_GDMA)
 }
 #endif
 

components/esp_driver_dma/test_apps/dma/main/test_gdma.c

@@ -147,6 +147,64 @@ TEST_CASE("GDMA channel allocation", "[GDMA]")
         TEST_ESP_OK(gdma_del_channel(rx_channels[i]));
     }
 #endif // GDMA_LL_AXI_PAIRS_PER_GROUP >= 2
+
+#if SOC_HAS(LP_AHB_GDMA)
+    // install TX channels
+    for (int i = 0; i < GDMA_LL_LP_AHB_PAIRS_PER_GROUP; i++) {
+        TEST_ESP_OK(gdma_new_lp_ahb_channel(&channel_config, &tx_channels[i], NULL));
+    };
+    TEST_ASSERT_EQUAL(ESP_ERR_NOT_FOUND, gdma_new_lp_ahb_channel(&channel_config, &tx_channels[0], NULL));
+
+    // Free interrupts before installing RX interrupts to ensure enough free interrupts
+    for (int i = 0; i < GDMA_LL_LP_AHB_PAIRS_PER_GROUP; i++) {
+        TEST_ESP_OK(gdma_del_channel(tx_channels[i]));
+    }
+
+    // install RX channels
+    for (int i = 0; i < GDMA_LL_LP_AHB_PAIRS_PER_GROUP; i++) {
+        TEST_ESP_OK(gdma_new_lp_ahb_channel(&channel_config, NULL, &rx_channels[i]));
+    }
+    TEST_ASSERT_EQUAL(ESP_ERR_NOT_FOUND, gdma_new_lp_ahb_channel(&channel_config, NULL, &rx_channels[0]));
+
+    for (int i = 0; i < GDMA_LL_LP_AHB_PAIRS_PER_GROUP; i++) {
+        TEST_ESP_OK(gdma_del_channel(rx_channels[i]));
+    }
+#endif // SOC_HAS(LP_AHB_GDMA)
+
+    // install single and paired TX/RX channels
+#if GDMA_LL_LP_AHB_PAIRS_PER_GROUP >= 2
+    // single tx channel
+    TEST_ESP_OK(gdma_new_lp_ahb_channel(&channel_config, &tx_channels[0], NULL));
+
+    // create tx and rx channel pair
+    TEST_ESP_OK(gdma_new_lp_ahb_channel(&channel_config, &tx_channels[1], &rx_channels[1]));
+    // create single rx channel
+    TEST_ESP_OK(gdma_new_lp_ahb_channel(&channel_config, NULL, &rx_channels[0]));
+
+    gdma_trigger_t fake_lp_ahb_trigger1 = {
+        .bus_id = SOC_GDMA_BUS_LP,
+        .instance_id = 0,
+    };
+    gdma_trigger_t fake_lp_ahb_trigger2 = {
+        .bus_id = SOC_GDMA_BUS_LP,
+        .instance_id = 1,
+    };
+    TEST_ESP_OK(gdma_connect(tx_channels[0], fake_lp_ahb_trigger1));
+    // can't connect multiple channels to the same peripheral
+    TEST_ESP_ERR(ESP_ERR_INVALID_STATE, gdma_connect(tx_channels[1], fake_lp_ahb_trigger1));
+    TEST_ESP_OK(gdma_connect(tx_channels[1], fake_lp_ahb_trigger2));
+
+    // but rx and tx can connect to the same peripheral
+    TEST_ESP_OK(gdma_connect(rx_channels[0], fake_lp_ahb_trigger1));
+    TEST_ESP_OK(gdma_connect(rx_channels[1], fake_lp_ahb_trigger2));
+    for (int i = 0; i < 2; i++) {
+        TEST_ESP_OK(gdma_disconnect(tx_channels[i]));
+        TEST_ESP_OK(gdma_disconnect(rx_channels[i]));
+        TEST_ESP_OK(gdma_del_channel(tx_channels[i]));
+        TEST_ESP_OK(gdma_del_channel(rx_channels[i]));
+    }
+#endif // GDMA_LL_LP_AHB_PAIRS_PER_GROUP >= 2
+
 }
 
 static void test_gdma_config_link_list(gdma_channel_handle_t tx_chan, gdma_channel_handle_t rx_chan,
@@ -363,6 +421,15 @@ static void test_gdma_m2m_mode(bool trig_retention_backup)
     TEST_ESP_OK(gdma_del_channel(tx_chan));
     TEST_ESP_OK(gdma_del_channel(rx_chan));
 #endif // SOC_HAS(AXI_GDMA)
+
+#if SOC_HAS(LP_AHB_GDMA)
+    TEST_ESP_OK(gdma_new_lp_ahb_channel(&chan_alloc_config, &tx_chan, &rx_chan));
+
+    test_gdma_m2m_transaction(tx_chan, rx_chan, false, trig_retention_backup);
+
+    TEST_ESP_OK(gdma_del_channel(tx_chan));
+    TEST_ESP_OK(gdma_del_channel(rx_chan));
+#endif // SOC_HAS(LP_AHB_GDMA)
 }
 
 TEST_CASE("GDMA M2M Mode", "[GDMA][M2M]")
@@ -677,5 +744,15 @@ TEST_CASE("GDMA memory copy SRAM->PSRAM->SRAM", "[GDMA][M2M]")
     TEST_ESP_OK(gdma_del_channel(rx_chan));
 #endif
 #endif // SOC_HAS(AXI_GDMA)
+
+#if SOC_HAS(LP_AHB_GDMA)
+    printf("Testing LP-AHB-GDMA memory copy SRAM->PSRAM->SRAM\n");
+    TEST_ESP_OK(gdma_new_lp_ahb_channel(&chan_alloc_config, &tx_chan, &rx_chan));
+
+    test_gdma_memcpy_from_to_psram(tx_chan, rx_chan);
+
+    TEST_ESP_OK(gdma_del_channel(tx_chan));
+    TEST_ESP_OK(gdma_del_channel(rx_chan));
+#endif // SOC_HAS(LP_AHB_GDMA)
 }
 #endif // SOC_SPIRAM_SUPPORTED

components/esp_hal_dma/esp32s31/gdma_periph.c

@@ -47,6 +47,18 @@ const gdma_signal_conn_t gdma_periph_signals = {
                     .tx_irq_id = ETS_AXI_PDMA_OUT_CH2_INTR_SOURCE,
                 }
             }
+        },
+        [2] = {
+            .pairs = {
+                [0] = {
+                    .rx_irq_id = ETS_LP_AHB_PDMA_IN_CH0_INTR_SOURCE,
+                    .tx_irq_id = ETS_LP_AHB_PDMA_OUT_CH0_INTR_SOURCE,
+                },
+                [1] = {
+                    .rx_irq_id = ETS_LP_AHB_PDMA_IN_CH1_INTR_SOURCE,
+                    .tx_irq_id = ETS_LP_AHB_PDMA_OUT_CH1_INTR_SOURCE,
+                }
+            }
         }
     }
 };

components/esp_hal_dma/esp32s31/include/hal/ahb_dma_ll.h

@@ -18,10 +18,11 @@
 extern "C" {
 #endif
 
-#define AHB_DMA_LL_GET_HW(id) (((id) == 0) ? (&AHB_DMA) : NULL)
+#define AHB_DMA_LL_GET_HW(id) (((id) == 0) ? (&AHB_DMA) : (((id) == 2) ? ((ahb_dma_dev_t *)&LP_AHB_DMA) : NULL))
 
 // any "dummy" peripheral ID can be used for M2M mode
 #define AHB_DMA_LL_M2M_FREE_PERIPH_ID_MASK (0x8200)
+#define LP_AHB_DMA_LL_M2M_FREE_PERIPH_ID_MASK (0xFFFC)
 
 ///////////////////////////////////// Common /////////////////////////////////////////
 
@@ -67,6 +68,17 @@ static inline void ahb_dma_ll_set_default_memory_range(ahb_dma_dev_t *dev)
     dev->intr_mem_end_addr.val = 0x53FFFFFF;
 }
 
+/**
+ * @brief Preset valid memory range for LP_AHB-DMA
+ * @param dev DMA register base address
+ */
+static inline void lp_ahb_dma_ll_set_default_memory_range(ahb_dma_dev_t *dev)
+{
+    // LP_AHB-DMA can access LPMEM, SRAM, ROM, MSPI Flash, MSPI PSRAM
+    dev->intr_mem_start_addr.val = 0x2E000000;
+    dev->intr_mem_end_addr.val = 0x53FFFFFF;
+}
+
 ///////////////////////////////////// RX /////////////////////////////////////////
 /**
  * @brief Get DMA RX channel interrupt status word