diff --git a/components/esp_psram/Kconfig.spiram.common b/components/esp_psram/Kconfig.spiram.common index ea16849a52..2d6c36831c 100644 --- a/components/esp_psram/Kconfig.spiram.common +++ b/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 diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 81f1452ddc..c7e74f66d4 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -83,11 +83,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 ` 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 ` 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: diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 363d57fbc8..69629a1a24 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -42,6 +42,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 ` 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 diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index d6a5b24f96..d7fd7592a6 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/docs/zh_CN/api-guides/external-ram.rst @@ -83,11 +83,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:`堆内存分配器 `。 +启用上述选项后，片外 RAM 被映射到数据虚拟地址空间，并将这个区域添加到携带 ``MALLOC_CAP_SPIRAM`` 标志的 :doc:`堆内存分配器 `。由于该内存区域同时带有 ``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: diff --git a/docs/zh_CN/api-reference/system/mem_alloc.rst b/docs/zh_CN/api-reference/system/mem_alloc.rst index ea3709de69..e740534634 100644 --- a/docs/zh_CN/api-reference/system/mem_alloc.rst +++ b/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 ` 被添加到基于能力的堆分配器后，``heap_caps_malloc(size, MALLOC_CAP_DEFAULT)`` 可能返回片外 RAM，而 ``malloc()`` 是否优先或仅使用内部 RAM 则取决于具体配置。 + ``malloc()`` 使用基于属性的分配系统，所以使用 :cpp:func:`heap_caps_malloc` 分配的内存可以通过调用标准的 ``free()`` 函数释放。 可用堆空间