Guide · Chapter 11 of 14

Plan a program that uses disk, REU, and RAM

Build a score updater that combines a disk DLL, an application REU arena, and a near working copy.

Jump to a section

Update a score with rules loaded from disk

Keep a score record in REU, materialize it into C64 RAM, call a scoring rule loaded from disk, then flush the update. The initial total is $0200 and the round count is 3. The DLL adds 3 to the round count it receives and returns 6 points. The program adds those points to the total and increments the stored round count to 4. A fresh far read checks both changes.

This exercise brings together arenas, materialized views, and typed disk calls. The score record and the DLL both use REU, and each needs its own address range and lifetime.

Assign a region to each owner

RegionAddressesContents and lifetime
ExecutionC64 $6000–$6fffActive DLL code and its jump table. The CPU executes here.
ScratchC64 $8000–$80ffThe three-byte near score view, until the edit and flush finish.
Disk stagingC64 $9000–$97ffTemporary buffer for the disk payload.
FramesC64 $c800–$cbffSoftware-stack frames for the scoring export and other stack calls.
ScoresREU $010000–$0100ffApplication data. The far arena owns the score record until reset.
CacheREU $030000–$031fffTwo window-sized payload slots. FixedMath is row 1, so its slot begins at $031000.

The ranges in the table include the last byte. The map records exclusive ends. The application reserves the current module's slot at $030000 as part of the registry plan. This run uses only the dependency's slot. The scoring export calls through the execution window while the near score remains live in scratch RAM.

Compile the scoring DLL first

The producer declares the fixed_math module and its stack-frame export. Its assembly contains a small bias routine. The compiler writes the metadata and relocation sidecars the caller needs and a disk payload with a load header for the configured staging address. The producer's main is empty because the exercise boots the application.

memory-plan-math.zp64
memory {
    region call_stack: c64 at 0xc800 size 0x0400;
    region module_window: c64 at 0x6000 size 0x1000;
    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 fixed_math abi 1 {
    export bias;
}

fn bias(value: u8) callconv(.stack) u8 {
    return value + 3;
}

export fn main() void {}

Complete scoring DLL source

Acquire, call, flush, and release

The caller declares the same signature in extern module and names the disk entry in its loader. FixedMath.acquire() gives the caller a reference. FixedMath.bias() activates the DLL as needed and returns an optional value. The near edit is committed with flush. Only then does the program reset scratch and read the score again from REU. It releases FixedMath on both paths after successful acquire.

memory-plan.zp64
const c64 = @import("c64");
const ZeroPage = @import("ZeroPage");

const Score = struct { total: u16, rounds: u8 };

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

memory {
    region scratch_ram: c64 at 0x8000 size 0x0100;
    region disk_ram: c64 at 0x9000 size 0x0800;
    region execution_ram: c64 at 0x6000 size 0x1000;
    region frame_ram: c64 at 0xc800 size 0x0400;
    region score_reu: reu at 0x010000 size 0x0100;
    region cache_reu: reu at 0x030000 size 0x2000;

    arena scratch in scratch_ram;
    arena scores in score_reu;
    stack in frame_ram;
}

module_loader {
    window main in execution_ram;
    reu_cache in cache_reu;
    disk_staging in disk_ram;
    capacity = 2;
    current {
        file = "scoreapp";
    }
    dependency fixed_math {
        file = "fixedmath";
    }
}

module score_app abi 1 {
    export round_limit = roundLimit;
    dependency fixed_math;
}

fn roundLimit() callconv(.stack) u8 {
    return 4;
}

fn play() bool {
    if (ZeroPage.reu.present() == false) {
        return false;
    }
    if (FixedMath.acquire() == false) {
        return false;
    }
    if (scores.allocBytes(@sizeOf(Score))) |bytes| {
        var table = ZeroPage.reu.view(Score, bytes, 1);
        table.set(0, Score{ .total = 0x0200, .rounds = 3 });
        if (table.materialize(scratch)) |local| {
            var score = local.get(0);
            if (FixedMath.bias(score.rounds)) |points| {
                score.total += @as(u16, points);
                score.rounds += 1;
                local.set(0, score);
                table.flush(local);
                scratch.reset();
                const saved = table.get(0);
                scores.reset();
                FixedMath.release();
                return saved.total == 0x0206 and saved.rounds == roundLimit();
            }
        }
    }
    scratch.reset();
    scores.reset();
    FixedMath.release();
    return false;
}

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

The current module declaration provides the application row and its own export. The app calls roundLimit() directly from resident code for its final check. Only the FixedMath dependency needs a separate disk entry in this exercise.

Complete score application source

Expect MEMORY PLAN OK and a green border. Inspect memory_regions in the caller's .zpmap.json and loader in its .zpmod.json to connect the layout to the generated artifacts.

Diagnose three failures at the stage that reports them

Change to tryWhat you observeRepair
Move score_reu to 0x030000.The compiler rejects overlapping regions. Application data would occupy the same REU range as the cache.Restore the score arena to 0x010000 and keep raw transfers within the owning region.
Declare FixedMath.bias with a u16 parameter in the caller.The compiler rejects the dependency sidecar. The caller expects a word and the producer exports a byte argument.Restore u8, or change and rebuild both sides together. Check module id, ABI, and window if the same diagnostic persists.
Build a second disk with only the boot entry.The app boots, acquire fails, and the screen shows MEMORY PLAN FAILED with a red border.Write the producer's .zpmod.disk.prg under fixedmath and boot again with the REU enabled.

The missing-disk command uses the score_build variable from the build command. Use the same shell. If you open a new shell, set it to the directory created by mktemp.

Host fixture checking the arena and DLL byte locations · Compile-fail fixture for a cache overlap · DLL diagnostics