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: ROM files,  Next: Keymap files,  Prev: System files,  Up: System files

ROM files
=========

   Every emulator requires its own ROM set.  For the VIC20 and the C64,
the ROM set consists of the following files:

   * `kernal',  the Kernal ROM (8 KBytes)

   * `basic', the Basic ROM (8 KBytes)

   * `chargen', the character generator ROM (4 Kbytes)


   The C128 needs the following files:

   * `kernal', the Kernal ROM (8 Kbytes)

   * `basic', the Basic + Editor ROM (32 Kbytes)

   * `chargen', the character generator ROM (4 Kbytes)


   The C128, VIC20 and C64 emulators also need the following DOS ROMs
for the hardware-level emulation of the 1541, 1571 and 1581 disk drives:

   * `dos1541', the 1541 drive ROM (16 Kbytes)

   * `dos1541II', the 1541-II drive ROM (16 Kbytes)

   * `dos1571', the 1571 drive ROM (32 Kbytes)

   * `dos1581', the 1581 drive ROM (32 Kbytes)


   In addition to those all emulators can handle a parallel IEEE488
interface (the C64 and C128 via `$df**' extension, the VIC20 via
VIC1112 emulation) so they also need the DOS ROM for the IEEE disk
drives:

   * `dos2031', the 2031 drive ROM (16 Kbytes) (DOS 2.6, Commodore ROM
     images 901484-03 and 901484-05)

   * `dos2040', the 2040 drive ROM (8 Kbytes) (DOS 1, Commodore ROM
     images 901468-06, 901468-07)

   * `dos3040', the 3040 drive ROM (12 Kbytes) (DOS 2, Commodore ROM
     images 901468-11, 901468-12 and 901468-13)

   * `dos4040', the 4040 drive ROM (12 Kbytes) (DOS 2, Commodore ROM
     images 901468-14, 901468-15 and 901468-16)

   * `dos1001', the 1001/8050/8250 drive ROM (16 Kbytes) (DOS 2.7,
     Commodore ROM images 901887-01 and 901888-01)


   Note that there are other DOS images on the internet. The DOS 2.5
images might be used with the 8050, but it cannot handle the double
sided drives of the 1001 and 8250 and it is not supported by VICE.

   The PET emulator uses an expanded setup, because there are three
major versions of the Basic and the Kernal, and many versions of the
Editor ROM. In addition there are cartridge ROM sockets.

   The Kernal files contain the memory from range $F000-$FFFF, the Basic
ROMs either the range $C000-$DFFF or $B000-$DFFF.  To handle the
different screen sizes and keyboards, different so-called "editor-ROMs"
for the memory range $E000-$E800 are provided.  The PET ROMs have the
following names:

   * `kernal1', the PET2001 Kernal ROM (4 KBytes) (Commodore ROM images
     901447-06 and 901447-07)

   * `kernal2', the PET3032 Kernal ROM (4 KBytes) (Commodore ROM image
     901465-03)

   * `kernal4', the PET4032/8032 Kernal ROM (4 KBytes) (Commodore ROM
     image 901465-22)

   * `basic1', the PET2001 Basic 1 ROM (8 KBytes) (Commodore ROM images
     901447-09, 901447-02, 901447-03, 901447-04.bin.  The -09 ROM is
     the revised -01 ROM)

   * `basic2', the PET3032 Basic 2 ROM (8 KBytes) (Commodore ROM images
     901465-01 and 901465-01)

   * `basic4', the PET4032/8032 Basic 4 ROM (12 KBytes) (Commodore ROM
     images 901465-23, 901465-20 and 901465-21.  The -23 ROM is a
     revised -19 ROM)

   * `edit1g', the PET2001 editor for graphics keyboards (2 KBytes)
     (Commodore ROM image 901447-05)

   * `edit2b', the PET3032 editor for business keyboards (2 KBytes)
     (Commodore ROM image 901474-01)

   * `edit2g', the PET3032 editor for graphics keyboards (2 KBytes)
     (Commodore ROM image 901447-24)

   * `edit4g40', the PET4032 editor for graphics keyboards (2 KBytes)
     (Commodore ROM image 901498-01)

   * `edit4b40', the PET4032 editor for business keyboards (2 KBytes)
     (Commodore ROM image 901474-02)

   * `edit4b80', the PET8032 editor for business keyboards (2 KBytes)
     (Commodore ROM image 901474-04-?)

   *   * `chargen', the character generator ROM (2k).  It has two sets with
     128 chars each.  The second (inverted) half of each set is
     computed from the first half by inverting it.  This is a PET
     hardware feature.  (Commodore ROM image 901447-10)

   * `chargen.de', the character generator ROM (2k). This version is a
     patched German charset, with the characters [, \ and ] replaced by
     umlauts.  It has been provided by U. Guettich and he reports that
     it is supported by some programs.

   The PETs also have sockets for extension ROMs for the addresses
$9000-$9FFF, $A000-$AFFF and $B000-$BFFF (the last one for PET2001 and
PET3032 only).  You can specify ROM image files for those extensions
command line options `-petrom9', `-petromA' and `-petromB' resp.

   An alternative would be to specify a long kernal ROM with the
