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,49 @@
|
||||
# Native audio and cassette milestone
|
||||
|
||||
> 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 compatibility
|
||||
|
||||
- A 44.1 kHz scheduled event samples the PIA sound state, selected analog source, independent cartridge outputs and cassette input/output. Samples follow emulated time and stop when the machine pauses. Reset clears the PIA output latches and replaces the sampler event.
|
||||
|
||||
- The packed PIA words are converted explicitly to signed stereo float samples. Native output uses AVAudioEngine/AVAudioSourceNode over the Mac audio system. The render callback only drains a fixed-capacity, single-producer/single-consumer buffer; it allocates no memory, acquires no locks, and never calls the emulator. [Apple source-node guidance](https://developer.apple.com/documentation/avfaudio/avaudiosourcenode/init(renderblock:)) requires avoiding blocking operations in device render callbacks.
|
||||
|
||||
- The machine queue refills roughly 100 ms ahead, with at most four frames per turn. Device consumption paces emulation without changing the CPU/GIME clock ratios. Output starts only after the reserve is filled. The queue has an 8,192-frame hard limit; the extra reserve adds about 50 ms of latency over the preceding implementation. Missing samples become silence; underrun, overrun, consumed/submitted/nonzero sample counts, occupancy and output-start counters are exposed in bridge snapshots. Zero volume still consumes samples. Volume/mute changes now preserve the running engine and queued audio. The producer uses interactive scheduling priority; a one-second loss of consumption falls back to silent pacing. See [timing and reliability](TIMING_RELIABILITY.md) for sustained checks and limits.
|
||||
|
||||
- The Windows sampler's `+25 Hz` host-buffer compensation is not carried over; output consumption supplies pacing. This is an intentional host-side difference that still needs sustained comparison with Windows.
|
||||
|
||||
- CAS retains the upstream least-significant-bit-first 21/40-sample waveforms, amplitude reduction and rising-edge decoder. Fast CAS retains the `$83` BASIC pulse-width convention. Motor gaps use emulated time. No ROM patch is bundled.
|
||||
|
||||
- WAV parsing walks RIFF chunks, including unknown chunks and padding, and checks sizes before reading. Input accepts mono/stereo PCM 8/16/24/32-bit and float32 at 8–192 kHz. Stereo is averaged; sample positions are normalized to 44.1 kHz. Compressed WAV and WAVE_FORMAT_EXTENSIBLE are not accepted in this milestone.
|
||||
|
||||
- Files and normalized/recorded WAV images are bounded to 64 MiB, including export-header space; CAS is bounded to 1 MiB. Recording stops at capacity. Recording resumes only through a new recording; this milestone does not overwrite sections of existing tapes or splice recordings.
|
||||
|
||||
- The active deck lives in memory. File-backed cassette assignment is now remembered and reopens stopped at the beginning on relaunch; unexported recordings are protected by quit/replacement safeguards, not serialized as a saved execution state. See startup behavior and profiles. A separate audio-output picker, analog filtering and broader cassette-library qualification remain outside this baseline.
|
||||
|
||||
## Validation and outstanding checks
|
||||
|
||||
Verified on the local Apple Silicon Mac with Xcode 27.2/macOS 27.2:
|
||||
|
||||
- 51 XCTest tests: 39 shared core checks, seven bridge tests and five native tests.
|
||||
|
||||
- Debug and Release universal app builds; the 39-check Release console suite and both-CPU BASIC integrations passed on arm64 and x86_64 under Rosetta. Rosetta does not validate physical Intel hardware.
|
||||
|
||||
- Focused audio/cassette and both-CPU BASIC integrations passed AddressSanitizer and UndefinedBehaviorSanitizer. The full legacy suite stops under UBSan at the existing signed-left-shift issue in `ssc/sp0256.cpp:125`; at this early checkpoint that chip was not connected to the Mac machine. Speech/Sound was integrated later; this historical sanitizer result is not a claim about the current full suite. LeakSanitizer is unavailable on this platform.
|
||||
|
||||
- Real native audio-device consumption at zero volume, pause stability, restart and shutdown.
|
||||
|
||||
- Concurrent ring-buffer ordering/wraparound, explicit channel/sign conversion, mute, bounded overflow, underrun silence and sample timing from both CPU engines.
|
||||
|
||||
- Tape motor gating, position/end behavior, reset retention, fast-load PIA reads, export/save state, invalid WAV input, all accepted sample representations, rate normalization, unknown chunks and truncated files.
|
||||
|
||||
- File loading with uppercase extensions, spaces and Unicode; oversized inputs are rejected and source bytes remain unchanged.
|
||||
|
||||
- The optional `VCCCoreChecks --rom /path/to/coco3.rom` check boots both CPUs, verifies BASIC SOUND produces samples, records the authored program using CSAVE to CAS and WAV, clears BASIC, reloads through CLOAD, and checks LIST/RUN and `42`. It separately repeats fast CAS loading. No ROM or generated tape is committed.
|
||||
|
||||
## Analog routing correction — November 11, 2026
|
||||
|
||||
The native sampler now honors sound enable and the DAC/cassette/cartridge/ground
|
||||
selector. This fixes the reproduced Quadrapassel splash-screen buzz with both
|
||||
Speech/Sound and Orchestra-90 connected, while retaining normal effects and
|
||||
independent external stereo. The game and installed app were not changed.
|
||||
See [cause, reproduction and qualification](AUDIO_ROUTING.md).
|
||||
@@ -0,0 +1,125 @@
|
||||
# Analog sound routing and Quadrapassel regression
|
||||
|
||||
> 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.
|
||||
|
||||
## Cause and correction
|
||||
|
||||
The native sampler mixed cartridge output into the speaker regardless of the
|
||||
PIA sound-enable control and selected analog input. An idle Speech/Sound output
|
||||
has unsigned midpoint 128. The old path emitted that as a large DC signal;
|
||||
joystick polling switched the mux to the cassette branch and back, chopping it
|
||||
into an audible waveform even though the game had disabled analog sound.
|
||||
|
||||
The sampler now follows the hardware routing:
|
||||
|
||||
| Analog selector | Source while sound is enabled |
|
||||
| --- | --- |
|
||||
| 0 | Six-bit CoCo DAC |
|
||||
| 1 | Cassette input |
|
||||
| 2 | Cartridge SND |
|
||||
| 3 | Ground / silence |
|
||||
|
||||
The sound-enable control gates that analog path. Single-bit sound and the
|
||||
modeled Orchestra-90 external RCA outputs remain independent. Cartridge PCM is
|
||||
centered on 128; a zero sample remains a valid negative peak, distinct from an
|
||||
absent/inactive sound device. The current DAC register is read even if the guest
|
||||
last wrote it during a muted joystick measurement. Final float mixing saturates
|
||||
rather than wrapping a signed packed word. Cartridge clocks and cassette
|
||||
advancement continue while muted or unselected.
|
||||
|
||||
The native sampler uses the new read-only PIA sound snapshot and separate
|
||||
cartridge speaker/external outputs. The original Windows packed mixer remains
|
||||
unchanged. Existing DAC, single-bit and Orchestra-90 gain conventions are retained.
|
||||
|
||||
Hardware cross-checks: MAME's [CoCo implementation](https://github.com/mamedev/mame/blob/master/src/mame/trs/coco.cpp)
|
||||
describes the selector map with its Tandy service-manual citation; its
|
||||
[CoCo machine wiring](https://github.com/mamedev/mame/blob/master/src/mame/trs/coco12.cpp)
|
||||
connects PIA selection, sound-enable inhibit and the separate single-bit path.
|
||||
No MAME implementation was imported.
|
||||
|
||||
## Unchanged real game reproduction
|
||||
|
||||
The optional `tests/macos/audio-game-validation.cpp` boots a supplied DOS disk
|
||||
through ordinary keyboard input, with local CoCo 3/Disk BASIC, Speech/Sound and
|
||||
Orchestra-90 ROMs. The source disk is read-only host input; guest writes affect
|
||||
only an owned memory copy. No text, registers or guest RAM are injected to create
|
||||
the observed results. The matrix uses 512 KiB, 1x overclock and both emulated CPUs,
|
||||
with a mounted stopped cassette and FD-502 in startup slot 4.
|
||||
|
||||
The real-game matrix ran on arm64. The test used Quadrapassel `QUADPSL01.DSK`, SHA-256
|
||||
`4ac171e87c51dfd99b302b9e035a91a59c030144e5ae0661a6d2dfc84ba3a63f`.
|
||||
Its repository remained clean and its source disk hash stayed unchanged.
|
||||
After 1,800 settling fields, each idle capture spans 120 fields:
|
||||
|
||||
| Configuration | Before | Corrected |
|
||||
| --- | --- | --- |
|
||||
| FD-502 only, either CPU | Exact digital silence | Exact digital silence |
|
||||
| FD-502 + Orchestra-90, either CPU | Exact digital silence | Exact digital silence |
|
||||
| FD-502 + Speech/Sound, 6809 | 84,827 / 88,651 nonzero frames; 1,409 transitions; AC RMS 0.101581 | Every sample zero |
|
||||
| FD-502 + both cartridges, 6809 | Same repeating erroneous signal | Every sample zero |
|
||||
| FD-502 + Speech/Sound, 6309 | 84,818 / 88,651 nonzero frames; 1,421 transitions; AC RMS 0.101695 | Every sample zero |
|
||||
| FD-502 + both cartridges, 6309 | Same repeating erroneous signal | Every sample zero |
|
||||
|
||||
With both cartridges present, normal Enter and D/right keyboard input started
|
||||
the game and produced movement effects on both CPUs. Peak was 0.242188 and the
|
||||
final half-second was exactly silent. Thus the correction does not globally mute
|
||||
the game. Raw PCM, framebuffer captures and logs remain private and outside Git.
|
||||
|
||||
Example reproduction after building the current core through Xcode:
|
||||
|
||||
```sh
|
||||
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
|
||||
xcrun clang++ -std=c++17 -O2 -mmacosx-version-min=14.0 \
|
||||
tests/macos/audio-game-validation.cpp /path/to/libVCCCore.a \
|
||||
-o /tmp/audio-game-validation
|
||||
/tmp/audio-game-validation /path/to/ROMs /path/to/game.DSK \
|
||||
/tmp/audio-game-captures --expect-quiet
|
||||
```
|
||||
|
||||
The quiet-title and movement assertions apply to a DOS-boot game with the same
|
||||
Enter-to-start and D-to-move controls. It is an explicit optional compatibility
|
||||
check, not a general assertion that every game's title screen should be silent.
|
||||
|
||||
## Regression qualification
|
||||
|
||||
- All 67 portable core checks passed, including the new authored routing
|
||||
regression on both guest CPUs. It covers all mux states, the sound gate,
|
||||
joystick-style selector changes, current DAC latch, unsigned midpoint and zero
|
||||
cartridge samples, independent one-bit/Orchestra stereo, and saturation.
|
||||
|
||||
- Seventeen focused XCTest checks passed on arm64 and again on x86_64 under
|
||||
Rosetta: audio buffer/scheduling/routing, cassette images and monitor, cartridge
|
||||
behavior, real output-device pause/restart, and volume changes retaining clocks.
|
||||
|
||||
- Real-ROM speech and AY tone checks passed on both CPUs: 22 phonemes,
|
||||
443,259 PCM frames, speech range 0.504 and tone range 0.332. Authored speech
|
||||
fixtures now explicitly select and enable cartridge audio. Test WAV writers
|
||||
retain actual signed PCM rather than subtracting another midpoint. Both speech
|
||||
WAV hashes remain identical to the previously qualified greeting capture
|
||||
recorded in the Speech/Sound guide.
|
||||
|
||||
- The guest Speech/Sound SDK checks passed on both CPUs with missing/absent and
|
||||
real firmware, phrases, joystick polling, tones and noise. Orchestra-90 SDK
|
||||
checks retained exact channel plateaus and approximately 3,996 frames/s at
|
||||
normal speed and 3,986–3,988 at fast speed on both CPUs.
|
||||
|
||||
- The isolated native playback test passed with both real cartridges, the
|
||||
unchanged game, and 25% volume. Across three seconds, emulated fields advanced
|
||||
from 2,336 to 2,515 and the real output device consumed another 132,182 sample
|
||||
frames. Nonzero-signal count remained zero and audio-engine start count stayed
|
||||
one. No mute or engine restart manufactured silence.
|
||||
|
||||
The native test is opt-in through `VCC_AUDIO_GAME_DISK`; ordinary UI runs skip it
|
||||
without that supplied disk or private ROMs. `--audio-game-listening ROM_DIRECTORY
|
||||
DOS_BOOT_DISK` also selects the same temporary fixture and automatically pauses.
|
||||
This is native output-consumption and digital-signal evidence, not a new human
|
||||
listening confirmation, physical Intel test or macOS 14 runtime qualification.
|
||||
The user's physical-machine observation remains the independent comparison.
|
||||
|
||||
The native case also passed independently after reopening its single main
|
||||
window through **Window → VCC UI Tests** (45.061 seconds). The test now uses that
|
||||
public reopening path and raises its window before capturing, avoiding saved
|
||||
closed-window state and unrelated foreground-window captures. The final window
|
||||
capture was visually checked against the game's splash screen and both sound
|
||||
cartridges. The universal normal Debug app built successfully; no DMG or
|
||||
installation was performed.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Native ROM cartridges and Multi-Pak Interface
|
||||
|
||||
> 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.
|
||||
|
||||
## Routing and retained behavior
|
||||
|
||||
`devices/CartridgeDevice.h` implements the single-slot/MPI bus without host UI or dynamic libraries. `devices/RomCartridge.h` retains the memory mapping and bank-switch behavior from `platforms/windows/libcommon/vcc/bus/rom_cartridge.cpp`:
|
||||
|
||||
- ROM addressing uses `((address & 32767) + bankOffset) % imageSize`.
|
||||
|
||||
- Writes to `$FF40` select one of sixteen 16 KiB bank offsets. Reset selects bank zero. Bank switching remains enabled as in the Windows ROM loader.
|
||||
|
||||
- Raw ROMs assert the cartridge-present line for the retained PIA auto-start mechanism; FD-502 does not assert it.
|
||||
|
||||
MPI routing follows `pakrouter.cpp`: `$FF7F` bits 4–5 select the ROM (CTS) slot, and bits 0–1 select the disk-port (SCS) slot. The register reads back those selected fields, with unused bits zero. `$FF40–$FF5F` accesses go only to SCS; ROM reads go only to CTS. Other port writes broadcast to active MPI slots, and reads return the first nonzero response in slot order. All active devices receive horizontal-sync callbacks; NMI is not gated by the ROM selection. Packed stereo samples mix each channel independently with saturation. Empty ROM slots read `$FF`; empty ports read zero.
|
||||
|
||||
Reset restores CTS and SCS to the physical startup selector. Software routing is runtime state, not a remembered preference. The native window shows current ROM and disk-port slots. Cartridge-line state follows CTS, including software changes: the Windows router updates it on physical selection but omits the update in its `$FF7F` write path. This port deliberately updates it on both paths so a deselected ROM does not leave a stale auto-start signal. Runtime reference comparison of that difference remains open.
|
||||
|
||||
The bridge owns one virtual hard-disk controller and one FD-502 instance that can be referenced in both retained configurations, but at most once in the active MPI. Layout changes validate before replacement, keep disk snapshots/save tokens valid, and run on the serialized emulation queue. Inactive configurations receive no ticks, port traffic or audio. All five device assignments reset when the machine resets, without clearing mounted disk bytes.
|
||||
|
||||
## Persistence and missing files
|
||||
|
||||
An additive `cartridges` section in the existing version-1 `DiskAssignments.json` stores mode, first-MPI-use state, startup selector, slot device kinds and ROM file URLs. It contains no ROM bytes, disk contents or machine state. Existing disk-only settings migrate to a single FD-502 assignment when a disk ROM is remembered. Both configurations restore before emulation starts, including inactive ROMs. Corrupt layouts, invalid slots/URLs and duplicate MPI floppy or hard-disk assignments are rejected.
|
||||
|
||||
An unavailable ROM remains assigned, appears as **Unavailable**, and contributes no device to the bus. Other slots and disks can still restore. **Retry Unavailable ROMs** reloads only missing ROMs; it retains the owned bytes of working cartridges. Choose a replacement or Remove to change a remembered assignment. File locations are absolute URLs, with the same move/rename limitations as disk assignments. Settings-write failures remain visible with **Retry Saving Settings**.
|
||||
|
||||
## Validation
|
||||
|
||||
Automated coverage adds four C++ cartridge checks and six bridge/model/persistence tests:
|
||||
|
||||
- Raw ROM mirroring, bank wrap/reset, size rejection, independent CTS/SCS routing, empty slots, other-port broadcast/priority, ticks, ungated NMI, stereo mixing, physical selection and mode changes.
|
||||
|
||||
- Authored guest programs on both 6809 and 6309 select separate ROM and disk slots and read the expected cartridge bytes/register values. A PIA check verifies cartridge-present status follows the selected ROM.
|
||||
|
||||
- Old-settings migration, first MPI activation, independent configurations, slot movement/removal, all assignments and startup choice across model recreation, missing-file recovery without reloading working slots (including an unavailable ROM copied on first MPI activation), invalid selections, retained dirty disks and explicit saving while disconnected.
|
||||
|
||||
- Bridge rejection of duplicate floppy controllers and layout changes during an incomplete disk command, preserving the previous layout and mounted disk.
|
||||
|
||||
- The existing automatic-saving test now runs guest sector writes in both single-slot and MPI mode on both CPUs, verifying exact file bytes, continued execution and clean reopen.
|
||||
|
||||
All 82 XCTest tests passed on Apple Silicon and on the Intel build under Rosetta with the local Xcode 27.2 toolchain on November 1, 2026. Debug and universal Release builds succeeded. The universal Release app was checked with an authored 8 KiB cartridge and a locally supplied CoCo 3 system ROM: native selection in MPI slot 1 auto-started the program and displayed `CART OK` on both 6809 and 6309. Slot 4 retained FD-502. Actual quit/relaunch restored MPI mode, the ROM file, FD-502 and startup slot 1. The temporary ROM was then removed, startup slot returned to 4, and single-cartridge mode restored the user's original FD-502/drive assignment, clean with automatic saving enabled. The verification app was closed. Native missing-file/busy-operation failures are covered by automated tests rather than separately forced in this UI pass. Physical Intel/macOS 14, Windows runtime comparisons and a broader commercial cartridge library remain separate compatibility work. No supplied ROMs or generated media are committed.
|
||||
@@ -0,0 +1,89 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,85 @@
|
||||
# Native debugger
|
||||
|
||||
> 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.
|
||||
|
||||
## Execution semantics
|
||||
|
||||
Explicit instruction stepping retains the Windows CPU engines' behavior: execute the opcode before servicing pending interrupts. Continue uses normal interrupt dispatch and temporarily bypasses a breakpoint just reached, so an interrupt-handler breakpoint can still stop execution.
|
||||
|
||||
HD6309 **Step** completes an entire TFM block-transfer instruction. Event timing continues during the transfer and completed video frames are counted/published at their actual raster boundaries. Continue from a breakpoint on TFM can stop again at the same address after one transfer byte, following the retained core's breakpoint checks. This differs from the whole-instruction Step action.
|
||||
|
||||
The 6309 stepping loop now clears stale TFM continuation after PC changes, reset and invalid-instruction traps, preventing it from following arbitrary code indefinitely. Regression programs cover both native and emulation modes, interrupted transfers, invalid operands and transfers spanning multiple frames.
|
||||
|
||||
The last completed video frame remains visible while paused; a few instruction steps need not complete a new raster frame. Single-step audio is discarded so resuming does not play a delayed burst.
|
||||
|
||||
## Implementation boundaries
|
||||
|
||||
`MachineSession` owns debug execution and breakpoints. The Objective-C++ controller captures CPU state, memory and machine/media status on its existing serial queue. No live core pointers cross into Swift. A window-owned `DebuggerModel` requests snapshots at most five times per second while visible; only one inspection is pending at a time. Closing cancels polling. Edits retain focus and text drafts and wait for a fresh authoritative capture before allowing another mutation.
|
||||
|
||||
Disassembly reuses upstream VCC opcode tables with portable formatting over captured bytes. It supports both CPU instruction sets, signed offsets, indexed forms, address wrapping and HD6309 register/bit/TFM forms. Invalid encodings produce bounded `FCB` rows. VCC's optional HALT/BREAK pseudo-opcodes are not enabled in this baseline and are not presented as active instructions. A capture is bounded to 64 KiB of logical memory, 48 decoded rows and an additional 256 physical RAM bytes only when physical inspection is selected. MMU data and both memory spaces belong to the same execution boundary. No work is added to normal frame polling when the debugger is closed.
|
||||
|
||||
## Validation
|
||||
|
||||
Authored programs and private, isolated app preferences are used throughout. No ROM or personal media is required by the debugger tests. Verified on November 3, 2026 with Xcode 27.2 on Apple Silicon:
|
||||
|
||||
- All **202 background XCTest checks passed on arm64 and x86_64 under Rosetta**, with zero failures. The full suite contains 203 tests; the unrelated foreground Metal presentation case was excluded from the background runs.
|
||||
|
||||
- Nineteen added debugger tests cover both CPU engines, snapshots and async commands, exact stepping, pending interrupts, repeat breakpoint stops, reset preservation, mapped-memory protection, strict input, focus/drafts, decoder forms and long/interrupted/invalid TFM transfers.
|
||||
|
||||
- The targeted native XCUITest passed: live opening, Pause/Set PC/Step, memory edit, breakpoint hit/removal, Continue, resizing, typing across refresh and close/reopen. Session generation and authored mounted media were retained. The native window was visually inspected.
|
||||
|
||||
- Universal Release app built and its executable verified to contain both arm64 and x86_64. This is a build check, not a newly signed/notarized distribution release.
|
||||
|
||||
- No new test requires private ROMs. Existing unsigned/local development products and test results stay outside Git. The previously published local signed app/DMG were not replaced.
|
||||
|
||||
The captured workspace uses the authored diagnostic loop and a test RAM edit. Tests under Rosetta are not physical Intel validation. The native UI check ran on the current Mac, not macOS 14, and does not certify comprehensive VoiceOver usability or Windows debugger parity.
|
||||
|
||||
## MMU and physical RAM increment — November 3, 2026
|
||||
|
||||
Eight new core/bridge/model tests cover both processors and all four RAM capacities; task switching and disabled mappings; ROM overlays and all-RAM mode; FE00 overrides and fixed ROM vectors; high 8 MB banks, latched prefixes and mirrored RAM; immutable snapshots, end bounds and recovery after a smaller RAM configuration. Physical capture has no device-read side effects and does not advance guest clocks or mutate the machine.
|
||||
|
||||
All **210 background tests passed on arm64 and x86_64 under Rosetta**. The full suite now contains 211 tests; the unrelated foreground Metal presentation case was excluded from these background runs. The existing debugger stepping/breakpoint/edit/focus UI case and the new live MMU/physical-memory UI case passed. Native inspection caught an accessibility-label recursion crash in selectable physical bytes; replacing them with plain labeled text fixed the crash, and the same test passed again. Final screenshot review corrected the segmented-picker label layout. The final universal Release app built successfully with both architectures. The signed distribution app and DMG were not replaced.
|
||||
|
||||
Both captures use the authored diagnostic in the isolated test app. The memory and MMU areas scroll independently; the divider can be dragged to give either more space. The normal emulator and personal media were untouched. Rosetta is not a substitute for physical Intel testing, and these UI checks do not certify macOS 14 or comprehensive VoiceOver behavior.
|
||||
|
||||
At the time of the MMU increment, physical export/disassembly, source/listing association and execution tracing were outside its scope; the following increment implements them. Physical editing remains excluded. Inspecting MMU controls does not change them; guest software remains responsible for programming the MMU.
|
||||
|
||||
### Source listings
|
||||
|
||||
Use **Source → Open Listing…** to select a LWASM `.lst` or text listing. Generate an absolute listing with the [LWTOOLS assembler](https://www.lwtools.ca/manual/manual.html), for example:
|
||||
|
||||
```sh
|
||||
lwasm --6809 --format=decb --list=program.lst --output=program.bin program.asm
|
||||
```
|
||||
|
||||
The listing does not load its program. Load the corresponding binary separately, then use exact logical CPU addresses for source following and breakpoints. The importer does not assert that listing bytes match current memory, and it does not read filenames embedded in the listing. Source locations retain LWASM's sometimes-truncated filename and original line number; the left-hand row number identifies the listing itself.
|
||||
|
||||
- Click a circle to add/remove a shared address breakpoint. Dashed circles identify disabled breakpoints. Their context menus offer Enable/Disable, Show Disassembly, Show in Memory, Set PC Here while paused, and Copy Source Line.
|
||||
|
||||
- **Follow PC** selects an exact addressed line, never a guessed nearby line. If several source lines share an address, a selected matching line is preferred; all share the same logical breakpoint. An unmatched PC is reported explicitly.
|
||||
|
||||
- **Find Next** searches source text and source locations, ignores case and wraps at the end. Searching or selecting a line turns off source PC following, allowing inspection without losing the selected location to live polling.
|
||||
|
||||
- **Close** unloads debugging information and retains all shared breakpoints. Failed imports preserve the previously loaded listing. Neither action changes guest execution.
|
||||
|
||||
- Imports are bounded to 8 MB, 50,000 lines and 4,096 characters per line. UTF-8 and BOM-marked UTF-16, standard filename/line metadata, `--list-nofiles`, cycle annotations, duplicate addresses and address zero are supported. Comments, directives, continuation bytes and non-code offsets remain visible without invented instruction associations.
|
||||
|
||||
CMOC uses LWASM to produce relocatable object files and LWLINK to assign final addresses. Its intermediate `.lst` is not a final logical-address listing. This standalone listing importer still rejects `SECTION`/`ENDSECTION` with a linker-map explanation. The separate **Develop → C Development** workspace now builds CMOC projects, resolves object sections through the matching linker map, verifies the linked executable bytes and supports C-source breakpoints across translation units. It retains exact build/source identity and does not treat a raw relocatable listing as an executable address map. See the workspace implementation and validation. The workspace now also provides [C source-line Into/Over/Out, variables and read-only watches](../development/CMOC_SOURCE_DEBUGGING.md). These use verified compiler metadata and the same machine; they are separate from importing an arbitrary assembler listing. Multiple statements on one source line are not separately mapped. See the C development roadmap for remaining work.
|
||||
|
||||
### Memory tools and tracing
|
||||
|
||||
See [Memory Tools](DEBUGGER_MEMORY_TOOLS.md) for bounded physical disassembly, explicit logical origin, raw range export and optional OS-9 interpretation. See [Trace](DEBUGGER_TRACING.md) for start/stop addresses, historical before/after registers, real interrupt/video events, native scheduler events, timing marks and ranged CSV export. CSV formatting runs off the emulator queue after capturing an immutable bounded range.
|
||||
|
||||
The original authored assembly and actual LWASM-generated listing are safe to retain in Git and correspond to the test diagnostic's two-instruction loop. Personal ROMs, games, compiler builds and generated test exports remain outside the repository.
|
||||
|
||||
### Completion validation
|
||||
|
||||
The checks below record completion of the original Windows-parity debugger milestone. Later CMOC workspace qualification is recorded separately in the workspace guide.
|
||||
|
||||
The final background suite passed **233 tests with zero failures on arm64 and x86_64 under Rosetta**, run separately on November 3, 2026. The full scheme contains 234 tests (61 shared and 173 Mac); the unrelated foreground Metal presentation case was excluded from these background runs. Twenty-three new tests cover listing parsing and failure recovery, disabled breakpoints, memory bounds/export, OS-9 interpretation, trace triggers and immutable samples, both CPU register sets, range export and asynchronous file-save success/failure.
|
||||
|
||||
Four targeted native UI cases passed during this increment: the existing execution/edit/focus case, MMU/physical inspection, source listings/disabled breakpoints, and memory/trace export. The final two-case run verified the corrected compact Source layout and background saves through actual native file panels. It read back the exact five-byte raw export and trace CSV, checked field focus and retained drafts, and checked continued execution, audio and mounted media where no explicit execution command was issued. The full unrelated UI suite was not rerun.
|
||||
|
||||
Native screenshot review exposed a Source minimum-height conflict in a restored compact window. The source and memory panes now share a stable combined minimum height, keeping execution controls below the title bar. A regression assertion guards that layout. An earlier overlapping test run contended for the audio device; the final architecture suites ran separately and both passed. All three final window captures were visually inspected. The final universal Release build succeeded, and its executable was verified to contain both arm64 and x86_64. This is a local build check; the signed distribution app and DMG were not replaced.
|
||||
|
||||
These captures use only the isolated authored diagnostic. Source lines and memory panes scroll independently; the splitter can give either more room. See the Windows source-level parity review for remaining differences. Fresh side-by-side Windows runtime comparison, physical Intel hardware, macOS 14 and comprehensive VoiceOver certification remain validation gaps. The CMOC workspace and SDC baseline are now implemented and qualified within their documented scope.
|
||||
@@ -0,0 +1,41 @@
|
||||
# Debugger memory tools
|
||||
|
||||
> 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.
|
||||
|
||||
## Disassembly
|
||||
|
||||
Choose **Mapped CPU** or **Physical RAM**, then enter hexadecimal **Start** and **End (inclusive)** addresses. Physical RAM uses the installed capacity, up to `$7FFFFF` for 8 MB. Mapped CPU uses `$0000–$FFFF`. Reversed, overflowing and wrapping ranges are rejected.
|
||||
|
||||
For physical RAM, **Assumed CPU origin** specifies the 16-bit logical address at which those bytes would execute. This controls relative branch destinations. The **Location** column always shows the actual RAM location; **CPU** shows the assumed logical address. Physical RAM is not implicitly mapped into the running processor merely by viewing it.
|
||||
|
||||
**Disassemble** captures up to the first 4,096 bytes and displays at most 128 rows. It takes a new capture only when requested; the caption identifies the processor and capture's cycle count. Changing address fields does not silently replace an existing capture. An incomplete instruction at the end becomes an explicitly marked `FCB`, with no invented trailing bytes. Unavailable mapped I/O is marked as unavailable and advances one address. Rows provide a native **Copy Row** context-menu action.
|
||||
|
||||
Both MC6809 and HD6309 use the retained VCC opcode tables. HD6309 decoding is available in native and emulation mode. The normal live disassembly view continues to follow the actual CPU PC; this separate area deliberately does not follow PC.
|
||||
|
||||
## OS-9 interpretation
|
||||
|
||||
**Interpret OS-9 calls and module headers** is opt-in because ordinary software may use SWI2 differently. It consumes the service byte after SWI2, names known OS-9/NitrOS-9 requests, and leaves unknown/private requests numeric. Names follow the [NitrOS-9 service definitions](https://github.com/nitros9project/nitros9/blob/master/defs/os9.d). This annotation does not imply that a particular guest OS implements every named service.
|
||||
|
||||
A module header is recognized only with `$87CD` sync and valid nine-byte header parity. Its row reports size, name offset, type/language, and attributes/revision. Program, system and file-manager headers also show execution and storage offsets. Header interpretation is an aid to inspection; it does not validate a module's CRC or load, relocate or execute it.
|
||||
|
||||
## Raw binary export
|
||||
|
||||
**Export Binary…** captures the entire selected range and opens a native save panel. The immutable captured bytes are saved atomically. The default extension is `.raw`; this is not a Disk BASIC `LOADM` file and has no DECB header. Export while running captures one execution boundary and does not stop the session. Export a paused machine when repeatable guest state is important.
|
||||
|
||||
A mapped range containing unavailable I/O is rejected before opening the save panel. The app does not substitute zeroes into an exported image. Choose a range excluding that I/O, or export physical RAM instead. This safeguard also applies to a whole-CPU-space export.
|
||||
|
||||
File errors remain visible in Memory Tools. Canceling the save panel writes nothing and changes no emulated state. Export does not alter mounted disks or acknowledge their dirty state.
|
||||
|
||||
## Graphics Preview
|
||||
|
||||
Open **Debug → Show Debugger → Graphics Preview**. **Current Video Page** follows the active video registers and palette, including the physical page that the video chip sees. While running, the preview samples up to four times per second. Pausing lets you inspect a stable page. A capture reads memory without advancing the emulated beam or changing the program.
|
||||
|
||||
**At Address** interprets a hexadecimal start address as text/SG4, PMODE 0–4, or HSCREEN 1–4. Select **Mapped CPU** for addresses used by BASIC or assembly instructions. Select **Physical RAM** for a page elsewhere in installed memory. A manual PMODE preview has its own color-set selector. A range extending beyond its address space produces an error. Unavailable mapped I/O appears as a gray pattern.
|
||||
|
||||
Click a pixel or enter **X** and **Y** in Pixel Inspector. It shows the stored byte, its address and the bit mask for that pixel. Attributed GIME text also shows the attribute byte. Composite artifact colors can depend on neighboring bits. **Show Byte in Memory** selects the byte in the matching address space. **Preview as Graphics** opens a preview from the memory inspector. Fit and 1×–4× zoom use nearest-neighbor scaling. **Highlight step changes** marks pixels whose displayed color changed across a single debugger instruction on the same page and mapping.
|
||||
|
||||
## Scope and validation
|
||||
|
||||
Regression coverage exercises both CPUs, logical versus physical backing, the final byte of 8 MB RAM, full physical export, invalid and overflowing ranges, immutable captures, unchanged guest cycles/PC/generation, incomplete instructions, unavailable I/O, optional OS-9 calls, unknown services and valid/invalid module headers. Model coverage checks native export data and file bytes, read-error refusal, address parsing and physical decoding at the final byte.
|
||||
|
||||
Separate Windows raw ROM/PAK views and adjustable memory-grid widths remain outside these tools. Mapped ROM remains inspectable through the CPU address space. Physical editing, assembly-level Step Over/Out, arbitrary register editing and conditional/watchpoint debugging are not provided by these tools. The separate [C workspace](../development/CMOC_SOURCE_DEBUGGING.md) implements C source-level Into/Over/Out.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Native execution tracing
|
||||
|
||||
> 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.
|
||||
|
||||
## Capture
|
||||
|
||||
- Capture options and trigger edits apply on **Start New**, not to a capture already in progress.
|
||||
|
||||
- Choose **1–100,000 samples**. **Start New** replaces the previous capture and arms the trace. The bound counts instruction and optional event rows together. At the limit, capture stops and the machine continues in its existing state.
|
||||
|
||||
- **Start at** accepts up to 32 logical hexadecimal addresses separated by spaces or commas; `$` and `0x` prefixes are accepted. Blank means the next executed instruction. Matching any start address begins capture immediately before that instruction.
|
||||
|
||||
- **Stop before** accepts the same syntax. Matching any stop address stops capture before that instruction, while the instruction still executes normally. This is a trace trigger, not a breakpoint. Identical start/stop addresses produce an empty capture. With no stop addresses, use the limit or **Stop**.
|
||||
|
||||
- **Clear** stops capture and removes its samples. Soft/cold reset and processor/RAM changes stop capture and retain already collected samples. Loading a different machine/profile or quitting clears it.
|
||||
|
||||
- Instructions store their own pre-execution bytes and before/after register states. Self-modifying code, subsequent edits, and MMU changes do not rewrite historical samples. Inspection does not re-read device ports; an instruction whose encoding crosses unavailable I/O is explicitly unavailable rather than decoded from invented bytes.
|
||||
|
||||
Instruction tracing uses the retained CPU engines' before/after hooks. Ordinary HD6309 TFM tracing follows their per-transfer-byte execution loop; an explicit debugger Step captures the whole TFM instruction, consistent with the existing Step operation. A partially filled capture remains armed when a breakpoint pauses execution, and continues when the user continues or steps.
|
||||
|
||||
## Events and timing
|
||||
|
||||
IRQ request, servicing and vector-entry rows come directly from the CPU hooks. IRQ/FIRQ/NMI names identify the line. A request does not imply that the CPU serviced it; separate rows establish that. The retained CPU engines do not emit a separate masked-interrupt callback, so the Mac does not invent masked events from the CC register.
|
||||
|
||||
**Screen events** records real HSYNC/VSYNC transitions and guest video-register changes from the existing GPU/register hooks. **Scheduler events** records entry and return of the native bounded frame-execution call. The Mac uses the event-driven timing engine; it does not fabricate the old Windows scheduler's state-switch variables, drift or nanosecond budgets. Screen events are timing/register events, not screenshots.
|
||||
|
||||
Rows expose the frame number and absolute emulated **master clock** within the current machine timeline. The native raster period is 263 × 912 master clocks; the frame-relative event clock supplies the remainder. Master clocks remain comparable across normal guest CPU speed/overclock changes. Instruction-cycle counts are measured by the CPU engines and are distinct from master clocks.
|
||||
|
||||
Select two rows and choose **Mark A** and **Mark B** to compare their master-clock difference and nominal emulated milliseconds (14.31818 MHz master crystal). This is guest time, not wall-clock capture duration or playback timing. A new capture or Clear resets marks.
|
||||
|
||||
## Inspection and export
|
||||
|
||||
The viewer fetches immutable pages of at most 256 rows at 2.5 Hz only while visible. Previous/Next and a decimal sample-number field navigate the capture. Select a row for its complete CPU before/after registers, event detail and instruction-cycle count. Both CPU register sets are supported.
|
||||
|
||||
**Export CSV** uses a decimal inclusive first/last sample range; a blank end means the current last sample. The range is copied on the machine's serial queue, then CSV formatting runs on a background queue before opening a native save panel. The emulator can continue during formatting. Cancellation or write failure leaves the trace and emulator unchanged. Export uses the retained historical samples, including instruction bytes. Numeric CSV addresses, clocks, cycles and register values are decimal; instruction operands remain assembler-style hexadecimal. Event numbers correspond to `TraceEvent` in `MachineDefs.h`.
|
||||
|
||||
The maximum capture is deliberately finite. It is not an unbounded profiler or a host-performance measurement. Trace capture and export consume extra CPU/memory while enabled; normal disabled execution uses the already-existing false debug-hook checks.
|
||||
|
||||
## Regression coverage
|
||||
|
||||
`DebuggerTraceTests` checks both processors, bounded capture without pausing or resetting, multiple start/stop addresses, stepping, immutable snapshots, ranged export, real screen/scheduler events and monotonic clocks across frame boundaries. It checks actual CPU IRQ request/service/vector callbacks, plus capture retention across reset. It also covers authoritative enabled/disabled breakpoint state and atomic rejection of conflicting states.
|
||||
|
||||
`DebuggerTraceBridgeTests` checks immutable decoded samples, before/after register text for both CPUs, range export, rejected triggers without losing a previous capture, strict trigger parsing and enabled/disabled breakpoint bridge state. Native UI validation and final build results are recorded in the main [debugger guide](DEBUGGER.md).
|
||||
@@ -0,0 +1,85 @@
|
||||
# Built-in FD-502 and DSK core milestone
|
||||
|
||||
> 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.
|
||||
|
||||
## Reused source and host boundary
|
||||
|
||||
`src/devices/FD502/Fd502Device.cpp` adapts the command model from Joseph Forgione's `platforms/windows/FD502/wd1793.cpp`: drive/side selection, register addresses, command families, step/settle delays, transfer timeouts, delayed byte-transfer completion and completion NMI. `src/devices/FD502/DiskImage.cpp` retains the sector-image geometry and layout. Copyright/provenance notices remain in the source. The original Windows DLL, settings/UI and physical-drive implementation are unchanged.
|
||||
|
||||
The portable implementation owns its registers, transfer buffer, four drives and head positions. It has no Windows handles, physical-floppy driver, native UI, global controller state or filesystem access. Separate instances are isolated. `src/devices/CartridgeDevice.h` supplies a small built-in registry and single-slot bus. The initial registry contains FD-502; it does not load a DLL. That initial callback contract carried NMI only. The subsequent native bus adds the selected devices’ cartridge signaling, DMA and MPI routing; see [cartridge integration](CARTRIDGES.md) and [hard disks](HARD_DISKS.md).
|
||||
|
||||
The session calls the device once on each falling horizontal-sync edge, after the PIA sync callback, matching the Windows `USE_NEWTIMING` connection. Pause freezes device time. Soft/cold reset cancel commands and stop the motor while retaining the device, mechanical head positions, mounted images and modified bytes. Shutdown disconnects callbacks before destroying the machine host. CPU changes and ROM reloads retain device ownership and reset controller state.
|
||||
|
||||
An FD-502 requires a user-supplied 8 or 16 KiB disk ROM, separate from the 32 KiB system ROM. The ROM occupies a 16 KiB cartridge window; an 8 KiB image is padded with `0xff`. Public source builds contain neither ROM. Explicit private inputs are now supported by Debug staging and local signed packaging.
|
||||
|
||||
## Image and transfer support
|
||||
|
||||
- Headerless JVC/DSK defaults to 18 sectors per track, 256 bytes per sector and one side, as upstream does. Double-sided geometry must be described by a JVC header or a recognized OS-9 descriptor; image length alone does not disambiguate it.
|
||||
|
||||
- JVC headers of one through four bytes specify sectors, sides, sector-size code and first-sector number. Supported limits are 1–256 tracks, one/two sides, 1–64 sectors, and 128/256/512/1,024-byte sectors. The payload must be a multiple of 256 bytes and contain complete tracks. Images are bounded to 16 MiB.
|
||||
|
||||
- Headerless OS-9 sector images with the upstream 18-sector geometry are recognized only when their descriptor's total sector count matches the image length. This is image-layout support, not evidence that NitrOS-9 boots yet.
|
||||
|
||||
- Restore, seek, step, single/multiple sector read/write, synthetic read-address, force interrupt and sector-image write-track formatting are connected. A standard blank 35-track DSK is 161,280 bytes. `DSKINI` supplies the filesystem through guest controller commands.
|
||||
|
||||
- The control register selects all four single-sided drives, or either side of a selected double-sided drive. Unowned ports return zero and ignore writes. NMI completion uses the retained density/control-bit gate; forced interrupts retain upstream's simplified low-nibble behavior.
|
||||
|
||||
- Writes change owned image bytes. Complete sectors commit together; interrupted partial sectors are discarded. Whole write-track streams are validated before any sector changes. Write protection is enforced before data acceptance and again by the image backend.
|
||||
|
||||
- Busy controllers reject media replacement. Dirty images require explicit export acknowledgement or discard before drive eject/replacement. Serialization preserves the image header and untouched sectors. The application bridge now enforces these protections when disabling the whole device and when quitting; bus installation is an owner-level operation, not a user-facing eject command.
|
||||
|
||||
Some safety and determinism changes are intentional: malformed geometry is rejected before indexing or shifting; invalid sectors cannot alias another track; short images are rejected rather than padded on read; switching drive/side aborts an active transfer; write-track parsing is bounded and transactional; random index wobble is replaced by a fixed 3,144-scanline revolution. Multi-sector commands now advance until the next sector is unavailable, whereas the retained Windows implementation records the multi-sector flag without using it. An end-of-transfer timeout no longer reports lost data when all payload bytes were serviced.
|
||||
|
||||
This retains the upstream controller's simplified timing model. HALT-line behavior, detailed density/side-compare/verify options, address CRC fidelity, copy-protected media and rotational timing accuracy are not established by this milestone. Read-track returns record-not-found for sector containers, consistent with upstream's JVC/OS-9 path. This initial checkpoint rejected DMK, VDK and attribute-byte JVC containers. See the November 5 update below for DMK and VDK. Becker networking, the Disto clock, alternate DOS configurations, MPI and physical drives are outside this checkpoint.
|
||||
|
||||
## Validation
|
||||
|
||||
Validated November 1, 2026 using the local Xcode 27.2 toolchain:
|
||||
|
||||
- **57 XCTest tests passed:** 45 shared C++ checks, seven application-bridge tests and five native tests.
|
||||
|
||||
- Debug and Release apps built as arm64/x86_64 universal binaries.
|
||||
|
||||
- The 45-check Release console suite and both-CPU disk-ROM integrations passed as arm64 and as x86_64 under Rosetta. Rosetta is not physical Intel validation.
|
||||
|
||||
- Focused floppy checks and both-CPU disk-ROM integrations passed AddressSanitizer and UndefinedBehaviorSanitizer. The pre-existing full-suite speech-chip sanitizer limitation remains documented in [audio/cassette validation](AUDIO_CASSETTE.md).
|
||||
|
||||
- The earlier optional system-ROM checks still pass BASIC sound, CAS/WAV save/load, fast CAS and soft/cold resets on both CPUs with no disk device installed.
|
||||
|
||||
- Six new shared checks cover image geometry/round trips, invalid input and bounds, command timing, transfers/formatting, protection/cancellation, bus routing/lifetime and complete machine integration.
|
||||
|
||||
- The machine integration uses an authored ROM to verify mapped cartridge ROM/data reads, one controller tick per scanline, and an actual FD-502 completion NMI serviced by both 6809 and 6309 engines. Pause/reset/shutdown lifetime checks do not require external ROMs.
|
||||
|
||||
- The optional disk-ROM check boots Disk Extended Color BASIC on both CPUs, runs `DSKINI0`, saves `10 PRINT 6*7`, verifies its directory entry, serializes/ejects/reloads the DSK bytes, cold-boots, and verifies `LOAD`, `LIST`, and `RUN` printing `42`. A protected save must report `?WP ERROR` and leave all image bytes unchanged.
|
||||
|
||||
Run the ROM-free tests through Product → Test in Xcode or the shared `VCCCoreChecks` scheme. To run the optional integration after building the Release console target:
|
||||
|
||||
```sh
|
||||
build/macos/Build/Products/Release/VCCCoreChecks --disk-rom /path/to/coco3.rom /path/to/disk11.rom
|
||||
```
|
||||
|
||||
The optional check currently expects the standard 8 KiB disk ROM. It opens both supplied ROM files read-only and creates every disk byte in memory. No ROMs, generated disks, logs or binaries are checked in.
|
||||
|
||||
Native drive/file controls, errors and filesystem export/reopen are covered by the follow-on milestone. NitrOS-9 boot/file operations, MPI and native configuration persistence were added in [hard disks](HARD_DISKS.md), [cartridges](CARTRIDGES.md) and profiles. The initial milestone left Windows interchange, broader disk-library qualification and physical Intel/macOS 14 testing open.
|
||||
|
||||
## DMK and VDK — November 5, 2026
|
||||
|
||||
All four FD-502 drives now mount and save DMK track images and uncompressed VDK sector images. The Mac file picker, Finder/drop routing, profile restoration and Software Library share this support. Standard DSK remains the first New Disk choice. A file named `.dsk` may contain any supported representation. Save As preserves the bytes in that representation, including extended headers and untouched tracks.
|
||||
|
||||
- **DMK.** The WD1793 reads the track's address table, actual sector sizes, deleted-data marks, and recorded CRCs. READ ADDRESS exposes the stored ID field. READ TRACK returns the captured track bytes after its pointer table. FM sectors stored twice and mixed FM/MFM disks are supported. A sector write updates its data mark, payload and CRC in place. WRITE TRACK replaces only a completed, validated track. Image-level write protection takes precedence over the drive switch.
|
||||
|
||||
- **VDK.** Signature, declared header length, tracks and sides locate the sector payload, including the 256-byte headers on both library VDKs. The reader also accepts the minimal 12-byte header produced by Windows VCC. This work applies to the FD-502. The separate CoCo SDC backend retains its own format limits.
|
||||
|
||||
- **Compatibility limits.** The controller uses deterministic timing and a simplified density model. Software relying on precise rotation, flux transitions or unusual protection routines needs title-specific testing. A readable Dragon-format disk still requires guest software compatible with the emulated CoCo.
|
||||
|
||||
### Validation and reproduction
|
||||
|
||||
The local Software Library contained **54 distinct DMK images and two VDK images** across 44 packages. Of the 55 DMK occurrences, 49 had a `.dsk` suffix. Disk BASIC read an independently located sector from each of the 56 images on **both the 6809 and 6309**. For the 55 writable images the test wrote a pattern, checked the surrounding bytes, ejected, remounted, reread and tried a protected write. White Fire's header protection rejected the initial write. Tests used in-memory copies.
|
||||
|
||||
*Shamus* exposed a false address marker in a protected directory track. A regression case reproduces it with authored bytes. The original disk passed `DIR` and reached its title screen with `RUN"SHAMUS"`. *Color FLEX 5.0:4* booted to its date prompt. *Kidwriter* listed its directory and reached its loading screen. Both extended-header VDKs passed sector checks. These observations describe the part of each title actually exercised.
|
||||
|
||||
- Run `VCCCoreChecks --disk-rom /path/to/coco3.rom /path/to/disk11.rom` for the six DSK/DMK/VDK × CPU round trips. Each creates a new disk, runs `DSKINI0`, saves a BASIC program, lists the directory, reopens the disk, cold-boots, loads and runs the program, and checks write protection.
|
||||
|
||||
- For retained software, [the optional real-media probe](../../tests/macos/fd502-media-probe.cpp) takes the ROMs, disk file, physical track, sector and independently determined payload offset. For the protected *Shamus* edition use `17 1 109019 --dir SHAMUS`. For Tiburon's `Dragon/S37H.VDK` use `17 3 157440`. Each invocation tests both processors and opens all host inputs read-only.
|
||||
|
||||
- The Xcode regressions cover failure without replacing mounted media, header protection, format-preserving export, Finder/drop choices and library routing. `testCreateDMKAndVDKFromFloppyWindow` exercises both menu choices in the isolated running app.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Graphics and frame timing — 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.
|
||||
|
||||
## Portable interfaces
|
||||
|
||||
- `VideoState` holds borrowed emulated memory and a host-owned render surface. It contains no window handles. The Windows `SystemState` inherits these fields, preserving source access for existing callers; `VideoHost.cpp` forwards surface and clearing requests to the Windows implementation.
|
||||
|
||||
- The Mac checks use a packed **640 × 480** surface of 32-bit **`0x00RRGGBB`** pixels. Pitch is measured in pixels, not bytes. On the supported little-endian hosts the bytes are B, G, R, zero. The native display bridge treats these as opaque pixels rather than interpreting the zero byte as transparency. The renderer still retains upstream 8/16/24-bit entry points for Windows, but the Mac path and new pixel tests use 32-bit output only.
|
||||
|
||||
- `ApplyVideoRegister` and `ApplyTimerRegister` connect machine-register writes directly to a selected `GimeGpu`. Tests now use the real graphics/timer implementation instead of recording those calls. External input, cartridge devices, audio delivery, cassette files, and printer output remain explicit test replacements.
|
||||
|
||||
- `RunFrame` is a synchronous execution operation. It returns when a frame completes, the debugger halts, a cycle budget is reached, or the CPU makes no progress. The final instruction can exceed the requested budget. Budget-limited frames can resume; the function does not restart the raster, pace wall-clock time, lock a window, or flush audio. The Windows event-based frame loop uses it too, replacing a loop that could wait indefinitely after a breakpoint.
|
||||
|
||||
Only one scheduled GPU/machine may own the global scheduler and host bindings at a time. Install the machine, video and debugger hosts, initialize memory/CPU, reset the scheduler, and then reset/configure the GPU before execution. Keep the surface and borrowed memory alive during rendering. Call `StopEvents` before changing hosts, memory, or the scheduled GPU. GPU callbacks carry weak lifetime guards, so abandoned callbacks cannot dereference a destroyed renderer. `StopEvents` cancels all owned raster and timer tags, while leaving unrelated scheduler events alone. Immediate debugger preview GPUs do not own scheduled raster tags.
|
||||
|
||||
## Seven added checks
|
||||
|
||||
| Check | Coverage |
|
||||
| --- | --- |
|
||||
| Pixel output | Known red/green/blue/white values, nibble order, horizontal/vertical doubling, alternating black scanlines, and unsupported-width regression |
|
||||
| Mode sweep | 2,304 CoCo 3 / compatibility register combinations across every active row, framebuffer guards, and a separate composite PMODE4 artifact-path check |
|
||||
| Raster timing | Both CPUs complete 263-line frames; 912 clocks per line; four-line VSYNC pulse; subsequent frame period of 239,856 clocks |
|
||||
| Full-frame pixels | CPU-driven eight-bar RGB image, every active pixel checked independently, and top/bottom border placement |
|
||||
| GIME timers | Fast-clock restart delay, interrupt issue delay, overlapping delayed IRQs for short periods, zero-count stop, and scanline-clock countdown |
|
||||
| Video lifecycle | Reset replaces existing callbacks, stop cancels owned events, and destroyed renderer callbacks expire safely |
|
||||
| Frame stops | Breakpoint halt returns immediately, bounded work, partial-frame resume, and stalled-CPU detection |
|
||||
|
||||
The synthetic `BRA` loop takes three CPU cycles per instruction. At 16 clocks per cycle, the first completed frame consumes 14,994 cycles because event boundaries are exclusive and execution finishes whole instructions; the following frame consumes 14,991 cycles. These checks preserve the retained source's timing model. They do not establish exact agreement with every GIME revision or a new Windows trace.
|
||||
|
||||
The mode sweep includes combinations whose derived width exceeds the supported framebuffer. Those layouts are deliberately skipped, rather than allowed to write into unrelated rows. The sweep establishes memory safety for the tested inputs; it is not visual parity evidence for every mode, palette, scroll, or mid-line register transition.
|
||||
|
||||
## Corrections and validation
|
||||
|
||||
Graphics operations now use their own GPU instance rather than accidentally calling the global Windows renderer. Raster update bookkeeping is initialized and cleared on reset; display geometry is established before the first sync event. Timer clock selection lives in the GPU, reset/stop cancels its scheduled work, and switching away from the fast timer cancels its remaining retrigger event. Multiple delayed IRQs are preserved when the timer period is shorter than the issue delay.
|
||||
|
||||
AddressSanitizer found an existing framebuffer overflow: a 1-bpp/128-byte row derived 1,024 pixels, causing the unsigned stretch factor to underflow and a border write to land past the framebuffer. Unsupported oversized layouts now leave the surface untouched, and duplicated border-row writes are bounded. A targeted regression check accompanies the broader sweep.
|
||||
|
||||
The full RGB color-bar frame was also exported outside the repository and visually inspected. It is generated entirely from authored RAM contents and the retained renderer; no ROM file, screenshot, binary, or user media was added to Git. See the build guide for current validation results.
|
||||
|
||||
## Subsequent integration and open qualification
|
||||
|
||||
The [Mac controller](MAC_CONTROLLER.md), [native boot](NATIVE_BOOT.md), [audio/cassette](AUDIO_CASSETTE.md), input and selected cartridge/storage devices now use this renderer. The native Metal display presents the active picture at 4:3 with the selected scaling/filtering; the core framebuffer contract above remains unchanged. Physical Intel/macOS 14, broader guest video modes, Windows recompilation/reference comparison and the wider representation audit remain open in the [porting plan](PORTING_PLAN.md).
|
||||
@@ -0,0 +1,47 @@
|
||||
# Native virtual hard disks
|
||||
|
||||
> 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.
|
||||
|
||||
## Saving and recovery
|
||||
|
||||
Writable backed images save automatically, coalesced at roughly one-second intervals. Only changed sectors cross the bridge. Per-sector revisions prevent a completed save from clearing guest writes made while that save was pending. Normal saves keep emulation running. Quit pauses and drains pending automatic saves, then warns if temporary, unbacked, protected or failed-save changes remain.
|
||||
|
||||
Host saves run off the emulation queue: copy the source to a sibling temporary file, verify its SHA-256 against the last known contents, apply sector changes and any zero-filled growth, synchronize the file, and atomically replace the source. File coordination and identity/size/modification checks detect ordinary external changes. Symbolic links are resolved so automatic saving preserves the link. A failed save retains in-memory changes, pauses execution, and offers Retry Save or Save As. Missing files are not silently recreated. Concurrent writes by noncooperating applications are not supported; do not share a writable backing file between emulators or drives.
|
||||
|
||||
Copying can use filesystem copy-on-write support, but hashing still scans the whole image. Long-running workloads and repeated writes to maximum-size images need performance profiling. Images are held in memory; explicit full-image export also needs temporary memory. This is not a crash-recovery journal, and a crash can lose changes not yet saved.
|
||||
|
||||
The guest flush command requests an immediate background-save pass. Its success status means the request was accepted, **not** that bytes are already durable on the Mac filesystem. Temporary/protected modes still apply. This differs from the Windows implementation’s synchronous `FlushFileBuffers` and remains a documented durability limitation.
|
||||
|
||||
Drive URLs, protection, temporary mode and clock options live in the additive `hardDisks` section of the existing version-1 `DiskAssignments.json` under Application Support. Older settings remain readable. Missing images retain their assignments and expose **Retry Unavailable Hard Disks**. Moving or renaming a file requires selecting it again; these are file URLs, not persistent bookmarks. Preferences contain no image or ROM bytes.
|
||||
|
||||
## Device contract
|
||||
|
||||
`HardDisk/HardDiskDevice.h` adapts `HardDisk/cc3vhd.cpp` into an owned portable device. It retains two drives, 24-bit sector addressing, 256-byte transfers, current-MMU DMA and the baseline register map:
|
||||
|
||||
| Address | Operation |
|
||||
| --- | --- |
|
||||
| `$FF80–$FF82` | Sector number, high byte first |
|
||||
| `$FF83` | Command write / status read |
|
||||
| `$FF84–$FF85` | 16-bit DMA address, high byte first |
|
||||
| `$FF86` | Drive 0 or 1 |
|
||||
|
||||
Commands are 0 read, 1 write and 2 flush. Status is 0 success, 4 missing/out-of-range, 5 write protected, `$FE` invalid command and `$FF` after reset. DMA wraps at 16 bits and follows current mapped memory, including an 8 KiB boundary. Recursive commands caused by DMA into I/O are suppressed. Reads past current EOF return zeroes within the 512 MiB limit; writes grow the image with zero-filled gaps. The Windows EOF loop’s stale-last-byte behavior and inclusive upper-bound bug are deliberately corrected.
|
||||
|
||||
The clock uses the retained serial cookie and ports `$FF78/$FF79/$FF7C`. It starts from Mac local time and keeps VCC/NitrOS-9’s years-since-1900 encoding. Guest clock writes are disabled by default. When enabled, they change only a session-local virtual offset, never the Mac clock. Reset clears serial transaction state; relaunch discards the offset. Clock-enable and write-permission preferences persist.
|
||||
|
||||
## Validation
|
||||
|
||||
Ten new hostless tests cover image bounds/growth, dirty-sector revisions, protocol/status/drive selection, DMA wrap and MMU boundaries, both CPU engines through MPI alongside FD-502, clock packets and write protection, atomic file saving, read-only/missing/external-change recovery, symlinks, invalid files, temporary mode, settings restoration, blank creation/export, disconnection, pending-save quit draining, and stale acknowledgements. All 92 XCTest tests passed on arm64 and x86_64 under Rosetta. Debug and universal Release builds succeeded with the local Xcode 27.2 toolchain.
|
||||
|
||||
An optional ROM-dependent console check booted the supplied NitrOS-9 image through RGBDOS on both emulated CPUs, created `vccmactest` with the expected contents, and independently parsed its OS-9 file descriptor/data from a reopened image. It passed on arm64 and x86_64 under Rosetta. Supplied files are opened read-only; all guest writes stay in an owned memory copy:
|
||||
|
||||
```sh
|
||||
build/macos/Build/Products/Release/VCCCoreChecks --hard-disk \
|
||||
/path/to/coco3.rom /path/to/rgbdos.rom /path/to/VCCEmuDisk.vhd
|
||||
```
|
||||
|
||||
This check expects the tested RGBDOS/NitrOS-9 `DOS255` boot layout, not an arbitrary VHD. The tested image is 135,659,520 bytes with SHA-256 `2ccd07cdfd6aa4d8a1d3ceff04f0a6c3490bde23e40e7c136830334f2264f462`. The supplied Empty and Sierra VHDs were inventoried as sector-aligned images; their applications/boot paths have not been exercised.
|
||||
|
||||
The native Release-app pass opened a disposable NitrOS-9 copy, verified its sector count, toggled protection/temporary mode, created and saved a 64 KiB blank second image, assigned the controller in MPI, and verified both images/options and the controller assignment after actual quit/relaunch. The device-specific Hard Drives menu was checked to appear on assignment, open the controls, and disappear on removal; menu observation was corrected during that check. Test media were then ejected and the user’s original cartridge and floppy settings restored. Native NitrOS-9 typing and file saves were not separately exercised in this UI pass; those paths are covered by the headless boot check and automated host-file tests. Original supplied images remain unchanged. No ROMs, images, screenshots or raw logs are committed.
|
||||
|
||||
Physical Intel/macOS 14 runtime, Windows reopening of Mac-written images, broader NitrOS-9/software libraries, sustained I/O and power-loss recovery remain outside this validation. SuperIDE remains deferred. SDC is a separate implemented device with its own supported formats and qualification limits.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Memory and hardware registers — 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.
|
||||
|
||||
## Connections and ownership
|
||||
|
||||
`MachineHost.h` makes the remaining connections explicit: ROM provisioning, cartridge memory/ports/audio, graphics register writes, timer controls, CPU selection and interrupt lines, keyboard scans, joystick strobes, tape signals, and printer bits. Every connection is required in the interface. The Mac tests install a recording host with synthetic ROM/cartridge bytes and controlled input. It records video/timer requests; it does not render video, advance a GIME timer, decode tape files, or emulate a cartridge device.
|
||||
|
||||
`MachineHost.cpp` supplies the Windows adapter, forwarding to the original implementations. Windows printer file/console handling has moved out of the PIA source into `PrinterWin.cpp`. That file is included in the Windows project and excluded from the Mac project. The native Mac host and Printer Output are now implemented separately; this extraction fixture uses a recording host.
|
||||
|
||||
The normal CPU memory functions now dispatch to the real MMU. Isolated instruction tests explicitly install a `CpuMemoryBus` containing flat memory, then detach it. The machine checks leave that override unset. No synthetic ROM or test bus is linked into the application target.
|
||||
|
||||
Install the machine/debugger hosts before initialization and keep them alive until execution and teardown finish. Select and initialize a CPU before routing interrupts to it. Clear the isolated CPU bus override when using the real MMU. Initialization, reset, execution, inspection, host replacement, and teardown must all be serialized by the machine controller: the legacy global state and initialization flag do **not** provide thread-safe ownership. Accessing a missing machine host on macOS fails explicitly rather than silently discarding a hardware operation.
|
||||
|
||||
`MmuInit` validates the RAM configuration and prepares RAM/ROM before replacing the active allocation. Allocation or ROM-provider failure returns null and retains the previous memory. The provider receives a 32 KiB buffer prefilled with `$FF`; file selection and ROM validation belong to the host. `LoadRom` similarly preserves the current ROM on failure. `MmuShutdown` releases both allocations and can be called repeatedly. Borrowed RAM/ROM pointers are invalidated by successful reinitialization or shutdown. The Windows host still reads the configured ROM path; its existing hard-reset caller treats a null initialization result as fatal.
|
||||
|
||||
## Added shared checks
|
||||
|
||||
| Check | Coverage |
|
||||
| --- | --- |
|
||||
| MMU mapping | 128 KiB, 512 KiB, 2 MiB, and 8 MiB configurations; reset/disabled maps; both tasks; physical write isolation; bank masks and 8 MiB prefix; debugger snapshots |
|
||||
| ROM and vectors | All four internal/cartridge ROM selections, write protection, SAM RAM/ROM toggles, internal interrupt vectors, and the fixed `$FE00` RAM-vector window |
|
||||
| Memory lifecycle | Power-on pattern, invalid configuration, failed ROM loading/reloading, replacement ROM, bounded page inspection, repeated teardown |
|
||||
| GIME/SAM registers | Selected-CPU floating-bus reads, palette masks, combined video offset, timer command forwarding, speed controls, bit-addressed video settings, cartridge port routing, IRQ/FIRQ masks and acknowledgement |
|
||||
| PIA registers | Data direction, keyboard column mask, joystick strobes, DAC/stereo sample, cassette output/input/motor, serial bit forwarding, mux selection |
|
||||
| PIA interrupts | Sync-edge polarity, independently asserted sources, control/data acknowledgement, cartridge FIRQ, side-effect-free debugger reads, reset |
|
||||
| Mapped CPU execution | Both CPUs execute guest writes to MMU/task registers, isolate `$A5` and `$5A` in physical pages 5 and 6, receive a GIME IRQ through the SAM vector, stack into mapped RAM, acknowledge the interrupt, and return with RTI |
|
||||
|
||||
These are authored source-level expectations, not a newly captured Windows reference trace. The existing Windows evidence remains separate. No ROM downloads, user media, raw logs, or binaries are added to the repository.
|
||||
|
||||
## Corrections covered by the checks
|
||||
|
||||
- GIME floating-bus reads now consult the selected CPU; previously they always consulted the 6809, including when the 6309 was running.
|
||||
|
||||
- GIME and PIA resets release their asserted CPU interrupt lines as well as clearing register latches.
|
||||
|
||||
- MMU initialization rejects out-of-range RAM configurations and preserves active allocations on failure. Debugger page reads are bounded, and reads after teardown cannot dereference freed memory.
|
||||
|
||||
- SAM vector reads use the current internal ROM allocation, avoiding a stale cached pointer after memory reinitialization.
|
||||
|
||||
## Validation and remaining work
|
||||
|
||||
The Debug console suite passes 21 checks on arm64. The Release suite passes on arm64 and as x86_64 under Rosetta. AddressSanitizer and UndefinedBehaviorSanitizer pass the combined CPU, scheduler, and machine checks. See the build guide for the current XCTest result and IDE instructions.
|
||||
|
||||
Graphics generation and frame/timer scheduling are now [extracted](GRAPHICS_CORE.md). The [Mac machine host and application bridge](MAC_CONTROLLER.md) now own serialized lifecycle and frame delivery. The [native boot milestone](NATIVE_BOOT.md) now adds ROM selection, Metal display and keyboard input. These checks validate register behavior and callback routing, not complete video/audio/tape/device timing. Windows recompilation, physical Intel testing, macOS 14 runtime testing, and full Windows/Mac trace parity remain outstanding. Phase 1 is still in progress.
|
||||
@@ -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).
|
||||
@@ -0,0 +1,31 @@
|
||||
# Native ROM boot, Metal display and keyboard — Phase 2
|
||||
|
||||
> 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.
|
||||
|
||||
## Display and input boundaries
|
||||
|
||||
- `EmulatorDisplay` embeds a native `MTKView` in SwiftUI. The CPU renderer still produces a 640 × 480 packed `0x00RRGGBB` image. Metal uploads it as BGRA bytes, forces opaque output, samples with nearest filtering, and letterboxes to 4:3 using drawable pixel dimensions. Retina backing size and window size do not alter the emulation timer.
|
||||
|
||||
- Every GPU submission owns its upload texture. Up to three submissions can be in flight; if the GPU is busy, presentation skips rather than waiting on the main thread or overwriting a texture still in use. Discrete-memory devices use managed uploads; unified-memory devices use shared uploads. Physical Intel GPU validation remains outstanding.
|
||||
|
||||
- `DisplayShader.txt` contains the small Metal shader source. It is copied into the app/test bundle and compiled through the Metal runtime at startup. The local Xcode installation lacks the optional offline Metal toolchain; this keeps the checked-in project self-contained without downloading that component. Initialization errors are shown in the native window.
|
||||
|
||||
- `CocoKeyboard` tracks held host-key identities and translated chords. Key-up removes the original chord even if modifiers changed. Host key-repeat is ignored; the emulated machine handles repeat. Shift transitions update held letters/special keys. Natural punctuation retains its selected chord until release.
|
||||
|
||||
- `MachineSession::setKeyboard` accepts a complete held-key matrix on the emulation queue. The PIA reads the actual active-low CoCo matrix, and new presses issue the retained GIME keyboard interrupt. Pause ignores further input until resumed. Focus loss, window deactivation, app deactivation, ROM replacement and reset release held keys.
|
||||
|
||||
- The retained renderer's blink state toggles at the Windows frame-loop interval. [Audio and cassette](AUDIO_CASSETTE.md) now connect to scheduled PIA samples. Joystick input, disks and [cartridge/MPI](CARTRIDGES.md) were connected in subsequent milestones; no Windows DLL loader is used.
|
||||
|
||||
## Repeatable checks
|
||||
|
||||
The default suite needs no ROM: **39 shared C++ checks + 7 bridge tests + 5 native display/file/keyboard tests = 51 XCTest tests**. The Metal tests read actual GPU output at five drawable sizes and verify resize preserves the source frame. They verify red/green/blue order, top/bottom orientation, opaque alpha and black letterboxing. Keyboard tests cover all 56 matrix positions, real PIA reads, modifiers, natural punctuation, repeat and release. File checks cover valid, missing, directory, wrong-size, oversized and invalid-vector input.
|
||||
|
||||
An optional integration check uses a ROM supplied at run time:
|
||||
|
||||
```sh
|
||||
build/macos/Build/Products/Release/VCCCoreChecks --rom /path/to/coco3.rom
|
||||
```
|
||||
|
||||
It boots each CPU for 300 frames, enters `10 PRINT 6*7` and `RUN` through matrix presses/releases, checks for `42` in guest text RAM, verifies pause, soft-resets while running and paused, lists/reruns the retained program, and cold-boots back to a clean BASIC prompt. The ROM and resulting screenshots are never written into Git.
|
||||
|
||||
The supplied ROM has SHA-256 `ad358430568250eb8330a37f85361d9ce67e5ae6d5a28c17b31802cd3953a5d2`, already recorded in Phase 0. Both CPU modes passed this check on arm64 and under x86_64 Rosetta. The native BASIC display, program execution and both reset controls were exercised on the local Apple Silicon Mac. Both CPU modes passed running/paused soft reset and keyboard focus recovery; window zoom/restore and clean Quit were also checked. See the interactive check record. This is not evidence of physical Intel, macOS 14 runtime, exhaustive graphics-mode parity, or sustained timing accuracy. See the build guide for build/test results.
|
||||
@@ -0,0 +1,37 @@
|
||||
# VCC Plus for Mac: native macOS porting plan
|
||||
|
||||
> 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.
|
||||
|
||||
## 3. Recommended architecture
|
||||
|
||||
| Area | Implementation | Boundary to preserve |
|
||||
| --- | --- | --- |
|
||||
| Application lifecycle, menus, emulator window | AppKit; use SwiftUI for suitable settings and forms | UI commands reach the core through explicit operations |
|
||||
| CPU, memory, GIME, PIA, bus, device behavior | Existing C/C++ | Emulated hardware behavior remains independent of UI frameworks |
|
||||
| Swift-to-C++ access | A small Objective-C++ bridge with an explicit interface | Keep C++ ownership and implementation details out of UI code |
|
||||
| Display | Metal/MetalKit presenting the generated framebuffer | Preserve pixel generation, palette, artifact colors, and scanline behavior |
|
||||
| Audio | Core Audio output consuming buffered samples | Preserve emulated sound timing; accommodate host sample rates separately |
|
||||
| Input | AppKit keyboard/mouse events and Game Controller support | Translate host events into CoCo key and joystick state |
|
||||
| Files and preferences | Native file panels, Foundation, and appropriate C++ file operations | Attach DSK images to emulated floppy drives; separate media access from hardware logic; no physical floppy backend |
|
||||
| Networking and serial | Native sockets/serial facilities behind device-specific interfaces | Preserve the emulated protocol and register behavior |
|
||||
| Expansion devices | Built-in C/C++ modules with native device selection and configuration UI | Preserve slot selection, device operations, callbacks, and user controls; DLL loading is not required |
|
||||
| Build | Xcode project with app, C++ library, and test targets | Build and test the core independently from the application |
|
||||
|
||||
Use one emulation worker initially and keep application UI on the main thread. Send commands to the worker and publish consistent state snapshots back to the UI. Transfer video and audio through bounded buffers with defined ownership. Audio callbacks must avoid disk access, allocation, and waiting on the UI.
|
||||
|
||||
The core remains the authority for emulated time. Display refresh rates and audio hardware rates must not redefine CPU speed or device timing.
|
||||
|
||||
Do not create a general replacement for Win32 APIs. Replace each actual dependency with an appropriate core interface or native Mac implementation. Start with one emulated machine per application; multiple independent machines would require additional work on the existing global state.
|
||||
|
||||
## Device scope decision — November 3, 2026
|
||||
|
||||
| Device | Decision | User value and reason |
|
||||
| --- | --- | --- |
|
||||
| Speech/Sound Cartridge | Implemented | Speech and synthesized sound used by CoCo software; native media management cannot replace those hardware capabilities. |
|
||||
| SDC | Implemented baseline; broaden compatibility | Native SDC-DOS ROM/folder selection, protected/writable cards, directory commands, DSK/JVC/VDK, multidisk switching and 512-byte streaming. All four Multi-Pak positions have SDC artwork, shared native controls and actual-transfer indication. Double Dragon loads all nine disks and reaches gameplay on both CPUs at 2 MB. SDC Explorer 1.35 passes configuration, browsing and BASIC launch; broader collection and OS-9 coverage remains open; flash programming, RTC and SDF/special formats are deferred. See scope and validation. |
|
||||
| Game Master Cartridge | Evaluate later with representative games | Banked ROM and its sound chip may be required by desired games. Require concrete test software before committing scope. |
|
||||
| SuperIDE | Deferred | Virtual hard disks already cover ordinary storage needs; revisit for software requiring the IDE interface. |
|
||||
| Becker/DriveWire | Outbound TCP implemented, November 5 | Optional FD-502 Becker networking for NitrOS-9 clients and a guest-only local Mac shell with 80×24 terminal handling. The Software Library and existing disks handle file delivery. See the NitrOS-9 guide. |
|
||||
| ACIA/RS-232 | Deferred | Revisit for terminal, BBS or serial-device workflows. |
|
||||
| Bit-banger printer output | Implemented | Native live text capture, text/raw export and printing; see Printer Output. Broader serial communications remain deferred. |
|
||||
| X-SID | Deferred | Revisit for specific music/software that benefits from this sound device. |
|
||||
@@ -0,0 +1,95 @@
|
||||
# Phase 3 timing and sustained-use checks
|
||||
|
||||
> 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.
|
||||
|
||||
## Timing contract
|
||||
|
||||
The retained Windows timing implementation enables `USE_NEWTIMING`. Its event clock is 14,318,180 Hz; a frame has 263 scanlines of 912 clocks each. That is 239,856 clocks per frame, approximately 59.695 frames/second. Sound-disabled Mac execution uses this interval, retaining deadlines across small host scheduling delays. A delay longer than four frame intervals abandons the old deadline instead of replaying a large backlog. Pause, reset, and sound enable/disable establish a new deadline.
|
||||
|
||||
With sound enabled, output consumption paces a queue approximately 100 ms ahead of the device. This adds about 50 ms of queue latency compared with the previous target; guest clocks are unchanged. Output starts only after the reserve is filled, in bounded batches of at most four guest frames per queue turn. CPU instructions, video, cassette samples, and device events still use guest time. Muting changes gain only; it does not flush the queue, restart the output engine, or execute extra guest frames to refill it. The render callback remains allocation-free and lock-free. A running engine that consumes no samples for a second falls back to silent, nominal-speed execution and reports an error; toggling Sound retries output.
|
||||
|
||||
The retained `$FFD8`/`$FFD9` speed switches and `$FF96` turbo bit provide normal, double, and quadruple CPU throughput. They leave raster duration and audio sample production unchanged. `TimingChecks.cpp` exercises those mapped registers on both CPUs using an authored three-cycle branch loop and verifies the independent cycle totals and sample counts.
|
||||
|
||||
This is source-contract validation, not a new timed Windows/Mac comparison. Windows also has host-specific throttle/audio feedback and a 60 FPS target. The Mac does not copy the Windows sampler's `+25 Hz` compensation. Windows frame skipping advances all guest frames while omitting presentations; the Mac likewise publishes fewer display updates than guest frames. Native Machine Settings now provide presentation intervals of 1–6 frames, fast-forward, and CPU overclock factors of 1–16. Their cycle/sample, transition, persistence and media-safety tests extend this source-contract validation; timed Windows comparisons and sustained high-overclock tests remain open.
|
||||
|
||||
## Repeatable checks
|
||||
|
||||
The normal Xcode test action includes:
|
||||
|
||||
- Thirty simulated minutes of irregular host callbacks without accumulating frame drift; short-delay catch-up, long-delay recovery, and resume deadline reset.
|
||||
|
||||
- Audio-progress timeout, progress recovery, and timeout reset after pause/device restart.
|
||||
|
||||
- Normal/double/turbo/back-to-normal register sequences on both CPU engines, with unchanged video/audio timing.
|
||||
|
||||
- A modeled 80 ms producer stall while the audio consumer keeps reading; the new reserve retains every sample and refills without overflow. The previous 50 ms reserve fails this case.
|
||||
|
||||
- Native volume/mute changes without output-engine restarts; switching to silent pacing and back; existing pause, reset, shutdown, buffer ordering and overflow/underrun checks.
|
||||
|
||||
The opt-in real-time runner uses the actual native controller and audio output, loads a separately supplied CoCo 3 ROM read-only, and types this authored BASIC workload:
|
||||
|
||||
```basic
|
||||
10 SOUND100,255
|
||||
20 PRINT 42
|
||||
30 GOTO10
|
||||
RUN
|
||||
```
|
||||
|
||||
It never loads remembered settings, mounts media, writes the ROM, or changes system volume. Its own output gain is zero; nonzero samples are counted before gain to verify that the tone loop continues. Logs report wall time, emulated frame time, consumed audio time, buffer occupancy, output starts, maximum callback request, maximum refill interval, sample shortages, and resident memory. Refill intervals exclude graph-creation time, before consumption begins. Counts are lifetime totals; the measured interval subtracts the warm-up baseline. Missing audio is measured in stereo sample frames (44,100 per second), not individual incidents. Memory includes retained frame snapshots.
|
||||
|
||||
From the repository root:
|
||||
|
||||
```sh
|
||||
export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
|
||||
# Native output remains active, with zero gain.
|
||||
tests/macos/run-sustained-check.sh /path/to/coco3.rom 1800 6809
|
||||
# Test the other CPU with sound disabled and nominal host pacing.
|
||||
VCC_CHECK_ARCH=x86_64 tests/macos/run-sustained-check.sh /path/to/coco3.rom 1800 6309 silent
|
||||
```
|
||||
|
||||
`VCC_CHECK_ARCH` accepts `arm64` or `x86_64`; the default is the host architecture. `VCC_CHECK_BUILD_DIR` optionally selects a build directory outside the checkout. The script builds both architecture slices. Rosetta execution is useful coverage but does not substitute for physical Intel hardware.
|
||||
|
||||
The script temporarily prevents idle system sleep for the runner's lifetime without changing saved power settings. Leave the Mac awake (do not manually sleep it) and its output route unchanged for a baseline run. The requested duration begins after boot, typing, and warm-up. Acceptance requires maximum sampled frame/audio deviation from wall time below 250 ms, resident-memory growth below 64 MiB, no additional sample shortages or overflow, continued execution without reset/error, and stable frame/audio counters after Pause. Each maximum is sampled approximately once per second, so this does not measure every short transient or end-to-end display latency. Output-device and sleep tests are separate interruption checks; their results must not be combined with uninterrupted baselines.
|
||||
|
||||
## Local evidence
|
||||
|
||||
Verified November 1–2, 2026, locally on Apple M5 Pro with Xcode 27.2/macOS 27.2:
|
||||
|
||||
- All 110 XCTest tests passed on arm64 and x86_64 under Rosetta. The Release console runner passed all 55 shared checks in both architecture slices, and the app built as a universal binary.
|
||||
|
||||
- The native app ran a NitrOS-9 shell on the main display at both 120 Hz (4,818 frames / 80.638 seconds, approximately 59.75 FPS) and 60 Hz (3,997 frames / 66.955 seconds, approximately 59.697 FPS). These are short accessibility-counter measurements, not precision visual synchronization measurements. The first attempted interval was discarded because a ROM load reset the counter. The display was restored to 120 Hz.
|
||||
|
||||
- Moving the running app to a second physical 60 Hz monitor retained the shell and rendering: 4,265 frames / 71.389 seconds, approximately 59.74 FPS. The app was returned to the original 120 Hz display.
|
||||
|
||||
- Two native-app RSS observations about eight minutes apart, spanning monitor changes, were 407,968 KiB and 341,520 KiB. This includes loaded media and display resources; it is a bounded-memory spot check, not a peak-memory trace.
|
||||
|
||||
- Native Pause held NitrOS-9 at frame 32,380 for more than 50 seconds; Run resumed the same shell, and Return produced a fresh prompt without reset or stuck input.
|
||||
|
||||
- The default USB headphone device runs at 48 kHz, exercising AVAudioEngine's conversion from the guest's 44.1 kHz stream. A second connected display runs at 60 Hz. Neither test changes guest clock constants.
|
||||
|
||||
Development runs with the earlier 50 ms reserve exposed intermittent shortages. The first pair used default queue priority; another audio run tested interactive priority. Desktop use and Xcode builds/tests continued during these runs:
|
||||
|
||||
| 30-minute workload | Maximum frame/audio deviation | Peak RSS growth | Missing / overflow samples | Result |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| arm64, 6809, native audio, default queue priority | 66.770 / 49.140 ms | 1,343,488 bytes | 1,888 / 0 | **Failed** the strict no-gap criterion. One early shortage totaled about 42.8 ms of missing samples; no additional shortages followed. Execution, bounded drift, memory and Pause checks otherwise held. |
|
||||
| arm64, 6309, native audio, interactive queue priority and 50 ms reserve | 68.915 / 36.070 ms | 1,359,872 bytes | 1,029 / 0 | **Failed** the no-gap criterion after a shortage at about 25 minutes. Priority alone was insufficient. |
|
||||
| x86_64 under Rosetta, 6309, sound disabled, default queue priority | 87.698 ms / not applicable | 2,490,368 bytes | 0 / 0 | **Passed** nominal pacing, memory and Pause criteria. |
|
||||
|
||||
After those shortfalls, the reserve was increased to 100 ms with full prefill before engine startup. A diagnostic run observed requests of at most 471 samples, so there was no oversized callback requirement in that run. The final implementation passed separate thirty-minute native-audio runs on arm64/6809 and x86_64/6309, concurrently with the native diagnostic app. This is not a guarantee against arbitrary OS stalls; the callback fills any future shortage with silence and counts it. Hardware interruption checks remain separate.
|
||||
|
||||
The final 100 ms reserve results were:
|
||||
|
||||
| 30-minute workload | Maximum frame/audio deviation | Peak RSS growth | Missing / overflow samples | Result |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| arm64, 6809, native audio | 38.235 / 7.738 ms | 1,327,104 bytes | 0 / 0 | **Passed**, including continued tone production, no reset/error, and stable frame/audio counters after Pause. |
|
||||
| x86_64 under Rosetta, 6309, native audio | 37.072 / 10.018 ms | 11,231,232 bytes | 0 / 0 | **Passed** the same criteria. Most memory growth occurred early, then remained bounded. |
|
||||
|
||||
Both engines stayed at one successful start throughout their measured interval. The largest observed callback request was 471 sample frames; maximum refill intervals were 23.344 ms (arm64) and 23.435 ms (x86_64). These runs did not reproduce the earlier longer interruption, so the separate modeled 80 ms stall remains the direct regression for the added reserve. Passing a thirty-minute window does not guarantee glitch-free output under every host workload.
|
||||
|
||||
The 100 ms implementation passed a separate 120-second native 6809 run while the default output was changed from USB headphones to built-in speakers: zero missing/overflow samples, maximum frame/audio deviations 45.132/43.363 ms, peak RSS growth 1,458,176 bytes. Audio continued without a graph restart (the engine start count remained one). Observed callbacks requested at most 471 sample frames, and the maximum measured refill interval was 10.992 ms. This establishes continued output consumption across the system route change; it was performed at zero gain and is not a listening comparison. USB output and its existing volume were restored, and the native app remained running. The user then put the Mac to sleep and woke/unlocked it. The updated native app was paused at frame 9,423 with Sound enabled and no error, remained at that count after wake, and resumed to frame 13,562 without reset or error. This uses the authored diagnostic session; the earlier NitrOS-9 session had already passed pause/resume and keyboard checks.
|
||||
|
||||
## Remaining acceptance work
|
||||
|
||||
This milestone does not by itself close M3. Physical Intel hardware, macOS 14, exact-revision Windows timed comparisons, a broader game/OS-9 workload matrix, additional audio devices/sample rates, and sustained visual synchronization remain separate coverage. The one-second stalled-consumer detector is covered with a fake clock; a forced live-driver hang has not been exercised. Controller reconnection and keyboard/mouse input were verified in native input. Audio listening and cassette round trips are recorded in [audio/cassette](AUDIO_CASSETTE.md).
|
||||
|
||||
For this timing checkpoint, ROMs, raw logs, generated media and raw screenshots remain outside Git. The repository retains authored checks and summaries; later milestones also include curated native screenshots with their provenance.
|
||||
Reference in new issue
Block a user