Embedded Alloc

https://docs.rs/embedded-alloc/0.6.0/
Admin
A heap allocator for embedded systems, offering Linked List First Fit (LlffHeap) and Two-Level...
Tokens:10,065
Snippets:21
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### embedded-alloc Crate Setup

Source: https://docs.rs/embedded-alloc/0.6.0/src/embedded_alloc/lib

This Rust code snippet demonstrates the basic setup of the embedded-alloc crate. It includes standard library configurations, conditional compilation for allocator features ('allocator_api', 'alloc_layout_extra'), and warnings for missing documentation. It also conditionally includes and re-exports the 'llff' and 'tlsf' allocator modules.

```Rust
#![doc = include_str!("../README.md")]
#![no_std]
#![cfg_attr(feature = "allocator_api", feature(allocator_api, alloc_layout_extra))]
#![warn(missing_docs)]

#[cfg(feature = "llff")]
mod llff;
#[cfg(feature = "tlsf")]
mod tlsf;

#[cfg(feature = "llff")]
pub use llff::Heap as LlffHeap;
#[cfg(feature = "tlsf")]
pub use tlsf::Heap as TlsfHeap;
```

--------------------------------

### Global Allocator Example (Rust)

Source: https://docs.rs/embedded-alloc/0.6.0/index

Demonstrates how to use embedded-alloc as a global allocator in an embedded Rust project. This example initializes the LlffHeap and shows how to make it available for types like Box and Vec. It requires Rust 1.68 or later and a critical-section implementation.

```Rust
#![no_std]
#![no_main]

extern crate alloc;

use cortex_m_rt::entry;
use embedded_alloc::LlffHeap as Heap;

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

#[entry]
fn main() -> ! {
    // Initialize the allocator BEFORE you use it
    {
        use core::mem::MaybeUninit;
        const HEAP_SIZE: usize = 1024;
        static mut HEAP_MEM: [MaybeUninit<u8>; HEAP_SIZE] = [MaybeUninit::uninit(); HEAP_SIZE];
        unsafe { HEAP.init(HEAP_MEM.as_ptr() as usize, HEAP_SIZE) }
    }

    // now the allocator is ready types like Box, Vec can be used.

    loop { /* .. */ }
}
```

--------------------------------

### Initialize embedded-alloc Heap

Source: https://docs.rs/embedded-alloc/0.6.0/src/embedded_alloc/tlsf

Demonstrates the initialization of the `Heap` allocator with a given start address and size. This function must be called exactly once before using the allocator.

```Rust
use core::alloc::{GlobalAlloc, Layout};
use core::cell::RefCell;
use core::ptr::{self, NonNull};

use const_default::ConstDefault;
use critical_section::Mutex;
use rlsf::Tlsf;

type TlsfHeap = Tlsf<'static, usize, usize, { usize::BITS as usize }, { usize::BITS as usize }>;

/// A two-Level segregated fit heap.
pub struct Heap {
    heap: Mutex<RefCell<TlsfHeap>>,
}

impl Heap {
    /// Create a new UNINITIALIZED heap allocator
    ///
    /// You must initialize this heap using the
    /// [`init`](Self::init) method before using the allocator.
    pub const fn empty() -> Heap {
        Heap {
            heap: Mutex::new(RefCell::new(ConstDefault::DEFAULT)),
        }
    }

    /// Initializes the heap
    ///
    /// This function must be called BEFORE you run any code that makes use of the
    /// allocator.
    ///
    /// `start_addr` is the address where the heap will be located.
    ///
    /// `size` is the size of the heap in bytes.
    ///
    /// Note that:
    ///
    /// - The heap grows "upwards", towards larger addresses. Thus `start_addr` will
    ///   be the smallest address used.
    ///
    /// - The largest address used is `start_addr + size - 1`, so if `start_addr` is
    ///   `0x1000` and `size` is `0x30000` then the allocator won't use memory at
    ///   addresses `0x31000` and larger.
    ///
    /// # Safety
    ///
    /// Obey these or Bad Stuff will happen.
    ///
    /// - This function must be called exactly ONCE.
    /// - `size > 0`
    pub unsafe fn init(&self, start_addr: usize, size: usize) {
        critical_section::with(|cs| {
            let block: &[u8] = core::slice::from_raw_parts(start_addr as *const u8, size);
            self.heap
                .borrow(cs)
                .borrow_mut()
                .insert_free_block_ptr(block.into());
        });
    }

    fn alloc(&self, layout: Layout) -> Option<NonNull<u8>> {
        critical_section::with(|cs| self.heap.borrow(cs).borrow_mut().allocate(layout))
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        critical_section::with(|cs| {
            self.heap
                .borrow(cs)
                .borrow_mut()
                .deallocate(NonNull::new_unchecked(ptr), layout.align())
        })
    }
}

unsafe impl GlobalAlloc for Heap {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        self.alloc(layout)
            .map_or(ptr::null_mut(), |allocation| allocation.as_ptr())
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        self.dealloc(ptr, layout)
    }
}

#[cfg(feature = "allocator_api")]
mod allocator_api {
    use super::*;
    use core::alloc::{AllocError, Allocator};

    unsafe impl Allocator for Heap {
        fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
            match layout.size() {
                0 => Ok(NonNull::slice_from_raw_parts(layout.dangling(), 0)),
                size => self.alloc(layout).map_or(Err(AllocError), |allocation| {
                    Ok(NonNull::slice_from_raw_parts(allocation, size))
                }),
            }
        }

        unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout) {
            if layout.size() != 0 {
                self.dealloc(ptr.as_ptr(), layout);
            }
        }
    }
}

```

