ULTIMATEEXPERIMENTSCommodore 64 · Work in progress

Research record and source register

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

Inspected 2026-10-14 (America/Los_Angeles). Distinguish local observation, source-backed fact, proposed design, and unmeasured hypothesis. The user's pasted ChatGPT discussion is useful background, not a specification or evidence of hardware performance.

Local observations

Item Observed evidence Planning consequence
Project contents Three .img files in reference/; no emulator implementation No existing project architecture to preserve
Disk size/BPB All 368,640 bytes, FAT12, 512-byte sectors, 2 sectors/cluster, 720 sectors, 9 sectors/track, 2 heads; 55AA boot trailer First storage profile is 360 KiB, 40-cylinder floppy; fits inside D81 SEQ file
Disk 1 IO.SYS, MSDOS.SYS, COMMAND.COM, DOS tools and CONFIG.SYS; subsequent cloned DOSBox boot reports MS-DOS 3.30 Primary boot fixture; retain original CONFIG behavior
Disk 2 Utility files, no IO.SYS/MSDOS.SYS/COMMAND.COM Data/utility disk, not independently bootable from these files
Disk 3 DOS system binaries hash-identical to disk 1, GWBASIC.EXE, HDFORM/HDPARK; different boot sector/OEM bytes Later BASIC/CGA fixture; do not infer version/validity from OEM string
Configuration Disk 1 contains c: and device=c:\dos\ansi.sys; disk 3 includes config.sys and control-c lines Observe original diagnostics; use separately hashed minimal/driver test copies
ZeroPage ../../zig64 README/testing/ABI/memory docs, runner, C++ shim, fixtures Copy testing architecture, not compiler/runtime as target
Zig test idiom Fixture discovery, linker label hooks, C imports, std.testing.expectEqual, KERNAL return/memory assertions Host Zig behavior tests around assembled target routines
ReuSQL64 ca65/cc65 builds, configurable REU shim, Zig runner, .NET VICE plans, independent c1541 extraction Good model for assembly artifact tests and disk persistence evidence
ReadyFS Asynchronous UCI code and failure tests; prior protocol/ASCII/banking lessons Port protocol semantics with tests; do not copy its whole application
Local tools Zig 0.16.0, DOSBox-X 2026.01.02 SDL2; NASM, x64sc, c1541, cc65 toolchain paths found No need to install DOSBox now; pin tool versions/binaries in M0
Sibling compiler state HEAD 82f16cf8afea90a43a8f8560692b869d55d34dd7; 1668 status entries during inspection Working tree differs substantially from HEAD; use content hashes if copying references
Repository state Pre-existing ReadyFS modifications; project initially untracked; parent ignores working-record directories Stay inside project; local ignore override makes planning records trackable
D81 container proof c1541 stored disk 1 as 1452-block SEQ and extracted identical bytes; 1708 blocks remained Proposed development container is feasible; target IEC runtime remains untested

Exact image and per-file hashes are in reference-images.json (local development record, not distributed), produced by the retained read-only inventory script (local development record, not distributed). That script is research tooling, not emulator implementation. Its limitations are recorded in the JSON. During that read-only inventory, originals were not mounted writable, modified, or executed. Later reference/target boot observations are recorded separately below.

Local tool/source evidence (local development record, not distributed) records exact observed versions and hashes of the inspected local integration sources. ca65/ld65 report V2.18 even though the package directory names cc65 2.19; pin reported tool identity rather than infer it from a folder. The user-supplied prior conversation (local development record, not distributed) is retained verbatim as non-authoritative background.

Sources actually consulted

