The Family Computer Disk System (FDS) is a Nintendo add-on for the Famicom, sold in
Japan and Hong Kong. It replaces mask ROM chips with a cheap rewritable disk, the “Disk
Card”, a version of Mitsumi’s Quick Disk. Software is on one or more disk sides. The
BIOS loads data from disk into PRG RAM or VRAM before the program starts. The
unit also has a timer IRQ and a wavetable sound channel (the sound registers
$4040–$4097 are on
expansion audio). The wiki marks the
register section as pending updates from new research, so some entries are marked
unknown below.
The unit
| Property | Value |
|---|---|
| Company | Nintendo |
| Complexity | ASIC (the RP2C33) |
| BIOS PRG ROM | 8 KiB |
| PRG RAM | 32 KiB |
| CHR | 8 KiB (RAM) |
| Disk capacity | about 64 KiB per side |
| Mirroring | horizontal or vertical, switchable |
| Bus conflicts | no |
| IRQ | yes |
| Audio | yes |
Banks (all fixed)
- PPU
$0000–$1FFF: 8 KiB CHR RAM. - CPU
$6000–$DFFF: 32 KiB PRG RAM. - CPU
$E000–$FFFF: 8 KiB BIOS ROM. It controls the Famicom at power-on and reset, dispatches NMI and IRQ, and offers routines for disk access, controller reading and PPU handling.
Parts
- The RAM adapter (HVC-023) is a specially shaped cartridge. It holds the RAM chips and an ASIC with the DRAM controller, IRQ hardware, sound generation, the serial interface to the drive and a parallel port.
- The disk drive (HVC-022) is powered separately and connects to the RAM adapter only through a serial cable. It is a modified Mitsumi Quick Disk drive. Instead of a spindle motor plus a stepper motor, it has one motor that does both, so data is in a single spiral track. When the head reaches the end it is returned to the start with an audible click. Random access is therefore impossible, like a tape but much faster: one cycle through a disk side takes about 7 seconds. A red LED at the front is on while the motor runs. The drive has no “intelligence”: the serial interface almost directly mirrors what is on the disk.
- The Disk Card (HVC-021) is a modified Quick Disk. Its recesses spell “NINTENDO”.
Protections
- A physical lockout: molds in the drive fit only disks with recesses spelling “NINTENDO”, which keeps ordinary Quick Disks out (a trademark protection like the licence screen). It can be bypassed with custom recesses or adapters.
- Later revisions of the drive controller power board contain protection against the long writes of disk copiers; hardware modifications defeat it. The wiki has no measurement of how much data can be written on protected drives.
Registers $4020–$4033
The $402x registers are write-only, the $403x registers read-only.
$4020 and $4021: timer IRQ reload value
7 bit 0
---------
LLLL LLLL
++++-++++- $4020: the 8 low bits of the reload value; $4021: the 8 high bits
Unlike $4022, these two are not affected by the “disk registers enabled” flag ($4023 bit 0): the reload value can be changed even when disk registers are disabled.
$4022: timer IRQ control
7 bit 0
---------
xxxx xxER
||
|+- Timer IRQ repeat flag (bit 0)
+-- Timer IRQ enabled (bit 1)
Bit 0 is repeat (R), bit 1 is enable (E). Writing with E set copies the reload value into the counter. While E is set, the counter falls by one on every CPU cycle. When the counter is 0 and E is set, on every CPU cycle: an IRQ is generated; the counter is reset to the reload value ($4020 + $4021); and if R is not set, E is cleared and the counter stops.
- The register is affected by
$4023bit 0: while disk registers are disabled, writing to$4022does nothing and the counter cannot be started. - Clearing
$4023bit 0 stops the counter at once and acknowledges any pending timer IRQ. So does writing$4022with E clear. - Enabling the timer IRQ with a reload value of 0 gives an IRQ at once. With R set it gives an IRQ on every CPU cycle for ever.
- The disk transfer routine also uses IRQs, so timer IRQs must be disabled before any disk access.
- The only three known ways to acknowledge the timer IRQ: read
$4030; disable timer IRQs by writing$4022; disable disk registers by writing$4023.
$4023: master I/O enable
7 bit 0
---------
Wxxx xxSD
| ||
| |+- Enable disk I/O registers (1: enable; 0: reset and disable writes)
| +-- Enable sound I/O registers (1: enable; 0: reset audio)
+--------- Enable DRAM refresh watchdog interrupts (1: enable)
Clearing bit 7 acknowledges pending IRQs of the DRAM refresh watchdog and disables more from it, but does not change the watchdog itself. The BIOS writes $00 and then $83 during reset, so programs should keep this state. The audio toggle only resets the wavetable generation. The disk toggle only affects the write-only registers: the read-only registers are always mapped and active. While disk registers are reset and disabled:
$4025is set to$06(%00000110). Bit 3 shows in$4030bit 3 when this happens.- The byte transfer flag, timer and DRAM refresh watchdog IRQ sources are disabled (and so acknowledged). The wiki marks the state of the byte transfer flag as unknown, and that
$4022is probably set to 0 while the reload value stays writable as to be confirmed. - The watchdog’s CPU cycle timer is set to all ones (4095) and the refresh counter to 0. The watchdog resumes only when disk registers are enabled again.
$4026is set to$7F(%01111111) and the external connector output is disabled (there are external pull-ups on EXT0 to EXT6). The drive power/battery status in bit 7 can still be seen in$4033.
$4024: write data
The byte written is the next 8-bit value loaded into the shift register (next time the byte transfer flag rises) and shifted out to pin 5 of the RAM adapter cable (2C33 pin 52). Writing clears the byte transfer flag and acknowledges its IRQs.
$4025: FDS control
7 bit 0
---------
IE1C MTDS
|||| ||||
|||| |||+- Scan disk (0: reset; 1: scan)
|||| ||+-- Drive motor (0: start; 1: stop)
|||| |+--- Transfer mode (0: write; 1: read)
|||| +---- Nametable arrangement (0: horizontal, “vertical mirroring”; 1: vertical, “horizontal mirroring”)
|||+------ CRC transfer control (1: transfer the CRC value)
||+------- Unknown, always set to 1
|+-------- CRC enabled (0: disable and reset; 1: enable)
+--------- Interrupt enabled (1: IRQ every time the byte transfer flag is raised)
- The BIOS and commercial software always write 1 to bit 5. Writing 0 changes bits 1 and 2 of the external connector (
$4026/$4033), purpose unknown. - CRC values are stored on the disk and verified when a file is read or written. Disabling the CRC resets its state. The BIOS disables the CRC between file blocks and enables it before each block to calculate or check its CRC.
- To change the nametable arrangement on the fly, read, modify and write the BIOS’s mirror variable so unrelated bits stay as they are.
- Unknown (marked by the wiki): whether a write to this register acknowledges disk IRQs, and if so which bits do it.
$4026: external connector output
The output of the expansion terminal behind the shutter on the back of the RAM adapter. The outputs are open collector with 4.7 kohm pull-ups (except bit 7) and share the inputs of $4033. Setting $4025 bit 5 to 0 changes bits 1 and 2 of the output (also seen in $4033); purpose unknown.
$4030: disk status
7 bit 0
---------
BExC MxWT
|| | | ||
|| | | |+- Timer interrupt (1: an IRQ occurred)
|| | | +-- (bit 1) DRAM refresh watchdog (1: an IRQ occurred)
|| | +---- Nametable arrangement (from $4025 bit 3)
|| +------ CRC control (0: CRC passed; 1: CRC error)
|+-------- End of head (1 when the head is on the innermost track)
+--------- Byte transfer flag
Reading acknowledges all FDS IRQs except the byte transfer flag, so interrupt handlers must keep the value to check each source. (Earlier documents said reading also cleared the byte transfer flag; the wiki now says it does not.)
The byte transfer flag
It is set once 8 bits would have been transferred between the adapter and the drive, whatever the shift register holds. This is every 1,792 cycles of the 21.4772 MHz master clock, or 149⅓ CPU cycles. The flag is updated only under these conditions, otherwise it reads 0:
- Write mode (
$4025bit 2 = 0): CRC enabled (bit 6 = 1) and bit 5 = 1; the motor state does not matter. Some games for the Super Magic Card and other unlicensed RAM cartridges use this, with bit 7 set, as a frame-timing IRQ. - Read mode (bit 2 = 1): CRC enabled, bit 5 = 1 and the motor on (bit 1 = 0). The wiki marks as unknown what happens when bit 5 is cleared, and whether read mode also depends on the disk inserted/ready flags.
It can be polled whether or not interrupts are enabled (Tonkachi Editor polls $4030 bit 7 instead of using $4025 bit 7). If interrupts are enabled in $4025 bit 7, an IRQ is raised when the flag is set. The flag and its IRQ are cleared when $4024 or $4031 is accessed. The flag and IRQ can still be raised past the end of a disk side: the BIOS relies on this to find truncated files, and the disk copier Kosodate Gokko relies on it to find the end of a side.
The DRAM refresh watchdog
The 2C33 refreshes DRAM rows on CPU cycles that access areas outside PRG RAM, for DRAM chips without hidden refresh (such as the Hitachi HM48416). A watchdog counts these refresh cycles and CPU cycles. If interrupts are enabled in $4023 bit 7, it raises an interrupt after a certain number of cycles without enough refreshes. Small infinite loops (for example “everything in NMI”) and long stretches that touch only PRG RAM trigger it. Low-level implementation as known:
- A 7-bit refresh counter: 0 while
$4023bit 0 is 0; increments on each CPU cycle that accesses memory outside PRG RAM; pauses on PRG RAM accesses. It selects the row to refresh. - A 12-bit CPU cycle timer: set to all ones (4095) while
$4023bit 0 is 0; reloaded with 3,245 when the refresh counter overflows; otherwise decremented every CPU cycle. The IRQ is raised when it underflows while$4023bit 7 = 1. - Both keep running while the IRQ is asserted.
- Ignoring the watchdog (SEI, or turning it off through
$4023) seems to let DRAM decay in those cases. The decay is analogue and varies with adapter and DRAM maker; adapters with four DRAM chips may differ from those with one. The safest known way: keep$4023=$83from the BIOS reset handler, and in the IRQ handler check$4030bit 1 and call the BIOS routine Delay131 ($E149) when it is set. The BIOS’s default IRQ handler does likewise.
$4031: read data
Loaded from an internal shift register each time the byte transfer flag rises. Serial data arrives on pin 9 of the RAM adapter cable (2C33 pin 51). Reading clears the byte transfer flag and acknowledges its IRQs.
$4032: drive status
7 bit 0
---------
xxxx xPRD
|||
||+- Disk flag (0: disk inserted; 1: not inserted)
|+-- Ready flag (0: disk ready; 1: not ready)
+--- Protect flag (0: not write protected; 1: write protected or disk ejected)
Ready follows the head position: it is 1 when the head reaches the end of the disk and cleared when it returns to the start. Protect follows the write-protect tab at the upper left of the disk side (1 if the tab is broken). Reading this register does not clear the byte transfer flag (against older documents).
$4033: external connector input
7 bit 0
---------
BIII IIII
|||| ||||
|+++-++++- Input from the expansion terminal behind the shutter on the back of the RAM adapter
+--------- Drive power/battery status (0: voltage low; 1: good)
A bit cleared in $4026 reads back 0 here (except the battery bit), because of the open-collector inputs. The battery bit must be checked while the motor is on ($4025 bit 1 = 0), otherwise it reads 0. The wiki marks as unknown how this bit relates to the drive’s LED.
Disk format
Each side holds a little over 64 KiB. The BIOS reads blocks in the order 1, 2, 3, 4, 3, 4 … 3, 4: block 1 (disk information), block 2 (file count), then a pair of blocks 3 (file header) and 4 (file data) for each file.
Gaps and CRC
- Between blocks, and before the start of the disk, there are gaps of zero bits. Before the start: at least 26,150 bits, 28,300 typical. Between blocks: at least 480 bits, 976 typical.
- A gap ends with a single 1 bit. In terms of bytes this is
$80, because the data is stored in little endian bit order. - Each block ends with a 16-bit CRC, calculated by the RP2C33, not the CPU. It sets
$4030bit 4 if the CRC read does not match (BIOS error 27). The algorithm is CRC-16/KERMIT, and the 1 bit at the end of the gap is part of the calculation. - The usual
.fdsimage (fwNES) holds 65,500 bytes per side with no CRCs or gaps. The.QDimage (seen in re-releases) holds 65,536 bytes per side with CRCs but no gaps. The true capacity is somewhat larger, and a few variant formats hold more.
Block 1: disk information ($38 bytes + CRC)
| Offset | Bytes | Meaning |
|---|---|---|
$00 | 1 | Block code $01 |
$01 | 14 | ASCII *NINTENDO-HVC*; the BIOS refuses a disk without it |
$0F | 1 | Licensee code |
$10 | 3 | Game name, three ASCII letters (ZEL for The Legend of Zelda) |
$13 | 1 | Game type: $20 normal; $45 “E” event (for example DiskFax tournaments); $4A “J” unknown, may indicate the Family Computer Network Adapter; $52 “R” price reduced by advertising |
$14 | 1 | Game version; starts at 0 and rises per revision |
$15 | 1 | Side number: 0 = A, 1 = B (one-sided disks use 0) |
$16 | 1 | Disk number: first disk 0, second 1, … |
$17 | 1 | Disk type (FMC): 1 for FMC blue-disk releases, otherwise 0 |
$18 | 1 | Unknown; 0 in all known games |
$19 | 1 | Boot read file code: the file code up to which files load at boot |
$1A | 5 | Unknown; $FF $FF $FF $FF $FF |
$1F | 3 | Manufacturing date (see below) |
$22 | 1 | Country code; $49 = Japan |
$23 | 1 | Unknown; $61 (perhaps a region code) |
$24 | 1 | Unknown; $00 (perhaps a location) |
$25 | 2 | Unknown; $00 $02 |
$27 | 5 | Unknown (perhaps some game information) |
$2C | 3 | “Rewritten disk” date (perhaps when a Disk Writer kiosk formatted the disk); equals the manufacturing date on an original disk |
$2F | 1 | Unknown |
$30 | 1 | Unknown; $80 |
$31 | 2 | Disk Writer serial number |
$33 | 1 | Unknown; $07 |
$34 | 1 | Disk rewrite count in BCD; 0 = original |
$35 | 1 | Actual disk side: 0 = A, 1 = B |
$36 | 1 | Disk type (other): $00 yellow disk; $FF blue disk; $FE prototype, sample or internal use (white or pink). Some prototypes have $00, perhaps unfilled |
$37 | 1 | Disk version; unknown how it differs from the game version. Perhaps it rose with each disk received from a licensee |
$38 | 2 | CRC (absent in .fds files) |
If the system starts with a disk whose side number and disk number are not both 0, it asks for the first disk side. Some games set 0 even on the second disk to make it bootable too. All files with an ID less than or equal to the boot read file code load at boot.
Date format: three bytes in BCD: year, month, day. The year is usually the 1-indexed year of the current Japanese era, Shōwa (1926) or Heisei (1989): observed $61–$63 for 1986–1988 and $01–$03 for 1989–1991. Disk Writer kiosks kept using Shōwa years after that era ended, up to $78 before service ended in 2003. A few games used the last two digits of the Western year ($85, $86).
Block 2: file amount (4 bytes with CRC)
$00 block code $02; $01 number of files; $02 two CRC bytes (absent in .fds). More files may exist on the disk but the BIOS load routine ignores them (“hidden” files). Some games use this as copy protection: their own loader hard-codes a larger file count. It also loads faster, because the BIOS stops reading after the last visible file.
Block 3: file header ($12 bytes with CRC)
| Offset | Bytes | Meaning |
|---|---|---|
$00 | 1 | Block code $03 |
$01 | 1 | File number |
$02 | 1 | File ID (the ID given at the disk-read call) |
$03 | 8 | File name, usually uppercase ASCII |
$0B | 2 | File address, 16-bit little endian: destination when loading |
$0D | 2 | File size, 16-bit little endian |
$0F | 1 | File type: 0 program (PRG RAM), 1 character (CHR RAM), 2 nametable (VRAM) |
$10 | 2 | CRC (absent in .fds) |
File numbers normally rise from 0. The BIOS does not use them on reads. File IDs can be freely chosen and decide which file loads (the parameter disks of Quick Hunter use identical file numbers except for the first file and tell files apart by ID only). A file ID less than or equal to the boot read file code marks a boot file. The BIOS writes to the PPU only when the file type is not 0, so types 2 and above are the same as 1.
Block 4: file data
Block code $04, then the file data, then two CRC bytes (absent in .fds).
Block 5: test data
Block code $05, then a repeating $6D, $B6, $DB to fill the side, then a CRC. It appears, in fragments, on retail disks, probably left by formatting. FMC Disk Card Checker can write and verify it. Some Magic Card 1M, 2M and 4M disks use block 5 for trainer data.
Non-standard formats
The format is enforced only in software by the BIOS routines, so custom formats are possible with low-level disk routines. Examples: Kosodate Gokko stores its main program with no block indicator (data prefixed by a $12 byte) and loads it with the BIOS disk IRQ handler; Quick Hunter stores an encrypted main program in a block of type 0 (data XORed with $C9; common dumps lack the needed 0 byte); Graphic Editor Hokusai and Jingorou use interleaved, encrypted PRG and CHR with fake file blocks; Game Doctor and Magic Card devices switch in a replacement BIOS and read their own formats.
The .fds file (fwNES)
An optional 16-byte header, then 65,500 bytes per side. Header: bytes 0 to 3 are $46 $44 $53 $1A (“FDS” and an MS-DOS end-of-file), byte 4 is the number of sides, bytes 5 to 15 are zero. Sides are in the order disk 1 side A, disk 1 side B, disk 2 side A, and so on. After the last file block, fill the side with zero to exactly 65,500 bytes. Some images omit the header. Most games have an even number of sides; ports from NROM had one, and no commercial FDS game had an odd number above one.
RAM adapter cable pinout
The RAM adapter needs a cable to the disk drive (real or emulated). The wiki marks this page as pending verification of the pin functions (taken from documentation of other Quick Disk drives) and of the register mapping. Looking into the open end of the adapter’s drive connector, pins 1, 3, 5, 7, 9, 11 are the top row and 2, 4, 6, 8, 10, 12 the bottom row. “/” means active low.
| Pin | 2C33 register | 2C33 pin | Cable colour (RAM-side pin) | Direction | Signal |
|---|---|---|---|---|---|
| 1 | $4025 bit 2 | 50 | 5 (green) | output | /write gate (polarity still to be confirmed on the wiki) |
| 2 | - | 64 | 12 (cyan) | output | VCC (+5 V) |
| 3 | $4025 bit 1 | 48 | 7 (violet) | output | /motor on |
| 4 | - | 32 | 1 (brown) | output | VEE (ground) |
| 5 | $4024 (through a shift register in the 2C33) | 52 | 3 (orange) | output | /write data (polarity still to be confirmed) |
| 6 | $4033 bit 7 | 37 | 11 (pink) | input | busy |
| 7 | $4032 bit 2 | 47 | 8 (grey) | input | write protect (polarity still to be confirmed) |
| 8 | - | - | - | input | motor VCC (no wire in the cable) |
| 9 | $4031 (through a shift register) | 51 | 4 (yellow) | input | read data |
| 10 | $4032 bit 0 | 45 | 10 (black) | input | /media set |
| 11 | $4032 bit 1 | 46 | 9 (white) | input | /ready |
| 12 | $4025 bit 0 | 49 | 6 (blue) | output | /reset |
Motor VCC (pin 8) is not used by the RAM adapter: an electronically controlled 5 V supply inside the drive generates it and shares it with the drive motor, so the motor comes on only when this pin has voltage. Signals: /write gate when active says the data on /write data is to be written to the media; /motor on controls the drive motor by default; /write data is the serial data to be written while the gate is active; busy is checked by the BIOS after /motor on to see that the motor started, and if it is inactive the BIOS concludes the drive’s batteries have failed (it is a TTL version of the motor VCC signal; the wiki wonders whether it also controls the drive LED); write protect, when active, says the media is write-protected; read data is the data read off the media while /motor on is active; /media set (also called /media sw) says media is present; /ready falls to tell the adapter the drive acknowledged /motor on and the head is at the start (outermost track), stays active while the head advances across the disk, and goes inactive at the end (innermost track) or when /motor on goes inactive; /reset, while active, holds the media pointer at the beginning, and when inactive lets it advance at a constant rate while data is transferred (the wiki notes that other devices’ reset logic seems simpler and that it probably just stops the motor, blocks the write logic and makes /ready go inactive). If /write gate is active, $4025 bit 0 seems to stop the motor and disable the write logic by force (to be confirmed on the wiki).
Expansion terminal
The FDS has an expansion port at the rear of the RAM adapter, behind a shutter (labelled Expansion Port B on the Twin Famicom). The unreleased Famicom Network Adapter was designed to use it. Two unlicensed devices are known to use it: the ILine-PC (connects the FDS to a PC’s printer port) and the Super Copy System: Hacker Pro Digital (disk copier software). Open-end view of the 10-pin connector:
+5V -- | 1 2 | <> EXT6
EXT5 <> | 3 4 | <> EXT4
EXT3 <> | 5 6 | <> EXT2
EXT1 <> | 7 8 | <> EXT0
SOUND <- | 9 10 | -- GND
+5 V comes from the main voltage regulator; GND is 0 V. EXT0 to EXT6 are bidirectional: outputs from $4026 bits 0 to 6 and inputs to $4033 bits 0 to 6, open-collector with 4.7 kilohm pull-ups (EXT1 and EXT2 are altered when $4025 bit 5 is 0, purpose unknown). SOUND is the analogue audio output after the FDS audio is mixed in.
RP2C33 ASIC pinout
The RAM adapter’s ASIC (RP2C33 or RP2C33A) is a 64-pin shrink DIP. In the list, R means the pin connects to the LH2833 DRAM in later PCB revisions, r to the DRAM in all revisions, f to the Famicom; + means an open-drain output that needs an external pull-up. The PRG address bus to the DRAM is multiplexed, as is typical.
| Pin | Signal | Pin | Signal |
|---|---|---|---|
| 1 | /ROMSEL in (R, f) | 64 | +5 V |
| 2 | CPU A14 in (R, f) | 63 | XTAL2 in |
| 3 | CPU A13 in (R, f) | 62 | XTAL1 out |
| 4 to 8 | CPU A12 to A8 in (f) | 61 | /EnableRAS in (grounded) |
| 9 to 14 | PRG A6/13 down to A1/8 out (r) | 60 | /RAS out (r) |
| 15 | PRG A0 out (r) | 59, 58 | /CAS1, /CAS0 out (r) |
| 16 | CPU A7 in (R, f) | 57 | R/W in (R, f) |
| 17 to 23 | CPU A6 down to A0 in (f) | 56 | M2 in (R, f) |
| 24 | /CE4100 out | 55 | /IRQ out (open drain, f) |
| 25 to 31 | CPU D0 to D6 (R, f; bidirectional) | 54 | audio out (f) |
| 32 | GND | 53 | +TestMode in (grounded) |
| 33 | CPU D7 (R, f; bidirectional) | 52 | SER OUT (open drain) |
| 34 | CIRAM A10 out (f) | 51 | SER IN |
| 35 | PPU A11 in (f) | 50 | $4025 bit 2 out (open drain): disk 0 = write, 1 = read |
| 36 | PPU A10 in (f) | 49 | $4025 bit 1 out (open drain): motor 0 = start, 1 = stop |
| 37 | EXT7/BATT (bidirectional, open drain) | 48 | $4025 bit 0 out (open drain): 1 = reset transfer timing |
| 38 to 44 | EXT6 down to EXT0 (bidirectional, open drain) | 47 | $4032 bit 2 in: 1 = write protected |
| 46 | $4032 bit 1 in: 1 = disk not ready | ||
| 45 | $4032 bit 0 in: 1 = disk missing |
Expansion audio mixing: the RP2C33 audio (pin 54) goes through a 1 microfarad capacitor and 2 megohm into a 1.2 megohm feedback inverter stage with a 0.1 microfarad capacitor to ground, then 56 kilohm, and is summed with the 2A03 audio from cartridge pin 45 (56 kilohm, 1 microfarad) before a 100 kilohm feedback inverter stage to cartridge pin 46 (RF). The EXT port is written through $4026 and read through $4033. Setting pin 53 high appears to enable a test mode: the /7 and /12 clock-divided signals are replaced by the master clock signal (M2 or XTAL, not yet determined); audio is muted (possibly related to $4023 bit 1); the timer IRQ decrements the upper 8 bits of its counter (the high byte reloaded from $4021 is decremented on every CPU cycle); and the DRAM refresh watchdog decrements the upper 6 bits of the 12-bit cycle timer (decrementing by 65 instead of 1 each CPU cycle).
Programming the FDS
This is a summary of the wiki’s programming guide, which it calls a work in progress that few developers other than its author have tested. A boot file is a file whose ID in the file header is less than or equal to the boot read file code; boot files load during the first load (main code and graphics, the title screen, the licence message). A non-boot file has a larger ID and loads only through the LoadFiles routine (save data, overlays).
General advice
- The cc65 tools (ca65 and ld65) suit FDS work because they can define the load addresses and sizes for the file headers, and linker segments keep the disk image apart from the file data.
- Bypass the licence screen (below).
$0100-$0103select the interrupt vectors and must always hold valid values. The bypass code sets$0102-$0103and the BIOS reset handler sets$0100-$0101, so a game need not set these on reset. Variables placed in the stack page must be kept clear of them. - The nametable arrangement is bit 3 of
$4025. A fixed arrangement is set once on reset; otherwise use the mirror variable at$FAso other bits are not changed. A program that uses BIOS routines must keep the RAM layout they expect. A cycle-timed NMI handler must allow for the cycles the BIOS NMI handler spends. A custom IRQ handler (chosen with$0101=$C0) must allow for the timer IRQ, the cycles of the BIOS IRQ handler and the DRAM refresh watchdog. Reading$4030to acknowledge IRQs conflicts with DPCM playback, so the two cannot be used together reliably (presumably why Akumajou Dracula uses a sprite-0 hit). - Rare PRG or CHR bank changes can be replaced by disk loads (for example between levels), but mid-frame bank switches cannot be ported. Keep loads and disk swaps few before play starts. After a LoadFiles call, compare the number of files loaded (in the Y register) with the expected number; commercial games use error code 40 for a mismatch. Battery saves can sometimes be replaced by disk saves. If more files or sides were loaded during play, make sure the right ones are reloaded after a reset; a double-sided or multi-disk game may prefer to clear
$0102-$0103to force a full reload from side A of the first disk, with a warning about unsaved data.
RAM used by the BIOS
$00-$0F are temporaries of BIOS routines; $F1-$F8 are used by the BIOS controller routines; $F9-$FF mirror write-only registers; $0100 is the NMI flag, $0101 the IRQ flag, $0102 the reset flag and $0103 the reset type. Some routines also use $0200-$02FF (the OAM DMA buffer), $0300-$03FF (the PPU VRAM buffer) and $0400-$07FF (the pattern table transfer buffer, for LoadTileset calls before the first load).
What a reset handler should do
At power-on and reset the BIOS does its start-up tasks, including the first load, and then jumps to the game’s reset vector at $DFFC. The handler should: clear the I flag (the BIOS does a CLI before it hands over, so omitting instructions that change I also works), because of the watchdog; set up the timer IRQ if wanted (the BIOS sets $4022 to 0 and leaves the reload value in $4020/$4021), and set $0101 = $C0 for a custom IRQ handler; set the APU frame counter $4017 to $40 (4-step, no IRQ) if the sound driver wants it (the BIOS sets $C0, 5-step); set the nametable arrangement in $4025 ($26 horizontal arrangement, that is vertical mirroring; $2E vertical arrangement, horizontal mirroring, which is the BIOS default); set up system RAM without hitting the BIOS variables, restoring $0100-$0103 if they were cleared or changed ($0100 = $C0, $0101 = $80, $0102 = $35, $0103 = $AC or $53); set the PPU registers (and their mirror variables), palettes and nametables (the BIOS sets PPUCTRL $10, PPUMASK $06, scroll 0,0 and does the PPU warm-up loop); and clear unused pattern table areas if wanted, because VRAM keeps whatever the BIOS loaded.
Registers most programs need
$4025 write bit 3 (nametable arrangement, through the mirror at $FA); $4020/$4021 and $4022 (the timer IRQ); $4030 read (acknowledge IRQs: bit 0 = timer, bit 1 = DRAM refresh watchdog); $4032 read bit 0 (0 = a disk is inserted, 1 = ejected); $4040-$408A (audio; the debug registers $4090-$4097 can be ignored).
The DRAM refresh watchdog in practice
The watchdog (reported by $4030 bit 1, and not implemented in emulators that came before its discovery) raises IRQs from the cycles spent accessing DRAM and refreshing rows. Single-instruction endless loops (“everything in the NMI”) and long runs of code in PRG RAM, which do not touch system RAM or registers often enough, starve it of refreshes. If it is ignored (SEI, or turned off), DRAM decays in an analogue way. The safest known method is to keep $4023 = $83 as the BIOS reset handler leaves it, then in the IRQ handler test $4030 bit 1 and call the BIOS routine Delay131. A game with no IRQs can simply CLI during reset (and perhaps at NMI entry) and keep the BIOS default IRQ choice $80 (acknowledge and delay).
Commercial games that do everything in the NMI wait for it with a loop that reads one zero-page byte and jumps back (a read outside PRG RAM is all that is needed). Each read of system RAM advances the 7-bit refresh counter: 6 cycles per loop times 128 loops is 768 cycles, which refreshes all rows and overflows the counter, reloading the 12-bit cycle timer long before it expires. Games that do everything in the main loop wrap the BIOS VINTWait routine with a small subroutine: read $2002 first (to clear the vblank flag and avoid the vblank NMI bug), call VINTWait (running from BIOS ROM refreshes DRAM), then CLI because VINTWait returns with I set. A cleaner design splits the work between a main thread and an NMI thread, whose wait loop already reads system RAM.
A custom IRQ handler for both sources has this order: save A, X and Y; read $4030 (this acknowledges all FDS IRQs); mask bits 1 and 0; shift bit 0 into carry; if bit 1 was set, call Delay131 ($E149) to refresh the DRAM; if the timer was the source, write 0 to $4022 to stop timer IRQs and do the scroll split or other timer work; restore the registers and RTI. It needs $0101 = $C0, all other IRQ sources off and no DPCM playing.
Disk input and output
Use LoadFiles to load more files after the first load. Disk I/O is slow beside mapper banking, especially when changing sides, so lay out files as overlays that load rarely (Super Mario Bros. 2 (J) keeps room for four worlds of level data and loads the overlay for worlds 1 to 4, 5 to 8 or A to D). WriteFile overwrites a given file number (not ID) with data from a CPU or PPU address, and AppendFile adds a new file; both update the file amount block so the written file is the last file of the side. So save data must be the last file of a side, and the only file that can safely be changed with the BIOS routines. A file is one contiguous byte stream, so games with several save slots must reserve memory for all slots joined. Also verify save data and check the error codes the BIOS returns (see the FDS BIOS page, which also has example load and save code). Typical layouts: single-sided: the main game, overlays, save data; double-sided: side A with the title screen and save management, extra overlays and save data, side B with the main game and its overlays.
Bypassing the licence screen
Bypassing it avoids keeping the licence message in source repositories and disk images. A short stub, placed in a boot file and pointed to by the NMI #3 vector at $DFFA, runs before NMIs are enabled by the boot files: it writes 0 to $2000 (NMIs off); stores the real NMI handler’s address in the NMI #3 vector; sets the reset flag $0102 = $35 (“boot files loaded”) and the reset type $0103 = $AC (or $53; the BIOS reset changes it to $53); and jumps through ($FFFC) to the BIOS reset handler. The last boot file must enable NMIs by loading data into PPUCTRL. Then the first load must be stalled until an NMI occurs, in one of two ways: (A) append large non-boot files and raise the file amount block to match, which keeps disk I/O usable after boot and lets copier software transfer the image (the default PowerPak BIOS may seek too quickly for this to work with small files); or (B) raise the file amount by 1 without adding files, which suits programs that load everything at once but breaks further disk I/O. A different bypass hijacks the disk drive IRQ.
Porting cartridge games
NROM’s 16 or 32 KiB of PRG ROM and 8 KiB of CHR ROM fit the FDS’s 32 KiB of PRG RAM and 8 KiB of CHR RAM, which is why so many cartridge games were ported (licensed and unlicensed). To port: assemble the PRG code to the area $6000-$DFFF ($E000-$FFFF is the BIOS) with the interrupt vectors in $DFFA-$DFFF ($DFF6 and $DFF8 can hold alternative NMI vectors) and no variable conflicts; adapt the reset handler and main code as above; then build the disk image from the disk info block, the file amount block, the PRG data as a boot file of type 0 (CPU RAM), the CHR data as a boot file of type 1 (PPU) and the licence bypass. Other boards that can work: iNES mapper 185 (with the chip select check removed) and mapper 218 (avoiding reads and writes of mirrored addresses) loaded once at boot; with rare disk loads, CNROM-like, GNROM-like, UNROM and MMC1 games (SEROM, SHROM and SH1ROM are the most compatible, and SNROM and SKROM were common sources of disk ports: Metroid, Kid Icarus, The Legend of Zelda). A program of 16 KiB or less that stays in $8000-$BFFF fits PRG RAM as it is, with duplicate vectors at $DFFA-$DFFF. Writes aimed at the ROM areas, whether mapper writes, harmless ones (as in Door Door) or bugs, must be handled.
Example programs
The wiki lists these code repositories: for ca65, the NES ca65 example (its FDS branch by bbbradsmith), the FDS BIOS Dumper and the FDS Mirroring Test (both by TakuikaNinja); for asm6f, an asm6f FDS example (TakuikaNinja). They are linked from the wiki page and not summarised further, because the page only lists them. Source: NESdev Wiki, Programming the FDS.
Not covered on this page
The FDS BIOS routines are on their own page, FDS BIOS. Not described here: the .QD format and the FDS audio details beyond expansion audio. The wiki marks several register behaviours as not yet determined; they are listed in the sections above as unknown. The unreleased Family Computer Network Adapter is on the controllers page and the Famicom Network System on its own page. The wiki’s guide gives short assembly examples (the endless wait loop, VINTWait_Safe, the IRQ handler and the licence bypass stub); they are described in words above, not copied.
Sources
The programming section is from NESdev Wiki: Programming the FDS.
The NESdev Wiki text is available under CC BY-SA 3.0. This page is written in our own words from the raw wikitext kept in samples/nes/sources/hardware.