Go to the first, previous, next, last section, table of contents.


8 Snapshots

Every VICE emulator has a built-in snapshot feature, that saves the complete emulator state into one file for later use. You can therefore save the emulator state - including the state of the game you are playing for example - in a single file.

8.1 Snapshot usage

A snapshot is one file containining the complete emulator state. A snapshot file can be generated by selecting the "Save snapshot" command at any time. This will pop up a requester from which you can specify whether the snapshot should also contain the disk and ROM status.

A snapshot file can be used to restore the emulator state by selecting the load snapshot menu entry at any time. Unfortunately attached ROM images/cartridges are only supported in the VIC20, the PET and the CBM-II emulators at this time.

The memory configuration of the emulator is saved in the snapshot file as well. This configuration is restored when the snapshot is loaded.

8.2 Snapshot format

A snapshot file consists of several modules of mostly different types. Each module has a name and saves the state of an entity like a CIA, the CPU, or the memory.

8.2.1 Emulator modules

This section lists the modules that are contained in each of the emulators snapshot files.

8.2.1.1 x64 modules

The modules in the x64 emulator are:

Name Type Description
MAINCPU 6502 The Main CPU - although it is a 6510, only the 6502 core is saved here
C64MEM Memory Holds the RAM contents of the C64. Also the CPU I/O register contents are saved here.
C64ROM ROM images Dump of the system ROMs
VIC-II 656* The VIC-II of the C64/128
CIA1 6526 The CIA for the interrupts and the keyboard
CIA2 6526 The CIA for the userport, IEC-bus and RS232.
SID 6581 The SID sound chip of the C64/C128
REU* The RAM Extension Unit state (optional)
ACIA1 6551 An ACIA (RS232 interface) at $DE00 (optional)
TPI 6525 A TPI at $DF00 for a parallel IEEE488 interface (optional)
* Drive modules The emulated drive(s) have their own modules see section 8.2.1.6 Drive modules

Some of the modules are optional and are only saved if the specific feature is enabled at save-time. If the module is found when restoring the state the optional features are enabled, and disabled otherwise.

8.2.1.2 x128 modules

The modules in the x128 emulator are:

Name Type Description
MAINCPU 6502 The Main CPU - although it is a 6510, only the 6502 core is saved here
C128MEM Memory Holds the RAM contents of the C64. Also the CPU I/O register contents are saved here.
C128ROM ROM images Dump of the system ROMs
VIC-II 656* The VIC-II of the C64/128
CIA1 6526 The CIA for the interrupts and the keyboard
CIA2 6526 The CIA for the userport, IEC-bus and RS232.
SID 6581 The SID sound chip of the C64/C128
ACIA1 6551 An ACIA at $DE00 (optional)
TPI 6525 A TPI at $DF00 for a parallel IEEE488 interface (optional)
* Drive modules The emulated drive(s) have their own modules see section 8.2.1.6 Drive modules

Some of the modules are optional and are only saved if the specific feature is enabled at save-time. If the module is found when restoring the state the optional features are enabled, and disabled otherwise.

Not yet supported are the 80 column video chip, cartridges and RAM expansion unit.

8.2.1.3 xvic modules

The modules in the xvic emulator are:

Name Type Description
MAINCPU 6502 The Main CPU
VIC20MEM Memory Holds the RAM contents of the VIC20.
VIC20ROM ROM images Holds the ROM images of the VIC20, including possibly attached cartridges
VIC-I 656* The VIC-I of the VIC20
VIA1 6522 The VIA for the interrupts and the keyboard
VIA2 6522 The VIA for the userport, IEC-bus and RS232.
* Drive modules The emulated drive(s) have their own modules see section 8.2.1.6 Drive modules

8.2.1.4 xpet modules

The modules in the xpet emulator are:

Name Type Description
MAINCPU 6502 The Main CPU
PETMEM Memory Holds the RAM contents of the PET.
PETROM ROM images Holds the ROM images of the PET, including possibly attached cartridges
CRTC 6545 The CRTC of the PET. This can even be included if it is a dump of a PET without CRTC.
PIA1 6520 The PIA for the interrupts, tape and the keyboard
PIA2 6520 The PIA for the IEEE488-bus
VIA 6522 The VIA for IEEE488, userport, sound
ACIA1 6551 The ACIA for the SuperPET. This module is optional.
* Drive modules The emulated drive(s) have their own modules see section 8.2.1.6 Drive modules