ID Primary source / implementation What it supports; limitations
S01 Ultimate turbo settings U64 vs Elite-II speed tables, register availability modes, VIC/external-bus caveats. Exact user's hardware/firmware remains to be inventoried
S02 Ultimate DOS target File targets, seek, bulk REU transfer commands and replies; not a latency measurement
S03 Ultimate dos.cc at 125da1f Actual seek/read/write code and transferred counts. Address mask 24 bits; length mask 25 bits differs from prose docs. Does not establish installed firmware behavior
S04 UCI architecture Asynchronous state/queue/abort handshake; combine with ReadyFS regression experience
S05 SingleStepTests 8088 Hardware-generated instruction tests, sparse expected states, flags metadata and exclusions. Not complete interrupt/system behavior coverage
S06 SingleStepTests 8086 Companion corpus for boundary/difference investigation; choose one declared original-CPU profile
S07 Microsoft Encyclopedia, Appendix M Original 8086/8088 vs later CPUs: divide return IP, PUSH SP, shift counts and prefix limits
S08 Microsoft Encyclopedia, Appendix O BIOS call contracts and text-page sizes; choose the PC/CGA subset rather than every later adapter function
S09 Microsoft Encyclopedia, Appendix A DOS 3.3 changes and command/service context; actual supplied binaries remain acceptance fixtures
S10 cc65 Soft-80 drawing Established 80-column drawing, two-character color conflict and restoration strategy
S11 cc65 Soft-80 color, layout Source-level display reference. Any reuse requires its license/attribution, and PC-specific glyph/attribute handling
S12 VICE quick setup, resource reference, machine features Virtual traps, REU options and warp configuration; installed build help is the final command-line authority
S13 DOSBox-X DOS 2.x/3.x installation, image management Real-image BOOT workflow and old DOS partition-format pitfalls. Its broad historical statements are not used as architectural evidence
S14 MartyPC Candidate original-PC timing/behavior reference; not installed/configured or benchmarked in this planning pass
S15 IBM XT BIOS listing archive Locates original IBM BIOS material and revisions; a synthetic BIOS will be project-owned rather than bundling an IBM ROM
S16 Peddle and local pinned source/license Host MOS_6510 engine. Local integration/source inspected; emulator timing/device claims limited to the actual shim

Additional authoritative references identified for detailed implementation: Intel 8086 Family User's Manual, October 1979 and Commodore 1764 user's guide. These were located, not fully audited page by page. Their detailed bus/REU edge semantics must be checked during M1/M2. An attempted IBM XT PDF fetch was unavailable; use the accessible listing archive/reference instead of claiming that PDF was read.

Corrections to the pasted discussion

Earlier suggestion Planning conclusion
Prefer a native DOS API layer and add actual DOS later Conflicts with this user's objective. Execute the real DOS kernel from the outset; native BIOS is the acceleration boundary
Map guest file handles to Ultimate DOS handles Unnecessary here: DOS manages guest handles inside disk images; host handles are for images
Illustrative 26 KiB guest cache Too optimistic to assume before layout. Budget 16 KiB with visible display/metadata/code allocations, then measure
Roughly 4 MB/s REU Unverified scenario, not a specification; measure each direction/size at the actual firmware/turbo/display settings
64 MHz might exceed XT generally Workload-dependent hypothesis. Fast bulk storage does not prove CPU or memory-heavy performance
80-column color is straightforward Width is feasible; two arbitrary colored characters in one VIC hires cell cannot always be represented faithfully
Skip most PC I/O Minimal PIC/PIT/keyboard/CGA port behavior is still needed for DOS/drivers and polling loops
“Zig” target User clarified assembly; host Zig provides tests, generators and assertions. ZeroPage remains the example testing workflow

Open research to close during implementation

Follow-up source inspection is recorded in existing emulator references. NES86 is a verified 6502-assembly 8086 interpreter and the closest inspected host-CPU match. 8086tiny supplies an MIT-licensed C core and BIOS; XTulator supplies a readable GPL CPU reference. Our target remains original 8088/XT, and none of these sources has been incorporated into the target. REU_IMPLEMENTATION.md records the subsequently implemented primitive, mock and functional VICE evidence.

Implementation follow-up: CPU boundaries and hardware corpus

Original-8088 word policy follows MartyPC byte-bus implementation at 05c0d088: wrap the offset for the second byte, then translate. No source copied. The pinned hardware projection retains 2,555 functional cases as of the 2026-10-15 math/indirect checkpoint and the MIT license. Audited A1/A3 originals have no word beginning at FFFF; A3 index 9570 covers FFFE. Independent corner tests supplement the source reference; they are not direct physical-8088 evidence. CPU implementation lists actual opcode coverage and exclusions.

Original shifts also consult MartyPC common ALU at 05c0d088 and the pinned hardware vectors. Original D0/D1 /6 is SETMO; D2/D3 /6 is SETMOC, not the later SHL alias. CL counts use all eight bits. The interrupt routine reads IVT words before stacking FLAGS/CS/IP; the current functional policy follows that order. No reference code copied; hardware projections cover functional state, not asynchronous event timing.

