Guide · Chapter 10 of 14

DLL loading, ownership, and banking

Handle missing disk files, share dependencies, preserve state, and use RAM under ROM.

Jump to a section

Decide when disk I/O happens

Start with an explicit load while you bring up a new module. Preload moves disk I/O to startup. On-demand moves it to the first call that needs the module. Choose based on where the user can tolerate a delay and what your program will do if the disk entry is missing.

Preload before main

Current module · configuration excerpt
current {
    load = .preload;
    load_file = "enemyrt";
}

Load on the first call

Current module · configuration excerpt
current {
    load = .on_demand;
    load_file = "enemyrt";
}

Both are settings inside module_loader. Supply disk staging and a filename. For dependencies, put the policy on the dependency row and supply its file. With .manual, use an explicit load or acquire. With .preload, check availability at entry before relying on the export. With .on_demand, handle null at the call site. A later call to an already loaded module can reuse the cache.

Current preload demo · Current on-demand demo · Preload with a missing disk entry · Dependency call with a missing disk entry

Observe when the same disk DLL becomes callable

This program checks the registry at entry, then calls three typed exports. Build it as written to see on-demand loading. Change only .on_demand to .preload and rebuild to see startup loading. For manual loading, use .manual, remove load_file, and put _ = Rules.loadFromDisk("rules"); immediately before the first call. That keeps the entry check at the same point in all three versions.

dll-policy.zp64
const c64 = @import("c64");
const ZeroPage = @import("ZeroPage");

extern module Rules = rules {
    fn tick(value: u8) u8;
    fn ready(value: u8) bool;
    fn widen(value: u16) u16;
}

memory {
    region execution: c64 at 0xc000 size 0x0800;
    region frames: c64 at 0xc800 size 0x0400;
    region staging: c64 at 0x9000 size 0x0800;
    region cache: reu at 0x030000 size 0x0800;
    stack in frames;
}

module_loader {
    window main in execution;
    reu_cache in cache;
    disk_staging in staging;
    current {
        load = .on_demand;
        load_file = "rules";
    }
}

module rules abi 1 {
    export tick;
    export ready;
    export widen;
}

fn tick(value: u8) callconv(.stack) u8 {
    return value + 1;
}

fn ready(value: u8) callconv(.stack) bool {
    return value == 4;
}

fn widen(value: u16) callconv(.stack) u16 {
    return value + 0x0101;
}

export fn main() void {
    c64.console.clear();
    if (ZeroPage.module.isLoaded("rules")) {
        c64.console.print("ENTRY LOADED\n", .{});
    } else {
        c64.console.print("ENTRY EMPTY\n", .{});
    }

    if (Rules.tick(5)) |count| {
        if (Rules.ready(3)) |flag| {
            if (Rules.widen(0x1234)) |word| {
                c64.console.print("BYTE {x} WORD {x16}\n", .{ count, word });
                if (count == 6 and flag == false and word == 0x1335) {
                    c64.console.print("FALSE IS A RESULT\n", .{});
                    c64.vic.border = 5;
                }
            }
        }
    } else {
        c64.console.print("DLL UNAVAILABLE\n", .{});
        c64.vic.border = 2;
    }
}
PolicyWhat main prints firstWhat starts the disk load
PreloadENTRY LOADED when startup found the fileGenerated startup
On demandENTRY EMPTYThe first call to Rules.tick
ManualENTRY EMPTYThe explicit loadFromDisk call

In every successful run, the byte is 06, the word is 1335, and the Boolean export returns false. The capture branch runs for a present Boolean even when its value is false. With the on-demand disk entry absent, the first call returns null and the program prints DLL UNAVAILABLE. An embedded load() instead seeds the current row from the resident PRG, as in the embedded walkthrough.

Complete on-demand source

Choose an export signature the loader can call

ABI 1 calls use stack-frame exports with supported scalar parameters and return types. Booleans, bytes, and byte enums occupy one byte. Words and usize occupy two. The return byte comes back in A, and a word uses A for its low byte and X for its high byte. In the policy exercise the typed binding exposes each return as an optional because the row might be unavailable. The optional belongs to the caller-side operation.

