From f992f12bd8bfbd9fdc44fbe6e1f1e19760f042fb Mon Sep 17 00:00:00 2001
From: wuzhenghui <wuzhenghui@espressif.com>
Date: Thu, 27 Aug 2026 19:50:26 +0800
Subject: [PATCH] fix(heap): revert DMA pool MALLOC_CAP_DEFAULT caps

---
 components/esp_psram/Kconfig.spiram.common    |  2 +-
 components/esp_psram/esp_psram.c              |  2 +-
 .../include/esp_private/esp_psram_extram.h    |  7 +----
 .../test_apps/heap_tests/main/test_malloc.c   | 28 +++++++++++++++++--
 docs/en/api-guides/external-ram.rst           |  9 +-----
 docs/zh_CN/api-guides/external-ram.rst        |  9 +-----
 6 files changed, 31 insertions(+), 26 deletions(-)

diff --git a/components/esp_psram/Kconfig.spiram.common b/components/esp_psram/Kconfig.spiram.common
index 0191705e73e..2832f1e6778 100644
--- a/components/esp_psram/Kconfig.spiram.common
+++ b/components/esp_psram/Kconfig.spiram.common
@@ -80,7 +80,7 @@ config SPIRAM_MALLOC_RESERVE_INTERNAL
         that the internal memory is entirely filled up. This causes allocations that are specifically done in
         internal memory, for example the stack for new tasks or memory to service DMA or have memory that's
         also available when SPI cache is down, to fail. This option reserves a pool specifically for requests
-        like that;  a normal malloc() can fall back to the pool only after all other internal are exhausted.
+        like that; the memory in this pool is not given out when a normal malloc() is called.
 
         Set this to 0 to disable this feature.
 
diff --git a/components/esp_psram/esp_psram.c b/components/esp_psram/esp_psram.c
index 44d61c6ccdf..24f31016d83 100644
--- a/components/esp_psram/esp_psram.c
+++ b/components/esp_psram/esp_psram.c
@@ -366,7 +366,7 @@ esp_err_t esp_psram_extram_reserve_dma_pool(size_t size)
             return ESP_ERR_NO_MEM;
         }
 
-        uint32_t caps[] = {0, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL, MALLOC_CAP_DEFAULT | MALLOC_CAP_8BIT | MALLOC_CAP_32BIT};
+        uint32_t caps[] = {0, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL, MALLOC_CAP_8BIT | MALLOC_CAP_32BIT};
         esp_err_t e = heap_caps_add_region_with_caps(caps, (intptr_t)dma_heap, (intptr_t)dma_heap + next_size - 1);
         if (e != ESP_OK) {
             return e;
diff --git a/components/esp_psram/include/esp_private/esp_psram_extram.h b/components/esp_psram/include/esp_private/esp_psram_extram.h
index b925a3b0edd..5cd7e52a153 100644
--- a/components/esp_psram/include/esp_private/esp_psram_extram.h
+++ b/components/esp_psram/include/esp_private/esp_psram_extram.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -37,11 +37,6 @@ esp_err_t esp_psram_extram_add_to_heap_allocator(void);
 /**
  * @brief Reserve a pool of internal memory for specific DMA/internal allocations
  *
- * Carves out @p size bytes from the regular internal heaps and registers the
- * region as separate heap pool with new priority-based caps: medium priority for
- * MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL, and low priority for MALLOC_CAP_DEFAULT.
- * malloc() uses the pool only after other internal heaps are exhausted.
- *
  * @param size Size of reserved pool in bytes
  *
  * @return
diff --git a/components/heap/test_apps/heap_tests/main/test_malloc.c b/components/heap/test_apps/heap_tests/main/test_malloc.c
index e78cdc1d144..38b4ea18a0c 100644
--- a/components/heap/test_apps/heap_tests/main/test_malloc.c
+++ b/components/heap/test_apps/heap_tests/main/test_malloc.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Unlicense OR CC0-1.0
  */
@@ -64,6 +64,30 @@ TEST_CASE("Malloc/overwrite, then free all available DRAM", "[heap]")
     TEST_ASSERT(m1==m2);
 }
 
