Files
VCCPlusOSS/docs/macos/CPU_CORE.md
T

90 lines
7.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.