Keep structured state in application memory and pass the fields the DLL needs. A source function in a static frame can accept and return a record. DLL dispatch rejects aggregate and optional exports, as well as pointer-shaped interfaces. Use a supported scalar result for status and test availability before interpreting it. The export signature also determines how many bytes the caller passes, so rebuild both ends together when changing widths.

Host assertions for byte, Boolean, and word results · Rejected aggregate export · Rejected optional export

Keep a module callable while callers still need it

A successful acquire takes a reference to the dependency. Release it after the work finishes. In this example two clients acquire the graph. The first release leaves the other client able to call MathCore. The last release makes the binding return null. The program then reacquires the graph and calls it again.

79_module_typed_dependency_graph_ownership.zp64
const c64 = @import("c64");

extern module MathCore = math_core {
    fn add(value: u8) u8;
}

memory {
    region call_stack: c64 at 0xc800 size 0x0400;
    region module_window: c64 at 0xc000 size 0x0800;
    region module_cache: reu at 0x030000 size 0x002000;
    region staging_ram: c64 at 0x9000 size 0x0800;

    stack in call_stack;
}

module_loader {
    window main in module_window;
    reu_cache in module_cache;
    disk_staging in staging_ram;
    capacity = 4;
    current {
        file = "enemyown";
    }
    dependency math_core {
        file = "mathcore";
        requires = .{.fixed_math};
    }
    dependency pathing {
        file = "pathing";
        requires = .{};
    }
    dependency fixed_math {
        file = "fixedmath";
        requires = .{};
    }
}

module enemy_typed_graph_ownership abi 1 {
    export tick;
    dependency math_core;
    dependency pathing;
}

fn tick(state: u8) callconv(.stack) u8 {
    return state + 1;
}

export fn main() void {
    c64.console.clear();
    var ok = false;
    if (MathCore.acquireGraph()) {
        if (MathCore.acquireGraph()) {
            MathCore.releaseGraph();
            if (MathCore.add(3)) |first| {
                MathCore.releaseGraph();
                if (MathCore.add(3) == null and MathCore.acquireGraph()) {
                    if (MathCore.add(4)) |second| {
                        if (first == 5 and second == 6) {
                            ok = true;
                        }
                    }
                }
            }
        }
    }
    c64.console.print("MODULE TYPED GRAPH OWNERSHIP\n", .{});
    if (ok) {
        c64.console.print("TYPED GRAPH OWNERSHIP OK\n", .{});
        c64.vic.border = 5;
    } else {
        c64.console.print("TYPED GRAPH OWNERSHIP BAD\n", .{});
        c64.vic.border = 2;
    }
}

Expect TYPED GRAPH OWNERSHIP OK. Follow the disk walkthrough for the producer and packaging steps. Use demo 79 as the caller and keep the two producer payloads on the disk.

Load prerequisites and recover from a failed graph load

Declare graph edges with requires on each participating row, including an empty list for a leaf. The compiler checks missing nodes and cycles. The loader visits prerequisites first. On failure it rolls back rows or references introduced by that operation. A dependency row can opt into the graph path with graph = true under preload or on-demand policy.

Declare a graph policy

Dependency row · configuration excerpt
dependency math_core {
    file = "mathcore";
    load = .on_demand;
    graph = true;
    requires = .{.fixed_math};
}

dependency fixed_math {
    file = "fixedmath";
    requires = .{};
}

Check a missing dependency

Call site · excerpt
if (MathCore.add(3)) |sum| {
    c64.console.print("SUM {x}\n", .{sum});
} else {
    c64.console.print("CHECK MATHCORE AND FIXEDMATH\n", .{});
}

Loading a graph makes its modules available in REU. It does not invoke their exports. To call a transitive module such as FixedMath, declare its binding and provide its sidecars at build time. A typed transitive binding can call its exports after a direct dependency loads the graph. It cannot independently acquire that transitive graph through the same binding.

On-demand graph demo · Preload graph demo · Rollback when disk load fails · Call a typed transitive dependency

