FDS BIOS

The Famicom Disk System contains a fixed 8KB BIOS at $E000-FFFF. This controls the Famicom at power-on and reset, dispatches the NMI and IRQ, and offers an API for accessing the data on disk.

Pseudo-registers

The FDS BIOS uses several bytes on the zero-page. They are used to overcome the problem that NES/FDS registers are write only, so it is effectively possible to modify only one bit of them without affecting other bits.

[$FF]:  value last written to $2000   $80 on reset.
[$FE]:  value last written to $2001   $06 on reset
[$FD]:  value last written to $2005/1 $00 on reset.
[$FC]:  value last written to $2005/2 $00 on reset.
[$FB]:  value last written to $4016   $00 on reset.
[$FA]:  value last written to $4025   $2E on reset.
[$F9]:  value last written to $4026   $FF on reset.
$F5..$F8 : Used by controller read routines
$00..$0F is used as temporary memory for the BIOS. The main program can use it as temporary memory too.

The FDS BIOS also uses 4 bytes at the lower end of the stack page to control behaviour of interrupt/reset vectors:

[$0102]/[$0103]: PC action on reset
[$0101]:         PC action on IRQ. set to $80 on reset
[$0100]:         PC action on NMI. set to $C0 on reset

RESET:
($DFFC):         disk game reset vector     (if [$0102] = $35, and [$0103] = $53 or $AC)

IRQ:
($DFFE):         disk game IRQ vector       (if [$0101] = %11xxxxxx)
 $E1EF :         BIOS acknowledge and delay (if [$0101] = %10xxxxxx)
 $E1CE :         BIOS disk transfer         (if [$0101] = %01xxxxxx)
 $E1D9 :         BIOS disk skip bytes       (if [$0101] = %00xxxxxx)

NMI:
($DFF6):         disk game NMI vector #1    (if [$0100] = %01xxxxxx)
($DFF8):         disk game NMI vector #2    (if [$0100] = %10xxxxxx)
($DFFA):         disk game NMI vector #3    (if [$0100] = %11xxxxxx)
 $E19D :         BIOS disable NMI           (if [$0100] = %00xxxxxx)

A few important notes :

• After loading the boot files, $0102 is set to $35 so that the ($DFFC) vector is used and the BIOS is skipped.
• $0103 indicate reset type : $AC = first boot of the game, $53 = the game was soft-reset by the user
• To use a custom IRQ routine, $C0 should be manually written to $0101
• There are 3 possible NMI vectors, #3 is used by default.
• On first start, the mirroring is set to horizontal, the stack pointer is $FF, and the I flag is clear. System RAM is filled with values used by the BIOS, and PRG RAM is uninitialized, except for parts of it which have files loaded in.

BIOS calls

Disk access routines

• Routines takes one or two pointers as arguments. Those are placed directly after the JSR instruction: the subroutines uses the return address in stack to fetch the pointers and fix the return address.
• Memory at $00-$0F will be affected by those routines
• Unlike the vast majority of disk drives, the FDS lacks any kind of intelligent tracking system. All BIOS load and save functions will do access to the whole disk, no matter which data they load/save. A simple way to overcome this problem is to have a custom loading routine, similar to the BIOS one but forcing the # of files to a smaller number than it actually is. That way the later files are not accessed at all and the earlier files load faster. Of course the maximal time is still taken when loading files that are late on the disk.
• All non-disk IRQ sources (timer, DMC and APU frame) should be properly disabled before calling any of these routines. The value at [$0101] however, is preserved on entry, and restored on exit.
• On return of those routines, A = $00 means no error occurred, other number is error #. Main program should test if an error occurred with the BEQ or BNE instruction, BEQ will branch if no error, and BNE will branch if there is an error.
• The structures defined below are used to identify files & disks in the access routines. The argument pointers should point to these structures in the program.

