Files

86 lines
11 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.
# 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.