Keep startup residency separate from a client's reference

With load = .preload; and graph = true;, startup loads FixedMath before MathCore. Each starts with one reference. A client can take a separate reference for its work and release it without clearing startup residency.

Use a preloaded dependency · excerpt
if (MathCore.acquireGraph()) {
    if (MathCore.add(3)) |sum| {
        c64.console.print("SUM {x}\n", .{sum});
    }
    MathCore.releaseGraph();
}

Keep the initial references while your program wants the feature available. Release those only when the program owns them and has finished using the graph. The loading policy exercise shows when the load happens.

Read the loader registry while diagnosing a failed call

Row 0 describes the current module. Direct dependencies follow their declared order. Transitive dependencies follow in first-seen order. In the missing-prerequisite fixture, that makes math_core row 1 and fixed_math row 3. A row can exist before any disk load succeeds. Its loaded byte answers whether the payload is available. Its refcount records ownership. The active-row byte belongs to the C64 execution window and can change without either module losing its REU residency.

Here the disk contains mathcore but omits fixedmath. The loader visits fixed_math first. The graph operation reports failure, and both rows remain unloaded with zero references. Inspect loaded state with the public API or use generated labels to find the registry bytes in the VICE monitor. If your program has already taken a reference, pair its successful acquisition with its own release. A failed operation rolls back the references it took, so an existing owner remains responsible for its reference.

In the registry-initialization fixture, all three rows start unloaded. Their cache slots begin at 030000, 030800, and 031000. Each gets one window-sized slot in that configuration. Increasing the number of rows consumes more REU capacity, even when the disk payloads are small. Registry rows and initial cache contents · Failed prerequisite load · Shared graph ownership

Preserve an existing owner when a later graph load fails

MathCore is already available. The program tries to acquire Pathing, which also needs MathCore. The disk contains MathCore and omits Pathing. The failed graph load unwinds its own reference, so the existing MathCore caller can still calculate a result.

dll-rollback.zp64
const ZeroPage = @import("ZeroPage");
const c64 = @import("c64");

extern module MathCore = math_core {
    fn add(value: u8) u8;
}

memory {
    region frames: c64 at 0xc800 size 0x0400;
    region execution: c64 at 0xc000 size 0x0800;
    region cache: reu at 0x030000 size 0x1800;
    region staging: c64 at 0x9000 size 0x0800;
    stack in frames;
}

module_loader {
    window main in execution;
    reu_cache in cache;
    disk_staging in staging;
    capacity = 3;

    current {
        file = "rollback";
    }
    dependency math_core {
        file = "mathcore";
        requires = .{};
    }
    dependency pathing {
        file = "pathing";
        requires = .{ .math_core };
    }
}

module rollback_demo abi 1 {
    export tick;
    dependency math_core;
    dependency pathing;
}

fn tick(value: u8) callconv(.stack) u8 {
    return value + 1;
}

fn pathingUnavailable() bool {
    if (ZeroPage.module.acquireDependencyGraph("pathing")) {
        ZeroPage.module.releaseDependencyGraph("pathing");
        return false;
    }
    return ZeroPage.module.isLoaded("pathing") == false;
}

export fn main() void {
    c64.console.clear();
    var ok = false;
    if (MathCore.acquire()) {
        if (pathingUnavailable()) {
            if (MathCore.add(3)) |value| {
                ok = value == 5;
            }
        }
        MathCore.release();
    }
    if (ok) {
        c64.console.print("MATH STILL AVAILABLE\n", .{});
        c64.vic.border = 5;
    } else {
        c64.console.print("CHECK THE DISK\n", .{});
        c64.vic.border = 2;
    }
}

Expect MATH STILL AVAILABLE. The program releases its original MathCore reference when it finishes. Release a graph only after its acquire reports success.

Choose a visible window or RAM under ROM

A visible RAM window is the easiest place to start. If you need more visible RAM for the main program, put the window under BASIC or KERNAL ROM. The range must fit entirely within the selected bank. The loader restores the processor port after the banked operation.

Under BASIC ROM