8.2.1.5 xcbm2 modules

The modules in the xcbm2 emulator are:

Name Type Description
MAINCPU 6502 The Main CPU - although it is a 6509, only the 6502 core is saved here
CBM2MEM Memory Holds the RAM contents of the CBM-II models. Also holds the exec-bank and indirection bank registers
CBM2ROM Memory optional. Holds the ROM images.
CRTC 6545 The video chip for the C6*0 and C7*0 models (only those models).
VIC-II 656? The video chip for the C5*0 models (only the C5*0 models).
CIA1 6526 The CIA for IEEE 488 and userport.
TPI1 6525 TPI 1 for IEEE488
TPI2 6525 TPI 2 for interrupts and keyboard.
ACIA1 6551 The RS232 interface
SID 6581 The CBM2s SID sound chip
* Drive modules The emulated drive(s) have their own modules see section 8.2.1.6 Drive modules

The snapshot either contains CRTC or VIC-II snapshot modules, but not both. Depending on which module is found, a C5*0 or C6*0 is emulated.

8.2.1.6 Drive modules

The modules for the real disk drive emulation are included in the emulator when the emulation is enabled during the writing of the snapshot.

Name Type Description
*CPU 6502 The Drive 0 CPU
* * *

8.2.2 Module formats

This section shows the basic module framework and the contents of the different types of modules.

The single chip modules contain the chip state, not the state of the emulator. We tried to make the format as implementation-independent as possible, to allow reuse of snapshots in later versions of this emulator, or even in other emulators.

8.2.2.1 Terminology

In this section we use certain abbreviations to define the types of the data saved in the snapshot.

BYTE
8 bit integer.

WORD
16 bit integer. Saved with low-byte first, high-byte last.

DWORD
32 bit integer. Saved with low-word first, then high-word. Each word saved with its low-byte first.

ARRAY
Array of BYTE values. Length depends on the description.

The tables for the single modules state the type, name and description of the data saved in the modules. The data is saved in the order it is in the tables, so no offset is given.

8.2.2.2 Module framework

The VICE snapshot file starts with the magic string and includes the fileformat version number.

Type Name Description
19 BYTE MAGIC "VICE Snapshot File\032", padded with 0
BYTE VMAJOR fileformat major version number
BYTE VMINOR fileformat minor version number
16 BYTE MACHINENAME Name of emulated machine, like "PET", "CBM-II", "VIC20", "C64" or "C128". zerobyte-padded.

The file header is followed by a number of different snapshot modules.

Each module has a header with the information given in the table below. The header includes two version numbers, VMAJOR and VMINOR. Modules with the same VMAJOR should be able to be exchanged. I.e. higher VMINOR numbers only append to the data for lower VMINOR. This additional data is ignored by older restore routines. The other way around newer restore routines must accept the fewer info from lower VMINOR dumps. Changes in VMAJOR might introduce any incompatibility you like, but that's what VMAJOR is for after all :-)

Type Name Description
16 BYTE MODULENAME The name of the module in ASCII, padded with 0 to 16 byte.
BYTE VMAJOR major version number
BYTE VMINOR minor version number
DWORD SIZE size of the module, not including this header

8.2.2.3 CPU module

This module saves the core 6502 state. You will find a clock value there. All other modules save their own clock values relative to this value. However, the drive modules save their clocks relative to their appropriate CPUs of course.

Warning: This module is still under construction and saves some information that is not sure to be VICE-independent. If in doubt, read the source.

Type Name Description
DWORD CLK the current CPU clock value. All other clock values are relative to this.
BYTE AC Accumulator
BYTE XR X index register
BYTE YR Y index register
BYTE SP Stack Pointer
WORD PC Programm Counter
BYTE ST Status Registers
DWORD LASTOPCODE ?
DWORD IRQCLK absolute CLK when the IRQ line came active
DOWRD NMICLK absolute CLK when the NMI line came active
DWORD ? ?
DWORD ? ?

8.2.2.4 CIA module

The CIA 6526 is an I/O port chip with 2 8-bit I/O ports, a shift register, two timers, a Time of Day clock and interrupts.

