This is vice.info, produced by makeinfo version 4.5 from vice.texi.

START-INFO-DIR-ENTRY
* VICE: (vice).        VICE, the Versatile Commodore Emulator.
END-INFO-DIR-ENTRY

   VICE Manual

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.


File: vice.info,  Node: CBM-II model,  Next: CBM-II commandline options,  Prev: CBM-II-specific,  Up: CBM-II-specific

Changing CBM-II model
---------------------

   With `xcbm2', it is possible to change at runtime the
characteristics of the emulated CBM so that it matches (or not) the ones
of a certain CBM model, and it is also possible to select from a common
set of CBM models so that all the features are selected accordingly.

   The former is done by changing the following resources (via resource
file, command line options or right-menu items):

`UseVicII'
     Whether to use VIC-II for video output (value 1) or the CRTC for
     the other machines (value 0)

`RamSize'
     Size of memory in kByte.  Possible values are 128, 256, 512 and
     1024

`Ram08, Ram1, Ram2, Ram4, Ram6, RamC'
     Expanded CBM-II models could map RAM to the expansion ROM areas at
     $0800-$0fff, $1000-$1fff, $2000-$3FFF, $4000-$5FFF, $6000-$7FFF
     and $c000-$cfff respectively.

`Cart2Name, Cart4Name, Cart6Name'
     Specify `NAME' as the $2000-$3FFF, $4000-$5FFF or $6000-$6FFF
     Expansion ROM file.  This file contains an 8k ROM dump.

`ModelLine'
     The CBM-II business models have two hardcoded lines at one of the
     I/O ports.  From those lines the kernal determines how it should
     init the CRTC video chip for either 50Hz (Europe) or 60Hz (North
     America), and either for 8 (C6x0) or 14 (C7x0) scanlines per
     character.  0 = CBM 7x0 (50Hz), 1 = 60Hz C6x0, 2 = 50Hz C6x0).


   Choosing a common CBM-II model is done from the right-button menu
instead, by choosing an item from the "Model defaults" submenu.
Available models are:

   * C510 (128k RAM)

   * C610 (128k RAM)

   * C620 (256k RAM)

   * C620+ (1024k RAM, expanded)

   * C710 (128k RAM)

   * C720 (256k RAM)

   * C720+ (1024k RAM, expanded)

   Notice that this will *reset the emulated machine*.

   Warning: At this time switching between 510 and other machines during
runtime is not supported and will not work.

   It is also possible to select the CBM model at startup, with the
`-model' command-line option: for example, `xcbm2 -model 610' will
emulate a CBM 610 while `xcbm2 -model 620' will emulate a CBM 620.
Notably this is the only way to start a C510 emulation, with `-model
510'.


File: vice.info,  Node: CBM-II commandline options,  Next: CBM-II colors,  Prev: CBM-II model,  Up: CBM-II-specific

CBM-II command line options
---------------------------

   These are the commandline options specific for the CBM-II models.

`-usevicii'
`+usevicii'
     Specify whether to use (-usevicii) or not to use (+usevicii) the
     VIC-II emulation.

`-kernal NAME'
     Specify `NAME' as the Kernal ROM file (`KernalName').

`-basic NAME'
     Specify `NAME' as the Basic ROM file (`BasicName').

`-chargen NAME'
     Specify `NAME' as the character generator ROM file (`ChargenName').

`-cart2 NAME, -cart4 NAME, -cart6 NAME'
     Specify `NAME' as the ROM image file for the respective cartridge
     areas (`Cart2Name', `Cart4Name', `Cart6Name').

`-ram08, -ram1, -ram2, -ram4, -ram6, -ramC'
     Switch on RAM mapping in bank 15 on addresses $0800-$0fff,
     $1000-$1fff, $2000-$3fff, $4000-$5fff, $6000-$7fff resp (`Ram08',
     `Ram1', `Ram2', `Ram4', `Ram6', `RamC').