Region inside memory
region module_window: c64 at 0xa000 size 0x0800
    bank .ram_under_basic;

Under KERNAL ROM

Region inside memory
region module_window: c64 at 0xe000 size 0x0800
    bank .ram_under_kernal;

The KERNAL path also preserves processor status and masks IRQs while KERNAL is hidden. Keep these exports independent of KERNAL services. ZeroPage supports a resident trampoline for supported console calls. Keyboard, raw KERNAL, disk, and unsupported inline assembly paths are rejected for this bank. Use a visible window when the export needs those services.

BASIC-bank demo · KERNAL-bank demo · Console trampoline demo · Fixture checking that $0001 is restored

Print from a DLL that runs under KERNAL ROM

Put a simple banner export in a window at $e000. While the DLL runs, KERNAL ROM is hidden so the CPU can fetch the DLL's instructions from RAM. The compiler accepts supported c64.console output in this export and emits a console trampoline path. In this demo the trampoline calls the screen-writing console helpers. A direct call into the hidden ROM would have a different target.

93_module_kernal_console_trampoline.zp64
const c64 = @import("c64");
const ZeroPage = @import("ZeroPage");

memory {
    region call_stack: c64 at 0xc800 size 0x0400;
    region module_window: c64 at 0xe000 size 0x0800 bank .ram_under_kernal;
    region module_cache: reu at 0x030000 size 0x010000;

    stack in call_stack;
}

module_loader {
    window main in module_window;
    reu_cache in module_cache;
}

module enemy_kernal_console abi 1 {
    export banner;
}

fn banner() callconv(.stack) u8 {
    c64.console.print("TRAMP EXPORT\n", .{});
    return 5;
}

export fn main() void {
    c64.console.clear();
    var ok = false;
    if (ZeroPage.module.load("enemy_kernal_console")) {
        if (ZeroPage.module.call("enemy_kernal_console", "banner", .{})) |value| {
            ok = value == 5;
        }
    }

    c64.console.print("\nMODULE KERNAL TRAMP\n", .{});
    if (ok) {
        c64.console.print("TRAMP OK\n", .{});
        c64.vic.border = 5;
    } else {
        c64.console.print("TRAMP BAD\n", .{});
        c64.vic.border = 2;
    }
}

Open the complete source

Expect TRAMP EXPORT from the DLL and TRAMP OK from the caller. The bank gateway saves the processor port, masks IRQs, exposes RAM for dispatch, preserves the return value across cleanup, and restores the caller's mapping. The host fixture checks $0001 before loading, after loading, and after calling. Its initial and final value is $37.

If the export needs a key, read it in the resident caller and pass a byte argument. The keyboard example below is rejected because it requests the KERNAL-dependent read inside the export. A visible window avoids the bank transition for code that needs supported ROM services. Rejected keyboard read in an export · Port and return-value assertions · Banking contract

Choose which state survives activation

When a new DLL takes a window, the loader copies a fresh image over the old contents. Use persist_in_reu for selected state bytes that must survive. The state offset is relative to the start of the execution window. For state at $c100 in a $c000 window, the offset is $0100. Use discard_on_unload when an unload should discard that row's state. These policies are mutually exclusive for a row.

Keep two bytes across activations · configuration excerpt
current {
    persist_in_reu at 0x0100 size 2;
}

Persistent ranges are saved separately from the payload before replacement or final unload and restored after copy and relocation. They consume REU capacity. The compiler checks bounds, overlap, and available cache space. Write two bytes, unload, clear the window, and reload · State and cache reservations

Trace one byte through unload and reload

Before loading, tick(5) calls the resident function and returns 6. Counter.tick(5) goes through the export table and returns null while the module is unavailable. After Counter.load(), the binding returns 6. The program writes that value at $c780, an offset of $0780 into the active window at $c000.

dll-state-cycle.zp64
const c64 = @import("c64");

extern module Counter = counter {
    fn tick(value: u8) u8;
}

memory {
    region frames: c64 at 0xc800 size 0x0400;
    region execution: c64 at 0xc000 size 0x0800;
    region cache: reu at 0x030000 size 0x1000;
    stack in frames;
}

