     START-INFO-DIR-ENTRY
     * VICE: (vice).        VICE, the Versatile Commodore Emulator.
     END-INFO-DIR-ENTRY

VICE Manual

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

This is the documentation for version 0.15 of VICE, the Versatile Commodore Emulator.

GNU GENERAL PUBLIC LICENSE
**************************

Version 2, June 1991

     Copyright © 1989, 1991 Free Software Foundation, Inc.  675
     Mass Ave, Boston, MA 02111-1307, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

The licenses for most software are designed to take away your freedom to share and change it.  By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software---to make sure the software is free for all its users.  This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it.  (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.)  You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price.  Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have.  You must make sure that they, too, receive or can get the source code.  And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software.  If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents.  We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary.  To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License.  The ``Program'', below, refers to any such program or work, and a ``work based on the Program'' means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language.  (Hereinafter, translation is included without limitation in the term ``modification''.)  Each licensee is addressed as ``you''.

     Activities other than copying, distribution and modification are not covered by this License; they are outside its scope.  The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

     You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

      a. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

      b. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

      c. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License.  (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

     These requirements apply to the modified work as a whole.  If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works.  But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

 3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

      a. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

      b. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

      c. Accompany it with the information you received as to the offer to distribute corresponding source code.  (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for making modifications to it.  For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable.  However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License.  Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

 5. You are not required to accept this License, since you have not signed it.  However, nothing else grants you permission to modify or distribute the Program or its derivative works.  These actions are prohibited by law if you do not accept this License.  Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions.  You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

 7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License.  If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all.  For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

     It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices.  Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded.  In such case, this License incorporates the limitation as if written in the body of this License.

 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time.  Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the Program specifies a version number of this License which applies to it and ``any later version'', you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation.  If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission.  For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this.  Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

     NO WARRANTY

 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs
=============================================

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program.  It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the ``copyright'' line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR

     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2
     of the License, or (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.  This is free software, and you are welcome
     to redistribute it under certain conditions; type `show c'
     for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License.  Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items---whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a ``copyright disclaimer'' for the program, if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright
     interest in the program `Gnomovision'
     (which makes passes at compilers) written
     by James Hacker.

     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs.  If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library.  If this is what you want to do, use the GNU Library General Public License instead of this License.

About VICE
**********

VICE is the one and only Versatile Commodore Emulator.  It allows you to emulate the Commodore 64, 128, VIC20 and PET 8-bit computers with one 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 about what a Commodore 8-bit computer is, or have questions about how these machines are used, how the file formats work or everything else that is not strictly related to VICE, you should read the appropriate FAQs first, as this kind of information is not available here.  See Contacts for information about how to retrieve the 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, the emulation of all the chips is cycle accurate, and tries to emulate timings as precisely as possible while trying to use as little processor power as possible.

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

C64 emulator features
=====================

The 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.  Since version 0.13.0, the emulation is fully cycle-accurate.

Moreover, a rather complete emulation of the SID sound chip is provided. All the basic features are implemented as well as most of the complex ones including sync, ring modulation and filters.

Of course, also both CIAs are cycle-accurate and fully emulated.

C128 emulator features
======================

The C128 emulator, called x128, features a complete emulation of the internal MMU (Memory Management Unit), plus all the features of the C64 emulation.  The following things are missing, though:

  * 80-column VDC chip;

  * 2 MHz mode;

  * C64 mode.

VIC20 emulator features
=======================

The VIC20 emulates all the internal hardware, including the VIA chips. Only part of the VIC-I video chip features are emulated, so some graphical effects will not work correctly.

Sound is implemented, but is still at the experimental stage.  If you think it does not sound right and know how to improve it, feel free to contact us (see Contacts).

PET emulator features
=====================

The PET emulator emulates the 2001, 3032, 4032, 8032, 8096 and 8296 models, which almost covers all models of this kind of machines.  The hardware is pretty much the same 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).  Anyway, those missing features are not very important for average applications.

Sound is available for the PET as well, but like the VIC20 it is still under construction.

The PET 8096 is basically a PET 8032 with a 64k extension board, that 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 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 in the IEEE488 part (they shipped it before they tested it with the floppy drive, so only tape worked - which is not supported in this emulator) so the ROM is patched to fix the IEEE488 routines.

What the 2001 patch basically does is (amongst more low level fixes) get the load address for a program file from the first two bytes of the file.  This allows loading of PET2001-saved files (that have $0400 as load address) and other PET files (that have $0401). The PET2001 still saves from $0400, not from $0401 as other PETs do.

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

To select which model to run, you specify the model on the command line with the -model MODEL option, where MODEL can be one of a list of PET model numbers, all described in ...

The keyboard emulation
======================

There are two ways of emulating the keyboard in VICE.

The default way (symbolic mapping) is to map every X11 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.

There is one problem with symbolic mapping, though: some keys have to be mapped specially anyway.  The most important execption is that, in the VIC20, C64 and C128 emulators, CTRL is mapped to Tab and the Commodore key is mapped to the left Control).

The second way (positional mapping) 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 Shift key is forced by the program (with the exception of the function keys F2, F4, F6 and F8, which require Shift 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.

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.

The joystick emulation
======================

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

There are two keyboard layouts, called numpad and custom layouts respectively.

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 uses the keys q, w, e, a, s, d, z, x, c for the directions and space for the fire button instead.

The disk drive emulation
========================

All the emulators support emulation of up to 4 external disk drives as devices 8, 9, 10 and 11.  Each of these devices can emulate virtual Commodore 1541 drives in two ways:

  * 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 comp.emulators.cbm FAQ);

  * accessing file system directories, thus allowing you to access files without having to copy them to disk images; this also allows you to read and write files in the P00 format (again, consult the comp.emulators.cbm FAQ for more info).

Moreover, there are two available types of 1541 emulation for the first kind of emulation.  One of them the DOS level 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).

The other alternative is a hardware level drive emulation.  The Commodore 1541 disk drive was provided with its own CPU (a 6502 as the VIC20 and the PETs) and its 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 are no longer patched 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 hardware level emulation is only available on the VIC20 and C64 emulators, and can only be used to emulate one drive at a time.  As a consequence, it is only available for unit 8 and disables all the other drives when activated.

On the other hand, the PETs don't use a serial IEC bus to communicate with the floppy, instead they use the parallel IEEE488 bus.  This bus transfers byte by byte, as opposed to bit by bit as the C64 and VIC20 do, so in this case it is 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 is available in the C64, to emulate the Commodore IEEE488 bus interface.

Supported file formats
======================

VICE supports the most popular Commodore file formats:

  * X64 (preferred) or D64 disk image files;

  * G64 GCR-encoded 1541 disk image files;

  * T64 tape image files (read-only);

  * P00 program files;

An utility (c1541, see c1541) is provided to allow transfers between these formats.

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

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

Common problems
===============

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

Sound problems
--------------

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, sound is the least portable part of the emulator and has not been thoroughly tested on all the supported platforms yet.

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

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

Shared memory problems
----------------------

If you cannot start VICE, because you get errors about shared memory, try to run it with the +mitshm command-line option (see Video options).  This will completely disable usage of the MITSHM extensions, that are normally used to speed up the process of updating the emulation window.  Of course, this will also result in a big loss in speed.

