1. Match the export to the caller
A ZeroPage DLL is a separately callable block of 6510 code with a declared export list. An app can keep several DLLs in REU storage and give them the same small slice of C64 RAM in which to run. This chapter starts with one export, adds a disk payload, then follows a window swap. The companion chapter covers loading policies, failure handling, ownership, banking, and sidecars.
We'll call tick(5) and get 6. In the first example, the producer and caller are in one source file. On the left, the producer defines a module called region_dll and lists what it exports. On the right, the caller gives that module the local name RegionDll and declares the signature it expects.
Producer
module region_dll abi 1 {
export tick;
}
fn tick(value: u8) callconv(.stack) u8 {
return value + 1;
}
Caller
extern module RegionDll = region_dll {
fn tick(value: u8) u8;
}
// Inside main:
if (RegionDll.load()) {
if (RegionDll.tick(5)) |value| {
ok = value == 6;
}
}
abi 1selects the module's calling contract.export tickputstickin the first export slot.callconv(.stack)gives the implementation the calling convention required by DLL exports.- Match the module id, export name, argument types, and return type.
RegionDllis a local name you choose. The compiler checks the signature against this source, or against the producer's sidecars when you build a separate dependency. load()reports whether the module is ready.tick(5)has type?u8: the signature promises a byte on success, andnullrepresents an unavailable call.|value|gives you the byte only on success.
Calling tick(5) directly inside the producer calls its resident implementation. Calling RegionDll.tick(5) goes through the loader and the export table. The compiler resolves the typed call to a module row and an export slot during the build. Module API reference
2. Build and run the embedded example
Start with a working zp64c and VICE. The example declares the memory map below. Follow the names from region to stack, window, and reu_cache to see what owns each range. The near arena is used by the demo for two data bytes alongside the DLL.
What you declare
memory {
region near_arena: c64 at 0x9000 size 0x0100;
region module_window: c64 at 0xc000 size 0x0800;
region software_stack: c64 at 0xc800 size 0x0400;
region module_cache: reu at 0x030000 size 0x010000;
stack in software_stack;
arena near_heap in near_arena;
}
module_loader {
window main in module_window;
reu_cache in module_cache;
}
How the regions are used
Resident PRG
↓ load()
REU payload cache $030000
↓ activate and relocate
C64 code window $c000
↓ call tick through export slot 0
C64 software stack $c800
Notice that the REU address and the C64 window address name different address spaces. The first load() copies the export table and payload from the resident PRG into the REU cache at $030000. The loader activates the module by copying it to C64 RAM at $c000 and patching addresses for that location. The 6510 runs the code from the C64 window. The software stack at $c800 supplies the export's call frame.
Look for REGION DLL CACHE OK and a green border. This program needs the PRG and an enabled REU. You can run it without a D64. Install and build
3. Load the same export from disk in two ways
Both programs below load the disk entry enemyrt and call the border export of enemy_runtime. The export adds two to its argument, so passing 3 sets the VIC-II border to color 5. Each program reports a load failure separately from an unavailable call.
Named invocation
export fn main() void {
c64.console.clear();
c64.console.print("DISK LOAD REAL\n", .{});
if (ZeroPage.module.loadFromDisk("enemy_runtime", "enemyrt")) {
const maybe_border = ZeroPage.module.call("enemy_runtime", "border", .{3});
if (maybe_border) |border| {
c64.console.print("REAL LOAD OK\n", .{});
c64.vic.border = border;
} else {
c64.console.print("REAL CALL FAIL\n", .{});
c64.vic.border = 2;
}
} else {
c64.console.print("REAL LOAD FAIL\n", .{});
c64.vic.border = 2;
}
}
Typed invocation
export fn main() void {
c64.console.clear();
c64.console.print("DISK LOAD REAL\n", .{});
if (EnemyRuntime.loadFromDisk("enemyrt")) {
const maybe_border = EnemyRuntime.border(3);
if (maybe_border) |border| {
c64.console.print("REAL LOAD OK\n", .{});
c64.vic.border = border;
} else {
c64.console.print("REAL CALL FAIL\n", .{});
c64.vic.border = 2;
}
} else {
c64.console.print("REAL LOAD FAIL\n", .{});
c64.vic.border = 2;
}
}
The named version supplies three pieces to module.call: the module id, the export name, and the argument tuple .{3}. The typed version takes its module id and signature from extern module, then uses normal call arguments. Both resolve the export during compilation. The runtime part is loading the bytes and deciding whether the module can be called. Both calls return ?u8.
Named caller import
const ZeroPage = @import("ZeroPage");
Typed caller binding
extern module EnemyRuntime = enemy_runtime {
fn border(seed: u8) u8;
}
Configuration shared by both programs
Disk loading uses visible C64 staging RAM at $9000. KERNAL reads the disk PRG into staging. The loader copies the payload to the REU cache, activates it at $c000, and applies relocation before dispatch. The public export name border comes from export border = borderColor;.
memory {
region call_stack: c64 at 0xc800 size 0x0400;
region module_window: c64 at 0xc000 size 0x0800;
region module_cache: reu at 0x030000 size 0x010000;
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;
}
module enemy_runtime abi 1 {
export border = borderColor;
}
fn borderColor(seed: u8) callconv(.stack) u8 {
return seed + 2;
}
Complete named source · Complete typed source
Expect REAL LOAD OK and a green border in both versions. Try removing enemyrt from a copy of either disk. The same program should report REAL LOAD FAIL and set a red border. For an example that checks null after unloading and then calls successfully after reloading, see the typed lifecycle demo.
4. Reuse the REU cache when two modules share RAM
Imagine a larger program with two independently built DLLs. Both fit at $6000, but you want to spend RAM on just one execution window. Give each DLL its own REU slot and assign both to the same named window. This example declares FixedMath as a prerequisite of MathCore, so a graph acquire can load both together.
Where they run
window aux in aux_window;
dependency math_core {
file = "mathcore";
window = aux;
requires = .{.fixed_math};
persist_in_reu at 0x0400 size 2;
}
dependency fixed_math {
file = "fixedmath";
window = aux;
requires = .{};
}
When they run
if (MathCore.acquireGraph()) {
const first = MathCore.add(3); // ?u8: 5
const second = FixedMath.bias(4); // ?u8: 7
const third = MathCore.add(4); // ?u8: 6
MathCore.releaseGraph();
}
| Step | Where the bytes come from | What runs at $6000 |
|---|---|---|
MathCore.acquireGraph() | Disk fills both REU cache slots. | Neither DLL needs to be active yet. |
MathCore.add(3) | MathCore's REU slot | MathCore |
FixedMath.bias(4) | FixedMath's REU slot | FixedMath replaces MathCore. |
MathCore.add(4) | MathCore's existing REU slot | MathCore returns without another disk read. |
The complete demo writes two state bytes at $6400 while MathCore is active. persist_in_reu at 0x0400 size 2 tells the loader to save those bytes when MathCore leaves the window and restore them when it returns. The offset is relative to the window base. Payload bytes and saved state occupy separate REU slots.
Build the producers, then the caller
In this example the producer and caller are separate files. The producer can export several functions. The caller declares the one it uses.
MathCore producer
module math_core abi 1 {
export add;
export is_five = isFive;
export wide;
export table_ptr = tablePtr;
}
fn add(value: u8) callconv(.stack) u8 {
return bump(value);
}
Application caller
extern module MathCore = math_core {
fn add(value: u8) u8;
}
Compile each DLL first. The caller's --dependency-module and --dependency-relocsim options use the producer's sidecars to check signatures and prepare relocation. Put the .zpmod.disk.prg payloads on the disk for the C64 to load.
Build both DLLs and boot the shared-window disk
Look for TYPED WINDOW OK. Use a new output filename or remove the generated swap.d64 before reformatting. The complete source shows the MathCore producer, the FixedMath producer, and the caller. End-to-end tool requirements
Keep the four locations straight
| Location | Job | Example |
|---|---|---|
| Resident PRG or disk | Supplies the initial module bytes. | The embedded export, or the enemyrt disk entry. |
| C64 staging RAM | Receives the bytes from KERNAL disk load. | $9000 in the disk example. |
| REU cache | Keeps payloads available while other modules use the window. | Separate slots for MathCore and FixedMath. |
| C64 execution window | Holds relocated code and the export jump table for the active module. | $6000 for the shared window. |
A row can stay loaded in REU while another row owns its window. Sharing a window saves C64 RAM. Switching its owner costs an REU transfer and relocation. A call to an already active row uses its existing jump table. Final release clears the row's callability even if its old bytes are still present. Acquiring it again can require another load. Module ABI and sidecar format
Choose what to learn next
Continue with DLL loading, ownership, and banking. Its examples show what happens when a file is missing, how two clients share a dependency, what changes under ROM, and which build artifacts you need to inspect.