This is Info file vice.info, produced by Makeinfo version 1.68 from the
input file vice.texi.

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.


File: vice.info,  Node: Top,  Next: License,  Prev: (dir),  Up: (dir)

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

* Menu:

* License::                     The GNU General Public License gives you
                                permission to redistribute this program
                                on certain terms; and also explains that
                                there is no warranty.

* Preface::                     Fundamental concepts.

* Usage::                       Invoking the emulators.
* System files::                Files needed to emulate.

* Basics::                      Simple things you can do.

* Settings and resources::      Emulator parameters you can change.

* Machine-specific features::   Peculiar characteristics of the emulators.

* Snapshots::                   Save the emulator state in one file
* Monitor::                     The VICE built-in monitor.
* c1541::                       The disk-image maintenance utility.

* File formats::                Technical description of file formats.

* Acknowledgments::             People involved in VICE.
* Copyright::                   Legal stuff.
* Contacts::                    Official home page, email addresses...

* Concept Index::
* Resource Index::


File: vice.info,  Node: License,  Next: Preface,  Prev: Top,  Up: Top

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

                         Version 2, June 1991

     Copyright (C) 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.


File: vice.info,  Node: Preface,  Next: Usage,  Prev: License,  Up: Top

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

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

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

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

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

   *Notice:* This documentation is written for the Unix release of VICE.

* Menu:

* C64 emulator features::
* C128 emulator features::
* VIC20 emulator features::
* PET emulator features::
* CBM-II emulator features::
* Keyboard emulation::
* Joystick emulation::
* Disk drive emulation::
* Supported file formats::
* Common problems::


File: vice.info,  Node: C64 emulator features,  Next: C128 emulator features,  Prev: Preface,  Up: Preface

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.  The emulation has been fully cycle-accurate since
version 0.13.0.

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

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