`-kernal' option that includes the extension ROM areas.

   Also, you can specify replacements for the basic ROM at $B000-$DFFF
with the `-petromBasic' option and for the editor ROM at $E000-$E7FF
with the `-petromEditor' option.

   The CBM-II emulator again uses another setup.  For those models the
kernal used is the same for all.  However, for different amounts of
memory exist different versions of the BASIC ROMs.  The 128k RAM version
(C610, C710, B128) uses one bank of 64k for the BASIC text and another
one for all the variables.  The 256k RAM version uses one bank for text,
one for variables, one for arrays and one for strings.

   Also the character generator ROMs have a format different from the
above.  The other character ROMs have 8 bytes of pixel data per
character.  Those ROMs have 16 bytes per character instead.  The C6x0
only uses the first 8 of it, but the C7x0 uses 14 lines per character
and needs those increased ROMs.  Both ROMs hold, like the PET, two
character sets with 128 characters each.  Again the second half of the
full (256 char) character set is computed by inverting.

   * `kernal', the KERNAL (8k) for the business machines (6xx/7xx)

   * `kernal.500', the KERNAL (8k) for the personal machine (510)
     (901234-02)

   * `basic.128', the CBM-II 128k BASIC (16k)

   * `basic.256', CBM-II 256k BASIC (16k)

   * `basic.500', C510 BASIC (16k) (901236-02 + 901235-02)

   * `chargen.500', character generator ROM for the C5x0 (4k)
     (901225-01)

   * `chargen.600', character generator ROM for the C6x0 (4k)

   * `chargen.700', character generator ROM for the C7x0 (4k)



File: vice.info,  Node: Keymap files,  Next: Palette files,  Prev: ROM files,  Up: System files

Keymap files
============

   "Keymap files" are used to define the keyboard layout, defining which
key (or combination of keys) must be mapped to each keysym.

   In other words, the keyboard emulation works like this: whenever the
user presses or releases a key while the emulation window has the input
focus, the emulator receives an X-Window event with a value that
identifies that key.  That value is called a "keysym" and is unique to
that key.  The emulator then looks up that keysym in an internal table
that tells it which key(s) to press or release on the emulated keyboard.

   This table is described by the keymap file, which is made up of lines
like the following:

     KEYSYM ROW COLUMN SHIFTFLAG

   Where:

   * `KEYSYM' is a string identifying the keysym: you can use the `xev'
     utility (shipped with the X Window system) to see what keysym is
     bound to any key;

   * `ROW' and `COLUMN' identify the key on the emulated keyboard;

   * `SHIFTFLAG' can have one of the following values:

        * `0': the key is never shifted;

        * `1': the key is shifted;

        * `2': the key is the left shift;

        * `4': the key is the right shift;

        * `8': the key can be (optionally) shifted by the user.



   The `SHIFTFLAG' is useful if you want certain keys to be
"artificially" shifted by the emulator, and not by the user.  For
example, <F2> is shifted on the C64 keyboard, but you might want it to
be mapped to the unshifted <F2> key on the PC keyboard.  To do so, you
just have to use a line like the following:

     F2 0 4 1

   where `0' and `4' identify the key (row 0, column 4 on the keyboard
matrix), and `1' specifies that every time the user presses <F2> the
shift key on the C64 keyboard must be pressed.

   There are also some special commands you can put into the keyboard
file; they are recognized because they start with an exclamation mark:

   * `!CLEAR' clears the currently loaded keyboard map; it is necessary
     to put this at the beginning of the file if you want the keymap
     file to override all of the current internal settings;

   * `!LSHIFT', `!RSHIFT', followed by a row and a column value,
     specify where the left and right shift keys are located on the
     emulated keyboard; for example, C64 default keymaps will specify

          !LSHIFT 1 7
          !RSHIFT 6 4


   Any line starting with the `#' sign, instead, is completely ignored.
This is useful for adding comments within the keymap file.

   VICE keymap files have the `.vkm' default extension, and every
emulator comes with a default positional mapping and a default symbolic
mapping.


File: vice.info,  Node: Palette files,  Next: Romset files,  Prev: Keymap files,  Up: System files

Palette files
=============

   "Palette files" are used to specify the colors used in the
emulators.  They are made up of lines like the following:

     RED GREEN BLUE DITHER

   where `RED', `GREEN' and `BLUE' are hexadecimal values ranging from
0 to FF and specifying the amount of red, green and blue you want for
each color and `DITHER' is a 4-bit hexadecimal number specifying the
pattern you want when rendering on a B/W display.

   You have to include as many lines as the number of colors the
emulated machine has, and the order of the lines must respect the one
used in the machine (so the N'th line must contain the specifications
for color N - 1 in the emulated machine).

   Lines starting with the `#' sign are completely ignored.  This is
useful for adding comments (such as color names) within the palette
file.

   For example, the default PET palette file (which has only two
colors, 0 for background and 1 for foreground), looks like the
following:

     #
     # VICE Palette file
     #
     # Syntax:
     # Red Green Blue Dither
     #
     
     # Background
     00 00 00 0
     
     # Foreground
     00 FF 00 F


