This project has one goal - a compatible re-implementation of the Famicom Disk System BIOS under an OSS license. Unlike the Famicom console itself, which has no program ROM built-in, the Famicom Disk System includes an 8 KiB PRG-ROM containing disk I/O routines, VRAM transfer routines, joypad reading code, an animation featuring Mario and Luigi when no disk is present in the drive, and more. The code, data, graphics, music, and animation contained in the original BIOS are copyrighted by Nintendo.
FreeDiskSysROM aims to provide a replacement for the original FDS BIOS that can be freely redistributed and that is capable of running all published FDS software.
This repository is a fork maintained by rom-weaver, for use as a freely redistributable FDS BIOS in EmulatorJS.
- James Athey created FreeDiskSysROM and wrote the original BIOS, VRAM, and input routines: jamesathey/FreeDiskSysROM
- yeah4578 (Nicholas Qualls) wrote the disk I/O routines and the boot screen: yeah4578/FreeDiskSysROM
- Changes made in this fork are listed in its git history.
Famicom and NES emulators historically require a dump of the Famicom Disk System BIOS to be able to emulate FDS titles. Emulators can ship FreeDiskSysROM with their installers instead of requiring end-users to either copy the ROM out of their own FDS hardware or breaking copyright law by downloading a BIOS rip from elsewhere on the Internet.
Modern hardware clones of the FDS RAM Adapter or FPGA re-implementations of the entire Famicom Disk System also need a BIOS.
Tested in EmulatorJS (FCEUmm core) with this BIOS:
- The Legend of Zelda (Japan): boots, loads side B, and saves a new file to disk. The save survives a console reset.
- Kid Icarus (Japan): boots, creates its save file on first start, and reaches the title screen.
- Metroid, Galaga (Japan): boot to the title screen.
Also tested in the simulator: Akumajou Dracula, Ice Hockey, Zelda II, and Nazo no Murasame Jou boot and load.
| Address | Name | # of Games | Implemented |
|---|---|---|---|
| $e149 | Delay131 | ✅ | |
| $e153 | Delayms | ✅ | |
| $e161 | DisPFObj | ✅ | |
| $e16b | EnPFObj | ✅ | |
| $e171 | DisObj | ✅ | |
| $e178 | EnObj | ✅ | |
| $e17e | DisPF | ✅ | |
| $e185 | EnPF | ✅ | |
| $e18b | NMI | ✅ | |
| $e1b2 | VINTWait | ✅ | |
| $e1c7 | IRQ | ✅ | |
| $e1f8 | LoadFiles | ✅ | |
| $e237 | AppendFile | ✅ | |
| $e239 | WriteFile | ✅ | |
| $e2b7 | CheckFileCount | ✅ | |
| $e2bb | AdjustFileCount | ✅ | |
| $e301 | SetFileCount1 | ✅ | |
| $e305 | SetFileCount | ✅ | |
| $e32a | GetDiskInfo | ✅ | |
| $e3da | AddYtoPtr0A | ✅ | |
| $e3e7 | GetHardCodedPointers | ✅ | |
| $e3ea | GetHardCodedPointersWriteProtected | ✅ | |
| $e445 | CheckDiskHeader | ✅ | |
| $e484 | GetNumFiles | ✅ | |
| $e492 | SetNumFiles | ✅ | |
| $e4a0 | FileMatchTest | 0 | ✅ |
| $e4da | SkipFiles | 0 | ✅ |
| $e4f9 | LoadData | ✅ | |
| $e506 | ReadData | ✅ | |
| $e5b5 | SaveData | ✅ | |
| $e64d | WaitForDriveReady | ✅ | |
| $e685 | StopMotor | ✅ | |
| $e68f | CheckBlockType | ✅ | |
| $e6b0 | WriteBlockType | ✅ | |
| $e6e3 | StartXfer | ✅ | |
| $e706 | EndOfBlockRead | ✅ | |
| $e729 | EndOfBlkWrite | ✅ | |
| $e778 | XferDone | ✅ | |
| $e794 | Xfer1stByte | ✅ | |
| $e7a3 | XferByte | ✅ | |
| $e7bb | VRAMStructWrite | ✅ | |
| $e844 | FetchDirectPtr | ✅ | |
| $e86a | WriteVRAMBuffers | ✅ | |
| $e8b3 | ReadIndividualVRAMBytes | ✅ | |
| $e8d2 | PrepareVRAMString | ✅ | |
| $e8e1 | PrepareVRAMStrings | ✅ | |
| $e94f | GetVRAMBufferByte | ✅ | |
| $e97d | Pixel2NamConv | ✅ | |
| $e997 | Nam2PixelConv | ✅ | |
| $e9b1 | Random | ✅ | |
| $e9c8 | SpriteDMA | ✅ | |
| $e9d3 | CounterLogic | ✅ | |
| $e9eb | ReadPads | ✅ | |
| $ea1a | ReadDownPads | ✅ | |
| $ea1f | ReadOrDownPads | ✅ | |
| $ea36 | ReadDownVerifyPads | ✅ | |
| $ea4c | ReadOrDownVerifyPads | ✅ | |
| $ea68 | ReadDownExpPads | ✅ | |
| $ea84 | VRAMFill | ✅ | |
| $ead2 | MemFill | ✅ | |
| $eaea | SetScroll | ✅ | |
| $eafd | JumpEngine | ✅ | |
| $eb13 | ReadKeyboard | 0 | ✅ |
| $ebaf | LoadTileset | ✅ | |
| $ec22 | UploadObject | ✅ | |
| $ee17 | StartMotor | ✅ |
Every entry point is implemented and covered by the simulator tests below. Not yet done:
- The license screen check. A free BIOS cannot contain Nintendo's license text, so disks boot without it.
- Retrying a failed read or write, as the original BIOS does. A disk error is returned at once.
- Testing against a broad library of commercial disks.
To build, use asm6f.
asm6f freedisksys.asm disksys.rom
The -l flag is very useful for development - it shows the addresses assigned
to each instruction, so you can easily see how much room remains for a given
subroutine.
tests/test_bios.py runs the assembled ROM in a 6502 simulator (py65) with a simulated PPU and FDS drive. It covers booting, soft reset, loading files to RAM and VRAM, writing and verifying files, file counts, disk info, error codes, the keyboard, the VRAM routines, and objects. The disk tests run twice: once against a drive that delivers a byte every 148 CPU cycles, as real hardware does, failing if the BIOS misses a byte; and once against a model of the FCEUmm core's drive, which EmulatorJS uses.
pip install py65
python tests/test_bios.py disksys.rom
EmulatorJS runs FDS games with its NES core and loads the BIOS from EJS_biosUrl:
EJS_core = 'nes';
EJS_gameUrl = 'game.fds';
EJS_biosUrl = 'disksys.rom';Prebuilt disksys.rom files are attached to each CI run.
To check FreeDiskSysROM in an emulator, python tests/make_demo_disk.py demo.fds writes a small disk that prints FREE BIOS OK using BIOS routines. It has no license file, so the original BIOS refuses it with error $20.
Rules:
- Do not even look at a disassembly of the original FDS BIOS.
- Only contribute code to which you hold the copyright or which is already under a compatible license.
FreeDiskSysROM is licensed under the GNU LGPL v3 (see LICENSE), which builds on the GNU GPL v3 (see COPYING). The intent in using this license is to allow anyone to replace the 8 KiB official FDS BIOS with FreeDiskSysROM, whether for commerical or non-commercial purposes, so long as the source of FreeDiskSysROM (including any modifications) is made available to the end-user under the same license.
Although the Famicom does not have an OS or any concept of dynamic linking, the FDS BIOS is analogous to a system library in practice. FDS titles, FDS emulators, and FDS clone systems are all permitted to utilize FreeDiskSysROM without regard to or changes to the licenses of their own code.