Import a .sav file as a save state, and export the cartridge's save as one

[macabeus]

A .sav file — the raw battery-backup dump every other GBA emulator and every flash
cart reads and writes — can be brought into gba-kit as a save state, and the save
sitting in the machine right now can be written back out as one.

A ⋯ button beside Save state in the Screen panel's save-state bar opens a menu with
Import from a .sav file and Export to a .sav file. An import is a power-on machine
of this ROM with the file already in its cartridge, at frame 0: load it, press
continue, and the ROM boots into its own save. That is what VBA-M's
File > Import > Battery file… and mGBA's Load alternate save game both do, and it
makes the result independent of wherever the session happened to be stopped. The import
adds the state and opens the drawer; it does not load it, and the machine being debugged
is not touched — no event is emitted, the revision and epoch do not move, and a session
replaying history keeps replaying.

Over DAP and in-process the requests are gba-kit/importSave and gba-kit/exportSave.
The file dialog is a host capability (pickFile / saveFile on Transport), so VS Code
serves it with showOpenDialog and workspace.fs the way gba-kit.importLabels already
does, and the webapp serves it with <input type="file"> and a download. A menu item
whose host cannot serve it is not shown.

The real import, end to end

kleod.gba declares EEPROM_V121 and nothing else; the retail save is 512 bytes and
begins 4b5f4b4c4f4e4f41, "K_KLONOA". Two boots of 900 frames, one with the save
imported and one without:

declared save type: {"type":"eeprom","id":"EEPROM_V121"}

control     248 EEPROM commands (126 read, 122 write)   screen 61a7f2bb0f92732b
imported     87 EEPROM commands ( 56 read,  31 write)   screen 079f0bc8047a1582

control  cartridge after 900 frames: 0000000000000000
imported cartridge after 900 frames: 4b5f4b4c4f4e4f41 "K_KLONOA"

control  first commands: r@0 w@0 r@0 w@1 r@1 w@2 r@2 w@3 r@3 w@4
imported first commands: r@0 r@1 r@6 r@12 r@16 r@17 r@22 r@28 r@32 w@32

The control finds a blank chip, zeroes the header and formats a fresh save from word 0
upward. The imported run leaves the header standing and goes straight to the words it
wants, then writes the save back rather than replacing it. The two runs end on different
screens. That is the game reading the save, not 512 bytes sitting in an array.

What it refuses, and why

Which chip a file belongs in follows from the ROM's declared save type and the file's
size together. A file those two cannot account for is refused by a message naming
both — never padded or truncated into the wrong chip, where it would silently do nothing:

EEPROM_V121    512:OK  8192:OK   0:no 1:no 511:no 513:no 32768:no 65536:no 131072:no
SRAM_V113      32768:OK                        every other size refused
SRAM_F_V102    32768:OK                        every other size refused
FLASH_V126     every size refused,  export refused
FLASH512_V130  every size refused,  export refused
FLASH1M_V103   every size refused,  export refused
(no declaration) every size refused, export refused

Flash is refused in both directions. gba-kit backs the cartridge with plain memory
and emulates no flash chip, and flash chip emulation is out of scope here — so the
question was whether a flash game can read an imported save anyway. It cannot. Sonic
Advance 1, 2 and 3 each write the identify sequence AA/55/90, read where a chip ID
should be, get the imported save's own bytes back, write the reset command, and never
touch the save again — 0 data reads in 1200 frames — while the command bytes they
wrote land in the save as data. Accepting the file would have been a silent corruption
dressed up as a feature. 1 Mbit flash is doubly out: 128 KB cannot be represented in the
single 64 KB window at all, and bank switching is not emulated either.

An EEPROM that has not said how wide it is cannot be exported. The array is always
8 KB in memory but a 4 Kbit chip's .sav is 512 bytes, so exporting before the game has
read or written its save would be a guess. It is refused with instructions instead: run
the game until it touches its save, or import a .sav first.

Three emulator fixes came with it

• EEPROM images are now byte-compatible with mGBA, VBA-M and a flash cart. The array
  was byte-reversed within each 8-byte word against every real .sav. ⚠️ A save state
  written before this, of a game that uses EEPROM, comes back with its in-game save
  byte-swapped. The state format is unchanged and still loads, but that game's save
  inside it will not be read — re-import the .sav.
• SRAM_F_V cartridges get their SRAM. Detection looked for the literal SRAM_V,
  which SRAM_F_V102 does not contain, so those games had no working save at all.
• A 64 Kbit EEPROM is read at the right addresses. The width was latched at 6 bits by
  the sixth bit of any address and never revised, so a 64 Kbit cartridge read the wrong
  words for the whole run. It now comes from the length of the read the game makes, which
  is what actually carries it.

Deliberately left alone

• A 64 Kbit EEPROM whose very first save access is a write still gets 6-bit
  addressing. A write carries no length — 64 data bits follow the address with nothing
  marking where it ended — so settling the width from one would need the DMA transfer's
  word count plumbed to the chip, which is how mGBA and VBA-M do it. That is main's
  behaviour, not something this branch introduced, and no ROM on hand exercises it. The
  changeset says so plainly rather than implying it is fixed.
• An imported file settles nothing about the width. A 4 Kbit save padded out to 8 KB
  is a file several emulators write; trusting its length forced 14-bit addressing on a
  4 Kbit cartridge and desynced the line. The cartridge's own first read decides, and the
  file's length only answers for how big an export is until then. Both reviewers instead
  suggested sniffing the file's contents — rejected, since a file's bytes are no more
  evidence about the cartridge than its length is.
• Nothing validates that a .sav is the right game's save. A file of a legal size for
  the declared type is accepted whatever is in it. Nothing in the format says what it is.
• No new save-state version. An imported state is an ordinary state file, named after
  the file, with a name already taken getting (2).

🤖 Generated with Claude Code