Intel iAPX86/88/186/188 manual (1985), §1.7.8 printed1-122 /PDFpage138, distinguishes per-iteration guest interrupt restart from uninterrupted REP. Multiple-prefix restart quirks and precise segment-register interrupt inhibition still need direct original-hardware event evidence. Our host REP yields preserve all decoded prefixes and are explicitly not guest interrupts.

Math, BIOS and real-kernel observations — 2026-10-15

The expanded hardware selection pins original F6/F7 divide-error, REP IDIV, signed-minimum-quotient and FF PUSH SP alias rows. F6/F7 MUL/IMUL/unsigned DIV input files have no REP prefixes at this pin; independent tests/source-derived policy must not be called direct hardware coverage. FE /2–7 input files are absent and 8F input contains only /0; unaudited forms remain explicit diagnostics. Original signed division rejects magnitude 80h/8000h even for a negative quotient, and divide errors retain original post-instruction saved IP. These distinctions were verified by the pinned original hardware projection rather than inferred from a modern x86 host.

The BIOS implementation's source comments pin the IBM 5160 XTBIOS/POST listings used for status/DMA interface facts, unsupported INT 15h AH=86h/CF=1, and disk-parameter table fields. Local archived listings and inspection notes are retained under ignored agentworking/scratch/; the synthetic code/table bytes are independently authored, and no IBM ROM is bundled. The configured 360 KiB profile uses nine sectors/track rather than treating a listing's compatibility default as the actual fixture geometry. The current BIOS contract distinguishes ordinary guest ROM handlers from whitelisted native disk/bootstrap gates.

The unchanged supplied bootloader actually reads 51 raw sectors starting at its IO.SYS extent; IO.SYS itself is 22,398 bytes and rounds to 44 sectors. An independent FAT12 fixture oracle records the full raw extent, padding and overread rather than assuming the file length describes every loaded byte. Actual target execution reaches 0070:0000 in 392 guest instructions, then continues to unsupported PIC OUT 20h at 0070:2BFB after 2,335 instructions. INT 11h/12h read mutable BDA and INT 15h returns XT unsupported status on this path. This is observed kernel entry, not evidence that COMMAND.COM, the original CONFIG.SYS or a DOS command prompt has completed.

Host disk-image tooling validates BPB/FAT/root/chain bounds and immutable source identity, and creates exclusive disposable clones/extractions for tests. It is a fixture/oracle aid, not a native DOS loader. Guest BIOS storage remains raw sectors through the actual assembly cache/range implementation. Native UCI/IEC import/persistence, hard-disk geometry/format behavior, display/input and event timing remain research/implementation gaps.

Fetch/PIC and candidate BIOS/adjust follow-up

The accepted fetch comparison (local development record, not distributed) uses the previous actual assembly helper as a differential reference, including one-frame operand eviction, generation changes, redirects and self-modification. Its target-cycle gains are workload-specific; large REP behavior is nearly unchanged. PIC integration (local development record, not distributed) adds all eight IN/OUT forms and software-visible 8259A programming, without asynchronous IRQ/INTA or imported IN/OUT hardware vectors. Genuine IO.SYS now passes OUT 20h and reaches INT 14h after 2,347 instructions at that accepted checkpoint.

Private adjust research pins the same SingleStepTests source revision and records 3,146 selected rows from eight additional files in agentworking/scratch/adjust/hardware-sources.json. Original BCD hardware distinguishes AF-sensitive DAA/DAS thresholds, DAS borrow and independent AAA/AAS byte corrections from later x86 assumptions. An initial AAM-zero expectation incorrectly preserved SZP; actual hardware rows showed the zero SZP result before INT 0, and the target/test were corrected. The source files contain no REP adjust cases; microcode analysis supplies that policy, with pinned MartyPC source as a cross-check. No implementation source was copied. Selected target execution, exhaustive offline oracle comparison and global corpus integration are distinct evidence lanes.

Private logical video tests consult Microsoft Appendix O, original XT listing facts and RBIL pixel/XOR/page behavior; exact citations and source identities are retained in include/video.inc and agentworking/scratch/video/evidence.json. The independently authored implementation preserves logical guest BDA/VRAM and exposes no host renderer/font/readability claim. Absent serial/printer calls follow the original XT listing's zero-base check before AH dispatch, preserving AX and unchecked wrapping DX index behavior; absence is not a timeout. Combined global quick/full/profile acceptance now passed; retained evidence (local development record, not distributed) pins sources, exact maps, private research and the real DOS continuation.

