ULTIMATEEXPERIMENTSCommodore 64 · Work in progress

Implementation plan for review

Development note: see current status, build instructions and installation for present qualification. Historical measurements below apply to their stated slice, not every current build.

2026-10-17 release steering: V1_ENDPOINT.md now defines the V1 exit gates and current work order. Installer/configuration, floppy/HD persistence and the full Turbo Pascal workflow are the priority. Further performance improvement and the 50%/85% speed objectives move to post-V1; the historical milestones below remain the broader backlog.

Original planning date: 2026-10-14, America/Los_Angeles. The milestone deliverables and exit criteria below remain the scope contract. Current implementation status is recorded separately from complete acceptance.

Implementation update 2026-10-15: genuine DOS 3.3 boots on the physical C64U, with actual 40/80-column VER, TYPE and DIR captures. CPU, REU memory, BIOS, text, HD and CGA have substantial tested implementations. Persistence integration, full utility coverage, physical HD/graphics/input acceptance and performance remain unfinished. Roughly 60% functional progress is a subjective scope estimate excluding performance, not a prediction of remaining effort. Exact current evidence and limitations are in agentworking/STATUS.md and agentworking/TEST_LOG.md.

Outcome and boundaries

A standalone PRG boots the supplied MS-DOS 3.3 in an emulated PC with 640 KiB conventional RAM, two floppy drives, keyboard, 40/80-column text, and limited CGA graphics. Guest execution uses the C64U's 64 MHz 6510; the REU stores guest memory, whole floppy images, and cached hard-disk extents. Native Ultimate DOS loads/saves image bytes. A KERNAL IEC backend supports development in VICE using D81 containers.

The first end-user workload is the supplied DOS command set. Full PC hardware fidelity, EGA/VGA, 8087, protected mode, sound, serial/parallel output, mouse, networking, and arbitrary third-party software are outside v1. Some minimal timer, interrupt, and port behavior remains necessary even without those peripherals.

The CPU profile is functionally 8086/8088, with original 8088 behavior chosen for edge cases and PC compatibility. Exact prefetch/bus timing is deferred. If later software depends on those details, record the incompatibility rather than quietly claiming complete IBM PC emulation.

Work sequence and gates

Milestone Bounded deliverable Exit evidence / dependency
M0 — reproducible foundation Pin ca65/ld65, Zig 0.16.0, Peddle; assembly PRG/raw-test targets; Zig assertions run linked routines; map checker; fixture manager An intentional assertion failure fails CI; a minimal routine passes and returns within budget; input images retain hashes; DOSBox-X boots a disposable disk-1 copy and confirms actual version/config behavior
M1 — hardware feasibility Small assembly probes for ALU, dispatch, address translation, cache hit/miss, REU DMA, bitmap rendering, and UCI image transfer Peddle CPU counts plus real C64U 1/16/64 MHz elapsed times and configuration; first page-size trade study; no extrapolated hardware speed claim from VICE
M2 — memory and devices One guest memory API, REU driver/model, 20-bit addressing, page cache, dirty write-back, bounded bulk copy, UCI state machine/file mock Zig property tests + real assembly Peddle tests; same REU test vectors in VICE/hardware; cache/IO ownership invariants; all ranges verified
M3 — CPU foundation Register state; instruction fetch; prefixes; ModR/M; MOV/ALU/flags/branches/stack; synthetic x86 test programs Defined SingleStepTests subsets and independent arithmetic oracle; every addressing form; aliases, cross-page operations, branch targets, stack edges
M4 — CPU completion for boot Remaining documented 8086 instructions; strings/REP; MUL/DIV; interrupt entry/IRET; TF/IF shadows; IN/OUT/HLT All declared documented instruction groups covered; original-CPU edge cases; interruptible REP and code modification; no unrecorded skips
M5 — native BIOS and first DOS boot Reset/IVT/BDA; disk INT 13h; video/keyboard/time/equipment/memory services; whole-image A:/B:; initial 40-column renderer Original disk-1 boot result recorded, minimal-config copy reaches prompt, VER, DIR, TYPE, command execution and keyboard work; show INT 21h executes DOS code
M6 — persistent floppy and VICE development Save/reload floppy image; Ultimate and IEC adapters; D81 packaging; error recovery Identical guest sector results in Peddle/UCI and VICE/IEC; saved image independently extracted and compared; full restart proves persistence; real C64U load/edit/save/reboot
M7 — usable text and DOS suite 80-column 4×8 renderer, colors policy, keyboard mapping, ANSI.SYS; internal commands and applicable included tools DOS acceptance matrix passes at 40/80 where meaningful; readable EDLIN/DEBUG interaction; paging/input/cursor/scroll tests and screenshots; error/abort paths
M8 — small hard disk Approximately 2 MiB raw disk, MBR/partition/CHS, file-offset adapter, bounded REU extent cache Guest FDISK → FORMAT → SYS → boot C:; cache forced smaller than disk; independent FAT/files check; data survives clean close/reopen and eviction
M9 — 20 MiB hard disk Same backend with larger offsets and image Accesses below/above 16 MiB, final sector, cache churn, disk-full/errors, flush/restart and utilities pass; no 24-bit file-offset truncation
M10 — CGA Guest modes 4/5/6, direct VRAM and BIOS pixel services, deterministic conversion Synthetic test cards and GW-BASIC from supplied disk 3 used as a later included-program test; reference pixels checked before downsampling; C64U visual approval
M11 — optimization and release Trace-driven hot paths, coherent fetch cache, safe REP acceleration, optional lazy flags All functional lanes remain green; memory map fits; measured performance report for every workload; documented limitations and reproducible user guide