--------------------------------

### Global Allocator Example (Rust)

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc

Demonstrates how to use embedded-alloc as a global allocator in an embedded Rust project. This example initializes the LlffHeap and shows how to make it available for types like Box and Vec. It requires Rust 1.68 or later and a critical-section implementation.

```Rust
#![no_std]
#![no_main]

extern crate alloc;

use cortex_m_rt::entry;
use embedded_alloc::LlffHeap as Heap;

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

#[entry]
fn main() -> ! {
    // Initialize the allocator BEFORE you use it
    {
        use core::mem::MaybeUninit;
        const HEAP_SIZE: usize = 1024;
        static mut HEAP_MEM: [MaybeUninit<u8>; HEAP_SIZE] = [MaybeUninit::uninit(); HEAP_SIZE];
        unsafe { HEAP.init(HEAP_MEM.as_ptr() as usize, HEAP_SIZE) }
    }

    // now the allocator is ready types like Box, Vec can be used.

    loop { /* .. */ }
}
```

--------------------------------

### Global Allocator Example (Rust)

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/index

Demonstrates how to use embedded-alloc as a global allocator in an embedded Rust project. This example initializes the LlffHeap and shows how to make it available for types like Box and Vec. It requires Rust 1.68 or later and a critical-section implementation.

```Rust
#![no_std]
#![no_main]

extern crate alloc;

use cortex_m_rt::entry;
use embedded_alloc::LlffHeap as Heap;

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

#[entry]
fn main() -> ! {
    // Initialize the allocator BEFORE you use it
    {
        use core::mem::MaybeUninit;
        const HEAP_SIZE: usize = 1024;
        static mut HEAP_MEM: [MaybeUninit<u8>; HEAP_SIZE] = [MaybeUninit::uninit(); HEAP_SIZE];
        unsafe { HEAP.init(HEAP_MEM.as_ptr() as usize, HEAP_SIZE) }
    }

    // now the allocator is ready types like Box, Vec can be used.

    loop { /* .. */ }
}
```

--------------------------------

### TlsfHeap Initialization

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Provides methods for initializing and managing the TlsfHeap. The `empty` method creates an uninitialized heap, and the `init` method initializes it with a given start address and size. Safety precautions for `init` include calling it exactly once and ensuring the size is greater than zero.

```Rust
pub const fn empty() -> Heap
Create a new UNINITIALIZED heap allocator
You must initialize this heap using the `init` method before using the allocator.
```

```Rust
pub unsafe fn init(&self, start_addr: usize, size: usize)
Initializes the heap
This function must be called BEFORE you run any code that makes use of the allocator.
`start_addr` is the address where the heap will be located.
`size` is the size of the heap in bytes.
Note that:
  * The heap grows “upwards”, towards larger addresses. Thus `start_addr` will be the smallest address used.
  * The largest address used is `start_addr + size - 1`, so if `start_addr` is `0x1000` and `size` is `0x30000` then the allocator won’t use memory at addresses `0x31000` and larger.

#####  §Safety
Obey these or Bad Stuff will happen.
  * This function must be called exactly ONCE.
  * `size > 0`
```

--------------------------------

### Initialize Heap Allocator

Source: https://docs.rs/embedded-alloc/0.6.0/src/embedded_alloc/llff

This function initializes the `Heap` allocator with a specified start address and size. It must be called exactly once before the allocator is used. The heap grows towards higher memory addresses.

```Rust
pub unsafe fn init(&self, start_addr: usize, size: usize) {
    critical_section::with(|cs| {
        self.heap
            .borrow(cs)
            .borrow_mut()
            .init(start_addr as *mut u8, size);
    });
}
```

--------------------------------

### Rustdoc Keyboard Shortcuts

Source: https://docs.rs/embedded-alloc/0.6.0/help

This section details the keyboard shortcuts available within the rustdoc documentation interface. These shortcuts allow users to navigate the documentation, focus the search field, and manage search results efficiently.

```text
`?`
    Show this help dialog 

`S` / `/` 
    Focus the search field 

`↑`
    Move up in search results 

`↓`
    Move down in search results 

`←` / `→` 
    Switch result tab (when results focused) 

`⏎`
    Go to active search result 

`+`
    Expand all sections 

`-`
    Collapse all sections 

`_`
    Collapse all sections, including impl blocks
```

--------------------------------

### Rustdoc Search Tricks

Source: https://docs.rs/embedded-alloc/0.6.0/help

This section outlines advanced search functionalities within rustdoc. It explains how to filter searches by item kind, search by type signature, find items with exact names, search for slice/array types, and locate items within specific paths.

