<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from ../vice.texi on 30 January 2000 -->

<TITLE>VICE Manual - 2  About VICE</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff" TEXT="#00000">
Go to the <A HREF="vice_1.html">first</A>, <A HREF="vice_1.html">previous</A>, <A HREF="vice_3.html">next</A>, <A HREF="vice_16.html">last</A> section, <A HREF="vice_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC5" HREF="vice_toc.html#TOC5">2  About VICE</A></H1>

<P>
VICE is the one and only <EM>Versatile Commodore Emulator</EM>.  It provides
emulation of the Commodore 64, 128, VIC20 and PET 8-bit 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.

</P>
<P>
<STRONG>Important notice:</STRONG> 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 <EM>first</EM>, as
that kind of information is not available here.  See section <A HREF="vice_14.html#SEC159">14  Contact information</A> for
information about how to retrieve the FAQs.

</P>
<P>
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 <EM>efficiently</EM>.

</P>
<P>
Please do <EM>not</EM> expect the VIC20, C128 and PET emulators to be as
good as the C64 one, as they are still under construction.

</P>



<H2><A NAME="SEC6" HREF="vice_toc.html#TOC6">2.1  C64 emulator features</A></H2>

<P>
The C64 emulator, called <SAMP>`x64'</SAMP>, 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.

</P>
<P>
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: one is the "standard" VICE
emulator, available since VICE 0.12; the other one 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.

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

</P>



<H2><A NAME="SEC7" HREF="vice_toc.html#TOC7">2.2  C128 emulator features</A></H2>

<P>
The C128 emulator, called <SAMP>`x128'</SAMP>, features a complete emulation of
the internal MMU (<EM>Memory Management Unit</EM>), plus all the features
of the C64 emulation.  The following things are missing, though:

</P>

<P> <UL>
<P> <LI>

80-column VDC chip;
<P> <LI>

2 MHz mode;
<P> <LI>

C64 mode.
</UL> </P>



<H2><A NAME="SEC8" HREF="vice_toc.html#TOC8">2.3  VIC20 emulator features</A></H2>

<P>
The VIC20 emulates all the internal hardware, including the VIA chips.
The VIC-I video chip is only partially emulated, so some
graphical effects will not work correctly.

</P>
<P>
Sound support is implemented, but is still at an experimental stage.  If
you think it could be improved and know how to do so, feel
free to contact us (see section <A HREF="vice_14.html#SEC159">14  Contact information</A>).

</P>
<P>
The VIC20 emulator now 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 <CODE>http://www.funet.fi/pub/cbm/schematics/cartridges/vic20/ieee-488/325329-04.bin</CODE>, but you have to double the size to 4k for now).
The IEEE-488 code is then started by <CODE>SYS45065</CODE>.

</P>



<H2><A NAME="SEC9" HREF="vice_toc.html#TOC9">2.4  PET emulator features</A></H2>

