Guide · Chapter 6 of 14

Frames, recursion, and interop

Follow data across static and stack calls, and understand the ReadyOS boundary.

Jump to a section

Static frames and return registers

Static calls copy arguments into fixed storage owned by the callee. The frame has program lifetime and is not reentrant. Record arguments copy flattened fields. Byte returns use A. Words and near pointers return low byte in A and high byte in X. Static aggregate results use return storage. Inspect the generated labels to follow the argument cells.

26_static_abi_metadata.zp64
const c64 = @import("c64");

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

    stack in call_stack;
}

fn helper(a: u8, b: u8) callconv(.static) u8 {
    return a + b;
}

export fn main() callconv(.static) void {
    c64.console.clear();
    c64.console.print("ABI METADATA\n", .{});

    var total: u8 = helper(2, 4);
    if (total == 6) {
        c64.console.print("STATIC OK\n", .{});
        c64.vic.border = 5;
    } else {
        c64.console.print("STATIC BAD\n", .{});
        c64.vic.border = 2;
    }
}

Follow a record through static return storage

A Reading occupies three bytes. The caller copies its channel and both total bytes into adjust's parameter cells. The callee adds the delta to its own copy, writes all three result bytes to its return storage, and returns. The caller copies those bytes into first before calling the function again. The second call reuses the callee cells. The first result remains available in the caller.

aggregate-return.zp64
const c64 = @import("c64");

const Reading = struct { channel: u8, total: u16 };

fn adjust(input: Reading, delta: u16) callconv(.static) Reading {
    input.total += delta;
    return input;
}

export fn main() void {
    c64.console.clear();
    const original = Reading{ .channel = 3, .total = 0x12ff };
    const first = adjust(original, 1);
    const second = adjust(original, 2);
    const old_word: u16 = original.total;
    const first_word: u16 = first.total;
    const second_word: u16 = second.total;
    c64.console.print("ORIGINAL {x16}\n", .{old_word});
    c64.console.print("FIRST {x16} SECOND {x16}\n", .{ first_word, second_word });
    if (first.channel == 3 and first.total == 0x1300 and second.total == 0x1301) {
        c64.vic.border = 5;
    }
}

Open the complete source

Expect the original total 12FF and the two new totals 1300 and 1301. Copy the word fields into named u16 locals before formatting. In this preview, a direct field argument to {x16} prints its low byte with a zero high byte. The named word locals pass both bytes.

In the generated assembly, follow adjust_input_channel and adjust_input_total into the function, then adjust_return_channel and adjust_return_total into the caller's result cells. The high byte lives at adjust_return_total+1. A byte or word return would use registers instead of a record return area.

These static cells belong to the function for the life of the program. They are reused on every call, so a recursive or interrupt-driven re-entry can overwrite a live invocation. Use a pointer when the caller wants in-place mutation. For calls through the software stack or DLL ABI, choose supported scalar interfaces. Record copies with two-byte pointer fields · Rejected software-stack record return

A separate stack for recursion

Ordinary functions use fixed frame storage. For recursion, reserve RAM for the software stack and mark the recursive function with callconv(.stack). This example counts down to zero and returns the green border value. An exhausted software stack traps.

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;
}

Compile the file and inspect the generated assembly for the entry and frame setup. The software stack holds the supported call-frame values. The 6510 hardware stack still holds CPU return addresses. Frame layouts and ABI limits

Configure a stack region in visible RAM. Its software stack and frame pointers use zero-page pairs. The 6510 hardware stack still holds the machine return address and compiler wrapper saves. The stack convention supports the documented scalar/pointer subset and checks frame bounds. Stack overflow traps. Avoid assuming every static-frame feature is available in a stack frame.

Bridge directions, limits, and register contracts

Use the mixed-call examples to see when a bridge is needed. Static code can call a stack function and a stack function can call an eligible static helper. The recursive fixture checks the normal path, and an expected-failure fixture exercises a stack bound. Static caller to stack helper · Stack caller to static helper · Recursion fixture · Expected overflow trap

Exercise a stack limit with two nested calls

Follow main → relay → identity. The nested calls keep both frames and their saved linkage live. After running the program, open the VICE monitor and look for the returned word 5a 80 at $c100–$c101.

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

Twelve bytes starting at $c8fc give the exclusive end $c908. Reduce the reservation to eleven and set a breakpoint on .zeropage_stack_overflow_trap to observe the rejected call. The hardware stack has its own budget for JSRs, wrapper saves, and interrupts.

Follow a word argument through a nested call

Break at .identity. The frame pointer names the active frame and the software stack pointer names its first free byte. The monitor shows 08 c9 06 c9 at $00f7–$00fa, which means SP is $c908 and FP is $c906.

AddressBytesPurpose
$c8fc00 00Unassigned result in main
$c8fe5a 80Pending word in main
$c900fc c8Saved main frame pointer
$c9025a 80Relay argument
$c90402 c9Saved relay frame pointer
$c9065a 80Identity argument

The bridge checks the new end before writing the saved frame pointer or the argument. The end equals the reservation limit and fits. On return, the bridge saves A and X, restores the previous frame, and reloads the return registers. Continue to see the word stored in visible RAM. Read the generated assembly for the build you are sizing, since private frame layout can change with the source.

Measure both stacks on a nested workload

Both fixtures run the same 48 updates and assert the same final word. Each update calls a second helper while its own frame is live. The static version gives the two helpers fixed storage. The stack version places their arguments and locals in a configured software stack while keeping the entry and loop driver static.

Frame policyPRG bytesHost CPU cyclesPeak hardware stack bytesSoftware stack write extentSoftware stack reserved
Static helpers29016,046500
Stack helpers54038,190621 bytes256 bytes

The write extent is the distance from the software-stack base to the highest byte written, inclusive. Frames can reserve bytes they never write. To check capacity, exercise the deepest call path and include its frame linkage and any compiler-reserved slots. The measured hardware stack is relative to the host runner's starting point. IRQs and firmware activity can add to it on a C64.

Use static frames when calls run to completion without re-entry. A second invocation of the same static function would share argument and local cells. Software-stack frames allow supported recursion and give each call its own cells. They do not make interrupt re-entry into shared runtime helpers safe. Keep interrupt handlers within a separately defined machine contract.

Static fixture · Stack fixture · Shared workload · Metric definitions

Resident code, banking, and ReadyOS

The raw-image entry and named regions also support hosted applications. The ReadyOS Tic-Tac-Toe example enters at $1000, leaves the resident shim's range available, and uses the shim's documented terminal vectors. The sample starts a fresh game on entry. Host-managed REU resources and resume-aware state are future integration work.

ReadyOS boundary and proposed host adapter · Shim source