Version numbers: Major 1, Minor 1.

Type Name Description
BYTE ORA Output register A
BYTE ORB Output register B
BYTE DDRA Data direction register A
BYTE DDRB Data direction register B
WORD TAC Timer A counter value
WORD TBC Timer B counter value
BYTE TOD_TEN Time of Day - current tenth of second
BYTE TOD_SEC Time of Day - current seconds
BYTE TOD_MIN Time of Day - current minutes
BYTE TOD_HR Time of Day - current hours
BYTE SDR contents of shift register
BYTE IER mask of enabled interrupt masks
BYTE CRA Control register A
BYTE CRB Control register B
WORD TAL Timer A latch value
WORD TBL Timer B latch value
BYTE IFR mask of currently active interrupts
BYTE PBSTATE Bit 6/7 reflect the PB6/7 toggle bit state. Bit 2/3 reflect the corresponding port bit state.
BYTE SRHBITS number of half-bits to still shift in/out SDR
BYTE ALARM_TEN Time of Day - alarm tenth of second
BYTE ALARM_SEC Time of Day - alarm seconds
BYTE ALARM_MIN Time of Day - alarm minutes
BYTE ALARM_HR Time of Day - alarm hours
BYTE READICR current clock minus the clock when ICR was read last plus 128.
BYTE TODLATCHED Bit 0: 1= latched for reading, Bit 1: 2=stopped for writing
BYTE TODL_TEN Time of Day - latched tenth of second
BYTE TODL_SEC Time of Day - latched seconds
BYTE TODL_MIN Time of Day - latched minutes
BYTE TODL_HR Time of Day - latched hours
DWORD TOD_TICKS clk ticks till next tenth of second
-- -- The next items have been added in V1.1
WORD TASTATE The state bits of the CIA timer A, according to ciatimer.h
WORD TBSTATE The state bits of the CIA timer B, according to ciatimer.h

The last two items have been added in CIA snapshot version 1.1 due to the improved CIA emulation in the newer VICE versions. Some state bits correspond to the CIA state as described in the "A Software Model of the CIA 6526" document by Wolfgang Lorenz, some are delayed versions. For more read the source file ciatimer.h.

8.2.2.5 VIA module

The VIA 6522 is the predecessor of the CIA and also an I/O port chip with 2 8-bit I/O ports, a shift register, two timers and interrupts.

Version numbers: Major 1, Minor 0.

Type Name Description
BYTE ORA Output register A
BYTE DDRA Data direction register A
BYTE ORB Output register B
BYTE DDRB Data direction register B
WORD T1L Timer 1 Latch value
WORD T1C Timer 1 counter value
BYTE T2L Timer 2 latch (8 bit as only lower byte is used)
WORD T2C Timer 2 counter value
BYTE RUNFL bit 7: timer 1 will generate IRQ on underflow; bit 6: timer 2 will generate IRQ on underflow
BYTE SR Shift register value
BYTE ACR Auxiliary control register
BYTE PCR Peripheral control register
BYTE IFR active interrupts
BYTE IER interrupt mask
BYTE PB7 bit 7 = pb7 state
BYTE SRHBITS number of half-bits to shift out on SR
BYTE CABSTATE bit 7: state of CA2 pin, bit 6: state of CB2 pin
BYTE ILA Port A Input Latch (see ACR bit 0)
BYTE ILB Port B Input Latch (see ACR bit 1)

8.2.2.6 PIA module

The PIA 6520 is a chip with two I/O ports (Parallel Interface Adapter) and four additional handshake lines. The chip is pretty the same for Port A and B, only that Port A implements handshake on read operation and port B on write operation.

Version numbers: Major 1, Minor 0.

Type Name Description
UBYTE ORA Output register A
UBYTE DDRA Data Direction Register A
UBYTE CTRLA Control Register A
UBYTE ORB Output register B
UBYTE DDRB Data Direction Register B
UBYTE CTRLB Control Register B
UBYTE CABSTATE Bit 7 = state of CA2, Bit 6 = state of CB2

8.2.2.7 TPI module

The TPI 6525 is a chip with three I/O ports (Tri-Port-Interface). One of the ports can double as an interrupt prioritizer. Therefore we also have to save the states of the interrupt stack etc.

