6 Settings and resources

In the VICE emulators, all the settings are stored in entities which are called resources. Every resource has a name and its value can be either an integer or a string. Often integer values are 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 user's home directory. At any time, 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. This can be achieved with the "Save settings" and "Load settings" right menu items. A third menu item, "Restore Default Settings", can be used to set 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.

6.1 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 is started with the name of an emulator in brackets (eg. `[C64]') and ends when another section starts, or the file ends.

Every line in a section has the following format:

RESOURCE=VALUE

where RESOURCE is the name of a resource, while VALUE is the value to assign. Resource names are case-sensitive, and resource values can be either strings or integers. Strings must start and end with a double quote ("), while integers do just have to be written in decimal notation.

Here is an example of a stripped-down `.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, keeping the other ones unchanged.

6.2 Using command-line options to change resources

Resources can also be changed via command-line options.

Command-line options always override the defaults from .vicerc, and their value lasts 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.

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

Moreover, options beginning with the plus sign always have a counterpart with the same name, but with the minus sign; in that case, the option beginning with the minus sign is used to enable a certain feature, while the one beginning with the 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.

6.3 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 makes the emulator faster, a lower one makes it slower. The setting "No limit" means to run as fast as possible, without limiting speed.

It is also possible to control the amount of screen frames the emulator calculates with 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.

Notice that you cannot specify "Auto" as the refresh rate and "No limit" as the maximum speed at the same time.

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.

6.3.1 Performance resources

Speed

Integer specifying the maximum relative speed, in percent. 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.

6.3.2 Performance command-line options

-speed VALUE

Specifies the maximum speed in percent. 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=1).

6.4 Video settings

The following right-button menu items control the video output:

• "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 amount of bandwidth required. But this can actually make the emulator slower when there is little graphics activity and the amount of work needed to maintain the cache is bigger 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 more similiar to the one 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 stealing so many system resources that it would become impossible for the user to interact with it.

6.4.1 Video resources

The following resources affect the screen emulation:

VideoCache

Boolean specifying whether the video cache is turned on.

DoubleSize

Boolean specifying whether double-size mode is turned on.

DoubleScan

Boolean specifying whether double-scan mode is turned on.

UseXSync

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

MITSHM

Boolean specyfying 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, or you might not be allowed to use them because you are running the emulator on an X terminal, across a network.

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) makes the emulator autodetect it.

6.4.2 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).

-install

+install

Enable-disable installation of a private colormap (PrivateColormap=1, PrivateColormap=0).

-displaydepth DEPTH

Specify the display depth (DisplayDepth).

6.5 Keyboard settings

It is possible to specify whether the "positional" or "symbolic" keyboard mapping is being used with the "Keyboard mapping type" submenu (see section 2.5 The 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").

6.5.1 Keyboard resources

KeymapIndex

Integer identifying which keymap is being used; 0 identifies symbolic mapping, 1 positional mapping.

KeymapSymFile

String specifying the name of the keymap file for the symbolic mapping (see section 2.5 The keyboard emulation).

KeymapPosFile

String specifying the name of the keymap file for the positional mapping (see section 2.5 The keyboard emulation).

6.5.2 Keyboard command-line options

-keymap N

Specifies which keymap is being used; 0 identifies symbolic mapping, 1 positional mapping (same as the KeymapIndex resource).

-symkeymap NAME

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

-poskeymap NAME

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

6.6 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 little 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 nearmost candidate will be picked up).

• "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!).

6.6.1 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 nearmost candidate will be picked up).

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.

• 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 installation.

SoundDeviceArg

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

6.6.2 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).

6.7 1541 settings

These settings are used to control the emulation of the 1541 drive.

• "Enable true 1541 emulation" enables the slow hardware-level emulation of the 1541 drive number 8 for maximum compatibility.

• "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.

• "True 1541 sync factor" specifies the speed of the 1541 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_1541 / clk_machine
  

  where clk_1541 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.