module_loader {
    window main in execution;
    reu_cache in cache;
    current {
        persist_in_reu at 0x0780 size 1;
    }
}

module counter abi 1 {
    export tick;
}

fn tick(value: u8) callconv(.stack) u8 {
    return value + 1;
}

fn checkCycle() bool {
    const state: *volatile u8 = @ptrFromInt(0xc780);

    // The direct call works before the DLL is loaded.
    if (tick(5) != 6 or Counter.tick(5) != null) {
        return false;
    }
    if (Counter.load() == false) {
        return false;
    }
    if (Counter.tick(5)) |value| {
        state.* = value;
    } else {
        return false;
    }

    Counter.unload();
    state.* = 0;
    if (tick(5) != 6 or Counter.tick(5) != null) {
        return false;
    }
    if (Counter.load() == false) {
        return false;
    }

    const restored = state.*;
    c64.console.print("STATE {x}\n", .{restored});
    return restored == 6;
}

export fn main() void {
    c64.console.clear();
    if (checkCycle()) {
        c64.console.print("STATE CYCLE OK\n", .{});
        c64.vic.border = 5;
    } else {
        c64.console.print("STATE CYCLE FAILED\n", .{});
        c64.vic.border = 2;
    }
}

Open the complete source

Unload saves the declared byte, then clears the row's callability. The program writes zero to the old location to prove that the next read depends on restoration. The direct function still returns 6. The binding returns null until the next load. Reload activates a fresh copy and restores the saved byte. Expect STATE 06 and STATE CYCLE OK.

In the module sidecar, state.current.snapshot_reu_addr gives the snapshot base $030800. Add the declared offset $0780 to find the saved byte at $030f80. The payload slot and the snapshot slot have separate jobs. Check the relocation sidecar's payload length before choosing a state offset. In this build, the payload ends before the byte at offset $0780. Declare only the state the DLL must keep.

Replace persist_in_reu at 0x0780 size 1; with discard_on_unload; and rebuild. In this run the byte reads 00, and the check reports STATE CYCLE FAILED. The test deliberately clears the window between loads. The discard policy leaves no snapshot for the loader to restore.

Read a two-window memory plan

The disk and REU cache exercise reserves two independent execution windows. Only the auxiliary one is exercised by the MathCore and FixedMath calls. The current module's tick calls in this example are direct resident calls. A separate window gives the loader room to keep a different row active there if the program uses it.

ResourceAddress rangeRole in the example
Auxiliary windowC64 $6000–$67ffMathCore and FixedMath alternate here.
Disk stagingC64 $9000–$97ffKERNAL reads each payload here before it goes to REU.
Main windowC64 $c000–$c7ffDefault window for unassigned rows.
Software stackC64 $c800–$cbffFrames for module calls and scalar helpers.
Cache reservationREU $030000–$033fffPayload slots plus space for declared saved state.

Inspect the caller's .zpmod.json. loader.load_windows lists the two address ranges. loader.window_assignments maps MathCore row 1 and FixedMath row 3 to aux. dependency_graph.rows includes the transitive row. state.deps shows the MathCore snapshot address $032800 for this configuration. Its two source bytes are at $6400–$6401 while MathCore owns the auxiliary window.

Change one declaration at a time while planning your own layout. Moving the window changes where the caller dispatches, where the relocation applies, and where window-relative state lives. Keep the RAM reservations disjoint and rebuild the caller against matching producer artifacts. Complete caller and memory plan · Region overlap and bank rules

Keep two DLLs active at the same time

Assign Pathing to the main window at $c000 and FixedMath to aux at $6000. Acquire and call each one. Both stay active until displaced in their own window or finally released.

Use both windows · excerpt
if (Pathing.acquire()) {
    if (Pathing.step(5)) |position| {
        c64.console.print("POSITION {x}\n", .{position});
        if (FixedMath.acquire()) {
            if (FixedMath.bias(4)) |score| {
                c64.console.print("SCORE {x}\n", .{score});
            }
            FixedMath.release();
        }
    }
    Pathing.release();
}