Reasons for this failure could be:

  * IPC support has been disabled from the system; some system administrators disable this for security reasons.  If you are the system administrator, use a kernel that has IPC support compiled in and enabled.

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

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

Invoking the emulators
**********************

The names of the available emulators are:

  * x64, the C64 emulator

  * x128, the C128 emulator

  * xpet, the PET emulator

  * xvic, the VIC20 emulator

You can run each of them by simply typing the name from a shell.  If you want to run them from another application (e.g. a window manager or some other sort of program launcher) you should always run them from a terminal window such as xterm or rxvt, as a lot of debugging information is printed and the built-in monitor will be run in there.  For example, you could do

     xterm -e x64

Command-line options used during initialization
===============================================

There are several options you can specify on the command line.  Some of them are used to specify emulation settings; they will be described in detail later (see Settings and resources for a complete list).  The other ones, instead, are used only to initialize the emulator:

-help
-?
     List all the available command-line options and their meaning.

-default
     Set default resources (see Settings and resources).  This will override all the settings specified before, but not the settings specified afterwards on the command line.

-autostart IMAGE
     Autostart IMAGE (see Command-line autostart).

-1 NAME
     Attach NAME as a tape image file.

-8 NAME
-9 NAME
-10 NAME
-11 NAME
     Attach NAME as a disk image to device 8, 9, 10 or 11.

Autostarting programs from the command-line
===========================================

It is possible to let the emulator autostart a disk or tape image file, by simply specifying its name as the last argument on the command line; for example

     x64 lovelygame.x64.gz

will start the C64 emulator, attaching lovelygame.x64.gz as a disk image and running the first program on it.  You can also specify the name of the program on the fisk image by appending a colon (:) the name itself to the argument; for example

     x64 "lovelygame.x64.gz:run me"

will run the program named run me on lovelygame.x64.gz instead of the first one.

Using the command-line option -autostart is equivalent; so the same result can be obtained with

     x64 -autostart "lovelygame.x64.gz:run me"

See Disk and tape images for more information about images and autostart.

System files
************

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

  * the system ROMs, raw binary files containing copies of the original ROMs of the machine you are emulating;

  * the keyboard maps, text files describing the keyboard layout;

  * the palette files, text files describing the colors of the machine you are emulating.

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:BOOTPATH/EMU

Where PREFIX is the installation prefix (usually /usr/local), EMU is the name of the emulated machine (C64, C128, PET or VIC20) and BOOTPATH is the directory where the executable resides.

For example, if you have the C64 emulator installed in

     /usr/local/bin/x64

then the value will be

     /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. /usr/local/lib/VICE/C64

 2. /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 Resource files).

ROM files
=========

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

  * kernal,  the Kernal ROM (8 KBytes)

  * basic, the Basic ROM (8 KBytes)

  * chargen, the character generator ROM (4 Kbytes)

  * dos1541, the 1541 drive ROM (16 Kbytes)

The C128 needs the following files instead:

  * kernal, the Kernal ROM (8 Kbytes)

  * basic, the BASIC + Editor ROM (32 Kbytes)

  * chargen, the character generator ROM (4 Kbytes)

  * dos1541, the 1541 drive ROM (16 Kbytes)

The PET emulator uses a quite different setup instead: the Basic and Kernal ROMS are packed into a single file and only three kernal files are provided; one for each basic revision.  To handle the different screen sizes and keyboards, different so-called ``editor-ROMs'' for the memory range $E000-$E800 are provided.  The kernal files contain an editor ROM for 40 columns and graphics keyboard already.  The PET ROMs have the following names:

  * pet2001, the PET2001 Basic 1 + Kernal ROM (16 KBytes)

  * pet3032, the PET3032 Basic 2 + Kernal ROM (16 KBytes)

  * pet4032, the PET4032/8032 Basic 4 + Kernal ROM (20 KBytes)

  * edit2.b, the PET3032 editor for business keyboard (2 KBytes)

  * edit4.b40, the PET4032 editor for business keyboard (2 KBytes)

  * edit4.b80, the PET8032 editor for 80 columns and business keyboard (2 KBytes)

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

Also, you can specify a replacement for the basic ROM at $B000-$DFFF with the -petromBasic option and a replacement for the editor ROM at $E000-$E7FF with the -petromEditor option.

Keymap files
============

Keymap files are used to define the keyboard layout, defining what key (or combination of keys) must me mapped to ever keysym.

In other words, the keyboard emulation works like this: whenever the user presses o releases a key while the input focus in the emulation window, the emulator receives an X-Window event with a value that identifies that key.  That value is called a keysym and is unique to that key.  Then the emulator looks for that keysym into an internal table which tells it what 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 identifying the keysym: you can use the xev utility (shipped with the X Window system) 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.

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;

  * !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

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
=============

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 an hexadecimal 4-bit number specifying the pattern you want to be used 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

Basic operation
***************

This section describes the basic things you can do after the emulator has been fired up.

The emulation window
====================

When the emulator is run, the screen of the emulated machine is displayed in a standard X Window which we will call the emulation window.  This window will be updated in real-time, displaying the same contents that a real monitor or TV set would.

Under the emulation window there is an area which is used to display information about the state of the emulator; we will call this area the status bar.

On the extreme left of the status bar, there is a performance meter.  The performance meter displays the current relative speed (in percent) of the emulator and the update frequency, in frames per second. All the machines emulated are PAL, so the update frequency will be of 50 frames per second if your system is fast enough to allow the emulator to run at the speed of the real machine.

On the extreme right of the status bar, there is a drive status indicator.  This is only visible if the hardware-level (``True'') 1541 emulation is turned on.  In that case, the drive status indicator will contain a rectangle which emulates the drive LED and will display the current track position of the read-write head of the drive.

Using the menus
===============

It is possible to execute some commands and change emulation parameters while running the emulator: two menus are available by pressing the right or left mouse buttons while the pointer is in the emulation window.  The left mouse button will open the command menu from which several emulation-related commands can be executed; the right mouse button will open the setting menu, from which emulation parameters can be changed.  The basic difference between the command and the setting menu is that, while commands have only effect on the current session, settings can be saved for later use: this can be done with the ``Save settings'' and ``Load settings'' right-button menu items. ``Restore default settings'' restores the factory defaults. See Settings and resources for more information about how settings work in VICE.

Sometimes commands can be reached via shortcuts or hotkeys, i.e. it is possible to reach them by pressing a sequence of keys instead of going through the menu with the mouse; when this happens, the corresponding shortcut is displayed in parenthesis on the right of the menu item.  In VICE, all the shortcuts must begin with the Meta or Alt key.  So, for example, to attach a disk image to drive #8 (the corresponding menu item displays ``M-8''), you have to press the Meta (or Alt) and then 8.

Notice that, while Meta or Alt is pressed, pressing other keys has no effect at all on the emulated machine.

Getting help
============

In case you suddenly get stuck or do not remember how to do a certain thing, you can in any moment use the ``Browse manuals'' command (left button menu).  This will popup a browser and open the HTML version of this documentation.  Notice that this requires VICE to be properly (and fully) installed with a make install.

The browser can be specified via the HTMLBrowserCommand string resource (see Settings and resources for information about resources).  Every %s in the string will be replaced with a URL to the VICE HTML pages.

