pub fn assert_stack_headroom()Expand description
Trap (loudly, via TTY) if the live stack pointer has descended into the static data region.
The linker lays out .text/.data/.bss from the load address upward
and runs the stack downward from the top of RAM. The two are only
safe while $sp stays above the top of .bss. A large
stack-resident object (e.g. a multi-hundred-KB struct held in a
main local) or very deep call frames push $sp below __bss_end;
from there a stack write and a write to some static alias the same
RAM and silently corrupt each other – the corruption surfaces far
from the cause and is brutal to debug. Call this once the deepest
expected stack frame is live (e.g. right after constructing the main
scene object) to turn that into an immediate, located halt instead.
Note: this checks against the actual top of static data, not the
linker’s __heap_end stack floor, which currently reserves only a
nominal slice and would false-positive on any real stack.