Files

48 lines
6.3 KiB
Markdown
Raw Permalink Blame History

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