Merge branch 'fix/issue-18391-psram-default-docs' into 'master'

docs: clarify PSRAM default allocation behavior

See merge request espressif/esp-idf!46985

components/esp_psram/Kconfig.spiram.common

@@ -71,7 +71,16 @@ choice SPIRAM_USE
     config SPIRAM_USE_MEMMAP
         bool "Integrate RAM into memory map"
     config SPIRAM_USE_CAPS_ALLOC
-        bool "Make RAM allocatable using heap_caps_malloc(..., MALLOC_CAP_SPIRAM)"
+        bool "Add RAM to heap_caps allocator (malloc() stays internal by default)"
+        help
+            Add SPI RAM to the capability allocator.
+
+            Use heap_caps_malloc(..., MALLOC_CAP_SPIRAM) to explicitly allocate
+            from SPI RAM. SPI RAM may also be returned by
+            heap_caps_malloc(..., MALLOC_CAP_DEFAULT), since this heap is also
+            registered with MALLOC_CAP_DEFAULT.
+
+            Standard malloc() does not allocate from SPI RAM by default in this mode.
     config SPIRAM_USE_MALLOC
         bool "Make RAM allocatable using malloc() as well"
         select FREERTOS_SUPPORT_STATIC_ALLOCATION

docs/en/api-guides/external-ram.rst

@@ -87,11 +87,13 @@ It is recommended to access the PSRAM by ESP-IDF heap memory allocator (see next
 Add External RAM to the Capability Allocator
 --------------------------------------------
 
-Select this option by choosing ``Make RAM allocatable using heap_caps_malloc(..., MALLOC_CAP_SPIRAM)`` from :ref:`CONFIG_SPIRAM_USE`.
+Select this option by choosing ``Add RAM to heap_caps allocator (malloc() stays internal by default)`` from :ref:`CONFIG_SPIRAM_USE`.
 
-When enabled, memory is mapped to data virtual address space and also added to the :doc:`capabilities-based heap memory allocator </api-reference/system/mem_alloc>` using ``MALLOC_CAP_SPIRAM``.
+When enabled, memory is mapped to data virtual address space and also added to the :doc:`capabilities-based heap memory allocator </api-reference/system/mem_alloc>` using ``MALLOC_CAP_SPIRAM``. Since this memory is also tagged with ``MALLOC_CAP_DEFAULT``, calls such as ``heap_caps_malloc(size, MALLOC_CAP_DEFAULT)`` can still return PSRAM pointers.
 
-To allocate memory from external RAM, a program should call ``heap_caps_malloc(size, MALLOC_CAP_SPIRAM)``. After use, this memory can be freed by calling the normal ``free()`` function.
+To explicitly allocate memory from external RAM, a program should call ``heap_caps_malloc(size, MALLOC_CAP_SPIRAM)``. After use, this memory can be freed by calling the normal ``free()`` function.
+
+In this mode, standard ``malloc()`` does not allocate from external RAM by default because it uses a separate default allocation policy.
 
 .. _external_ram_config_malloc:
 

docs/en/api-reference/system/mem_alloc.rst

@@ -45,6 +45,12 @@ All DRAM memory is single-byte accessible, thus all DRAM heaps possess the ``MAL
 
 When calling ``malloc()``, the ESP-IDF ``malloc()`` internally calls ``heap_caps_malloc_default(size)``. This will allocate memory with the capability ``MALLOC_CAP_DEFAULT``, which is byte-addressable.
 
+``MALLOC_CAP_DEFAULT`` describes the memory capability, not the exact allocation policy. In particular, ``heap_caps_malloc(size, MALLOC_CAP_DEFAULT)`` is not required to follow the same placement strategy as ``malloc()``.
+
+.. only:: SOC_SPIRAM_SUPPORTED
+
+    For example, when :doc:`external RAM </api-guides/external-ram>` is added to the capability allocator, ``heap_caps_malloc(size, MALLOC_CAP_DEFAULT)`` may return external RAM, while ``malloc()`` may still prefer or require internal RAM depending on the configuration.
+
 Because ``malloc()`` uses the capabilities-based allocation system, memory allocated using :cpp:func:`heap_caps_malloc` can be freed by calling the standard ``free()`` function.
 
 Available Heap

docs/zh_CN/api-guides/external-ram.rst

@@ -87,11 +87,13 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该
 添加片外 RAM 到堆内存分配器
 ----------------------------
 
-在 :ref:`CONFIG_SPIRAM_USE` 中选择 ``Make RAM allocatable using heap_caps_malloc(..., MALLOC_CAP_SPIRAM)`` 选项。
+在 :ref:`CONFIG_SPIRAM_USE` 中选择 ``Add RAM to heap_caps allocator (malloc() stays internal by default)`` 选项。
 
-启用上述选项后，片外 RAM 被映射到数据虚拟地址空间，并将这个区域添加到携带 ``MALLOC_CAP_SPIRAM`` 标志的 :doc:`堆内存分配器 </api-reference/system/mem_alloc>`。
+启用上述选项后，片外 RAM 被映射到数据虚拟地址空间，并将这个区域添加到携带 ``MALLOC_CAP_SPIRAM`` 标志的 :doc:`堆内存分配器 </api-reference/system/mem_alloc>`。由于该内存区域同时带有 ``MALLOC_CAP_DEFAULT`` 标志，因此 ``heap_caps_malloc(size, MALLOC_CAP_DEFAULT)`` 这类调用仍然可能返回 PSRAM 指针。
 
-程序如果想从片外存储器分配存储空间，则需要调用 ``heap_caps_malloc(size, MALLOC_CAP_SPIRAM)``，之后可以调用 ``free()`` 函数释放这部分存储空间。
+如果程序想显式地从片外存储器分配存储空间，则需要调用 ``heap_caps_malloc(size, MALLOC_CAP_SPIRAM)``，之后可以调用 ``free()`` 函数释放这部分存储空间。
+
+在该模式下，标准 ``malloc()`` 默认不会从外部 RAM 分配内存，因为它使用的是单独的默认分配策略。
 
 .. _external_ram_config_malloc:
 

docs/zh_CN/api-reference/system/mem_alloc.rst

@@ -42,6 +42,12 @@ ESP-IDF 应用程序使用常见的计算机架构模式：由程序控制流动
 
 调用 ``malloc()`` 时，ESP-IDF ``malloc()`` 内部调用 ``heap_caps_malloc_default(size)``，使用属性 ``MALLOC_CAP_DEFAULT`` 分配内存。该属性可实现字节寻址功能，即存储空间的最小编址单位为字节。
 
+``MALLOC_CAP_DEFAULT`` 描述的是内存能力，而不是精确的分配策略。特别是，``heap_caps_malloc(size, MALLOC_CAP_DEFAULT)`` 不一定遵循与 ``malloc()`` 相同的放置策略。
+
+.. only:: SOC_SPIRAM_SUPPORTED
+
+    例如，当 :doc:`片外 RAM </api-guides/external-ram>` 被添加到基于能力的堆分配器后，``heap_caps_malloc(size, MALLOC_CAP_DEFAULT)`` 可能返回片外 RAM，而 ``malloc()`` 是否优先或仅使用内部 RAM 则取决于具体配置。
+
 ``malloc()`` 使用基于属性的分配系统，所以使用 :cpp:func:`heap_caps_malloc` 分配的内存可以通过调用标准的 ``free()`` 函数释放。
 
 可用堆空间