Address	Name	Input parameters	Output parameters	Description
$E1F8	LoadFiles	Pointer to Disk ID, Pointer to File List	A = error #, Y = # of files loaded	Loads files specified by DiskID into memory from disk. Load addresses are decided by the file's header.
$E237	AppendFile	Pointer to Disk ID, Pointer to File Header	A = error #	Appends the file data given by DiskID to the disk. This means that the file is tacked onto the end of the disk, and the disk file count is incremented. The file is then read back to verify the write. If an error occurs during verification, the disk's file count is decremented (logically hiding the written file).
$E239	WriteFile	Pointer to Disk ID, Pointer to File Header, A = file #	A = error #	Same as "Append File", but instead of writing the file to the end of the disk, A specifies the sequential position on the disk to write the file (0 is the first). This also has the effect of setting the disk's file count to the A value, therefore logically hiding any other files that may reside after the written one.
$E2B7	CheckFileCount	Pointer to Disk ID, A = # to set file count to	A = error #	Reads in disk's file count, compares it to A, then sets the disk's file count to A.
$E2BB	AdjustFileCount	Pointer to Disk ID, A = number to reduce current file count by	A = error #	Reads in disk's file count, decrements it by A, then writes the new value back.
$E301	SetFileCount1	Pointer to Disk ID, A = file count minus one = # of the last file	A = error #	Set the file count to A + 1
$E305	SetFileCount	Pointer to Disk ID, A = file count	A = error #	Set the file count to A
$E32A	GetDiskInfo	Pointer to Disk Info	A = error #	Fills DiskInfo up with data read off the current disk.

Low-Level Disk access routines

Address	Name	Input parameters	Output parameters	Description
$E445	CheckDiskHeader	Pointer to 10 byte string at $00		Compares the first 10 bytes on the disk coming after the FDS string, to 10 bytes pointed to by Ptr($00). To bypass the checking of any byte, a -1 can be placed in the equivelant place in the compare string. Otherwise, if the comparison fails, an appropriate error will be generated.
$E484	GetNumFiles			Reads # of files stored on disk, stores the result in $06
$E492	SetNumFiles		A = # of files	Writes new number of files to disk header.
$E4A0	FileMatchTest	Pointer to FileID list at $02		Uses a byte string pointed at by Ptr($02) to tell the disk system which files to load. The file ID's number is searched for in the string. If an exact match is found, [$09] is 0'd, and [$0E] is incremented. If no matches are found after 20 bytes, or a -1 entry is encountered, [$09] is set to -1. If the first byte in the string is -1, the BootID number is used for matching files (any FileID that is not greater than the BootID qualifies as a match).
$E4DA	SkipFiles	Number of files to skip in $06		Skips over specified number of files.

Example code how to load files

Load
   jsr LoadFiles
   .dw DiskID
   .dw LoadList
   bne _Error        ;Check if there is an error
   rts
_Error
   jsr PrintError      ;If so print the error number and message to screen (include side/disk changing prompts)
_sideError
   lda $4032
   and #$01
   beq _sideError     ;Wait until disk is ejected
_insert
   lda $4032
   and #$01
   bne _instert      ;Wait until disk is inserted
   jmp Load

DiskID
   .db $01        ;Manufacturer code
   .db "NAME"     ;4-letter code of game
   .db $00        ;Version
   .db $01        ;Disk side
   .db $00        ;Disk number
   .db $00, $00   ;Extra disk IDs

LoadList          ;In this example the files with IDs equal to $02, $03 or $04 will be loaded into memory
   .db $02, $03, $04, $ff

Error list

Message in bold is the official BIOS message (if there is one) followed by an explanation