```text
Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given item kind.
Accepted kinds are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.
Search functions by type signature (e.g., `vec -> usize` or `-> vec` or `String, enum:Cow -> bool`)
You can look for items with an exact name by putting double quotes around your request: `"string"`
Look for functions that accept or return slices and arrays by writing square brackets (e.g., `-> [u8]` or `[] -> Option`)
Look for items inside another one by searching for a path: `vec::Vec`
```

--------------------------------

### Create an Uninitialized Heap

Source: https://docs.rs/embedded-alloc/0.6.0/src/embedded_alloc/llff

This constant function creates an uninitialized `Heap` allocator. The `init` method must be called on the returned `Heap` instance before it can be used for memory allocation.

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

--------------------------------

### Implement GlobalAlloc for Heap

Source: https://docs.rs/embedded-alloc/0.6.0/src/embedded_alloc/llff

This code implements the `GlobalAlloc` trait for the `Heap` struct, enabling it to be used as a global memory allocator in Rust. It defines how memory allocation and deallocation should occur using the underlying linked list allocator.

```Rust
unsafe impl GlobalAlloc for Heap {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        self.alloc(layout)
            .map_or(ptr::null_mut(), |allocation| allocation.as_ptr())
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        self.dealloc(ptr, layout);
    }
}
```

--------------------------------

### Implement Allocator API for Heap

Source: https://docs.rs/embedded-alloc/0.6.0/src/embedded_alloc/llff

This snippet implements the `Allocator` trait from Rust's `allocator_api` module for the `Heap` struct. This allows the heap allocator to be used with newer allocation APIs, providing methods for `allocate` and `deallocate` that handle `Layout` and `AllocError`.

```Rust
unsafe impl Allocator for Heap {
    fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
        match layout.size() {
            0 => Ok(NonNull::slice_from_raw_parts(layout.dangling(), 0)),
            size => self.alloc(layout).map_or(Err(AllocError), |allocation| {
                Ok(NonNull::slice_from_raw_parts(allocation, size))
            }),
        }
    }

    unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout) {
        if layout.size() != 0 {
            self.dealloc(ptr.as_ptr(), layout);
        }
    }
}
```

--------------------------------

### Any Trait Implementation for T

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Implements the `Any` trait for any type `T` that is `'static` and `?Sized`. This allows for runtime type identification.

```Rust
fn type_id(&self) -> TypeId
Gets the `TypeId` of `self`. Read more
```

--------------------------------

### TryInto Trait Implementation for T

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Implements the `TryInto<U>` trait for type `T` where `U` implements `TryFrom<T>`. This allows for fallible conversions.

```Rust
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
```

```Rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
Performs the conversion.
```

--------------------------------

### GlobalAlloc Trait Implementation for Heap

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Implements the `GlobalAlloc` trait for the Heap, providing core memory allocation and deallocation functionalities. This includes `alloc`, `dealloc`, `alloc_zeroed`, and `realloc`.

```Rust
unsafe fn alloc(&self, layout: Layout) -> *mut u8
Allocates memory as described by the given `layout`. Read more
```

```Rust
unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout)
Deallocates the block of memory at the given `ptr` pointer with the given `layout`. Read more
1.28.0 · Source
```

```Rust
unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8
Behaves like `alloc`, but also ensures that the contents are set to zero before being returned. Read more
1.28.0 · Source
```

```Rust
unsafe fn realloc( &self, ptr: *mut u8, layout: Layout, new_size: usize, ) -> *mut u8
Shrinks or grows a block of memory to the given `new_size` in bytes. The block is described by the given `ptr` pointer and `layout`. Read more
```

--------------------------------

### TryFrom Trait Implementation for T

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Implements the `TryFrom<U>` trait for type `T` where `U` implements `Into<T>`. This provides a fallible conversion mechanism.

```Rust
type Error = Infallible
The type returned in the event of a conversion error.
```

```Rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion.
```

--------------------------------

### Into Trait Implementation for T

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Implements the `Into<U>` trait for type `T` where `U` implements `From<T>`. This allows conversion between types.

```Rust
fn into(self) -> U
Calls `U::from(self)`.
That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.
```

--------------------------------

### BorrowMut Trait Implementation for T

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Implements the `BorrowMut<T>` trait for type `T` where `T` is `?Sized`. This enables mutable borrowing.

```Rust
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
```

--------------------------------

### Borrow Trait Implementation for T

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Implements the `Borrow<T>` trait for type `T` where `T` is `?Sized`. This enables immutable borrowing.

```Rust
fn borrow(&self) -> &T
Immutably borrows from an owned value. Read more
```

--------------------------------

### From Trait Implementation for T

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Implements the `From<T>` trait for type `T`, which simply returns the argument unchanged.

```Rust
fn from(t: T) -> T
Returns the argument unchanged.
```

--------------------------------

### TlsfHeap Struct Definition

Source: https://docs.rs/embedded-alloc/0.6.0/embedded_alloc/struct

Defines the TlsfHeap struct, which is a two-level segregated fit heap allocator. It has private fields and is intended for use within embedded systems.

```Rust
pub struct TlsfHeap { /* private fields */ }
```
Tokens:
Raw