Version numbers: Major 1, Minor 0.

Type Name Description
BYTE PRA Port A output register
BYTE PRB Port B output register
BYTE PRC Port C output register (doubles as IRQ latch register)
BYTE DDRA Port A data direction register
BYTE DDRB Port B data direction register
BYTE DDRC Port C data direction register (doubles as IRQ mask register)
BYTE CR Control Register
BYTE AIR Active interrupt register
BYTE STACK Interrupt stack - the interrupt bits that are not (yet) served.
BYTE CABSTATE State of CA/CB pins. Bit 7 = state of CA, Bit 6 = state of CB

8.2.2.8 SID module

TODO

8.2.2.9 ACIA module

The ACIA 6551 is an RS232 interface chip. VICE emulates RS232 connections via /dev/ttyS* (Unix) or COM: (DOS/WIN - not yet?). When saving a snapshot, those connections are of course lost. The state of the ACIA however is restored if possible. I.e. if a connection is already open when restoring the snapshot, this connection is used instead. If no connection is open, a carrier/DTR drop is emulated.

Version numbers: Major 1, Minor 0.

Type Name Description
BYTE TDR Transmit Data Register
BYTE RDR Receiver Data Register
BYTE SR Status Register
BYTE CMD Command Register
BYTE CTRL Ctrl Register
BYTE INTX 0 = no data to tx; 1 = Data is being transmitted; 2 = Data is being transmitted while data in TDR waiting to be put to internal transmit register
DWORD TICKS Clock ticks till the next TDR empty interrupt

8.2.2.10 VIC-I module

TODO

8.2.2.11 VIC-II module

TODO

8.2.2.12 CRTC module

Warning: This module is still under construction. Especially the RASTERY and RASTERLINE values might be bogus.

Type Name Description
BYTE RASTERY The number of clock cycles from rasterlines start
WORD RASTERLINE The current rasterline
WORD ADDRMASK The address mask valid for the CRTC. All memory accesses are masked with this value
BYTE HWFLAG Bit 0: 1= hardware cursor available. Bit 1: 1= number of columns is doubled by external hardware
20 BYTE REGISTERS register DUMP of the CRTC registers 0-19.
BYTE CRSRSTATE Hardware cursor: Bits 0-3: frame counter till next crsr line toggle. Bit 7: 1= cursor line active

8.2.2.13 C64 memory module

The C64 memory module actually consists of two modules. The "C128MEM" module is mandatory and contains the RAM dump. The "C64ROM" module is optional and contains a dump of the ROM images.

The size of the C64 memory modules differs with each different memory configuration. The RAM configuration is saved in the snapshot, and restored when the snapshot is loaded. The attached cartridges are not yet(!) saved and not yet restored upon load.

Version numbers: Major 0, Minor 0

The C64MEM module

Type Name Description
BYTE CPUDATA CPU port data byte
BYTE CPUDIR CPU port direction byte
BYTE EXROM state of the EXROM line (?)
BYTE GAME state of the GAME line (?)
ARRAY RAM 64k RAM dump

The C64ROM module

Type Name Description
ARRAY KERNAL 8k dump of the kernal ROM
ARRAY BASIC 8k dump of the basic ROM
ARRAY CHARGEN 4k dump of the chargen ROM

8.2.2.14 C128 memory module

The C128 memory module actually consists of two modules. The "C128MEM" module is mandatory and contains the RAM dump. The "C128ROM" module is optional and contains a dump of the ROM images.

The size of the C128 memory modules differs with each different memory configuration. The RAM configuration is saved in the snapshot, and restored when the snapshot is loaded. The attached cartridges are also restored upon load if they have been saved in the snapshot.

Version numbers: Major 0, Minor 0

The C128MEM module

Type Name Description
12 BYTE MMU dump of the 12 MMU registers
ARRAY RAM 128k RAM dump banks 0 and 1

The C128ROM module

Type Name Description
ARRAY KERNAL 8k dump of the kernal ROM
ARRAY BASIC 32k dump of the basic ROM
ARRAY EDITOR 4k dump of the editor ROM
ARRAY 4k CHARGEN dump of the chargen ROM

8.2.2.15 VIC20 memory module