File: vice.info,  Node: C128 emulator features,  Next: VIC20 emulator features,  Prev: C64 emulator features,  Up: Preface

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

   The C128 emulator, called `x128', features a complete emulation of
the internal MMU ("Memory Management Unit"), 80 column VDC screen, fast
IEC bus emulation, Z80 emulation plus all the features of the C64
emulation.  The following things are missing, though:

   * 2 MHz mode;


File: vice.info,  Node: VIC20 emulator features,  Next: PET emulator features,  Prev: C128 emulator features,  Up: Preface

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

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

   Sound support is implemented, but is still at an experimental stage.
If you think it could be improved and know how to do so, feel free to
contact us (*note Contacts::.).

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


File: vice.info,  Node: PET emulator features,  Next: CBM-II emulator features,  Prev: VIC20 emulator features,  Up: Preface

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

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

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

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

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

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

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

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

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

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


File: vice.info,  Node: CBM-II emulator features,  Next: Keyboard emulation,  Prev: PET emulator features,  Up: Preface

CBM-II emulator features
========================

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

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

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

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

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

   The different settings are described in *note CBM-II model::..


File: vice.info,  Node: Keyboard emulation,  Next: Joystick emulation,  Prev: CBM-II emulator features,  Up: Preface

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

   There are two ways of emulating the keyboard in VICE.

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

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

   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 `RESTORE' key is mapped to `Page Up' (or `Prev') by default.


File: vice.info,  Node: Joystick emulation,  Next: Disk drive emulation,  Prev: Keyboard emulation,  Up: Preface

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 for joystick use, known as "numpad"
and "custom".

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

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


File: vice.info,  Node: Disk drive emulation,  Next: Supported file formats,  Prev: Joystick emulation,  Up: Preface

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

   All the emulators support up to 4 external disk drives as devices 8,
9, 10 and 11.  Each of these devices can emulate virtual Commodore
1541, 1541-II, 1571, 1581, 2031, 2040, 3040, 4040, 1001, 8050 and 8250
drives in one of four 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 giving you the use of files
     without having to copy them to disk images; this also allows you to
     read and write files in the `P00' format (again, consult the
     `comp.emulators.cbm' FAQ for more info).

   * accessing a real device connected to the host machine. As of VICE
     1.11 it is possible to connect real drives like Commodore 1541 to
     the printer port of the host using the XA1541 or XM1541 cable.
     Currently this only works on Linux using the OpenCBM library. You
     can get it from http://www.lb.shuttle.de/puffin/cbm4linux.

   * directly using the disk drive of the host. The 3.5" disk drive of
     the host can be used to read or write Commodore 1581 formatted
     disks. Currently this raw drive access feature is only available
     for Linux hosts.

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

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

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

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

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

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

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

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

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

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


File: vice.info,  Node: Supported file formats,  Next: Common problems,  Prev: Disk drive emulation,  Up: Preface

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

   VICE supports the most popular Commodore file formats:

   * `X64' (preferred) or `D64' disk image files; Used by the 1541,
     2031, 3040, 4040 drives.

   * `G64' GCR-encoded 1541 disk image files;

   * `D67' CBM2040 (DOS1) disk image format

   * `D71' VC1571 disk image format

   * `D81' VC1581 disk image format

   * `D80' CBM8050 disk image format

   * `D82' CBM8250/1001 disk image format

   * `T64' tape image files (read-only);

   * `P00' program files;

   An utility (`c1541', *note c1541::.) is provided to allow transfers
and conversions between these formats.

   Notice that the use of the `X64' file format is depreciated now.

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

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

   *Note File formats::. for a technical description of the supported
file formats.


File: vice.info,  Node: Common problems,  Prev: Supported file formats,  Up: Preface

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

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

* Menu:

* Sound problems::
* Shared memory problems::
* Printer problems::
* PET keyboard problems::


File: vice.info,  Node: Sound problems,  Next: Shared memory problems,  Prev: Common problems,  Up: Common problems

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

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

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

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


File: vice.info,  Node: Shared memory problems,  Next: Printer problems,  Prev: Sound problems,  Up: Common problems

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 (*note Video
options::.).  This will completely disable usage of the MITSHM
extensions, that are normally used to speed up the emulation window
updates.  Of course, this will also result in a big loss in speed.

   Reasons for this failure could be:

   * IPC support has been disabled at the system level; 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 (i.e.,
     the emulator runs on one machine, and the output is displayed on
     another machine that works as an X terminal) and for some reason
     VICE does not recognize this fact.  In this case, you have found a
     bug, so please report it to us.

   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.


File: vice.info,  Node: Printer problems,  Next: PET keyboard problems,  Prev: Shared memory problems,  Up: Common problems

Printer problems
----------------

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

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


File: vice.info,  Node: PET keyboard problems,  Prev: Printer problems,  Up: Common problems

PET keyboard problems
---------------------

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

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


File: vice.info,  Node: Usage,  Next: System files,  Prev: Preface,  Up: Top

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

   The names of the available emulators are:

   * `x64', the C64 emulator

   * `x128', the C128 emulator

   * `xvic', the VIC20 emulator

   * `xpet', the PET emulator

   * `xplus4', the PLUS4 emulator

   * `xcbm2', the CBM-II 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' since VICE provides a lot of
debugging information that is sent to the terminal and has built-in
monitor that also appears there.  For example, you could do

     xterm -e x64

* Menu:

* Command-line initialization::
* Command-line autostart::


File: vice.info,  Node: Command-line initialization,  Next: Command-line autostart,  Prev: Usage,  Up: Usage

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 and will be described in
detail later (*note Settings and resources::. for a complete list).  The
remaining options are used only to give usage information or to
initialize the emulator in some way:

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

`-default'
     Set default resources (*note 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' (*note 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.


File: vice.info,  Node: Command-line autostart,  Prev: Command-line initialization,  Up: Usage

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"

   If you specify a raw CBM or P00 file, the emulator will setup the
file system based drive emulation so that it is enabled and accesses the
directory containing the file first.  This is a very convenient way to
start multi-file programs stored in file system directories and not
requiring "true" drive emulation.

   *Note Disk and tape images::. for more information about images and
autostart.