File: vice.info,  Node: Romset files,  Prev: Palette files,  Up: System files

Romset files
============

   The Romset files are not used by default on all emulators.  You
might have recognized that the names of the ROM images are saved in
resources. Loading a Romset file now just means a `shortcut' to
changing all the resources with ROM image names and reloading the ROMs.

   The PET and CBM-II emulators use this feature to change between the
different ROM versions available for those machines. E.g. the Romset
file for the PET 2001 is

     KernalName="pet2001"
     EditorName=
     ChargenName="chargen"
     RomModule9Name=
     RomModuleAName=
     RomModuleBName=

   As you can see, the file even uses the same syntax as the resource
file, it is just a bit stripped down.


File: vice.info,  Node: Basics,  Next: Settings and resources,  Prev: System files,  Up: Top

Basic operation
***************

   This section describes the basic things you can do once the emulator
has been fired up.

* Menu:

* Emulation window::            The window the emulator runs in.
* Menus::                       Using emulator menus.
* Help::                        Getting help if you are stuck.
* File Selector::               Selecting files interactively.
* Disk and tape images::        Using virtual disks and tapes.
* Reset::                       Resetting the virtual machines.


File: vice.info,  Node: Emulation window,  Next: Menus,  Prev: Basics,  Up: Basics

The emulation window
====================

   When the emulator is run, the screen of the emulated machine is
displayed in a standard X Window which we will call the "emulation
window".  This window will be updated in real time, displaying the same
contents that a real monitor or TV set would.

   Below the emulation window there is an area which is used to display
information about the state of the emulator; we will call this area the
"status bar".

   On the extreme left of the status bar, there is a "performance
meter".  This displays the current relative speed of the emulator (as a
percentage) and the update frequency (in frames per second).  All the
machines emulated are PAL, so the update frequency will be 50 frames
per second if your system is fast enough to allow emulation at the
speed of the real machine.

   On the extreme right of the status bar, there is a "drive status
indicator".  This is only visible if the hardware-level ("True") 1541
emulation is turned on.  In that case, the drive status indicator will
contain a rectangle emulating the drive LED and will display the current
track position of the drive's read/write head.


File: vice.info,  Node: Menus,  Next: Help,  Prev: Emulation window,  Up: Basics

Using the menus
===============

   It is possible to execute some commands and change emulation
parameters while the emulator is running: when the pointer is over the
emulation window, two menus are available by pressing either the left
or right mouse buttons.  The left mouse button will open the "command
menu" from which several emulation-related commands can be executed;
the right mouse button will open the "settings menu" from which
emulation parameters can be changed.  The basic difference between the
command and the settings menu is that, while commands have only effect
on the current session, settings can be saved and later used with the
"Save settings" and "Load settings" right-button menu items,
respectively.  "Restore default settings" restores the factory defaults.
*Note Settings and resources::. for more information about how settings
work in VICE.

   Sometimes commands can be reached via "shortcuts" or "hotkeys",
i.e., it is possible to execute them by pressing a sequence of keys
instead of going through the menu with the mouse.  Where shortcuts
exist, they are displayed in parentheses at the right edge of the menu
item.  In VICE, all shortcuts must begin with the <Meta> or <Alt> key.
So, for example, to attach a disk image to drive #8 (the corresponding
menu item displays "M-8"), you have to press the <Meta> (or <Alt>) and
then <8>.

   Note that no other key presses are passed on to the emulated machine
while either <Meta> or <Alt> are held down.


File: vice.info,  Node: Help,  Next: File Selector,  Prev: Menus,  Up: Basics

Getting help
============

   At any time, if you get stuck or do not remember how to perform a
certain action, you can use the "Browse manuals" command (left button
menu).  This will popup a browser and open the HTML version of this
documentation.  Notice that this requires VICE to be properly (and
fully) installed with a `make install'.

   The browser can be specified via the `HTMLBrowserCommand' string
resource (*note Settings and resources:: for information about
resources).  Every `%s' in the string will be replaced with a URL to
the VICE HTML pages.


File: vice.info,  Node: File Selector,  Next: Disk and tape images,  Prev: Help,  Up: Basics

Using the file selector
=======================

   In those situations where it is necessary to specify a file name, all
of the VICE emulators will pop up a file selector window allowing you
to select or specify a file interactively.

   To the left of the file selector, there is a list of ancestor
directories: by clicking on them, you can ascend the directory tree.  To
the right, there is a list of the files in the current directory; files
can be selected by clicking on them.  If you click on a directory, that
directory becomes the current one; if you click on an ordinary file, it
becomes the active selection.

   At the top, there is a "directory box", with the complete path of
the current directory, and a "file name box", with the name of the
currently selected file.  At the bottom there are two buttons: "OK"
confirms the selected file and "Cancel" abandons the file selector
without cancelling the operation.

   It is also possible to specify what files you want to show in the