The VIC20 memory module actually consists of two modules. The "VIC20MEM" module is mandatory and contains the RAM dump. The "VIC20ROM" module is optional and contains a dump of the ROM images.

The size of the VIC20 memory modules differs with each different memory configuration. The RAM configuration is saved in the snapshot, and restored when the snapshot is loaded. The attached cartridges are also restored upon load if they have been saved in the snapshot.

Version numbers: Major 1, Minor 0

The VIC20MEM module

Type Name Description
BYTE CONFIG Configuration register. Bits 0,1,2,3,5 reflect if the corresponding memory block is RAM (bit=1) or not (bit=0).
ARRAY RAM0 1k RAM dump $0000-$03ff
ARRAY RAM1 4k RAM dump $1000-$1fff
ARRAY COLORRAM 2k Color RAM, $9400-$9bff
ARRAY BLK0 if CONFIG & 1 then: 3k RAM dump $0400-$0fff
ARRAY BLK1 if CONFIG & 2 then: 8k RAM dump $2000-$3fff
ARRAY BLK2 if CONFIG & 4 then: 8k RAM dump $4000-$5fff
ARRAY BLK3 if CONFIG & 8 then: 8k RAM dump $6000-$7fff
ARRAY BLK5 if CONFIG & 32 then: 8k RAM dump $a000-$bfff

The VIC20ROM module

Type Name Description
BYTE CONFIG Bit 0: 1= ROM block $2*** enabled. Bit 1: 1= ROM block $3*** enabled. Bit 4: 1= ROM block $6*** enabled. Bit 5: 1= ROM block $7*** enabled. Bit 6: 1= ROM block $A*** enabled. Bit 7: 1= ROM block $B*** enabled.
ARRAY KERNAL 8k KERNAL ROM image $e000-$ffff
ARRAY BASIC 16k BASIC ROM image $c000-$dfff
ARRAY CHARGEN 4k CHARGEN ROM image
ARRAY BLK1A 4k ROM image $2*** (if CONFIG & 1)
ARRAY BLK1B 4k ROM image $3*** (if CONFIG & 2)
ARRAY BLK3A 4k ROM image $6*** (if CONFIG & 16)
ARRAY BLK3B 4k ROM image $7*** (if CONFIG & 32)
ARRAY BLK5A 4k ROM image $A*** (if CONFIG & 64)
ARRAY BLK5B 4k ROM image $B*** (if CONFIG & 128)

8.2.2.16 PET memory module

The PET memory module actually consists of two modules. The "PETMEM" module is mandatory and contains the RAM dump. The "PETROM" module is optional and contains a dump of the ROM images.

The size of the PET memory modules differs with each different memory configuration. The RAM configuration is saved in the snapshot, and restored when the snapshot is loaded.

The PETMEM module

Version numbers: Major 1, Minor 1

Type Name Description
BYTE CONFIG Configuration value. Bits 0-3: 0= 40 col PET without CRTC; 1= 40 col PET with CRTC; 2 = 80 col PET (with CRTC); 3= SuperPET; 4= 8096; 5= 8296. Bit 6: 1= RAM at $9***. Bit 7: 1= RAM at $A***.
BYTE KEYBOARD Keyboard type. 0= UK business; 1= Graphics; 2= German business
BYTE MEMSIZE memory size of low 32k in k (possible values 4, 8, 16, 32)
BYTE CONF8X96 Value of the 8x96 configuration register
BYTE SUPERPET SuperPET config. Bit 0: 1= $9*** RAM enabled. Bit 1: 1= RAM write protected. Bit 2: 1= CTRL register write protected. Bit 3: 0= DIAG pin active. Bits 4-7: RAM block in use.
ARRAY RAM 4-32k RAM (not 8296, size depends on MEMSIZE)
ARRAY VRAM 2/4k RAM (not 8296, size depends on CONFIG)
ARRAY EXTRAM 64k expansion RAM (SuperPET and 8096 only)
ARRAY RAM 128k RAM (8296 only)
-- -- The following item has been added in V1.1
BYTE POSITIONAL bit 0=0 = symbolic keyboard mapping, bit 0=1 = positional mapping.

