Guide · Chapter 9 of 14

Your first DLL on the C64

Export one function, call it through a typed binding, then watch the same loader use disk and reuse the REU cache.

Jump to a section

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

Export table and implementation
module region_dll abi 1 {
    export tick;
}

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

Caller

Binding and use inside main
extern module RegionDll = region_dll {
    fn tick(value: u8) u8;
}

// Inside main:
if (RegionDll.load()) {
    if (RegionDll.tick(5)) |value| {
        ok = value == 6;
    }
}
  1. abi 1 selects the module's calling contract. export tick puts tick in the first export slot. callconv(.stack) gives the implementation the calling convention required by DLL exports.
  2. Match the module id, export name, argument types, and return type. RegionDll is 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.
  3. load() reports whether the module is ready. tick(5) has type ?u8: the signature promises a byte on success, and null represents 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 and loader configuration
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

Embedded load · addresses from this example
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.

Open the complete source

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

Complete main from the disk demo
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

Complete main from the typed demo
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

Top of the named source
const ZeroPage = @import("ZeroPage");

Typed caller binding

Top of the typed source
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;.

Shared layout, export declaration, and implementation
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

Excerpt from module_loader
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

Call sequence inside main
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();
}
StepWhere the bytes come fromWhat runs at $6000
MathCore.acquireGraph()Disk fills both REU cache slots.Neither DLL needs to be active yet.
MathCore.add(3)MathCore's REU slotMathCore
FixedMath.bias(4)FixedMath's REU slotFixedMath replaces MathCore.
MathCore.add(4)MathCore's existing REU slotMathCore 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

From math_core_dispatch.zp64
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

From 85_module_typed_multi_window_binding.zp64
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.

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

LocationJobExample
Resident PRG or diskSupplies the initial module bytes.The embedded export, or the enemyrt disk entry.
C64 staging RAMReceives the bytes from KERNAL disk load.$9000 in the disk example.
REU cacheKeeps payloads available while other modules use the window.Separate slots for MathCore and FixedMath.
C64 execution windowHolds 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.

REU and DLL reference · ABI and relocation reference