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.
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.
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.
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.
Speed
0
stands for "no limit".
RefreshRate
n specifies a
refresh rate of 1/n. A value of 0 enables automatic frame
skipping.
WarpMode
-speed VALUE
0 stands for "no
limit". (Same as setting the Speed resource.)
-refresh VALUE
n specifies a refresh rate of
1/n. A value of 0 enables automatic frame skipping.
(Same as setting the RefreshRate resource.)
-warp
+warp
WarpMode=1, WarpMode=0).
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.
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.
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
DoubleSize, CrtcDoubleSize
DoubleScan, CrtcDoubleScan
UseXSync
XSync() is called after updating the
emulation window.
MITSHM
PrivateColormap
DisplayDepth
PaletteFile, CrtcPaletteFile
-vcache
+vcache
VideoCache=1, VideoCache=0).
-dsize
+dsize
DoubleSize=1,
DoubleSize=0).
-dscan
+dscan
DoubleScan=1,
DoubleScan=0).
-xsync
+xsync
XSync() when updating the emulation
window (UseXSync=1, UseXSync=0).
-mitshm
+mitshm
MITSHM=1,
MITSHM=0).
-mitshmauto
MITSHM=-1)
-install
+install
PrivateColormap=1, PrivateColormap=0).
-displaydepth DEPTH
DisplayDepth).
-palette NAME
-crtcpalette NAME
NAME as the palette file (PaletteFile,CrtcPaletteFile).
It is possible to specify whether the "positional" or "symbolic" keyboard mapping should be used with the "Keyboard mapping type" submenu (see section 2.6 The keyboard emulation for an explanation of positional and symbolic mappings).
The keyboard settings submenu also allows you to:
KeymapIndex
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
KeymapPosFile
KeymapBusinessUKSymFile
KeymapBusinessUKPosFile
KeymapGraphicsSymFile
KeymapGraphicsPosFile
KeymapBusinessDESymFile
KeymapBusinessDEPosFile
-keymap N
0 indicates symbolic
mapping, 1 positional mapping (as for the KeymapIndex
resource).
-symkeymap NAME
KeymapSymFile).
-poskeymap NAME
KeymapPosFile).
-buksymkeymap NAME
-bukposkeymap NAME
KeymapBusinessUKSymFile, KeymapBusinessUKPosFile, PET and CBM-II).
-grsymkeymap NAME
-grposkeymap NAME
KeymapGraphicsSymFile, KeymapGraphicsPosFile, PET only).
-bdesymkeymap NAME
-bdeposkeymap NAME
KeymapBusinessDESymFile, KeymapBusinessDEPosFile, PET only).
The following menu items control sound output:
Sound
SoundSpeedAdjustment
0: "flexible"
1: "adjusting"
2: "exact"
SoundSampleRate
SoundBufferSize
SoundSuspendTime
0 means no pause is done.
SoundOversample
0 (no
oversampling) to 3 (8 times oversampling).
SoundDeviceName
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');
SoundDeviceArg
SoundDeviceName).
-sound
+sound
Sound=1) and off (Sound=0).
-soundsync N
N as the sound speed adjustment method
(SoundSpeedAdjustment).
-soundrate RATE
SoundSampleRate).
-soundbufsize SIZE
SoundBufferSize).
-sounddev NAME
SoundDeviceName).
-soundarg ARG
SoundDeviceArg).
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:
sync_factor = 65536 * clk_drive / clk_machinewhere
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:
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.
DriveTrueEmulation
Drive8Type
Drive9Type
1541, 1571, 1581 and 2031.
Drive8ParallelCable
Drive9ParallelCable
Drive8ExtendImagePolicy
Drive9ExtendImagePolicy
0 (never extend), 1 (ask on extend),
2 (extend on access).
Drive8IdleMethod
Drive9IdleMethod
0 (none), 1 (skip cycles), 2 (trap idle).
See section 6.7 Drive settings.
DriveSyncFactor
-1 and -2 mean PAL and NTSC,
respectively.
DosName1541
DosName1571
DosName1581
DosName2031
-truedrive
+truedrive
DriveTrueEmulation=1) and off
(DriveTrueEmulation=0), respectively.
-drive8type TYPE
-drive9type TYPE
TYPE are 1541, 1571, 1581 and
2031.
-parallel8
+parallel8
-parallel9
+parallel9
DriveXParallelCable=1, X=8 or 9) and off
(DriveXParallelCable=0), respectively.
-drive8idle NUM
-drive9idle NUM
NUM as the idling method in drives 8 and 9, respectively
(Drive8IdleMethod, Drive9IdleMethod).
-drive8extend NUM
-drive9extend NUM
NUM as the track 40 extend policy in drives 8 and 9,
respectively
(Drive8ExtendImagePolicy, Drive9ExtendImagePolicy).
-paldrive
DriveSyncFactor=-1).
-ntscdrive
DriveSyncFactor=-2).
-drivesync NUM
True1541SyncFactor).
-dos1541
-dos1571
-dos1581
-dos2031
-dos2040
-dos3040
-dos4040
-dos1001
VICE is able to support some special peripherals:
These features depend on some kernal traps that replace the existing routines in the original Commodore operating system with custom-made C routines.
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.
Four peripherals, numbered from 8 to 11, are accessible; each of them provides the following settings:
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.
FSDevice8ConvertP00
FSDevice9ConvertP00
FSDevice10ConvertP00
FSDevice11ConvertP00
FSDevice8SaveP00
FSDevice9SaveP00
FSDevice10SaveP00
FSDevice11SaveP00
FSDevice8HideCBMFiles
FSDevice9HideCBMFiles
FSDevice10HideCBMFiles
FSDevice11HideCBMFiles
FSDevice8Dir
FSDevice9Dir
FSDevice10Dir
FSDevice11Dir
-fs8 PATH
-fs9 PATH
-fs10 PATH
-fs11 PATH
FSDevice8Dir, FSDevice9Dir,
FSDevice10Dir and FSDevice11Dir).
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:
print.dump;
|lpr.
|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.
PrDevice1
PrDevice2
PrDevice3
Printer4
Printer4Dev
PrUser
PrUserDev
-prdev1 NAME
-prdev2 NAME
-prdev3 NAME
NAME as printer devices 1, 2 and 3, respectively
(PrDevice1, PrDevice2 and PrDevice3).
-printer4
+printer4
Printer4=1,
Printer4=0).
-pr4dev DEV
Printer4Dev).
-pruser
+pruser
PrUser=1,
PrUser=0).
-pruserdev DEV
PrUserDev).
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.
VirtualDevices
-virtualdev
+virtualdev
VirtualDevices=1) or disable (VirtualDevices=0)
virtual devices.
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:
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:
/dev/ttyS0;
/dev/ttyS1;
rs232.dump;
|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).
RsDevice1
RsDevice2
RsDevice3
RsDevice4
RsDevice1Baud
RsDevice2Baud
RsDevice3Baud
RsDevice4Baud
AciaDE
$de**.
Acia1Dev
Acia1Irq
RsUser
RsUserDev
-rsdev1 NAME
-rsdev2 NAME
-rsdev3 NAME
-rsdev4 NAME
NAME as RS232 devices 1, 2, 3 and 4, respectively
(RsDevice1, RsDevice2 RsDevice3 and RsDevice4).
-rsdev1 BAUDRATE
-rsdev2 BAUDRATE
-rsdev3 BAUDRATE
-rsdev4 BAUDRATE
BAUDRATE as baudrate for the RS232 devices if the device name
specifies a special device (like `/dev/ttyS0' for example,
see section 6.9 RS232 settings;
RsDevice1Baud, RsDevice2Baud RsDevice3Baud and
RsDevice4Baud).
-acia1dev
Acia1Dev).
-rsuser BAUDRATE
RsUser; C64, C128 and VIC20)
-rsuserdev DEV
RsUserDev;
C64, C128 and VIC20).
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.
start VICE
Setup VICE to use your modem as "serial device 1"
Select the RS232 emulation your programs use
Enable the emulation
Load your program and start it.
This section lists generic resources that do not fit in the other categories.
Directory
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/DRIVESwhere:
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.)
HTMLBrowserCommand
SaveResourcesOnExit
DoCoreDump
JoyDevice1
JoyDevice2
-directory SEARCHPATH
Directory).
-htmlbrowser COMMAND
HTMLBrowserCommand).
-saveres
+saveres
SaveResourcesOnExit=1, SaveResourcesOnExit=0).
-core
+core
DoCoreDump=1,
DoCoreDump=0).
-joydev1
-joydev2
JoyDevice1, JoyDevice2).
Go to the first, previous, next, last section, table of contents.