• $00: no error
• $01: disk set, ($4032.0) disk not set
• $02: battery, ($4033.7) power supply failure
• $03: ($4032.2) disk is write protected
• $04: Wrong maker ID
• $05: Wrong game
• $06: Wrong game version
• $07: a,b side, wrong side number
• $08: disk no., wrong disk number
• $09: wrong additional disk ID 1
• $0a: wrong additional disk ID 2
• $20: disk trouble, approval check failed
• $21: disk trouble, '*NINTENDO-HVC*' string in block 1 doesn't match
• $22: disk trouble, block type 1 expected
• $23: disk trouble, block type 2 expected
• $24: disk trouble, block type 3 expected
• $25: disk trouble, block type 4 expected
• $27: disk trouble, ($4030.4) block failed CRC
• $28: disk trouble, ($4030.6) file ends prematurely during read
• $29: disk trouble, ($4030.6) file ends prematurely during write
• $30: disk trouble, ($4032.1) disk is full

Disk ID structure

This is a commonly used string. It consists of 10 bytes which are all compared directly against bytes 15..24 (right after the '*NINTENDO-HVC*' string) of the disk's header block (block type 1; always the first one on the disk). If any of the bytes fail the comparison, an appropriate error # is generated. Comparisons of immaterial data can be skipped by placing an $FF byte in the appropriate place in the DiskID string (for example, when the ROM BIOS boots a disk, it sets all the fields in the DiskID string to -1, except disk side #, and disk #, which are set to 0 (so these fields have to match 0)). The following chart describes the DiskID structure, and the error #'s returned when a comparison fails.

offset	size	error#	description
------	----	------	-----------
0	1	$04	game manufacturer code
1	4	$05	game ASCII name string
5	1	$06	game version
6	1	$07	disk side #
7	1	$08	disk #
8	1	$09	extra disk # data
9	1	$10	extra disk # data
A			-

File list structure

This is a list of 1-byte IDs of files to load. All files that matches any ID in the list are loaded. A list of up to 20 IDs is possible at a time, smaller lists should be terminated by a $ff byte (this implies a file ID can never be $ff).

Multiple files are loaded in the order as they exist on the disk, not in the order of the list.

File header structure

This structure is specified when a file is to be written to the disk. The first 14 bytes of this structure directly specify the data to use for generating a file header block (type 3, bytes [2..15]) to write to disk. The last 2 entries concern the file data to be written to disk (block type 4). The following is a table describing the FileHeader structure.

offset	size	description
------	----	-----------
00	1	file ID code
01	8	file name
09	2	load address
0B	2	file data size
0D	1	file type ($00 : Program; $01 : Character; $02 : Nametable)
0E	2	source address of file data (NOT written to disk)
10	1	source address type ($00 : RAM, $01 : VRAM)
11		-

Disk information structure

This is a data structure returned by a subroutine, of collected information from the disk (list of files on disk, disk size, etc.). The following table is a description of that structure.

offset	size
------  ----
0	1	game manufacturer code
1	4	game ASCII name string
5	1	game version
6	1	disk side #
7	1	disk #
8	1	extra disk # data
9	1	extra disk # data
A	1	# of files on disk

(the following block will appear for as many files as the "# of files on disk" byte indicates)

B	1	file ID code
C	8	file name (ASCII)

