Struct ScratchpadStack 

pub struct ScratchpadStack<const START: usize, const END: usize>;

A call stack in scratchpad bytes START..END.

The stack grows down from END - 16; the bottom word at START is the canary. See the module docs for the rules.

A layout the stack cannot use is a compile error where it is run:

use psx_rt::scratchpad::ScratchpadStack;
// END is not 8-byte aligned.
const _: usize = ScratchpadStack::<0, 1020>::BUDGET;

Implementations

impl<const START: usize, const END: usize> ScratchpadStack<START, END>

pub const REGION: Region

The bytes this stack owns while a call runs on it. Evaluating it checks the layout: in bounds, START word aligned, END 8-byte aligned (the o32 stack alignment) and room for more than the overhead.

pub const BUDGET: usize

Bytes of frames the call tree may use; stack-guard fails the build when the linked tree needs more.

pub unsafe fn run<R, F: FnOnce() -> R>(f: F) -> R

Run f with $sp in this region and return its result.

The switch is a 16-instruction trampoline after a 4-instruction $sp test. Already on a scratchpad stack, it calls f in place. On the host there is no scratchpad and it only calls f.

Safety

• No scratchpad data another piece of code relies on may live in Self::REGION while f runs, and f must not put any there. Record the regions that are live around the call with assert_disjoint.
• The linked call tree of f must fit in Self::BUDGET. Run stack-guard on every linked image that calls this.
• Any exception handler installed while interrupts are enabled must leave $sp and the memory below it alone (psx-rt’s does; declare another with declare_stack_safe_handler).