Tutorial · Chapter 10 of 23

Choose static and software-stack frames

Follow a recursive call, then measure where a nested word result and its live frames fit.

Jump to a section

Choose where a call keeps its arguments and locals

CallStorageUse it when
Static frameFixed cells owned by the callee.Each invocation finishes before the same function enters again.
callconv(.stack)A new frame in a declared C64 RAM region.Supported recursion needs live arguments from earlier calls, or a DLL export uses the stack ABI.

Both use the 6510 hardware stack for machine return addresses. Inline assembly also uses that hardware stack for register saves. The software stack gives arguments and locals their own storage. A byte return uses A. A word return uses its low byte in A and its high byte in X.

Give each recursive call its own argument

32_stack_recursive_border.zp64
const c64 = @import("c64");

memory {
    region call_stack: c64 at 0xc800 size 0x0400;

    stack in call_stack;
}

fn borderFrom(value: u8) callconv(.stack) u8 {
    if (value == 0) {
        return 5;
    }
    return borderFrom(value - 1);
}

export fn main() callconv(.stack) void {
    var border: u8 = borderFrom(4);
    c64.vic.border = border;
}

Follow the argument from 4 to 0. Five invocations of borderFrom are live at the deepest point. When the base case returns 5, every pending call returns the same value. The border turns green. Static recursion would reuse the same parameter cell, so the compiler requires a supported stack-frame call for this pattern.

Open the complete source

Check a frame reservation at its boundary

The word example uses a twelve-byte software stack at $c8fc. Follow main → relay → identity. The frame at the deepest call ends at $c908, the first byte outside the reservation. The two-byte saved frame pointer before a nested frame is part of the budget.

stack-result.zp64
pub const zeropage_options = .{
    .stack = .{ .base = 0xc8fc, .size = 12 },
    .abi = .{ .default_frame = .stack, .functions = .{ .store = .{ .frame = .static } } },
};

fn identity(value: u16) u16 {
    return value;
}

fn relay(value: u16) u16 {
    return identity(value);
}

export fn main() void {
    const word: u16 = relay(0x805a);
    store(word);
}

fn store(value: u16) void {
    const result: *volatile u16 = @ptrFromInt(0xc100);
    result.* = value;
}

Open the complete source

After the program runs, use m c100 c101 in the VICE monitor. Expect 5a 80, the returned word in little-endian order. The bridge restores the caller frame and delivers A/X to the caller, which passes the result to the static store helper. This example uses an options declaration to select the default frame and override one function.

Reduce the stack to eleven bytes. Set a breakpoint at .zeropage_stack_overflow_trap using its address in the new labels file and rerun. The nested call traps before the word is stored. Restore twelve bytes to recover. See the annotated frame bytes if you want to inspect each active frame.