Files
VCCPlusOSS/docs/macos/NATIVE_BOOT.md
T

3.9 KiB
Raw Blame History

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 now connect to scheduled PIA samples. Joystick input, disks and cartridge/MPI 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:

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.