<P>
The PET emulator emulates the 2001, 3032, 4032, 8032, 8096, 8296 and
SuperPET (MicroMainFrame 9000) models, covering practically 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 <TT>`PETdoc'</TT> file.

</P>
<P>
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.

</P>
<P>
Sound is available for the PET as well, but like the VIC20's it is still
under construction.

</P>
<P>
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 <CODE>$fff0</CODE> 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 <SAMP>`-petram9'</SAMP> and <SAMP>`-petramA'</SAMP>
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 <TT>`PETdoc'</TT> for more information.

</P>
<P>
The SuperPET also is a PET 8032 with an expansion board.  It can map 4k
at a time out of 64k into the <CODE>$9***</CODE> area.  Also it has an ACIA
6551 for RS232 communication.  The 6809 that is built into the SuperPET
is not emulated, though.

</P>
<P>
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.

</P>
<P>
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.

</P>
<P>
Moreover, the secondary addresses used are now <CODE>0</CODE> and <CODE>1</CODE> for
load and save, respectively, and not arbitrary unused secondary
addresses.

</P>
<P>
To select which model to run, specify it on the
command line with the <CODE>-model MODEL</CODE> option, where
<CODE>MODEL</CODE> can be one of a list of PET model numbers, all
described in see section <A HREF="vice_7.html#SEC98">7.3.1  Changing PET model settings</A>

</P>



<H2><A NAME="SEC10" HREF="vice_toc.html#TOC10">2.5  CBM-II emulator features</A></H2>

<P>
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 <CODE>B128</CODE> and <CODE>B256</CODE>, in Europe as
<CODE>CBM 610</CODE>, <CODE>CBM 620</CODE> (low-profile case) or <CODE>CBM 710</CODE> and
<CODE>CBM 720</CODE> (high-profile case with monitor).

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

</P>
<P>
The basic difference is the amount of RAM these machines have been
supplied with.  The <CODE>B128</CODE> and the <CODE>CBM *10</CODE> 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 <CODE>LDA (zp),Y</CODE> and <CODE>STA (zp),Y</CODE> take the data from.  The
exec bank register at address 0 determines the bank where all other read
and write addresses take place.

</P>
<P>
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.

</P>
<P>
The different settings are described in see section <A HREF="vice_7.html#SEC103">7.4.1  Changing CBM-II model</A>.

</P>


<H2><A NAME="SEC11" HREF="vice_toc.html#TOC11">2.6  The keyboard emulation</A></H2>

<P>
There are two ways of emulating the keyboard in VICE.

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

</P>
<P>
There is, however, one problem with symbolic mapping: some keys really
need to be mapped specially regardless.  The most important examples
being, in the VIC20, C64 and C128 emulators, that <KBD>CTRL</KBD> is mapped
to <KBD>Tab</KBD> and that the <KBD>Commodore</KBD> key is mapped to the left
<KBD>Control</KBD>). The <KBD>RUN/STOP</KBD> key is mapped to the <KBD>ESC</KBD> key
on the PC keyboard. The PET emulator, lacking the <KBD>Commodore</KBD> key
but having an <KBD>ESC</KBD> key, uses the left <KBD>Control</KBD> key as
<KBD>RUN/STOP</KBD> and the <KBD>ESC</KBD> key as <KBD>ESC</KBD> of course.

</P>

<P>
The second way (<EM>positional mapping</EM>) is to map every key on the
"real" keyboard to the key which has the same position on the keyboard
of the emulated machine.  This way, no <KBD>Shift</KBD> key is forced by the
program (with the exception of the function keys <KBD>F2</KBD>, <KBD>F4</KBD>,
<KBD>F6</KBD> and <KBD>F8</KBD>, which require <KBD>Shift</KBD> on the Commodore
keyboards), and the keyboard is more comfortable to use in those
programs (such as some games) that require the keys to be in the correct
positions.

</P>
<P>
<STRONG>Warning:</STRONG> unlike the real C64, VICE "presses" the <KBD>Shift</KBD>
key <EM>together</EM> with the key to shift when the <KBD>Shift</KBD> 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, <KBD>F6</KBD> (which on the real C64 is obtained with
<KBD>Shift + F5</KBD>) could be recognized as <KBD>F5</KBD>.  In that case, use
the shift key manually (i.e., type <KBD>Shift + F5</KBD> in the example).
Yes, we know this is a bug.

</P>
<P>
The <KBD>RESTORE</KBD> key is mapped to <KBD>Page Up</KBD> (or <KBD>Prev</KBD>) by
default.

</P>



<H2><A NAME="SEC12" HREF="vice_toc.html#TOC12">2.7  The joystick emulation</A></H2>

<P>
Joysticks can be emulated both via the keyboard and via a real joystick
connected to the host machine (the latter only works on GNU/Linux
systems).

</P>
<P>
There are two keyboard layouts for joystick use, known as <EM>numpad</EM>
and <EM>custom</EM>.

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

</P>
<P>
The <EM>custom</EM> layout uses the keys <KBD>w</KBD>, <KBD>e</KBD>, <KBD>r</KBD>,
<KBD>s</KBD>, <KBD>d</KBD>, <KBD>f</KBD>, <KBD>x</KBD>, <KBD>c</KBD>, <KBD>v</KBD> for the directions
and <KBD>space</KBD> for the fire button instead.

</P>



<H2><A NAME="SEC13" HREF="vice_toc.html#TOC13">2.8  The disk drive emulation</A></H2>

<P>
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, 3040, 4040, 1001, 8050 and 
8250 drives in one of two ways:

</P>

<P> <UL>
<P> <LI>

using disk images, i.e., files that contain a dump
of all the blocks contained in a real floppy disk (if you want more
information about what a disk image is, consult the
<CODE>comp.emulators.cbm</CODE> FAQ);
<P> <LI>

accessing file system directories, thus giving you the use of files
without having to copy them to disk images; this also allows you to
read and write files in the <CODE>P00</CODE> format (again, consult the
<CODE>comp.emulators.cbm</CODE> FAQ for more info).
</UL> </P>

<P>
When using disk images there are two available types of drive
emulation.  One of them the <EM>DOS level</EM> drive emulation.  It
does <EM>not</EM> really emulate the serial line, but patches the kernal
ROM (with the so-called <EM>kernal traps</EM>) 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). The IEEE488 drives (2031, 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.

</P>
<P>
The other alternative is a <EM>hardware level</EM> 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 <EM>hardware level</EM> emulation does.
When the <EM>hardware level</EM> emulation is used, the kernal routines are
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.

</P>
<P>
As of 0.14.0 the <EM>hardware level</EM> emulation is available on all
emulators.  It can only be used to emulate drive unit #8 or #9.  Other
units are disabled if <EM>hardware level</EM> drive emulation is enabled.

</P>
<P>
The PETs do not use a serial IEC bus to communicate with the
floppy drive but instead use the parallel IEEE488 bus.  This does
<EM>byte by byte</EM> transfers, as opposed to the <EM>bit by bit</EM>
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.

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

</P>
<P>
The Commodore 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.

</P>
<P>
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. It is, however, not yet clear whether those disks
are write compatible, 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.

</P>
<P>
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 <CODE>dos1001</CODE> is needed.

</P>


<H2><A NAME="SEC14" HREF="vice_toc.html#TOC14">2.9  Supported file formats</A></H2>

<P>
VICE supports the most popular Commodore file formats:

</P>

<P> <UL>

<P> <LI>

<CODE>X64</CODE> (preferred) or <CODE>D64</CODE> disk image files; Used by the 1541, 2031, 3040, 4040 drives.

<P> <LI>

<CODE>G64</CODE> GCR-encoded 1541 disk image files;

<P> <LI>

<CODE>D71</CODE> VC1571 disk image format

<P> <LI>

<CODE>D81</CODE> VC1581 disk image format

<P> <LI>

<CODE>D80</CODE> CBM8050 disk image format

<P> <LI>

<CODE>D82</CODE> CBM8250/1001 disk image format

<P> <LI>

<CODE>T64</CODE> tape image files (read-only);

<P> <LI>

<CODE>P00</CODE> program files;

</UL> </P>

<P>
An utility (<CODE>c1541</CODE>, see section <A HREF="vice_10.html#SEC146">10  c1541</A>) is provided to allow transfers
and conversions between these formats.

</P>
<P>
Notice that the native format for disk images is <CODE>X64</CODE>; this
means that, although the emulators and utilities can both read and write
on <CODE>D64</CODE> disk images, they never produce <CODE>D64</CODE> files.

</P>
<P>
<A NAME="IDX1"></A>
You can convert an <CODE>X64</CODE> file back into a <CODE>D64</CODE> file with the
UNIX <CODE>dd</CODE> command:

</P>

<PRE>
dd bs=64 skip=1 if=IMAGE.X64 of=IMAGE.D64
</PRE>

<P>
See section <A HREF="vice_11.html#SEC151">11  The emulator file formats</A> for a technical description of the supported file
formats.

</P>


<H2><A NAME="SEC15" HREF="vice_toc.html#TOC15">2.10  Common problems</A></H2>

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

</P>



<H3><A NAME="SEC16" HREF="vice_toc.html#TOC16">2.10.1  Sound problems</A></H3>

<P>
VICE should compile and run without major problems on many UNIX systems,
but there are some known issues related to the sound driver.  In fact,
the sound code is the least portable part of the emulator and has not
yet been thoroughly tested on all the supported platforms.

</P>
<P>
Linux, AIX and SGI systems should play sound without any problems; if
you are running Linux please use a 2.x kernel, as VICE needs some
features that were not implemented in older versions of the Linux sound
driver.

</P>
<P>
<A NAME="IDX2"></A>
On the other hand, HP-UX and Solaris machines are known to cause
troubles.  If you think you can help debugging the code for these
systems, your help would be really appreciated.  We are having troubles
finding HP-UX and SUN consoles to work at...

</P>
<P>
<A NAME="IDX3"></A>
Some problems have been reported with the proprietary version of the
Open Sound System for Linux.  With a Crystal sound card, sound output
was significantly delayed and, apparently, the allocated buffer size was 
completely wrong.  This is not a VICE bug, but rather an OSS bug.

</P>



<H3><A NAME="SEC17" HREF="vice_toc.html#TOC17">2.10.2  Shared memory problems</A></H3>

<P>
<A NAME="IDX4"></A>
<A NAME="IDX5"></A>
If you cannot start VICE because you get errors about shared memory, try
to run it with the <SAMP>`+mitshm'</SAMP> command-line option (see section <A HREF="vice_6.html#SEC47">6.4.2  Video command-line options</A>).  This will completely disable usage of the MITSHM extensions,
that are normally used to speed up the emulation window updates.  Of
course, this will also result in a big loss in speed.