(the following is present after the last file info block. Disk size is equal to the sum of each file's size entry, plus an extra 261 per file.)

x	1	disk size high byte
x+1	1	disk size low  byte
x+2		-

Other BIOS calls

Address	Name	Input parameters	Output parameters	Affected RAM/Registers	Description
$e149	Delay132				132 clock cycle delay
$e153	Delayms			X, Y	Delay routine, Y = delay in ms (approximate)
$e161	DisPFObj			A, $fe	Disable sprites and background
$e16b	EnPFObj			A, $fe	Enable sprites and background
$e171	DisObj			A, $fe	Disable sprites
$e178	EnObj			A, $fe	Enable sprites
$e17e	DisPF			A, $fe	Disable background
$e185	EnPF			A, $fe	Enable background
$e1b2	VINTWait			$ff	Wait until next VBlank NMI fires, and return (for programs that does it the "everything in main" way). NMI vector selection at $100 is preserved, but further VBlanks are disabled.
$e7bb	VRAMStructWrite	Pointer to VRAM buffer to be written		A, X, Y, $00, $01, $ff	Set VRAM increment to 1 (clear PPUCTRL/$ff bit 2), and write a VRAM buffer to VRAM. Read below for information on the structure.
$e844	FetchDirectPtr		$00, $01 = pointer fetched	A, X, Y, $05, $06	Fetch a direct pointer from the stack (the pointer should be placed after the return address of the routine that calls this one (see "important notes" above)), save the pointer at ($00) and fix the return address.
$e86a	WriteVRAMBuffer			A, X, Y, $301, $302	Write the VRAM Buffer at $302 to VRAM. Read below for information on the structure.
$e8b3	ReadVRAMBuffer	X = start address of read buffer, Y = # of bytes to read		A, X, Y	Read individual bytes from VRAM to the VRAMBuffer. (see notes below)
$e8d2	PrepareVRAMString	A = High VRAM address, X = Low VRAM address, Y = string length, Direct Pointer = data to be written to VRAM	A = $ff : no error, A = $01 : string didn't fit in buffer	A, X, Y, $00, $01, $02, $03, $04, $05, $06	This routine copies pointed data into the VRAM buffer.
$e8e1	PrepareVRAMStrings	A = High VRAM address, X = Low VRAM address, Direct pointer = data to be written to VRAM	A = $ff : no error, A = $01 : data didn't fit in buffer	A, X, Y, $00, $01, $02, $03, $04, $05, $06	This routine copies a 2D string into the VRAM buffer. The first byte of the data determines the width and height of the following string (in tiles): Upper nybble = height, lower nybble = width.
$e94f	GetVRAMBufferByte	X = starting index of read buffer, Y = # of address to compare (starting at 1), $00, $01 = address to read from	carry clear : a previously read byte was returned, carry set : no byte was read, should wait next call to ReadVRAMBuffer	A, X, Y	This routine was likely planned to be used in order to avoid useless latency on a VRAM reads (see notes below). It compares the VRAM address in ($00) with the Yth (starting at 1) address of the read buffer. If both addresses match, the corresponding data byte is returned exit with c clear. If the addresses are different, the buffer address is overwritten by the address in ($00) and the routine exit with c set.
$e97d	Pixel2NamConv	$02 = Pixel X cord, $03 = Pixel Y cord	$00 = High nametable address, $01 = Low nametable address	A	This routine convert pixel screen coordinates to corresponding nametable address (assumes no scrolling, and points to first nametable at $2000-$23ff).
$e997	Nam2PixelConv	$00 = High nametable address, $01 = low nametable address	$02 = Pixel X cord, $03 = Pixel Y cord	A	This routine convert a nametable address to corresponding pixel coordinates (assume no scrolling).
$e9b1	Random	X = Zero Page address where the random bytes are placed, Y = # of shift register bytes (normally $02)		A, X, Y, $00	This is a shift-register based random number generator, normally takes 2 bytes (using more won't affect random sequence). On reset the program is supposed to write some non-zero values here (BIOS uses writes $d0, $d0), and call this routine several times before the data is actually random. Each call of this routine will shift the bytes right.
$e9c8	SpriteDMA			A	This routine does sprite DMA from RAM $200-$2ff
$e9d3	CounterLogic	A, Y = end Zeropage address of counters, X = start zeropage address of counters		A, X, $00	This decrements several counters in Zeropage. The first counter is a decimal counter 9 -> 8 -> 7 -> ... -> 1 -> 0 -> 9 -> ... Counters 1...A are simply decremented and stays at 0. Counters A+1...Y are decremented when the first counter does a 0 -> 9 transition, and stays at 0.
$e9eb	ReadPads		$f5 = Joypad #1 data, $f6 = Joypad #2 data	A, X, $00, $01,	This read hardwired famicom joypads.
$ea1a	ReadDownPads		$f5 = Joypad #1 up->down transitions, $f6 = Joypad #2 up->down transitions $f7 = Joypad #1 data, $f8 = Joypad #2 data	A, X, $00, $01	This reads hardwired famicom joypads, and detect up->down button transitions
$ea1f	ReadOrDownPads		$f5 = Joypad #1 up->down transitions, $f6 = Joypad #2 up->down transitions $f7 = Joypad #1 data, $f8 = Joypad #2 data	A, X, $00, $01	This read both hardwired famicom and expansion port joypads and detect up->down button transitions.
$ea36	ReadDownVerifyPads		$f5 = Joypad #1 up->down transitions, $f6 = Joypad #2 up->down transitions $f7 = Joypad #1 data, $f8 = Joypad #2 data	A, X, $00, $01	This reads hardwired Famicom joypads, and detect up->down button transitions. Data is read until two consecutive read matches to work around the DMC reading glitches.
$ea4c	ReadOrDownVerifyPads		$f5 = Joypad #1 up->down transitions, $f6 = Joypad #2 up->down transitions $f7 = Joypad #1 data, $f8 = Joypad #2 data	A, X, $00, $01	This read both hardwired famicom and expansion port joypads and detect up->down button transitions. Data is read until two consecutive read matches to work around the DMC reading glitches.
$ea68	ReadDownExpPads	$f1-$f4 = up->down transitions, $f5-$f8 = Joypad data in the order : Pad1, Pad2, Expansion1, Expansion2		A, X, $00, $01	This read both hardwired famicom and expansion port joypad, but stores their data separately instead of ORing them together like the other routines does. This routine is NOT DMC fortified.
$ea84	VRAMFill	A = High VRAM Address (aka tile row #), X = Fill value, Y = # of tile rows OR attribute fill data		A, X, Y, $00, $01, $02	This routine does 2 things : If A < $20, it fills pattern table data with the value in X for 16 * Y tiles. If A >= $20, it fills the corresponding nametable with the value in X and attribute table with the value in Y.
$ead2	MemFill	A = fill value, X = first page #, Y = last page #		A, X, Y, $00, $01	This routines fills RAM pages with specified value.
$eaea	SetScroll			A	This routine set scroll registers according to values in $fc, $fd and $ff. Should typically be called in VBlank after VRAM updates
$eafd	JumpEngine	A = Jump table entry		A, X, Y, $00, $01	The instruction calling this is supposed to be followed by a jump table (16-bit pointers little endian, up to 128 pointers). A is the entry # to jump to, return address on stack is used to get jump table entries.
$eb13	ReadKeyboard				Read Family Basic Keyboard expansion (detail is under analysis)
$eb66	LoadTileset	A = Low VRAM Address & Flags, Y = Hi VRAM Address, X = # of tiles to transfer to/from VRAM		A, X, Y, $00, $01, $02, $03, $04	This routine can read and write 2BP and 1BP tilesets to/from VRAM. See appendix below about the flags.
$ec22	unk_EC22				Some kind of logic that some games use. (detail is under analysis)

VRAM write transfer structure

The structure of VRAM buffers are as follows:

SIZE   CONTENTS
2      VRAM Address (big endian)
1      bit 0-5 length of data ($0 means a length of 64)
       bit 6 : 0 = copy, 1 = fill
       bit 7 : 0 = increment by 1, 1 = increment by 32
n      Data to copy to VRAM
.....  repeated as many times as needed
1      $ff

• The main structure is terminated by a $ff byte (High address is always supposed to be in $00..$3f range)
• $4c is a "call" command. The 2 bytes that follow is the address of a sub-VRAM structure. The sub-structure can call another sub-structure and so on.
• $60 is a "return" command. It will terminate a sub-structure.
• If Fill mode is used, the routine takes only 1 byte of data which is repeated.

VRAM Buffer notes

The VRAM buffer is located at $300-$3xx. $300 holds the size of the buffer (maximum), and $301 holds the end index of the buffer. The actual buffer lies at $302-$3xx, and is of variable length.

• $300 is initialized to the value $7d, effectively making the buffer lie at $300-$37f. It's possible to change the value here to make it bigger or smaller, but the biggest possible value is $fd, making the buffer lie at $300-$3ff.
• Format of the buffer is equivalent to the VRAM structure above, except that there are no sub-structures, no increment by 32 flag and no fill flag.
• For this reason, the VRAM buffer at $302 can be used as a sub-structure.
• A call to WriteVRAMBuffer will execute faster than a call to VRAMStructWrite with $302 as an argument, but both will have the same effect.

Read routines and VRAM buffer

Unlike the write routines which are very complete, the read routines are somewhat incomplete and their functionality have to be completed by the user (which limits their usefulness). Most of what follows is some sort of speculation about the usefulness of the incomplete read routines of the BIOS.

The read buffer is a part of the VRAM buffer at $300-$3xx, but the same location can't be used to transfer read and writes on the same frame (for example a RMW operation). Instead the user must manually split the buffer in two parts, the "read" buffer and the "write" buffer. The read buffer is probably supposed to always lies after the write buffer, so that when the read buffer is in use, the value in $300 (size of the write buffer) should be adjusted accordingly. The user should manually keep track of how many bytes are used for the read buffer, as well as the starting point of the read buffer (they are argument to the ReadVRAMBuffer function).

The structure of the read buffer itself is trivial - only single bytes are read (there's no runs of data). Very likely the purpose is to read one or a few individual attribute table data, in order to change the color mapping of individual 2x2 squares instead of whole 4x4 square (read-modify-write operation). All reads are mapped to a structure of 3 bytes in the read buffer :

SIZE   CONTENTS
2      VRAM Address (big endian)
1      data

Therfore, for each byte which is read from VRAM, 3 bytes have to be reserved in the read buffer. Once data from VRAM has been read, if it must be written back after a modification, the user need to copy it to the write buffer manually.

The GetVRAMBufferByte was probably designed to prevent reading attribute tables when it has already been read in the past by a call to ReadVRAMBuffer. For example if you don't know if you're modifying another area of the same 4x4 attribute byte as previously (no need to read again), or if you're modifying part of another 4x4 attribute byte (need to read from VRAM). If the routine return with C=0, the accumulator contains the attribute byte that was already read, but if C=1, it means we should first call ReadVRAMBuffer before getting the data we want.

Since reading VRAM for nothing is not a harmful operation, the user can call ReadVRAMBuffer every frame even if nobody has to be read (no need for check flags) which is probably why these routines are less complete than the write buffer related routines.

Load Tileset notes

The flags parameters are as follows:

7  bit  0
---------
AAAA MMIT
|||| ||||
|||| |||+- Fill bit
|||| ||+-- Transfer direction (0 = Write tiles, 1 = Read tiles)
|||| ++--- Bitplane type (see below)
++++------ Low VRAM Address (aka tile # within a row)

        1st bitplane	2nd bitplane     Description
        -----------	-----------      -----------
    0:  data           data+8           Normal 2-bitplane graphics
    1:  data           fill bit         Single bitplane graphics. Fill bit clear : Use colors 0&1  Fill bit set : Use colors 2&3
    2:  fill bit       data             Single bitplane graphics. Fill bit clear : Use colors 0&2  Fill bit set : Use colors 1&3
    3:  data^fill bit  data             Single bitplane graphics. Fill bit clear : Use colors 0&3  Fill bit set : Use colors 1&2

This makes it possible for single bitplane tiles to take all possible color schemes when they end up in VRAM. However, it is not possible to (natively) load single bitplane graphics directly from the disk into VRAM; it should be loaded into PRG-RAM before transferring the data into VRAM. In read mode, all non "data" bitplanes are replaced by dummy reads.