+#if CONFIG_SPIRAM_USE_MALLOC
+
+#if (CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL > 1024)
+TEST_CASE("Check if reserved DMA pool still can allocate even when malloc()'ed memory is exhausted", "[heap]")
+{
+    char** dmaMem=malloc(sizeof(char*)*512);
+    assert(dmaMem);
+    int m=tryAllocMem();
+    int i=0;
+    for (i=0; i<512; i++) {
+        dmaMem[i]=heap_caps_malloc(1024, MALLOC_CAP_DMA);
+        if (dmaMem[i]==NULL) break;
+    }
+    for (int j=0; j<i; j++) free(dmaMem[j]);
+    free(dmaMem);
+    tryAllocMemFree();
+    printf("Could allocate %dK of DMA memory after allocating all of %dK of normal memory.\n", i, m);
+    TEST_ASSERT(i);
+}
+#endif
+
+#endif
+
+
 /* As you see, we are desperately trying to outsmart the compiler, so that it
  * doesn't warn about oversized allocations in the next two unit tests.
  * To be removed when we switch to GCC 8.2 and add
@@ -152,7 +176,7 @@ TEST_CASE("test get allocated size", "[heap]")
         const size_t aligned_size = (alloc_sizes[i] + 3) & ~3;
         const size_t real_size = heap_caps_get_allocated_size(ptr_array[i]);
         printf("initial size: %d, requested size : %d, allocated size: %d\n", alloc_sizes[i], aligned_size, real_size);
-        TEST_ASSERT(aligned_size <= real_size);
+        TEST_ASSERT_EQUAL(aligned_size, real_size);
 
         heap_caps_free(ptr_array[i]);
     }
diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst
index fb74fd77021..572c64f1819 100644
--- a/docs/en/api-guides/external-ram.rst
+++ b/docs/en/api-guides/external-ram.rst
@@ -97,14 +97,7 @@ An additional configuration item, :ref:`CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL`, ca
 
 If a suitable block of preferred internal/external memory is not available, the allocator will try the other type of memory.
 
-Because some buffers can only be allocated in internal memory, a second configuration item :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` reserves a pool of internal DMA-capable memory at startup (in ``main_task``, after PSRAM is initialized). The pool is malloc from the regular internal heaps and re-registered as separate heap pool.
-
-The reserved pool uses the heap capability priority mechanism:
-
-- **Medium priority** — ``MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL``: explicit ``heap_caps_malloc()`` requests with these flags are preferentially served from this pool.
-- **Low priority** — ``MALLOC_CAP_DEFAULT``: ``malloc()`` may use the pool only after other internal heaps with higher-priority ``MALLOC_CAP_DEFAULT`` are exhausted.
-
-Therefore, under normal conditions ``malloc()`` does not allocate from this pool, but it can fall back to it as a last resort before allocation fails entirely.
+Because some buffers can only be allocated in internal memory, a second configuration item :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` defines a pool of internal memory which is reserved for *only* explicitly internal allocations (such as memory for DMA use). Regular ``malloc()`` will not allocate from this pool. The :ref:`MALLOC_CAP_DMA <dma-capable-memory>` and ``MALLOC_CAP_INTERNAL`` flags can be used to allocate memory from this pool.
 
 .. _external_ram_config_bss:
 
diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst
index 584cd714a39..c4d96037289 100644
--- a/docs/zh_CN/api-guides/external-ram.rst
+++ b/docs/zh_CN/api-guides/external-ram.rst
@@ -97,14 +97,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该
 
 如果优先考虑的内部或外部存储器中没有可用的存储块，分配程序则会选择其他类型存储。
 
-由于有些内存缓冲器仅可在内部存储器中分配，因此需要使用第二个配置项 :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` 在启动阶段（PSRAM 初始化完成后，于 ``main_task`` 中）预留一块内部 DMA 可用内存池。该内存从常规内部堆中分配出，并重新注册为独立的内存池。
-
-预留池通过堆能力优先级机制管理：
-
-- **中优先级** — ``MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL``：显式使用这些标志的 ``heap_caps_malloc()`` 请求会优先从此池分配。
-- **低优先级** — ``MALLOC_CAP_DEFAULT``：仅当其他具有更高优先级 ``MALLOC_CAP_DEFAULT`` 的内部堆耗尽后，``malloc()`` 才会回退使用此池。
-
-因此，在正常情况下 ``malloc()`` 不会从该池分配；仅当其他内部内存耗尽后，``malloc()`` 才会将其作为最后的回退来源以避免分配完全失败。
+由于有些内存缓冲器仅可在内部存储器中分配，因此需要使用第二个配置项 :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` 定义一个内部内存池，仅限显式的内部存储器分配使用（例如用于 DMA 的存储器）。常规 ``malloc()`` 将不会从该池中分配，但可以使用 :ref:`MALLOC_CAP_DMA <dma-capable-memory>` 和 ``MALLOC_CAP_INTERNAL`` 标志从该池中分配存储器。
 
 .. _external_ram_config_bss: