This is Info file vice.info, produced by Makeinfo version 1.68 from the
input file 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: Drive settings,  Next: Peripheral settings,  Prev: Sound settings,  Up: Settings and resources

Drive settings
==============

   These settings are used to control the hardware-level emulation of
the drive.  When hardware-level emulation is turned on, only drives 8
and 9 are being emulated.

   The following settings affect both drives:

   * "Enable true drive emulation" enables the (slow) hardware-level
     emulation of the drives for maximum compatibility.  This must be
     turned on for any of the following settings to have effect.

   * "Drive sync factor" specifies the speed of the drive's CPU.  This
     can be used to help loading certain programs that have trouble
     with the default PAL setting (for example, programs designed for
     NTSC machines).  The ratio is calculated as follows:

          sync_factor = 65536 * clk_drive / clk_machine

     where `clk_drive' and `clk_machine' are clock speeds in MHz.  The
     menu lets you choose between the PAL and NTSC values, and also lets
     you specify whatever value you want.  Be careful when changing it,
     though, because a wrong value can break things and even corrupt
     disk images.

   The following settings, instead, are specific of each drive:

   * "Drive model" specifies the model of the drive being emulated.
     *Warning:* This will reset the drive.

   * "Enable parallel cable" enables emulation of a SpeedDOS parallel
     cable; if you switch this option on and replace the original
     Commodore ROMs with SpeedDOS-compatible ones, you can speed up
     loading/saving times.

   * "Idle method" specifies which method the drive emulation should
     use to save CPU cycles in the host CPU.  There are three methods:

        * "Skip cycles": Each time the serial line is accessed by the
          C64, the drive executes all the cycles since the last time it
          ran.  If the number of elapsed cycles is larger than a
          certain value, the drive discards part of them.

        * "Trap idle": The disk drive is still emulated upon serial line
          accesses as with the previous option, but it is also always
          emulated at the end of each screen frame.  If the drive gets
          into the DOS idle loop, only pending interrupts are emulated
          to save time.

        * "No traps": Like "Trap idle", but without any traps at all.
          So basically the drive works exactly as with the real thing,
          and nothing is done to reduce the power needs of the drive
          emulation.

     The first option ("Skip cycles") is usually best for performance,
     as the drive is emulated as little as possible; on the other hand,
     you may notice sudden slowdowns (when the drive executes several
     cycles at once) and the LED status is never updated (because it
     would not be possible to do correctly so).  Moreover, if the drive
     tries to get in sync with the computer in some weird way and the
     computer does not access the serial line for a long time, it is
     possible that some cycles are discarded and the sync is lost.
     Notice that this hack will have no effect on performance if a
     program continuously reads from the IEC port, as the drive will
     have to be fully emulated in any case (some stupid programs do
     this, even when they don't actually need to use the drive).

     The second option ("Trap idle") is usually a bit slower, as at
     least interrupts are always emulated, but ensures the LED state is
     always updated correctly and always keeps the drive and the
     computer in sync.  On the other hand, if a program installs a
     non-standard idle loop in the drive, the drive CPU has to be
     emulated even when not necessary and the global emulation speed is
     then *much* slower.

   * "40-track image support" specifies how 40-track ("extended") disk
     images should be supported.  There are three possible ways:

        * "Never extend" never extends disk images at all (so if a
          program tries to write tracks beyond the 35th, it is not
          allowed to do so);

        * "Ask on extend" prompts the user as soon as a program tries
          to write tracks beyond the 35th, and the user can then choose
          whether he wants the disk image to be extended or not;

        * "Extend on access" simply extends the disk image as soon the
          program needs it, without prompting the user.

* Menu:

* Drive resources::
* Drive options::


File: vice.info,  Node: Drive resources,  Next: Drive options,  Prev: Drive settings,  Up: Drive settings

Drive resources
---------------

`DriveTrueEmulation'
     Boolean controlling whether the "true" drive emulation is turned
     on.

`Drive8Type'
`Drive9Type'
     Integers specifying the model number for drives 8 and 9.  Possible
     values are `1541', `1571', `1581' and `2031'.

`Drive8ParallelCable'
`Drive9ParallelCable'
     Booleans controlling whether the SpeedDOS-compatible cable is
     emulated or not for drives 8 and 9.

`Drive8ExtendImagePolicy'
`Drive9ExtendImagePolicy'
     Integer specifying the policy for 40-track support for drives 8
     and 9.  Possible values are `0' (never extend), `1' (ask on
     extend), `2' (extend on access).

`Drive8IdleMethod'
`Drive9IdleMethod'
     Integers specifying the idling method for the drive CPU.  Possible
     values are `0' (none), `1' (skip cycles), `2' (trap idle).  *Note
     Drive settings::.

`DriveSyncFactor'
     Integer specifying the drive's clock sync factor (*note Drive
     settings::.).  Special values `-1' and `-2' mean PAL and NTSC,
     respectively.

`DosName1541'
`DosName1571'
`DosName1581'
`DosName2031'
     Strings specifying the names of the ROM images for the drive
     emulation.


File: vice.info,  Node: Drive options,  Prev: Drive resources,  Up: Drive settings

Drive command-line options
--------------------------

