[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

[kfox]

I reviewed the engine on the host. I built small C programs against DiskImage.h with fake reader/writer callbacks; I did not test it on hardware. Three defects and one design note are inline. None of them can happen on a board yet, since nothing calls the engine, but VDrive's write path will reach all of them.

[wesbiggs]

Thanks for the review, and for building against the engine on the host. The repros made each fix easy to pin down.

All four points are addressed, each with a host test in Source/Teensy/tests/disk_image_harness.c. I checked that every new case fails on the engine as it was:

• Disk full with blocks free: the allocator searches the rest of the disk before reporting FULL (1153fec).
• Failed close: the file being written is removed, and an append puts the original back (512683e).
• d64_build_dir: separate return codes, so a small buffer and an unreadable image no longer look the same (050deb8).
• @:: the old file is kept until the new one closes. A replace now needs room for both files, which d64.h documents (029f455, plus a locked-file test in 7a1d9e7).

One more change you didn't raise: the d64_format_blank comment now says to call it only on an image known to be all zeros, since it skips d64_format's clearing pass (6ebd42c).

npm test passes. The engine still isn't compiled into the firmware in this PR, so these changes don't affect its build. The branch that does compile it in builds for both TR and TR+ with these fixes, with RAM1 unchanged. Host build only, not hardware tested.