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


4 System files

In order to work properly, the emulators need to load a few system files:

The place where they will be searched for depends on the value of the Directory resource, which is a colon (:)-separated search path list, like the UNIX PATH environment variable. The default value is

$HOME/.local/share/vice/EMU:PREFIX/lib/vice/EMU:BOOTPATH/EMU

Where PREFIX is the installation prefix (usually `/usr/local'), EMU is the name of the emulated machine (C64, C64DTV, C128, PET, PLUS4, CBM-II, SCPU64 or VIC20) and BOOTPATH is the directory where the executable resides. The disk drive ROMs are looked for in a directory with EMU set to DRIVES. $HOME is the user's home directory.

For example, if you have the C64 emulator installed in

/usr/local/bin/x64

then the value will be

$HOME/.local/share/vice/C64:/usr/local/lib/vice/C64:/usr/local/bin/C64

And system files will be searched for under the following directories, in the specified order:

  1. $HOME/.local/share/vice/C64
  2. /usr/local/lib/VICE/C64
  3. /usr/local/bin/C64

System files can still be installed in a different directory if you specify a complete path instead of just a file name. For example, if you specify `./kernal' as the kernal image name, the kernal image will be loaded from the current directory. This can be done by using command-line options or by modifying resource values (see section 6.1 Format of resource files).

4.1 ROM files

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

The C128 needs the following files:

The C128, VIC20, SCPU64 and C64 emulators also need the following DOS ROMs for the hardware-level emulation of the 1540, 1541, 1571, 1581, 2000, and 4000 disk drives, as well as the CMD hard drive:

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:

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:

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 128KiB RAM version (C610, C710, B128) uses one bank of 64KiB for the BASIC text and another one for all the variables. The 256KiB 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 larger 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.

The SCPU64 needs the following files:

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

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, these usually appear at the beginning of the file, before any actual keycode definitions; they are recognized because they start with an exclamation mark:

For emulated keyboards that have only one shift key, set both !LSHIFT and !RSHIFT to the same row/col and use RSHIFT for !VSHIFT and !SHIFTL.

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, see section 2.8 The keyboard emulation.

4.3 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

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

While a Romset file is processed, the directory where the Romset file was found is temporarily prepended to the search path (Directory resource). This also means that if you have a setting for Directory in it, its effect is limited to the Romset file itself.

4.4.1 Romset command line options

-romsetfile <File>
load the given romset file
-romsetarchive <File>
load the given romset archive
-romsetarchiveselect <Item number>
select the given item from the current romset archive

4.5 Gtk3 Hotkeys files

The Gtk3 port of VICE allows setting custom keyboard shortcuts, which we refer to as hotkeys. These hotkeys can be set either through the user interface or by editing hotkeys files, which are stored either in the VICE data directory or in the user's VICE configuration directory.

VICE's hotkeys files are read from VICE's data directory, which we'll refer to as $VICEDIR and the (optional) user's hotkeys will be in the user's VICE configuration directory, which we'll refer to as $USERDIR.

On Unix, $VICEDIR will point to /usr/local/share/vice/, when using the default install prefix, and $USERDIR will point to $HOME/.config/vice/. On Windows, $VICEDIR will point to the root directory of the bindist and $USERDIR will point to %APPDATA%\vice, which usually is C:\Users\%USERNAME%\AppData\Roaming\vice.

A custom path can be specified by using the command line interface: x64sc -hotkeyfile <some-file>, or by using the UI (TODO).

4.6 Syntax of the hotkeys files

The syntax of the hotkeys files is pretty straightforward, a file can contain mappings, directives and comments. Leading and trailing whitespace is ignored by the parser.

4.6.1 Comments

Comments are started with either ; or # and occupy the rest of the line, they can also appear inline after a directive or mapping.

For example:

# This is a comment

monitor-open    <Alt>h      # This is an inline comment

4.6.2 Directives

Directives are special commands for the parser. They start with ! and are case-insensitive.

4.6.2.1 !CLEAR

Syntax

!clear

Clear all registered hotkeys. Best used as the first directive in the (main) hotkeys file.

4.6.2.2 !DEBUG

Syntax

!debug <enable|disable|on|off>

Enable or disable debugging messages via VICE's log system. Messages will be prefixed with 'Hotkeys:'. Debugging is disabled by default.

4.6.2.3 !INCLUDE

Syntax

!include <file>

Process <file> as if its contents were injected into the current file being processed. This can be used recursively. The <file> argument can be inside quotes (") to be able to use paths or filenames with spaces in them, and quotes inside quotes can be used by escaping them with \, for example: !include "foo \"bar\".vhk". Special variables As mentioned before, a few special variables exist to use in the argument to the !include directive: $VICEDIR and $USERDIR. These can be used to avoid hardcoded, absolute paths.

For example:

!include "$VICEDIR/common/gtk3-hotkeys-drive.vhk"

will include /usr/local/share/vice/common/gtk3-hotkeys-drive.vhk, assuming the default install prefix for VICE was used.

4.6.2.4 !UNDEF

Syntax

!undef [<modifier>..]<keyname>

Remove a hotkey from whatever action it is mapped to.

For example:

!undef      <Alt>r      # Unmap Alt+r from 'restore display'
reset-soft  <Alt>r      # Map Alt+r to soft reset

4.6.3 Hotkey mappings

4.6.3.1 Syntax

<action-name>   [<modifier>...]<keyname>

Create a mapping of a hotkey to an action, where <action-name> is a string refering to an operation triggered by a menu item -- such as toggling Warp Mode, or attaching a disk to a drive -- followed by a keyname, optionally prefixed with one or more modifiers.

For example:

monitor-open    <Alt>m
settings-open   KP_Divide       # map '/' on the keypad to the settings dialog
edit-paste      <Control><Alt>Insert

The key names are case-sensitive and map directly to the symbolic constants GDK uses, but without the leading GDK_KEY_ component. In the above example the string 'Insert' would map to GDK_KEY_Insert.

For a list of available symbolic key names, see the gdkkeysyms.h header of the GDK development headers. On a Debian system the file is located at /usr/include/gtk-3.0/gdk/gdkkeysyms.h. It can also be viewed online at https://gitlab.gnome.org/GNOME/gtk/blob/master/gdk/gdkkeysyms.h

4.6.4 List of modifiers

Windows/Unix @tab MacOS @tab GDK symbolic constant <Alt> @tab <Option> @tab GDK_MOD1_MASK<Control> @tab <Command> @tab GDK_CONTROL_MASK<Hyper> @tab GDK_HYPER_MASK<Shift> @tab <Shift> @tab GDK_SHIFT_MASK<Super> @tab <Super> @tab GDK_SUPER_MASK

Please be aware that some modifier+key combinations are either mapped to the emulated machine's keyboard -- such as <Control>1 being mapped to CBM+1 when using a positional keymap -- or to the operating system/window manager. Mappings using <Alt> or <Alt><Shift> are usually fine.

4.6.5 List of action names

@tab description advance-frame @tab Advance emulation one frame cart-attach @tab Attach cartridge cart-detach @tab Detach cartridge cart-freeze @tab Press cartridge freeze button debug-autoplayback-frames @tab Set autoplayback frames debug-core-dump-toggle @tab Toggle saving core dump debug-trace-cpu-toggle @tab Toggle CPU trace debug-trace-drive-10-toggle @tab Toggle Drive 10 CPU trace debug-trace-drive-11-toggle @tab Toggle Drive 11 CPU trace debug-trace-drive-8-toggle @tab Toggle Drive 8 CPU trace debug-trace-drive-9-toggle @tab Toggle Drive 9 CPU trace debug-trace-iec-toggle @tab Toggle IEC bus trace drive-attach-8:1 @tab Attach disk to unit 8, drive 1 drive-attach-9:0 @tab Attach disk to unit 9, drive 0 drive-attach-9:1 @tab Attach disk to unit 9, drive 1 drive-create @tab Create and attach empty disk image drive-detach-10:0 @tab Detach disk from unit 10, drive 0 drive-detach-10:1 @tab Detach disk from unit 10, drive 1 drive-detach-11:0 @tab Detach disk from unit 11, drive 0 drive-detach-11:1 @tab Detach disk from unit 11, drive 1 drive-detach-8:0 @tab Detach disk from unit 8, drive 0 drive-detach-8:1 @tab Detach disk from unit 8, drive 1 drive-detach-9:0 @tab Detach disk from unit 9, drive 0 drive-detach-9:1 @tab Detach disk from unit 9, drive 1 drive-detach-all @tab Detach all disks edit-copy @tab Copy screen content to clipboard edit-paste @tab Paste clipboard content into machine fliplist-add @tab Add current disk to fliplist fliplist-clear @tab Clear fliplist fliplist-load @tab Load fliplist fliplist-next @tab Attach next disk in fliplist fliplist-previous @tab Attach previous disk in fliplist fliplist-remove @tab Remove current disk from fliplist fliplist-save @tab Save fliplist fullscreen-decorations-toggle @tab Show menu/status in fullscreen fullscreen-toggle @tab Toggle fullscreen help-about @tab Show about dialog help-command-line @tab Command line options help-compile-time @tab Compile time features help-hotkeys @tab Hotkeys help-manual @tab Browse VICE manual history-milestone-reset @tab Return to recording milestone history-milestone-set @tab Set recording milestone history-playback-start @tab Start playing back events history-playback-stop @tab Stop playing back events history-record-start @tab Start recording events history-record-stop @tab Stop recording events keyset-joystick-enable @tab Allow keyset joystick media-record @tab Record media media-stop @tab Stop media recording monitor-open @tab Open monitor mouse-grab-toggle @tab Toggle Mouse Grab pause-toggle @tab Toggle Pause quit @tab Quit emulator reset-drive-10 @tab Reset drive 10 reset-drive-11 @tab Reset drive 11 reset-drive-8 @tab Reset drive 8 reset-drive-9 @tab Reset drive 9 reset-hard @tab Hard reset the machine reset-soft @tab Soft reset the machine restore-display @tab Resize application window to fit contents screenshot-quicksave @tab Save screenshot in current working directory settings-default @tab Restore default settings settings-dialog @tab Open settings dialog settings-load @tab Load settings settings-load-extra @tab Load additional settings settings-load-from @tab Load settings from alternate file settings-save @tab Save settings settings-save-to @tab Save settings to alternate file smart-attach @tab Attach a medium to the emulator inspecting its type snapshot-load @tab Load snapshot file snapshot-quickload @tab Quickload snapshot snapshot-quicksave @tab Quicksave snapshot snapshot-save @tab Save snapshot file swap-controlport-toggle @tab Swap controlport joysticks tape-attach-1 @tab Attach tape to datasette 1 tape-attach-2 @tab Attach tape to datasette 2 tape-create-1 @tab Create tape and attach to datasette 1 tape-create-2 @tab Create tape and attach to datasette 2 tape-detach-1 @tab Detach tape from datasette 1 tape-detach-2 @tab Detach tape from datasette 2 tape-ffwd-1 @tab Press FFWD on datasette 1 tape-ffwd-2 @tab Press FFWD on datasette 2 tape-play-1 @tab Press PLAY on datasette 1 tape-play-2 @tab Press PLAY on datasette 2 tape-record-1 @tab Press RECORD on datasette 1 tape-record-2 @tab Press RECORD on datasette 2 tape-reset-1 @tab Reset datasette 1 tape-reset-1 @tab Reset datasette 2 tape-reset-counter-1 @tab Reset datasette 1 counter tape-reset-counter-2 @tab Reset datasette 2 counter tape-rewind-1 @tab Press REWIND on datasette 1 tape-rewind-2 @tab Press REWIND on datasette 2 tape-stop-1 @tab Press STOP on datasette 1 tape-stop-2 @tab Press STOP on datasette 2 warp-mode-toggle @tab Toggle Warp Mode
name

To see which emulators support which actions please look at doc/gtk3-hotkeys.md or src/arch/gtk3/uiactions.h.

4.6.6 Syntax highlighting

Vim syntax highlighting files can be found in doc/vim/. Currently there are two files: syntax/vhk.vim and ftdetect/vhk.vim, these can be copied to $VIMFILES/ to enable hotkeys syntax highlighting in Vim.


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