Files
VCCPlusOSS/docs/macos/CPU_CORE.md
T

7.0 KiB
Raw Blame History

CPU extraction — Phase 1

Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.

Boundaries and ownership

  • CpuMemory.h declares the existing byte/word memory and map-selection operations. CpuMemory.cpp routes them to the real MMU by default. Isolated CPU checks explicitly install a flat 64 KiB CpuMemoryBus from tests/core/CpuChecks.cpp and detach it afterward. The separate machine checks use the real MMU; see memory and hardware extraction. The flat test bus is excluded from the library and application targets.

  • CpuHost.h exposes synchronous debugger hooks for halt, step, breakpoints, trace triggers, interrupt tracing, and patched haltpoints. CpuHost.cpp forwards these to the existing Windows debugger by default. The non-Windows default supports a halt latch without tracing; the Mac controller installs its own hooks before running a machine. Tests install a recording implementation and detach it after each check.

  • Hosts retain ownership of installed hooks. Install/detach on the emulation thread, outside execution, and keep the object alive while installed. The engines, scheduler, and joystick clock still have global state. Run one engine at a time; these are not yet independent machine instances or thread-safe UI entry points.

  • CPU initialization, reset, execution, register snapshots, breakpoints, and trace-trigger functions remain the original public interfaces. Call initialization before reset, especially for the 6309 register-pointer tables. Exec(budget) returns unused cycles, which can be negative when the final instruction exceeds the budget.

  • The retained register unions require little-endian hosts and 8/16/32-bit byte/short/int layouts. Compile-time checks document those assumptions. Both supported Mac architectures meet them. This is an initial layout check, not a completed audit of every instruction, aliasing assumption, or arithmetic edge case.

Reproducible checks

Seven new XCTest cases share their C++ implementation with the console runner:

Check Coverage
6809 execution Reset vector/registers/masks, authored guest loop, indexed writes, arithmetic flags, word-store byte order/address wrap
6309 execution The same checks in 6809-compatible mode
6809 interrupts IRQ/FIRQ/NMI vectors and stack frames, RTI, shared interrupt sources, reset masks and cleared sources
6309 interrupts The same checks in emulation mode
6309 native mode LDMD, LDQ/STQ byte order, native NOP timing, restoration of emulation timing on reset
CPU debugger Triggered trace boundaries, breakpoint halt, no execution while halted, single-step for both engines
Event scheduler Initial clock rate, exact-boundary deferral, ordering, callback-created events, reschedule/erase, rebase, overclock, reset

The authored guest fixture executes 69 instructions and stores bytes 1–16 at $4100. Both engines end at $4012, A=$10, B=$00, X=$4110, S=$7000. Its expected 222 cycles comprise 14 setup cycles and 16 iterations of 13 cycles. These are synthetic architectural expectations; a matching Windows CPU trace has not yet been captured. Existing Windows evidence remains described in the reference review.

The scheduler's embedded legacy static-initialization test block is disabled in the Mac library with USE_DEBUG_TESTS=false; the explicit XCTest/console checks above run in both configurations. Existing SSC smoke assertions remain enabled in Release.

Defects found during extraction

  1. Event used mResolution before that member was initialized, because C++ initializes members in declaration order. It now initializes clock scaling with a defined constant. A full reset also clears requested clock/overclock settings, so a later rebase cannot restore stale settings.

  2. HD6309Reset cleared native-mode bits but retained cached native instruction timings. It now resets that timing table through the existing mode-setting function. The native-mode reset check failed before this fix.

These are shared source fixes and are included in the Windows build definition. Windows recompilation and reference comparison of this increment are still pending.

Scripsit II timing correction — November 4, 2026

Color Scripsit II booted its menu but hung after E on the Mac. Its editor polls the PIA VSYNC flag with TST while its IRQ handler acknowledges that same flag. Advancing all instruction cycles after the operand read allowed every edge to be acknowledged before the polling loop observed it.

The 6809 and 6309 emulation-mode TST direct, indexed and extended paths now advance the addressing/data cycles before reading the operand, followed by the two remaining internal cycles. Total instruction timing and indexed addressing penalties are unchanged. This follows Figure 18, sheets 3–5 of the Motorola MC6809 datasheet. The 6309 native-mode path retains its previous timing. This is a targeted timing correction, not a claim of complete bus-cycle or 6847T1 conformance.

Validation:

  • ROM-free checks exercise every edge position for direct, indexed, extended and indexed-offset forms on both CPUs: sampling time, total cycles, one read, flags, and a polling loop whose IRQ handler acknowledges the flag. These checks fail with the original CPU implementations.

  • All 61 console checks pass. Both Apple Silicon and Intel/Rosetta XCTest runs execute 491 tests, with two skips and no failures.

  • The optional real-cartridge probe passes on both CPUs: boot, polling-loop exit, inserted text retained in memory, Ctrl–Break menu return, and reentry. The tested cartridge SHA-256 is 2dfac5ecb1d7c5853e5dbf1059730bd134e891751429e1643149b669056c43db.

  • Native isolated-app inspection verifies editor entry, typing and the VU lowercase display option. Native automated Ctrl–Break delivery was inconclusive; menu return is verified through the emulated keyboard matrix by the probe, not claimed as a completed native shortcut check.

The Scripsit manual explains that E enters editor command mode, then I starts insertion. Break returns to command mode; Ctrl–Break returns to the main menu. The default display represents lowercase letters as inverse uppercase glyphs.

To run the optional probe after building VCCCore, compile tests/macos/scripsit-compatibility-probe.cpp with C++17 and link the built libVCCCore.a. Pass a private CoCo 3 system ROM, the Scripsit II cartridge, and an output prefix. It writes one PPM capture per processor; it neither changes supplied media nor includes ROM payloads in the repository. The native UITesting app also accepts --cartridge-validation SYSTEM_ROM CARTRIDGE and optional --cartridge-6309, using isolated preferences.