Publish VCC Plus OSS source distribution for 3.6.2 build 60
This commit is contained in:
commit
c652a5276d
1192 files changed
+272368
No files matched your search
@@ -0,0 +1,47 @@
|
||||
# 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).
|
||||
Reference in new issue
Block a user