embedded-alloc

The crate provides two different heap implementation strategies. The choice depends on your specific application requirements:

• LlffHeap: A Linked List First Fit heap.
• TlsfHeap: A Two-Level Segregated Fit heap.

Refer to the project's discussion on heap selection for more detailed performance and behavior comparisons.

Depending on the enabled features, embedded-alloc provides different heap management algorithms. You can use these as your #[global_allocator].

• LlffHeap: Available when the llff feature is enabled.
• TlsfHeap: Available when the tlsf feature is enabled.

To use embedded-alloc as a heap, you must first create an uninitialized heap instance using Heap::empty() and then initialize it with a specific memory region using the init method.

Important Safety and Usage Notes:

• Initialization Timing: You must call init before any code that performs allocations runs.
• Memory Direction: The heap grows

// Example setup pattern
static HEAP: Heap = Heap::empty();

fn main() {
    // Safety: Ensure start_addr and size represent a valid, unused memory region
    unsafe {
        HEAP.init(0x2000_0000, 64 * 1024);
    }
    // Now you can use the allocator
}

Use Heap::empty() to create a new, uninitialized heap allocator. This is a const fn, making it suitable for defining a global allocator instance.

Note: You must call init on the resulting instance before attempting to allocate any memory.

pub struct Heap {
    heap: Mutex<RefCell<(LLHeap, bool)>>,
}

impl Heap {
    pub const fn empty() -> Heap {
        Heap {
            heap: Mutex::new(RefCell::new((LLHeap::empty(), false))),
        }
    }
}

The Heap struct provides methods to query the current state of memory allocation:

• used(): Returns the total number of bytes currently allocated by the allocator.
• free(): Returns the total number of bytes currently available for allocation.

These methods use a critical section to ensure thread-safe access to the heap state.

let used_bytes = HEAP.used();
let free_bytes = HEAP.free();

Before using the allocator, you must initialize it using the init method. This method sets up the memory region where the heap will reside.

Parameters

• start_addr: The starting address of the heap. The heap grows upwards towards larger addresses.
• size: The total size of the heap in bytes.

Memory Bounds

• The smallest address used is start_addr.
• The largest address used is start_addr + size - 1.

Safety and Constraints

• Safety: You must ensure start_addr points to valid memory and that size is correct.
• Panics: The function will panic if called more than once or if size == 0.
• Uniqueness: This must be called exactly once before any code that uses the allocator runs.

unsafe {
    // Example initialization
    HEAP.init(0x2000_0000, 0x10000);
}

The Heap struct provides methods to estimate the current state of the memory pool:

• used(): Returns an estimate of the number of bytes currently in use.
• free(): Returns an estimate of the number of bytes currently available for allocation.

The Heap struct implements the core::alloc::GlobalAlloc trait. This allows you to use the Heap instance as the global allocator for your entire embedded application by using the #[global_allocator] attribute.

Note: Because init is an unsafe operation that must be called at runtime, you typically declare a static heap and initialize it early in your program's entry point.

use embedded_alloc::Heap;

#[global_allocator]
static ALLOCATOR: Heap = Heap::empty();

fn main() {
    unsafe {
        ALLOCATOR.init(0x2000_0000, 64 * 1024);
    }
    // Now standard library/core collections like Box or Vec can work
}

If the allocator_api feature is enabled, Heap implements the core::alloc::Allocator trait. This allows you to use the heap with collections that accept a specific allocator instance (e.g., Vec::new_in(&heap)).

// Requires feature "allocator_api"
// use core::alloc::Allocator;
// let mut vec = Vec::new_in(&HEAP);