The normal imported projection now contains 5,701 selected hardware cases: all prior 2,555 retained unchanged plus the 3,146 adjust rows. Fixture SHA-256 aba315edeb9bf6517e9c0eb0f5a887d97589c1604b74ff7f83e1dd2a64bf2f8e; all 47 AAM-zero saved-FLAGS frames compare exact RAM with no new masks. The earlier 205-test quick gate executed its 581-row projection; the expanded fixture designates 597 quick rows, covered by the final full 5,701-case execution rather than a separate quick rerun. Original source-file populations and offline 10,000-row model audits remain distinct from selected target execution.

Logical mode-3 initialization and absent serial/printer services advance genuine IO.SYS to missing INT 1Ah after 2,542 instructions. Clock/native-clock, keyboard and UCI candidate modules are not linked. The new resident layout zero-pads MAIN and explicitly initializes 4000–4FFF display RAM before DEVICECODE at 5000; neither padding nor startup zeros are linked executable allocations. The full runtime binary is untested physically, while four isolated prior hardware probe PRGs remain byte-identical.

Genuine SYSINIT shared-rearm and COMMAND built-ins

The retained primary audit (local development record, not distributed) pins Microsoft SYSINIT1.ASM at repository revision 2d04cacc5322951f187bb17e017c12920ac8ebe2, the original supplied binaries and the observed relocated SYSINIT span. The stop at 9DFD:0A53 with DX=02F2h was a legitimate DOS 3.30 GLOBAL REARM broadcast to shared IRQ levels 2–7. Microsoft v4 comments identify its inherited 3.30 purpose and arbitrary write value; they are not claimed to be the exact source build of this supplied binary. The actual six-port sequence and XT model check remain binary-authoritative. Only byte writes to 02F2h–02F7h are recognized for absent boards, without PIC side effects.

A retained differential execution (local development record, not distributed) compared the retained slow fetch with fast fetch through all 55,583 scheduling calls/53,861 guest instructions to that stop, every 14-word register state and complete coherent 640 KiB RAM plus 16 KiB CGA. It found identical results. This excludes a regression relative to the previous fetch path; it does not independently establish every CPU behavior. The original CONFIG.SYS c: line explains the observed unrecognized-command diagnostic; no source image repair was made.

After implementing that narrow port behavior and clock/keyboard BIOS, the opt-in long assembly/Peddle lane reaches real COMMAND.COM. Date/time Enter, VER and DIR use ten words through the actual assembly enqueue routine. The independent read-only FAT12 oracle requires all 35 visible names/exact sizes, the 35-file total and 9,216 free bytes; output observations also require MS-DOS Version 3.30 and the returned A> prompt. The original/in-REU floppy remains unchanged. Built-ins evidence (local development record, not distributed) retains selected screens and exact raw schema-2 report identity; 939 changed-screen observations remain in the raw run.

This is a Peddle functional milestone. Default tests stop at IO.SYS handoff, while make test-dos-boot owns the long scripted command proof. Linked generic UCI transport does not yet open/import runtime images. Native file-command/render/overlay components remain private/unlinked; physical keyboard scanning, C64 presentation, asynchronous events and HD persistence remain ahead.

The first physical native-clock matrix failed at Manual 1 MHz and is explicitly rejected as timing validation. Failure evidence (local development record, not distributed) pins the probe/tool/firmware identity and configuration-restoration result. The first error-3 subreason remains unknown. Failure capture now retains RAM/mailbox/40-byte DCK1 before reset, and the probe uses a 16-line endpoint window with ±1,008-tick bounds; no successful physical rerun or 16/64 MHz calibration follows from these functional corrections alone.

The corrected physical CIA/raster matrix (local development record, not distributed) passes Manual 1/16/64 MHz: 100-frame deltas 1,965,627/1,965,599/1,965,600 versus 1,965,600±1,008, zero retries, 28-tick spread and restored configuration/reset-resume. This establishes the observed PAL clock domain and turbo independence for the pinned firmware/core; it does not establish CPU/REU throughput or wire native time conversion. The corrected 1 MHz raster endpoints of 8/8 suggest the old narrow window as a possible first-failure cause, but the missing old record prevents confirmation.