Support for external RAM

[中文]

Introduction

ESP32 has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so ESP32 has the ability to also use up to 4 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM.

Hardware

ESP32 supports SPI PSRAM connected in parallel with the SPI flash chip. While ESP32 is capable of supporting several types of RAM chips, ESP-IDF currently only supports Espressif branded PSRAM chips (ESP-PSRAM32, ESP-PSRAM64, etc).

Note

Some PSRAM chips are 1.8 V devices and some are 3.3 V. The working voltage of the PSRAM chip must match the working voltage of the flash component. Consult the datasheet for your PSRAM chip and ESP32 device to find out the working voltages. For a 1.8 V PSRAM chip, make sure to either set the MTDI pin to a high signal level on bootup, or program ESP32 eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip.

Note

Espressif produces both modules and system-in-package chips that integrate compatible PSRAM and flash and are ready to mount on a product PCB. Consult the Espressif website for more information.

For specific details about connecting the SoC or module pins to an external PSRAM chip, consult the SoC or module datasheet.

Configuring External RAM

ESP-IDF fully supports the use of external memory in applications. Once the external RAM is initialized at startup, ESP-IDF can be configured to handle it in several ways:

Integrate RAM into the ESP32 memory map

Select this option by choosing “Integrate RAM into memory map” from CONFIG_SPIRAM_USE.

This is the most basic option for external SPI RAM integration. Most likely, you will need another, more advanced option.

During the ESP-IDF startup, external RAM is mapped into the data address space, starting at address 0x3F800000 (byte-accessible). The length of this region is the same as the SPI RAM size (up to the limit of 4 MB).

Applications can manually place data in external memory by creating pointers to this region. So if an application uses external memory, it is responsible for all management of the external SPI RAM: coordinating buffer usage, preventing corruption, etc.

Add external RAM to the capability allocator

Select this option by choosing “Make RAM allocatable using heap_caps_malloc(…, MALLOC_CAP_SPIRAM)” from CONFIG_SPIRAM_USE.

When enabled, memory is mapped to address 0x3F800000 and also added to the capabilities-based heap memory allocator using MALLOC_CAP_SPIRAM.

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.

Provide external RAM via malloc()

Select this option by choosing “Make RAM allocatable using malloc() as well” from CONFIG_SPIRAM_USE. This is the default option.

In this case, memory is added to the capability allocator as described for the previous option. However, it is also added to the pool of RAM that can be returned by the standard malloc() function.

This allows any application to use the external RAM without having to rewrite the code to use heap_caps_malloc(..., MALLOC_CAP_SPIRAM).

An additional configuration item, CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL, can be used to set the size threshold when a single allocation should prefer external memory:

  • When allocating a size less than the threshold, the allocator will try internal memory first.

  • When allocating a size equal to or larger than the threshold, the allocator will try external memory first.

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 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 MALLOC_CAP_DMA and MALLOC_CAP_INTERNAL flags can be used to allocate memory from this pool.

Allow .bss segment placed in external memory

Enable this option by checking CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY. This configuration setting is independent of the other three.

If enabled, a region of the address space starting from 0x3F800000 will be used to store zero-initialized data (BSS segment) from the lwIP, net80211, libpp, and bluedroid ESP-IDF libraries.

Additional data can be moved from the internal BSS segment to external RAM by applying the macro EXT_RAM_ATTR to any static declaration (which is not initialized to a non-zero value).

It is also possible to place the BSS section of a component or a library to external RAM using linker fragment scheme extram_bss.

This option reduces the internal static memory used by the BSS segment.

Remaining external RAM can also be added to the capability heap allocator using the method shown above.

Restrictions

External RAM use has the following restrictions:

  • When flash cache is disabled (for example, if the flash is being written to), the external RAM also becomes inaccessible; any reads from or writes to it will lead to an illegal cache access exception. This is also the reason why ESP-IDF does not by default allocate any task stacks in external RAM (see below).

  • External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Therefore when External RAM is enabled, any buffers that will be used in combination with DMA must be allocated using heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL) and can be freed using a standard free() call.

  • External RAM uses the same cache region as the external flash. This means that frequently accessed variables in external RAM can be read and modified almost as quickly as in internal ram. However, when accessing large chunks of data (>32 KB), the cache can be insufficient, and speeds will fall back to the access speed of the external RAM. Moreover, accessing large chunks of data can “push out” cached flash, possibly making the execution of code slower afterwards.

  • In general, external RAM cannot be used as task stack memory. Due to this, xTaskCreate() and similar functions will always allocate internal memory for stack and task TCBs, and functions such as xTaskCreateStatic() will check if the buffers passed are internal.

The option CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY can be used to place task stacks into external memory. In these cases xTaskCreateStatic() must be used to specify a task stack buffer allocated from external memory, otherwise task stacks will still be allocated from internal memory.

Failure to initialize

By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item CONFIG_SPIRAM_IGNORE_NOTFOUND.

If CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY is enabled, the option to ignore failure is not available as the linker will have assigned symbols to external memory addresses at link time.

  • Regarding stacks in PSRAM: For tasks not calling on code in ROM in any way, directly or indirectly, the menuconfig option CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY will eliminate the check in xTaskCreateStatic, allowing a task’s stack to be in external RAM. Using this is not advised, however.

  • When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by CONFIG_SPIRAM_OCCUPY_SPI_HOST.

Chip revisions

There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues are documented in the ESP32 ECO document. In particular, ESP-IDF handles the bugs mentioned in the following ways:

ESP32 rev v0

ESP-IDF has no workaround for the bugs in this revision of silicon, and it cannot be used to map external PSRAM into ESP32’s main memory map.

ESP32 rev v1

The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (ESP32 ECO 3.2). As a workaround, the GCC compiler received the flag -mfix-esp32-psram-cache-issue to filter these sequences and only output the code that can safely be executed. Enable this flag by checking CONFIG_SPIRAM_CACHE_WORKAROUND.

Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following:

  • Avoids using some ROM functions

  • Allocates static memory for the WiFi stack

ESP32 rev v3

ESP32 revision 3 (“ECO V3”) fixes the PSRAM cache issue found in rev. 1. When CONFIG_ESP32_REV_MIN option is set to rev. 3, compiler workarounds related to PSRAM will be disabled. For more information about ESP32 ECO V3, see ESP32 ECO V3 User Guide.

Provide feedback about this document