The calls produce 8 and 7. Before either release, inspect the export jump tables at $c000 and $6000. Separate windows keep more code in C64 RAM. A shared window trades activation work for a smaller RAM reservation.

Know which file goes where

FileWho uses it
.zpmod.jsonCaller build and inspection. Describes ids, ABI, export signatures and ordinals.
.zpmod.relocsim.jsonCaller build and inspection. Records the relocation plan and its simulation.
.zpmodHost tooling. Versioned binary with metadata and payload.
.zpmod.disk.prgC64 disk loader. Put it on the D64 under the declared disk filename.
.zpmod.diskmanifest.jsonDisk packaging, when configured. Describes filenames and payload placement.

Exports are ordered from zero. The payload begins with one three-byte JMP per export, so dispatch uses window_base + ordinal * 3. The compiler emits relocation records for known addresses, including full 16-bit operands and separate low and high bytes. The target uses compiled rows and ordinals. It reads the disk payload without parsing the build sidecars. Read-only data relocation demo · Format and relocation details

Trace an internal call and a table pointer into RAM

Read this module with its execution window at $8000. The first jump at $8000 dispatches export 0, tick. The second at $8003 dispatches export 1, table_ptr. Moving the payload also moves its private bump helper and reloc_table. Code that refers to them needs their new addresses.

Complete relocation simulation demo
const c64 = @import("c64");

const reloc_table = [_]u8{ 3, 5, 8, 13 };

memory {
    region call_stack: c64 at 0xc800 size 0x0400;
    region module_window: c64 at 0x8000 size 0x1000;
    region module_cache: reu at 0x020000 size 0x010000;

    stack in call_stack;
}

module_loader {
    window main in module_window;
    reu_cache in module_cache;
}

module enemy_reloc_sim abi 1 {
    export tick;
    export table_ptr = tablePtr;
}

fn bump(value: u8) callconv(.stack) u8 {
    return value + 1;
}

fn tick(value: u8) callconv(.stack) u8 {
    return bump(value);
}

fn tablePtr() callconv(.stack) usize {
    return @intFromPtr(&reloc_table[1]);
}

export fn main() void {
    c64.console.clear();
    c64.console.print("MODULE RELOC SIM\n", .{});
    c64.console.print("SIM OK\n", .{});
    c64.vic.border = 5;
}

Open applied_relocations in the simulation sidecar. The following records show one build. Addresses and offsets can change after recompiling. Follow the target name and kind in your output.

TargetRecordBytes beforeBytes after
bumpabs1696 0806 80
reloc_table[1]hi80a82
reloc_table[1]lo8c838

The first pair changes an absolute operand from $0896 to $8006. The table records carry an addend of one for the element index. The adjusted address becomes $8238, with the two bytes patched at separate offsets. The simulation shows the patch plan. For a program that actually activates a DLL, use the runtime window demo. Treat a pointer into a shared window as valid only while that DLL remains active there.

Runtime load and activation example · Relocation record reference

Tell a build error from an unavailable call

What you seeWhat to check
Binding signature rejectedMatch the export name, argument types, and return type. Rebuild stale sidecars. Signature mismatch fixture
Graph or placement rejectedCheck graph rows and edges, window visibility, reserved ranges, and REU capacity. Cycle fixture · Cache sizing fixture
load fails or the call returns nullCheck REU setup, the disk entry, and whether the row is still loaded. In manual mode, ensure the load succeeded before calling. Call before loading fixture

Declare your binding in the caller and call it from a supported static-frame context. DLL export implementations use the software-stack convention. The compiler rejects unsupported loader calls within software-stack functions. The standalone fixed-address cache described here also differs from the proposed ReadyOS host-managed cache. ReadyOS integration boundary

Package the same DLL for two applications

Build the fixed_math producer once. Its export accepts one byte, adds three, and returns a byte. The score updater acquires it explicitly while the calculator below loads it on demand. The loading policy belongs to each caller's dependency row. Both bind the same export signature and use the same execution window and staging address. Each disk gets the same producer payload under fixedmath.

