Crate esp_alloc

A no_std heap allocator for RISC-V and Xtensa processors from Espressif. Supports all currently available ESP32 devices.

NOTE: using this as your global allocator requires using Rust 1.68 or greater, or the nightly release channel.

Using this as your Global Allocator

use esp_alloc as _;

fn init_heap() {
    const HEAP_SIZE: usize = 32 * 1024;
    static mut HEAP: MaybeUninit<[u8; HEAP_SIZE]> = MaybeUninit::uninit();

    unsafe {
        esp_alloc::HEAP.add_region(esp_alloc::HeapRegion::new(
            HEAP.as_mut_ptr() as *mut u8,
            HEAP_SIZE,
            esp_alloc::MemoryCapability::Internal.into(),
        ));
    }
}

Using this with the nightly allocator_api-feature

Sometimes you want to have more control over allocations.

For that, it’s convenient to use the nightly allocator_api-feature, which allows you to specify an allocator for single allocations.

NOTE: To use this, you have to enable the crate’s nightly feature flag.

Create and initialize an allocator to use in single allocations:

static PSRAM_ALLOCATOR: esp_alloc::EspHeap = esp_alloc::EspHeap::empty();

fn init_psram_heap() {
    unsafe {
        PSRAM_ALLOCATOR.add_region(esp_alloc::HeapRegion::new(
            psram::psram_vaddr_start() as *mut u8,
            psram::PSRAM_BYTES,
            esp_alloc::MemoryCapability::Internal.into(),
        ));
    }
}

And then use it in an allocation:

let large_buffer: Vec<u8, _> = Vec::with_capacity_in(1048576, &PSRAM_ALLOCATOR);

You can also get stats about the heap usage at anytime with:

let stats: HeapStats = esp_alloc::HEAP.stats();
// HeapStats implements the Display and defmt::Format traits, so you can pretty-print the heap stats.
println!("{}", stats);

HEAP INFO
Size: 131068
Current usage: 46148
Max usage: 46148
Total freed: 0
Total allocated: 46148
Memory Layout:
Internal | ████████████░░░░░░░░░░░░░░░░░░░░░░░ | Used: 35% (Used 46148 of 131068, free: 84920)
Unused   | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
Unused   | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |

Feature Flags

• defmt — Implement defmt::Format on certain types.

• internal-heap-stats — Enable this feature if you want to keep stats about the internal heap usage such as:

  • Max memory usage since initialization of the heap
  • Total allocated memory since initialization of the heap
  • Total freed memory since initialization of the heap

  ⚠️ Note: Enabling this feature will require extra computation every time alloc/dealloc is called.

Macros

heap_allocator

Initialize a global heap allocator providing a heap of the given size in bytes. This supports attributes.

psram_allocator

Initialize a global heap allocator backed by PSRAM

Structs

EspHeap

A memory allocator

HeapRegion

A memory region to be used as heap memory

HeapStats

Stats for a heap allocator

RegionStats

Stats for a heap region

Enums

MemoryCapability

Describes the properties of a memory region

Statics

HEAP

The global allocator instance