Documentation/fcs.txt

   1 FCE Ultra Save State Format
   2 (preliminary document - AKA *very incomplete*)
   3 ---------------------------------------
   4
   5 FCE Ultra's save state format is now designed to be as forward and backwards
   6 compatible as possible.  This is achieved through the (over)use of chunks.
   7 All multiple-byte variables are stored LSB(least significant byte)-first.
   8 Data 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
  16 The main file header is 16-bytes in length.  The first three bytes contain
  17 the string "FCS".  The next byte contains the version of FCE Ultra that saved
  18 this save state.  This document only applies to version "53"(.53) and higher.
  19 After the version byte, the size of the entire file in bytes(minus the 16 byte
  20 main file header) is stored.  The rest of the header is currently unused
  21 and should be nulled out.  Graphical example of relevant parts:
  22
  23         FCS <uint8 version> <uint32 totalsize>
  24
  25 -- Section Chunks:
  26
  27 Sections chunk headers are 5-bytes in length.  The first byte defines what
  28 section 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
  33 Section 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
  44 Subsection chunks are stored within section chunks.  They contain the actual
  45 state data.  Each subsection chunk is composed of an 8-byte header and the data.
  46 The header contains a description(a name) and the size of the data contained
  47 in the chunk:
  48                 <uint8 description[4]> <uint32 size>
  49
  50 The name is a four-byte string.  It does not need to be null-terminated.
  51 If the string is less than four bytes in length, the remaining unused bytes
  52 must be null.
  53
  54 -- Subsection Chunk Description Definitions
  55
  56 Note that not all subsection chunk description definitions listed below
  57 are guaranteed to be in the section chunk.  It's just a list of what CAN
  58 be 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