Repository navigation
ISO Loader: VMU emulation unusable on SCIF SD adapter (freeze / console reset / failed save across multiple games) #142
Description
Environment
- Console: Dreamcast VA0 (Japanese), MIL-CD capable
- Storage: SD via serial port adapter (SCIF, bit-bang SPI) — ~700 KB/s read (Speedtest app)
- SD card: Lexar 512 GB SDXC, FAT32/MBR, 32 KB clusters
- DreamShell: v4.0.4 release rebuilt 2026-07-25 (with the latest fatfs fixes) loaded from SD via bootloader v2.9 CD; also reproduced identically on v4.0.3
- Games: unmodified GDI dumps, each in its own folder under /games, launched via ISO Loader app (SD device, dma = 0, async = 8)
VMU emulation (vmu = 1, private 128 KB dump in the game folder, VMU number 1, IRQ hooking enabled) fails on the SCIF-SD path in every game tested, with three different failure modes. Results are identical on 4.0.3 and 4.0.4, so this is not a regression.
- Shenmue (USA) │ heap Auto / Ingame (Katana) / Maple DMA buffer; also CDDA on + heap Behind │ freezes at the game's "NOW LOADING" screen │ heap Behind the loader, or fixed 0x8cfd0000 │ passes loading, then black screen
It doesn't look Shenmue-specific either: with the same VMU settings, other games on my setup also misbehave in different ways — one resets the console at boot, another boots and detects the emulated VMU but fails when actually saving. So my impression is that VMU emulation as a whole struggles on the SCIF-SD path on my hardware; Shenmue is just the game where I dug deepest.
Shenmue runs perfectly from the same SD/setup with irq = 0 and no VMU emulation (memory 0x8cfe8000, the embedded preset values).
Additional observations
- Without irq = 1 the emulated VMU is completely silent (expected from the code — maple_init_irq() is only reached inside if (IsoInfo->use_irq) in firmware/isoldr/loader/syscalls.c), and games report "no memory card". Maybe worth forcing/documenting, since a preset with vmu > 0 but irq = 0 silently does nothing (the Games Menu already forces it, the ISO Loader GUI forces it only via the checkbox).
- With the 1 MB VMU dump, maple.c derives geometry from file size (last_block = total/512 - 1 = 2047). Shenmue detects the card but rejects it as "not formatted" — 1999–2000 era games seem to validate against real-VMU geometry (255). The 128 KB dump is required for those games; might be worth a note in the app.
- device_info in firmware/isoldr/loader/maple.c advertises MAPLE_FUNC_STORAGE | MAPLE_FUNC_LCD | MAPLE_FUNC_CLOCK, but only storage commands are handled. Games that actively use the VMU LCD (Shenmue does) get no response to LCD writes — possibly related to its behavior.
- My working hypothesis for the SCIF-specific failures: the Maple DMA hook performs FatFs file I/O inside the interrupt path, which on bit-bang SPI at ~700 KB/s blocks far longer than on IDE — different games then die in different ways depending on how hard they hit the Maple bus (SA2 resets, Virtua Tennis fails on write, Shenmue hangs). If VMU emulation is only expected to work on IDE/HDD, documenting that would already help.
Happy to run debug builds or provide more logs/tests on this hardware — this console+adapter combo seems to be a blind spot (none of the 1027 embedded SD presets enable vmu).
Thanks for the recent fatfs fixes in the rebuilt 4.0.4 — they resolved a long-standing mxml: Bad control character error when opening the ISO Loader app from SD (42 KB app.xml crossing the 32 KB cluster boundary was read corrupted; small app.xml files never failed). That one is confirmed fixed on real hardware.
Activity
DC-SWAT commentedon Jul 26, 2026
Thanks for the detailed report! There's one detail you didn't take into account, which I've written about elsewhere, but unfortunately, there's no complete guide. For VMU emulation to work, you need to leave the original VMU in the slot. This will improve in game detection and keep the LCD screen usable. However, all files on the original VMU will turn into mush, as it will also be written to, so be prepared for that. Nothing will happen to it; just format it later and that's it. Another thing to consider: loader with VMU emulation is much larger, and not all games have enough free space for it. Also WinCE games are not supported yet.
DC-SWAT commentedon Jul 26, 2026
I hope you are using optimized GDI (.iso tracks), since it works much better.
1 MB VMU support just few games unfortunately.
Also btw, for games such as Shenmue 1/2, Crazy Taxi 1/2 and so on (with data streaming during gameplay), for SD better set the emu async param lower than default 8, for example 4/3/2 (need find better for your SD). The lower the value, the smoother the game runs, but the overall loading time is slower, and vice versa.
somentedan5577 commentedon Jul 26, 2026
Thank you for the quick and detailed answer — that clears up a lot.
You're right, and it's the one thing I couldn't have guessed: I never tested with the original VMU in the slot. I ordered one but it hasn't arrived yet, so every test in my report was done with an empty controller. I'll retest the whole matrix as soon as it gets here and report back, including whether Shenmue behaves once the real VMU is there to handle the LCD side.
The loader size point also makes a lot of sense and explains something I couldn't account for: the three games I tried failed in three different ways (freeze, console reset, failed save) rather than failing identically. If it still doesn't work with the physical VMU in place, I'll focus on the loader memory address instead of the heap setting, since that's where the extra size would bite.
Two things I'm doing meanwhile, based on your advice:
Your note about the 1 MB VMU matches what I saw from the game side: Shenmue detects it but rejects it as unformatted, while the 128 KB one is at least accepted as a card.
If it's useful, once I've retested with the physical VMU I'd be glad to write up what I learn as a short "VMU emulation requirements" summary you could reuse or adapt, you mentioned there's no complete guide, and I've now got fairly detailed notes on the failure modes.
Thanks again, both for the answer and for the recent fatfs fixes.
DC-SWAT commentedon Jul 27, 2026
It would be great if you could prepare such material. DreamShell has a number of features that aren't really described anywhere. I don't have time to write manuals for each of them, as I'm busy with coding and testing, of which there's a lot.
And it's very nice to talk to someone who understands everything; you haven't made a single mistake in your reasoning and understood me correctly in all respects.
Regarding the DreamShell 4.0.4 fixes, I uploaded two updates yesterday (2026-07-26), and now everything should work smoothly. Just re-download release archive to get it. This happened because of bugs in KallistiOS.
somentedan5577 commentedon Jul 27, 2026
First, a small disclosure: I'm from Brazil and my English isn't good enough for technical writing, so I use AI to help me put these comments together. The hardware, the tests and the observations are all mine — apologies if anything reads a bit oddly because of that.
The VMU arrived, so here are the results. Setup is the same as before (VA0, SD via serial/SCIF adapter, latest release archive re-downloaded), now with a real VMU in expansion socket 1 of the controller in port A.
Physical VMU alone, no emulation — Shenmue saves and loads normally. So the console, controller and VMU itself are all fine.
Emulation on, 128 KB dump (vmu = 1, irq = 1, private dump in the game's folder, real VMU in the socket):
What strikes me about #3 is that it works as a controlled experiment: the loader is the same size and at the same address as in #2. The only thing that changed is that the game rejects the card's geometry immediately instead of reading its filesystem — and then it runs fine. So the crashes in #2 don't look like they're about the loader's memory footprint; they look like they happen once the game actually starts reading blocks from the emulated device.
My guess, and I may well be wrong: every one of those block reads has to reach the SD card from inside the Maple DMA interrupt, and on this adapter (bit-bang SPI over the serial port, ~700 KB/s) that takes far longer than it would on IDE — so the game dies as soon as it uses the card for real. That would also explain why the feature works fine on IDE/HDD setups and why nobody has reported this before.
It does confirm the LCD behaviour you described: with the real VMU in the socket, the game's icon appears on it.
If there's any parameter I haven't tried that would reduce or defer the I/O happening inside the interrupt, I'd be glad to test it — my setup is ready and I can run whatever combination you'd like, including debug builds if that helps.
I'm still working on the guide and will post it here when it's done. I'll include this as a known limitation for serial/SD setups, since it seems worth documenting alongside the requirements.
DC-SWAT commentedon Jul 28, 2026
No, SD card even in serial port much faster than real VMU and it's not very bad if it reads inside interrupt few sectors, games should work with it, CDDA emulation as example, it reads much more.
Try demolition racer, re:veronica, alien front and quake 3.