Files
VCCPlusOSS/docs/macos/TIMING_RELIABILITY.md
T

96 lines
11 KiB
Markdown
Raw Blame History

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