Skip to content

feat: complete the BIOS for EmulatorJS - #1

Merged
brandonocasey merged 19 commits into
masterfrom
readme-credits-and-stubs
Nov 3, 2026
Merged

brandonocasey merged 19 commits into
masterfrom
readme-credits-and-stubs

Conversation

@brandonocasey

@brandonocasey brandonocasey commented Nov 3, 2026 •

Copy link
Copy Markdown

FreeDiskSysROM stopped with most disk routines missing, and the yeah4578 fork filled in many of them but could not load or save reliably. This completes every BIOS entry point so the ROM can ship as disksys.rom for EmulatorJS, and credits both original authors.

  • Fills the remaining stubs (file counts, disk info, skip files, keyboard, objects) and fixes loading to VRAM, saving and verifying, error unwinding, soft reset, and the value GetHardCodedPointers passes in $02.
  • Writes blocks so they work on both real drives and FCEUmm, the EmulatorJS NES core: each block starts with an $80 mark, its last byte goes out before the CRC, and every written byte rewrites $4025.
  • Adds simulator tests (tests/test_bios.py, 54 tests) that run the ROM against a real-timing drive and a model of FCEUmm's drive, plus CI that builds and tests the ROM and attaches disksys.rom.
  • Validation: tests pass, and the BIOS keeps up with the disk down to 124 cycles per byte (real disks run near 148). A demo disk (tests/make_demo_disk.py) boots and prints text through BIOS routines in EmulatorJS with this ROM; without a BIOS, EmulatorJS falls back to the RetroArch menu.
  • Real games in EmulatorJS: The Legend of Zelda (Japan) boots, loads side B, and saves a new file that survives a console reset. Kid Icarus creates its save file and reaches the title. Metroid and Galaga reach the title. Fixed along the way: VRAM routines clobbered zero page outside their documented lists, the game could get an NMI before its setup finished, and disk errors returned with Z set so BNE missed them.
  • Risks: tested with only a few commercial disks. UploadObject treats its OAM index as a byte offset, which the docs leave unclear. There is no license screen check, and failed reads and writes are not retried.

Fill the disk, file count, disk info, keyboard, and object stubs. Fix save and verify, VRAM loads, error unwinding, write mode, soft reset, and the A value GetHardCodedPointers passes in $02.
Start each written block with the $80 mark and rewrite $4025 for every written byte. FCEUmm, the EmulatorJS NES core, drops the first byte of a block and only signals the next byte to write after a $4025 write.
A byte written to $4024 leaves at the next byte event, so EndOfBlkWrite waits one more event before sending the CRC, then waits out the CRC with a delay because drives raise no IRQs during it. The write loop is inlined to stay ahead of the disk.
Games call VRAMStructWrite, WriteVRAMBuffers, and LoadTileset from their NMI handlers, so these routines must only touch the zero page bytes listed in their Affects lines. They used $02-$06 as scratch, which corrupted Zelda's state. They now keep the pointer in $00/$01 and use the stack.
The BIOS turned NMIs on at a random point in the frame, then jumped to the game. An NMI could fire before the game finished its setup, which crashed Zelda. The BIOS now waits for a vblank first, giving the game a whole frame before its first NMI. NMIs stay on at handoff because Metroid expects them.
The simulator now clears the vblank flag at the end of vblank, stops a transfer when it is reset, and has a controller on $4016.
The error path popped the API's return address with PLP, so the flags took its high byte ($E2 or $E3), which has Z set. Callers that check BNE after LoadFiles or WriteFile took a missing or write-protected disk as success.
VINTWait returns with IRQs masked, so games started with I set after the handoff change. Cold boots start with I clear again.
Comment thread gethardcodedpointers.asm Resolved
Comment thread reset.asm Resolved
Comment thread README.md Resolved
@brandonocasey

brandonocasey commented Nov 3, 2026 •

Copy link
Copy Markdown
Author

✅ Nothing to fix at 1fad641 · 🔍 approved

5 🧪 QA checks · 3 🔍 closed findings
🧪 QA check Result Where Evidence
assemble ✅ pass head=1fad641
test_bios ✅ pass head=1fad641
entry-points ✅ pass (out of date)
emulatorjs-games ⏭️ skipped (out of date)
error-flags-and-boot-I ✅ pass head=1fad641
🔍 Closed finding Outcome
🐛 The error path discards the API return address with two PLPs, so the flags take its high … ✅ Fixed in 4eb7689
❓ HandOffPpu calls VINTWait, which returns with I set, so games now start with IRQs masked;… ✅ Fixed in 8ca2e58
💬 The not-done list names only write retries; LoadFiles does not retry a failed read either. ✅ Fixed in 1fad641

agt 0.34.1 · 🔍 review and 🧪 QA · 2 reviewers, claude-opus-5-5, claude-sonnet-5-5 · 17s · updated after each review

@brandonocasey
brandonocasey merged commit 494851c into master Nov 3, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant