90 lines
7.0 KiB
Markdown
90 lines
7.0 KiB
Markdown
# 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](MACHINE_CORE.md). 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](https://colorcomputerarchive.com/repo/Documents/Datasheets/MC6809%20HMOS%208%20Bit%20Microprocessor%20(Motorola).pdf).
|
||
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](https://colorcomputerarchive.com/repo/Documents/Manuals/Applications/Color%20Scripsit%20II%20(Tandy).pdf)
|
||
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.
|