In a Rust `#![no_std]` firmware binary, what must exist before `alloc::vec::Vec` links, and what happens when that allocator runs out of memory?
answer
- one allocator per crate graph
- a static implementing an unsafe trait
- null means exhausted
- handle_alloc_error, then the handler
- try_reserve to stay in control
basics
~20 sThe binary needs exactly one #[global_allocator] static whose type implements GlobalAlloc, usually over a RAM region it owns. When alloc returns null, Vec calls handle_alloc_error; with no std in the program that panics and your #[panic_handler] runs.
solid answer
~40 s`extern crate alloc;` compiles in any crate, and libraries need nothing more, but the final binary must contain exactly one `#[global_allocator]` static whose type implements `core::alloc::GlobalAlloc`; without it linking stops with "no global memory allocator found but one is required". `GlobalAlloc` is an `unsafe trait` with two required methods, `alloc` and `dealloc` (`alloc_zeroed` and `realloc` have defaults), and the implementer promises the contract: hand out memory that is not in use and never unwind; the docs encourage returning null on exhaustion rather than aborting. On firmware the heap is usually a static buffer or a linker-defined region. When `alloc` returns null, `Vec::push` or `Vec::with_capacity` calls `handle_alloc_error`, which in a program with no `std` calls `panic!`, so the panic handler runs. Code that must survive exhaustion uses `Vec::try_reserve`, which returns `Err` instead.
code
rust · 43 lines#![no_std]
#![no_main]
extern crate alloc;
use alloc::vec::Vec;
use core::alloc::{GlobalAlloc, Layout};
use core::cell::UnsafeCell;
use core::sync::atomic::{AtomicUsize, Ordering::Relaxed};
const HEAP_SIZE: usize = 4096;
// A bump allocator over a static buffer: it never reuses freed memory.
struct Bump { heap: UnsafeCell<[u8; HEAP_SIZE]>, next: AtomicUsize }
unsafe impl Sync for Bump {}
unsafe impl GlobalAlloc for Bump {
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
let base = self.heap.get() as usize;
let start = |cur: usize| (base + cur).next_multiple_of(layout.align()) - base;
let claimed = self.next.try_update(Relaxed, Relaxed, |cur| {
Some(start(cur) + layout.size()).filter(|&end| end <= HEAP_SIZE)
});
match claimed {
Ok(cur) => (base + start(cur)) as *mut u8,
Err(_) => core::ptr::null_mut(), // out of memory
}
}
unsafe fn dealloc(&self, _ptr: *mut u8, _layout: Layout) {}
}
#[global_allocator]
static HEAP: Bump = Bump { heap: UnsafeCell::new([0; HEAP_SIZE]), next: AtomicUsize::new(0) };
#[cortex_m_rt::entry]
fn main() -> ! {
let mut crcs: Vec<u16> = Vec::with_capacity(16);
crcs.push(0x29B1);
loop {}
}
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! { loop {} }go deeper
Know that alloc's types need a heap and that a no_std binary chooses it with one #[global_allocator] static.
Explain the GlobalAlloc contract, null for exhaustion and no unwinding, and trace an out-of-memory Vec::push through handle_alloc_error to the panic handler.
Choose a heap strategy for a device: allocate only at start-up, use try_reserve on untrusted sizes, size the region from the linker map, and prefer a published allocator crate.
Decide whether firmware should have a heap at all, weighing fragmentation and unbounded allocation time against the convenience of Vec and Box.
## Why `alloc` needs one more piece `alloc` provides `Vec`, `String`, `Box` and the rest, but not the memory. Every allocation goes through one global allocator. In a `std` program the standard library supplies a default (the std docs leave which one unspecified). In a `no_std` program nobody does, so the binary must. - A **library** may write `extern crate alloc;` and use `alloc::vec::Vec`; it builds without choosing anything. - The **binary** must contain exactly one `#[global_allocator]` static. The Reference says the attribute applies only to a `static` whose type implements `GlobalAlloc`, and may be used **once in the crate graph**. - Forget it, and rustc 1.99.1 stops linking with: "no global memory allocator found but one is required; link to std or add `#[global_allocator]` to a static item that implements the GlobalAlloc trait". ## The `GlobalAlloc` contract `core::alloc::GlobalAlloc` is an `unsafe trait`: implementing it is a promise the compiler cannot check. | method | required? | what it does | |---|---|---| | `alloc(&self, layout)` | yes | returns a pointer to `layout.size()` bytes aligned to `layout.align()`, or null | | `dealloc(&self, ptr, layout)` | yes | releases a block obtained from this allocator with the same layout | | `alloc_zeroed` | default: `alloc` then zero | override when zeroed memory is cheaper | | `realloc` | default: allocate, copy, free | override to grow in place | From the trait's documentation: 1. The allocator must not read, write or free memory that is currently allocated to someone else. 2. **Unwinding out of an allocator is undefined behaviour.** 3. A null return means memory is exhausted or the layout is unsupported, and implementations are encouraged to return null on exhaustion rather than abort; callers then decide what to do. Because the allocator lives in a `static` and can be called from an interrupt handler as well as the main loop, its type must be `Sync`, and its internal state needs atomics or a critical section. The snippet below uses an atomic bump pointer; why `static mut` would be unsound here is the interrupts material's subject. ## Reading the example - `HEAP` is a `static`, so its type must be `Sync`. `UnsafeCell` gives interior mutability over the byte array, and `unsafe impl Sync` is the author's promise that access is coordinated. - `next` is an offset advanced with `try_update`, a compare-and-swap loop, so an allocation interrupted by another allocation cannot hand out the same bytes twice. - The start is rounded up with `next_multiple_of(layout.align())`, which gives every block the alignment its `Layout` demands. - When the end would pass `HEAP_SIZE`, `alloc` returns null instead of panicking: null is how the trait signals exhaustion, and unwinding out of an allocator is undefined behaviour. - `dealloc` does nothing, so memory freed by dropping a `Vec` is never reused: acceptable for start-up allocations, fatal for a loop that allocates per message. ## Where the heap comes from on firmware - A `static` byte array, as in the example: simple, sized at compile time, placed in `.bss`. - A region between the end of static data and the stack, given by linker-script symbols, so the heap gets whatever RAM is left. - In practice teams use a published allocator crate (linked-list or two-level segregated fit designs) rather than writing one. The bump allocator below never frees, which is acceptable only for allocations made once at start-up. ## Running out of memory 1. `alloc` returns null. 2. `Vec::push`, `Vec::with_capacity`, `Box::new` and friends call `alloc::alloc::handle_alloc_error`. 3. Its documented default: if the binary links `std`, print a message to standard error and abort; if all crates are `#![no_std]`, **call `panic!`**, and the panic handler applies as for any other panic. On a host `std` program the abort shows up as "memory allocation of 8000 bytes failed". In a `no_std` program it is your handler, typically halting or resetting the device. ## Staying in control - `Vec::try_reserve(additional)` returns `Result<(), TryReserveError>` instead of calling `handle_alloc_error`, so a protocol buffer can reject one oversized frame and carry on. - Allocate once at start-up and never again, so exhaustion can only happen during boot, where a reset is cheap. - Avoid the heap entirely with fixed-capacity collections, the heapless material's subject, when the worst case is known.
- Why should a Rust `GlobalAlloc` implementation return null instead of panicking when its memory runs out?The trait's contract makes unwinding out of a global allocator undefined behaviour, so a panic there is unsound on any target that unwinds. Even where panics abort, null keeps the choice with the caller: `Vec::try_reserve` turns it into an error, and `handle_alloc_error` panics or aborts from a point that is prepared for it.
- In a `no_std` Rust binary, how does a parser accept a frame only if memory allows, without reaching the panic handler?Call `Vec::try_reserve(n)` before filling the buffer. It returns `Err(TryReserveError)` when the allocator returns null, and the parser can drop that frame and continue; `Vec::with_capacity(n)` or `push` would call `handle_alloc_error`, which panics in a `no_std` program.
- Can a Rust `no_std` library crate define `#[global_allocator]` for its users?It can compile, but it should not: the attribute may appear only once in the crate graph, so a library that defines one collides with any binary that picks its own, and it fixes heap size and placement for every board. Libraries use `alloc`; the binary chooses the allocator.
- Expecting `extern crate alloc` alone to give a firmware binary a working heap.
- Thinking each crate that uses `alloc` must declare its own allocator.
- Panicking inside `GlobalAlloc::alloc` on exhaustion instead of returning null.
- Assuming `Vec::push` on firmware returns an error when the heap is full.
- Implementing `GlobalAlloc` over a `static mut` buffer with no synchronisation.