</P>
<P>
Reasons for this failure could be:

</P>

<P> <UL>
<P> <LI>

IPC support has been disabled at the system level; some system
administrators disable this for security reasons.  If <EM>you</EM> are the
system administrator, use a kernel that has IPC support compiled in and
enabled.
<P> <LI>

You are attempting to run the emulator across the network (i.e., the
emulator runs on one machine, and the output is displayed on another
machine that works as an X terminal) and for some reason VICE does not
recognize this fact.  In this case, you have found a bug, so please report it
to us.
</UL> </P>

<P>
If you want to avoid running the emulator with <SAMP>`+mitshm'</SAMP> every
time, run it once with <SAMP>`+mitshm'</SAMP> and then choose "Save settings"
from the right-button menu.

</P>


<H3><A NAME="SEC18" HREF="vice_toc.html#TOC18">2.10.3  Printer problems</A></H3>

<P>
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 <CODE>OPEN 1,4</CODE>
is not seen on the IEC bus. Also a <CODE>CLOSE 1</CODE> after that
is not seen. VICE can see from printing that there was an <CODE>OPEN</CODE>,
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 <CODE>print.dump</CODE> or to the 
printer) now a menu entry can be used. Disabling and re-enabling the printer
should work as well.

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

</P>


<H3><A NAME="SEC19" HREF="vice_toc.html#TOC19">2.10.4  PET keyboard problems</A></H3>

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

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

</P>
<P><HR><P>
Go to the <A HREF="vice_1.html">first</A>, <A HREF="vice_1.html">previous</A>, <A HREF="vice_3.html">next</A>, <A HREF="vice_16.html">last</A> section, <A HREF="vice_toc.html">table of contents</A>.
</BODY>
</HTML>