The last item has been added in PETMEM snapshot version 1.1. It is ignored by earlier restore routines (V1.0) and the V1.1 restore routines do not change the current setting when reading a V1.0 snapshot.

The PETROM module

Version numbers: Major 1, Minor 0

Type Name Description
BYTE CONFIG Bit 0: 1= $9*** ROM included. Bit 1: 1= $A*** ROM included. Bit 2: 1= $B*** ROM included. Bit 3: 1= $e900-$efff ROM included
ARRAY KERNAL 4k KERNAL ROM image $f000-$ffff
ARRAY EDITOR 2k EDITOR ROM image $e000-$e7ff
ARRAY CHARGEN 2k CHARGEN ROM image
ARRAY ROM9 4k $9*** ROM image (if CONFIG & 1)
ARRAY ROMA 4k $A*** ROM image (if CONFIG & 2)
ARRAY ROMB 4k $B*** ROM image (if CONFIG & 4)
ARRAY ROMC 4k $C*** ROM image
ARRAY ROMD 4k $D*** ROM image
ARRAY ROME9 7 blocks $e900-$efff ROM image (if CONFIG & 8)

8.2.2.17 CBM-II memory module

The CBM-II memory module actually consists of two modules. The "CBM2MEM" module is mandatory and contains the RAM dump. The "CBM2ROM" module is optional and contains a dump of the ROM images.

The size of the CBM-II memory modules differs with each different memory configuration. The RAM configuration is saved in the snapshot, and restored when the snapshot is loaded.

Version numbers: Major 1, Minor 0

The CBM2MEM module

Type Name Description
UBYTE MEMSIZE Memory size in 128k blocks (1=128k, 2=256k, 4=512k, 8=1024k)
UBYTE CONFIG Bit 0 = $f0800-$f0fff RAM, Bit 1 = $f1000-$f1fff RAM, Bit 2 = $f2000-$f3fff RAM, Bit 3 = $f4000-$f5fff RAM, Bit 4 = $f6000-$f7fff RAM, Bit 5 = $fc000-$fcfff RAM
UBYTE HWCONFIG Bit 0: 0 = CRTC, 1 = VIC-II video chip (Basically the destinction between C500 and C600/700)
UBYTE EXECBANK CPUs execution bank register
UBYTE INDBANK CPUs indirection bank register
ARRAY SYSRAM 2k system RAM $f0000-$f07ff
ARRAY VIDEO 2k video RAM $fd000-$fd7ff
ARRAY RAM RAM dump, size according to MEMSIZE
ARRAY RAM08 if memsize < 1M and CONFIG & 1 : 2k RAM $f0800-$f0fff
ARRAY RAM1 if memsize < 1M and CONFIG & 2 : 4k RAM $f1000-$f1fff
ARRAY RAM2 if memsize < 1M and CONFIG & 4 : 8k RAM $f2000-$f3fff
ARRAY RAM4 if memsize < 1M and CONFIG & 8 : 8k RAM $f4000-$f5fff
ARRAY RAM6 if memsize < 1M and CONFIG & 16 : 8k RAM $f6000-$f7fff
ARRAY RAMC if memsize < 1M and CONFIG & 32 : 4k RAM $fc000-$fcfff

The RAM* arrays are only saved if the RAM itself is less than 1M. If the memory size is 1M then those areas are taken from the bank 15 area of the normal RAM.

The CBM2ROM module

Type Name Description
UBYTE CONFIG Bit 1: 1= $1*** ROM image included. Bit 2: 1= $2000-$3fff ROM image included. Bit 3: 1= $4000-$5fff ROM image included. Bit 4: 1= $6000-$7fff ROM image included.
ARRAY KERNAL 8 KERNAL ROM image ($e000-$efff)
ARRAY BASIC BASIC ROM image ($8000-$bfff)
ARRAY CHARGEN 4k CHARGEN ROM image
ARRAY ROM1 4k cartridge ROM image for $1*** (if CONFIG & 2)
ARRAY ROM2 8k cartridge ROM image for $2000-$3fff (if CONFIG & 4)
ARRAY ROM4 8k cartridge ROM image for $4000-$5fff (if CONFIG & 8)
ARRAY ROM6 8k cartridge ROM image for $6000-$7fff (if CONFIG & 16)


Go to the first, previous, next, last section, table of contents.