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

2 About VICE

VICE is the one and only Versatile Commodore Emulator. It provides emulation of the Commodore C64, C64DTV, C128, VIC20, PET, PLUS4, SCPU64 and CBM-II computers within a single package. The emulators run as separate programs, but have the same user interface, share the same settings and support the same file formats.

Important notice: If you have no idea what a Commodore 8-bit computer is, or have questions about how these machines are used, how the file formats work or anything else that is not strictly related to VICE, you should read the appropriate FAQs first, as that kind of information is not available here. See section 20 Contact information. for information about how to retrieve the FAQs.

All the emulators provide an accurate 6502/6510 emulator, with emulation of all the opcodes (both documented and undocumented ones) and accurate timing. Unlike other emulators, VICE aims to be cycle accurate; it tries to emulate chip timings as precisely as possible and does so efficiently.

Please do not expect the C64DTV, C128, PET, PLUS4, SCPU64 and CBM-II emulators to be as good as the C64 or VIC20 one, as they are still under construction.

Notice: This documentation is written for the Unix release of VICE, but is slowly being made universal.

2.1 C64 emulator features

As of version 2.3, two C64 emulators are provided: `x64' (fast) and `x64sc' (accurate). As of version 3.4 `x64' will no more get built by default and is not contained in the default binary packages.

The fast C64 emulator, called `x64', features a fairly complete emulation of the VIC-II video chip: sprites, all registers and all video modes are fully emulated. The emulation has been fully cycle-accurate since version 0.13.0.

The accurate C64 emulator, called `x64sc', features a cycle-based and pixel-accurate VIC-II emulation. This requires a much faster machine than the old `x64'.

A rather complete emulation of the SID sound chip is also provided. All the basic features are implemented as well as most of the complex ones including synchronisation, ring modulation and filters. There are two emulators of the SID chip available: first is the "standard" VICE emulator, available since VICE 0.12; the second is Dag Lem's reSID engine. The reSID engine is a lot more accurate than the standard engine, but it is also a lot slower, and only suitable for faster machines.

Naturally, also both CIAs (or VIAs, in some cases) are fully emulated and cycle accurate.

2.2 C64DTV emulator features

The C64DTV emulator, called `x64dtv', features emulation of C64DTV revisions 2 and 3. The emulator is under construction, but most of the DTV specific features are already supported (with varying accuracy).

Video cache is disabled by default as it currently doesn't work with some of C64DTV's new video modes. The new video modes have a simple "fake" video cache implementation that may give incorrect results and decreased performance.

2.3 C128 emulator features

The C128 emulator, called `x128', features a complete emulation of the internal MMU (Memory Management Unit), 80 column VDC screen, fast IEC bus emulation, 2 MHz mode, Z80 emulation plus all the features of the C64 emulation.

2.4 VIC20 emulator features

The VIC20 emulates all the internal hardware, including the VIA chips. The VIC-I video chip is fully emulated except NTSC interlace mode, so most graphical effects will work correctly.