`-modelline'
     Define the hardcoded model switch in the CBM-II models.



File: vice.info,  Node: CBM-II colors,  Prev: CBM-II commandline options,  Up: CBM-II-specific

Changing screen colors
----------------------

   It is also possible to choose what color set is used for the
emulation window.  This is done by specifying a palette file name
(*note Palette files::) in the `PaletteName' resource.  The menu
provides the following values:

   * `green.vpl' (default, "green"), the good old green-on-black
     feeling;

   * `amber.vpl' ("amber"), an amber phosphor lookalike;

   * `white.vpl' ("white"), simple white-on-black palette.


File: vice.info,  Node: Snapshots,  Next: Monitor,  Prev: Machine-specific features,  Up: Top

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.

* Menu:

* Snapshot usage::
* Snapshot format::


File: vice.info,  Node: Snapshot usage,  Next: Snapshot format,  Prev: Snapshots,  Up: Snapshots

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.

   A quick snapshot can now be made by pressing the `M-F11' key and
reloaded by pressing the `M-F10' key.


File: vice.info,  Node: Snapshot format,  Prev: Snapshot usage,  Up: Snapshots

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.

* Menu:

* Emulator modules::
* Module formats::


File: vice.info,  Node: Emulator modules,  Next: Module formats,  Prev: Snapshot format,  Up: Snapshot format

Emulator modules
----------------

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

* Menu:

* x64 modules::
* x128 modules::
* xvic modules::
* xpet modules::
* xcbm2 modules::
* Drive modules::


File: vice.info,  Node: x64 modules,  Next: x128 modules,  Prev: Emulator modules,  Up: Emulator modules

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 *note 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.


File: vice.info,  Node: x128 modules,  Next: xvic modules,  Prev: x64 modules,  Up: Emulator modules

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 *note 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.


File: vice.info,  Node: xvic modules,  Next: xpet modules,  Prev: x128 modules,  Up: Emulator modules

xvic modules
............

   The modules in the xvic emulator are:

Name    Type                          Description
MAINCPU 6502                          The Main CPU
VIC20MEMMemory                        Holds the RAM contents of the VIC20.
VIC20ROMROM 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 *note Drive modules::


File: vice.info,  Node: xpet modules,  Next: xcbm2 modules,  Prev: xvic modules,  Up: Emulator modules

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 is also
                                      included if it is a dump of a PET
                                      without CRTC, because the video
                                      state is saved here anyway.
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 *note Drive modules::


File: vice.info,  Node: xcbm2 modules,  Next: Drive modules,  Prev: xpet modules,  Up: Emulator modules

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
C500DATA                              Holds additional state information
                                      necessary for the C500 (e.g. cycles
                                      till the next IRQ)
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 *note Drive modules::

   The snapshot either contains CRTC or VIC-II snapshot modules, but
not both. Currently switching between the two video emulations is not
possible at runtime, so only snapshots that fit the current UseVicII
resource are accepted.


File: vice.info,  Node: Drive modules,  Prev: xcbm2 modules,  Up: Emulator modules

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
*       *                             *


File: vice.info,  Node: Module formats,  Prev: Emulator modules,  Up: Snapshot format

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.

* Menu:

* Module Terminology::
* Module framework::
* CPU 6502 module::
* CIA 6526 module::
* VIA 6522 module::
* PIA 6520 module::
* TPI 6525 module::
* RIOT 6532 module::
* SID 6581 module::
* ACIA 6551 module::
* VIC-I module::
* VIC-II module::
* CRTC module::
* C64 memory module::
* C128 memory module::
* VIC20 memory module::
* PET memory module::
* CBM-II memory module::
* C500 data module::


File: vice.info,  Node: Module Terminology,  Next: Module framework,  Prev: Module formats,  Up: Module formats

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.


File: vice.info,  Node: Module framework,  Next: CPU 6502 module,  Prev: Module Terminology,  Up: Module formats

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, including this
                                      header


File: vice.info,  Node: CPU 6502 module,  Next: CIA 6526 module,  Prev: Module framework,  Up: Module formats

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   ?                             ?


File: vice.info,  Node: CIA 6526 module,  Next: VIA 6522 module,  Prev: CPU 6502 module,  Up: Module formats

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'.


File: vice.info,  Node: VIA 6522 module,  Next: PIA 6520 module,  Prev: CIA 6526 module,  Up: Module formats

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)


File: vice.info,  Node: PIA 6520 module,  Next: TPI 6525 module,  Prev: VIA 6522 module,  Up: Module formats

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


File: vice.info,  Node: TPI 6525 module,  Next: RIOT 6532 module,  Prev: PIA 6520 module,  Up: Module formats

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


File: vice.info,  Node: RIOT 6532 module,  Next: SID 6581 module,  Prev: TPI 6525 module,  Up: Module formats

RIOT module
...........

   The RIOT 6532 is a chip with two I/O ports, some RAM and a Timer.
The chip contains 128 byte RAM, but the RAM is not saved in the RIOT
snapshot, but in the memory section.

   Warning: This module is still under construction

   Version numbers: Major 0, Minor 0.

Type    Name                          Description
BYTE    ORA                           Port A output register
BYTE    DDRA                          Port A data direction register
BYTE    ORB                           Port B output register
BYTE    DDRB                          Port B data direction register
BYTE    EDGECTRL                      Bit 0/1: A0/A1 address bits written
                                      to edgecontrol registers
BYTE    IRQFL                         Bit 6/7: A6/A7 IRQ flag register.
                                      Bit 0: state of the IRQ line
                                      (0=inactive, 1=active)
BYTE    N                             timer value
WORD    DIVIDER                       Pre-scale divider value (1, 8, 64,
                                      or 1024)
WORD    REST                          cycles since the last counter change
BYTE    IRQEN                         Bit 0: 0= timer IRQ disabled, 1=
                                      timer IRQ enabled


File: vice.info,  Node: SID 6581 module,  Next: ACIA 6551 module,  Prev: RIOT 6532 module,  Up: Module formats

SID module
..........

   Warning: This module is still under construction.


File: vice.info,  Node: ACIA 6551 module,  Next: VIC-I module,  Prev: SID 6581 module,  Up: Module formats

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


File: vice.info,  Node: VIC-I module,  Next: VIC-II module,  Prev: ACIA 6551 module,  Up: Module formats

VIC-I module
............

   Warning: This module is still under construction.


File: vice.info,  Node: VIC-II module,  Next: CRTC module,  Prev: VIC-I module,  Up: Module formats

VIC-II module
.............

   Warning: This module is still under construction.


File: vice.info,  Node: CRTC module,  Next: C64 memory module,  Prev: VIC-II module,  Up: Module formats

CRTC module
...........

   Warning: After VICE version 1.0 the CRTC emulation has improved
considerably. Especially it is now cycle exact. Therefore a lot more
variables must be saved. The snapshot module version jumped from 0.0 to
1.0. Newer versions of VICE can read the old snapshots, but older
versions (1.0 and below) cannot read the new snapshots.

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

   Version numbers: Major 1, Minor 1.

Type    Name                          Description
                                      Hardware options
WORD    VADDR_MASK                    Mask of the address bits valid when
                                      accessing the video memory
WORD    VADDR_CHARSWITCH              If one bit in the video address is
                                      used to switch the character
                                      generator, it is masked here.
WORD    VADDR_CHAROFFSET              The offset in characters in the
                                      character generator that CHARSWITCH
                                      switches.
WORD    VADDR_REVSWITCH               If one bit in the video address
                                      inverts the screen, it is masked
                                      here.
WORD    CHARGEN_MASK                  size of character generator in byte
                                      - 1
WORD    CHARGEN_OFFSET                offset given by external circuitry
BYTE    HW_CURSOR                     external hardware cursor circuitry
                                      enabled
BYTE    HW_COLS                       number of displayed columns during
                                      one character clock cycle
BYTE    HW_BLANK                      set if the hardware blank feature
                                      is available
                                      CRTC register
20 BYTE REGISTERS                     register DUMP of the CRTC registers
                                      0-19.
                                      CRTC internal registers
BYTE    REGNO                         The current index in the CRTC
                                      register file
BYTE    CHAR                          The current cycle within the
                                      current rasterline
BYTE    CHARLINE                      The current character line
BYTE    YCOUNTER                      The current rasterline in the
                                      character
BYTE    CRSRCNT                       Framecounter for the blinking cursor
BYTE    CRSRSTATE                     if set the hardware cursor is
                                      visible
BYTE    CRSRLINES                     set if ycounter is within the
                                      active cursor rasterlines for a char
WORD    CHARGEN_REL                   relative base of currently used
                                      character generator in ROM (in byte)
WORD    SCREEN_REL                    screen address to load the counter
                                      at the beginning of the next
                                      rasterline
WORD    VSYNC                         number of rasterlines left within
                                      vsync; 0 = not in vsync
BYTE    VENABLE                       vertical enable flipflop; 1=
                                      display, 0= blank.
                                      (VICE-dependent?) variables
WORD    SCREEN_WIDTH                  width of the current display window
WORD    SCREEN_HEIGHT                 height of the current display window
WORD    SCREEN_XOFFSET                x position where the first
                                      character in a line starts in the
                                      window...
WORD    HJITTER                       ...but only after adding this jitter
WORD    SCREEN_YOFFSET                x position where the first
                                      character in a line starts in the
                                      window...
WORD    FRAMELINES                    expected number of rasterlines for
                                      the current frame
WORD    CURRENT_LINE                  current rasterline as seen from the
                                      CRTC
                                      This value has been added in module
                                      version V1.1
BYTE    FLAG                          Bit 0: If 1 then bit in
                                      VADDR_REVSWITCH must be set for
                                      reverse; if 0 then bit must be
                                      cleared for reverse.

   Here is the reference for the previous CRTC snapshot module. It is
outdated and will not be read by this and later versions of VICE.

   Version numbers: Major 0, Minor 0.

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


File: vice.info,  Node: C64 memory module,  Next: C128 memory module,  Prev: CRTC module,  Up: Module formats

C64 memory module
.................

   The C64 memory module actually consists of two modules.  The
"C64MEM" 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


File: vice.info,  Node: C128 memory module,  Next: VIC20 memory module,  Prev: C64 memory module,  Up: Module formats

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


File: vice.info,  Node: VIC20 memory module,  Next: PET memory module,  Prev: C128 memory module,  Up: Module formats

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.

   The VIC20MEM module

   Version numbers: Major 1, Minor 0

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

   Version numbers: Major 1, Minor 1

Type    Name                          Description
BYTE    CONFIG                        Bit 0: 1= ROM block $2*** enabled.
                                      Bit 1: 1= ROM block $3*** enabled.
                                      Bit 2: 1= ROM block $4*** enabled.
                                      Bit 3: 1= ROM block $5*** 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)
ARRAY   BLK2A                         4k ROM image $4*** (if CONFIG & 4;
                                      added in V1.1)
ARRAY   BLK2B                         4k ROM image $5*** (if CONFIG & 8;
                                      added in V1.1)


File: vice.info,  Node: PET memory module,  Next: CBM-II memory module,  Prev: VIC20 memory module,  Up: Module formats

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 2

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 following item has been added
                                      in V1.1
BYTE    EOIBLANK                      bit 0=0 = EOI does not blank
                                      screen, bit 0=1 = EOI blanks screen.

   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.

   In V1.2 the new EOIBLANK variable has been added. This implements
the "blank screen on EOI" feature that was previously linked to a wrong
resource.

   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)