file selector by writing an appropriate shell-like pattern in the
directory box; e.g., `~/*.[dx]64' will only show files in the home
directory whose name ends with either `.d64' or with `.x64'.


File: vice.info,  Node: Disk and tape images,  Next: Reset,  Prev: File Selector,  Up: Basics

Using disk and tape images
==========================

   The emulator is able to emulate disk drives and (read-only) tape
recorders if provided with suitable "disk images" or "tape images".  An
"image" is a raw dump of the contents of the media, and must be
"attached" before the emulator can use it.  "Attaching" a disk or tape
image is like "virtually" inserting a diskette or a cassette into the
disk drive or the tape recorder: once an image is attached, the
emulator is able to use it as a storage media.

   There are five commands (in the left button menu) that deal with disk
and tape images:

   * Attach Disk Image

   * Detach Disk Image

   * Attach Tape Image

   * Detach Tape Image

   * Smart-attach a file


   The first four commands are used to insert and remove the virtual
disks and cassettes from the respective units.  On the other hand, the
last commands tries to guess the type of the image you are attaching
from its name and size, and attaches it to the most reasonable device.

   Supported formats are `D64' and `X64' for disk images (devices 8, 9
and 10) and `T64' for tape images.  Notice that `T64' support is
_read-only_, and that the cassette is automatically rewound when you
reach its end.

   Another important feature is that raw Commodore BASIC binary files
and .P00 files can be attached as tapes.  As you can autostart a tape
image when it is attached (*note Autostart::), this allows you to
autostart these particular files as well.

   You can attach a disk for which you do not have write permissions:
