Files

48 lines
6.4 KiB
Markdown
Raw Permalink 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.
# Mac machine controller and application bridge — 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.
## Ownership and execution
`src/core/MachineSession` is the synchronous C++ owner. It accepts an exact 32 KiB ROM image and either the 6809 or 6309, currently with 512 KiB RAM and RGB output. ROM bytes are copied before initialization. Invalid size/processor input leaves the current machine intact. Initialization failure after ownership transfer leaves an empty session with hosts, memory, and scheduled events released.
The retained engines still contain process-wide globals. An atomic ownership claim permits only one loaded session. A rejected second session cannot replace the first session's hosts. This claim does not make low-level emulator APIs thread-safe: initialization, execution, snapshots, and destruction must all be serialized, and direct core tests cannot run alongside a loaded session.
The session installs the real machine, video, and CPU-debugger hosts and connects video/timer writes and interrupts to the selected CPU. SAM double-speed and turbo requests update the retained scheduler. The joystick ramp clock now has non-Windows storage in the core rather than in the test executable; native joystick input is now connected.
- Loading creates a paused machine at its ROM reset vector.
- Resume starts execution; Pause stops future frame execution without resetting state.
- Advance executes at most one frame, with a 100,000-cycle safety budget. A halt pauses the machine; a stalled or over-budget frame pauses and reports an error.
- Reset constructs a fresh machine, including a new GPU, from the retained ROM and processor selection. RAM, registers, callbacks, frame counters and graphics state restart. This is a **cold reset**.
- Soft Reset follows the retained Windows warm-reset sequence for the connected hardware, preserving the RAM allocation and its contents at the reset boundary. It resets CPU/PIA/SAM/MMU and scheduled raster/timer work, reloads the owned ROM bytes, releases keys, advances the generation and clears published frames/counters. It preserves the running/paused choice. Guest warm-start code can subsequently modify RAM; program recovery depends on the guest. The retained GIME register image/palette are not cold-initialized. Attached devices receive the corresponding native bus reset.
- Shutdown is idempotent and cancels events, frees RAM/ROM, detaches hosts and releases ownership. The synchronous session can subsequently load again.
At the initial controller checkpoint, cartridges/MPI, disks and printer were disconnected. Those selected devices are now connected; see [cartridges](CARTRIDGES.md), native disks, [hard disks](HARD_DISKS.md), SDC and Printer Output. [Audio and cassette](AUDIO_CASSETTE.md) now connect the retained PIA sound/input/output through scheduled samples and a persistent in-memory deck. The native audio callback consumes a bounded buffer without accessing the core. Deferred Windows peripherals are not emulated by the native host. The app exposes ROM/media selection and native input for its implemented devices.
## Native bridge and frame delivery
`platforms/macos/Bridge/VCCMachineController` wraps the session in Objective-C++ for Swift. Every command and timer callback runs on one private serial dispatch queue. Completion callbacks carry immutable snapshots to the main queue; no UI code reads the live core. Snapshots contain state, generation, frame/cycle counts, program counter, an optional error, and an owned pixel copy.
Completed frames contain 640 × 480 packed `0x00RRGGBB` pixels. Both C++ frame ownership and the bridge's `NSData` copy allow a display consumer to retain a frame safely across later execution, reset, or shutdown. Generation changes distinguish frames across resets. Reset clears the current frame; a new frame appears after execution resumes. The preview explicitly ignores the zero high byte as alpha and disables image interpolation.
With native audio enabled, the machine queue fills a bounded sample buffer in response to device consumption, at most four frames per turn. With audio disabled, it uses the nominal NTSC frame interval (239,856 / 14,318,180 seconds), without unbounded catch-up. The UI requests snapshots at 30 Hz with at most one poll outstanding. This controller checkpoint alone did not establish sustained accuracy; subsequent [timing and sleep/wake checks](TIMING_RELIABILITY.md) record the implemented baseline and remaining coverage.
Bridge shutdown is terminal. Commands submitted afterward report an error; queued frame delivery cannot restart the machine. Deallocation also drains the worker and releases ownership. The application delegate waits for asynchronous shutdown before approving Quit; closing the sole window pauses execution.
## Validation
Five new shared C++ suites cover both CPUs, empty/paused/running transitions, cold reset determinism, retained frame ownership, singleton exclusion/destruction, ROM validation and copied ROM lifetime. Three additional hostless XCTest suites exercise asynchronous command order, main-queue completion, paced execution, pause stability, reset/shutdown, invalid input, post-shutdown rejection and deallocation/reacquisition.
Soft-reset checks additionally verify all 512 KiB remain byte-for-byte unchanged before guest execution, interrupt masking/reset vectors, default MMU mapping, held-key release, event replacement, immutable previous frames, repeated reset and paused behavior on both CPUs. Two bridge tests exercise soft reset with each CPU.
The test inventory is **39 shared core checks** plus **7 Mac bridge tests** and **5 native tests** (51 in XCTest). See the build guide for verified configurations. Authored diagnostics and tests are source code; no third-party ROM, raw Windows evidence, screenshots or binaries are included.
## Subsequent integration and open qualification
Native ROM boot, Metal/input, audio/cassette, device routing, disks, profiles and debugger/C-workspace commands now share this serialized machine owner. [Sustained timing and sleep/wake](TIMING_RELIABILITY.md) have baseline evidence. Physical Intel/macOS 14, broader workloads and Windows comparisons remain required; Rosetta and deployment-target builds do not establish those results. See the [current porting plan](PORTING_PLAN.md).