`-truedrive'
`+truedrive'
     Turns true drive emulation on (`DriveTrueEmulation=1') and off
     (`DriveTrueEmulation=0'), respectively.

`-drive8type TYPE'
`-drive9type TYPE'
     Specifies the drive types for units 8 and 9, respectively.
     Possible values for `TYPE' are `1541', `1571', `1581' and `2031'.

`-parallel8'
`+parallel8'
`-parallel9'
`+parallel9'
     Turns emulation of the SpeedDOS-compatible parallel cable for disk
     unit 8 or 9 on (`DriveXParallelCable=1', X=8 or 9) and off
     (`DriveXParallelCable=0'), respectively.

`-drive8idle NUM'
`-drive9idle NUM'
     Specifies `NUM' as the idling method in drives 8 and 9,
     respectively (`Drive8IdleMethod', `Drive9IdleMethod').

`-drive8extend NUM'
`-drive9extend NUM'
     Specifies `NUM' as the track 40 extend policy in drives 8 and 9,
     respectively (`Drive8ExtendImagePolicy',
     `Drive9ExtendImagePolicy').

`-paldrive'
     Specifies a PAL sync factor for the drive emulation
     (`DriveSyncFactor=-1').

`-ntscdrive'
     Specifies an NTSC sync factor for the drive emulation
     (`DriveSyncFactor=-2').

`-drivesync NUM'
     Specifies a generic sync factor for the drive emulation
     (`True1541SyncFactor').

`-dos1541'
`-dos1571'
`-dos1581'
`-dos2031'
`-dos2040'
`-dos3040'
`-dos4040'
`-dos1001'
     Specify the ROM names for the 1541, 1571, 1581, 2031, 2040, 3040,
     4040 and 1001 emulation respectively.


File: vice.info,  Node: Peripheral settings,  Next: RS232 settings,  Prev: Drive settings,  Up: Settings and resources

Peripheral settings
===================

   VICE is able to support some special peripherals:

   * "file system devices", pseudo-drives accessing the Unix file
     system;

   * printers.

   These features depend on some "kernal traps" that replace the
existing routines in the original Commodore operating system with
custom-made C routines.

* Menu:

* File system device settings::  Settings for file system devices.
* Printer settings::            Settings for emulating a printer.
* No kernal traps::             Disabling kernal traps completely.


File: vice.info,  Node: File system device settings,  Next: Printer settings,  Prev: Peripheral settings,  Up: Peripheral settings

Settings for file system devices
--------------------------------

   These settings deal with the drive-like peripherals connected to the
bus of the emulated machine.  The first setting relates to the parallel
IEEE488 interface. With this interface a special engine is used to
listen to the bus lines to translates them to the filesystem code. Thus
the PET will always detect a drive for example, but it can also use
drives 10 and 11 even together with true disk drive emulation.

   * "Enable virtual devices", enables the peripheral access via the
     fast disk emulation (either kernal traps or IEEE488 interface).
     Both, filesystem and disk image access via fast drive emulation,
     are affected.

   Four peripherals, numbered from 8 to 11, are accessible; each of
them provides the following settings:

   * "File system access", if enabled, allows the device to emulate a
     drive accessing a file system directory; note that when a disk
     image is attached to the same drive, the directory is no longer
     visible and the attached disk is used instead.

   * "File system directory" specifies the directory to be accessed by
     the drive.

   * "Convert P00 file names", if enabled, allows access to P00 files
     using their built-in name instead of the Unix one.

   * "Create P00 files on save", if enabled, creates P00 files (instead
     of raw CBM files) whenever a program creates a file.

   Note that, by default, all drives except 11 create P00 files on save,
while drive 11 creates raw CBM files. Those files come without any
header, but also with the filename restrictions given by the operating
system VICE runs on.

* Menu:

* File system device resources::
* File system device options::


File: vice.info,  Node: File system device resources,  Next: File system device options,  Prev: File system device settings,  Up: File system device settings

Resources for file system devices
.................................

`FSDevice8ConvertP00'
`FSDevice9ConvertP00'
`FSDevice10ConvertP00'
`FSDevice11ConvertP00'
     Booleans specifying whether on-read support for P00 files is
     enabled on drives 8, 9, 10 and 11 respectively (on by default).

`FSDevice8SaveP00'
`FSDevice9SaveP00'
`FSDevice10SaveP00'
`FSDevice11SaveP00'
     Booleans specifying whether the drives should create P00 files
     instead of plain CBM ones (on by default for drives 8-10, off for
     11).

`FSDevice8HideCBMFiles'
`FSDevice9HideCBMFiles'
`FSDevice10HideCBMFiles'
`FSDevice11HideCBMFiles'
     Booleans specifying whether non-P00 files should be invisible to
     programs running in the emulator (do not hide by default).

`FSDevice8Dir'
`FSDevice9Dir'
`FSDevice10Dir'
`FSDevice11Dir'
     Strings specifying the directories to which drives 8, 9, 10 and 11
     have access.


File: vice.info,  Node: File system device options,  Prev: File system device resources,  Up: File system device settings

Command-line options for file system devices
............................................

`-fs8 PATH'
`-fs9 PATH'
`-fs10 PATH'
`-fs11 PATH'
     Specify the paths for the file system access on drives 8, 9, 10
     and 11, respectively (`FSDevice8Dir', `FSDevice9Dir',
     `FSDevice10Dir' and `FSDevice11Dir').


File: vice.info,  Node: Printer settings,  Next: No kernal traps,  Prev: File system device settings,  Up: Peripheral settings

Printer settings
----------------

   The VICE emulators can emulate printers connected to either the IEC
buffer or the user port.  Emulation can be achieved by redirecting the
printer output to a file or by piping it through an external process.
This is defined by so-called "printer device file names"; a printer
device file name can be either a simple path, or a command name
preceeded by a pipe symbol `|'.

   For example, printer device `filename' will cause the output to be
appended to the file `filename', while printer device `|lpr' will cause
the `lpr' command to be executed and be fed the printer output.  The
printer output will not be converted but saved as printed by the
emulated machine.

   Up to three printer devices may be specified through the following
resources:

   * device 1, whose default value is `print.dump';

   * device 2, whose default value is `|lpr'.

   * device 3, whose default value is `|petlp -F PS|lpr';

   So, basically, by default printer device 1 will dump printer output
to `print.dump'; printer device 2 will print it via `lpr' directly to
the printer and device 3 will print it via `petlp' (a not-yet-complete
utility that will produce Postscript output from the Commodore printer
code) and then to the printer via `lpr'.

* Menu:

* Printer resources::
* Printer options::


File: vice.info,  Node: Printer resources,  Next: Printer options,  Prev: Printer settings,  Up: Printer settings

Printer resources
.................

`PrDevice1'
`PrDevice2'
`PrDevice3'
     Strings specifying the printer devices (*note Printer settings::.).

`Printer4'
     Boolean specifying if the IEC printer (device 4) is being emulated.

`Printer4Dev'
     Integer (ranging from 0 to 2, for device 1-3) specifying what
     printer device (*note Printer settings::.) the IEC printer is
     using.

`PrUser'
     Boolean specifying if the user-port printer is being emulated.

`PrUserDev'
     Integer (ranging from 0 to 2, for device 1-3) specifying what
     printer device the user-port printer is using.


File: vice.info,  Node: Printer options,  Prev: Printer resources,  Up: Printer settings

Printer command-line options
............................

`-prdev1 NAME'
`-prdev2 NAME'
`-prdev3 NAME'
     Specify `NAME' as printer devices 1, 2 and 3, respectively
     (`PrDevice1', `PrDevice2' and `PrDevice3').

`-printer4'
`+printer4'
     Enable/disable emulation of the IEC printer (`Printer4=1',
     `Printer4=0').

`-pr4dev DEV'
     Specify device for the IEC printer (`Printer4Dev').

`-pruser'
`+pruser'
     Enable/disable emulation of the IEC printer (`PrUser=1',
     `PrUser=0').

`-pruserdev DEV'
     Specify device for the IEC printer (`PrUserDev').


File: vice.info,  Node: No kernal traps,  Prev: Printer settings,  Up: Peripheral settings

Disabling kernal traps
----------------------

   If you have compatibility problems, you can completely disable Kernal
traps with the "Disable kernal traps" option.  This will of course
disable all the features that depend on it, such as the fast 1541
emulation (so you will have to turn true 1541 emulation on if you want
to be able to read or write disk images) and tape support.

* Menu:

* No traps resources::
* No traps options::


File: vice.info,  Node: No traps resources,  Next: No traps options,  Prev: No kernal traps,  Up: No kernal traps

Resources to control Kernal traps
.................................

`VirtualDevices'
     Boolean specifying whether all the mechanisms for virtual device
     emulation should be enabled. Serial IEC devices use kernal traps,
     parallel IEEE488 devices use an own IEEE488 engine. Both are
     switched on and off with this resource.


File: vice.info,  Node: No traps options,  Prev: No traps resources,  Up: No kernal traps

Command-line options to control Kernal traps
............................................

`-virtualdev'
`+virtualdev'
     Enable (`VirtualDevices=1') or disable (`VirtualDevices=0')
     virtual devices.


File: vice.info,  Node: RS232 settings,  Next: Misc settings,  Prev: Peripheral settings,  Up: Settings and resources

RS232 settings
==============

   The VICE emulators can emulate the RS232 device most of the machines
have.  The C64, C128 and VIC20 emulators emulate the userport RS232
interface at 300 and 1200 baud.  The C64 and C128 can also use the 9600
baud interface by Daniel Dallmann, using the shift registers of the two
CIA 6526 chips.  The PET can have a 6551 ACIA RS232 interface when
running as a SuperPET, and the CBM-II has such an ACIA by default.  The
C64 and C128 emulators can emulate an ACIA 6551 (also known as Datapump
for example) as extension at `$de**'.

   Emulation can be achieved by either:

   * connecting a real UNIX serial device;

   * dumping to a file;

   * piping through a process.

   It is possible to define up to four UNIX serial devices, and then
decide which interface should be connected to which device.  This is
done by so-called "rs232 device file names"; an rs232 device file name
can be either a simple path, or a command name preceeded by a pipe
symbol `|'.  If the path specifies a special device (e.g. `/dev/ttyS0')
it is recognized by VICE and the emulator can set the baudrate.

   For example, rs232 device `filename' will cause the output to be
written (not appended) to the file `filename', while printer device
`|lpr' will cause the `lpr' command to be executed and be fed the rs232
output.  The rs232 output will not be converted but saved as sent by
the emulated machine.  The same holds true for the rs232 input.  If the
command writes data to the standard output it will be caught by VICE
and sent back to the emulator.  Also the data sent by the pseudo device
will be sent back to VICE.

   For example you can setup a null-modem cable between two serial ports
of your PC, setup one port for login and use the other in VICE.  Then
you can login from your emulator via the RS232 emulation and the
null-modem cable to your machine again.

   You can not simply run a shell from VICE, as the shell will notice
that it does not run on its own pseudo terminal and will thus buffer its
output.  You need to write some program that opens an own pseudo
terminal and runs the shell from there (not yet finished).

   Up to four RS232 devices may be specified through the following
resources:

   * device 1, whose default value is `/dev/ttyS0';

   * device 2, whose default value is `/dev/ttyS1';

   * device 3, whose default value is `rs232.dump';

   * device 4, whose default value is `|lpr'.

   For the first two devices you can change the baudrate the tty device
is set to by specifying it on the commandline or in the menu.  This
baudrate is 9600 by default for the latter two, but can be changed only
by resources (The baudrate is independent from the baudrate the emulator
actually expects).

* Menu:

* RS232 resources::
* RS232 options::
* RS232 usage::


File: vice.info,  Node: RS232 resources,  Next: RS232 options,  Prev: RS232 settings,  Up: RS232 settings

RS232 resources
---------------

`RsDevice1'
`RsDevice2'
`RsDevice3'
`RsDevice4'
     Strings specifying the RS232 devices (*note RS232 settings::.).

`RsDevice1Baud'
`RsDevice2Baud'
`RsDevice3Baud'
`RsDevice4Baud'
     Integer specifying the RS232 baudrate devices if the device file
     points to a special device (like `/dev/ttyS0'; *note RS232
     settings::.).

`AciaDE'
     Boolean specifying whether C64 or C128 should emulate ACIA 6551 in
     I/O 1, at `$de**'.

`Acia1Dev'
     Integer (ranging from 0 to 3, for device 1-4) specifying what
     RS232 device (*note RS232 settings::.) the ACIA is using (all
     except VIC20).

`Acia1Irq'
     Integer specifying which interrupt to use. 0 = none, 1 = IRQ, 2 =
     NMI (C64 and C128 only)

`RsUser'
     Integer specifying if the user-port RS232 interface is being
     emulated and at which baudrate it should have for the emulator. 0
     = off; > 0 specifies the baudrate (C64, C128 and VIC20).

`RsUserDev'
     Integer (ranging from 0 to 3, for device 1-4) specifying what
     RS232 device the user-port interface is using (C64, C128 and
     VIC20).


File: vice.info,  Node: RS232 options,  Next: RS232 usage,  Prev: RS232 resources,  Up: RS232 settings

RS232 command-line options
--------------------------

`-rsdev1 NAME'
`-rsdev2 NAME'
`-rsdev3 NAME'
`-rsdev4 NAME'
     Specify `NAME' as RS232 devices 1, 2, 3 and 4, respectively
     (`RsDevice1', `RsDevice2' `RsDevice3' and `RsDevice4').

`-rsdev1 BAUDRATE'
`-rsdev2 BAUDRATE'
`-rsdev3 BAUDRATE'
`-rsdev4 BAUDRATE'
     Specify `BAUDRATE' as baudrate for the RS232 devices if the device
     name specifies a special device (like `/dev/ttyS0' for example,
     *note RS232 settings::.; `RsDevice1Baud', `RsDevice2Baud'
     `RsDevice3Baud' and `RsDevice4Baud').

`-acia1dev'
     Specify device for the ACIA (`Acia1Dev').

`-rsuser BAUDRATE'
     Enable (BAUDRATE not 0) or disable (BAUDRATE = 0) emulation of the
     userport RS232 emulation (`RsUser'; C64, C128 and VIC20)

`-rsuserdev DEV'
     Specify device for the userport RS232 emulation (`RsUserDev'; C64,
     C128 and VIC20).


File: vice.info,  Node: RS232 usage,  Prev: RS232 options,  Up: RS232 settings

RS232 usage example
-------------------

   Here we give you a simple example how to set up an emulated C64 using
the modem connected to your PC. The following list shows each step.

`Attach your modem to your PC at a serial port.'
     Normally you should set it up to use the modem as "/dev/modem".

`start VICE'

`Setup VICE to use your modem as "serial device 1"'
     Go to the RS232 settings menu and change "Serial 1 device" to
     "/dev/modem" (or the device where you attached your modem to) Then
     go to the RS232 settings menu and change "Serial 1 baudrate" to
     the baudrate your modem should run at.    Watch out, e.g. on Linux
     there is an additional multiplier   to multiply with the baudrate
     (so e.g. 19200 gives 115200 or so baud)   See the "setserial"
     manpage on Linux for example.    However, most modems should be
     able to autodetect the speed to   the computer as well.

`Select the RS232 emulation your programs use'
     If you want to use the Userport emulation, go to the RS232
     settings and   change "Userport RS232 Device" to   "Serial 1". If
     you want ACIA emulation (swiftlink or what's it called?)    then
     change "ACIA $DE** device" to "Serial 1".

`Enable the emulation'
     Go to the RS232 settings and select either "ACIA $DE** emulation"
     or Userport 300/1200 baud or CIA 9600 baud emulation.

`Load your program and start it.'
     If it is able to detect an   RS232 cartridge like swiftlink or so,
     try to detect the ACIA emulation   if enabled.    Otherwise just
     set the baudrate to either 300, 1200 or 9600 according   to what
     you enabled in the VICE menu for the userport.


File: vice.info,  Node: Misc settings,  Prev: RS232 settings,  Up: Settings and resources

Miscellaneous settings
======================

   This section lists generic resources that do not fit in the other
categories.

* Menu:

* Misc resources::
* Misc options::


File: vice.info,  Node: Misc resources,  Next: Misc options,  Prev: Misc settings,  Up: Misc settings

Miscellaneous resources
-----------------------

`Directory'
     String specifying the search path for system files.  It is defined
     as a sequence of directory names, separated by colons (`:'), just
     like the `PATH' variable in the shell.  The special string `$$'
     stands for the default search path, which is initialized at
     startup to the following value:

          LIBDIR/EMUID:$HOME/.vice/EMUID:BOOTPATH/EMUID:LIBDIR/DRIVES:$HOME/.vice/DRIVES:BOOTPATH/DRIVES

     where:

        * `LIBDIR' is the VICE installation directory (usually
          `/usr/local/lib/vice', `/usr/lib/vice' or `/opt/vice/lib');

        * `EMUID' is the emulation identification string (`C64',
          `C128', `VIC20' or `PET');

        * `BOOTPATH' is the directory where the binary lies (usually
          `/usr/local/bin', `/usr/bin' or `/opt/vice/bin').

        * `DRIVES' is the directory called "DRIVES", where the disk
          drive ROMs are.  (The disk drive ROMs are used by all
          emulators, so there is an extra directory for them.)

     Notice that the middle entry points to a default location in the
     user's home directory. Here private ROM versions (e.g.  speeddos
     or JiffyDos) can be stored for example.

     *Note System files::. for a description of the method used to load
     the emulator's system files.

`HTMLBrowserCommand'
     String specifying the command to run the help browser.  The help
     browser can be any HTML browser, and every `%s' in the string is
     replaced with the name of the toplevel file of the VICE
     documentation.  For example, the default value `netscape %s' runs
     Netscape Navigator.

`SaveResourcesOnExit'
     Boolean specifying whether the emulator should save changed
     settings before exiting.  If this is enabled, the user will be
     always prompted first, in case the settings have changed.

`DoCoreDump'
     Boolean specifying whether the emulator should dump core when it
     gets a signal.

`JoyDevice1'
`JoyDevice2'
     Integer specifying which joystick device the emulator should use
     for joystick emulation for ports 1 and 2, respectively (0=None,
     1=Numpad, 2=Custom keys, 3=Analog joystick 1, 4=Analog joystick 2,
     5=Digital joystick 1, 6=Digital joystick 2 on Unix) The available
     joysticks might differ depending on operating system and joystick
     support in the OS (Linux joystick module must be available for
     example).


File: vice.info,  Node: Misc options,  Prev: Misc resources,  Up: Misc settings

Miscellaneous command-line options
----------------------------------

`-directory SEARCHPATH'
     Specify the system file search path (`Directory').

`-htmlbrowser COMMAND'
     Specify the command to run the HTML browser for the on-line help
     (`HTMLBrowserCommand').

`-saveres'
`+saveres'
     Enable/disable automatic saving of settings on exit
     (`SaveResourcesOnExit=1', `SaveResourcesOnExit=0').

`-core'
`+core'
     Enable/disable generation of core dumps (`DoCoreDump=1',
     `DoCoreDump=0').

`-joydev1'
`-joydev2'
     Set the device for joystick emulation of port 1 and 2, respectively
     (`JoyDevice1', `JoyDevice2').


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

Machine-specific features
*************************

* Menu:

* C64/128-specific::            Commands and settings specific to the
                                C64/128 emulators
* VIC20-specific::              Commands and settings specific to the
                                VIC20 emulator
* PET-specific::                Commands and settings specific to the
                                PET emulator
* CBM-II-specific::             Commands and settings specific to the
				CBM-II emulator


File: vice.info,  Node: C64/128-specific,  Next: VIC20-specific,  Prev: Machine-specific features,  Up: Machine-specific features

C64/128-specific commands and settings
======================================

   This section lists the settings and commands that are C64/128
specific and thus are not present in the other emulators.

* Menu:

* C64 cartridges::              Using cartridge images with the C64 emulator.
* VIC-II settings::             Settings that control the video chip.
* SID settings::                Settings that control the audio chip.
* C64 I/O extension settings::  Settings that enable special extensions.
* C64/128 system ROM settings::  Settings to control the system ROMs.


File: vice.info,  Node: C64 cartridges,  Next: VIC-II settings,  Prev: C64/128-specific,  Up: C64/128-specific

Using cartridge images
----------------------

   "Cartridge images" are like disk images, but mirror the contents of
cartridge ROM images instead of disk images.

   X64 and X128 allow you to attach the following kinds of cartridges:

   * `.crt' images, as used by the CCS64 emulator by Per Håkan Sundell;

   * generic raw dumps of 8K and 16K images;

   * Action Replay images.

   * Atomic Power images.

   * Epyx fastload images.

   * The Commodore IEEE488 interface cartridge









     (`http://www.funet.fi/pub/cbm/schematics/cartridges/c64/ieee-488/eprom.bin')

   * Retro Replay images.

   * IDE64 interface cartridge.  (`http://www.volny.cz/dundera/')

   * Super Snapshot 4 images.

   * Super Snapshot 5 images.

   * Expert Cartridge images.

   Each of these kinds has a specific command in the "Attach a cartridge
image" submenu.  When you have successfully attached a cartridge image,
you should then reset the machine to make sure the cartridge initializes
itself.  Of course, it is also possible to detach a currently attached
cartridge image ("Detach cartridge image").

   If you are using a freezer cart like an Action Replay cartridge, you
can emulate the cartridge's freeze button with the "Cartridge freeze"
command.

   Attaching the IEEE488 cartridge automatically enables the IEEE488
interface emulation on the `$DF**' I/O ports.

   Attaching the IDE64 cartridge automatically enables the IDE64
interface emulation on the `$DE**' I/O ports.


File: vice.info,  Node: VIC-II settings,  Next: SID settings,  Prev: C64 cartridges,  Up: C64/128-specific

VIC-II settings
---------------

   These settings control the emulation of the VIC-II (MOS6569) video
chip used in both the C64 and the C128.

   * "Sprite-sprite collisions" and "Sprite-background collisions", if
     enabled, cause the hardware detection of sprite-to-sprite and
     sprite-to-background collisions of the VIC-II to be emulated.  This
     feature is used by many games, and disabling either of the two
     detection systems can sometimes make you invincible (although
     there is also a chance that also enemies become invincible then).

   * "Color set" can be used to dynamically change the palette file
     being used by choosing one of the available predefined color sets:

        * `default.vpl' ("default"), the default VICE palette;

        * `c64s.vpl' ("C64S"), palette taken from the shareware C64S
          emulator by Miha Peternel.

        * `ccs64.vpl' ("CCS64"), palette taken from the shareware CCS64
          emulator by Per Håkan Sundell.

        * `frodo.vpl' ("Frodo"), palette taken from the free Frodo
          emulator by Christian Bauer
          (http://www.uni-mainz.de/~bauec002/FRMain.html).

        * `pc64.vpl' ("PC64"), palette taken from the free PC64
          emulator by Wolfgang Lorenz.

        * `godot.vpl' ("GoDot"), palette as suggested by the authors of
          the C64 graphics package GoDot
          (http://users.aol.com/howtogodot/welcome.htm).

* Menu:

* VIC-II resources::
* VIC-II options::


File: vice.info,  Node: VIC-II resources,  Next: VIC-II options,  Prev: VIC-II settings,  Up: VIC-II settings

VIC-II resources
................

`CheckSsColl'
     Boolean specifying whether the sprite-sprite hardware collision
     detection must be emulated.

`CheckSbColl'
     Boolean specifying whether the sprite-background hardware collision
     detection must be emulated.


File: vice.info,  Node: VIC-II options,  Prev: VIC-II resources,  Up: VIC-II settings

VIC-II command-line options
...........................

`-checkss'
`+checkss'
     Enable (`CheckSsColl=1') and disable (`CheckSsColl=0') emulation
     of hardware sprite-sprite collision detection, respectively.

`-checksb'
`+checksb'
     Enable (`CheckSbColl=1') and disable (`CheckSbColl=0') emulation
     of hardware sprite-background collision detection, respectively.


File: vice.info,  Node: SID settings,  Next: C64 I/O extension settings,  Prev: VIC-II settings,  Up: C64/128-specific

SID settings
------------

   These settings control the emulation of the SID (MOS6581 or MOS8580)
audio chip.

   * "Second SID" maps a second SID chip into the address space for
     stereo sound. This emulates e.g. the "SID Symphony Stereo
     Cartridge" from Dr. Evil Laboratories. The second SID can be used
     with software such as "Stereo SID Player" by Mark Dickenson or
     "The Enhanced Sidplayer" by Craig Chamberlain.

   * "Second SID base address" sets the start address for the second SID
     chip. Software normally uses $DE00 or $DF00, since $DE00-$DEFF and
     $DF00-$DFFF can be mapped through the cartridge port of the C64.
     The default start address is $DE00.

   * "Emulate filters" causes the built-in programmable filters of the
     SID chip to be emulated.  A lot of C64 music requires them to be
     emulated properly, but their emulation requires some additional
     processor power.

   * "ChipModel" specifies the model of the SID chip being emulated:
     there are two slightly different generations of SID chips: MOS6581
     ones and MOS8580 ones.

   * "Use reSID emulation" specifies whether the more accurate (and
     resource hungry) reSID emulation is turned on or off.

   * "reSID sampling method" selects the method for conversion of the
     SID output signal to a sampling rate appropriate for playback by
     standard digital sound equipment. Possible settings are:
        * "Fast" simply clocks the SID chip at the output sampling
          frequency, picking the nearest sample. This yields acceptable
          sound quality, but sampling noise is noticeable in some
          cases, especially with SID combined waveforms. The sound
          emulation is still cycle exact.

        * "Interpolating" clocks the SID chip each cycle, and
          calculates each sample with linear interpolation. The
          sampling noise is now strongly attenuated by the SID external
          filter (as long as "Emulate filters" is selected), and the
          linear interpolation further improves the sound quality.

        * "Resampling" clocks the SID chip each cycle, and uses the
          theoretically correct method for sample generation. This
          delivers CD quality sound, but is extremely CPU intensive,
          and is thus most useful for non-interactive sound generation.
          Unless you have a very fast machine, that is.

   * "reSID resampling passband" specifies the percentage of the total
     bandwidth allocated to the resampling filter passband. The work
     rate of the resampling filter is inversely proportional to the
     remaining transition band percentage. This implies that e.g. with
     the transition band starting at ~ 20kHz, it is faster to generate
     48kHz than 44.1kHz samples. For CD quality sound generation at
     44.1kHz the passband percentage should be set to 90 (i.e. the
     transition band starting at almost 20kHz).

* Menu:

* SID resources::
* SID options::


File: vice.info,  Node: SID resources,  Next: SID options,  Prev: SID settings,  Up: SID settings

SID resources
.............

`SidStereo'
     Boolean selecting emulation of a second SID.

`SidStereoAddressStart'
     Integer specifying the start address for the second SID.

`SidFilters'
     Boolean specifying whether the built-in SID filters must be
     emulated.

`SidModel'
     Integer specifying what model of the SID must be emulated (`0':
     MOS6581, `1': MOS8580).

`SidUseResid'
     Boolean specifying whether the accurate reSID emulation is being
     used.

`SidResidSampling'
     Integer specifying the sampling method (`0': Fast, `1':
     Interpolation, `2': Resampling)

`SidResidPassband'
     Integer specifying the resampling filter passband in percentage of
     the total bandwidth (`0 - 90').


File: vice.info,  Node: SID options,  Prev: SID resources,  Up: SID settings

SID command-line options
........................

`-sidstereo'
     Emulates a second SID chip for stereo sound (`SidStereo').

`-sidstereoaddress `ADDRESS''
     Specifies the start address for the second SID chip
     (`SidStereoAddressStart').

`-sidmodel MODEL'
     Specifies `MODEL' as the emulated model of the SID chip
     (`SidModel').

`-sidfilters'
`+sidfilters'
     Enable (`SidFilters=1') or disable (`SidFilters=0') emulation of
     the built-in SID filters.

`-resid'
`+resid'
     Enable (`SidFilters=1') or disable (`SidFilters=0') usage of the
     reSID emulator.

`-residsamp `METHOD''
     Specifies the sampling method; fast (`SidResidSampling=0'),
     interpolating (`SidResidSampling=1'), or resampling
     (`SidResidSampling=2').

`-residpass `PERCENTAGE''
     Specifies the resampling filter passband in percentage of the total
     bandwidth (`SidResidPassband=0-90').


File: vice.info,  Node: C64 I/O extension settings,  Next: C64/128 system ROM settings,  Prev: SID settings,  Up: C64/128-specific

C64 I/O extension settings
--------------------------

   There are three I/O extensions available: they are located at the
address range $DF00 ... $DFFF and each of them is controlled by a
boolean resource.  Please use these extensions only when needed, as they
might cause compatibility problems.

   * The "emulator identification" extension allows programs to
     identify the kind of emulator they are running on, according to the
     emulation detection proposal by Wolfgang Lorenz.  This basically
     means that, when some locations in the $DFxx I/O space are read,
     the emulator returns some values which identify the emulator
     itself, its version and a copyright message.  If this extension is
     disabled, programs will have virtually no way to realize they are
     running on an emulator.

   * The "512K RAM Expansion Unit" extension emulates a standard 512K
     Commodore RAM Expansion Unit; this can be used with GEOS and other
     programs that are designed to take advantage of it.  This currently
     works only in the C64 emulator.

   * FIXME

* Menu:

* C64 I/O extension resources::
* C64 I/O extension options::


File: vice.info,  Node: C64 I/O extension resources,  Next: C64 I/O extension options,  Prev: C64 I/O extension settings,  Up: C64 I/O extension settings

C64 I/O extension resources
...........................

`IEEE488'
     Boolean specifying whether the IEEE488 interface should be
     emulated or not.

`REU'
     Boolean specifying whether the 512K RAM Expansion Unit should be
     emulated or not.

`EmuID'
     Boolean specifying whether the emulation identification extension
     should be emulated or not.


File: vice.info,  Node: C64 I/O extension options,  Prev: C64 I/O extension resources,  Up: C64 I/O extension settings

C64 I/O extension command-line options
......................................

`-ieee488'
`+ieee488'
     Enable (`IEEE488=1') or disable (`IEEE488=0') emulation of the
     IEEE488 interface.

`-reu'
`+reu'
     Enable (`REU=1') or disable (`REU=0') emulation of the 512K RAM
     Expansion Unit.

`-emuid'
`+emuid'
     Enable (`EmuID=1') or disable (`EmuID=0') the emulation
     identification extension.


File: vice.info,  Node: C64/128 system ROM settings,  Prev: C64 I/O extension settings,  Up: C64/128-specific

C64/128 system ROM settings
---------------------------

   These settings can be used to control what system ROMs are loaded in
the C64/128 emulators at startup.  They cannot be changed from the
menus.

* Menu:

* C64/128 system ROM resources::
* C64/128 system ROM options::


File: vice.info,  Node: C64/128 system ROM resources,  Next: C64/128 system ROM options,  Prev: C64/128 system ROM settings,  Up: C64/128 system ROM settings

C64/128 system ROM resources
............................

`KernalName'
     String specifying the name of the Kernal ROM (default `kernal').

`BasicName'
     String specifying the name of the Basic ROM (default `basic').  In
     the C128 emulator, the ROM image must actually include the editor
     ROM too.

`ChargenName'
     String specifying the name of the character generator ROM (default
     `chargen').

`KernalRev'
     String specifying the Kernal revision.  This resource can be used
     to control what revision of the C64 kernal is being used; it
     cannot be changed at runtime.  VICE is able to automatically
     convert one ROM revision into another, by manually patching the
     loaded image.  This way, it is possible to use any of the ROM
     revisions without changing the ROM set.  Valid values are:

    `0'
          Kernal revision 0;

    `3'
          Kernal revision 3;

    `sx'
    `67'
          Commodore SX-64 ROM;

    `100'

    `4064'
          Commodore 4064 (also known as "PET64" or "Educator 64") ROM.


File: vice.info,  Node: C64/128 system ROM options,  Prev: C64/128 system ROM resources,  Up: C64/128 system ROM settings

C64/128 system ROM command-line options
.......................................

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

`-kernalrev REVISION'
     Specify Kernal revision (`KernalRev').


File: vice.info,  Node: VIC20-specific,  Next: PET-specific,  Prev: C64/128-specific,  Up: Machine-specific features

VIC20-specific commands and settings
====================================

   This section lists the settings and commands that are VIC20-specific
and thus are not present in the other emulators.

* Menu:

* VIC20 cartridges::
* VIC20 memory expansions::
* VIC20 system ROM settings::


File: vice.info,  Node: VIC20 cartridges,  Next: VIC20 memory expansions,  Prev: VIC20-specific,  Up: VIC20-specific

Using cartridge images
----------------------

   As with the C64 (*note C64 cartridges::.), it is possible to attach
several types of cartridge images:

   * 4 or 8 Kbyte cartridges located at $2000;

   * 4 or 8 Kbyte cartridges located at $4000;

   * 4 or 8 Kbyte cartridges located at $6000;

   * 4 or 8 Kbyte cartridges located at $A000;

   * 4 Kbyte cartridges located at $B000.

   This can all be done via the "Attach cartridge image..." command in
the left-button menu.  It is also possible to let XVIC "guess" the type
of cartridge using "Smart-attach cartridge image...".

   Notice that several cartridges are actually made up of two pieces
(and two files), that need to be loaded separately at different
addresses.  In that case, you have to know the addresses (which are
usually specified in the file name) and use the "attach" command twice.

   A special kind of cartridge file is where the two files mentioned
above are concatenated (with removing the two byte load address of the
second image) into one 16k image. There are only few of those images,
though. Normally the second part is located at $A000.  Vice can now
attach such concatenated files at the start address $2000, $4000, and
$6000. The second half of such an image is moved to $A000. If you
encounter 16k images that have the second half not at $A000 you can
split the image into two halfs (i.e. one 8194 byte and one 8192 byte,
because the first has the load address) and attach both files
separately.

   One cartridge that is currently only partially supported here is the
VIC1112 IEEE488 interface. You have to load the ROM as a cartridge, but
you also have to enable the IEEE488 hardware by menu.


File: vice.info,  Node: VIC20 memory expansions,  Next: VIC20 system ROM settings,  Prev: VIC20 cartridges,  Up: VIC20-specific

Changing memory configuration
-----------------------------

   It is possible to change the VIC20 memory configuration in two ways:
by enabling and/or disabling certain individual memory blocks, or by
choosing one among a few typical memory configurations.  The former can
be done by modifying resource values directly or from the right-button
menu; the latter can only be done from the menu.

   There are 5 RAM expansion blocks in the VIC20, numbered 0, 1, 2, 3
and 5:

   * block 0 (3 Kbytes at $0400-$0FFF);

   * block 1 (8 Kbytes at $2000-$3FFF);

   * block 2 (8 Kbytes at $4000-$5FFF);

   * block 3 (8 Kbytes at $6000-$7FFF);

   * block 5 (8 Kbytes at $A000-$BFFF).

   These blocks are called "expansion blocks" because they are not
present a stock ("unexpanded") machine.  Each of them is associated to
a boolean `RamBlockX' resource (where `X' is the block number) that
specifies whether the block is enabled or not.

   There are also some common memory configurations you can pick from
the right-button menu:

   * no RAM expansion blocks at all;

   * all RAM expansion blocks enabled;

   * 3K expansion (only block 0 is enabled);

   * 8K expansion (only block 1 is enabled);

   * 16K expansion (only blocks 1 and 2 are enabled);

   * 24K expansion (only blocks 1, 2 and 3 are enabled).

   As with the X64 (*note C64 I/O extension settings::.), it is also
possible to enable a special emulator identification mechanism that uses
certain memory locations to let a running program query information
about the emulator itself; this is enabled by the "Emulator
identification" option.

* Menu:

* VIC20 memconf resources::
* VIC20 memconf options::


File: vice.info,  Node: VIC20 memconf resources,  Next: VIC20 memconf options,  Prev: VIC20 memory expansions,  Up: VIC20 memory expansions

VIC20 memory configuration resources
....................................

`RAMBlock0'
`RAMBlock1'
`RAMBlock2'
`RAMBlock3'
`RAMBlock5'
     Booleans specifying whether RAM blocks 0, 1, 2, 3 and 5 must be
     enabled.

`EmuID'
     Boolean specifying whether the emulation identification extension
     must be enabled.


File: vice.info,  Node: VIC20 memconf options,  Prev: VIC20 memconf resources,  Up: VIC20 memory expansions

VIC20 memory configuration command-line options
...............................................

`-memory CONFIG'
     Specify memory configuration.  It must be a comma-separated list of
     options, each of which can be one the following:

        * `none' (no extension);

        * `all' (all blocks);

        * `3k' (3k space in block 0);

        * `8k' (first 8k extension block);

        * `16k' (first and second 8k extension blocks);

        * `24k' (first, second and 3rd extension blocks);

        * `0', `1', `2', `3', `5' (memory in respective blocks);

        * `04', `20', `40', `60', `A0' (memory at respective address.

     For example,

          xvic -memory none

     gives an unexpanded VIC20.  While

          xvic -memory 60,a0

     or

          xvic -memory 3,5

     enables memory in blocks 3 and 5, which is the usual configuration
     for 16k ROM modules.

`-emuid'
`+emuid'
     Enable (`EmuID=1') or disable (`EmuID=0') the emulation
     identification extension.


File: vice.info,  Node: VIC20 system ROM settings,  Prev: VIC20 memory expansions,  Up: VIC20-specific

VIC20 system ROM settings
-------------------------

   These settings can be used to control what system ROMs are loaded in
the VIC20 emulator at startup.  They cannot be changed from the menus.

* Menu:

* VIC20 system ROM resources::
* VIC20 system ROM options::


File: vice.info,  Node: VIC20 system ROM resources,  Next: VIC20 system ROM options,  Prev: VIC20 system ROM settings,  Up: VIC20 system ROM settings

VIC20 system ROM resources
..........................

`KernalName'
     String specifying the name of the Kernal ROM (default `kernal').

`BasicName'
     String specifying the name of the Basic ROM (default `basic').

`ChargenName'
     String specifying the name of the character generator ROM (default
     `chargen').

`CartridgeFile2000'
`CartridgeFile4000'
`CartridgeFile6000'
`CartridgeFileA000'
`CartridgeFileB000'
     String specifying the name of the respective cartridge ROM images.


File: vice.info,  Node: VIC20 system ROM options,  Prev: VIC20 system ROM resources,  Up: VIC20 system ROM settings

VIC20 system ROM command-line options
.....................................

`-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'
`-cartA NAME'
`-cartB NAME'
     Specify `NAME' as the cartridge image to attach.
     (`CartridgeFile2000',...,`CartridgeFileB000').


File: vice.info,  Node: PET-specific,  Next: CBM-II-specific,  Prev: VIC20-specific,  Up: Machine-specific features

PET-specific commands and settings
==================================

   This section lists the settings and commands that are PET-specific
and thus are not present in the other emulators.

* Menu:

* PET model::
* PET diagnostic pin::
* PET commandline options::
* PET colors::

