more cleanups
[fceu.git] / Documentation / fcs.txt
CommitLineData
c62d2810 1FCE Ultra Save State Format
2(preliminary document - AKA *very incomplete*)
3---------------------------------------
4
5FCE Ultra's save state format is now designed to be as forward and backwards
6compatible as possible. This is achieved through the (over)use of chunks.
7All multiple-byte variables are stored LSB(least significant byte)-first.
8Data types:
9
10 (u)int8 - (un)signed 8 bit variable(also referred to as "byte")
11 (u)int16 - (un)signed 16 bit variable
12 (u)int32 - (un)signed 32 bit variable
13
14-- Main File Header:
15
16The main file header is 16-bytes in length. The first three bytes contain
17the string "FCS". The next byte contains the version of FCE Ultra that saved
18this save state. This document only applies to version "53"(.53) and higher.
19After the version byte, the size of the entire file in bytes(minus the 16 byte
20main file header) is stored. The rest of the header is currently unused
21and should be nulled out. Graphical example of relevant parts:
22
23 FCS <uint8 version> <uint32 totalsize>
24
25-- Section Chunks:
26
27Sections chunk headers are 5-bytes in length. The first byte defines what
28section it is, the next four bytes define the total size of the section
29(including the section chunk header).
30
31 <uint8 section> <uint32 size>
32
33Section definitions:
34
35 1 - "CPU"
36 2 - "CPUC"
37 3 - "PPU"
38 4 - "CTLR"
39 5 - "SND"
40 16 - "EXTRA"
41
42-- Subsection Chunks
43
44Subsection chunks are stored within section chunks. They contain the actual
45state data. Each subsection chunk is composed of an 8-byte header and the data.
46The header contains a description(a name) and the size of the data contained
47in the chunk:
48 <uint8 description[4]> <uint32 size>
49
50The name is a four-byte string. It does not need to be null-terminated.
51If the string is less than four bytes in length, the remaining unused bytes
52must be null.
53
54-- Subsection Chunk Description Definitions
55
56Note that not all subsection chunk description definitions listed below
57are guaranteed to be in the section chunk. It's just a list of what CAN
58be in a section chunk. This especially applies to the "EXTRA" subsection.
59
60---- Section "CPU"
61
62 Name: Type: Description:
63
64 PC uint16 Program Counter
65 A uint8 Accumulator
66 P uint8 Processor status register
67 X uint8 X register
68 Y uint8 Y register
69 S uint8 Stack pointer
70 RAM uint8[0x800] 2KB work RAM
71
72---- Section "CPUC" (emulator specific)
73
74 Name: Type: Description:
75
76 JAMM uint8 Non-zero value if CPU in a "jammed" state
77 IRQL uint8 Non-zero value if IRQs are to be generated constantly
78 ICoa int32 Temporary cycle counter
79 ICou int32 Cycle counter
80
81---- Section "PPU"
82
83 Name: Type: Description:
84
85 NTAR uint8[0x800] 2 KB of name/attribute table RAM
86 PRAM uint8[32] 32 bytes of palette index RAM
87 SPRA uint8[0x100] 256 bytes of sprite RAM
88 PPU uint8[4] Last values written to $2000 and $2001, the PPU
89 status register, and the last value written to
90 $2003.
91 XOFF uint8 Tile X-offset.
92 VTOG uint8 Toggle used by $2005 and $2006.
93 RADD uint16 PPU Address Register(address written to/read from
94 when $2007 is accessed).
95 TADD uint16 PPU Address Register
96 VBUF uint8 VRAM Read Buffer
97 PGEN uint8 PPU "general" latch. See Ki's document.
98
99---- Section "CTLR" (somewhat emulator specific)
100
101 Name: Type: Description:
102
103 J1RB uint8 Bit to be returned when first joystick is read.
104 J2RB uint8 Bit to be returned when second joystick is read.
105
106---- Section "SND" (somewhat emulator specific)
107
108 <to be written>
109
110---- Section "EXTRA" (varying emulator specificness)
111
112 For iNES-format games(incomplete):
113
114 Name: Type: Description:
115
116 WRAM uint8[0x2000] 8KB of WRAM at $6000-$7fff
117 MEXR uint8[0x8000] (very emulator specific)
118 CHRR uint8[0x2000] 8KB of CHR RAM at $0000-$1fff(in PPU address space).
119 EXNR uint8[0x800] Extra 2KB of name/attribute table RAM.
120 MPBY uint8[32] (very emulator specific)
121 MIRR uint8 Current mirroring:
122 0 = "Horizontal"
123 1 = "Vertical"
124 $10 = Mirror from $2000
125 $11 = Mirror from $2400
126 IRQC uint32 Generic IRQ counter
127 IQL1 uint32 Generic IRQ latch
128 IQL2 uint32 Generic IRQ latch
129 IRQA uint8 Generic IRQ on/off register.
130 PBL uint8[4] List of 4 8KB ROM banks paged in at $8000-$FFFF
131 CBL uint8[8] List of 8 1KB VROM banks page in at $0000-$1FFF(PPU).
132
133 For FDS games(incomplete):
134
135 Name: Type: Description:
136
137 DDT<x> uint8[65500] Disk data for side x(0-3).
138 FDSR uint8[0x8000] 32 KB of work RAM
139 CHRR uint8[0x2000] 8 KB of CHR RAM
140 IRQC uint32 IRQ counter
141 IQL1 uint32 IRQ latch
142 IRQA uint8 IRQ on/off.
143