User:Zzo38/DotFami

This is a draft for .fami format of NES/Famicom ROM image files. This format allows title text, debugging information, custom mapper, and a few more.

(N.B. Do not delete or move this file until the draft is completed.)

Difference of this format with others includes:

• You can specify NTSC and PAL.
• Can include descriptive text.
• There is no fixed set of mapper numbers; instead the components of the cartridge are configured individually.
• Debugging symbols can be included.

File Order

• Header
• ROM data
• Mapper codes
• Symbol data
• Descriptive text

(Note: Sixteen bit numbers throughout the file are small-endian form.)

Header

  0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|'F'|'A'|'M'|'I'|cpu| * | banks |textLen|mapLen |symLen | * | * |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

• The first four bytes of the header must be the ASCII codes for "FAMI".
• banks: Number 8K ROM banks.
• cpu: CPU mode flag:
  • bit0: Set if decimal mode should work (not used in NES/Famicom, although some Famiclones may have decimal mode).
  • bit1: Set if the 2A03 APU noise Mode flag should be ignored.
  • bit2: Swap PPUCTRL and PPUMASK (used in some Vs. System games).
  • bit3: Treat tint bits as they do on RGB PPU.
  • bit4: Buggy Famiclone audio.
  • bit5: Can be used with Dendy TV mode.
  • bit6: Can be used with PAL TV mode.
  • bit7: Can be used with NTSC TV mode.
• *: Reserved bytes; set to zero.
• textLen: Length of descriptive text.
• mapLen: Length of mapper codes.
• symLen: Length of symbol data.

Note for TV modes: It can set multiple bits to indicate if it is OK with multiple TV modes. If none of these bits are set, it means to use NTSC timing, but use RGB palettes, no NTSC color artifacts, square pixels, and the entire 256x240 screen to be visible.

Mapper Codes

Each mapper command consists of a length byte, followed by a command code, an ID number, and the parameters which have the length indicated by the length byte (the first byte of parameters is called parameter $00, etc).

($00) Add non-audio component

• ID number: ID of added component (must be unique for each component; non-audio and audio components additionally may not share ID numbers with themselves or each other).
• Parameter $00: Type of component to add.
• Parameter $01...: Parameters of component (depends on type of component).

($01) Add audio component

• ID number: ID of added component (must be unique for each component; non-audio and audio components additionally may not share ID numbers with themselves or each other).
• Parameter $00: Type of component to add.
• Parameter $01: Volume from 0 to 64.
• Parameter $02: Panning from 0 (left) to 64 (right), or 100 for surround. This parameter can be safely ignored by emulators and hardware.
• Parameter $03...: Parameters of component (depends on type of component).

($02) Set CPU/PPU memory mapping

• ID number: ID of component which is being mapped.
• Parameter $00: Read bit mask (set bits are active for this map).
• Parameter $01: Write bit mask (set bits are active for this map).
• Parameter $02..$03: Starting CPU/PPU address.
• Parameter $04..$05: Starting component address.
• Parameter $06..$07: Length of mapping.
• Parameter $08..$09: AND mask for mirrored memory (all bits set if no mirrored memory is used).

When using this code to map the CPU/PPU memory, the addresses are translated as follows:

• $0000..$1FFF = CHR memory (addresses in PPU memory map)
• $2000..$3FFF = Nametables (if nametable mirroring is set up to use these)
• $4000..$4017 = Reserved (DO NOT USE)
• $4018..$FFFF = CPU memory map

($05) Memory mapping between components

This is the same as ($02) but there is no address translation for CPU/PPU, and there is one extra parameter:

• Parameter $0A: ID of component being mapped onto.

Symbol Data

Symbol data consists of zero or more blocks consisting of a 16-bit ID followed by a 16-bit address followed by data. (If the mode is 0, 1, or 2, then the address must be an address within the ROM, mapper component, or CPU memory, and the data is an ASCII text giving its name).

The ID is formed as follows:

• bit0-bit5: Length of data (0 to 63 bytes).
• bit6-bit7: Mode (0=ROM, 1=mapper, 2=CPU memory, 3=extra)
• bit8-bit15: Depend on mode as follows:
  • 0: High bits of address.
  • 1: Component ID.
  • 2: bit8=read, bit9=write, bit10=execute, bit11=16-bit data, bit12-bit15=reserved (set to zero).
  • 3: ID number of what kind of extra it is.

The extras would be:

