Memory allocation¶
Overview¶
The ESP32 has multiple types of RAM. Internally, there’s IRAM, DRAM as well as RAM that can be used as both. It’s also possible to connect external SPI flash to the ESP32; it’s memory can be integrated into the ESP32s memory map using the flash cache.
In order to make use of all this memory, esp-idf has a capabilities-based memory allocator. Basically, if you want to have
memory with certain properties (for example, DMA-capable, accessible by a certain PID, or capable of executing code), you
can create an OR-mask of the required capabilities and pass that to pvPortMallocCaps. For instance, the normal malloc
code internally allocates memory with `pvPortMallocCaps(size, MALLOC_CAP_8BIT)`
in order to get data memory that is
byte-addressable.
Because malloc uses this allocation system as well, memory allocated using pvPortMallocCaps can be freed by calling
the standard `free()`
function.
Internally, this allocator is split in two pieces. The allocator in the FreeRTOS directory can allocate memory from tagged regions: a tag is an integer value and every region of free memory has one of these tags. The esp32-specific code initializes these regions with specific tags, and contains the logic to select applicable tags from the capabilities given by the user. While shown in the public API, tags are used in the communication between the two parts and should not be used directly.
Special Uses¶
If a certain memory structure is only addressed in 32-bit units, for example an array of ints or pointers, it can be useful to allocate it with the MALLOC_CAP_32BIT flag. This also allows the allocator to give out IRAM memory; something which it can’t do for a normal malloc() call. This can help to use all the available memory in the ESP32.
API Reference - Heap Allocation¶
Header File¶
Functions¶
-
void
heap_alloc_caps_init
()¶ Initialize the capability-aware heap allocator.
For the ESP32, this is called once in the startup code.
-
void
heap_alloc_enable_nonos_stack_tag
()¶ Enable the memory region where the startup stacks are located for allocation.
On startup, the pro/app CPUs have a certain memory region they use as stack, so we cannot do allocations in the regions these stack frames are. When FreeRTOS is completely started, they do not use that memory anymore and allocation there can be re-enabled.
-
void *
pvPortMallocCaps
(size_t xWantedSize, uint32_t caps)¶ Allocate a chunk of memory which has the given capabilities.
- Return
- A pointer to the memory allocated on success, NULL on failure
- Parameters
xWantedSize
: Size, in bytes, of the amount of memory to allocatecaps
: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory to be returned
-
size_t
xPortGetFreeHeapSizeCaps
(uint32_t caps)¶ Get the total free size of all the regions that have the given capabilities.
This function takes all regions capable of having the given capabilities allocated in them and adds up the free space they have.
- Return
- Amount of free bytes in the regions
- Parameters
caps
: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
-
size_t
xPortGetMinimumEverFreeHeapSizeCaps
(uint32_t caps)¶ Get the total minimum free memory of all regions with the given capabilities.
This adds all the lowmarks of the regions capable of delivering the memory with the given capabilities
- Return
- Amount of free bytes in the regions
- Parameters
caps
: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory
-
static bool
esp_ptr_dma_capable
(const void *ptr)¶ Convenience function to check if a pointer is DMA-capable.
- Return
- True if DMA-capable, false if not.
- Parameters
ptr
: Pointer to check
Macros¶
-
MALLOC_CAP_EXEC
¶ Flags to indicate the capabilities of the various memory systems.
Memory must be able to run executable code
-
MALLOC_CAP_32BIT
¶ Memory must allow for aligned 32-bit data accesses.
-
MALLOC_CAP_8BIT
¶ Memory must allow for 8/16/…-bit data accesses.
-
MALLOC_CAP_DMA
¶ Memory must be able to accessed by DMA.
-
MALLOC_CAP_PID2
¶ Memory must be mapped to PID2 memory space.
-
MALLOC_CAP_PID3
¶ Memory must be mapped to PID3 memory space.
-
MALLOC_CAP_PID4
¶ Memory must be mapped to PID4 memory space.
-
MALLOC_CAP_PID5
¶ Memory must be mapped to PID5 memory space.
-
MALLOC_CAP_PID6
¶ Memory must be mapped to PID6 memory space.
-
MALLOC_CAP_PID7
¶ Memory must be mapped to PID7 memory space.
-
MALLOC_CAP_SPISRAM
¶ Memory must be in SPI SRAM.
-
MALLOC_CAP_INVALID
¶ Memory can’t be used / list end marker.
API Reference - Heap Regions¶
Header File¶
Functions¶
-
void
vPortDefineHeapRegionsTagged
(const HeapRegionTagged_t *const pxHeapRegions)¶ Initialize the heap allocator by feeding it the usable memory regions and their tags.
This takes an array of heapRegionTagged_t structs, the last entry of which is a dummy entry which has pucStartAddress set to NULL. It will initialize the heap allocator to serve memory from these ranges.
- Parameters
pxHeapRegions
: Array of region definitions
-
void *
pvPortMallocTagged
(size_t xWantedSize, BaseType_t tag)¶ Allocate memory from a region with a certain tag.
Like pvPortMalloc, this returns an allocated chunk of memory. This function, however, forces the allocator to allocate from a region specified by a specific tag.
- Return
- Pointer to allocated memory if succesful. NULL if unsuccesful.
- Parameters
xWantedSize
: Size needed, in bytestag
: Tag of the memory region the allocation has to be from
-
void
vPortFreeTagged
(void *pv)¶ Free memory allocated with pvPortMallocTagged.
This is basically an implementation of free().
- Parameters
pv
: Pointer to region allocated by pvPortMallocTagged
-
size_t
xPortGetMinimumEverFreeHeapSizeTagged
(BaseType_t tag)¶ Get the lowest amount of memory free for a certain tag.
This function allows the user to see what the least amount of free memory for a certain tag is.
- Return
- Minimum amount of free bytes available in the runtime of the program
- Parameters
tag
: Tag of the memory region
-
size_t
xPortGetFreeHeapSizeTagged
(BaseType_t tag)¶ Get the amount of free bytes in a certain tagged region.
Works like xPortGetFreeHeapSize but allows the user to specify a specific tag
- Return
- Remaining amount of free bytes in region
- Parameters
tag
: Tag of the memory region
Type Definitions¶
-
typedef struct HeapRegionTagged
HeapRegionTagged_t
¶ Structure to define a memory region.