when this happens, the 1541 emulator will emulate a write-protected
disk.  This is also useful if you want to prevent certain disk images
from being written to; in the latter case, just remove the write
permission for that file, e.g., by doing a `chmod a-w'.

* Menu:

* Previewing contents::         Looking into the image before attaching it.
* Autostart::                   Starting a program automagically.
* Compressed files::            Dealing with compressed files.
* Zipcode and Lynx::            Using Zipcoded ([1-4]!*) and Lynx files.


File: vice.info,  Node: Previewing contents,  Next: Autostart,  Prev: Disk and tape images,  Up: Disk and tape images

Previewing the image contents
-----------------------------

   It is possible to examine the directory of a disk or tape image
before attaching it.  Just press the "Contents" button in the file
selector window and a new window will pop up with the contents of the
selected image.

   Notice that this function automatically translates the directory from
PETSCII to ASCII; but, due to differences in the two encodings, it is
not always possible to translate all the characters, so you might get
funny results when "weird" characters such as the semi-graphical ones
are being used.


File: vice.info,  Node: Autostart,  Next: Compressed files,  Prev: Previewing contents,  Up: Disk and tape images

"Autostarting" an image
-----------------------

   If you want to reset the machine and run the first program on a
certain image without typing any commands at the Commodore BASIC
prompt, you can use the "Autostart" button in the file selector window
after selecting a proper disk or tape image file.

   Notice that, if true drive emulation is turned on, it will be turned
off before running the program and then turned on again after it has
been loaded.  This way, you get the maximum possible speed while
loading the file, but you do not lose compatibility once the program
itself is running.

   This method is not completely safe, because some autostarting methods
might cause the true drive emulation not to be turned on again.  In such
cases, the best thing to do is to disable kernal traps (which will cause
true drive emulation to be always kept turned on), or to manually load
the program with true drive emulation turned on.


File: vice.info,  Node: Compressed files,  Next: Zipcode and Lynx,  Prev: Autostart,  Up: Disk and tape images

Using compressed files
----------------------

   It is also possible to attach disk or tape images that have been
compressed through various algorithms; compression formats are
identified from the file extension.  The following formats are supported
(the expected file name extension is in parenthesis):

   * GNU Zip (`.gz' or `.z');

   * BZip version 2 (`.bz2');

   * PkZip (`.zip');

   * GNU Zipped TAR archives (`.tar.gz', `.tgz');

   * Zoo (`.zoo').

   PkZip, `tar.gz', `lha' and `zoo' support is _read-only_ and always
uses the _first_ `T64' or `D64' file in the archive.  So archives
containing multiple files will always be handled as if they contain
only a single file.

   Windows and MSDOS don't contain the needful programs to handle
compressed archives. Get gzip and unzip for Windows at
ftp://ftp.freesoftware.com/pub/infozip/WIN32 and for MSDOS at
ftp://ftp.freesoftware.com/pub/infozip/MSDOS. Don't use pkunzip for
MSDOS, it doesn't work. The programs to use BZip2 archives may be found
at http://sourceware.cygnus.com/bzip2.  Just put the programs
(unzip.exe, gzip.exe, bzip2.exe) into a directory of your search path
(e.g. C:\DOS or C:\WINDOWS\COMMAND; have a look at the PATH variable).


File: vice.info,  Node: Zipcode and Lynx,  Prev: Compressed files,  Up: Disk and tape images

Using Zipcode and Lynx images
-----------------------------

   Since version 0.15, the VICE emulators have been able to attach disks
packed with Zipcode or Lynx directly, removing the need to manually
convert them into `D64' or `X64' files with `c1541'.  This is achieved
by automatically invoking `c1541', letting it decode the file into a
temporary image and attaching the resulting temporary image read-only.
For this to work, the directory containing `c1541' must be in your
`PATH'.

   This uses the `-unlynx' and `-zcreate' options of `c1541' (*note
c1541 commands and options::); these commands are not very reliable
yet, and could fail with certain kinds of Lynx and Zipcode images (for
example, they cannot deal with `DEL' files properly).  So please use
them with caution.

   Lynx files usually come as `.lnx' files which are unpacked into
single disk images.  On the other hand, Zipcode files do not have a
particular extension (although `.z64' is sometimes used), and represent
a disk by means of component files, named as follows:

   * `1!NAME'

   * `2!NAME'

   * `3!NAME'

   * `4!NAME'

   If you attach as a disk image (or smart-attach) any one of these
files, the emulator will simply pick up the other three (by examining
the name) and then build a disk image using all four.


File: vice.info,  Node: Reset,  Prev: Disk and tape images,  Up: Basics

Resetting the machine
=====================

   You can reset the emulated machine at any time by using the "Reset"
command from the command menu.  There are two types of reset:

   * "soft reset", which simply resets the CPU and all the other chips;

   * "hard reset", which also clears up the contents of RAM.

   A "soft reset" is the same as a hardware reset achieved by pulling
the RESET line down; a "hard reset" is more like a power on/power off
sequence in that it makes sure the whole RAM is cleared.

   It is possible that a soft reset may not be enough to take the
machine to the OS initialization sequence: in such cases, you will have
to do a hard reset instead.

   This is especially the case for the CBM-II emulators.  Those machines
examine a memory location and if they find a certain "magic" value they
only do what you know from the C64 as `Run/Stop-Restore'.  Therefore,
to really reset a CBM-II use hard reset.


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

Settings and resources
**********************

   In the VICE emulators, all the settings are stored in entities known
as called "resources".  Each resource has a name and a value which may
be either an integer or a string.  Integer values are often used as
boolean values with the usual convention of using zero for "false" and
any other value for "true".

   Resource values can be changed via the right-button menu (the
"settings" menu), via command-line options or via the "resource file".

   The "resource file" is a human-readable file containing resource
values: it is called `vicerc' and is stored in the directory `.vice/'
in the user's home directory.  It is possible to dump the current
values of the resources into that file or load the values stored into
that file as the current values, at any time.  This is achieved with
the "Save settings" and "Load settings" right menu items.  A third menu
item, "Restore Default Settings", can be used to reset all the values
to the factory defaults.

   A special resource, `SaveResourcesOnExit', if set to a non zero
value, causes the emulator to ask you if you want to save the current
(changed) settings before exiting, and can be toggled with the "Save
settings on exit" command from the right-button menu.

   Notice that not all the resources can be changed from the menus;
some of them can only be changed by manually modifying the resource
file or by using command-line options.

* Menu:

* Resource files::              Format of resource files.
* Resources and command-line::  Specifying settings from the
                                command-line

* Performance settings::        Settings that affect speed of execution.
* Video settings::              Settings dealing with the video output.
* Keyboard settings::           Settings relative to the keyboard emulation.
* Sound settings::              Settings that control audio playback
* Drive settings::              Settings that control disk-drive emulation.
* Peripheral settings::         Settings for emulated external devices.
* RS232 settings::              Settings for the RS232 emulation.
* Misc settings::               Other settings.


File: vice.info,  Node: Resource files,  Next: Resources and command-line,  Prev: Settings and resources,  Up: Settings and resources

Format of resource files
========================

   A resource file is made up of several sections; sections have the
purpose of separating the resources of a certain emulator from the ones
of the other emulators.  A section starts with the name of an emulator
in brackets (e.g., `[C64]') and ends when another section starts or
when the file ends.

   Every line in a section has the following format:

     RESOURCE=VALUE

   where `RESOURCE' is the name of a resource and `VALUE' is its
assigned value.  Resource names are case-sensitive and resource values
are either strings or integers.  Strings must start and end with a
double quote character (`"'), while integers must be given in decimal
notation.

   Here is an example of a stripped-down `.vice/vicerc' file:

     [VIC20]
     HTMLBrowserCommand="netscape %s"
     SaveResourcesOnExit=0
     FileSystemDevice8=1
     FSDevice8ConvertP00=1
     FSDevice8Dir="/home/ettore/cbm/stuff/vic20p00"
     FSDevice8SaveP00=1
     FSDevice8HideCBMFiles=1
     [C64]
     HTMLBrowserCommand="netscape %s"
     SaveResourcesOnExit=1
     FileSystemDevice8=1
     FSDevice8ConvertP00=1
     FSDevice8Dir="/home/ettore/cbm/stuff/c64p00"
     FSDevice8SaveP00=1
     FSDevice8HideCBMFiles=1

   Notice that, when resource values are saved with "Save settings", the
emulator only modifies its own section, leaving the others unchanged.


File: vice.info,  Node: Resources and command-line,  Next: Performance settings,  Prev: Resource files,  Up: Settings and resources

Using command-line options to change resources
==============================================

   Resources can also be changed via command-line options.

   Command-line options always override the defaults from
`.vice/vicerc', and their assignments last for the whole session.  So,
if you specify a certain command-line option that changes a certain
resource from its default value and then use "Save Settings", the value
specified with the command-line option will be saved back to the
resource file.

   Command-line options can begin with with a minus sign (`-') or with
a plus sign (`+').  Options beginning with a minus sign may require an
additional parameter, while the ones beginning with the plus sign never
require one.

   Moreover, options beginning with a plus sign always have a
counterpart with the same name, but with a minus sign; in that case,
the option beginning with a minus sign is used to _enable_ a certain
feature, while the one beginning with a plus sign is used to _disable_
the same feature (this is an X11 convention).  For example, `-mitshm'
enables support of MITSHM, while `+mitshm' disables it.


File: vice.info,  Node: Performance settings,  Next: Video settings,  Prev: Resources and command-line,  Up: Settings and resources

Performance settings
====================

   It is possible to control the emulation speed by using the "Maximum
speed" menu item in the right-button menu.  The default setting is
`100', which causes the emulation to never run faster than the real
machine.  A higher value allows the emulator to run faster, a lower one
may force it to run slower.  The setting "No limit" means to run as
fast as possible, without limiting speed.

   It is also possible to control the emulator's rate of frame update
using the "Refresh rate" setting; the value ranges from "1/1" (update
1/1 of the frames of the real machine, that is 50 frames per second) to
"1/10" (update 1 every 10 frames) and can be changed via the "Refresh
Rate" submenu.  The "Auto" setting means to dynamically adapt the
refresh rate to the current speed of the host machine, making sure the
maximum speed specified by the via "Maxium speed" is always reached if
possible.  In any case, the refresh rate will never be worse than 1/10
if this option is specified.

   Note that you cannot simultaneously specify "Auto" as the refresh
rate and "No limit" as the maximum speed..

   Moreover, a special "warp speed" mode is provided and can be toggled
with the "Enable Warp Mode" menu item.  If this mode is enabled, it
will cause the emulator to disable any speed limit, turn sound emulation
off and use a 1/10 refresh rate, so that it will run at the maximum
possible speed.

* Menu:

* Performance resources::
* Performance options::


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

Performance resources
---------------------

`Speed'
     Integer specifying the maximum relative speed, as a percentage.
     `0' stands for "no limit".

`RefreshRate'
     Integer specifying the refresh rate; a value of `n' specifies a
     refresh rate of 1/`n'.  A value of `0' enables automatic frame
     skipping.

`WarpMode'
     Booolean specifying whether "warp mode" is turned on or not.



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

Performance command-line options
--------------------------------

`-speed VALUE'
     Specifies the maximum speed as a percentage.  `0' stands for "no
     limit".  (Same as setting the `Speed' resource.)

`-refresh VALUE'
     Specifies refresh rate; a value of `n' specifies a refresh rate of
     1/`n'.  A value of `0' enables automatic frame skipping.  (Same as
     setting the `RefreshRate' resource.)

`-warp'
`+warp'
     Enables/disables warp mode (`WarpMode=1', `WarpMode=0').



File: vice.info,  Node: Video settings,  Next: Keyboard settings,  Prev: Performance settings,  Up: Settings and resources

Video settings
==============

   The following right-button menu items control the video output.  On
emulators that include two video chips (like `x128') all options but
XSync exist twice, once for each chip.  XSync is shared between the
video chips.

   * "Video Cache" enables a video cache that can speed up the emulation
     when little graphics activity is going on; it is especially useful
     when you run the emulator on a networked X terminal as it can
     reduce the network bandwidth required.  However, this setting can
     actually make the emulator slower when there is little graphics
     activity and the amount of work needed to maintain the cache is
     greater than the amount of work that would be wasted by not using
     it (if any).

   * "Double Size" toggles "double-size mode", which makes the
     emulation window twice as big.  When emulating a 80-column PET,
     only the height is doubled, so that the aspect ratio is closer to
     that of the real thing.

   * "Double Scan" toggles "double-scan mode", which causes the
     emulator to draw only odd lines when running in double-size mode
     (this saves some CPU time and also makes the emulation window look
     more like an old monitor).

   * `Use XSync()" causes the emulator to call the X11 function
     `XSync()' before updating the emulation window: this might be
     necessary on low-end systems to prevent it from consuming so many
     system resources that it becomes impossible for the user to
     interact with it.


* Menu:

* Video resources::
* Video options::


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

Video resources
---------------

   The following resources affect the screen emulation. The prefix of
some of the resources and commandline options denote the video chip the
values apply to.

`VideoCache, CrtcVideoCache'
     Boolean specifying whether the video cache is turned on.

`DoubleSize, CrtcDoubleSize'
     Boolean specifying whether double-size mode is turned on.

`DoubleScan, CrtcDoubleScan'
     Boolean specifying whether double-scan mode is turned on.

`UseXSync'
     Boolean specifying whether `XSync()' is called after updating the
     emulation window.

`MITSHM'
     Integer specifying whether VICE should try to use the shared memory
     extensions (MITSHM) when starting up.  The shared memory
     extensions make things a lot faster but might not be available on
     your system.  You will not be able to use these extensions if you
     are sitting at an X terminal while running the emulator on a
     remote machine across a network.  Valid values are: 0 = do not use
     MITSHM, 1 = do use MITSHM, -1 = try to autodetect availability on
     startup (default).  The last is a simple test if the emulator runs
     across a network and if so disables MITSHM (If you have problems
     with this test please report it).

`PrivateColormap'
     Boolean specifying whether VICE should install a private colormap
     at startup.  This makes sense for 8-bit displays that could run
     out of colors if other color-hungry applications are running at
     the same time.

`DisplayDepth'
     Integer specifying the depth of the host display.  The value `0'
     (the default) causes the emulator to autodetect it.

`PaletteFile, CrtcPaletteFile'
     String specifying the name of the palette file being used.  The
     `.vpl' extension is optional.



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

Video command-line options
--------------------------

`-vcache'
`+vcache'
     Enable/disable the video cache (`VideoCache=1', `VideoCache=0').

`-dsize'
`+dsize'
     Enable/disable the double size mode (`DoubleSize=1',
     `DoubleSize=0').

`-dscan'
`+dscan'
     Enable/disable the double scan mode (`DoubleScan=1',
     `DoubleScan=0').

`-xsync'
`+xsync'
     Enable/disable usage of `XSync()' when updating the emulation
     window (`UseXSync=1', `UseXSync=0').

`-mitshm'
`+mitshm'
     Enable/disable usage of the MITSHM extensions (`MITSHM=1',
     `MITSHM=0').

`-mitshmauto'
     Enable autodetection of MITSHM availability (`MITSHM=-1')

`-install'
`+install'
     Enable/disable installation of a private colormap
     (`PrivateColormap=1', `PrivateColormap=0').

`-displaydepth DEPTH'
     Specify the display depth (`DisplayDepth').

`-palette NAME'
`-crtcpalette NAME'
     Specify `NAME' as the palette file
     (`PaletteFile',`CrtcPaletteFile').



File: vice.info,  Node: Keyboard settings,  Next: Sound settings,  Prev: Video settings,  Up: Settings and resources

Keyboard settings
=================

   It is possible to specify whether the "positional" or "symbolic"
keyboard mapping should be used with the "Keyboard mapping type"
submenu (*note Keyboard emulation:: for an explanation of positional
and symbolic mappings).

   The keyboard settings submenu also allows you to:

   * Load custom-made positional and symbolic keymap files ("Set
     symbolic keymap file" and "Set positional keymap file").

   * Dump the current keymap to a user-defined keymap file ("Dump to
     keymap file").

* Menu:

* Keyboard resources::
* Keyboard options::


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

Keyboard resources
------------------

`KeymapIndex'
     Integer identifying which keymap is being used; `0' indicates
     symbolic mapping, `1' positional mapping.  For the PET the even
     values represent symbolic mapping, odd positional.  Then add `0'
     for UK business keyboard or `2' for graphics keyboard.

`KeymapSymFile'
     String specifying the name of the keymap file for the symbolic
     mapping (*note Keyboard emulation::, all but PET and CBM-II).

`KeymapPosFile'
     String specifying the name of the keymap file for the positional
     mapping (*note Keyboard emulation::, all but PET and CBM-II).

`KeymapBusinessUKSymFile'
`KeymapBusinessUKPosFile'
     String specifying the name of the keymap file for the symbolic and
     positional mapping for the UK business keyboard (*note Keyboard
     emulation::, PET and CBM-II).

`KeymapGraphicsSymFile'
`KeymapGraphicsPosFile'
     String specifying the name of the keymap file for the symbolic and
     positional mapping for the graphics keyboard (*note Keyboard
     emulation::, PET only).

`KeymapBusinessDESymFile'
`KeymapBusinessDEPosFile'
     String specifying the name of the keymap file for the symbolic and
     positional mapping for the German business keyboard.  (*note
     Keyboard emulation::, PET only).



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

Keyboard command-line options
-----------------------------

`-keymap N'
     Specifies which keymap is being used; `0' indicates symbolic
     mapping, `1' positional mapping (as for the `KeymapIndex'
     resource).

`-symkeymap NAME'
     Specify `NAME' as the symbolic keymap file (`KeymapSymFile').

`-poskeymap NAME'
     Specify `NAME' as the positional keymap file (`KeymapPosFile').

`-buksymkeymap NAME'
`-bukposkeymap NAME'
     Specify `NAME' as the symbolic/positional keymap file for the UK
     business keyboard (`KeymapBusinessUKSymFile',
     `KeymapBusinessUKPosFile', PET and CBM-II).

`-grsymkeymap NAME'
`-grposkeymap NAME'
     Specify `NAME' as the symbolic/positional keymap file for the
     graphics keyboard (`KeymapGraphicsSymFile',
     `KeymapGraphicsPosFile', PET only).

`-bdesymkeymap NAME'
`-bdeposkeymap NAME'
     Specify `NAME' as the symbolic/positional keymap file for the
     German business keyboard (`KeymapBusinessDESymFile',
     `KeymapBusinessDEPosFile', PET only).



File: vice.info,  Node: Sound settings,  Next: Drive settings,  Prev: Keyboard settings,  Up: Settings and resources

Sound settings
==============

   The following menu items control sound output:

   * "Enable sound playback" turns sound emulation on and off.

   * "Sound synchronization" specifies the method for syncronizing the
     sound playback.  Possible settings are:
        * "Flexible", i.e., the audio renderer flexibly adds/removes
          samples to the output to smoothly adapt the playback to
          slight changes in the speed of the emulator.

        * "Adjusting" works like "flexible", but supports bigger
          differences in speed.  For example, if the emulation speed
          drops down from from 100% to 50%, audio slows down by the
          same amount too.

        * "Exact", instead, makes the audio renderer output always the
          same sounds you would hear from the real thing, without
          trying to adapt the ratio; to compensate the tolerances in
          speed, some extra frames will be skipped or added.

   * "Sample rate" specifies the sampling frequency, ranging from 8000
     to 48000 Hz (not all the sound cards and/or sound drivers can
     support all the frequencies, so actually the nearest candidate
     will be chosen).

   * "Buffer size" specifies the size of the audio buffer; the bigger
     the buffer, the longer the delay with which sounds are played.
     You should pick the smallest value your machine can handle without
     problems.

   * "Sound suspend time", will cause the audio playback to pause for
     the specified number of seconds whenever some clicking happens.
     If "Keep going" is selected, no pausing is done.

   * "Oversample" specifies an oversampling factor, from 1 to 8 times
     (warning: this eats CPU cycles!).


* Menu:

* Sound resources::
* Sound options::


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

Sound resources
---------------

`Sound'
     Boolean specifying whether audio emulation is turned on.

`SoundSpeedAdjustment'
     Integer specifying what speed adjustment method the audio renderer
     should use.  Possible values are:
        * `0': "flexible"

        * `1': "adjusting"

        * `2': "exact"

`SoundSampleRate'
     Integer specifying the sampling frequency, ranging from 8000 to
     48000 Hz (not all the sound cards and/or sound drivers can support
     all the frequencies, so actually the nearest candidate will be
     chosen).

`SoundBufferSize'
     Integer specifying the size of the audio buffer, in milliseconds.

`SoundSuspendTime'
     Integer specifying the pause interval when audio underflows
     ("clicks") happen.  `0' means no pause is done.

`SoundOversample'
     Integer specifying the oversampling factor, ranging from `0' (no
     oversampling) to `3' (8 times oversampling).

`SoundDeviceName'
     String specifying the audio driver.

     Implemented drivers are:

        * `aix', for the IBM AIX sound driver.

        * `uss', for the Linux/FreeBSD Universal Sound System driver
          (`SoundDeviceArg' specifies the audio device, `/dev/dsp' by
          default);

        * `sgi', for the Silicon Graphics audio device (`SoundDeviceArg'
          specifies the audio device, `/dev/audio' by default);

        * `sun', for the Solaris audio device (unfinished;
          `SoundDeviceArg' specifies the audio device, `/dev/audio' by
          default).

        * `hpux', for the HP-UX audio device (unfinished;
          `SoundDeviceArg' specifies the audio device, `/dev/audio' by
          default).

        * `sdl', for the Simple DirectMedia Layer audio driver.

        * `esd', for EsounD, the Enlightened Sound Daemon;
          `SoundDeviceArg' specifies the ESD server (`host:port') to
          connect, empty by default.

        * `dummy', fully emulating the SID, but not actually playing
          samples.

        * `dump', writing all the write accesses to the registers to a
          file (specified by `SoundDeviceArg', default value is
          `vicesnd.sid');

        * `speed', like `dummy' but also calculating samples (mainly
          used to evaluate the speed of the sample generator);

        * `fs', writing samples to a file (specified by
          `SoundDeviceArg'; default is `vicesnd.raw');

     These drivers will actually be present only if the VICE
     configuration script detected the corresponding devices at the
     time of compilation.

`SoundDeviceArg'
     String specifying an additional parameter for the audio driver (see
     `SoundDeviceName').



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

Sound command-line options
--------------------------

`-sound'
`+sound'
     Turns sound emulation on (`Sound=1') and off (`Sound=0').

`-soundsync N'
     Specify `N' as the sound speed adjustment method
     (`SoundSpeedAdjustment').

`-soundrate RATE'
     Specifies the sound playback sample rate (`SoundSampleRate').

`-soundbufsize SIZE'
     Specifies the size of the audio buffer in milliseconds
     (`SoundBufferSize').

`-sounddev NAME'
     Specifies the name of the audio device (`SoundDeviceName').

`-soundarg ARG'
     Specifies an additional parameter for the audio device
     (`SoundDeviceArg').



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