The VIC20 emulator allows the use of the VIC1112 IEEE488 interface. You have to enable the hardware (by menu, resource, or commandline option) and then load the IEEE488 ROM (see for example http://www.funet.fi/pub/cbm/schematics/cartridges/vic20/ieee-488/325329-04.bin, but you have to double the size to 4k for now). The IEEE-488 code is then started by SYS45065.

2.5 PET emulator features

The PET emulator emulates the 2001, 3032, 4032, 8032, 8096, 8296 and SuperPET (MicroMainFrame 9000) models, covering the whole series. The hardware is pretty much the same in each and that is why one single program is enough to emulate all of them. For more detailed information about PET hardware please refer to the `PETdoc' file.

Both the 40 column and 80 column CRTC video chips are emulated (from the 4032 onward), but a few of the features are not implemented yet (numbers of rasterlines per char and lines per screen). Fortunately, they are not very important for average applications.

The PET 8096 is basically a PET 8032 with a 64k extension board which allows remapping the upper 32k with RAM. You have to write to a special register at $fff0 to remap the memory. The PET 8296 is a 8096 but with a completely redesigned motherboard with 128k RAM in total. Of the additional 32k RAM you can use only some in blocks of 4k, but you have to set jumpers on the motherboard for it. VICE uses the command line options `-petram9' and `-petramA' instead. Also, the video controller can handle a larger address range. The PET 8x96 model emulations run the Commodore LOS-96 operating system - basically an improved BASIC 4 version with up to 32k for BASIC text and 32k for variables. See `PETdoc' for more information.

The PET 8296D is an 8296 with built-in 8250 low-profile dual disk drive.

The PET 8296GD is an 8296D with additionally a "HiRes Emulator" (HRE). This is a cheaper version of a "HRG" hi-res board which was based on Thomson chips. This version instead uses no additional hardware support apart from some memory mapping tricks. It has supporting software in the hre-*.bin rom files.

The SuperPET also is a PET 8032 with an expansion board. It can map 4k at a time out of 64k into the $9*** area. Also it has an ACIA 6551 for RS232 communication. The 6809 CPU that is built into the SuperPET is now emulated, since release 2.4, including the 6702 dongle chip.

The Super-OS-9 MMU expansion, developed by TPUG (Toronto PET Users Group) is also emulated.

The PET computers came with three major ROM revisions, so-called BASIC 1, 2 and 4, all of which are provided. The PET 2001 uses the version 1, the PET 3032 uses version 2, and the others use version 4. The 2001 ROM is horribly broken with respect to IEEE488 (they shipped it before they tested it with the floppy drive, so only tape worked. Therefore the emulator patches the ROM to fix the IEEE488 routines.

As well as other low-level fixes the 2001 patch obtains the load address for a program file from the first two bytes of the file. This allows the loading of both PET2001-saved files (that have $0400 as their load address) and other PET files (that have $0401). The PET2001 saves from $0400 and not from $0401 as other PETs do.

Moreover, the secondary addresses used are now 0 and 1 for load and save, respectively, and not arbitrary unused secondary addresses.

To select which model to run, specify it on the command line with the -model MODEL option, where MODEL can be one of a list of PET model numbers, all described in see section 7.7.1 Changing PET model settings

2.6 CBM-II emulator features

The CBM-II emulator emulates several types of CBM-II models. Those models are known under different names in the USA and Europe. In the States they have been sold as B128 and B256, in Europe as CBM 610, CBM 620 (low-profile case) or CBM 710 and CBM 720 (high-profile case with monitor). In addition to that now an experimental C510 emulation is included. The C510 (also known as P500) is the little brother of the C600/700 machines. It runs at roughly 1 MHz and, surprise, it has a VIC-II instead of the CRTC. Otherwise the different line of computers are very similar.

These computers are prepared to take a coprocessor board with an 8088 or Z80 CPU. Indeed there are models CBM 630 and CBM 730 that supposedly had those processors. However these models are not emulated.

The basic difference is the amount of RAM these machines have been supplied with. The B128 and the CBM *10 models had 128k RAM, the others 256k. This implies some banking scheme, as the 6502 can only address 64k. And indeed those machines use a 6509, that can address 1 MByte of RAM. It has 2 registers at addresses 0 and 1. The indirect bank register at address 1 determines the bank (0-15) where the opcodes LDA (zp),Y and STA (zp),Y take the data from. The exec bank register at address 0 determines the bank where all other read and write addresses take place.

The business line machines (C6xx/7xx) have the RAM in banks 1-2, resp. 1-4. All available banks are used for BASIC, where program code is separated from all variables, resp. from normal variables, strings and arrays that are distributed over other banks. The C510 instead has RAM in banks 0 and 1, and uses bank 1 for program and all variables. Bank 0, though, can be accessed by the VIC-II to display graphics.

Many models have been expanded to more than the built-in memory. In fact some machines have been expanded to the full 1M. Bank 15 is used as system bank, with only little RAM, and lots of expansion cartridge ROM area, the I/O and the kernal/basic ROMs. Some models have been modified to map RAM into the expansion ROM area. Those modifications can be emulated as well.

The different settings are described in see section 7.8.1 Changing CBM-II model.

2.7 SCPU64 emulator features

The XSCPU64 emulator is a simulation of a C64 equipped with a SuperCPU64 V2B. Features:

Still to do:

The emulation is quite accurate but not perfect. If you code something timing intensive using this simulation please always check it on real hardware to avoid bad surprises.

The hardware itself is asynchronous in nature, therefore caution must be taken to not do long timing loops without synchronization in 20 MHz mode. Also don't squeeze out the last remaining cycles without leaving a safety buffer. Synchronization points can be created by doing I/O reads or writes and leaving a few hundred cycles left each frame will not hurt.

Otherwise it can happen that the code is running on this version of VICE or my SCPU64 V2+C128D perfectly but nowhere else due to manufacturing variations and frequency drifts.

2.8 The keyboard emulation

There are two ways of emulating the keyboard in VICE.

The default way (symbolic mapping) is to map every key combination to the corresponding key combination on the real machine: for example, if you press *, which is bound to Shift-8 on a U.S. keyboard, in the C64 emulator, the emulated machine will have just the unshifted * key pressed (as * is unshifted on the C64 keyboard). Likewise, pressing ' on the same U.S. keyboard without any shift key will cause the combination Shift-7 to be pressed in the emulated C64. This way, it becomes quite obvious what keys should be typed to obtain all the symbols. The key printed on the host keyboard will be pressed in the emulator.

There is, however, one problem with symbolic mapping: some keys really need to be mapped specially regardless (those that do not exist on a PC keyboard). Some examples are the Commodore key, RUN/STOP, Clear/Home. The exact mapping depends on your host layout, but should be easy to find out by try and error :) If in doubt, you can read the keyboard mapping files.

The second way (positional mapping) is to map every key on the host keyboard to the key which has the same position on the keyboard of the emulated machine. This way the keyboard is more comfortable to use in those programs (such as some games) that require the keys to be in the correct positions. On the other hand it can be quite confusing if you are not very familiar with the original emulated keyboards. Also not all keys can be mapped exactly this way either, which means some of them still need to be mapped to other keys (see above).

Warning: unlike the real C64, VICE "presses" the Shift key together with the key to shift when the Shift must be forced. In most cases this should work fine, but some keyboard routines are quite picky and tend not to recognize the shift key because of this. For instance, F6 (which on the real C64 is obtained with Shift + F5) could be recognized as F5. In that case, use the shift key manually (i.e., type Shift + F5 in the example). Yes, we know this is a bug.

We depend a lot on your support to improve the keyboard maps, as we can not test all emulators in all possible configurations and using all host keyboard mappings. Please report any problems to us so we can fix them!

If you experience problems with 'accent' keys such as acute, grave, tilde, circumflex, diaresis (and possibly more/other, depending on your host keyboard layout) try switching to a "no deadkeys" layout in your OS. In any case, please also report these problems so we can fix them!

To find out the keycodes to use, incase you want to edit the keymaps yourself, you can enable showing the keycodes in the status bar in the settings.

2.9 The joystick emulation

Joysticks can be emulated both via the keyboard and via a real joystick connected to the host machine.

There are two keyboard layouts for joystick use, known as numpad and custom.

The numpad layout uses the numeric keypad keys, i.e., the numbers 1...9 which emulate all the directions including the diagonal ones; 0 emulates the fire button.

The custom layout is configurable to your liking.

2.10 The disk drive emulation

All the emulators support up to 4 external disk drives as devices 8, 9, 10 and 11. Each of these devices can emulate virtual Commodore 1541, 1541-II, 1571, 1581, 2031, 2040, 3040, 4040, 1001, 8050 and 8250 drives in one of the following ways:

When using disk images there are two available types of drive emulation. One of them the virtual drive emulation. It does not really emulate the serial line, but patches the kernal ROM (with the so-called kernal traps) so that serial line operations can be emulated via C language routines. This emulation is very fast, but only allows use of standard DOS functions (and not even all of them). For real device access it is required to enable this type of emulation.

The IEEE488 drives (2031, 2040, 3040, 4040, 1001, 8050 and 8250) do not use kernal traps. Instead the IEEE488 interface lines are monitored and the data is passed to the drive emulation. To use them on the C64, you need to enable the IEEE488 interface emulation. Only if the IEEE488 emulation is enabled, those drives can be selected.

The other alternative is a true drive emulation. The Commodore disk drives are provided with their own CPU (a 6502 as the VIC20 and the PETs) and their own RAM and ROM. So, in order to more closely emulate its features, a complete emulation of this hardware must be provided and that is what the hardware level emulation does. When the hardware level emulation is used, the kernal routines remain unpatched and the serial line is fully emulated. The problem with this emulation is that it needs a lot of processing power, mainly because the emulator has to emulate two CPUs instead of one.

The PETs do not use a serial IEC bus to communicate with the floppy drive but instead use the parallel IEEE488 bus. This does byte by byte transfers, as opposed to the bit by bit transfers of the C64 and VIC20, so making it feasible to emulate the parallel line completely while emulating the drive at DOS level only. The IEEE488 line interpreter maps the drives 8-11 (as described above) to the IEEE488 disk units, and no kernal traps are needed. The same emulation of the Commodore IEEE488 bus interface is available for the C64 and the VIC20. With IEEE488 drives you can have true 2031 emulation at unit #8, and still have filesystem access at units #10 or #11, because monitoring the IEEE488 lines does not interfere with the true drive emulation.

The IEEE488 disk drives 2040, 3040, 4040, 8050 and 8250 are Dual Drive Floppy Disks. This means that these drives handle two disks. To accomplish the emulation, only two disks can be emulated, namely units #8 and #10. The attached image, track display and LED display of unit #9 and #11 are used for the second drive of the dual disk drives. On unix the unit number display (8 or 9, 10 or 11) in the emulation window changes to the drive number display (0 or 1).

The Commodore 2040, 3040, 4040, 1001, 8050 and 8250 disk drives are so-called "old-style" disk drives. Their architecture includes not one, but two processors of the 6502 type, namely a 6502 for the file handling and communication with the PET (IP), and a 6504 (which is a 6502 with reduced address space) for the drive handling (FDC). Both processors communicate over a shared memory area. The IP writes commands to read/write blocks to this area and the FDC executes them. To make the emulation feasible, the FDC processor is not emulated cycle-exactly as a 6504, but simply by checking the commands and executing them on the host. This provides a fast FDC emulation, but disallows the sending the FDC processor commands to execute code. Applications where this is necessary are believed to be rather seldom. Only the format command uses this feature, but this is checked for.

The dual disk drive 2040 emulates one of the very first CBM disk drives. This drive has DOS version 1. DOS1 uses an own disk type, that is closely related to the 1541 disk image. Only on tracks 18-24 DOS1 disks have a sector more than 1541 disks. DOS1 disk images have the extension .d67.

The dual disk drives 3040 and 4040 use the same logical disk format as the VC1541 and the 2031. In fact, the 4040 was the first disk with DOS version 2. The 3040 emulated here originally was the same as 2040, only for the european 30xx PET series. As many of the original DOS1 disk drives were upgraded (a simple ROM upgrade!) to DOS2, I use the 3040 number for a DOS 2.0 disk drive, and 4040 for a revised DOS 2 disk drive. It is, however, not yet clear whether the disks here are write compatible to the 1541, as rumors exist that the write gap between sectors is different. But read compatible they are. As VICE emulates the FDC processor in C and not as 6504 emulation, this does not matter in VICE.

The drives 1001, 8050 and 8250 do actually have the very same DOS ROM. Only the code in the FDC is different, which is taken care of by VICE. So for all three of those disk drives, only dos1001 is needed. The DOS version used is 2.7.

2.11 Supported file formats

VICE supports the most popular Commodore file formats:

A utility (c1541, see section 14 c1541) is provided to allow transfers and conversions between these formats.

Notice that the use of the X64 file format is deprecated now.

You can convert an X64 file back into a D64 file with the UNIX dd command:

dd bs=64 skip=1 if=IMAGE.X64 of=IMAGE.D64

See section 17 The emulator file formats. for a technical description of the supported file formats.

2.12 Common problems

This section tries to describe the most common known problems with VICE, and how to resolve them.

2.12.1 Sound problems

VICE should compile and run without major problems on many systems, but there are some known issues related to the sound driver.

If you are having sound problems, such as skipping, first monitor how much CPU time the respective emulator is taking on your system. To run smoothly, on a modern system, it should really never go over 50% or so, except for very short peaks that should also stay well beyond 90%. If you see it takes more, try disabling some of the most CPU intense features (disable CRT emulation, use fastsid instead of reSID, disable true drive emulation).

If the CPU usage is ok, try using a different sound driver. You may also try increasing the sound buffer size (although the default should be ok for modern systems).

All platforms that can run the SDL port (like Amiga, BeOS, etc) should be able to play sound via SDL.

2.12.2 Video problems

Due to the way VICE currently handles its main loop, a common problem with video sync occurs when the real (the monitors) frame rate is very close to, equal, or lower than the framerate of the emulated machine. We recommend to use a framerate which is slightly higher than that (eg 51Hz for the C64).

2.12.3 Printer problems

VICE supports the emulation of a printer either on the userport or as IEC device 4. Unfortunately the Commodore IEC routines do not send all commands to the IEC bus. For example an OPEN 1,4 is not seen on the IEC bus. Also a CLOSE 1 after that is not seen. VICE can see from printing that there was an OPEN, but it cannot see when the close was. Also a "finish print job" cannot be seen on the userport device. To flush the printer buffer (write to print.dump or to the printer) now a menu entry can be used. Disabling and re-enabling the printer should work as well.

The printing services have not been extensively tested but apart from the problem mentioned above it should work fine now.

2.12.4 PET keyboard problems

If you find that the German keyboard mapping (plus German charset) does not print uppercase umlauts, then you are right. The umlauts replace the [,\ and ] characters in the charset. The keys that make these characters do not have a different entry in the PET editor ROM tables when shifted. Thus it is not possible to get the uppercase umlauts in the editor. Nevertheless other programs are reported to change the keyboard mapping table and thus allow the use of the shifted (uppercase) umlauts.

Anyway, the VICE keyboard mappings are far from being perfect and we are open to any suggestions.

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