• $00: Arcade cabinet switch. Bit0-bit2 of address is the switch number, bit8 of address is the default setting (1=on, 0=off). Data is the name of the switch.
• $01: Cartridge component name. Address bit0-bit7 = component ID, bit8-bit15 = sub-part. Data is name of component.
• $02: ASCII/shortkana text. Address indicate what the text means: 0=title, 1=author, 2=copyright, 3=mapper name, 4=license, 5=publisher, 6=version, 7=date, 8=composer of original, 9=composer of cover, 10=Nintendo four-letter code, 11=arcade cabinet model number.
• $03: RGB palette. Address is from 0 to 63 indicating which palette index is used at first, data is the RGB triples (one byte per channel) starting from the specified palette index, ranging from 0 for black to 255 for full intensity. (This is basically like the .pal format but made into 63-byte chunks)
• $04: Track name. Address is track number (0 to 255 only). Data is the name of the track in ASCII/shortkana text. Names can be blank, and if higher track number is given name but lower one is not, the lower numbered tracks still exist and have blank name. If this field is used, the initial value of accumulator is the track number to start at, and the mapper codes can also use the track number (which will not change at runtime unless the mapper code tells it to) to decide which ROM bank to enable and so on.
• $05: CIC region code. Data should be empty or ASCII name of region code. Address should be a number identifying the region code (0=unused or Japan).

Mapper Components

($00) Memory

If there is nothing mapped to this memory for writing, it is ROM; otherwise it is RAM (but which may be auto initialized at reset).

($05) Multiplication

This is like the MMC5 multiplication registers.

Mapper Audio

Note that you can have multiple instances of each and that their parameters can differ as well as how the address lines are connected by using other mapper codes.

($00) Extra 2A03 audio

(see APU)

This need not be indicated if using only the NES/Famicom internal audio; this is if you need an additional 2A03 audio as well as the internal one.

Parameters:

• (none)

($01) Famicom Disk System audio

(see FDS audio)

Parameters:

• (none)

($02) VRC6 audio

(see VRC6 audio)

Parameters:

• (none)

($03) VRC7 audio

(see VRC7 audio)

Parameters:

• Parameter $03: Register write delay (1=on/0=off) (should be on; turn it off if it is necessary to emulate a program that does not properly wait for the register to be ready)
• Parameter $04..$7B: Internal patch set (8 bytes each for 15 instruments) (optional; please set the length to 4 if you are not using this parameter)

($04) MMC5 audio

(see MMC5 audio)

Parameters:

• (none)

($05) Sunsoft audio

(see Sunsoft 5B audio)

Parameters:

• Parameter $03: Clock speed (0=half, 1=full) (should be 0 to emulate Sunsoft 5B audio)

($06) Namco audio

(see Namco 163 audio)

Parameters:

• (none)

ASCII/shortkana Table

#	0	1	2	3	4	5	6	7	8	9	A	B	C	D	E	F
0	***	***	***	***	***	***	***	***	***	***	***	***	***	***	***	***
1	***	***	***	***	***	***	***	***	***	***	***	***	***	***	***	***
2	sp	!	"	#	$	%	&	'	(	)	*	+	,	-	.	/
3	0	1	2	3	4	5	6	7	8	9	:	;	<	=	>	?
4	@	A	B	C	D	E	F	G	H	I	J	K	L	M	N	O
5	P	Q	R	S	T	U	V	W	X	Y	Z	[	\	]	^	_
6	`	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o
7	p	q	r	s	t	u	v	w	x	y	z	{	|	}	~	***
8	Ç	ü	é	â	ä	à	å	ç	ê	ë	è	ï	î	ì	Ä	Å
9	É	æ	Æ	ô	ö	ò	û	ù	ÿ	Ö	Ü	¢	£	¥	«	»
A	ア	カ	ガ	サ	ザ	タ	ダ	ナ	ハ	バ	パ	マ	ヤ	ャ	ラ	ァ
B	イ	キ	ギ	シ	ジ	チ	ヂ	ニ	ヒ	ビ	ピ	ミ	ワ	ン	リ	ィ
C	ウ	ク	グ	ス	ズ	ツ	ヅ	ヌ	フ	ブ	プ	ム	ユ	ュ	ル	ゥ
D	エ	ケ	ゲ	セ	ゼ	テ	デ	ネ	ヘ	ベ	ペ	メ	ッ	ヲ	レ	ェ
E	オ	コ	ゴ	ソ	ゾ	ト	ド	ノ	ホ	ボ	ポ	モ	ヨ	ョ	ロ	ォ
F	á	í	ó	ú	ñ	Ñ	???	???	¿	???	???	???	???	¡	ー	***

• *** indicates permanently reserved codes would should not be used in ASCII/shortkana text.
• ??? indicates codes which are reserved for future use.

There are suggestions to use different encodings (such as UTF-8 or UTF-16, although I don't want UTF-16 or anything else that is incompatible with ASCII), so it might be changed in future.