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
PREFIX/lib/vice/EMU:$HOME/.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
/usr/local/lib/vice/C64:$HOME/.vice/C64:/usr/local/bin/C64
And system files will be searched for under the following directories, in the specified order:
/usr/local/lib/VICE/C64
$HOME/.vice/C64
/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).
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:
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:
SYS 36864
.
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 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:
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:
KEYSYM
is a string (GTK) or number (SDL) identifying the keysym: you can
use the "show keycodes in statusbar" feature 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.
16
: deshift key for this keysym/scancode
32
: another definition for this keysym/scancode follows
64
: key is shift-lock on emulated machine
128
: shift modifier required on host
256
: key is used for an alternative keyboard mapping
512
: alt-r (alt-gr) modifier required on host
1024
: ctrl modifier required on host
2048
: key is combined with cbm for this keysym/scancode
4096
: key is combined with ctrl for this keysym/scancode
8192
: key is (left) cbm on emulated machine
16384
: key is (left) ctrl on emulated machine
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;
!INCLUDE
followed by "filename" reads (inserts) file as mapping file. This is useful
when adding local mappings to an otherwise generic file (so you dont have to
copy the while file, but just add/modify a few keys).
!UNDEF
keysym' remove keysym from table
!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
!LCTRL
, followed by a row and a column value, specifiy where the left
control key is located on the emulated keyboard.
!LCBM
, followed by a row and a column value, specifiy where the left
CBM key is located on the emulated keyboard.
!VSHIFT
, followed by a shiftkey (RSHIFT or LSHIFT), specify what key will
be used as a virtual shift key when the shift flag is set.
!SHIFTL
, followed by a shiftkey (RSHIFT or LSHIFT), specify what key will
be used as a virtual shift-lock key.
!VCTRL
, followed by a ctrlkey (LCTRL), specify what key will
be used as a virtual control key.
!VCBM
, followed by a cbmkey (LCBM), specify what key will
be used as a virtual CBM key.
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.
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
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.
-romsetfile <File>
-romsetarchive <File>
-romsetarchiveselect <Item number>
Go to the first, previous, next, last section, table of contents.