Current milestone status — 2026-10-15

Milestone Current status
M0 Foundation and DOSBox-X reference boot verified.
M1 Hardware clock, REU, UCI and renderer evidence retained; matched performance baseline remains outstanding.
M2 Memory/cache/ownership and native UCI core implemented and tested; transport acceptance continues.
M3 CPU foundation implemented and tested.
M4 Documented CPU groups and original-8088 edge cases implemented/tested; exact corpus proofs remain tied to their executable/source identities.
M5 Core boot milestone achieved on physical C64U: genuine DOS/COMMAND.COM, VER, DIR, TYPE and MODE. Full B: and physical keyboard coverage remain.
M6 Native floppy SAVE/reopen passes actual assembly tests; standalone IEC/D81 import passes VICE. Production integration and physical save/reboot remain.
M7 Actual 40/80-column text and several DOS workflows pass. Full supplied-utility matrix, interactive editors/debugger, physical keyboard and readability acceptance remain.
M8 2 MiB backend/BIOS and genuine DOS model workflows tested. Physical guest-write/persistence acceptance remains.
M9 20 MiB addressing/cache boundary support tested. Physical scale, persistence/restart and utility acceptance remain.
M10 CGA4/5/6 and genuine DOS-loaded graphics probe verified in Peddle. Physical CGA and later GW-BASIC acceptance remain.
M11 Initial measured optimizations completed; near-XT speed has not been achieved. Matched benchmarks, further optimization and release work remain.

Current screenshot work follows the user's request for genuine DIR | MORE first-page captures in both modes. Native and physical pipeline/pagination, temporary-file cleanup, paired captures and full REU restoration pass. Earlier DIR /W pairs and complete REU restoration passed. See screenshots and performance assessment.

M1 can begin after the minimal M0 runner, before the entire reference-boot tooling is polished. M2's plain memory API should precede CPU work; aggressive paging optimization can follow CPU correctness. Do not make the full instruction suite wait for a beautiful UI. Ship bounded working boot slices, but do not mark CPU completion solely because DOS boots.

M10 follows the DOS text/utility acceptance priority. Graphics test-card research may happen earlier to validate the display budget. Do not pursue third-party applications before the applicable supplied DOS utilities are accounted for.

Early stop-and-reconsider gates

Deliverable layout for implementation

src/                 6502 assembly: cpu, memory, bios, devices, video, storage
include/             assembly ABI, structures, constants
cfg/                 linker layouts and memory contracts
tests/host/          Zig runners, assertions, property tests, fixture parsing
tests/guest/         small NASM 8086 programs; source + deterministic fixtures
tests/vice/          VICE integration plans and image extraction checks
tests/ultimate/      physical C64U plans and ownership/configuration checks
tests/acceptance/    DOS scripts, expected semantics, disk transformations
third_party/         pinned Peddle core/license; test-corpus manifests
build_support/       artifact, fixture and map tooling
docs/                durable contracts and user documentation
agentworking/        state, decisions, lessons, research; ignored runs/scratch

Proposed command contract, not yet implemented: make build, make test, make test-cpu-full, make test-vice, make test-ultimate, make benchmark, make verify-memory. The standard fast test invokes Zig and Peddle, with deterministic seeds and no physical device. Hardware/reference tools are separate named lanes; unavailable lanes report not run, never pass.

Review points

Current defaults: native BIOS with real DOS, 4 MiB minimum REU (user clarification supersedes the 16 MiB proposal), assembly via ca65/ld65, 16 KiB guest cache, measured page-size selection, explicit image-save behavior for floppies, read-through/write-through hard-disk caching initially, and approximate CGA rendering. Larger REUs can expand caches and overlay storage.