Complete calculator caller
const c64 = @import("c64");

extern module FixedMath = fixed_math {
    fn bias(value: u8) u8;
}

memory {
    region window_ram: c64 at 0x6000 size 0x1000;
    region staging_ram: c64 at 0x9000 size 0x0800;
    region frame_ram: c64 at 0xc800 size 0x0400;
    region module_cache: reu at 0x030000 size 0x2000;
    stack in frame_ram;
}

module_loader {
    window main in window_ram;
    disk_staging in staging_ram;
    reu_cache in module_cache;
    capacity = 2;
    current {
        file = "calculator";
    }
    dependency fixed_math {
        file = "fixedmath";
        load = .on_demand;
    }
}

module calculator abi 1 {
    export base;
    dependency fixed_math;
}

fn base() callconv(.stack) u8 {
    return 0x20;
}

export fn main() void {
    c64.console.clear();
    const input = base();
    if (FixedMath.bias(input)) |value| {
        c64.console.print("BIAS {x}\n", .{value});
        c64.vic.border = 5;
    } else {
        c64.console.print("FIXEDMATH UNAVAILABLE\n", .{});
        c64.vic.border = 2;
    }
}

The calculator passes $20 and prints BIAS 23. The score updater passes the current round count, adds the result to a far record, and prints MEMORY PLAN OK. The calculator evaluates base() before calling the binding. The preview rejects a nested user call in an argument to a software-stack bridge.

Producer outputUsed byWhat it supplies
math.prg.zpmod.jsonBoth caller buildsModule ID, ABI, export signatures and ordinals.
math.prg.zpmod.relocsim.jsonBoth caller buildsPayload size, window and relocation information.
math.prg.zpmod.disk.prgBoth D64 imagesThe bytes KERNAL loads when the caller asks for fixedmath.

Keep these three outputs together. If you change a signature, export order, or window contract, rebuild the caller and replace the disk entry from the matching producer build. Each caller's disk manifest describes packaging names. The calculator's current.file names its own module row. The boot entry is a separate PRG named boot for this exercise, and the calculator only loads its dependency from disk.

Producer source · Calculator source · Dependency sidecar options

Use a producer built for a different window

By default, the caller expects an unassigned dependency's producer window to match its main window in address and size. In the calculator, that is $6000 with $1000 bytes. Change the producer to $7000 with $0800 bytes and the default caller rejects its sidecars.

An explicit window assignment enables relocation to that named destination. Add window = main; to the calculator's dependency fixed_math block. The producer's declared window size must fit within the destination window, and the payload and export requirements must fit too. This example boots with the same BIAS 23. Its first jump instruction at $6000 points to $6003, inside the caller's window. The producer still uses disk staging at $9000.

To see the diagnostic, use the original calculator source with the same new producer sidecars. A valid assignment only resolves the window constraint. The caller still checks the module ID, ABI, export signatures, and bank requirements. Window compatibility reference · How the loader patches addresses

Check what actually made it onto the disk

A successful build proves the binding and the sidecars agree. The disk can still contain an older file under the right name. Starting with the typed disk exercise, list the D64 directory and extract enemyrt. Compare its bytes with the .zpmod.disk.prg generated by the same build. An empty cmp result with exit status zero means the files match. Rebuild the disk from the matching caller and producer outputs if they differ.

The first two bytes of the disk payload in this example are 00 90, the little-endian staging address $9000. The next byte, 4c, starts the export jump table. One preview build has a 900-byte disk file, which is an 898-byte payload plus the header. Use your build's file size. Fit the payload inside disk staging as well as its execution window and REU slot. The boot PRG and the payload PRG have separate jobs and their bytes differ.

Use the compiler-generated payload and compare it before booting a suspect disk. The runtime uses the caller's compiled length and relocation plan when activating the module. It does not verify that disk bytes match the producer's sidecars. The dependency load path checks the KERNAL result and the returned byte count against its loader limit after KERNAL has written staging RAM. Keep every packaged payload within the reserved staging range. Disk, cache, and activation contracts