[wesbiggs]

This is part 1 of a series of PRs to streamline and consolidate disk image (.d64/.d71/.d81) access, which will then be used to power the VDrive Special IO. This is a big hunk of code by itself, which is why I'm separating it out like this.

Rationale

The GEOS installer and the TR block device each carry their own image geometry, BAM and directory code, and VDrive brings a third, more complete engine (40-track D64s, error bytes, BAM and directory growth for all three kinds, tested against VICE's c1541). This brings VDrive's engine in under Source/Teensy/DiskImage/ so the other two can move onto it.

State of affairs after this PR

Nothing uses it yet. The copy differs from teensyrom-vdrive's d64/ (commit b74ce37) only in what the firmware needs: SPDX lines, the placement macros moving into d64.h, and its three constant tables marked D64_FLASH so they land in PROGMEM rather than DTCM. DiskImage.h includes the code once, for the single translation unit the firmware and the host harnesses build.

Follow-up PRs move the block device, then the GEOS installer and boot-file reader, then the TR menu's D64/D71/D81 loading and directory listing onto it.

Memory

• Every engine function is VD_COLD, which DiskImage.h defines as FLASHMEM on the firmware. None of it is reachable from the PHI2 ISR or an IO handler's cycle path.
• The constant tables are PROGMEM.
• The engine never calls malloc and adds no globals: all state lives in structs the caller owns, so it holds nothing in RAM1 or RAM2 between uses.
• Nothing in either firmware build includes DiskImage.h yet, so this PR doesn't change the TR or TR+ images. The RAM cost will show up in the follow-up PRs that call it, and those will report it.

Docs

• New docs/Architecture/Disk-Images.md: what the engine is, where it came from, how a caller uses it, the size-to-format table, and its tests.
• Linked from docs/Architecture/Overview.md.

Testing

• New host test Source/Teensy/tests/disk-image.test.js, which builds the engine with the firmware's warning flags as both C and C++. On a blank image of each kind it saves a file and reads it back, and it checks the size-to-format table.
• npm test passes, and CI is green on both firmware builds (tr, tr-plus) and the tools job.
• Host build only, not hardware tested. Nothing on the board runs this code until the follow-up PRs.

Compatibility

No change to the remote protocol (docs/ControlComms.md), the cartridge register map, the EEPROM settings or any timing.

License

The engine is my own work from teensyrom-vdrive, which is MIT licensed. The files here carry SPDX-License-Identifier: MIT.

🤖 Generated with Claude Code