Module stack 

Available on crate feature rt only.

Extent of the main stack and how much of it is left — see stack::headroom.

Needs the rt feature, since the region it reports on is the one this crate’s linker script reserves and its boot code points sp at. A program supplying its own boot code and linker script owns that layout instead. Extent of the main stack, and how much of it is left.

The stack is a region the linker script reserves and boot.s points sp at, rather than whatever happened to sit below the load address — so its size is a number in a file (__stack_size, 1 MiB by default, overridable with -Wl,--defsym=__stack_size=...), the same on both architectures.

What this module is for is the question that is otherwise unanswerable from inside a program: how close am I? An overflow runs off the bottom of the region and takes a data abort — the mmu feature leaves the margin below it unmapped for exactly that reason — and with no handler for it that abort parks silently and looks like a hang in a driver. rpi-hal’s fault-report feature prints it instead, and names the overflow rather than leaving a plain translation fault to be recognised. One line at startup —

writeln!(uart, "sp {:#x}, {} KiB free", stack::pointer(),
         stack::headroom().unwrap_or(0) / 1024)?;

— turns that class of bug from a debugging session into a number.

Only core 0’s main stack lives in this region. A secondary core runs on the Stack<BYTES> its application supplied, and the AArch32 exception modes run on their own banked regions, which is why used and headroom are Option — they report None rather than a meaningless number when sp isn’t in this region at all.

Functions

bottom

Lowest address of the main stack region.

headroom

Bytes between the current stack pointer and the bottom of the main stack — the headroom left before an overflow — or None if the caller isn’t running on it.

pointer

The calling core’s current stack pointer.

size

Size of the main stack region in bytes (__stack_size).

top

One past the highest address of the main stack region — where sp starts.

used

Bytes of the main stack currently in use, or None if the caller isn’t running on it.