Using the file selector
=======================

In those situations where it is necessary to specify a file name, all of the VICE emulators will pop up a file selector window which allows you to select one file interactively.

On the left of the file selector, there is a list of ancestor directories: by clicking on them, you can go up the directory tree.  On the right, there is a list of the files in the current directory; files can be selected by clicking on them.  If you click on a directory, that directory becomes the current one; if you click on an ordinary file, it becomes active.

On the top, there are a directory box, with the complete path of the current directory, and a file name box, with the name of the file you are selecting.  On the bottom there are two buttons: ``OK'' confirms the selected file and ``Cancel'' abandons the file selector without cancelling the operation.

It is also possible to specify what files you want to show in the file selector by writing an appropriate shell-like pattern in the directory box; eg. ~/*.[dx]64 will only show files in the home directory whose name ends with .d64 or *.x64.

Using disk and tape images
==========================

The emulator is able to emulate disk drives and (read-only) tape recorders if provided with suitable disk images or tape images.  An image is a raw dump of the contents of the media, and must be attached before the emulator can use it.  ``Attaching'' a disk or tape image is like ``virtually'' inserting a diskette or a cassette into the disk drive or the tape recorder: after an image is attached, the emulator is able to use it as a storage media.

There are five commands (in the left button menu) that deal with disk and tape images:

  * Attach Disk Image

  * Detach Disk Image

  * Attach Tape Image

  * Detach Tape Image

  * Smart-attach a file

The first four commands are used to insert and remove the virtual disks and cassette tapes from the respective units.  On the other hand, the last commands tries to guess the type of the image you are attaching from its name and size, and attaches it to the most reasonable device.

Supported formats are D64 and X64 for disk images (devices 8, 9 and 10) and T64 for tape images.  Notice that T64 support is read-only, and that the cassette is automatically rewound from the start when you reach the end.

Another important feature is that raw Commodore BASIC binary files and .P00 files can be attached as tapes.  As you can autostart a tape image when it is attached (see Autostart), this allows you to autostart these particular files as well.

You can attach a disk for which you do have write permissions: when this happens, the 1541 emulator will emulate a write-protected disk.  This is also useful if you want to preserve certain disk image from being written to; in the latter case, just remove the write permission for that file, eg. doing a chmod a-w.

Previewing the image contents
-----------------------------

It is possible to look into the disk or tape image and see its directory before attaching it: to do so, just press the ``Contents'' button in the file selector window.  This way, a new window will be popped up with the contents of the selected image.

Notice that this function automatically translates the directory from PETSCII to ASCII; but, due to differences in the two encodings, it is not always possible to translate all the characters, so you might get funny results when ``weird'' characters such as the semi-graphical ones are being used.

``Autostarting'' an image
-------------------------

If you want to reset the machine and run the first program on a certain image without typing any commands at the Commodore BASIC prompt, you can use the ``Autostart'' button in the file selector window after selecting a proper disk or tape image file.

Notice that, if true 1541 emulation is turned on, it will be turned off before running the program and then turned on again after it has been loaded.  This way, you get the maximum possible speed while loading the file, but you don't loose compatibility when the actual program is running.

This method is not completely safe, because some autostarting methods might cause the true 1541 emulation not to be turned on again.  In such cases, the best thing to do is to disable kernal traps (which will cause true 1541 emulation to be always kept turned on), or to manually load the program with true 1541 emulation turned on.

Using compressed files
----------------------

It is also possible to attach disk or tape images that have been compressed through various algorithms; the compression format is recognized from the file extension.  The following formats are supported (the expected file name extension is in parenthesis):

  * GNU Zip (.gz or .z);

  * BZip version 2 (.bz2);

  * PkZip (.zip);

  * GNU Zipped TAR archives (.tar.gz, .tgz);

  * Zoo (.zoo).

PkZip, tar.gz, lha and zoo support is read-only and always uses the first T64 or D64 file in the archive.  So archives containing multiple files will always be handled as if they contained one single file.

Using Zipcode and Lynx images
-----------------------------

Since version 0.15, the VICE emulators are able to attach disks packed with Zipcoded or Lynx without the need of converting them into D64 or X64 files with c1541.  This is done by executing c1541, letting it decode the file into a temporary image, and then by attaching the temporary image read-only.  For this reason, the directory c1541 is contained in must be in your PATH.

This uses the -unlynx and -zcreate options of c1541 (see c1541 commands and options); these commands are not very reliable yet, and could fail with certain kinds of Lynx and Zipcode images (for example, they cannot deal with DEL files properly). So please use with care.

Lynx files usually come as .lnx files and are depacked into a single disk.  On the other hand, Zipcode files do not have a particular extension (although .z64 is sometimes used), and represent a disk by means of four sub-files, named as follows:

  * 1!NAME

  * 2!NAME

  * 3!NAME

  * 4!NAME

If you attach as a disk image (or smart-attach) any of these files, the emulator will simply pick up the other three parts (by looking at the name) and build one disk image out of them.

Resetting the machine
=====================

You can reset the emulated machine at any time by using the ``Reset'' command from the command menu.  There are two types of reset:

  * soft reset, which simply resets the CPU and all the chips;

  * hard reset, which also clears up the contents of RAM.

A soft reset is the same as a hardware reset achieved by pulling the RESET line down; a hard reset is more like a power on/power off sequence, which makes sure the whole RAM is cleared.

It is possible that a soft reset is not enough to bring the machine back to the OS initialization sequence: in such cases, you have to do a hard reset instead.

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.

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.

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.

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.

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.

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

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.

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.

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

Keyboard settings
=================

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

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

KeymapPosFile
     String specifying the name of the keymap file for the positional mapping (see Keyboard emulation).

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

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

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

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

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.

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 1541 settings.

True1541SyncFactor
     Integer specifying the true 1541 clock sync factor (see 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.

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

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.

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.

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.

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

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.

Printer resources
.................

PrDevice1
PrDevice2
PrDevice3
     Strings specifying the printer devices (see 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.

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

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.

Resources to control Kernal traps
.................................

NoTraps
     Boolean specifying whether all the Kernal trap should be disabled.

Command-line options to control Kernal traps
............................................

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

Miscellaneous settings
======================

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

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

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

Machine-specific features
*************************

C64/128-specific commands and settings
======================================

This section lists the settings and commands that are C64/128 specific and thus are not present in the other emulators.

Using cartridge images
----------------------

Cartridge images are like disk images, but mirror the contents of cartridge ROM images instead of disk images.  They are currently not supported on the C128 emulator.

X64 allows you to attach the following kinds of cartridges:

  * .crt images, as used by the CCS64 emulator by Per Hâkan Sundell;

  * generic raw dumps of 8K and 16K images;

  * Action Replay images.

Each of these kinds has a specific command in the ``Attach a cartridge image'' submenu.  When you have successfully attached a cartridge image, you should then reset the machine to make sure the cartridge initializes itself.  Of course, it is also possible to detach a currently attached cartridge image (``Detach cartridge image'').

If you are using an Action Replay cartridge, you can emulate the cartridge's freeze button with the ``Freeze'' command.

VIC-II settings
---------------

These settings control the emulation of the VIC-II (MOS6569) video chip used in both the C64 and the C128.

  * ``Sprite-sprite collisions'' and ``Sprite-background collisions'', if enabled, cause the hardware detection of sprite-to-sprite and sprite-to-background collisions of the VIC-II to be emulated.  This feature is used by many games, and disabling either of the two detection systems can sometimes make you invincible (although there is also a chance that also enemies become invincible then).

  * ``Color set'' can be used to dynamically change the palette file being used by choosing one of the available predefined color sets:

       * default.vpl (``default''), the default VICE palette;

       * ccs64.vpl (``CCS64''), palette taken from the CCS64 emulator by Per Hâkan Sundell (http://www.fatal-design.com/ccs64/).

       * frodo.vpl (``Frodo''), palette taken from the Frodo emulator by Christian Bauer (http://www.uni-mainz.de/~bauec002/FRMain.html).

       * godot.vpl (``GoDot''), palette as suggested by the authors of the C64 graphics package GoDot (http://users.aol.com/howtogodot/welcome.htm).

VIC-II resources
................

CheckSsColl
     Boolean specifying whether the sprite-sprite hardware collision detection must be emulated.

CheckSbColl
     Boolean specifying whether the sprite-background hardware collision detection must be emulated.

PaletteFile
     String specifying the name of the palette file being used.  The .vpl extension is optional.

VIC-II command-line options
...........................

-checkss
+checkss
     Enable (CheckSsColl=1) and disable (CheckSsColl=0) emulation of hardware sprite-sprite collision detection, respectively.

-checksb
+checksb
     Enable (CheckSbColl=1) and disable (CheckSbColl=0) emulation of hardware sprite-background collision detection, respectively.

-palette NAME
     Specify NAME as the palette file (PaletteFile).

SID settings
------------

These settings control the emulation of the SID (MOS6581 or MOS8580) audio chip.

  * ``Emulate filters'' causes the built-in programmable filters of the SID chip to be emulated.  A lot of C64 music requires them to be emulated properly, but their emulation requires some additional processor power.

  * ``ChipModel'' specifies the model of the SID chip being emulated: there are two slightly different generations of SID chips: MOS6581 ones and MOS8580 ones.

SID resources
.............

SidFilters
     Boolean specifying whether the built-in SID filters must be emulated.

SidModel
     Integer specifying what model of the SID must be emulated (0: MOS6581, 1: MOS8580).

SID command-line options
........................

-sidmodel MODEL
     Specifies MODEL as the emulated model of the SID chip (SidModel).

-sidfilters
+sidfilters
     Enable (SidFilters=1) or disable (SidFilters=0) emulation of the built-in SID filters.

C64 I/O extension settings
--------------------------

There are three I/O extensions available: they are located at the address range $DF00 ... $DFFF and each of them is controlled by a boolean resource.  Please use these extensions only when needed, as they might cause compatibility problems.

  * The ``emulator identification'' extension allows programs to identify the kind of emulator they are running on, according to the emulation detection proposal by Wolfgang Lorenz.  This basically means that, when some locations in the $DFxx I/O space are read, the emulator returns some values which identify the emulator itself, its version and a copyright message.  If this extension is disabled, programs will have virtually no way to realize they are running on an emulator.

  * The ``IEEE488 interface emulation'' extension emulates a standard Commodore IEEE488 interface connected to the IEC bus; one possible use for this is André Fachat's OS/A65 multitasking operating system.

  * The ``512K RAM Expansion Unit'' extension emulates a standard 512K Commodore RAM Expansion Unit; this can be used with GEOS and other programs that are designed to take advantage of it.  This currently works only in the C64 emulator.

C64 I/O extension resources
...........................

IEEE488
     Boolean specifying whether the IEEE488 interface should be emulated or not.

REU
     Boolean specifying whether the 512K RAM Expansion Unit should be emulated or not.

EmuID
     Boolean specifying whether the emulation identification extension should be emulated or not.

C64 I/O extension command-line options
......................................

-ieee488
+ieee488
     Enable (IEEE488=1) or disable (IEEE488=0) emulation of the IEEE488 interface.

-reu
+reu
     Enable (REU=1) or disable (REU=0) emulation of the 512K RAM Expansion Unit.

-emuid
+emuid
     Enable (EmuID=1) or disable (EmuID=0) the emulation identification extension.

RS232 settings
--------------

X64 and X128 can support RS232 in the following ways:

  * by emulating Daniel Dallmann's 9600 baud userport-based RS232 interface;

  * by emulating a 6551-based RS232 interface located at $DE00.

Each of these emulated devices can be either:

  * connected a real UNIX serial device;

  * dumped to a file;

  * piped through a process.

It is possible to define up to two UNIX serial devices, and then decide which interface should be connected to which device.  Devices are defined through the following settings:

  * ``Serial 1 device...'' and ``Serial 2 device...'' are used to specify the the pathnames of the serial devices, with the file selector;

  * ``Serial 1 baudrate'' and ``Serial 2 baudrate'' specify the baudrate.

RS232 resources
...............

RsDevice1
RsDevice2
     Strings specifying the pathnames of the two available serial devices.

RsDevice1Baud
RsDevice2Baud
     Integers specifying the baudrates.

RsDevice3
     String defining the name of the file used when dumping RS232 output.

RsDevice4
     String defining the name of the process to pipe the RS232 data through.

RsUser
     Boolean specifying whether the userport-based RS232 should be emulated.

Acia1
     Boolean specifying whether the ACIA-based RS232 should be emulated.

RsUserDev
Acia1Dev
     Integers specifying how the userport-based interface and the ACIA-based one are emulated.  The possible values are:

       * 0: connect to serial device number 1;

       * 1: connect to serial device number 2;

       * 2: dump to file;

       * 3: exec an external process.

RS232 command-line options
..........................

-acia1
+acia1
     Enable/disable emulation of the ACIA-based RS232 interface (Acia1=1, Acia1=0).

-acia1dev DEVICE
     Specify DEVICE as the device for the ACIA-based RS232 emulation (Acia1Dev).

-rsuser
+rsuser
     Enable/disable emulation of the userport-based RS232 interface (RsUser=1, RsUser=0).

-rsuserdev DEVICE
     Specify DEVICE as the device for the ACIA-based RS232 emulation (RsUserDev).

C64/128 system ROM settings
---------------------------

These settings can be used to control what system ROMs are loaded in the C64/128 emulators at startup.  They cannot be changed from the menus.

C64/128 system ROM resources
............................

KernalName
     String specifying the name of the Kernal ROM (default kernal).

BasicName
     String specifying the name of the Basic ROM (default basic).  In the C128 emulator, the ROM image must actually include the editor ROM too.

ChargenName
     String specifying the name of the character generator ROM (default chargen).

KernalRev
     String specifying the Kernal revision.  This resource can be used to control what revision of the C64 kernal is being used; it cannot be changed at runtime.  VICE is able to automatically convert one ROM revision into another, by manually patching the loaded image.  This way, it is possible to use any of the ROM revisions without changing the ROM set.  Valid values are:

     0
          Kernal revision 0

     3
          Kernal revision 3

     sx
     67
          Commodore SX-64 ROM

     100

     4064
          Commodore 4064 (also known as ``PET64'' or ``Educator 64'') ROM

C64/128 system ROM command-line options
.......................................

-kernal NAME
     Specify NAME as the Kernal ROM file (KernalName).

-basic NAME
     Specify NAME as the Basic ROM file (BasicName).

-chargen NAME
     Specify NAME as the character generator ROM file (ChargenName).

-kernalrev REVISION
     Specify Kernal revision (KernalRev).

VIC20-specific commands and settings
====================================

This section lists the settings and commands that are VIC20-specific and thus are not present in the other emulators.

Using cartridge images
----------------------

As with the C64 (see C64 cartridges), it is possible to attach several types of cartridge images:

  * 4 or 8 Kbyte cartridges located at $2000;

  * 4 or 8 Kbyte cartridges located at $6000;

  * 4 or 8 Kbyte cartridges located at $A000;

  * 4 Kbyte cartridges located at $B000.

This can all be done via the ``Attach cartridge image...'' command in the left-button menu.  It is also possible to let XVIC ``guess'' the type of cartridge using ``Smart-attach cartridge image...''.

Notice that several cartridges are actually made up of two pieces (and two files), that need to be loaded separately at different addresses. In that case, you have to know the addresses (which are usually specified in the file name) and use the ``attach'' command twice.

Changing memory configuration
-----------------------------

It is possible to change the VIC20 memory configuration in two ways: by enabling and/or disabling certain individual memory blocks, or by choosing one among a few typical memory configurations.  The former can be done by modifying resource values directly or from the right-button menu; the latter can only be done from the menu.

There are 5 RAM expansion blocks in the VIC20, numbered 0, 1, 2, 3 and 5:

  * block 0 (3 Kbytes at $0400-$0FFF);

  * block 1 (8 Kbytes at $2000-$3FFF);

  * block 2 (8 Kbytes at $4000-$5FFF);

  * block 3 (8 Kbytes at $6000-$7FFF);

  * block 5 (8 Kbytes at $A000-$BFFF).

These blocks are called expansion blocks because they are not present a stock (``unexpanded'') machine.  Each of them is associated to a boolean RamBlockX resource (where X is the block number) that specifies whether the block is enabled or not.

There are also some common memory configurations you can pick from the right-button menu:

  * no RAM expansion blocks at all;

  * all RAM expansion blocks enabled;

  * 3K expansion (only block 0 is enabled);

  * 8K expansion (only block 1 is enabled);

  * 16K expansion (only blocks 1 and 2 are enabled);

  * 24K expansion (only blocks 1, 2 and 3 are enabled).

As with the X64 (see C64 I/O extension settings), it is also possible to enable a special emulator identification mechanism that uses certain memory locations to let a running program query information about the emulator itself; this is enabled by the ``Emulator identification'' option.

VIC20 memory configuration resources
....................................

RAMBlock0
RAMBlock1
RAMBlock2
RAMBlock3
RAMBlock5
     Booleans specifying whether RAM blocks 0, 1, 2, 3 and 5 must be enabled.

EmuID
     Boolean specifying whether the emulation identification extension must be enabled.

VIC20 memory configuration command-line options
...............................................

-memory CONFIG
     Specify memory configuration.  It must be a comma-separated list of options, each of which can be one the following:

       * none (no extension);

       * all (all blocks);

       * 3k (3k space in block 0);

       * 8k (first 8k extension block);

       * 16k (first and second 8k extension blocks);

       * 24k (first, second and 3rd extension blocks);

       * 0, 1, 2, 3, 5 (memory in respective blocks);

       * 04, 20, 40, 60, A0 (memory at respective address.

     For example,

          xvic -memory none

     gives an unexpanded VIC20.  While

          xvic -memory 60,a0

     or

          xvic -memory 3,5

     enables memory in blocks 3 and 5, which is the usual configuration for 16k ROM modules.

-emuid
+emuid
     Enable (EmuID=1) or disable (EmuID=0) the emulation identification extension.

VIC20 system ROM settings
-------------------------

These settings can be used to control what system ROMs are loaded in the VIC20 emulator at startup.  They cannot be changed from the menus.

VIC20 system ROM resources
..........................

KernalName
     String specifying the name of the Kernal ROM (default kernal).

BasicName
     String specifying the name of the Basic ROM (default basic).

ChargenName
     String specifying the name of the character generator ROM (default chargen).

VIC20 system ROM command-line options
.....................................

-kernal NAME
     Specify NAME as the Kernal ROM file (KernalName).

-basic NAME
     Specify NAME as the Basic ROM file (BasicName).

-chargen NAME
     Specify NAME as the character generator ROM file (ChargenName).

PET-specific commands and settings
==================================

This section lists the settings and commands that are PET-specific and thus are not present in the other emulators.

Changing PET model settings
---------------------------

With xpet, it is possible to change at runtime the characteristics of the emulated PET so that it matches (or not) the ones of a certain PET model, and it is also possible to select from a common set of PET models so that all the features are selected accordingly.

The former is done by changing the following resources (via resource file, command line options or right-menu items):

  * (None yet.)

Choosing a common PET model is done from the right-button menu instead, by choosing an item from the ``Model defaults'' submenu.  Available models are:

  * PET 2001-8N

  * PET 3008

  * PET 3016

  * PET 3032

  * PET 3032B

  * PET 4016

  * PET 4032

  * PET 4032B

  * PET 8032

  * PET 8096

  * PET 8296

Notice that this will reset the emulated machine.

It is also possible to select the PET model at startup, with the -model command-line option: for example, xpet -model 3032 will emulate a PET 3032 while xpet -model 8296 will emulate a PET 8296.

The PET diagnostic pin
----------------------

It is possible to enable or disable emulation of the PET diagnostic pin via the DiagPin resource, or the ``PET userport diagnostic pin'' item in the right-button menu.

Changing screen colors
----------------------

It is also possible to choose what color set is used for the emulation window.  This is done by specifying a palette file name (see Palette files) in the PaletteName resource.  The menu provides the following values:

  * default.vpl (``default (green)''), the good old green-on-black feeling;

  * amber.vpl (``amber''), an amber phosphor lookalike;

  * white.vpl (``white''), simple white-on-black palette.

Monitor
*******

Every VICE emulator has a complete built-in monitor, which can be used to examine, disassemble and assemble machine language programs, as well as debug them through breakpoints.  It can be activated by using the ``Activate monitor'' command (left button menu).  Notice that you have to run the emulator from a terminal emulation program (such as rxvt or xterm) in order to use the monitor.

Warning: this version of the monitor is still under construction, and some of the features are not fully working yet.

Terminology
===========

address_space
     This refers to the range of memory locations and a set of registers. This can be the addresses available to the computer's processor, the disk drive's processor or a specific memory configuration of one of the mentioned processors.

register
     One of the following: program counter (PC), stack pointer (SP), accumulator (A), X register (X), or Y register (Y).

address
     A specific memory location in the range $0000 to $FFFF.

address_range
     Two addresses.  If the second address is less than the first, the range is assumed to wraparound from $FFFF to $0000.  Both addresses must be in the same address space.

address_opt_range
     An address or an address range.

prompt
     The prompt has the format [x:y].  If x is -, memory reads from the monitor do not have side effects.  Otherwise, x is S.  The second part of the prompt, y, shows the default address space.

checkpoint
     The monitor has the ability to setup triggers that perform an action when a specified situation occurs.  There are three types of checkpoints; breakpoints, tracepoints and watchpoints.

breakpoint
     A breakpoint is triggered based on the program counter.  When it is triggered, the monitor is entered.

tracepoint
     Like breakpoints, a tracepoint is triggered based on the program counter.  Instead of entering the monitor, the program counter is printed and execution continues.

watchpoint
     Watchpoints are triggered by a read and/or write to an address.  When a watchpoint is triggered, the monitor is entered.

<...>
     A data type.

*
     Zero or more occurrences.

[...]
     An optional argument.

Machine state commands
======================

goto <address>
     Change the PC to address and continue execution.

io
     Nothing yet.  Will display VIC/VIA/CIA/SID registers.

next [<count>]
     Advance to the next instruction.  Subroutines are treated as a single instruction.

registers [<reg_name> = <number> [, <reg_name> = <number>]*]
     Assign respective registers.  With no parameters, display register values.

return
     Continues execution  and returns to the monitor just before(after?) the next RTS or RTI is executed.

step [<count>]
     Single step through instructions.  An optional count allows stepping more than a single instruction at a time.

Memory commands
===============

compare <address_range> <address>
     Compare memory from the source specified by the address range to the destination specified by the address.  The regions may overlap.  Any values that miscompare are displayed using the default displaytype.

fill <address_range> <data_list>
     Fill memory in the specified address range with the data in <data_list>.  If the size of the address range is greater than the size of the data_list, the data_list is repeated.

hunt <address_range> <data_list>
     Hunt memory in the specified address range for the data in <data_list>.  If the data is found, the starting address of the match is displayed.  The entire range is searched for all possible matches.

i <address_opt_range>
     Display memory contents as PETSCII text.

m [<data_type>] [<address_opt_range>]
     Display the contents of memory.  If no datatype is given, the default is used.  If only one address is specified, the length of data displayed is based on the datatype.  If no addresses are given, the 'dot' address is used.

mc [<data_type>] [<address_opt_range>]
     Display the contents of memory as character data.  If only one address is specified, only one character is displayed.  If no addresses are given, the ``dot'' address is used.

ms [<data_type>] [<address_opt_range>]
     Display the contents of memory as sprite data.  If only one address is specified, only one sprite is displayed.  If no addresses are given, the ``dot'' address is used.

move <address_range> <address>
     Move memory from the source specified by the address range to the destination specified by the address.  The regions may overlap.

> [<address>] <data_list>
     Write the specified data at address.

Assembly commands
=================

a <address> [ <instruction> [: <instruction>]* ]
     Assemble instructions to the specified address.  If only one instruction is specified, enter assembly mode (enter an empty line to exit assembly mode).

d [<address> [<address>]]
     Disassemble instructions.  If two addresses are specified, they are used as a start and end address.  If only one is specified, it is treated as the start address and a default number of instructions are disassembled.  If no addresses are specified, a default number of instructions are disassembled from the dot address.

Checkpoint commands
===================

break [<address> [if <cond_expr>] ]
     This command allows setting a breakpoint or listing the current breakpoints.  If no address is given, the currently valid checkpoints are printed.  If an address is given, a breakpoint is set for that address and the breakpoint number is printed.  A conditional expression can also be specified for the breakpoint.  For more information on conditions, see the CONDITION command.

enable <checknum>

disable <checknum>
     Each checkpoint can be enabled or disabled.  This command allows changing between these states.

command <checknum> "<command>"
     When checkpoint checknum is hit, the specified command is executed by the monitor.  Note that the x command is not yet supported as a command argument.

condition <checknum> if <cond_expr>
     Each time the specified checkpoint is examined, the condition is evaluated.  If it evalutes to true, the checkpoint is activated. Otherwise, it is ignores.  If registers are specified in the expression, the values used are those at the time the checkpoint is examined, not when the condition is set.

delete <checknum>
     Delete the specified checkpoint.

ignore <checknum> [<count>]
     Ignore a checkpoint a given number of crossings.  If no count is given, the default value is 1.

trace [address [address]]
     This command is similar to the break command except that it operates on tracepoints.  A tracepoint differs from a breakpoint by not stopping execution but simply printing the PC, giving the user an execution trace.  The second optional address can be used to specify the end of an range of addresses to be traced.

watch [address [address]]
     This command is similar to the previous two commands except that it operates on watchpoints.  A watchpoint differs from the others by stopping on a read and/or write to an address or range of addresses.  If no addresses are given, a list of all the watchpoints is printed.

General commands
================

cd <directory>
     Change the working directory.

device [c:|d:]
     Set the default memory device to either the computer (c:) or the disk (d:).

radix [H|D|O|B]
     Set the default radix to hex, decimal, octal, or binary.  With no argument, the current radix is printed.

sidefx [on|off|toggle]
     Control how monitor generated reads affect memory locations that have read side-effects.  If the argument is 'on' then reads may cause side-effects.  If the argument is 'off' then reads don't cause side-effects.  If the argument is 'toggle' then the current mode is switched.  No argument displays the current state.

system <system command>
     Nothing yet.

Disk commands
=============

br <track> <sector> [<address>]
     Read the block at the specified track and sector.  If an address is specified, the data is loaded into memory.  If no address is given, the data is displayed using the default datatype.

bw <track> <sector> <address>
     Write a block of data at address to the specified track and sector of disk in drive 8.

@<disk command>
     Perform a disk command on the currently attached disk image on drive 8.  The specified disk command is sent to the drive's channel #15.

load "<filename>" <address>
     Load the specified file into memory at the specified address.

save "<filename>" <address1> <address2>
     Save the memory from address1 to address2 to the specified file.

Command file commands
=====================

playback "<filename>"
     Monitor commands from the specified file are read and executed.  This command stops at the end of file or when a STOP command is read.

record "<filename>"
     After this command, all commands entered are written to the specified file until the STOP command is entered.

stop
     Stop recording commands.  See record.

Label commands
==============

add_label <address> <label>
     Map a given address to a label.  This label can be used when entering assembly code and is shown during disassembly.

delete_label [<memspace>] <label>
     Remove the specified label from the label tables.  If no memory space is checked, all tables are checked.

load_labels [<memspace>] "<filename>"
     Load a file containing a mapping of labels to addresses.  If no memory space is specified, the default readspace is used.

save_labels [<memspace>] "<filename>"
     Save labels to a file.  If no memory space is specified, all of the labels are saved.

show_labels [<memspace>]
     Display current label mappings.  If no memory space is specified, show all labels.

Miscellaneous commands
======================

exit
     Leave the monitor and return to execution.

print <expression>
     Evaluate the specified expression and output the result.

quit
     Exit the emulator immediately.

~ <number>
     Display the specified number in decimal, hex, octal and binary.

c1541
*****

VICE is provided with a complete stand-alone disk image maintenance utility, called c1541.  You can either invoke it from the command line or from within one of the VICE emulators, using the ``Run c1541'' command which will open a new xterm window with a running c1541 in it.

The syntax is:

     c1541 OPTIONS IMAGE

If some OPTIONS but no IMAGE are specified, c1541 runs in batch mode; otherwise, it attaches the IMAGE if present and enters interactive mode, where you can type commands that are executed when you press Enter (abbreviations are allowed).  As with the monitor, file name completion and command line editing with history are provided via GNU readline.  Use the command quit to exit.

Notice that c1541 always creates X64 files, but can read and write D64 and T64 files automatically, without the need for any special options.

c1541 commands and options
==========================

Each command-line option has an interactive-mode counterpart, that is shown after it.  - as a file name stands for standard input or standard output, depending on the context.

-attach  IMAGE

attach  IMAGE
     Attach the disk image IMAGE for use.  All the following commands will refer to this image.

-detach

detach
     Detach the currently attached disk image.

-format  IMAGE 'NAME,ID'

format  IMAGE 'NAME,ID'
     Format the D64 disk image IMAGE, giving the specified label.  If IMAGE does not exist, create it.

-gcr  IMAGENAME ['NAME,ID']

gcrformat  IMAGE 'NAME,ID'
     Create a GCR disk image; if NAME,ID is specified, format it.

-delete  IMAGE FILES...

delete  FILES...
     Delete  FILES  from IMAGE.

-list  IMAGE

list
     List files in IMAGE.

-validate  IMAGE

validate
     Validate the disk.

-copy  IMAGE OLDNAME1 [OLDNAME2...] NEWNAME

copy  OLDNAME1 [OLDNAME2...] NEWNAME
     Concatenate OLDNAME1, OLDNAME2.. into NEWNAME on IMAGE (can be used to copy files).

-create  IMAGE DUMP ['DESCR']

create  IMAGE DUMP ['DESCR']
     Build IMAGE from raw dump file DUMP (i.e. convert from D64 to X64 file).

-tape  IMAGE TAPEIMAGE [FILES...]

tape  IMAGE TAPEIMAGE [FILES...]
     Transfer FILES from TAPEIMAGE to IMAGE (default is copy all files).

-read  IMAGE 1541NAME [FSNAME]

read  1541NAME [FSNAME]
     Extract 1541NAME from the disk image into FSNAME (1541NAME by default) from IMAGE.

-extract  IMAGE

extract
     Extract all files from IMAGE.

-write  IMAGE FSNAME [1541NAME]

write  FSNAME [1541NAME]
     Write FSNAME to IMAGE as 1541NAME (FSNAME by default). (works with P00 files as well)

-block  [DRIVE:] [TRACK] [SECTOR] [DISP]

block  [DRIVE:] [TRACK] [SECTOR] [DISP]
     Show disk blocks in hex format.

-info  IMAGE ['DESCRIPTION']

info  ['DESCRIPTION']
     Show version information about IMAGE.

-unlynx IMAGE LYNXFILE

unlynx LYNXFILE
     Unlynx LYNXFILE into the image.

-zcreate  IMAGE DUMP ['DESCR']

zcreate IMAGE DUMP ['DESCR']
     Build IMAGE from a Zipcoded image made up of files called 1!DUMP, 2!DUMP, 3!DUMP, 4!DUMP.

When more than one command is specified in batch mode, all of them are executed in the same order they have on the command line.

Acknowledgments
***************

VICE derives from X64, the first Commodore 64 emulator for the X Window System.  Here is an informal list of the people who were mostly involved in the development of X64 and VICE:

The VICE core team:

  * Ettore Perazzoli (ettore@comm2000.it) made the 6510, VIC-II, VIC-I and CRTC emulations, part of the hardware-level 1541 emulation, speed optimizations, bug fixes, the event-driven cycle-exact engine, the Xt/Xaw/Xfwf-based GUI for X11, a general code reorganization, the new resource handling, most of the documentation and the MS-DOS port (well, somebody had to do it).

  * Teemu Rantanen (tvr@cs.hut.fi) implemented the SID emulation and the trap-based disk drive and serial bus implementation; added support for multiple display depths under X11.

  * André Fachat (fachat@physik.tu-chemnitz.de) wrote the PET emulators, the CIA and VIA emulation, the IEEE488 interface, implemented the IEC serial bus in xvic and made tons of bug fixes.

  * Daniel Sladic (sladic@eecg.toronto.edu) started the work on hardware-level 1541 emulation and wrote the new monitor introduced with VICE 0.15.

  * Andreas Boose (boose@linux.rz.fh-hannover.de) gave lots of information and bug reports about the VIC-II, the 6510 and the CIAs; moreover, he wrote several test-routines that were used to improve the emulation.  Also contributed some important patches, fixed several problems in the 1541 emulation, implemented the SpeedDOS parallel cable emulation and added cartridge support.

Former team members:

  * Jouko Valta (jopi@stekt.oulu.fi) wrote petcat and c1541, T64 handling, user service and maintenance (most of the work in x64 0.3.x was made by him); retired from the project in July 96, after VICE 0.10.0.

  * Jarkko Sonninen (sonninen@lut.fi) was the founder of the project, wrote the old version of the 6502 emulation and the XDebugger, and retired from the project after x64 0.2.1.

External contributors:

  * Michael Schwendt (sidplay@geocities.com) helped with the SID (audio) chip emulation, bringing important suggestions and bug reports, as well as the wave tables and filter emulation from his SIDplay emulator.

  * Christian Bauer (bauec002@goofy.zdv.uni-mainz.de) wrote the very interesting ``VIC article'' from which we got invaluable information about the VIC-II chip: without this, the VIC-II implementation would have not been possible.

  * Wolfgang Lorenz wrote an excellent 6510 test suite that helped us to debug the CPU emulation.

  * Giuliano Procida (gpp10@cam.ac.uk) is the maintainer of the VICE deb package for the Debian distribution.

  * Marko Mäkelä (msmakela@nic.funet.fi) wrote lots of CPU documentation.

  * Martin Pottendorfer (Martin.Pottendorfer@aut.alcatel.at) implemented the ``Contents'' button in the file selector and provided us with several suggestions and constant testing of constantly broken snapshots.

  * Chris Sharp (sharpc@hurlsey.ibm.com) wrote the AIX sound driver.

  * Krister Walfridsson (cato@df.lth.se) implemented joystick and sound support for NetBSD.

  * Dag Lem (resid@nimrod.no) implemented an alternative cycle-exact SID emulator (reSID), and contributed a bugfix in our SID emulation.

  * Peter Andrew Felvegi aka Petschy (petschy@derceto.sch.bme.hu) fixed a couple of bugs in the fast serial emulation.

  * Olaf Seibert (rhialto@polder.ubc.kun.nl) contributed some PET, and disk drive patches.

  * Daniel Fandrich (dan@fch.wimsey.bc.ca) contributed some disk drive patches.

  * Heiko Selber (selber@fhi-berlin.mpg.de) contributed some VIC20 I/O patches.

  * Steven Tieu (stieu@physics.ubc.ca) added initial support for 16/24 bpp X11 displays.

  * Alexander Lehmann (alex@mathematik.th-darmstadt.de) added complete support for all the VIC20 memory configurations for the old VICE 0.12.

  * Lionel Ulmer implemented joystick support for Linux and a first try of a SID emulation for SGI machines.

  * Bernhard Kuhn (kuhn@eikon.e-technik.tu-muenchen.de) made some joystick improvements for Linux.

  * Gerhard Wesp (gwesp@cosy.sbg.ac.at) contributed the extract command in c1541.

  * Ricardo Ferreira (storm@esoterica.pt) contributed the unlynx and system commands in c1541.

  * Tomi Ollila (Tomi.Ollila@tfi.net) donated findpath.c.

  * Richard Hable (hab@fim.uni-linz.ac.at) contributed the initial version of the REU Emulation.

  * Vesa-Matti Puro (vmp@lut.fi) wrote the very first 6502 CPU emulator in x64 0.1.0. That was the beginning of the story...

  * Dan Miner (dminer@nyx10.cs.du.edu) contributed some patches to the fast disk drive emulation.

  * Frank Prindle (Frank.Prindle@lambada.oit.unc.edu) contributed some patches.

  * Peter Weighill (stuce@csv.warwick.ac.uk) gave many ideas and contributed the ROM patcher.

  * Dominique Strigl (strigl@sxb.bsf.alcatel.fr), Craig Jackson (Craig.Jackson@lambada.oit.unc.edu) and Lasse Jyrkinen ((Lasse.Jyrkinen@uz.kuleuven.ac.be) contributed miscellaneous patches in the old X64 times.

  * Per Olofsson (MagerValp@Goth.Org) digitalized the C64 colors used in the default palette.

  * Paul David Doherty (h0142kdd@rz.hu-berlin.de) wrote zip2disk, on which the Zipcode support in c1541 is based.

  * Robert H. Forsman Jr., Brian Totty (totty@cs.uiuc.edu) and Robert W. McMullen (rwmcm@orion.ae.utexas.edu) provided the widget set for implementing the Xaw GUI.

  * Shawn Hargreaves (shawn@talula.demon.co.uk) wrote Allegro, the graphics and audio library used in the MS-DOS version.

(We hope we have not forgotten anybody; if you think we have, please tell us.)

Thanks also to everyone else for sending suggestions, ideas, bug reports, questions and requests.  In particular, a warm thank goes to the following people:

  * Lutz Sammer

  * Ralph Mason (RALPHM@msmail02.liffe.com)

  * George Caswell (timbuktu@the-eye.res.wpi.edu)

  * Per Olofsson (MagerValp@goth.org)

  * Jasper Phillips (philljas@newt.cs.orst.edu)

  * Luca Forcucci (frk@geocities.com)

  * Asger Alstrup (alstrup@diku.dk)

  * Bernhard Schwall (uzs484@uni-bonn.de)

  * Salvatore Valente (svalente@mit.edu)

  * Arthur Hagen (art@broomstick.com)

  * Douglas Carmichael (dcarmich@mcs.com)

  * Ferenc Veres (lion@c64.rulez.org)

Last but not least, a very special thank to Andreas Arens, Lutz Sammer, Edgar Tornig, Christian Bauer, Wolfgang Lorenz, Miha Peternel and Per Hâkan Sundell for writing cool emulators to compete with.  :-)

Copyright
*********

Copyright (C) 1996-1998 Ettore Perazzoli

Copyright (C) 1996-1998 André Fachat

Copyright (C) 1993-1994, 1997-1998 Teemu Rantanen

Copyright (C) 1997-1998 Daniel Sladic

Copyright (C) 1998 Andreas Boose

Copyright (C) 1993-1996 Jouko Valta

Copyright (C) 1993-1994 Jarkko Sonninen

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

Contact information
*******************

VICE home page
==============

You can find the latest news about VICE at the official VICE home page:

     http://www.tu-chemnitz.de/~fachat/vice/vice.html

Also the public patches and beta releases will be available there as well, so you might want to have a look at it periodically.  If you are going to report a bug, please check those pages first; it is possible that the problem you encountered has already been fixed with a newer version.

How to send feedback
====================

If you want to report bugs, make suggestions or contribute to the project, please email one of the following people:

  * Teemu Rantanen (tvr@cs.hut.fi) for the SID stuff;

  * Andreas Boose (boose@linux.rz.fh-hannover.de) for the 1541 disk drive;

  * André Fachat (fachat@physik.tu-chemnitz.de) for the PETs;

  * Ettore Perazzoli (ettore@comm2000.it), the current maintainer, for everything else.

It's always nice to receive feedback and/or bugreports about VICE, but please read these few notes before sending mail to anybody in the team.

  * Please put the word VICE in all capitals in your subject line (e.g. VICE fails to run game XXX).  This helps mail splitting and reduces chances that your message is unintentionally deleted, forgotten or lost.

  * Please don't send any HTML mail (we really hate that!).  If you use M$ Outlook or Netscape Communicator, make sure you turn off the "rich text" (HTML) feature.

  * Please don't send any binaries without asking first.

  * Please read the following documents carefully before reporting a bug or a problem you cannot solve:

       * the VICE documentation (you are reading it!);

       * the VICE FAQ (it is available on the Internet, and reachable from the VICE home page: http://www.tu-chemnitz.de/~fachat/vice/vice.html);

       * the comp.emulators.cbm and comp.sys.cbm FAQs (see FAQs you should read).

  * When you report a bug, please try to be as accurate as possible and describe how it can be reproduced to the very detail.  You should also tell us what machine you are running on, what operating system you are using as well as the version of it.

  * Please don't ask us how to transfer original C64 disk or tapes to your PC; this has been asked a gazillion times through email.  To transfer disks, you can use the Star Commander (http://ludens.elte.hu/~sta/sc.html).  And no, you cannot read C64 disks with your old 5"1/4 PC drive.

  * Please don't ask us where to find games for the emulator on the Internet.

  * Please don't ask us when the next version will be out, because we really don't know.

  * Please write in English, or in the language of the person you are writing to (Ettore is Italian, André and Andreas are German, Teemu is Finnish, Daniel is from Canada).

In any case, we would be really glad to receive your comments about VICE.

Thanks!

How to contribute
=================

If you want to make a major contribution, please ask first.  It has already happened a couple of times that somebody started working at something that had already been done but not released to the public yet, and we really do not want anybody to waste time.

If you are going to make a patch, please make sure the patch is relative to the very latest version, and provide us with the following:

  * a diff file containing all the changes you have made (diff -c or diff -u (better) is fine; please don't use plain diff);

  * GNU-style ChangeLog entries with a description of the changes you have made (look at the ChangeLogs provided with the original VICE sources for an example).

This is very important, and makes adding patches much smoother and safer.

People willing to port VICE to other platforms are always welcome.  A Windows and a MacOS port are in the works, so if you are interested in those platforms, please let us know.  There is plenty of work to do and any sort of help can be very useful.

Interesting newsgroups
======================

There are some Usenet newsgroups you might be interested in:

  * comp.emulators.cbm, discussing about emulators of Commodore 8-bit machines (definitely not Amiga emulators).

  * comp.sys.cbm, discussing various topics regarding real Commodore 8-bit machines.  This newsgroup is mainly for people who actually use original Commodore equipment (so please don't talk about emulation here).

  * comp.emulators.misc, discussing emulators in general.

FAQs you should read
====================

We recommend reading the comp.emulators.cbm and comp.sys.cbm FAQs, which are posted regularly on the corresponding newsgroups and are also available via FTP from ftp://rtfm.mit.edu.