Tutorial · Chapter 15 of 23

Build and call a disk-loaded DLL

Follow one export from source declaration to a disk payload and a running C64 call.

Jump to a section

Start with a function whose result you can predict

The border export takes one byte and adds two. Passing 3 should produce 5, the green border value. A stack-frame function implements that signature. The module declaration gives it the public name border. The disk entry enemyrt carries the payload, and enemy_runtime identifies the module in source.

Producer export

From the module declaration
module enemy_runtime abi 1 {
    export border = borderColor;
}

fn borderColor(seed: u8) callconv(.stack) u8 {
    return seed + 2;
}

Caller binding

From the typed version
extern module EnemyRuntime = enemy_runtime {
    fn border(seed: u8) u8;
}

Read the names from left to right. borderColor is the implementation. border is the public export. EnemyRuntime is the caller's local binding. The signature tells the compiler how to pass the argument and read the result. The stack declaration in the memory layout provides room for the export's frame.

Read the complete load and call sequence

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

In each version, handle the load result before calling. Then unwrap the optional export result. The typed version declares the export signature with extern module. The named version supplies the export name and an argument tuple at the call site. An export returning zero still produces a value. An empty optional means the call was unavailable.

Complete typed caller · Complete named caller

Follow the payload through four locations

LocationJob in this example
D64 entry enemyrtKERNAL reads the generated disk payload by this filename.
C64 RAM at $9000Staging receives the disk bytes.
REU at $030000The cache keeps a copy ready for activation.
C64 RAM at $c000The loader copies and relocates the payload here so the CPU can run it.

Staging can be reused after loading. The REU copy can stay available even after a different DLL replaces the active code in C64 RAM. The next chapter exercises that difference with two independent modules.

Build the disk and check both outcomes

Put the boot PRG and the generated DLL payload on the same D64. The payload file ends in .zpmod.disk.prg. Give that entry the name enemyrt so it matches the load call. Start VICE with an REU enabled. The loader stages the disk bytes in visible RAM, caches the payload in REU, and activates it in the C64 execution window.

Expect REAL LOAD OK with the payload present and REAL LOAD FAIL when it is missing. The sample builds the boot program and its export together. The next chapter builds two independent producers before compiling the caller.