• "True 1541 idle method" specifies which method the 1541 emulation should use to save CPU cycles. 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 was running. 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 traps at all. So basically the 1541 works exactly as with the real thing, and nothing is done to reduce the power needs of the 1541 emulation.
  The first option ("Skip cycles") is usually better for performance, as the drive is emulated as little as possible; on the other hand, you can 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 can have no effect on performance if one program continuously reads from the IEC port, as the drive will have to be emulated in any case (some stupid programs do so, 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 allows the LED state to be always updated correctly and always keeps the 1541 and the computer in sync. On the other hand, if a program installs a non-standard idle loop in the drive, the 1541 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 she 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.

6.7.1 1541 resources

True1541

Boolean controlling whether the "true" 1541 emulation emulation is turned on.

True1541ParallelCable

Boolean controlling whether the SpeedDOS-compatible cable is emulated or not.

True1541ExtendImagePolicy

Integer specifying the policy for 40-track support. Possible values are 0 (never extend), 1 (ask on extend), 2 (extend on access).

True1541IdleMethod

Integer specifying the idling method for the 1541 CPU. Possible values are 0 (none), 1 (skip cycles), 2 (trap idle). See section 6.7 1541 settings.

True1541SyncFactor

Integer specifying the true 1541 clock sync factor (see section 6.7 1541 settings). Special values -1 and -2 mean PAL and NTSC, respectively.

DosName

String specifying the name of the ROM image for the 1541 emulation.

6.7.2 1541 command-line options

-1541

+1541

Turns true 1541 emulation on (True1541=1) and off (True1541=0), respectively.

-parallel

+parallel

Turns emulation of the SpeedDOS-compatible parallel cable on (True1541ParallelCable=1) and off (True1541ParallelCable=0), respectively.

-driveidle NUM

Specifies NUM as the 1541 idling method (True1541IdleMethod).

-paldrive

Specifies a PAL sync factor for the 1541 emulation (True1541SyncFactor=-1).

-ntscdrive

Specifies an NTSC sync factor for the 1541 emulation (True1541SyncFactor=-2).

-drivesync NUM

Specifies a generic sync factor for the 1541 emulation (True1541SyncFactor).

-dosname NAME

Specifies the name of the DOS ROM image (DosName).

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

6.8.1 Settings for file system devices

These settings deal with the drive-like peripherals connected to the bus of the emulated machine. 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; notice that if a disk is attached to the same drive, the directory is not visible anymore, and the attached disk is used instead.

• "File system directory" specifies what directory is 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.

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

FSDevice8SaveP00

FSDevice9SaveP00

FSDevice10SaveP00

FSDevice11SaveP00

Booleans specifying whether the drives should create P00 files instead of plain CBM ones.

FSDevice8HideCBMFiles

FSDevice9HideCBMFiles

FSDevice10HideCBMFiles

FSDevice11HideCBMFiles

Booleans specifying whether non-P00 files should be invisible to programs running in the emulator.

FSDevice8Dir

FSDevice9Dir

FSDevice10Dir

FSDevice11Dir

Strings specifying the paths of the directories drives 8, 9, 10 and 11 have access to.

6.8.1.2 Command-line options for file system devices

-fs8 PATH

-fs9 PATH

-fs10 PATH

-fs11 PATH

Specify the path for the file-system access on drives 8, 9, 10 and 11, respectively (FSDevice8Dir, FSDevice9Dir, FSDevice10Dir and FSDevice11Dir).

6.8.2 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 prepended by the pipe symbol `|'.

For example, printer device `filename' will cause the output to be appended to file `filename', while printer device `|lpr' will cause the lpr command to be executed and fed with the printer output.

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

• device 1, whose default value is print.dump;

• device 2, whose default value is |petlp |lpr;

• device 3, whose default value is |lpr.

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

6.8.2.1 Printer resources

PrDevice1

PrDevice2

PrDevice3

Strings specifying the printer devices (see section 6.8.2 Printer settings).

Printer4

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

Printer4Dev

Integer (ranging from 1 to 3) specifying what device the IEC printer is using.

PrUser

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

PrUserDev

Integer (ranging from 1 to 3) specifying what device the user-port printer is using.

6.8.2.2 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).

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

6.8.3.1 Resources to control Kernal traps

NoTraps

Boolean specifying whether all the Kernal trap should be disabled.

6.8.3.2 Command-line options to control Kernal traps

-traps

+traps

Enable (NoTraps=0) or disable (NoTraps=1) kernal traps.

6.9 Miscellaneous settings

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

6.9.1 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:BOOTPATH/EMUID

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

See section 4 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.

6.9.2 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).

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