File: vice.texi

package info (click to toggle)
vice 1.19-1etch1
links: PTS
area: contrib
in suites: etch
size: 27,132 kB
ctags: 33,406
sloc: ansic: 257,145; cpp: 13,395; sh: 3,674; makefile: 3,380; perl: 1,801; yacc: 622; lex: 258; asm: 4
file content (7878 lines) | stat: -rw-r--r-- 253,507 bytes
parent folder | download | duplicates (2)
\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename vice.info
@settitle VICE Manual
@c %**end of header

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

@c @setchapternewpage odd
@setchapternewpage off

@c @iftex
@c @set CHAPTER chapter
@c @end iftex

@c @ifinfo
@c @set CHAPTER node
@c @end ifinfo

@c Theoretically, this should not be needed.  But my makeinfo does not
@c understand it.
@ifinfo
@macro uref{PARAM}
\PARAM\
@end macro
@end ifinfo

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

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

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.

@end ifinfo

@titlepage

@title VICE, the Versatile Commodore Emulator

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2006 Andreas Boose
Copyright @copyright{} 1998-2006 Dag Lem
Copyright @copyright{} 1998-2006 Tibor Biczo
Copyright @copyright{} 1999-2006 Andreas Dehmel
Copyright @copyright{} 1999-2006 Andreas Matthies
Copyright @copyright{} 1999-2006 Martin Pottendorfer
Copyright @copyright{} 2000-2006 Spiro Trikaliotis
Copyright @copyright{} 2005-2006 Marco van den Heuvel
Copyright @copyright{} 1999-2005 Thomas Bretz
Copyright @copyright{} 2003-2005 David Hansel
Copyright @copyright{} 2000-2004 Markus Brenner

Copyright @copyright{} 1997-2001 Daniel Sladic
Copyright @copyright{} 1996-1999 Ettore Perazzoli
Copyright @copyright{} 1996-1999 Andr Fachat
Copyright @copyright{} 1993-1994, 1997-1999 Teemu Rantanen
Copyright @copyright{} 1993-1996 Jouko Valta
Copyright @copyright{} 1993-1994 Jarkko Sonninen

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.

@end titlepage

@c @ifinfo
@node Top, License, (dir), (dir)
@c @top Version

@c Last updated @value{lastupdate}.
@c @end ifinfo

@ifinfo

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

@end ifinfo

@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::              
@end menu

@node License, Preface, Top, Top
@chapter GNU GENERAL PUBLIC LICENSE

@center Version 2, June 1991

@display
Copyright @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.
@end display

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

@iftex
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifinfo
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifinfo

@enumerate 0
@item
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.

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

@item
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:

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

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

@item
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.)
@end enumerate

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.

@item
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:

@enumerate a
@item
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,

@item
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,

@item
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.)
@end enumerate

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.

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

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

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

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

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

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

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

@iftex
@vskip -@baselineskip
@vskip -@baselineskip
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

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

@item
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 enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo

@page
@unnumberedsec 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.

@smallexample
@var{one line to give the program's name and an idea of what it does.}
Copyright (C) 19@var{yy}  @var{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.
@end smallexample

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:

@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{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.
@end smallexample

The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than @samp{show w} and
@samp{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:

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

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end group
@end example

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.

@node Preface, Usage, License, Top
@chapter About VICE

VICE is the one and only @dfn{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.

@strong{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 @emph{first}, as
that kind of information is not available here.  @xref{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 @emph{efficiently}.

Please do @emph{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.

@emph{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::             
@end menu


@node C64 emulator features, C128 emulator features, Preface, Preface
@section C64 emulator features

The C64 emulator, called @samp{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.


@node C128 emulator features, VIC20 emulator features, C64 emulator features, Preface
@section C128 emulator features

The C128 emulator, called @samp{x128}, features a complete emulation of
the internal MMU (@dfn{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:

@itemize @bullet
@item
2 MHz mode;
@end itemize


@node VIC20 emulator features, PET emulator features, C128 emulator features, Preface
@section 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 (@pxref{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 @code{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 @code{SYS45065}.


@node PET emulator features, CBM-II emulator features, VIC20 emulator features, Preface
@section 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 @file{PETdoc} file.
@c FIXME: link!

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 @code{$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 @samp{-petram9} and @samp{-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 @file{PETdoc} for more information.
@c FIXME link!

The SuperPET also is a PET 8032 with an expansion board.  It can map 4k
at a time out of 64k into the @code{$9***} 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 @code{0} and @code{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 @code{-model MODEL} option, where
@code{MODEL} can be one of a list of PET model numbers, all
described in @pxref{PET model}
@c FIXME link!


@node CBM-II emulator features, Keyboard emulation, PET emulator features, Preface
@section 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 @code{B128} and @code{B256}, in Europe as
@code{CBM 610}, @code{CBM 620} (low-profile case) or @code{CBM 710} and
@code{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 @code{CBM 630} and @code{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 @code{B128} and the @code{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 @code{LDA (zp),Y} and @code{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 @pxref{CBM-II model}.

@node Keyboard emulation, Joystick emulation, CBM-II emulator features, Preface
@section The keyboard emulation

There are two ways of emulating the keyboard in VICE.

The default way (@dfn{symbolic mapping}) is to map every key
combination to the corresponding key combination on the real machine:
for example, if you press @key{*}, which is bound to @kbd{Shift-8} on a
U.S. keyboard, in the C64 emulator, the emulated machine will have just
the @emph{unshifted} @key{*} key pressed (as @key{*} is unshifted on the
C64 keyboard).  Likewise, pressing @key{'} on the same U.S. keyboard
without any shift key will cause the combination @kbd{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 @key{CTRL} is mapped
to @key{Tab} and that the @key{Commodore} key is mapped to the left
@key{Control}). The @key{RUN/STOP} key is mapped to the @key{ESC} key
on the PC keyboard. The PET emulator, lacking the @key{Commodore} key
but having an @key{ESC} key, uses the left @key{Control} key as
@key{RUN/STOP} and the @key{ESC} key as @key{ESC} of course.

@c (@dots{}) FIXME: we need the detailed list here.

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

@strong{Warning:} unlike the real C64, VICE ``presses'' the @key{Shift}
key @emph{together} with the key to shift when the @key{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, @kbd{F6} (which on the real C64 is obtained with
@kbd{Shift + F5}) could be recognized as @kbd{F5}.  In that case, use
the shift key manually (i.e., type @kbd{Shift + F5} in the example).
Yes, we know this is a bug.

The @kbd{RESTORE} key is mapped to @kbd{Page Up} (or @kbd{Prev}) by
default.


@node Joystick emulation, Disk drive emulation, Keyboard emulation, Preface
@section 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 @dfn{numpad}
and @dfn{custom}.

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

The @dfn{custom} layout uses the keys @key{w}, @key{e}, @key{r},
@key{s}, @key{d}, @key{f}, @key{x}, @key{c}, @key{v} for the directions
and @key{space} for the fire button instead.


@node Disk drive emulation, Supported file formats, Joystick emulation, Preface
@section 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:

@itemize @bullet
@item
using disk images, i.e., files that contain a dump of all the blocks
contained in a real floppy disk (if you want more information about
what a disk image is, consult the
@code{comp.emulators.cbm} FAQ);
@item
accessing file system directories, thus giving you the use of files
without having to copy them to disk images; this also allows you to
read and write files in the @code{P00} format (again, consult the
@code{comp.emulators.cbm} FAQ for more info).
@item
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 or Windows using the OpenCBM library. You can
get it from @uref{http://www.lb.shuttle.de/puffin/cbm4linux} (cbm4linux,
Linux version) or from @uref{http://cbm4win.sf.net/} (cbm4win, Windows
version).

@item
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.
@end itemize

When using disk images there are two available types of drive
emulation.  One of them the @dfn{virtual drive} emulation.  It does
@emph{not} really emulate the serial line, but patches the kernal ROM
(with the so-called @dfn{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 @dfn{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 @dfn{hardware level} emulation
does. When the @dfn{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.

The PETs do not use a serial IEC bus to communicate with the floppy
drive but instead use the parallel IEEE488 bus.  This does
@emph{byte by byte} transfers, as opposed to the @emph{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 @code{dos1001} is
needed. The DOS version used is 2.7.

@node Supported file formats, Common problems, Disk drive emulation, Preface
@section Supported file formats

VICE supports the most popular Commodore file formats:

@itemize @bullet

@item
@code{X64} (preferred) or @code{D64} disk image files; Used by the 1541, 2031, 3040, 4040 drives.

@item
@code{G64} GCR-encoded 1541 disk image files;

@item
@code{D67} CBM2040 (DOS1) disk image format

@item
@code{D71} VC1571 disk image format

@item
@code{D81} VC1581 disk image format

@item
@code{D80} CBM8050 disk image format

@item
@code{D82} CBM8250/1001 disk image format

@item
@code{T64} tape image files (read-only);

@item
@code{P00} program files;

@end itemize

An utility (@code{c1541}, @pxref{c1541}) is provided to allow transfers
and conversions between these formats.

Notice that the use of the @code{X64} file format is depreciated now.

@cindex Converting X64 files into D64
You can convert an @code{X64} file back into a @code{D64} file with the
UNIX @code{dd} command:

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

@xref{File formats}. for a technical description of the supported file
formats.

@node Common problems,  , Supported file formats, Preface
@section 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::
@end menu

@node Sound problems, Shared memory problems, Common problems, Common problems
@subsection 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.

@cindex HP-UX and Solaris audio problems
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@dots{}

@cindex OSS/Linux problems
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.


@node Shared memory problems, Printer problems , Sound problems, Common problems
@subsection Shared memory problems

@cindex MITSHM
@cindex -mitshm, +mitshm
If you cannot start VICE because you get errors about shared memory, try
to run it with the @samp{+mitshm} command-line option (@pxref{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:

@itemize @bullet
@item
IPC support has been disabled at the system level; some system
administrators disable this for security reasons.  If @emph{you} are the
system administrator, use a kernel that has IPC support compiled in and
enabled.
@item
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.
@end itemize

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

@node Printer problems, PET keyboard problems ,Shared memory problems, Common problems
@subsection 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 @code{OPEN 1,4}
is not seen on the IEC bus. Also a @code{CLOSE 1} after that
is not seen. VICE can see from printing that there was an @code{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 @code{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.

@node PET keyboard problems, ,Printer problems, Common problems
@subsection 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.

@node Usage, System files, Preface, Top
@chapter Invoking the emulators

The names of the available emulators are:

@itemize @bullet

@item
@code{x64}, the C64 emulator

@item
@code{x128}, the C128 emulator

@item
@code{xvic}, the VIC20 emulator

@item
@code{xpet}, the PET emulator

@item
@code{xplus4}, the PLUS4 emulator

@item
@code{xcbm2}, the CBM-II emulator

@end itemize

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 @code{xterm} or @code{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

@example
xterm -e x64
@end example


@menu
* Command-line initialization::  
* Command-line autostart::      
@end menu

@node Command-line initialization, Command-line autostart, Usage, Usage
@section 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 (@pxref{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:

@table @code
@cindex -help
@item -help
@cindex -?
@itemx -?
List all the available command-line options and their meaning.
@cindex -default
@item -default
Set default resources (@pxref{Settings and resources}).  This will
override all the settings specified before, but not the settings
specified afterwards on the command line.
@cindex -autostart
@item -autostart IMAGE
Autostart @file{IMAGE} (@pxref{Command-line autostart}).
@cindex -1
@item -1 NAME
Attach @file{NAME} as a tape image file.
@cindex -8
@item -8 NAME
@cindex -9
@itemx -9 NAME
@cindex -10
@itemx -10 NAME
@cindex -11
@itemx -11 NAME
Attach @file{NAME} as a disk image to device 8, 9, 10 or 11.
@end table


@node Command-line autostart,  , Command-line initialization, Usage
@section Autostarting programs from the command-line

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

@example
x64 lovelygame.x64.gz
@end example

will start the C64 emulator, attaching @file{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
(@samp{:}) the name itself to the argument; for example

@example
x64 "lovelygame.x64.gz:run me"
@end example

will run the program named @file{run me} on @file{lovelygame.x64.gz}
instead of the first one.

@cindex -autostart
Using the command-line option @code{-autostart} is equivalent; so the same
result can be obtained with

@example
x64 -autostart "lovelygame.x64.gz:run me"
@end example

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.

@xref{Disk and tape images}. for more information about images and
autostart.


@node System files, Basics, Usage, Top
@chapter System files

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

@itemize @bullet

@item
the @dfn{system ROMs}, raw binary files containing copies of the original ROMs
of the machine you are emulating;

@item
the @dfn{keyboard maps}, text files describing the keyboard layout;

@item
the @dfn{palette files}, text files describing the colors of the machine you
are emulating.

@item
the @dfn{romset files}, text files describing the different ROMs to load.

@end itemize

The place where they will be searched for depends on the value of the
@code{Directory} resource, which is a colon (@code{:})-separated search
path list, like the @sc{unix} @code{PATH} environment variable.  The
default value is

@example
PREFIX/lib/vice/EMU:$HOME/.vice/EMU:BOOTPATH/EMU
@end example

Where @code{PREFIX} is the installation prefix (usually
@file{/usr/local}), @code{EMU} is the name of the emulated machine
(@code{C64}, @code{C128}, @code{PET}, @code{CBM-II} or @code{VIC20}) and
@code{BOOTPATH} is the directory where the executable resides.
The disk drive ROMs are looked for in a directory with @code{EMU} set to 
@code{DRIVES}. @code{$HOME} is the user's home directory.

For example, if you have the C64 emulator installed in

@example
/usr/local/bin/x64
@end example

then the value will be

@example
/usr/local/lib/vice/C64:$HOME/.vice/C64:/usr/local/bin/C64
@end example

And system files will be searched for under the following directories,
in the specified order:

@enumerate 1
@item
@code{/usr/local/lib/VICE/C64}
@item
@code{$HOME/.vice/C64}
@item
@code{/usr/local/bin/C64}
@end enumerate

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 @file{./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 (@pxref{Resource
files}).

@menu
* ROM files::                   Files containing dumps of the original ROMs.
* Keymap files::                Files describing the keyboard layout.
* Palette files::               Files defining the machine's colors.
* Romset files::                Files defining the machine's ROM set.
@end menu

@node ROM files, Keymap files, System files, System files
@section ROM files

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

@itemize @bullet

@item
@file{kernal},  the Kernal ROM (8 KBytes)

@item
@file{basic}, the Basic ROM (8 KBytes)

@item
@file{chargen}, the character generator ROM (4 Kbytes)

@end itemize

The C128 needs the following files:

@itemize @bullet

@item
@file{kernal}, the Kernal ROM (8 Kbytes)

@item
@file{basic}, the Basic + Editor ROM (32 Kbytes)

@item
@file{chargen}, the character generator ROM (4 Kbytes)

@end itemize

The C128, VIC20 and C64 emulators also need the following DOS ROMs for
the hardware-level emulation of the 1541, 1571 and 1581 disk drives:

@itemize @bullet

@item
@file{dos1541}, the 1541 drive ROM (16 Kbytes)

@item
@file{dos1541II}, the 1541-II drive ROM (16 Kbytes)

@item
@file{dos1571}, the 1571 drive ROM (32 Kbytes)

@item
@file{dos1581}, the 1581 drive ROM (32 Kbytes)

@end itemize

In addition to those all emulators can handle 
a parallel IEEE488 interface (the C64 and C128 via @code{$df**} extension,
the VIC20 via VIC1112 emulation)
so they also need the DOS ROM for the IEEE disk drives:

@itemize @bullet

@item
@file{dos2031}, the 2031 drive ROM (16 Kbytes)
(DOS 2.6, Commodore ROM images 901484-03 and 901484-05)

@item
@file{dos2040}, the 2040 drive ROM (8 Kbytes)
(DOS 1, Commodore ROM images 901468-06, 901468-07)

@item
@file{dos3040}, the 3040 drive ROM (12 Kbytes)
(DOS 2, Commodore ROM images 901468-11, 901468-12 and 901468-13)

@item
@file{dos4040}, the 4040 drive ROM (12 Kbytes)
(DOS 2, Commodore ROM images 901468-14, 901468-15 and 901468-16)

@item
@file{dos1001}, the 1001/8050/8250 drive ROM (16 Kbytes)
(DOS 2.7, Commodore ROM images 901887-01 and 901888-01)

@end itemize

Note that there are other DOS images on the internet. The DOS 2.5 images
might be used with the 8050, but it cannot handle the double sided drives
of the 1001 and 8250 and it is not supported by VICE.

The PET emulator uses an expanded setup, because there are three major 
versions of the Basic and the Kernal, and many versions of the 
Editor ROM. In addition there are cartridge ROM sockets.

The Kernal files contain the memory from range $F000-$FFFF, the Basic
ROMs either the range $C000-$DFFF or $B000-$DFFF.
To handle the different screen
sizes and keyboards, different so-called ``editor-ROMs'' for the memory
range $E000-$E800 are provided. 
The PET ROMs have the following names:

@itemize @bullet

@item
@file{kernal1}, the PET2001 Kernal ROM (4 KBytes)
(Commodore ROM images 901447-06 and 901447-07)
@item
@file{kernal2}, the PET3032 Kernal ROM (4 KBytes)
(Commodore ROM image 901465-03)
@item
@file{kernal4}, the PET4032/8032 Kernal ROM (4 KBytes)
(Commodore ROM image 901465-22)

@item
@file{basic1}, the PET2001 Basic 1 ROM (8 KBytes)
(Commodore ROM images 901447-09, 901447-02, 901447-03, 901447-04.bin.
The -09 ROM is the revised -01 ROM)
@item
@file{basic2}, the PET3032 Basic 2 ROM (8 KBytes)
(Commodore ROM images 901465-01 and 901465-01)
@item
@file{basic4}, the PET4032/8032 Basic 4 ROM (12 KBytes)
(Commodore ROM images 901465-23, 901465-20 and 901465-21. 
The -23 ROM is a revised -19 ROM)

@item
@file{edit1g}, the PET2001 editor for graphics keyboards (2 KBytes)
(Commodore ROM image 901447-05)
@item
@file{edit2b}, the PET3032 editor for business keyboards (2 KBytes)
(Commodore ROM image 901474-01)
@item
@file{edit2g}, the PET3032 editor for graphics keyboards (2 KBytes)
(Commodore ROM image 901447-24)
@item
@file{edit4g40}, the PET4032 editor for graphics keyboards (2 KBytes)
(Commodore ROM image 901498-01)
@item
@file{edit4b40}, the PET4032 editor for business keyboards (2 KBytes)
(Commodore ROM image 901474-02)
@item
@file{edit4b80}, the PET8032 editor for business keyboards (2 KBytes)
(Commodore ROM image 901474-04-?)
@item

@item
@file{chargen}, the character generator ROM (2k).  It has two sets
with 128 chars each.  The second (inverted) half of each set is computed from
the first half by inverting it.  This is a PET hardware feature.
(Commodore ROM image 901447-10)
@item
@file{chargen.de}, the character generator ROM (2k). This version is a 
patched German charset, with the characters [, \ and ] replaced by umlauts.
It has been provided by U. Guettich and he reports that it is supported
by some programs.
@end itemize

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 @code{-petrom9}, @code{-petromA} and
@code{-petromB} resp.

An alternative would be to specify a long kernal ROM with the
@code{-kernal} option that includes the extension ROM areas.

Also, you can specify replacements for the basic ROM at $B000-$DFFF
with the @code{-petromBasic} option and for the editor ROM
at $E000-$E7FF with the @code{-petromEditor} option.

The CBM-II emulator again uses another setup.  For those models the
kernal used is the same for all.  However, for different amounts of
memory exist different versions of the BASIC ROMs.  The 128k RAM version
(C610, C710, B128) uses one bank of 64k for the BASIC text and another
one for all the variables.  The 256k RAM version uses one bank for text,
one for variables, one for arrays and one for strings.

Also the character generator ROMs have a format different from the
above.  The other character ROMs have 8 bytes of pixel data per
character.  Those ROMs have 16 bytes per character instead.  The C6x0
only uses the first 8 of it, but the C7x0 uses 14 lines per character
and needs those increased ROMs.  Both ROMs hold, like the PET, two
character sets with 128 characters each.  Again the second half of the
full (256 char) character set is computed by inverting.

@itemize @bullet

@item
@file{kernal}, the KERNAL (8k) for the business machines (6xx/7xx)

@item
@file{kernal.500}, the KERNAL (8k) for the personal machine (510) (901234-02)

@item
@file{basic.128}, the CBM-II 128k BASIC (16k)

@item
@file{basic.256}, CBM-II 256k BASIC (16k)

@item
@file{basic.500}, C510 BASIC (16k) (901236-02 + 901235-02)

@item
@file{chargen.500}, character generator ROM for the C5x0 (4k) (901225-01)

@item
@file{chargen.600}, character generator ROM for the C6x0 (4k)

@item
@file{chargen.700}, character generator ROM for the C7x0 (4k)

@end itemize

@node Keymap files, Palette files, ROM files, System files
@section Keymap files

@dfn{Keymap files} are used to define the keyboard layout, defining which
key (or combination of keys) must be mapped to each keysym.

In other words, the keyboard emulation works like this: whenever the
user presses or releases a key while the emulation window has the input
focus, the emulator receives an X-Window event with a value that
identifies that key.  That value is called a @dfn{keysym} and is unique
to that key.  The emulator then looks up that keysym in an internal
table that tells it which key(s) to press or release on the emulated
keyboard.

This table is described by the keymap file, which is made up of lines
like the following:

@example
KEYSYM ROW COLUMN SHIFTFLAG
@end example

Where:

@itemize @bullet

@item
@code{KEYSYM} is a string identifying the keysym: you can use the
@code{xev} utility (shipped with the X Window system) to see what keysym
is bound to any key;

@item
@code{ROW} and @code{COLUMN} identify the key on the emulated keyboard;

@item
@code{SHIFTFLAG} can have one of the following values:

@itemize @bullet

@item
@code{0}: the key is never shifted;

@item
@code{1}: the key is shifted;

@item
@code{2}: the key is the left shift;

@item
@code{4}: the key is the right shift;

@item
@code{8}: the key can be (optionally) shifted by the user.

@end itemize

@end itemize

The @code{SHIFTFLAG} is useful if you want certain keys to be
``artificially'' shifted by the emulator, and not by the user.  For
example, @key{F2} is shifted on the C64 keyboard, but you might want it
to be mapped to the unshifted @key{F2} key on the PC keyboard.  To do
so, you just have to use a line like the following:

@example
F2 0 4 1
@end example

where @code{0} and @code{4} identify the key (row 0, column 4 on the
keyboard matrix), and @code{1} specifies that every time the user presses
@key{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:

@itemize @bullet

@item
@code{!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;

@item
@code{!LSHIFT}, @code{!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

@example
!LSHIFT 1 7
!RSHIFT 6 4
@end example

@end itemize

Any line starting with the @code{#} sign, instead, is completely
ignored.  This is useful for adding comments within the keymap file.

VICE keymap files have the @file{.vkm} default extension, and every
emulator comes with a default positional mapping and a default symbolic
mapping.


@node Palette files, Romset files, Keymap files, System files
@section Palette files

@dfn{Palette files} are used to specify the colors used in the
emulators.  They are made up of lines like the following:

@example
RED GREEN BLUE DITHER
@end example

where @code{RED}, @code{GREEN} and @code{BLUE} are hexadecimal values
ranging from 0 to FF and specifying the amount of red, green and blue
you want for each color and @code{DITHER} is a 4-bit hexadecimal number
specifying the pattern you want when rendering on a B/W display.

You have to include as many lines as the number of colors the emulated
machine has, and the order of the lines must respect the one used in the
machine (so the N'th line must contain the specifications for color N -
1 in the emulated machine).

Lines starting with the @code{#} 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:

@example
#
# VICE Palette file
#
# Syntax:
# Red Green Blue Dither
#

# Background
00 00 00 0

# Foreground
00 FF 00 F
@end example

@node Romset files, , Palette files, System files
@section Romset files

The Romset files are not used by default on all emulators. 
You might have recognized that the names of the ROM images are 
saved in resources. Loading a Romset file now just means a `shortcut'
to changing all the resources with ROM image names and reloading
the ROMs. 

The PET and CBM-II emulators use this feature to change between the
different ROM versions available for those machines. E.g. the 
Romset file for the PET 2001 is

@example
KernalName="pet2001"
EditorName=
ChargenName="chargen"
RomModule9Name=
RomModuleAName=
RomModuleBName=
@end example

As you can see, the file even uses the same syntax as the 
resource file, it is just a bit stripped down.

@node Basics, Settings and resources, System files, Top
@chapter Basic operation

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


@menu
* Emulation window::            The window the emulator runs in.
* Menus::                       Using emulator menus.
* Help::                        Getting help if you are stuck.
* File Selector::               Selecting files interactively.
* Disk and tape images::        Using virtual disks and tapes.
* Reset::                       Resetting the virtual machines.
@end menu

@node Emulation window, Menus, Basics, Basics
@section 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 @dfn{emulation
window}.  This window will be updated in real time, displaying the same
contents that a real monitor or TV set would.

Below 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
@dfn{status bar}.

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

On the extreme right of the status bar, there is a @dfn{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 emulating the drive LED and will display the current
track position of the drive's read/write head.

@node Menus, Help, Emulation window, Basics
@section Using the menus

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

Sometimes commands can be reached via @dfn{shortcuts} or @dfn{hotkeys},
i.e., it is possible to execute them by pressing a sequence of keys
instead of going through the menu with the mouse.  Where shortcuts
exist, they are displayed in parentheses at the right edge of the menu
item.  In VICE, all shortcuts must begin with the @key{Meta} or
@key{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
@key{Meta} (or @key{Alt}) and then @key{8}.

Note that no other key presses are passed on to the emulated machine
while either @key{Meta} or @key{Alt} are held down.


@node Help, File Selector, Menus, Basics
@section Getting help

At any time, if you get stuck or do not remember how to perform a
certain action, you can 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 @samp{make install}.

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


@node File Selector, Disk and tape images, Help, Basics
@section 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 allowing
you to select or specify a file interactively.

To the left of the file selector, there is a list of ancestor
directories: by clicking on them, you can ascend the directory tree.  To
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 the active selection.

At the top, there is a @dfn{directory box}, with the complete path of
the current directory, and a @dfn{file name box}, with the name of the
currently selected file.  At 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; e.g., @samp{~/*.[dx]64} will only show files in the home directory whose
name ends with either @file{.d64} or with @file{.x64}.


@node Disk and tape images, Reset, File Selector, Basics
@section Using disk and tape images

The emulator is able to emulate disk drives and (read-only) tape
recorders if provided with suitable @dfn{disk images} or @dfn{tape
images}.  An @dfn{image} is a raw dump of the contents of the media, and
must be @dfn{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: once 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:

@itemize @bullet

@item
Attach Disk Image
@item
Detach Disk Image
@item
Attach Tape Image
@item
Detach Tape Image
@item
Smart-attach a file

@end itemize

The first four commands are used to insert and remove the virtual disks
and cassettes 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 @code{D64} and @code{X64} for disk images (devices
8, 9 and 10) and @code{T64} for tape images.  Notice that @code{T64}
support is @emph{read-only}, and that the cassette is automatically
rewound when you reach its 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 (@pxref{Autostart}), this allows you to
autostart these particular files as well.

You can attach a disk for which you do not have write permissions: when this
happens, the 1541 emulator will emulate a write-protected disk.  This is
also useful if you want to prevent certain disk images from being
written to; in the latter case, just remove the write permission for
that file, e.g., by doing a @code{chmod a-w}.

@menu
* Previewing contents::         Looking into the image before attaching it.
* Autostart::                   Starting a program automagically.
* Compressed files::            Dealing with compressed files.
* Zipcode and Lynx::            Using Zipcoded ([1-4]!*) and Lynx files.
@end menu

@node Previewing contents, Autostart, Disk and tape images, Disk and tape images
@subsection Previewing the image contents

It is possible to examine the directory of a disk or tape image before
attaching it.  Just press the ``Contents'' button in the file selector
window and a new window will pop 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.


@node Autostart, Compressed files, Previewing contents, Disk and tape images
@subsection ``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 drive 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 do not lose compatibility once the program itself is
running.

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


@node Compressed files, Zipcode and Lynx, Autostart, Disk and tape images
@subsection Using compressed files

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

@itemize @bullet
@item
GNU Zip (@code{.gz} or @code{.z});
@item
BZip version 2 (@code{.bz2});
@item
PkZip (@code{.zip});
@item
GNU Zipped TAR archives (@code{.tar.gz}, @code{.tgz});
@item
Zoo (@code{.zoo}).
@end itemize

PkZip, @code{tar.gz}, @code{lha} and @code{zoo} support is
@emph{read-only} and always uses the @emph{first} @code{T64} or
@code{D64} file in the archive.  So archives containing multiple files
will always be handled as if they contain only a single file.

Windows and MSDOS don't contain the needful programs to handle
compressed archives. Get gzip and unzip for Windows at
@uref{ftp://ftp.freesoftware.com/pub/infozip/WIN32} and for MSDOS at
@uref{ftp://ftp.freesoftware.com/pub/infozip/MSDOS}. Don't use pkunzip
for MSDOS, it doesn't work. The programs to use BZip2 archives may be
found at @uref{http://sourceware.cygnus.com/bzip2}.
Just put the programs (unzip.exe, gzip.exe, bzip2.exe) into a directory
of your search path (e.g. C:\DOS or C:\WINDOWS\COMMAND; have a look at 
the PATH variable).

@node Zipcode and Lynx,  , Compressed files, Disk and tape images
@subsection Using Zipcode and Lynx images

Since version 0.15, the VICE emulators have been able to attach disks
packed with Zipcode or Lynx directly, removing the need to manually
convert them into @code{D64} or @code{X64} files with @code{c1541}.
This is achieved by automatically invoking @code{c1541}, letting it
decode the file into a temporary image and attaching the resulting
temporary image read-only.  For this to work, the directory containing
@code{c1541} must be in your @code{PATH}.

This uses the @code{-unlynx} and @code{-zcreate} options of @code{c1541}
(@pxref{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 @code{DEL} files properly).
So please use them with caution.

Lynx files usually come as @file{.lnx} files which are unpacked into
single disk images.  On the other hand, Zipcode files do not have a
particular extension (although @file{.z64} is sometimes used), and
represent a disk by means of component files, named as follows:

@itemize @bullet
@item
@file{1!NAME}
@item
@file{2!NAME}
@item
@file{3!NAME}
@item
@file{4!NAME}
@end itemize

If you attach as a disk image (or smart-attach) any one of these files,
the emulator will simply pick up the other three (by examining
the name) and then build a disk image using all four.


@node Reset,  , Disk and tape images, Basics
@section 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:

@itemize @bullet
@item
@dfn{soft reset}, which simply resets the CPU and all the other chips;
@item
@dfn{hard reset}, which also clears up the contents of RAM.
@end itemize

A @dfn{soft reset} is the same as a hardware reset achieved by pulling
the @sc{reset} line down; a @dfn{hard reset} is more like a power
on/power off sequence in that it makes sure the whole RAM is cleared.

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

This is especially the case for the CBM-II emulators.  Those machines
examine a memory location and if they find a certain "magic" value they
only do what you know from the C64 as @code{Run/Stop-Restore}.
Therefore, to really reset a CBM-II use hard reset.

@node Settings and resources, Machine-specific features, Basics, Top
@chapter Settings and resources

In the VICE emulators, all the settings are stored in entities known as
called @dfn{resources}.  Each resource has a name and a value which may
be either an integer or a string.  Integer values are often 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
@dfn{settings} menu), via command-line options or via the @dfn{resource
file}.

The @dfn{resource file} is a human-readable file containing resource
values: it is called @file{vicerc} and is stored in the directory 
@file{.vice/} in the user's home
directory.  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, at any time.  This is achieved with the ``Save settings'' and
``Load settings'' right menu items.  A third menu item, ``Restore
Default Settings'', can be used to reset all the values to the factory
defaults.

A special resource, @code{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.

@menu
* Resource files::              Format of resource files.
* Resources and command-line::  Specifying settings from the
                                command-line

* Performance settings::        Settings that affect speed of execution.
* Video settings::              Settings dealing with the video output.
* Keyboard settings::           Settings relative to the keyboard emulation.
* Sound settings::              Settings that control audio playback
* Drive settings::              Settings that control disk-drive emulation.
* Peripheral settings::         Settings for emulated external devices.
* RS232 settings::              Settings for the RS232 emulation.
* Misc settings::               Other settings.
@end menu

@node Resource files, Resources and command-line, Settings and resources, Settings and resources
@section 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 starts with the name of an
emulator in brackets (e.g., @samp{[C64]}) and ends when another section
starts or when the file ends.

Every line in a section has the following format:

@example
RESOURCE=VALUE
@end example

where @code{RESOURCE} is the name of a resource and @code{VALUE} is its
assigned value.  Resource names are case-sensitive and resource values
are either strings or integers.  Strings must start and end with a
double quote character (@code{"}), while integers must be given in
decimal notation.

Here is an example of a stripped-down @file{.vice/vicerc} file:

@example
[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
@end example

Notice that, when resource values are saved with ``Save settings'', the
emulator only modifies its own section, leaving the others unchanged.

@node Resources and command-line, Performance settings, Resource files, Settings and resources
@section Using command-line options to change resources

Resources can also be changed via command-line options.

Command-line options always override the defaults from @code{.vice/vicerc},
and their assignments last 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 back to the resource file.

Command-line options can begin with with a minus sign (@samp{-}) or
with a plus sign (@samp{+}).  Options beginning with a minus sign
may require an additional parameter, while the ones beginning with the
plus sign never require one.

Moreover, options beginning with a plus sign always have a counterpart
with the same name, but with a minus sign; in that case, the option
beginning with a minus sign is used to @emph{enable} a certain
feature, while the one beginning with a plus sign is used to
@emph{disable} the same feature (this is an X11 convention).  For
example, @code{-mitshm} enables support of MITSHM, while @code{+mitshm}
disables it.


@node Performance settings, Video settings, Resources and command-line, Settings and resources
@section Performance settings

@cindex Limiting emulation speed
It is possible to control the emulation speed by using the ``Maximum
speed'' menu item in the right-button menu.  The default setting is
@code{100}, which causes the emulation to never run faster than the real
machine.  A higher value allows the emulator to run faster, a lower one
may force it to run slower.  The setting ``No limit'' means to run as
fast as possible, without limiting speed.

@cindex Refresh rate
It is also possible to control the emulator's rate of frame update using
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.

Note that you cannot simultaneously specify ``Auto'' as the refresh rate
and ``No limit'' as the maximum speed..

@cindex Warp speed mode
Moreover, a special @dfn{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.

@menu
* Performance resources::       
* Performance options::         
@end menu

@node Performance resources, Performance options, Performance settings, Performance settings
@subsection Performance resources

@table @code

@vindex Speed
@item Speed
Integer specifying the maximum relative speed, as a percentage.  @code{0}
stands for ``no limit''.

@vindex RefreshRate
@item RefreshRate
Integer specifying the refresh rate; a value of @code{n} specifies a
refresh rate of 1/@code{n}.  A value of @code{0} enables automatic frame
skipping.

@vindex WarpMode
@item WarpMode
Booolean specifying whether ``warp mode'' is turned on or not.

@end table


@node Performance options,  , Performance resources, Performance settings
@subsection Performance command-line options

@table @code

@cindex -speed
@item -speed VALUE
Specifies the maximum speed as a percentage.  @code{0} stands for ``no
limit''.  (Same as setting the @code{Speed} resource.)

@cindex -refresh
@item -refresh VALUE
Specifies refresh rate; a value of @code{n} specifies a refresh rate of
1/@code{n}.  A value of @code{0} enables automatic frame skipping.
(Same as setting the @code{RefreshRate} resource.)

@cindex -warp, +warp
@item -warp
@itemx +warp
Enables/disables warp mode (@code{WarpMode=1}, @code{WarpMode=0}).

@end table


@node Video settings, Keyboard settings, Performance settings, Settings and resources
@section Video settings

The following right-button menu items control the video output.
On emulators that include two video chips (like @code{x128})
all options but XSync exist twice, once for each chip.
XSync is shared between the video chips.

@itemize @bullet

@cindex Video cache
@item
``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
network bandwidth required.  However, this setting can actually make the
emulator slower when there is little graphics activity and the amount of
work needed to maintain the cache is greater than the amount of work that
would be wasted by not using it (if any).

@cindex Double-size mode
@item
``Double Size'' toggles @dfn{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 closer to that of the
real thing.

@cindex Double-scan mode.
@item
``Double Scan'' toggles @dfn{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).

@cindex Using XSync()
@cindex Loosing control on low-end systems
@item
`Use XSync()'' causes the emulator to call the X11 function
@code{XSync()} before updating the emulation window: this might be
necessary on low-end systems to prevent it from consuming so many system
resources that it becomes impossible for the user to interact with it.

@end itemize


@menu
* Video resources::             
* Video options::               
@end menu

@node Video resources, Video options, Video settings, Video settings
@subsection Video resources

The following resources affect the screen emulation. The prefix of
some of the resources and commandline options denote the video chip 
the values apply to.

@table @code

@vindex VideoCache
@vindex CrtcVideoCache
@item VideoCache, CrtcVideoCache
Boolean specifying whether the video cache is turned on.

@vindex DoubleSize
@vindex CrtcDoubleSize
@item DoubleSize, CrtcDoubleSize
Boolean specifying whether double-size mode is turned on.

@vindex DoubleScan
@vindex CrtcDoubleScan
@item DoubleScan, CrtcDoubleScan
Boolean specifying whether double-scan mode is turned on.

@vindex UseXSync
@item UseXSync
Boolean specifying whether @code{XSync()} is called after updating the
emulation window.

@vindex MITSHM
@item MITSHM
Integer specifying 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.  You will
not be able to use these extensions if you are sitting at an X terminal
while running the emulator on a remote machine across a network.  Valid
values are: 0 = do not use MITSHM, 1 = do use MITSHM, -1 = try to
autodetect availability on startup (default).  The last is a simple test
if the emulator runs across a network and if so disables MITSHM (If you
have problems with this test please report it).

@vindex PrivateColormap
@item 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.

@vindex DisplayDepth
@item DisplayDepth
Integer specifying the depth of the host display.  The value @samp{0}
(the default) causes the emulator to autodetect it.

@vindex PaletteFile
@vindex CrtcPaletteFile
@item PaletteFile, CrtcPaletteFile
String specifying the name of the palette file being used.  The
@file{.vpl} extension is optional.

@end table


@node Video options,  , Video resources, Video settings
@subsection Video command-line options

@table @code

@cindex -vcache, +vcache
@item -vcache
@itemx +vcache
Enable/disable the video cache (@code{VideoCache=1}, @code{VideoCache=0}).

@cindex -dsize, +dsize
@item -dsize
@itemx +dsize
Enable/disable the double size mode (@code{DoubleSize=1},
@code{DoubleSize=0}).

@cindex -dscan, +dscan
@item -dscan
@itemx +dscan
Enable/disable the double scan mode (@code{DoubleScan=1},
@code{DoubleScan=0}).

@cindex -xsync, +xsync
@item -xsync
@itemx +xsync
Enable/disable usage of @code{XSync()} when updating the emulation
window (@code{UseXSync=1}, @code{UseXSync=0}).

@cindex -mitshm, +mitshm
@item -mitshm
@itemx +mitshm
Enable/disable usage of the MITSHM extensions (@code{MITSHM=1},
@code{MITSHM=0}).

@cindex -mitshmauto
@item -mitshmauto
Enable autodetection of MITSHM availability (@code{MITSHM=-1})

@cindex -install, +install
@item -install
@itemx +install
Enable/disable installation of a private colormap
(@code{PrivateColormap=1}, @code{PrivateColormap=0}).

@cindex -displaydepth
@item -displaydepth DEPTH
Specify the display depth (@code{DisplayDepth}).

@cindex -palette, -crtcpalette 
@item -palette NAME
@itemx -crtcpalette NAME
Specify @code{NAME} as the palette file (@code{PaletteFile},@code{CrtcPaletteFile}).

@end table


@node Keyboard settings, Sound settings, Video settings, Settings and resources
@section Keyboard settings

It is possible to specify whether the ``positional'' or ``symbolic''
keyboard mapping should be used with the ``Keyboard mapping type''
submenu (@pxref{Keyboard emulation} for an explanation of positional
and symbolic mappings).

The keyboard settings submenu also allows you to:

@itemize @bullet
@item
Load custom-made positional and symbolic keymap files
(``Set symbolic keymap file'' and ``Set positional keymap file'').
@item
Dump the current keymap to a user-defined keymap file (``Dump to keymap
file'').
@end itemize


@menu
* Keyboard resources::          
* Keyboard options::            
@end menu

@node Keyboard resources, Keyboard options, Keyboard settings, Keyboard settings
@subsection Keyboard resources

@table @code

@vindex KeymapIndex
@item KeymapIndex
Integer identifying which keymap is being used; @code{0} indicates
symbolic mapping, @code{1} positional mapping.  For the PET the even
values represent symbolic mapping, odd positional.  Then add @code{0}
for UK business keyboard or @code{2} for graphics keyboard.

@vindex KeymapSymFile
@item KeymapSymFile
String specifying the name of the keymap file for the symbolic mapping
(@pxref{Keyboard emulation}, all but PET and CBM-II).

@vindex KeymapPosFile
@item KeymapPosFile
String specifying the name of the keymap file for the positional mapping
(@pxref{Keyboard emulation}, all but PET and CBM-II).

@vindex KeymapBusinessUKSymFile KeymapBusinessUKPosFile
@item KeymapBusinessUKSymFile
@itemx KeymapBusinessUKPosFile
String specifying the name of the keymap file for the symbolic 
and positional mapping for the UK business keyboard
(@pxref{Keyboard emulation}, PET and CBM-II).

@vindex KeymapGraphicsSymFile KeymapGraphicsPosFile
@item KeymapGraphicsSymFile
@itemx KeymapGraphicsPosFile
String specifying the name of the keymap file for the symbolic and 
positional mapping for the graphics keyboard
(@pxref{Keyboard emulation}, PET only).

@vindex KeymapBusinessDESymFile KeymapBusinessDEPosFile
@item KeymapBusinessDESymFile
@itemx KeymapBusinessDEPosFile
String specifying the name of the keymap file for the symbolic 
and positional mapping for the German business keyboard.
(@pxref{Keyboard emulation}, PET only).

@end table


@node Keyboard options,  , Keyboard resources, Keyboard settings
@subsection Keyboard command-line options

@table @code

@cindex -keymap
@item -keymap N
Specifies which keymap is being used; @code{0} indicates symbolic
mapping, @code{1} positional mapping (as for the @code{KeymapIndex}
resource).

@cindex -symkeymap
@item -symkeymap NAME
Specify @file{NAME} as the symbolic keymap file (@code{KeymapSymFile}).

@cindex -poskeymap
@item -poskeymap NAME
Specify @file{NAME} as the positional keymap file (@code{KeymapPosFile}).

@cindex -buksymkeymap -bukposkeymap
@item -buksymkeymap NAME
@itemx -bukposkeymap NAME
Specify @file{NAME} as the symbolic/positional keymap file for the
UK business keyboard
(@code{KeymapBusinessUKSymFile}, @code{KeymapBusinessUKPosFile}, PET and CBM-II).

@cindex -grsymkeymap -grposkeymap
@item -grsymkeymap NAME
@itemx -grposkeymap NAME
Specify @file{NAME} as the symbolic/positional keymap file for the
graphics keyboard
(@code{KeymapGraphicsSymFile}, @code{KeymapGraphicsPosFile}, PET only).

@cindex -bdesymkeymap -bdeposkeymap
@item -bdesymkeymap NAME
@itemx -bdeposkeymap NAME
Specify @file{NAME} as the symbolic/positional keymap file for the
German business keyboard
(@code{KeymapBusinessDESymFile}, @code{KeymapBusinessDEPosFile}, PET only).

@end table


@node Sound settings, Drive settings, Keyboard settings, Settings and resources
@section Sound settings

The following menu items control sound output:

@itemize @bullet

@cindex Turning sound playback on/off
@item
``Enable sound playback'' turns sound emulation on and off.

@cindex Sound syncronization
@cindex Sound speed adjustment
@item
``Sound synchronization'' specifies the method for syncronizing the
sound playback.  Possible settings are:
@itemize @bullet
@item
``Flexible'', i.e., the audio renderer flexibly adds/removes samples to
the output to smoothly adapt the playback to slight changes in the speed
of the emulator.
@item
``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.
@item
``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.
@end itemize

@cindex Sample rate
@item
``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 nearest candidate will be chosen).

@cindex Audio buffer size
@cindex Sound buffer size
@item
``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.

@cindex Sound suspend time
@item
``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.

@cindex Oversampling
@item
``Oversample'' specifies an oversampling factor, from 1 to 8 times
(warning: this eats CPU cycles!).

@end itemize

@menu
* Sound resources::             
* Sound options::               
@end menu

@node Sound resources, Sound options, Sound settings, Sound settings
@subsection Sound resources

@table @code

@vindex Sound
@item Sound
Boolean specifying whether audio emulation is turned on.

@vindex SoundSpeedAdjustment
@item SoundSpeedAdjustment
Integer specifying what speed adjustment method the audio renderer should
use.  Possible values are:
@itemize @bullet
@item
@code{0}: ``flexible''
@item
@code{1}: ``adjusting''
@item
@code{2}: ``exact''
@end itemize

@vindex SoundSampleRate
@item 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 nearest candidate will be chosen).

@vindex SoundBufferSize
@item SoundBufferSize
Integer specifying the size of the audio buffer, in milliseconds.

@vindex SoundSuspendTime
@item SoundSuspendTime
Integer specifying the pause interval when audio underflows (``clicks'')
happen.  @code{0} means no pause is done.

@vindex SoundOversample
@item SoundOversample
Integer specifying the oversampling factor, ranging from @code{0} (no
oversampling) to @code{3} (8 times oversampling).

@vindex SoundDeviceName
@item SoundDeviceName
String specifying the audio driver.

Implemented drivers are:

@itemize @bullet
@item
@code{aix}, for the IBM AIX sound driver.
@item
@code{uss}, for the Linux/FreeBSD Universal Sound System driver
(@code{SoundDeviceArg} specifies the audio device, @file{/dev/dsp} by
default);
@item
@code{sgi}, for the Silicon Graphics audio device (@code{SoundDeviceArg}
specifies the audio device, @file{/dev/audio} by default);
@item
@code{sun}, for the Solaris audio device (unfinished;
@code{SoundDeviceArg} specifies the audio device, @file{/dev/audio} by
default).
@item
@code{hpux}, for the HP-UX audio device (unfinished;
@code{SoundDeviceArg} specifies the audio device, @file{/dev/audio} by
default).
@item
@code{sdl}, for the Simple DirectMedia Layer audio driver.
@item
@code{esd}, for EsounD, the Enlightened Sound Daemon; @code{SoundDeviceArg}
specifies the ESD server (@file{host:port}) to connect, empty by default.
@item
@code{dummy}, fully emulating the SID, but not actually playing samples.
@item
@code{dump}, writing all the write accesses to the registers to a file
(specified by @code{SoundDeviceArg}, default value is
@code{vicesnd.sid});
@item
@code{speed}, like @code{dummy} but also calculating samples (mainly
used to evaluate the speed of the sample generator);
@item
@code{fs}, writing samples to a file (specified by
@code{SoundDeviceArg}; default is @file{vicesnd.raw});
@end itemize

These drivers will actually be present only if the VICE configuration
script detected the corresponding devices at the time of compilation.

@vindex SoundDeviceArg
@item SoundDeviceArg
String specifying an additional parameter for the audio driver (see
@code{SoundDeviceName}).

@end table

@node Sound options,  , Sound resources, Sound settings
@subsection Sound command-line options

@table @code

@cindex -sound, +sound
@item -sound
@itemx +sound
Turns sound emulation on (@code{Sound=1}) and off (@code{Sound=0}).

@cindex -soundsync
@item -soundsync N
Specify @code{N} as the sound speed adjustment method
(@code{SoundSpeedAdjustment}).

@cindex -soundrate
@item -soundrate RATE
Specifies the sound playback sample rate (@code{SoundSampleRate}).

@cindex -soundbufsize
@item -soundbufsize SIZE
Specifies the size of the audio buffer in milliseconds
(@code{SoundBufferSize}).

@cindex -sounddev
@item -sounddev NAME
Specifies the name of the audio device (@code{SoundDeviceName}).

@cindex -soundarg
@item -soundarg ARG
Specifies an additional parameter for the audio device
(@code{SoundDeviceArg}).

@end table


@node Drive settings, Peripheral settings, Sound settings, Settings and resources
@section Drive settings

These settings are used to control the hardware-level emulation of the
drive.  When hardware-level emulation is turned on, only drives 8 and 9
are being emulated.

The following settings affect both drives:

@itemize @bullet

@item
``Enable true drive emulation'' enables the (slow) hardware-level
emulation of the drives for maximum compatibility.  This must be turned
on for any of the following settings to have effect.

@item
``Drive sync factor'' specifies the speed of the drive's 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:

@example
sync_factor = 65536 * clk_drive / clk_machine
@end example

where @code{clk_drive} and @code{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.

@end itemize

The following settings, instead, are specific of each drive:

@itemize @bullet

@item
``Drive model'' specifies the model of the drive being emulated.
@strong{Warning:} This will reset the drive.

@item
``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.

@item
``Idle method'' specifies which method the drive emulation should use to
save CPU cycles in the host CPU.  There are three methods:

@itemize @bullet
@item
@dfn{Skip cycles}: Each time the serial line is accessed by the C64, the
drive executes all the cycles since the last time it ran.  If
the number of elapsed cycles is larger than a certain value, the drive
discards part of them.
@item
@dfn{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.
@item
@dfn{No traps}: Like ``Trap idle'', but without any traps at all.  So
basically the drive works exactly as with the real thing, and nothing is
done to reduce the power needs of the drive emulation.
@end itemize

The first option (``Skip cycles'') is usually best for performance, as
the drive is emulated as little as possible; on the other hand, you may
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 will have no effect on
performance if a program continuously reads from the IEC port, as the
drive will have to be fully emulated in any case (some stupid programs
do this, even when they don't actually need to use the drive).

@c without this, texi2html strips our end-of-paragraph away.
@c maybe we should patch it?
@ifhtml
<P>
@end ifhtml

The second option (``Trap idle'') is usually a bit slower, as at least
interrupts are always emulated, but ensures the LED state is always
updated correctly and always keeps the drive and the computer in sync.
On the other hand, if a program installs a non-standard idle loop in the
drive, the drive CPU has to be emulated even when not necessary and the
global emulation speed is then @emph{much} slower.

@item
``40-track image support'' specifies how 40-track (``extended'') disk
images should be supported.  There are three possible ways:

@itemize @bullet
@item
``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);
@item
``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 he wants
the disk image to be extended or not;
@item
``Extend on access'' simply extends the disk image as soon the program
needs it, without prompting the user.
@end itemize

@end itemize


@menu
* Drive resources::             
* Drive options::               
@end menu

@node Drive resources, Drive options, Drive settings, Drive settings
@subsection Drive resources

@table @code

@vindex DriveTrueEmulation
@item DriveTrueEmulation
Boolean controlling whether the ``true'' drive emulation is turned on.

@vindex Drive8Type
@vindex Drive9Type
@item Drive8Type
@itemx Drive9Type
Integers specifying the model number for drives 8 and 9.  Possible values 
are @code{1541}, @code{1571}, @code{1581} and @code{2031}.

@vindex Drive8ParallelCable
@item Drive8ParallelCable
@vindex Drive9ParallelCable
@itemx Drive9ParallelCable
Booleans controlling whether the SpeedDOS-compatible cable is emulated or
not for drives 8 and 9.

@vindex Drive8ExtendImagePolicy
@item Drive8ExtendImagePolicy
@vindex Drive9ExtendImagePolicy
@itemx Drive9ExtendImagePolicy
Integer specifying the policy for 40-track support for drives 8 and 9.
Possible values are @code{0} (never extend), @code{1} (ask on extend),
@code{2} (extend on access).

@vindex Drive8IdleMethod
@item Drive8IdleMethod
@vindex Drive9IdleMethod
@itemx Drive9IdleMethod
Integers specifying the idling method for the drive CPU.  Possible values
are @code{0} (none), @code{1} (skip cycles), @code{2} (trap idle).
@xref{Drive settings}.

@vindex DriveSyncFactor
@item DriveSyncFactor
Integer specifying the drive's clock sync factor (@pxref{Drive
settings}).  Special values @code{-1} and @code{-2} mean PAL and NTSC,
respectively.

@vindex DosName1541
@item DosName1541
@vindex DosName1571
@itemx DosName1571
@vindex DosName1581
@itemx DosName1581
@vindex DosName2031
@itemx DosName2031
Strings specifying the names of the ROM images for the drive emulation.

@end table

@node Drive options,  , Drive resources, Drive settings
@subsection Drive command-line options

@table @code

@cindex -truedrive, +truedrive
@item -truedrive
@itemx +truedrive
Turns true drive emulation on (@code{DriveTrueEmulation=1}) and off
(@code{DriveTrueEmulation=0}), respectively.

@cindex -drive8type, -drive9type
@item -drive8type TYPE
@itemx -drive9type TYPE
Specifies the drive types for units 8 and 9, respectively.  Possible
values for @code{TYPE} are @code{1541}, @code{1571}, @code{1581} and
@code{2031}.

@cindex -parallel8, +parallel8, -parallel9, +parallel9
@item -parallel8
@itemx +parallel8
@itemx -parallel9
@itemx +parallel9
Turns emulation of the SpeedDOS-compatible parallel cable for 
disk unit 8 or 9 on
(@code{DriveXParallelCable=1}, X=8 or 9) and off 
(@code{DriveXParallelCable=0}), respectively.

@cindex -drive8idle, -drive9idle
@item -drive8idle NUM
@itemx -drive9idle NUM
Specifies @code{NUM} as the idling method in drives 8 and 9, respectively
(@code{Drive8IdleMethod}, @code{Drive9IdleMethod}).

@cindex -drive8extend, -drive9extend
@item -drive8extend NUM
@itemx -drive9extend NUM
Specifies @code{NUM} as the track 40 extend policy in drives 8 and 9, 
respectively
(@code{Drive8ExtendImagePolicy}, @code{Drive9ExtendImagePolicy}).

@cindex -paldrive
@item -paldrive
Specifies a PAL sync factor for the drive emulation
(@code{DriveSyncFactor=-1}).

@cindex -ntscdrive
@item -ntscdrive
Specifies an NTSC sync factor for the drive emulation
(@code{DriveSyncFactor=-2}).

@cindex -drivesync
@item -drivesync NUM
Specifies a generic sync factor for the drive emulation
(@code{True1541SyncFactor}).

@cindex -dos1541
@cindex -dos1571
@cindex -dos1581
@cindex -dos2031
@cindex -dos1001
@item -dos1541
@itemx -dos1571
@itemx -dos1581
@itemx -dos2031
@itemx -dos2040
@itemx -dos3040
@itemx -dos4040
@itemx -dos1001
Specify the ROM names for the 1541, 1571, 1581, 2031, 2040, 3040, 4040 
and 1001 emulation respectively.

@end table


@node Peripheral settings, RS232 settings, Drive settings, Settings and resources
@section Peripheral settings

VICE is able to support some special peripherals:

@itemize @bullet
@item
@dfn{file system devices}, pseudo-drives accessing the Unix file system;
@item
printers.
@end itemize

These features depend on some @dfn{kernal traps} that replace the
existing routines in the original Commodore operating system with
custom-made C routines.

@menu
* File system device settings::  Settings for file system devices.
* Printer settings::            Settings for emulating a printer.
* No kernal traps::             Disabling kernal traps completely.
@end menu

@node File system device settings, Printer settings, Peripheral settings, Peripheral settings
@subsection Settings for file system devices

These settings deal with the drive-like peripherals connected to the bus
of the emulated machine. 
The first setting relates to the parallel IEEE488 interface. With 
this interface a special engine is used to listen to the bus lines 
to translates them to the filesystem code. Thus the PET will always
detect a drive for example, but it can also use drives 10 and 11 even
together with true disk drive emulation. 

@itemize @bullet
@item
``Enable virtual devices'', enables the peripheral access via
the fast disk emulation (either kernal traps or IEEE488 interface). 
Both, filesystem and disk image access via fast
drive emulation, are affected.
@end itemize

Four peripherals, numbered from 8 to 11, are
accessible; each of them provides the following settings:

@itemize @bullet
@item
``File system access'', if enabled, allows the device to emulate a drive
accessing a file system directory; note that when a disk image is
attached to the same drive, the directory is no longer visible and the
attached disk is used instead.
@item
``File system directory'' specifies the directory to be accessed by the
drive.
@item
``Convert P00 file names'', if enabled, allows access to P00 files using
their built-in name instead of the Unix one.
@item
``Create P00 files on save'', if enabled, creates P00 files (instead of
raw CBM files) whenever a program creates a file.
@end itemize

Note that, by default, all drives except 11 create P00 files on save,
while drive 11 creates raw CBM files. Those files come without any header, 
but also with the filename restrictions given by the operating system
VICE runs on.

@menu
* File system device resources::  
* File system device options::  
@end menu


@node File system device resources, File system device options, File system device settings, File system device settings
@subsubsection Resources for file system devices


@table @code

@vindex FSDevice8ConvertP00
@item FSDevice8ConvertP00
@vindex FSDevice9ConvertP00
@itemx FSDevice9ConvertP00
@vindex FSDevice10ConvertP00
@itemx FSDevice10ConvertP00
@vindex FSDevice11ConvertP00
@itemx FSDevice11ConvertP00
Booleans specifying whether on-read support for P00 files is enabled on
drives 8, 9, 10 and 11 respectively (on by default).

@vindex FSDevice8SaveP00
@item FSDevice8SaveP00
@vindex FSDevice9SaveP00
@itemx FSDevice9SaveP00
@vindex FSDevice10SaveP00
@itemx FSDevice10SaveP00
@vindex FSDevice11SaveP00
@itemx FSDevice11SaveP00
Booleans specifying whether the drives should create P00 files instead
of plain CBM ones (on by default for drives 8-10, off for 11).

@vindex FSDevice8HideCBMFiles
@item FSDevice8HideCBMFiles
@vindex FSDevice9HideCBMFiles
@itemx FSDevice9HideCBMFiles
@vindex FSDevice10HideCBMFiles
@itemx FSDevice10HideCBMFiles
@vindex FSDevice11HideCBMFiles
@itemx FSDevice11HideCBMFiles
Booleans specifying whether non-P00 files should be invisible to
programs running in the emulator (do not hide by default).

@vindex FSDevice8Dir
@item FSDevice8Dir
@vindex FSDevice9Dir
@itemx FSDevice9Dir
@vindex FSDevice10Dir
@itemx FSDevice10Dir
@vindex FSDevice11Dir
@itemx FSDevice11Dir
Strings specifying the directories to which drives 8, 9, 10 and 11
have access.

@end table


@node File system device options,  , File system device resources, File system device settings
@subsubsection Command-line options for file system devices

@table @code

@cindex -fs8
@item -fs8 PATH
@cindex -fs9
@itemx -fs9 PATH
@cindex -fs10
@itemx -fs10 PATH
@cindex -fs11
@itemx -fs11 PATH
Specify the paths for the file system access on drives 8, 9, 10 and 11,
respectively (@code{FSDevice8Dir}, @code{FSDevice9Dir},
@code{FSDevice10Dir} and @code{FSDevice11Dir}).

@end table


@node Printer settings, No kernal traps, File system device settings, Peripheral settings
@subsection 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 @dfn{printer device file names}; a printer
device file name can be either a simple path, or a command name
preceeded by a pipe symbol @samp{|}.

For example, printer device @samp{filename} will cause the output to be
appended to the file @file{filename}, while printer device @samp{|lpr}
will cause the @code{lpr} command to be executed and be fed the printer
output.  The printer output will not be converted but saved as printed
by the emulated machine.

Up to three printer devices may be specified through the following
resources:

@itemize @bullet
@item
device 1, whose default value is @code{print.dump};
@item
device 2, whose default value is @code{|lpr}.
@item
device 3, whose default value is @code{|petlp -F PS|lpr};
@end itemize

So, basically, by default printer device 1 will dump printer
output to @file{print.dump}; printer device 2 will print it via
@code{lpr} directly to the printer and device 3 will print it via
@code{petlp} (a not-yet-complete utility that will produce Postscript
output from the Commodore printer code) and then to the printer via 
@code{lpr}.


@menu
* Printer resources::           
* Printer options::             
@end menu

@node Printer resources, Printer options, Printer settings, Printer settings
@subsubsection Printer resources

@table @code

@vindex PrDevice1
@item PrDevice1
@vindex PrDevice2
@itemx PrDevice2
@vindex PrDevice3
@itemx PrDevice3
Strings specifying the printer devices (@pxref{Printer settings}).

@vindex Printer4
@item Printer4
Boolean specifying if the IEC printer (device 4) is being emulated.

@vindex Printer4Dev
@item Printer4Dev
Integer (ranging from 0 to 2, for device 1-3) specifying what printer device 
(@pxref{Printer settings}) the IEC printer is using.

@vindex PrUser
@item PrUser
Boolean specifying if the user-port printer is being emulated.

@vindex PrUserDev
@item PrUserDev
Integer (ranging from 0 to 2, for device 1-3) specifying what printer 
device the user-port printer is using.

@end table

@node Printer options,  , Printer resources, Printer settings
@subsubsection Printer command-line options

@table @code

@cindex -prdev1
@item -prdev1 NAME
@cindex -prdev2
@itemx -prdev2 NAME
@cindex -prdev3
@itemx -prdev3 NAME
Specify @code{NAME} as printer devices 1, 2 and 3, respectively
(@code{PrDevice1}, @code{PrDevice2} and @code{PrDevice3}).

@cindex -printer4, +printer4
@item -printer4
@itemx +printer4
Enable/disable emulation of the IEC printer (@code{Printer4=1},
@code{Printer4=0}).

@cindex -pr4dev
@item -pr4dev DEV
Specify device for the IEC printer (@code{Printer4Dev}).

@cindex -pruser, +pruser
@item -pruser
@itemx +pruser
Enable/disable emulation of the IEC printer (@code{PrUser=1},
@code{PrUser=0}).

@cindex -pruserdev
@item -pruserdev DEV
Specify device for the IEC printer (@code{PrUserDev}).

@end table


@node No kernal traps,  , Printer settings, Peripheral settings
@subsection 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.

@menu
* No traps resources::          
* No traps options::            
@end menu

@node No traps resources, No traps options, No kernal traps, No kernal traps
@subsubsection Resources to control Kernal traps

@table @code

@vindex VirtualDevices
@item VirtualDevices
Boolean specifying whether all the mechanisms for virtual device
emulation should be enabled. Serial IEC devices use kernal traps, 
parallel IEEE488 devices use an own IEEE488 engine. Both are switched
on and off with this resource.

@end table


@node No traps options,  , No traps resources, No kernal traps
@subsubsection Command-line options to control Kernal traps

@table @code

@cindex -virtualdev, +virtualdev
@item -virtualdev
@itemx +virtualdev
Enable (@code{VirtualDevices=1}) or disable (@code{VirtualDevices=0}) 
virtual devices.

@end table

@c ----------------------------------------------------------------

@node RS232 settings, Misc settings, Peripheral settings, Settings and resources
@section RS232 settings

The VICE emulators can emulate the RS232 device most of the machines
have.  The C64, C128 and VIC20 emulators emulate the userport RS232
interface at 300 and 1200 baud.  The C64 and C128 can also use the 9600
baud interface by Daniel Dallmann, using the shift registers of the two
CIA 6526 chips.  The PET can have a 6551 ACIA RS232 interface when
running as a SuperPET, and the CBM-II has such an ACIA by default.  The
C64 and C128 emulators can emulate an ACIA 6551 (also known as Datapump
for example) as extension at @code{$de**}.

Emulation can be achieved by either:

@itemize @bullet
@item
connecting a real UNIX serial device;
@item
dumping to a file;
@item
piping through a process.
@end itemize

It is possible to define up to four UNIX serial devices, and then decide
which interface should be connected to which device.  This is done by
so-called @dfn{rs232 device file names}; an rs232 device file name can
be either a simple path, or a command name preceeded by a pipe symbol
@samp{|}.  If the path specifies a special device (e.g. @file{/dev/ttyS0}) it
is recognized by VICE and the emulator can set the baudrate.

For example, rs232 device @samp{filename} will cause the output to be
written (not appended) to the file @file{filename}, while printer device
@samp{|lpr} will cause the @code{lpr} command to be executed and be fed
the rs232 output.  The rs232 output will not be converted but saved as
sent by the emulated machine.  The same holds true for the rs232 input.
If the command writes data to the standard output it will be caught by VICE 
and sent back to the emulator.  Also the data sent by the pseudo device will
be sent back to VICE.

For example you can setup a null-modem cable between two serial ports
of your PC, setup one port for login and use the other in VICE.  Then you
can login from your emulator via the RS232 emulation and the null-modem
cable to your machine again.

You can not simply run a shell from VICE, as the shell will notice that
it does not run on its own pseudo terminal and will thus buffer its
output.  You need to write some program that opens an own pseudo terminal
and runs the shell from there (not yet finished).

Up to four RS232 devices may be specified through the following
resources:

@itemize @bullet
@item
device 1, whose default value is @code{/dev/ttyS0};
@item
device 2, whose default value is @code{/dev/ttyS1};
@item
device 3, whose default value is @code{rs232.dump};
@item
device 4, whose default value is @code{|lpr}.
@end itemize

For the first two devices you can change the baudrate the tty device is
set to by specifying it on the commandline or in the menu.  This
baudrate is 9600 by default for the latter two, but can be changed only
by resources (The baudrate is independent from the baudrate the emulator
actually expects).

@menu
* RS232 resources::             
* RS232 options::               
* RS232 usage::               
@end menu

@node RS232 resources, RS232 options, RS232 settings, RS232 settings
@subsection RS232 resources

@table @code

@vindex RsDevice1
@item RsDevice1
@vindex RsDevice2
@itemx RsDevice2
@vindex RsDevice3
@itemx RsDevice3
@vindex RsDevice4
@itemx RsDevice4
Strings specifying the RS232 devices (@pxref{RS232 settings}).

@vindex RsDevice1Baud
@item RsDevice1Baud
@vindex RsDevice2Baud
@itemx RsDevice2Baud
@vindex RsDevice3Baud
@itemx RsDevice3Baud
@vindex RsDevice4Baud
@itemx RsDevice4Baud
Integer specifying the RS232 baudrate devices if the device file points
to a special device (like @file{/dev/ttyS0}; @pxref{RS232 settings}).

@vindex AciaDE
@item AciaDE
Boolean specifying whether C64 or C128 should emulate ACIA 6551 in
I/O 1, at @code{$de**}.

@vindex Acia1Dev
@item Acia1Dev
Integer (ranging from 0 to 3, for device 1-4) specifying what RS232 device 
(@pxref{RS232 settings}) the ACIA is using (all except VIC20).

@vindex Acia1Irq
@item Acia1Irq
Integer specifying which interrupt to use. 0 = none, 1 = IRQ, 2 = NMI 
(C64 and C128 only)

@vindex RsUser
@item RsUser
Integer specifying if the user-port RS232 interface is being emulated and 
at which baudrate it should have for the emulator. 0 = off; > 0 specifies the
baudrate (C64, C128 and VIC20).

@vindex RsUserDev
@item RsUserDev
Integer (ranging from 0 to 3, for device 1-4) specifying what RS232 device 
the user-port interface is using (C64, C128 and VIC20).

@end table

@node RS232 options, RS232 usage, RS232 resources, RS232 settings
@subsection RS232 command-line options

@table @code

@cindex -rsdev1
@item -rsdev1 NAME
@cindex -rsdev2
@itemx -rsdev2 NAME
@cindex -rsdev3
@itemx -rsdev3 NAME
@cindex -rsdev4
@itemx -rsdev4 NAME
Specify @code{NAME} as RS232 devices 1, 2, 3 and 4, respectively
(@code{RsDevice1}, @code{RsDevice2} @code{RsDevice3} and @code{RsDevice4}).

@cindex -rsdev1baud
@item -rsdev1 BAUDRATE
@cindex -rsdev2baud
@itemx -rsdev2 BAUDRATE
@cindex -rsdev3baud
@itemx -rsdev3 BAUDRATE
@cindex -rsdev4baud
@itemx -rsdev4 BAUDRATE
Specify @code{BAUDRATE} as baudrate for the RS232 devices if the device name
specifies a special device (like @file{/dev/ttyS0} for example, 
@pxref{RS232 settings};
@code{RsDevice1Baud}, @code{RsDevice2Baud} @code{RsDevice3Baud} and 
@code{RsDevice4Baud}).

@cindex -acia1dev
@item -acia1dev
Specify device for the ACIA (@code{Acia1Dev}).

@cindex -rsuser
@item -rsuser BAUDRATE
Enable (BAUDRATE not 0) or disable (BAUDRATE = 0) emulation of the 
userport RS232 emulation (@code{RsUser}; C64, C128 and VIC20)

@cindex -rsuserdev
@item -rsuserdev DEV
Specify device for the userport RS232 emulation (@code{RsUserDev}; 
C64, C128 and VIC20).

@end table

@node RS232 usage, , RS232 options, RS232 settings
@subsection RS232 usage example

Here we give you a simple example how to set up an emulated C64 using
the modem connected to your PC. The following list shows each step.

@table @code
@item Attach your modem to your PC at a serial port. 
Normally you should set it up to use the modem as "/dev/modem".
@item start VICE

@item Setup VICE to use your modem as "serial device 1"
Go to the RS232 settings menu and change "Serial 1 device" to "/dev/modem" (or the device where you attached your modem to)
Then go to the RS232 settings menu and change "Serial 1 baudrate" to the baudrate your modem should run at.
  Watch out, e.g. on Linux there is an additional multiplier
  to multiply with the baudrate (so e.g. 19200 gives 115200 or so baud)
  See the "setserial" manpage on Linux for example. 
  However, most modems should be able to autodetect the speed to 
  the computer as well.

@item Select the RS232 emulation your programs use
If you want to use the Userport emulation, go to the RS232 settings and 
  change "Userport RS232 Device" to 
  "Serial 1". If you want ACIA emulation (swiftlink or what's it called?)
  then change "ACIA $DE** device" to "Serial 1".

@item Enable the emulation
  Go to the RS232 settings and select either "ACIA $DE** emulation"
  or Userport 300/1200 baud or CIA 9600 baud emulation.

@item Load your program and start it.
If it is able to detect an
  RS232 cartridge like swiftlink or so, try to detect the ACIA emulation
  if enabled. 
  Otherwise just set the baudrate to either 300, 1200 or 9600 according
  to what you enabled in the VICE menu for the userport.

@end table

@c ----------------------------------------------------------------

@node Misc settings,  , RS232 settings, Settings and resources
@section Miscellaneous settings

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

@menu
* Misc resources::              
* Misc options::                
@end menu

@node Misc resources, Misc options, Misc settings, Misc settings
@subsection Miscellaneous resources

@table @code
@vindex Directory
@item Directory
String specifying the search path for system files.  It is defined as a
sequence of directory names, separated by colons (@samp{:}), just like
the @code{PATH} variable in the shell.  The special string @samp{$$}
stands for the default search path, which is initialized at startup to
the following value:

@example
LIBDIR/EMUID:$HOME/.vice/EMUID:BOOTPATH/EMUID:LIBDIR/DRIVES:$HOME/.vice/DRIVES:BOOTPATH/DRIVES
@end example

where:

@itemize @bullet
@item
@code{LIBDIR} is the VICE installation directory (usually
@file{/usr/local/lib/vice}, @file{/usr/lib/vice} or
@file{/opt/vice/lib});
@item
@code{EMUID} is the emulation identification
string (@code{C64}, @code{C128}, @code{VIC20} or @code{PET});
@item
@code{BOOTPATH} is the directory where the binary lies (usually
@file{/usr/local/bin}, @file{/usr/bin} or @code{/opt/vice/bin}).
@item
@code{DRIVES} is the directory called "DRIVES", where the disk drive ROMs are.
(The disk drive ROMs are used by all emulators, so there is an extra
directory for them.)
@end itemize

Notice that the middle entry points to a default location in
the user's home directory. Here private ROM versions (e.g. 
speeddos or JiffyDos) can be stored for example.

@xref{System files}. for a description of the method used to load the
emulator's system files.

@vindex HTMLBrowserCommand
@item HTMLBrowserCommand
String specifying the command to run the help browser.  The help browser
can be any HTML browser, and every @samp{%s} in the string is replaced
with the name of the toplevel file of the VICE documentation.  For
example, the default value @samp{netscape %s} runs Netscape Navigator.

@vindex SaveResourcesOnExit
@item 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.

@vindex DoCoreDump
@item DoCoreDump
Boolean specifying whether the emulator should dump core when it gets a
signal.

@vindex JoyDevice1, JoyDevice2
@item JoyDevice1
@itemx JoyDevice2
Integer specifying which joystick device the emulator should use for
joystick emulation for ports 1 and 2, respectively
(0=None, 1=Numpad, 2=Custom keys, 3=Analog joystick 1, 4=Analog joystick 2,
5=Digital joystick 1, 6=Digital joystick 2 on Unix)
The available joysticks might differ depending on operating system and
joystick support in the OS (Linux joystick module must be 
available for example).

@end table


@node Misc options,  , Misc resources, Misc settings
@subsection Miscellaneous command-line options

@table @code
@cindex -directory
@item -directory SEARCHPATH
Specify the system file search path (@code{Directory}).
@cindex -htmlbrowser
@item -htmlbrowser COMMAND
Specify the command to run the HTML browser for the on-line help
(@code{HTMLBrowserCommand}).
@cindex -saveres, +saveres
@item -saveres
@itemx +saveres
Enable/disable automatic saving of settings on exit
(@code{SaveResourcesOnExit=1}, @code{SaveResourcesOnExit=0}).

@cindex -core, +core
@item -core
@itemx +core
Enable/disable generation of core dumps (@code{DoCoreDump=1},
@code{DoCoreDump=0}).

@cindex -joydev1, -joydev2
@item -joydev1
@itemx -joydev2
Set the device for joystick emulation of port 1 and 2, respectively
(@code{JoyDevice1}, @code{JoyDevice2}).
@end table


@node Machine-specific features, Snapshots, Settings and resources, Top
@chapter Machine-specific features

@menu
* C64/128-specific::            Commands and settings specific to the
                                C64/128 emulators
* VIC20-specific::              Commands and settings specific to the
                                VIC20 emulator
* PET-specific::                Commands and settings specific to the
                                PET emulator
* CBM-II-specific::             Commands and settings specific to the
				CBM-II emulator
@end menu

@node C64/128-specific, VIC20-specific, Machine-specific features, Machine-specific features
@section 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.

@menu
* C64 cartridges::              Using cartridge images with the C64 emulator.
* VIC-II settings::             Settings that control the video chip.
* SID settings::                Settings that control the audio chip.
* C64 I/O extension settings::  Settings that enable special extensions.
* C64/128 system ROM settings::  Settings to control the system ROMs.
@end menu

@node C64 cartridges, VIC-II settings, C64/128-specific, C64/128-specific
@subsection Using cartridge images

@dfn{Cartridge images} are like disk images, but mirror the contents of
cartridge ROM images instead of disk images.

X64 and X128 allow you to attach the following kinds of cartridges:

@itemize @bullet
@item
@file{.crt} images, as used by the CCS64 emulator by Per Hkan Sundell;
@item
generic raw dumps of 8K and 16K images;
@item
Action Replay images.
@item
Atomic Power images.
@item
Epyx fastload images.
@item
The Commodore IEEE488 interface cartridge
(@code{http://www.funet.fi/pub/cbm/schematics/cartridges/c64/ieee-488/eprom.bin})
@item
Retro Replay images.
@item
IDE64 interface cartridge.
(@code{http://www.volny.cz/dundera/})
@item
Super Snapshot 4 images.
@item
Super Snapshot 5 images.
@item
Expert Cartridge images.
@end itemize

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 a freezer cart like an Action Replay cartridge, you can
emulate the cartridge's freeze button with the ``Cartridge freeze''
command.

Attaching the IEEE488 cartridge automatically enables the IEEE488
interface emulation on the @code{$DF**} I/O ports.

Attaching the IDE64 cartridge automatically enables the IDE64
interface emulation on the @code{$DE**} I/O ports.

@node VIC-II settings, SID settings, C64 cartridges, C64/128-specific
@subsection VIC-II settings

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

@itemize @bullet

@cindex Sprite collision detection
@item
``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).

@cindex VIC-II color sets
@item
``Color set'' can be used to dynamically change the palette file
being used by choosing one of the available predefined color sets:

@itemize @bullet
@item
@file{default.vpl} (``default''), the default VICE palette;
@item
@file{c64s.vpl} (``C64S''), palette taken from the shareware C64S
emulator by Miha Peternel.
@item
@file{ccs64.vpl} (``CCS64''), palette taken from the shareware CCS64
emulator by Per Hkan Sundell.
@item
@file{frodo.vpl} (``Frodo''), palette taken from the free Frodo emulator
by Christian Bauer
(@uref{http://www.uni-mainz.de/~bauec002/FRMain.html}).
@item
@file{pc64.vpl} (``PC64''), palette taken from the free PC64 emulator by
Wolfgang Lorenz.
@item
@file{godot.vpl} (``GoDot''), palette as suggested by the authors of the
C64 graphics package GoDot
(@uref{http://users.aol.com/howtogodot/welcome.htm}).
@end itemize

@end itemize

@menu
* VIC-II resources::            
* VIC-II options::              
@end menu

@node VIC-II resources, VIC-II options, VIC-II settings, VIC-II settings
@subsubsection VIC-II resources

@table @code

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

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

@end table


@node VIC-II options,  , VIC-II resources, VIC-II settings
@subsubsection VIC-II command-line options

@table @code

@cindex -checkss, +checkss
@item -checkss
@itemx +checkss
Enable (@code{CheckSsColl=1}) and disable (@code{CheckSsColl=0})
emulation of hardware sprite-sprite collision detection, respectively.
@cindex -checkss, +checkss

@cindex -checksb, +checksb
@item -checksb
@itemx +checksb
Enable (@code{CheckSbColl=1}) and disable (@code{CheckSbColl=0})
emulation of hardware sprite-background collision detection,
respectively.

@end table


@node SID settings, C64 I/O extension settings, VIC-II settings, C64/128-specific
@subsection SID settings

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

@itemize @bullet

@cindex Second SID
@item
``Second SID'' maps a second SID chip into the address space for stereo
sound. This emulates e.g. the ``SID Symphony Stereo Cartridge'' from
Dr. Evil Laboratories. The second SID can be used with software such as
``Stereo SID Player'' by Mark Dickenson or ``The Enhanced Sidplayer'' by
Craig Chamberlain.

@cindex Second SID base address
@item
``Second SID base address'' sets the start address for the second SID
chip. Software normally uses $DE00 or $DF00, since $DE00-$DEFF and
$DF00-$DFFF can be mapped through the cartridge port of the C64. The
default start address is $DE00.

@cindex SID filters
@item
``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.

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

@cindex Toggling reSID emulation
@item
``Use reSID emulation'' specifies whether the more accurate (and
resource hungry) reSID emulation is turned on or off.

@cindex reSID samping method
@item
``reSID sampling method'' selects the method for conversion of the SID
output signal to a sampling rate appropriate for playback by standard
digital sound equipment. Possible settings are:
@itemize @bullet
@item
``Fast'' simply clocks the SID chip at the output sampling frequency,
picking the nearest sample. This yields acceptable sound quality, but
sampling noise is noticeable in some cases, especially with SID combined
waveforms. The sound emulation is still cycle exact.
@item
``Interpolating'' clocks the SID chip each cycle, and calculates each
sample with linear interpolation. The sampling noise is now strongly
attenuated by the SID external filter (as long as ``Emulate filters'' is
selected), and the linear interpolation further improves the sound
quality.
@item
``Resampling'' clocks the SID chip each cycle, and uses the
theoretically correct method for sample generation. This delivers CD
quality sound, but is extremely CPU intensive, and is thus most useful
for non-interactive sound generation. Unless you have a very fast
machine, that is.
@end itemize

@cindex reSID resampling passband
@item ``reSID resampling passband'' specifies the percentage of the
total bandwidth allocated to the resampling filter passband. The work
rate of the resampling filter is inversely proportional to the remaining
transition band percentage. This implies that e.g. with the transition
band starting at ~ 20kHz, it is faster to generate 48kHz than 44.1kHz
samples. For CD quality sound generation at 44.1kHz the passband
percentage should be set to 90 (i.e. the transition band starting at
almost 20kHz).

@end itemize

@menu
* SID resources::               
* SID options::                 
@end menu

@node SID resources, SID options, SID settings, SID settings
@subsubsection SID resources

@table @code

@vindex SidStereo
@item SidStereo
Boolean selecting emulation of a second SID.

@vindex SidStereoAddressStart
@item SidStereoAddressStart
Integer specifying the start address for the second SID.

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

@vindex SidModel
@item SidModel
Integer specifying what model of the SID must be emulated (@code{0}:
MOS6581, @code{1}: MOS8580).

@vindex SidUseResid
@item SidUseResid
Boolean specifying whether the accurate reSID emulation is being used.

@vindex SidResidSampling
@item SidResidSampling
Integer specifying the sampling method (@code{0}: Fast, @code{1}:
Interpolation, @code{2}: Resampling)

@vindex SidResidPassband
@item SidResidPassband
Integer specifying the resampling filter passband in percentage of the
total bandwidth (@code{0 - 90}).

@end table


@node SID options,  , SID resources, SID settings
@subsubsection SID command-line options

@table @code

@cindex -sidstereo
@item -sidstereo
Emulates a second SID chip for stereo sound (@code{SidStereo}).

@cindex -sidstereoaddress
@item -sidstereoaddress @code{ADDRESS}
Specifies the start address for the second SID chip
(@code{SidStereoAddressStart}).

@cindex -sidmodel
@item -sidmodel MODEL
Specifies @code{MODEL} as the emulated model of the SID chip
(@code{SidModel}).

@cindex -sidfilters, +sidfilters
@item -sidfilters
@itemx +sidfilters
Enable (@code{SidFilters=1}) or disable (@code{SidFilters=0}) emulation
of the built-in SID filters.

@cindex -resid, +resid
@item -resid
@itemx +resid
Enable (@code{SidFilters=1}) or disable (@code{SidFilters=0}) usage of
the reSID emulator.

@cindex -residsamp
@item -residsamp @code{METHOD}
Specifies the sampling method; fast (@code{SidResidSampling=0}),
interpolating (@code{SidResidSampling=1}), or resampling
(@code{SidResidSampling=2}).

@cindex -residpass
@item -residpass @code{PERCENTAGE}
Specifies the resampling filter passband in percentage of the total
bandwidth (@code{SidResidPassband=0-90}).

@end table


@node C64 I/O extension settings, C64/128 system ROM settings, SID settings, C64/128-specific
@subsection C64 I/O extension settings

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

@itemize @bullet

@cindex C64/128 emulator identification
@item
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.

@cindex REU
@item
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.

@cindex 1351 Mouse emulation
@item FIXME

@end itemize


@menu
* C64 I/O extension resources::  
* C64 I/O extension options::   
@end menu

@node C64 I/O extension resources, C64 I/O extension options, C64 I/O extension settings, C64 I/O extension settings
@subsubsection C64 I/O extension resources

@table @code

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

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

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

@end table


@node C64 I/O extension options,  , C64 I/O extension resources, C64 I/O extension settings
@subsubsection C64 I/O extension command-line options

@table @code

@cindex -ieee488, +ieee488
@item -ieee488
@itemx +ieee488
Enable (@code{IEEE488=1}) or disable (@code{IEEE488=0}) emulation of the
IEEE488 interface.

@cindex -reu, +reu
@item -reu
@itemx +reu
Enable (@code{REU=1}) or disable (@code{REU=0}) emulation of the
512K RAM Expansion Unit.

@cindex -emuid, +emuid
@item -emuid
@itemx +emuid
Enable (@code{EmuID=1}) or disable (@code{EmuID=0}) the emulation
identification extension.

@end table

@c @node RS232 settings, C64/128 system ROM settings, C64 I/O extension settings, C64/128-specific
@c @subsection RS232 settings
@c 
@c X64 and X128 can support RS232 in the following ways:
@c 
@c @itemize @bullet
@c @item
@c by emulating Daniel Dallmann's 9600 baud userport-based RS232 interface;
@c @item
@c by emulating a 6551-based RS232 interface located at $DE00.
@c @end itemize
@c 
@c Each of these emulated devices can be either:
@c 
@c @itemize @bullet
@c @item
@c connected a real UNIX serial device;
@c @item
@c dumped to a file;
@c @item
@c piped through a process.
@c @end itemize
@c 
@c It is possible to define up to two UNIX serial devices, and then decide
@c which interface should be connected to which device.  Devices are
@c defined through the following settings:
@c 
@c @itemize @bullet
@c @item
@c ``Serial 1 device@dots{}'' and ``Serial 2 device@dots{}'' are used to specify
@c the the pathnames of the serial devices, with the file selector;
@c @item
@c ``Serial 1 baudrate'' and ``Serial 2 baudrate'' specify the baudrate.
@c @end itemize
@c 
@c 
@c @menu
@c * RS232 resources::
@c * RS232 options::
@c @end menu
@c 
@c @node RS232 resources, RS232 options, RS232 settings, RS232 settings
@c @subsubsection RS232 resources
@c 
@c @table @code
@c 
@c @vindex RsDevice1
@c @item RsDevice1
@c @vindex RsDevice2
@c @itemx RsDevice2
@c Strings specifying the pathnames of the two available serial devices.
@c 
@c @vindex RsDevice1Baud
@c @item RsDevice1Baud
@c @vindex RsDevice2Baud
@c @itemx RsDevice2Baud
@c Integers specifying the baudrates.
@c 
@c @vindex RsDevice3
@c @item RsDevice3
@c String defining the name of the file used when dumping RS232 output.
@c 
@c @vindex RsDevice4
@c @item RsDevice4
@c String defining the name of the process to pipe the RS232 data through.
@c 
@c @vindex RsUser
@c @item RsUser
@c Boolean specifying whether the userport-based RS232 should be emulated.
@c 
@c @vindex Acia1
@c @item Acia1
@c Boolean specifying whether the ACIA-based RS232 should be emulated.
@c 
@c @vindex RsUserDev
@c @item RsUserDev
@c @vindex Acia1Dev
@c @itemx Acia1Dev
@c Integers specifying how the userport-based interface and the ACIA-based
@c one are emulated.  The possible values are:
@c @itemize @bullet
@c @item
@c @code{0}: connect to serial device number 1;
@c @item
@c @code{1}: connect to serial device number 2;
@c @item
@c @code{2}: dump to file;
@c @item
@c @code{3}: exec an external process.
@c @end itemize
@c @end table
@c 
@c @node RS232 options,  , RS232 resources, RS232 settings
@c @subsubsection RS232 command-line options
@c 
@c @table @code
@c 
@c @cindex -acia1, +acia1
@c @item -acia1
@c @itemx +acia1
@c Enable/disable emulation of the ACIA-based RS232 interface
@c (@code{Acia1=1}, @code{Acia1=0}).
@c 
@c @cindex -acia1dev
@c @item -acia1dev DEVICE
@c Specify @code{DEVICE} as the device for the ACIA-based RS232 emulation
@c (@code{Acia1Dev}).
@c 
@c @cindex -rsuser, +rsuser
@c @item -rsuser
@c @itemx +rsuser
@c Enable/disable emulation of the userport-based RS232 interface
@c (@code{RsUser=1}, @code{RsUser=0}).
@c 
@c @cindex -rsuserdev
@c @item -rsuserdev DEVICE
@c Specify @code{DEVICE} as the device for the ACIA-based RS232 emulation
@c (@code{RsUserDev}).
@c 
@c @end table
@c 

@node C64/128 system ROM settings,  , C64 I/O extension settings, C64/128-specific
@subsection 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.

@menu
* C64/128 system ROM resources::  
* C64/128 system ROM options::  
@end menu

@node C64/128 system ROM resources, C64/128 system ROM options, C64/128 system ROM settings, C64/128 system ROM settings
@subsubsection C64/128 system ROM resources

@table @code

@cindex KernalName
@item KernalName
String specifying the name of the Kernal ROM (default @file{kernal}).

@cindex BasicName
@item BasicName
String specifying the name of the Basic ROM (default @file{basic}).  In
the C128 emulator, the ROM image must actually include the editor ROM too.

@cindex ChargenName
@item ChargenName
String specifying the name of the character generator ROM (default
@file{chargen}).

@cindex KernalRev
@item 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:

@table @code
@item 0
Kernal revision 0;
@item 3
Kernal revision 3;
@item sx
@itemx 67
Commodore SX-64 ROM;
@item 100
@item 4064
Commodore 4064 (also known as ``PET64'' or ``Educator 64'') ROM.
@end table

@end table

@node C64/128 system ROM options,  , C64/128 system ROM resources, C64/128 system ROM settings
@subsubsection C64/128 system ROM command-line options

@table @code

@cindex -kernal
@item -kernal NAME
Specify @file{NAME} as the Kernal ROM file (@code{KernalName}).

@cindex -basic
@item -basic NAME
Specify @file{NAME} as the Basic ROM file (@code{BasicName}).

@cindex -chargen
@item -chargen NAME
Specify @file{NAME} as the character generator ROM file
(@code{ChargenName}).

@cindex -kernalrev
@item -kernalrev REVISION
Specify Kernal revision (@code{KernalRev}).

@end table


@node VIC20-specific, PET-specific, C64/128-specific, Machine-specific features
@section 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.

@menu
* VIC20 cartridges::            
* VIC20 memory expansions::     
* VIC20 system ROM settings::   
@end menu


@node VIC20 cartridges, VIC20 memory expansions, VIC20-specific, VIC20-specific
@subsection Using cartridge images

As with the C64 (@pxref{C64 cartridges}), it is possible to attach
several types of cartridge images:

@itemize @bullet
@item
4 or 8 Kbyte cartridges located at $2000;
@item
4 or 8 Kbyte cartridges located at $4000;
@item
4 or 8 Kbyte cartridges located at $6000;
@item
4 or 8 Kbyte cartridges located at $A000;
@item
4 Kbyte cartridges located at $B000.
@end itemize

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

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.

A special kind of cartridge file is where the two files mentioned
above are concatenated (with removing the two byte load address of
the second image) into one 16k image. There are only few of those
images, though. Normally the second part is located at $A000. 
Vice can now attach such concatenated files at the start address
$2000, $4000, and $6000. The second half of such an image is
moved to $A000. If you encounter 16k images that have the second
half not at $A000 you can split the image into two halfs 
(i.e. one 8194 byte and one 8192 byte, because the first has the load
address) and attach both files separately.

One cartridge that is currently only partially supported here is
the VIC1112 IEEE488 interface. You have to load the ROM as a cartridge,
but you also have to enable the IEEE488 hardware by menu.

@node VIC20 memory expansions, VIC20 system ROM settings, VIC20 cartridges, VIC20-specific
@subsection 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:

@itemize @bullet
@item
block 0 (3 Kbytes at $0400-$0FFF);
@item
block 1 (8 Kbytes at $2000-$3FFF);
@item
block 2 (8 Kbytes at $4000-$5FFF);
@item
block 3 (8 Kbytes at $6000-$7FFF);
@item
block 5 (8 Kbytes at $A000-$BFFF).
@end itemize

These blocks are called @dfn{expansion blocks} because they are not
present a stock (``unexpanded'') machine.  Each of them is associated to
a boolean @code{RamBlockX} resource (where @code{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:

@itemize @bullet
@item
no RAM expansion blocks at all;
@item
all RAM expansion blocks enabled;
@item
3K expansion (only block 0 is enabled);
@item
8K expansion (only block 1 is enabled);
@item
16K expansion (only blocks 1 and 2 are enabled);
@item
24K expansion (only blocks 1, 2 and 3 are enabled).
@end itemize

As with the X64 (@pxref{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.

@menu
* VIC20 memconf resources::     
* VIC20 memconf options::       
@end menu

@node VIC20 memconf resources, VIC20 memconf options, VIC20 memory expansions, VIC20 memory expansions
@subsubsection VIC20 memory configuration resources

@table @code

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

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

@end table

@node VIC20 memconf options,  , VIC20 memconf resources, VIC20 memory expansions
@subsubsection VIC20 memory configuration command-line options

@table @code

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

@itemize @bullet
@item
@code{none} (no extension);
@item
@code{all} (all blocks);
@item
@code{3k} (3k space in block 0);
@item
@code{8k} (first 8k extension block);
@item
@code{16k} (first and second 8k extension blocks);
@item
@code{24k} (first, second and 3rd extension blocks);
@item
@code{0}, @code{1}, @code{2}, @code{3}, @code{5} (memory in respective
blocks);
@item
@code{04}, @code{20}, @code{40}, @code{60}, @code{A0} (memory at
respective address.
@end itemize

For example,

@example
xvic -memory none
@end example

gives an unexpanded VIC20.  While

@example
xvic -memory 60,a0
@end example

or

@example
xvic -memory 3,5
@end example

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

@cindex -emuid, +emuid
@item -emuid
@itemx +emuid
Enable (@code{EmuID=1}) or disable (@code{EmuID=0}) the emulation
identification extension.

@end table


@node VIC20 system ROM settings,  , VIC20 memory expansions, VIC20-specific
@subsection 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.

@menu
* VIC20 system ROM resources::  
* VIC20 system ROM options::    
@end menu

@node VIC20 system ROM resources, VIC20 system ROM options, VIC20 system ROM settings, VIC20 system ROM settings
@subsubsection VIC20 system ROM resources

@table @code

@cindex KernalName
@item KernalName
String specifying the name of the Kernal ROM (default @file{kernal}).

@cindex BasicName
@item BasicName
String specifying the name of the Basic ROM (default @file{basic}).

@cindex ChargenName
@item ChargenName
String specifying the name of the character generator ROM (default
@file{chargen}).

@cindex CartridgeFile2000
@cindex CartridgeFile4000
@cindex CartridgeFile6000
@cindex CartridgeFileA000
@cindex CartridgeFileB000
@item CartridgeFile2000
@itemx CartridgeFile4000
@itemx CartridgeFile6000
@itemx CartridgeFileA000
@itemx CartridgeFileB000
String specifying the name of the respective cartridge ROM images.

@end table

@node VIC20 system ROM options,  , VIC20 system ROM resources, VIC20 system ROM settings
@subsubsection VIC20 system ROM command-line options

@table @code

@cindex -kernal
@item -kernal NAME
Specify @file{NAME} as the Kernal ROM file (@code{KernalName}).

@cindex -basic
@item -basic NAME
Specify @file{NAME} as the Basic ROM file (@code{BasicName}).

@cindex -chargen
@item -chargen NAME
Specify @file{NAME} as the character generator ROM file
(@code{ChargenName}).

@cindex -cart2
@cindex -cart4
@cindex -cart6
@cindex -cartA
@cindex -cartB
@item -cart2 NAME
@itemx -cart4 NAME
@itemx -cart6 NAME
@itemx -cartA NAME
@itemx -cartB NAME
Specify @file{NAME} as the cartridge image to attach.
(@code{CartridgeFile2000},...,@code{CartridgeFileB000}).

@end table


@node PET-specific, CBM-II-specific, VIC20-specific, Machine-specific features
@section 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.

@menu
* PET model::                   
* PET diagnostic pin::          
* PET commandline options::     
* PET colors::                  
@end menu

@node PET model, PET diagnostic pin, PET-specific, PET-specific
@subsection Changing PET model settings

With @code{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):

@table @code

@cindex RamSize
@item RamSize
Size of memory in kByte. 96k denotes a 8096, 128k a 8296.

@cindex IOSize
@item IOSize
Size of I/O area in Byte.  Either 2048 or 256 for 8296.

@cindex Crtc
@item Crtc
Enables CRTC 6545 emulation (all models from 40xx and above)

@cindex VideoSize
@item VideoSize
The number of columns on the screen (40 or 80).  A 0 auto-detects this
from the ROM.

@cindex Ram9
@item Ram9
The 8296 can map RAM into the address range $9***

@cindex RamA
@item RamA
The 8296 can map RAM into the address range $A***

@cindex SuperPET
@item SuperPET
This resource enables the SuperPET (MicroMainFrame 9000) I/O
and disables the 8x96 mappings.

@cindex Basic1
@item Basic1
If (by checksum) a version 1 kernal is detected, then the 
kernal ROM is patched to make the IEEE488 interface work.

@cindex Basic1Chars
@item Basic1Chars
Exchanges some character in the character ROM that have changed
between the first PET 2001 and all newer versions.

@cindex EoiBlank
@item EoiBlank
This resource enables the "blank screen on EOI" feature of the 
oldest PET 2001.

@cindex EmuID
@item EmuID
Enable emulator ID (at @code{$e8a0-$e8ff}, for use see C64).

@cindex DiagPin
@item DiagPin
Set the diagnositc pin on the PET userport (see below).

@cindex ChargenName
@item ChargenName
Specify @file{NAME} as the character generator ROM file

@cindex KernalName
@item KernalName
Specify @file{NAME} as the kernal ROM file.  This file contains the
complete BASIC, EDITOR and KERNAL ROMs and is either 16k (BASIC 1 and 2)
or 20k (BASIC 4) in size.

@cindex EditorName
@item EditorName
Specify @file{NAME} as the editor ROM file.  This file contains
an overlay for the editor ROM at $E000-$E7FF if necessary.

@cindex RomModule9Name
@item RomModule9Name
Specify @file{NAME} as the $9*** Expansion ROM file.  This file contains
an expansion ROM image of 4k.

@cindex RomModuleAName
@item RomModuleAName
Specify @file{NAME} as the $A*** Expansion ROM file.  This file contains
an expansion ROM image of 4k.

@cindex RomModuleBName
@item RomModuleBName
Specify @file{NAME} as the $B*** Expansion ROM file.  This file contains
an expansion ROM image of 4k.
This file overlays the lowest 4k of a BASIC 4 ROM.

@end table

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:

@itemize @bullet
@item
PET 2001-8N
@item
PET 3008
@item
PET 3016
@item
PET 3032
@item
PET 3032B
@item
PET 4016
@item
PET 4032
@item
PET 4032B
@item
PET 8032
@item
PET 8096
@item
PET 8296
@item
SuperPET
@end itemize

Notice that this will @strong{reset the emulated machine}.

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


@node PET diagnostic pin, PET commandline options, PET model, PET-specific
@subsection The PET diagnostic pin

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

When the diagnostic pin is set, the Kernal does not try to initialize
the BASIC, but directly jumps into the builtin machine monitor.

@node PET commandline options, PET colors, PET diagnostic pin, PET-specific
@subsection PET command line options

These are the commandline options specific for the CBM-II models.

@table @code

@cindex -model
@item -model MODEL
Specify the PET model you want to emulate.

@cindex -kernal
@item -kernal NAME
Specify @file{NAME} as the Kernal/BASIC ROM file (@code{KernalName}).

@cindex -editor
@item -editor NAME
Specify @file{NAME} as the editor ROM file (@code{EditorName}).

@cindex -chargen
@item -chargen NAME
Specify @file{NAME} as the character generator ROM file
(@code{ChargenName}).

@cindex -rom9
@cindex -romA
@cindex -romB
@item -rom9 NAME, -romA NAME, -romB NAME
Specify @file{NAME} as the ROM image file for the respective 
cartridge areas (@code{RomModule9Name}, @code{RomModuleAName}, 
@code{RomModuleBName}).

@cindex -petramA
@cindex -petramB
@item -petramA, -petramB
Switch on RAM mapping on addresses 
$9000-$9fff, $a000-$afff
(@code{Ram9}, @code{RamA}).

@cindex -superpet
@cindex +superpet
@item -superpet, +superpet
Enable/Disable SuperPET I/O emulation (@code{SuperPET}).

@cindex -basic1
@cindex +basic1
@item -basic1, +basic1
Enable/Disable patching the IEEE488 section of the PET2001 ROM when detected
(@code{Basic1}).

@cindex -basic1char
@cindex +basic1char
@item -basic1char, +basic1char
Enable/Disable PET 2001 character generator
(@code{Basic1Chars}).

@cindex -eoiblank
@cindex +eoiblank
@item -eoiblank, +eoiblank
Enable/Disable EOI blanking the screen
(@code{EoiBlank}).

@cindex -emuid, +emuid
@item -emuid
@itemx +emuid
Enable (@code{EmuID=1}) or disable (@code{EmuID=0}) the emulation
identification extension (at @code{$e8a0-$e8ff}).

@cindex -diagpin, +diagpin
@item -diagpin
@itemx +diagpin
Enable (@code{DiagPin=1}) or disable (@code{DiagPin=0}) the 
diagnostic pin at the PET userport.

@end table

@node PET colors,  , PET commandline options, PET-specific
@subsection 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 (@pxref{Palette
files}) in the @code{PaletteName} resource.  The menu provides the
following values:

@itemize @bullet
@item
@code{green.vpl} (default, ``green)''), the good old green-on-black
feeling;
@item
@code{amber.vpl} (``amber''), an amber phosphor lookalike;
@item
@code{white.vpl} (``white''), simple white-on-black palette.
@end itemize

@c --------------------------------------------------------------

@node CBM-II-specific,  , PET-specific, Machine-specific features
@section CBM-II-specific commands and settings

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

@menu
* CBM-II model::                
* CBM-II commandline options::  
* CBM-II colors::               
@end menu

@node CBM-II model, CBM-II commandline options, CBM-II-specific, CBM-II-specific
@subsection Changing CBM-II model

With @code{xcbm2}, it is possible to change at runtime the
characteristics of the emulated CBM so that it matches (or not) the ones
of a certain CBM model, and it is also possible to select from a common
set of CBM 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):

@table @code

@cindex UseVicII
@item UseVicII
Whether to use VIC-II for video output (value 1) or the CRTC for the
other machines (value 0)

@cindex RamSize
@item RamSize
Size of memory in kByte.  Possible values are 128, 256, 512 and 1024

@cindex Ram08
@cindex Ram1
@cindex Ram2
@cindex Ram4
@cindex Ram6
@cindex RamC
@item Ram08, Ram1, Ram2, Ram4, Ram6, RamC
Expanded CBM-II models could map RAM to the expansion ROM areas
at $0800-$0fff, $1000-$1fff, $2000-$3FFF, $4000-$5FFF, $6000-$7FFF
and $c000-$cfff respectively.

@cindex Cart2Name
@cindex Cart4Name
@cindex Cart6Name
@item Cart2Name, Cart4Name, Cart6Name
Specify @file{NAME} as the $2000-$3FFF, $4000-$5FFF or $6000-$6FFF
Expansion ROM file.  This file contains an 8k ROM dump.

@cindex ModelLine
@item ModelLine
The CBM-II business models have two hardcoded lines at one of the I/O ports.
From those lines the kernal determines how it should init the 
CRTC video chip for either 50Hz (Europe) or 60Hz (North America),
and either for 8 (C6x0) or 14 (C7x0) scanlines per character.
0 = CBM 7x0 (50Hz), 1 = 60Hz C6x0, 2 = 50Hz C6x0).

@end table

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

@itemize @bullet
@item
C510 (128k RAM)
@item
C610 (128k RAM)
@item
C620 (256k RAM)
@item
C620+ (1024k RAM, expanded)
@item
C710 (128k RAM)
@item
C720 (256k RAM)
@item
C720+ (1024k RAM, expanded)
@end itemize

Notice that this will @strong{reset the emulated machine}.

@b{Warning:} At this time switching between 510 and other machines during
runtime is not supported and will not work.

It is also possible to select the CBM model at startup, with the
@code{-model} command-line option: for example, @samp{xcbm2 -model 610}
will emulate a CBM 610 while @samp{xcbm2 -model 620} will emulate a CBM
620. Notably this is the only way to start a C510 emulation, with
@code{-model 510}.

@node CBM-II commandline options, CBM-II colors, CBM-II model, CBM-II-specific
@subsection CBM-II command line options

These are the commandline options specific for the CBM-II models.

@table @code

@cindex -usevicii +usevicii
@item -usevicii
@itemx +usevicii
Specify whether to use (-usevicii) or not to use (+usevicii) the VIC-II 
emulation.

@cindex -kernal
@item -kernal NAME
Specify @file{NAME} as the Kernal ROM file (@code{KernalName}).

@cindex -basic
@item -basic NAME
Specify @file{NAME} as the Basic ROM file (@code{BasicName}).

@cindex -chargen
@item -chargen NAME
Specify @file{NAME} as the character generator ROM file
(@code{ChargenName}).

@cindex -cart2
@cindex -cart4
@cindex -cart6
@item -cart2 NAME, -cart4 NAME, -cart6 NAME
Specify @file{NAME} as the ROM image file for the respective 
cartridge areas (@code{Cart2Name}, @code{Cart4Name}, @code{Cart6Name}).

@cindex -ram08
@cindex -ram1
@cindex -ram2
@cindex -ram4
@cindex -ram6
@cindex -ramC
@item -ram08, -ram1, -ram2, -ram4, -ram6, -ramC
Switch on RAM mapping in bank 15 on addresses 
$0800-$0fff, $1000-$1fff, $2000-$3fff, $4000-$5fff, $6000-$7fff resp
(@code{Ram08}, @code{Ram1}, @code{Ram2}, @code{Ram4}, @code{Ram6},
@code{RamC}).

@cindex -modelline
@item -modelline
Define the hardcoded model switch in the CBM-II models.

@end table

@node CBM-II colors,  , CBM-II commandline options, CBM-II-specific
@subsection 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 (@pxref{Palette
files}) in the @code{PaletteName} resource.  The menu provides the
following values:

@itemize @bullet
@item
@code{green.vpl} (default, ``green''), the good old green-on-black
feeling;
@item
@code{amber.vpl} (``amber''), an amber phosphor lookalike;
@item
@code{white.vpl} (``white''), simple white-on-black palette.
@end itemize

@c -----------------------------------------------------------------

@node Snapshots, Monitor, Machine-specific features, Top
@chapter Snapshots

Every VICE emulator has a built-in snapshot feature, that saves the
complete emulator state into one file for later use.
You can therefore save the emulator state - including the state of
the game you are playing for example - in a single file. 

@menu
* Snapshot usage::              
* Snapshot format::             
@end menu

@node Snapshot usage, Snapshot format, Snapshots, Snapshots
@section Snapshot usage

A snapshot is one file containining the complete emulator state.  A
snapshot file can be generated by selecting the ``Save snapshot''
command at any time.  This will pop up a requester from which you can
specify whether the snapshot should also contain the disk and ROM
status.

A snapshot file can be used to restore the emulator state by selecting
the @code{load snapshot} menu entry at any time.
Unfortunately attached ROM images/cartridges are only supported in the VIC20,
the PET and the CBM-II emulators at this time.

The memory configuration of the emulator is saved in the snapshot file as
well. This configuration is restored when the snapshot is loaded.

A quick snapshot can now be made by pressing the @code{M-F11} key and
reloaded by pressing the @code{M-F10} key. 

@node Snapshot format,  , Snapshot usage, Snapshots
@section Snapshot format

A snapshot file consists of several modules of mostly different types.
Each module has a name and saves the state of an entity like a CIA, the CPU, 
or the memory.

@menu
* Emulator modules::            
* Module formats::              
@end menu

@node Emulator modules, Module formats, Snapshot format, Snapshot format
@subsection Emulator modules

This section lists the modules that are contained in each of the
emulators snapshot files.

@menu
* x64 modules::                 
* x128 modules::                
* xvic modules::                
* xpet modules::                
* xcbm2 modules::               
* Drive modules::               
@end menu

@node x64 modules, x128 modules, Emulator modules, Emulator modules
@subsubsection x64 modules

The modules in the x64 emulator are:

@multitable @columnfractions .1 .4 .5
@item Name
@tab Type
@tab Description
@item MAINCPU
@tab 6502
@tab The Main CPU - although it is a 6510, only the 6502 core is saved here
@item C64MEM
@tab Memory
@tab Holds the RAM contents of the C64.  Also the CPU I/O register contents are saved here.
@item C64ROM
@tab ROM images
@tab Dump of the system ROMs
@item VIC-II
@tab 656*
@tab The VIC-II of the C64/128
@item CIA1
@tab 6526
@tab The CIA for the interrupts and the keyboard
@item CIA2
@tab 6526
@tab The CIA for the userport, IEC-bus and RS232.
@item SID
@tab 6581
@tab The SID sound chip of the C64/C128
@item REU*
@tab
@tab The RAM Extension Unit state (optional)
@item ACIA1
@tab 6551
@tab An ACIA (RS232 interface) at $DE00 (optional)
@item TPI
@tab 6525
@tab A TPI at $DF00 for a parallel IEEE488 interface (optional)
@item *
@tab Drive modules
@tab The emulated drive(s) have their own modules @pxref{Drive modules}
@end multitable

Some of the modules are optional and are only saved if the specific
feature is enabled at save-time.  If the module is found when restoring
the state the optional features are enabled, and disabled otherwise.

@node x128 modules, xvic modules, x64 modules, Emulator modules
@subsubsection x128 modules

The modules in the x128 emulator are:

@multitable @columnfractions .1 .4 .5
@item Name
@tab Type
@tab Description
@item MAINCPU
@tab 6502
@tab The Main CPU - although it is a 6510, only the 6502 core is saved here
@item C128MEM
@tab Memory
@tab Holds the RAM contents of the C64.  Also the CPU I/O register contents are saved here.
@item C128ROM
@tab ROM images
@tab Dump of the system ROMs
@item VIC-II
@tab 656*
@tab The VIC-II of the C64/128
@item CIA1
@tab 6526
@tab The CIA for the interrupts and the keyboard
@item CIA2
@tab 6526
@tab The CIA for the userport, IEC-bus and RS232.
@item SID
@tab 6581
@tab The SID sound chip of the C64/C128
@item ACIA1
@tab 6551
@tab An ACIA at $DE00 (optional)
@item TPI
@tab 6525
@tab A TPI at $DF00 for a parallel IEEE488 interface (optional)
@item *
@tab Drive modules
@tab The emulated drive(s) have their own modules @pxref{Drive modules}
@end multitable

Some of the modules are optional and are only saved if the specific
feature is enabled at save-time.  If the module is found when restoring
the state the optional features are enabled, and disabled otherwise.

Not yet supported are the 80 column video chip, cartridges and 
RAM expansion unit.

@node xvic modules, xpet modules, x128 modules, Emulator modules
@subsubsection xvic modules

The modules in the xvic emulator are:

@multitable @columnfractions .1 .4 .5
@item Name
@tab Type
@tab Description
@item MAINCPU
@tab 6502
@tab The Main CPU 
@item VIC20MEM
@tab Memory
@tab Holds the RAM contents of the VIC20.
@item VIC20ROM
@tab ROM images
@tab Holds the ROM images of the VIC20, including possibly attached cartridges
@item VIC-I
@tab 656*
@tab The VIC-I of the VIC20
@item VIA1
@tab 6522
@tab The VIA for the interrupts and the keyboard
@item VIA2
@tab 6522
@tab The VIA for the userport, IEC-bus and RS232.
@item *
@tab Drive modules
@tab The emulated drive(s) have their own modules @pxref{Drive modules}
@end multitable

@node xpet modules, xcbm2 modules, xvic modules, Emulator modules
@subsubsection xpet modules

The modules in the xpet emulator are:

@multitable @columnfractions .1 .4 .5
@item Name
@tab Type
@tab Description
@item MAINCPU
@tab 6502
@tab The Main CPU 
@item PETMEM
@tab Memory
@tab Holds the RAM contents of the PET.
@item PETROM
@tab ROM images
@tab Holds the ROM images of the PET, including possibly attached cartridges
@item CRTC
@tab 6545
@tab The CRTC of the PET. This is also included if it is a dump of a PET without CRTC, because the video state is saved here anyway.
@item PIA1
@tab 6520
@tab The PIA for the interrupts, tape and the keyboard
@item PIA2
@tab 6520
@tab The PIA for the IEEE488-bus
@item VIA
@tab 6522
@tab The VIA for IEEE488, userport, sound
@item ACIA1
@tab 6551
@tab The ACIA for the SuperPET.  This module is optional.
@item *
@tab Drive modules
@tab The emulated drive(s) have their own modules @pxref{Drive modules}
@end multitable

@node xcbm2 modules, Drive modules, xpet modules, Emulator modules
@subsubsection xcbm2 modules

The modules in the xcbm2 emulator are:

@multitable @columnfractions .1 .4 .5
@item Name
@tab Type
@tab Description
@item MAINCPU
@tab 6502
@tab The Main CPU - although it is a 6509, only the 6502 core is saved here
@item CBM2MEM
@tab Memory
@tab Holds the RAM contents of the CBM-II models.  Also holds the exec-bank and indirection bank registers
@item C500DATA
@tab 
@tab Holds additional state information necessary for the C500 (e.g. cycles till the next IRQ)
@item CBM2ROM
@tab Memory
@tab optional.  Holds the ROM images.
@item CRTC
@tab 6545
@tab The video chip for the C6*0 and C7*0 models (only those models).
@item VIC-II
@tab 656?
@tab The video chip for the C5*0 models (only the C5*0 models).
@item CIA1
@tab 6526
@tab The CIA for IEEE 488 and userport.
@item TPI1
@tab 6525
@tab TPI 1 for IEEE488
@item TPI2
@tab 6525
@tab TPI 2 for interrupts and keyboard.
@item ACIA1
@tab 6551
@tab The RS232 interface
@item SID
@tab 6581
@tab The CBM2s SID sound chip
@item *
@tab Drive modules
@tab The emulated drive(s) have their own modules @pxref{Drive modules}
@end multitable

The snapshot either contains CRTC or VIC-II snapshot modules, but
not both. Currently switching between the two video emulations is not
possible at runtime, so only snapshots that fit the current UseVicII 
resource are accepted.

@node Drive modules,  , xcbm2 modules, Emulator modules
@subsubsection Drive modules

The modules for the real disk drive emulation are included in the emulator
when the emulation is enabled during the writing of the snapshot.

@multitable @columnfractions .1 .4 .5
@item Name
@tab Type
@tab Description
@item *CPU
@tab 6502
@tab The Drive 0 CPU
@item *
@tab *
@tab *
@end multitable

@node Module formats,  , Emulator modules, Snapshot format
@subsection Module formats

This section shows the basic module framework and the contents of the
different types of modules.

The single chip modules contain the @b{chip} state, not the state of the
emulator.  We tried to make the format as implementation-independent as
possible, to allow reuse of snapshots in later versions of this
emulator, or even in other emulators.

@menu
* Module Terminology::          
* Module framework::            
* CPU 6502 module::             
* CIA 6526 module::             
* VIA 6522 module::             
* PIA 6520 module::             
* TPI 6525 module::             
* RIOT 6532 module::             
* SID 6581 module::             
* ACIA 6551 module::            
* VIC-I module::                
* VIC-II module::               
* CRTC module::                 
* C64 memory module::           
* C128 memory module::          
* VIC20 memory module::         
* PET memory module::           
* CBM-II memory module::        
* C500 data module::        
@end menu

@node Module Terminology, Module framework, Module formats, Module formats
@subsubsection Terminology

In this section we use certain abbreviations to define the types of the
data saved in the snapshot.

@table @code
@item BYTE
8 bit integer.
@item WORD
16 bit integer.  Saved with low-byte first, high-byte last.
@item DWORD
32 bit integer.  Saved with low-word first, then high-word.  Each word saved with its low-byte first.
@item ARRAY
Array of BYTE values.  Length depends on the description.
@end table

The tables for the single modules state the type, name and description
of the data saved in the modules.  The data is saved in the order it is
in the tables, so no offset is given.

@node Module framework, CPU 6502 module, Module Terminology, Module formats
@subsubsection Module framework

The VICE snapshot file starts with the magic string and includes the
fileformat version number.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item 19 BYTE
@tab MAGIC
@tab "VICE Snapshot File\032", padded with 0
@item BYTE
@tab VMAJOR
@tab fileformat major version number
@item BYTE
@tab VMINOR
@tab fileformat minor version number
@item 16 BYTE
@tab MACHINENAME
@tab Name of emulated machine, like "PET", "CBM-II", "VIC20", "C64" or "C128". zerobyte-padded.
@end multitable

The file header is followed by a number of different snapshot modules.

Each module has a header with the information given in the table below.
The header includes two version numbers, VMAJOR and VMINOR.  Modules
with the same VMAJOR should be able to be exchanged.  I.e. higher VMINOR
numbers only append to the data for lower VMINOR.  This additional data
is ignored by older restore routines.  The other way around newer
restore routines must accept the fewer info from lower VMINOR dumps.
Changes in VMAJOR might introduce any incompatibility you like, but
that's what VMAJOR is for after all :-)

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item 16 BYTE
@tab MODULENAME
@tab The name of the module in ASCII, padded with 0 to 16 byte.
@item BYTE
@tab VMAJOR
@tab major version number
@item BYTE
@tab VMINOR
@tab minor version number
@item DWORD
@tab SIZE
@tab size of the module, including this header
@end multitable

@node CPU 6502 module, CIA 6526 module, Module framework, Module formats
@subsubsection CPU module

This module saves the core 6502 state.  You will find a clock value
there.  All other modules save their own clock values relative to this
value.  However, the drive modules save their clocks relative to their
appropriate CPUs of course.

@b{Warning:} This module is still under construction and saves some
information that is not sure to be VICE-independent.  If in doubt, read
the source.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item DWORD
@tab CLK
@tab the current CPU clock value.  All other clock values are relative to this.
@item BYTE
@tab AC
@tab Accumulator
@item BYTE
@tab XR
@tab X index register
@item BYTE
@tab YR
@tab Y index register
@item BYTE
@tab SP
@tab Stack Pointer
@item WORD
@tab PC
@tab Programm Counter
@item BYTE
@tab ST
@tab Status Registers
@item DWORD
@tab LASTOPCODE
@tab ?
@item DWORD
@tab IRQCLK
@tab absolute CLK when the IRQ line came active
@item DOWRD
@tab NMICLK
@tab absolute CLK when the NMI line came active
@item DWORD
@tab ?
@tab ?
@item DWORD
@tab ?
@tab ?
@end multitable


@node CIA 6526 module, VIA 6522 module, CPU 6502 module, Module formats
@subsubsection CIA module

The CIA 6526 is an I/O port chip with 2 8-bit I/O ports, a shift register,
two timers, a Time of Day clock and interrupts.

Version numbers: Major 1, Minor 1.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab ORA
@tab Output register A
@item BYTE
@tab ORB
@tab Output register B
@item BYTE
@tab DDRA
@tab Data direction register A
@item BYTE
@tab DDRB
@tab Data direction register B
@item WORD
@tab TAC
@tab Timer A counter value
@item WORD
@tab TBC
@tab Timer B counter value
@item BYTE
@tab TOD_TEN
@tab Time of Day - current tenth of second
@item BYTE
@tab TOD_SEC
@tab Time of Day - current seconds
@item BYTE
@tab TOD_MIN
@tab Time of Day - current minutes
@item BYTE
@tab TOD_HR
@tab Time of Day - current hours
@item BYTE
@tab SDR
@tab contents of shift register
@item BYTE
@tab IER
@tab mask of enabled interrupt masks
@item BYTE
@tab CRA
@tab Control register A
@item BYTE
@tab CRB
@tab Control register B
@item WORD
@tab TAL
@tab Timer A latch value
@item WORD
@tab TBL
@tab Timer B latch value
@item BYTE
@tab IFR
@tab mask of currently active interrupts
@item BYTE
@tab PBSTATE
@tab Bit 6/7 reflect the PB6/7 toggle bit state.  Bit 2/3 reflect the corresponding port bit state.
@item BYTE
@tab SRHBITS
@tab number of half-bits to still shift in/out SDR
@item BYTE
@tab ALARM_TEN
@tab Time of Day - alarm tenth of second
@item BYTE
@tab ALARM_SEC
@tab Time of Day - alarm seconds
@item BYTE
@tab ALARM_MIN
@tab Time of Day - alarm minutes
@item BYTE
@tab ALARM_HR
@tab Time of Day - alarm hours
@item BYTE
@tab READICR
@tab current clock minus the clock when ICR was read last plus 128.
@item BYTE
@tab TODLATCHED
@tab Bit 0: 1= latched for reading, Bit 1: 2=stopped for writing
@item BYTE
@tab TODL_TEN
@tab Time of Day - latched tenth of second
@item BYTE
@tab TODL_SEC
@tab Time of Day - latched seconds
@item BYTE
@tab TODL_MIN
@tab Time of Day - latched minutes
@item BYTE
@tab TODL_HR
@tab Time of Day - latched hours
@item DWORD
@tab TOD_TICKS
@tab clk ticks till next tenth of second
@item --
@tab --
@tab The next items have been added in V1.1
@item WORD
@tab TASTATE
@tab The state bits of the CIA timer A, according to ciatimer.h
@item WORD
@tab TBSTATE
@tab The state bits of the CIA timer B, according to ciatimer.h
@end multitable

The last two items have been added in CIA snapshot version 1.1 due
to the improved CIA emulation in the newer VICE versions. 
Some state bits correspond to the CIA state as described in the
"A Software Model of the CIA 6526" document by Wolfgang Lorenz,
some are delayed versions. For more read the source file 
@code{ciatimer.h}.

@node VIA 6522 module, PIA 6520 module, CIA 6526 module, Module formats
@subsubsection VIA module

The VIA 6522 is the predecessor of the CIA and also an I/O port chip
with 2 8-bit I/O ports, a shift register,
two timers and interrupts.

Version numbers: Major 1, Minor 0.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab ORA
@tab Output register A
@item BYTE
@tab DDRA
@tab Data direction register A
@item BYTE
@tab ORB
@tab Output register B
@item BYTE
@tab DDRB
@tab Data direction register B
@item WORD
@tab T1L
@tab Timer 1 Latch value
@item WORD
@tab T1C
@tab Timer 1 counter value
@item BYTE
@tab T2L
@tab Timer 2 latch (8 bit as only lower byte is used)
@item WORD
@tab T2C
@tab Timer 2 counter value
@item BYTE
@tab RUNFL
@tab bit 7: timer 1 will generate IRQ on underflow; bit 6: timer 2 will generate IRQ on underflow
@item BYTE
@tab SR
@tab Shift register value
@item BYTE
@tab ACR
@tab Auxiliary control register
@item BYTE
@tab PCR
@tab Peripheral control register
@item BYTE
@tab IFR
@tab active interrupts
@item BYTE
@tab IER
@tab interrupt mask
@item BYTE
@tab PB7
@tab bit 7 = pb7 state
@item BYTE
@tab SRHBITS
@tab number of half-bits to shift out on SR
@item BYTE
@tab CABSTATE
@tab bit 7: state of CA2 pin, bit 6: state of CB2 pin
@item BYTE
@tab ILA
@tab Port A Input Latch (see ACR bit 0)
@item BYTE
@tab ILB
@tab Port B Input Latch (see ACR bit 1)
@end multitable

@node PIA 6520 module, TPI 6525 module, VIA 6522 module, Module formats
@subsubsection PIA module

The PIA 6520 is a chip with two I/O ports (Parallel Interface Adapter)
and four additional handshake lines.  The chip is pretty the same for
Port A and B, only that Port A implements handshake on read operation
and port B on write operation.

Version numbers: Major 1, Minor 0.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item UBYTE
@tab ORA
@tab Output register A
@item UBYTE
@tab DDRA
@tab Data Direction Register A
@item UBYTE
@tab CTRLA
@tab Control Register A
@item UBYTE
@tab ORB
@tab Output register B
@item UBYTE
@tab DDRB
@tab Data Direction Register B
@item UBYTE
@tab CTRLB
@tab Control Register B
@item UBYTE
@tab CABSTATE
@tab Bit 7 = state of CA2, Bit 6 = state of CB2
@end multitable

@node TPI 6525 module, RIOT 6532 module, PIA 6520 module, Module formats
@subsubsection TPI module

The TPI 6525 is a chip with three I/O ports (Tri-Port-Interface).  One of
the ports can double as an interrupt prioritizer.  Therefore we also have
to save the states of the interrupt stack etc.

Version numbers: Major 1, Minor 0.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab PRA
@tab Port A output register
@item BYTE
@tab PRB
@tab Port B output register
@item BYTE
@tab PRC
@tab Port C output register (doubles as IRQ latch register)
@item BYTE
@tab DDRA
@tab Port A data direction register
@item BYTE
@tab DDRB
@tab Port B data direction register
@item BYTE
@tab DDRC
@tab Port C data direction register (doubles as IRQ mask register)
@item BYTE
@tab CR
@tab Control Register
@item BYTE
@tab AIR
@tab Active interrupt register
@item BYTE
@tab STACK
@tab Interrupt stack - the interrupt bits that are not (yet) served.
@item BYTE
@tab CABSTATE
@tab State of CA/CB pins.  Bit 7 = state of CA, Bit 6 = state of CB
@end multitable

@node RIOT 6532 module, SID 6581 module, TPI 6525 module, Module formats
@subsubsection RIOT module

The RIOT 6532 is a chip with two I/O ports, some RAM and a Timer. 
The chip contains 128 byte RAM, but the RAM is not saved in the 
RIOT snapshot, but in the memory section.

@b{Warning:} This module is still under construction

Version numbers: Major 0, Minor 0.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab ORA
@tab Port A output register
@item BYTE
@tab DDRA
@tab Port A data direction register
@item BYTE
@tab ORB
@tab Port B output register
@item BYTE
@tab DDRB
@tab Port B data direction register
@item BYTE
@tab EDGECTRL
@tab Bit 0/1: A0/A1 address bits written to edgecontrol registers
@item BYTE
@tab IRQFL
@tab Bit 6/7: A6/A7 IRQ flag register. Bit 0: state of the IRQ line (0=inactive, 1=active)
@item BYTE
@tab N
@tab timer value
@item WORD
@tab DIVIDER
@tab Pre-scale divider value (1, 8, 64, or 1024)
@item WORD
@tab REST
@tab cycles since the last counter change
@item BYTE
@tab IRQEN
@tab Bit 0: 0= timer IRQ disabled, 1= timer IRQ enabled
@end multitable

@node SID 6581 module, ACIA 6551 module, RIOT 6532 module, Module formats
@subsubsection SID module

@b{Warning:} This module is still under construction.

@node ACIA 6551 module, VIC-I module, SID 6581 module, Module formats
@subsubsection ACIA module

The ACIA 6551 is an RS232 interface chip.  VICE emulates RS232 connections
via @code{/dev/ttyS*} (Unix) or @code{COM:} (DOS/WIN - not yet?).
When saving a snapshot, those connections are of course lost.
The state of the ACIA however is restored if possible.  I.e. if a connection
is already open when restoring the snapshot, this connection is used
instead.  If no connection is open, a carrier/DTR drop is emulated.

Version numbers: Major 1, Minor 0.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab TDR
@tab Transmit Data Register
@item BYTE
@tab RDR
@tab Receiver Data Register
@item BYTE
@tab SR
@tab Status Register
@item BYTE
@tab CMD
@tab Command Register
@item BYTE
@tab CTRL
@tab Ctrl Register
@item BYTE
@tab INTX
@tab 0 = no data to tx; 1 = Data is being transmitted; 2 = Data is being transmitted while data in TDR waiting to be put to internal transmit register
@item DWORD
@tab TICKS
@tab Clock ticks till the next TDR empty interrupt
@end multitable

@node VIC-I module, VIC-II module, ACIA 6551 module, Module formats
@subsubsection VIC-I module

@b{Warning:} This module is still under construction.

@node VIC-II module, CRTC module, VIC-I module, Module formats
@subsubsection VIC-II module

@b{Warning:} This module is still under construction.

@node CRTC module, C64 memory module, VIC-II module, Module formats
@subsubsection CRTC module

@b{Warning:} After VICE version 1.0 the CRTC emulation has improved
considerably. Especially it is now cycle exact. Therefore a lot more
variables must be saved. The snapshot module version jumped from
0.0 to 1.0. Newer versions of VICE can read the old snapshots, but
older versions (1.0 and below) cannot read the new snapshots.

@b{Warning:} This module is still under construction.  Especially the
RASTERY and RASTERLINE values might be bogus.

Version numbers: Major 1, Minor 1.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item
@tab
@tab Hardware options
@item WORD
@tab VADDR_MASK
@tab Mask of the address bits valid when accessing the video memory
@item WORD
@tab VADDR_CHARSWITCH
@tab If one bit in the video address is used to switch the character generator, it is masked here.
@item WORD
@tab VADDR_CHAROFFSET
@tab The offset in characters in the character generator that CHARSWITCH switches.
@item WORD
@tab VADDR_REVSWITCH
@tab If one bit in the video address inverts the screen, it is masked here. 
@item WORD
@tab CHARGEN_MASK
@tab size of character generator in byte - 1
@item WORD
@tab CHARGEN_OFFSET
@tab offset given by external circuitry
@item BYTE
@tab HW_CURSOR
@tab external hardware cursor circuitry enabled
@item BYTE
@tab HW_COLS
@tab number of displayed columns during one character clock cycle
@item BYTE
@tab HW_BLANK
@tab set if the hardware blank feature is available
@item 
@tab
@tab CRTC register
@item 20 BYTE
@tab REGISTERS
@tab register DUMP of the CRTC registers 0-19.
@item
@tab
@tab CRTC internal registers
@item BYTE
@tab REGNO
@tab The current index in the CRTC register file
@item BYTE
@tab CHAR
@tab The current cycle within the current rasterline
@item BYTE
@tab CHARLINE
@tab The current character line
@item BYTE
@tab YCOUNTER
@tab The current rasterline in the character
@item BYTE
@tab CRSRCNT
@tab Framecounter for the blinking cursor
@item BYTE
@tab CRSRSTATE
@tab if set the hardware cursor is visible
@item BYTE
@tab CRSRLINES
@tab set if ycounter is within the active cursor rasterlines for a char
@item WORD
@tab CHARGEN_REL
@tab relative base of currently used character generator in ROM (in byte)
@item WORD
@tab SCREEN_REL
@tab screen address to load the counter at the beginning of the next rasterline
@item WORD
@tab VSYNC
@tab number of rasterlines left within vsync; 0 = not in vsync
@item BYTE
@tab VENABLE
@tab vertical enable flipflop; 1= display, 0= blank.
@item
@tab
@tab (VICE-dependent?) variables
@item WORD
@tab SCREEN_WIDTH
@tab width of the current display window
@item WORD
@tab SCREEN_HEIGHT
@tab height of the current display window
@item WORD
@tab SCREEN_XOFFSET
@tab x position where the first character in a line starts in the window...
@item WORD
@tab HJITTER
@tab ...but only after adding this jitter
@item WORD
@tab SCREEN_YOFFSET
@tab x position where the first character in a line starts in the window...
@item WORD
@tab FRAMELINES
@tab expected number of rasterlines for the current frame
@item WORD
@tab CURRENT_LINE
@tab current rasterline as seen from the CRTC
@item
@tab
@tab This value has been added in module version V1.1
@item BYTE
@tab FLAG
@tab Bit 0: If 1 then bit in VADDR_REVSWITCH must be set for reverse; if 0 then bit must be cleared for reverse.
@end multitable

Here is the reference for the previous CRTC snapshot module. It is outdated
and will not be read by this and later versions of VICE.

Version numbers: Major 0, Minor 0.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab RASTERY
@tab The number of clock cycles from rasterlines start
@item WORD
@tab RASTERLINE
@tab The current rasterline 
@item WORD
@tab ADDRMASK
@tab The address mask valid for the CRTC.  All memory accesses are masked with this value
@item BYTE
@tab HWFLAG
@tab Bit 0: 1= hardware cursor available.  Bit 1: 1= number of columns is doubled by external hardware
@item 20 BYTE
@tab REGISTERS
@tab register DUMP of the CRTC registers 0-19.
@item BYTE
@tab CRSRSTATE
@tab Hardware cursor: Bits 0-3: frame counter till next crsr line toggle. Bit 7: 1= cursor line active
@end multitable

@node C64 memory module, C128 memory module, CRTC module, Module formats
@subsubsection C64 memory module

The C64 memory module actually consists of two modules.  The "C64MEM" module
is mandatory and contains the RAM dump.  The "C64ROM" module is optional
and contains a dump of the ROM images.

The size of the C64 memory modules differs with each different memory
configuration. The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded. The attached cartridges are
@b{not yet(!)} saved and not yet restored upon load.

Version numbers: Major 0, Minor 0

@b{The C64MEM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CPUDATA
@tab CPU port data byte
@item BYTE
@tab CPUDIR
@tab CPU port direction byte
@item BYTE
@tab EXROM
@tab state of the EXROM line (?)
@item BYTE
@tab GAME
@tab state of the GAME line (?)
@item ARRAY
@tab RAM
@tab 64k RAM dump
@end multitable

@b{The C64ROM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item ARRAY
@tab KERNAL
@tab 8k dump of the kernal ROM
@item ARRAY
@tab BASIC
@tab 8k dump of the basic ROM
@item ARRAY
@tab CHARGEN
@tab 4k dump of the chargen ROM
@end multitable

@node C128 memory module, VIC20 memory module, C64 memory module, Module formats
@subsubsection C128 memory module

The C128 memory module actually consists of two modules.  The "C128MEM" module
is mandatory and contains the RAM dump.  The "C128ROM" module is optional
and contains a dump of the ROM images.

The size of the C128 memory modules differs with each different memory
configuration. The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded. The attached cartridges are
also restored upon load if they have been saved in the snapshot.

Version numbers: Major 0, Minor 0

@b{The C128MEM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item 12 BYTE
@tab MMU
@tab dump of the 12 MMU registers
@item ARRAY
@tab RAM
@tab 128k RAM dump banks 0 and 1
@end multitable

@b{The C128ROM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item ARRAY
@tab KERNAL
@tab 8k dump of the kernal ROM
@item ARRAY
@tab BASIC
@tab 32k dump of the basic ROM
@item ARRAY
@tab EDITOR
@tab 4k dump of the editor ROM
@item ARRAY
@tab 4k CHARGEN
@tab dump of the chargen ROM
@end multitable

@node VIC20 memory module, PET memory module, C128 memory module, Module formats
@subsubsection VIC20 memory module

The VIC20 memory module actually consists of two modules.  The "VIC20MEM" module
is mandatory and contains the RAM dump.  The "VIC20ROM" module is optional
and contains a dump of the ROM images.

The size of the VIC20 memory modules differs with each different memory
configuration. The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded. The attached cartridges are
also restored upon load if they have been saved in the snapshot.

@b{The VIC20MEM module}

Version numbers: Major 1, Minor 0

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CONFIG
@tab Configuration register.  Bits 0,1,2,3,5 reflect if the corresponding memory block is RAM (bit=1) or not (bit=0).
@item ARRAY
@tab RAM0
@tab 1k RAM dump $0000-$03ff
@item ARRAY
@tab RAM1
@tab 4k RAM dump $1000-$1fff
@item ARRAY
@tab COLORRAM
@tab 2k Color RAM, $9400-$9bff
@item ARRAY
@tab BLK0
@tab if CONFIG & 1 then: 3k RAM dump $0400-$0fff
@item ARRAY
@tab BLK1
@tab if CONFIG & 2 then: 8k RAM dump $2000-$3fff
@item ARRAY
@tab BLK2
@tab if CONFIG & 4 then: 8k RAM dump $4000-$5fff
@item ARRAY
@tab BLK3
@tab if CONFIG & 8 then: 8k RAM dump $6000-$7fff
@item ARRAY
@tab BLK5
@tab if CONFIG & 32 then: 8k RAM dump $a000-$bfff
@end multitable

@b{The VIC20ROM module}

Version numbers: Major 1, Minor 1

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CONFIG
@tab Bit 0: 1= ROM block $2*** enabled.  Bit 1: 1= ROM block $3*** enabled. Bit 2: 1= ROM block $4*** enabled.  Bit 3: 1= ROM block $5*** enabled. Bit 4: 1= ROM block $6*** enabled. Bit 5: 1= ROM block $7*** enabled. Bit 6: 1= ROM block $A*** enabled. Bit 7: 1= ROM block $B*** enabled.
@item ARRAY
@tab KERNAL
@tab 8k KERNAL ROM image $e000-$ffff
@item ARRAY
@tab BASIC
@tab 16k BASIC ROM image $c000-$dfff
@item ARRAY
@tab CHARGEN
@tab 4k CHARGEN ROM image
@item ARRAY
@tab BLK1A
@tab 4k ROM image $2*** (if CONFIG & 1)
@item ARRAY
@tab BLK1B
@tab 4k ROM image $3*** (if CONFIG & 2)
@item ARRAY
@tab BLK3A
@tab 4k ROM image $6*** (if CONFIG & 16)
@item ARRAY
@tab BLK3B
@tab 4k ROM image $7*** (if CONFIG & 32)
@item ARRAY
@tab BLK5A
@tab 4k ROM image $A*** (if CONFIG & 64)
@item ARRAY
@tab BLK5B
@tab 4k ROM image $B*** (if CONFIG & 128)
@item ARRAY
@tab BLK2A
@tab 4k ROM image $4*** (if CONFIG & 4; added in V1.1)
@item ARRAY
@tab BLK2B
@tab 4k ROM image $5*** (if CONFIG & 8; added in V1.1)
@end multitable

@node PET memory module, CBM-II memory module, VIC20 memory module, Module formats
@subsubsection PET memory module

The PET memory module actually consists of two modules.  The "PETMEM" module
is mandatory and contains the RAM dump.  The "PETROM" module is optional
and contains a dump of the ROM images.

The size of the PET memory modules differs with each different memory
configuration.  The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded.

@b{The PETMEM module}

Version numbers: Major 1, Minor 2

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CONFIG
@tab Configuration value. Bits 0-3: 0= 40 col PET without CRTC; 1= 40 col PET with CRTC; 2 = 80 col PET (with CRTC); 3= SuperPET; 4= 8096; 5= 8296. Bit 6: 1= RAM at $9***. Bit 7: 1= RAM at $A***.
@item BYTE
@tab KEYBOARD
@tab Keyboard type. 0= UK business; 1= Graphics; 2= German business
@item BYTE
@tab MEMSIZE
@tab memory size of low 32k in k (possible values 4, 8, 16, 32)
@item BYTE
@tab CONF8X96
@tab Value of the 8x96 configuration register
@item BYTE
@tab SUPERPET
@tab SuperPET config. Bit 0: 1= $9*** RAM enabled. Bit 1: 1= RAM write protected. Bit 2: 1= CTRL register write protected. Bit 3: 0= DIAG pin active. Bits 4-7: RAM block in use. 
@item ARRAY
@tab RAM
@tab 4-32k RAM (not 8296, size depends on MEMSIZE)
@item ARRAY
@tab VRAM
@tab 2/4k RAM (not 8296, size depends on CONFIG)
@item ARRAY
@tab EXTRAM
@tab 64k expansion RAM (SuperPET and 8096 only)
@item ARRAY
@tab RAM
@tab 128k RAM (8296 only)
@item --
@tab --
@tab The following item has been added in V1.1
@item BYTE
@tab POSITIONAL
@tab bit 0=0 = symbolic keyboard mapping, bit 0=1 = positional mapping.
@item --
@tab --
@tab The following item has been added in V1.1
@item BYTE
@tab EOIBLANK
@tab bit 0=0 = EOI does not blank screen, bit 0=1 = EOI blanks screen.
@end multitable

The last item has been added in PETMEM snapshot version 1.1. It is
ignored by earlier restore routines (V1.0) and the V1.1 restore routines
do not change the current setting when reading a V1.0 snapshot.

In V1.2 the new EOIBLANK variable has been added. This implements
the "blank screen on EOI" feature that was previously linked to a wrong 
resource.

@b{The PETROM module}

Version numbers: Major 1, Minor 0

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CONFIG
@tab Bit 0: 1= $9*** ROM included. Bit 1: 1= $A*** ROM included. Bit 2: 1= $B*** ROM included. Bit 3: 1= $e900-$efff ROM included
@item ARRAY
@tab KERNAL
@tab 4k KERNAL ROM image $f000-$ffff
@item ARRAY
@tab EDITOR
@tab 2k EDITOR ROM image $e000-$e7ff
@item ARRAY
@tab CHARGEN
@tab 2k CHARGEN ROM image
@item ARRAY 
@tab ROM9
@tab 4k $9*** ROM image (if CONFIG & 1)
@item ARRAY 
@tab ROMA
@tab 4k $A*** ROM image (if CONFIG & 2)
@item ARRAY 
@tab ROMB
@tab 4k $B*** ROM image (if CONFIG & 4)
@item ARRAY 
@tab ROMC
@tab 4k $C*** ROM image  
@item ARRAY 
@tab ROMD
@tab 4k $D*** ROM image
@item ARRAY
@tab ROME9
@tab 7 blocks $e900-$efff ROM image (if CONFIG & 8)
@end multitable

@node CBM-II memory module, C500 data module, PET memory module, Module formats
@subsubsection CBM-II memory module

The CBM-II memory module actually consists of two modules.  The
"CBM2MEM" module is mandatory and contains the RAM dump.  The "CBM2ROM"
module is optional and contains a dump of the ROM images.

The size of the CBM-II memory modules differs with each different memory
configuration.  The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded.

Version numbers: Major 1, Minor 0

@b{The CBM2MEM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item UBYTE
@tab MEMSIZE
@tab Memory size in 128k blocks (1=128k, 2=256k, 4=512k, 8=1024k)
@item UBYTE
@tab CONFIG
@tab Bit 0 = $f0800-$f0fff RAM, Bit 1 = $f1000-$f1fff RAM, Bit 2 = $f2000-$f3fff RAM, Bit 3 = $f4000-$f5fff RAM, Bit 4 = $f6000-$f7fff RAM, Bit 5 = $fc000-$fcfff RAM, Bit 6 = is a C500
@item UBYTE
@tab HWCONFIG
@tab Bit 0/1: model line configuration
@item UBYTE
@tab EXECBANK
@tab CPUs execution bank register
@item UBYTE
@tab INDBANK
@tab CPUs indirection bank register
@item ARRAY
@tab SYSRAM
@tab 2k system RAM $f0000-$f07ff
@item ARRAY
@tab VIDEO
@tab 2k video RAM $fd000-$fd7ff
@item ARRAY
@tab RAM
@tab RAM dump, size according to MEMSIZE
@item ARRAY
@tab RAM08
@tab if memsize < 1M and CONFIG & 1 : 2k RAM $f0800-$f0fff
@item ARRAY
@tab RAM1
@tab if memsize < 1M and CONFIG & 2 : 4k RAM $f1000-$f1fff
@item ARRAY
@tab RAM2
@tab if memsize < 1M and CONFIG & 4 : 8k RAM $f2000-$f3fff
@item ARRAY
@tab RAM4
@tab if memsize < 1M and CONFIG & 8 : 8k RAM $f4000-$f5fff
@item ARRAY
@tab RAM6
@tab if memsize < 1M and CONFIG & 16 : 8k RAM $f6000-$f7fff
@item ARRAY
@tab RAMC
@tab if memsize < 1M and CONFIG & 32 : 4k RAM $fc000-$fcfff
@end multitable

The RAM* arrays are only saved if the RAM itself is less than 1M.
If the memory size is 1M then those areas are taken from the
bank 15 area of the normal RAM.

The memory array starts at $10000 if the memory size is less than 512k,
or at $00000 if 512k or more. In case of a C510, then the memory array
also always starts at $00000.

@b{The CBM2ROM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item UBYTE
@tab CONFIG
@tab Bit 1: 1= $1*** ROM image included. Bit 2: 1= $2000-$3fff ROM image included. Bit 3: 1= $4000-$5fff ROM image included. Bit 4: 1= $6000-$7fff ROM image included. Bit 5: 1= chargen ROM is VIC-II chargen, 0= CRTC chargen.
@item ARRAY
@tab KERNAL
@tab 8 KERNAL ROM image ($e000-$efff)
@item ARRAY
@tab BASIC
@tab BASIC ROM image ($8000-$bfff)
@item ARRAY
@tab CHARGEN
@tab 4k CHARGEN ROM image
@item ARRAY
@tab ROM1
@tab 4k cartridge ROM image for $1*** (if CONFIG & 2)
@item ARRAY
@tab ROM2
@tab 8k cartridge ROM image for $2000-$3fff (if CONFIG & 4)
@item ARRAY
@tab ROM4
@tab 8k cartridge ROM image for $4000-$5fff (if CONFIG & 8)
@item ARRAY
@tab ROM6
@tab 8k cartridge ROM image for $6000-$7fff (if CONFIG & 16)
@end multitable

@node C500 data module,  ,CBM-II memory module, Module formats
@subsubsection C500 data module

The C500 data module contains simple state information not already saved
in the other modules.

Version numbers: Major 0, Minor 0

@b{The C500DATA module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item DWORD
@tab IRQCLK
@tab CPU clock ticks till next 50Hz IRQ
@end multitable


@c -----------------------------------------------------------------

@node Monitor, c1541, Snapshots, Top
@chapter 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
@code{rxvt} or @code{xterm}) in order to use the monitor.

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

@menu
* Terminology::                 
* Machine state commands::      
* Memory commands::             
* Assembly commands::           
* Checkpoint commands::         
* General commands::            
* Disk commands::               
* Command file commands::       
* Label commands::              
* Miscellaneous commands::      
@end menu

@node Terminology, Machine state commands, Monitor, Monitor
@section Terminology

@table @samp

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

@item bankname
The CPU can only see 64k of memory at any one time, due to its 16 bit
address bus. The C64 and other computers have more than this amount,
and this is handled by banking: a memory address can have different
contents, depending on the active memory bank. 
A bankname names a specific bank in the current address_space.

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

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

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

@item address_opt_range
An address or an address range.

@c @item label
@c Fixme.

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

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

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

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

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

@item <...>
A data type.

@item *
Zero or more occurrences.

@item [...]
An optional argument.

@end table

@node Machine state commands, Memory commands, Terminology, Monitor
@section Machine state commands

@table @code

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

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

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

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

@item return
Continues execution  and returns to the monitor just
after the next RTS or RTI is executed.

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

@c @item up
@c Nothing yet.  Is this really useful?

@end table


@node Memory commands, Assembly commands, Machine state commands, Monitor
@section Memory commands


@table @code

@item bank [<bankname>]
Without a bankname, display all available banks for the current
address_space. With a bankname given, switch to the specified
bank. If a bank is not completely filled (ROM banks for example)
normally the @code{ram} bank is used where the bank has holes.
The @code{cpu} bank uses the bank currently used by the CPU.

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

@item device [c:|8:|9:]
Set the default address space to either the computer `c:' or the
specified drive `8:' or `9:'
@item 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.

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

@item i <address_opt_range>
Display memory contents as PETSCII text.

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

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

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

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

@item sidefx [on|off|toggle]
Control how monitor generated reads affect memory locations that have
read side-effects, like CIA interrupt registers for example.  
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.

@item > [<address>] <data_list>
Write the specified data at @code{address}.

@end table

@node Assembly commands, Checkpoint commands, Memory commands, Monitor
@section Assembly commands

@table @code

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

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

@end table

@node Checkpoint commands, General commands, Assembly commands, Monitor
@section Checkpoint commands


@table @code

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

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

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

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

@item delete <checknum>
Delete the specified checkpoint.

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

@item trace [address [address]]
This command is similar to the @code{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.

@item watch [loadstore] [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.
The loadstore parameter can be either "load" or "store" to determine
on which operation the monitor breaks. If not specified, the monitor
breaks on both operations.

@end table


@node General commands, Disk commands, Checkpoint commands, Monitor
@section General commands


@table @code

@item cd <directory>
Change the working directory.

@item device [c:|d:]
Set the default memory device to either the computer (@code{c:}) or
the disk (@code{d:}).

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

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

@item system <system command>
Nothing yet.

@end table


@node Disk commands, Command file commands, General commands, Monitor
@section Disk commands

@table @code

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

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

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

@item load "<filename>" <device> [<address>]
Load the specified file into memory.  If no address is given, the file
is loaded to the address specified by the first two bytes read from
the file.  If address is given, the file is loaded to the specified
address and the first two bytes read from the file are skipped.  If
device is 0, the file is read from the file system.

@item save "<filename>" <device> <address1> <address2>
Save the memory from address1 to address2 to the specified file.  If
device is 0, the file is written to the file system.

@c @item v "<filename>" <address>
@c Nothing yet.  Is this really needed?

@end table


@node Command file commands, Label commands, Disk commands, Monitor
@section Command file commands


@table @code

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

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

@item stop
Stop recording commands.  See @code{record}.

@end table

@node Label commands, Miscellaneous commands, Command file commands, Monitor
@section Label commands


@table @code

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

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

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

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

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

@end table


@node Miscellaneous commands,  , Label commands, Monitor
@section Miscellaneous commands


@table @code

@c @item bank <number>
@c Nothing yet.

@c @item brmon
@c Nothing yet.  Will toggle monitor entry on BRK.

@item exit
Leave the monitor and return to execution.

@c @item help [topic]
@c Nothing yet.

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

@item quit
Exit the emulator immediately.

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

@end table


@node c1541, File formats, Monitor, Top
@chapter c1541

VICE is provided with a complete stand-alone disk image maintenance
utility, called @code{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 @code{xterm} window with a running
@code{c1541} in it.

The syntax is:

@example
c1541 [IMAGE1 [IMAGE2]] [COMMAND1 COMMAND2 ... COMMANDN]
@end example

@code{IMAGE1} and @code{IMAGE2} are disk image names that can be
attached before @code{c1541} starts.  @code{c1541} can handle up to
two disk images at the same time by using two virtual built-in drives,
numbered @code{8} and @code{9}; @code{IMAGE1} (if present) is always
attached to drive @code{8}, while @code{IMAGE2} is attached to drive
@code{9}.

@code{COMMAND}s specified on the command-line all begin with the minus
sign (@code{-}); if present, @code{c1541} executes them in the same
order as they are on the command line and returns a zero error code if
they were successful.  If any of the @code{COMMAND}s fails, @code{c1541}
stops and returns a nonzero error code.

If no @code{COMMAND}s are specified at all, @code{c1541} enters
interactive mode, where you can type commands manually.  Commands in
interactive mode are the same as commands in batch mode, but do not
require a leading @code{-}.  As with the monitor, file name completion
and command line editing with history are provided via GNU
@code{readline}.  Use the command @samp{quit} or press @kbd{C-d} to
exit.

@menu
* c1541 file specification::    
* c1541 quoting::               
* c1541 commands and options::  
* c1541 executing shell commands::  
@end menu

@node c1541 file specification, c1541 quoting, c1541, c1541
@section Specifying files in c1541

When accessing CBM DOS files (i.e. files that reside on disk images),
c1541 uses a special syntax that lets you access files on both drive 8
and 9.  If you prepend the file name with @code{@@8:} or @code{@@9:}, you
will specified that file is to be found or created on drive 8 and 9,
respectively.

For instance,

@example
@@8:somefile
@end example

will name file named @code{somefile} on unit 8, while

@example
@@9:somefile
@end example

will name file named @code{somefile} on unit 9.

@node c1541 quoting, c1541 commands and options, c1541 file specification, c1541
@section Using quotes and backslashes

You can use quotes (@code{"}) in a command to embed spaces into file
names.  For instance,

@example
read some file
@end example

will read file @code{some} from the disk image and write it into the
file system as @code{file}, while

@example
read "some file"
@end example

will copy @code{some file} into the file system, with the name
@code{some file}.

The backslash character (@code{\}) has a special meaning too: it lets
you literally insert the following character no matter what it is.  For
example,

@example
read some\ file
@end example

will copy file @code{some file} into the file system, while

@example
read some\ file this\"file
@end example

will copy @code{some file} into the file system with name
@code{this"file} (with an embedded quote).


@node c1541 commands and options, c1541 executing shell commands, c1541 quoting, c1541
@section c1541 commands and options

This is a list of the @code{c1541} commands.  They are shown in their
interactive form, without the leading @code{-}.
Square brackets [] indicate an optional part, and "<COMMAND>" translates
to a disk command according to CBM DOS, like "i0" for example.

@table @code

@item @ [<command>]
Execute specified CBM DOS command and print the current status of the
drive.  If no @code{command} is specified, just print the status.

@item ? [<command>]
Explain specified command.  If no command is specified, list available
ones.

@item attach <diskimage> [<unit>]
Attach @code{diskimage} to @code{unit} (default unit is 8).

@item block <track> <sector> <disp> [<drive>]
Show specified disk block in hex form.

@item copy <source1> [<source2> ... <sourceN>] <destination>
Copy @code{source1} ... @code{sourceN} into destination.  If N > 1,
@code{destination} must be a simple drive specifier (@code{@@n:}).

@item delete <file1> [<file2> ... <fileN>]
Delete the specified files.

@item exit
Exit (same as @code{quit}).

@item extract
Extract all the files to the file system.

@item format <diskname,id> [<type> <imagename>] [<unit>]
If @code{unit} is specified, format the disk in unit @code{unit}.  If
@code{type} and @code{imagename} are specified, create a new image named
@code{imagename}, attach it to unit 8 and format it.  @code{type} is a
disk image type, and must be either @code{x64}, @code{d64} (both VC1541/2031), 
@code{g64} (VC1541/2031 but in GCR coding), @code{d71} (VC1571), @code{d81}
(VC1581), @code{d80} (CBM8050) or @code{d82} (CBM8250/1001). 
Otherwise, format the disk in the current unit, if any.

@item gcrformat <diskname,id> <imagename>
Create and format a G64 disk image named @code{imagename}.

@item help [<command>]
Explain specified command.  If no command is specified, list available
ones.

@item info [<unit>]
Display information about unit @code{unit} (if unspecified, use the current
one).

@item list [<pattern>]
List files matching @code{pattern} (default is all files).

@item quit
Exit (same as @code{exit}).

@item read <source> [<destination>]
Read @code{source} from the disk image and copy it into @code{destination} in
the file system.  If @code{destination} is not specified, copy it into a
file with the same name as @code{source}.", 

@item rename <oldname> <newname>
Rename @code{oldname} into @code{newname}.  The files must be on the
same drive.

@item tape <t64name> [<file1> ... <fileN>]
Extract files from a T64 image.

@item unit <number>
Make unit @code{number} the current unit.

@item unlynx <lynxname> [<unit>]
Extract the specified Lynx image file into the specified unit (default
is the current unit).

@item validate [<unit>]
Validate the disk in unit @code{unit}.  If @code{unit} is not specified,
validate the disk in the current unit.

@item write <source> [<destination>]
Write @code{source} from the file system into @code{destination} on a
disk image.

@item zcreate <x64name> <zipname> [<label,id>]
Create an X64 disk image out of a set of four Zipcoded files named
@code{1!zipname}, @code{2!zipname}, @code{3!zipname} and
@code{4!zipname}.

@end table

@node c1541 executing shell commands,  , c1541 commands and options, c1541
@section Executing shell commands

If you want to execute a shell command from withing @code{c1541}, just
prepend it with an exclamation mark (@code{!}).  For example,

@example
!ls -la
@end example

will execute the command @code{ls -la}, which will show you all the
files in the current directory.

@c This would be nice!
@c @node Examples,  , Commands, c1541
@c @section c1541 examples

@node File formats, Acknowledgments, c1541, Top
@chapter The emulator file formats

This chapter gives a technical description of the various files
supported by the emulators.

@menu
* T64::                         The tape image format
* G64::                         The GCR-encoded disk image format
@end menu

@node T64, G64, File formats, File formats
@section The T64 tape image format

(This section was taken from the C64S distribution.)

The @code{T64} File Structure was developed by Miha Peternel for use in
the C64S emulator.  It is easy to use and allows future extensions.

@menu
* T64 file structure::          
* T64 tape record::             
* T64 file record::             
@end menu

@node T64 file structure, T64 tape record, T64, T64
@subsection T64 File structure

@multitable @columnfractions .3 .3 .4
@item @b{Offset}
@tab @b{Size}
@tab @b{Description}
@item 0
@tab 64
@tab tape record
@item 64
@tab 32*n
@tab file records for n directory entries
@item 64+32*n
@tab varies
@tab binary contents of the files
@end multitable

@node T64 tape record, T64 file record, T64 file structure, T64
@subsection Tape Record

@multitable @columnfractions .3 .3 .4
@item @b{Offset}
@tab @b{Size}
@tab @b{Description}
@item 0
@tab 32
@tab DOS tape description + EOF (for type)
@item 32
@tab 2
@tab tape version ($0200)
@item 34
@tab 2
@tab number of directory entries
@item 36
@tab 2
@tab number of used entries (can be 0 in my loader)
@item 38
@tab 2
@tab free
@item 40
@tab 24
@tab user description as displayed in tape menu
@end multitable

@node T64 file record,  , T64 tape record, T64
@subsection  File record

@multitable @columnfractions .3 .3 .4
@item @b{Offset}
@tab @b{Size}
@tab @b{Description}
@item 0
@tab 1
@tab entry type (see below)
@item 1
@tab 1
@tab C64 file type
@item 2
@tab 2
@tab start address
@item 4
@tab 2
@tab end address
@item 6
@tab 2
@tab free
@item 8
@tab 4
@tab offset of file contents start within T64 file
@item 12
@tab 4
@tab free
@item 16
@tab 16
@tab C64 file name
@end multitable

Valid entry types are:

@multitable @columnfractions .3 .7
@item @b{Code}
@tab @b{Explanation}
@item @code{0}
@tab free entry
@item @code{1}
@tab normal tape file
@item @code{2}
@tab tape file with header: header is saved just before file data
@item @code{3}
@tab memory snapshot v0.9, uncompressed
@item @code{4}
@tab tape block
@item @code{5}
@tab digitized stream
@item @code{6} @dots{} @code{255}
@tab reserved
@end multitable

Notes:

@itemize @bullet
@item VICE only supports file type @code{1}.
@item Types @code{3}, @code{4} and @code{5} are subject to change (and
are rarely  used).
@end itemize

@node G64,  , T64, File formats
@section The G64 GCR-encoded disk image format

(This section was contributed by Peter Schepers and slightly edited by
Ettore Perazzoli.)

This format was defined in 1998 as a cooperative effort between several
emulator people, mainly Per Hkan Sundell, author of the CCS64 C64
emulator, Andreas Boose of the VICE CBM emulator team and Joe
Forster/STA, the author of Star Commander.  It was the first real public
attempt to create a format for the emulator community which removed
almost all of the drawbacks of the other existing image formats, namely
@code{D64}.

The intention behind @code{G64} is not to replace the widely used
@code{D64} format, as @code{D64} works fine with the vast majority of
disks in existence.  It is intended for those small percentage of
programs which demand to work with the 1541 drive in a non-standard way,
such as reading or writing data in a custom format.  The best example is
with speeder software such as Action Cartridge in Warp Save mode or
Vorpal which write track/sector data in another format other than
standard GCR.  The other obvious example is copy-protected software
which looks for some specific data on a track, like the disk ID, which
is not stored in a standard @code{D64} image.

@code{G64} has a deceptively simply layout for what it is capable of
doing.  We have a signature, version byte, some predefined size values,
and a series of offsets to the track data and speed zones.  It is what's
contained in the track data areas and speed zones which is really at the
heart of this format.

Each track entry in simply the raw stream of GCR data, just what a read
head would see when a diskette is rotating past it.  How the data gets
interpreted is up to the program trying to access the disk.  Because the
data is stored in such a low-level manner, just about anything can be
done.  Most of the time I would suspect the data in the track would be
standard sectors, with SYNC, GAP, header, data and checksums.  The
arrangement of the data when it is in a standard GCR sector layout is
beyond the scope of this document.

Since it is a flexible format in both track count and track byte size,
there is no ``standard'' file size.  However, given a few constants like
42 tracks and halftracks, a track size of 7928 bytes and no speed offset
entries, the typical file size will a minimum of 333744 bytes.

Below is a dump of the header, broken down into its various parts.
After that will be an explanation of the track offset and speed zone
offset areas, as they demand much more explanation.

@example
Addr  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
----  -----------------------------------------------
0000: 47 43 52 2D 31 35 34 31 00 54 F8 1E .. .. .. ..
@end example

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $0000-0007
@tab File signature (@code{GCR-1541})
@item $0008
@tab @code{G64} version (presently only $00 defined)
@item $0009
@tab Number of tracks in image (usually $54, decimal 84)
@item $000A-000B
@tab Size of each stored track in bytes (usually 7928, or $1EF8) in LO/HI format.
@end multitable

An obvious question here is ``why are there 84 tracks defined when a
normal @code{D64} disk only has 35 tracks?''  Well, by definition, this
image includes all half-tracks, so there are actually 42 tracks and 42
half tracks.  The 1541 stepper motor can access up to 42 tracks and the
in-between half-tracks.  Even though using more than 35 tracks is not
typical, it was important to define this format from the start with what
the 1541 is capable of doing, and not just what it typically does.

At first, the defined track size value of 7928 bytes may seem to be
arbitrary, but it is not.  It is determined by the fastest write speed
possible (speed zone 0), coupled with the average rotation speed of the
disk (300 rpm).  After some math, the answer that actually comes up is
7692 bytes.  Why the discrepency between the actual size of 7692 and the
defined size of 7928? Simply put, not all drives rotate at 300 rpm.
Some can be faster or slower, so a upper safety margin of +3% was built
added, in case some disks rotate slower and can write more data.  After
applying this safety factor, and some rounding-up, 7928 bytes per track
was arrived at.

Also note that this upper limit of 7928 bytes per track really only
applies to 1541 and compatible disks.  If this format were applied to
another disk type like the SFD1001, this value would be higher.

Below is a dump of the first section of a @code{G64} file, showing the offsets
to the data portion for each track and half-track entry. Following that
is a dump of the speed zone offsets.

@example
Addr  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
----  -----------------------------------------------
0000: .. .. .. .. .. .. .. .. .. .. .. .. AC 02 00 00
0010: 00 00 00 00 A6 21 00 00 00 00 00 00 A0 40 00 00
0020: 00 00 00 00 9A 5F 00 00 00 00 00 00 94 7E 00 00
0030: 00 00 00 00 8E 9D 00 00 00 00 00 00 88 BC 00 00
0040: 00 00 00 00 82 DB 00 00 00 00 00 00 7C FA 00 00
0050: 00 00 00 00 76 19 01 00 00 00 00 00 70 38 01 00
0060: 00 00 00 00 6A 57 01 00 00 00 00 00 64 76 01 00
0070: 00 00 00 00 5E 95 01 00 00 00 00 00 58 B4 01 00
0080: 00 00 00 00 52 D3 01 00 00 00 00 00 4C F2 01 00
0090: 00 00 00 00 46 11 02 00 00 00 00 00 40 30 02 00
00A0: 00 00 00 00 3A 4F 02 00 00 00 00 00 34 6E 02 00
00B0: 00 00 00 00 2E 8D 02 00 00 00 00 00 28 AC 02 00
00C0: 00 00 00 00 22 CB 02 00 00 00 00 00 1C EA 02 00
00D0: 00 00 00 00 16 09 03 00 00 00 00 00 10 28 03 00
00E0: 00 00 00 00 0A 47 03 00 00 00 00 00 04 66 03 00
00F0: 00 00 00 00 FE 84 03 00 00 00 00 00 F8 A3 03 00
0100: 00 00 00 00 F2 C2 03 00 00 00 00 00 EC E1 03 00
0110: 00 00 00 00 E6 00 04 00 00 00 00 00 E0 1F 04 00
0120: 00 00 00 00 DA 3E 04 00 00 00 00 00 D4 5D 04 00
0130: 00 00 00 00 CE 7C 04 00 00 00 00 00 C8 9B 04 00
0140: 00 00 00 00 C2 BA 04 00 00 00 00 00 BC D9 04 00
0150: 00 00 00 00 B6 F8 04 00 00 00 00 00 .. .. .. ..
@end example

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $000C-000F
@tab Offset to stored track 1.0 ($000002AC, in LO/HI format, see below for more)
@item $0010-0013
@tab Offset to stored track 1.5 ($00000000)
@item $0014-0017
@tab Offset to stored track 2.0 ($000021A6)
@item ...
@item $0154-0157
@tab Offset to stored track 42.0 ($0004F8B6)
@item $0158-015B
@tab Offset to stored track 42.5 ($00000000)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
0150: .. .. .. .. .. .. .. .. .. .. .. .. 03 00 00 00
0160: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
0170: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
0180: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
0190: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01A0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01B0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01C0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01D0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01E0: 00 00 00 00 02 00 00 00 00 00 00 00 02 00 00 00
01F0: 00 00 00 00 02 00 00 00 00 00 00 00 02 00 00 00
0200: 00 00 00 00 02 00 00 00 00 00 00 00 02 00 00 00
0210: 00 00 00 00 02 00 00 00 00 00 00 00 01 00 00 00
0220: 00 00 00 00 01 00 00 00 00 00 00 00 01 00 00 00
0230: 00 00 00 00 01 00 00 00 00 00 00 00 01 00 00 00
0240: 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00
0250: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0260: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0270: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0280: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0290: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
02A0: 00 00 00 00 00 00 00 00 00 00 00 00 .. .. .. ..
@end example

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $015C-015F
@tab Speed zone entry for track 1 ($03, in LO/HI  format, see below for more)
@item $0160-0163
@tab Speed zone entry for track 1.5 ($03)
@item ...
@item $02A4-02A7
@tab Speed zone entry for track 42 ($00)
@item $02A8-02AB
@tab Speed zone entry for track 42.5 ($00)
@end multitable

Starting here at $02AC is the first track entry (from above, it is the
first entry for track 1.0)

The track offsets (from above) require some explanation.  When one is
set to all 0's, no track data exists for this entry.  If there is a
value, it is an absolute reference into the file (starting from the
beginning of the file).  From the track 1.0 entry we see it is set for
$000002AC.  Going to that file offset, here is what we see...

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
02A0: .. .. .. .. .. .. .. .. .. .. .. .. 0C 1E FF FF
02B0: FF FF FF 52 54 B5 29 4B 7A 5E 95 55 55 55 55 55
02C0: 55 55 55 55 55 55 FF FF FF FF FF 55 D4 A5 29 4A
02D0: 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52
@end example

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $02AC-02AD
@tab Actual size of stored track (7692 or $1E0C, in LO/HI format)
@item $02AE-02AE+$1E0C
@tab Track data
@end multitable

Following the track data is filler bytes.  In this case, there are 368
bytes of unused space.  This space can contain anything, but for the
sake of those wishing to compress these images for storage, they should
all be set to the same value.  In the sample I used, these are all set
to $FF.

Below is a dump of the end of the track 1.0 data area.  Note the actual
track data ends at address $20B9, with the rest of the block being
unused, and set to $FF.

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
1FE0: 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52
1FF0: 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94
2000: A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5
2010: 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29
2020: 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A
2030: 55 55 55 55 55 55 FF FF FF FF FF FF FF FF FF FF
2040: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2050: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2060: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2070: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2080: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2090: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20A0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20B0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20C0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20D0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20E0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20F0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2100: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2110: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2120: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2130: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2140: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2150: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2160: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2170: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2180: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2190: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
21A0: FF FF FF FF FF FF .. .. .. .. .. .. .. .. .. ..
@end example

The speed offset entries can be a little more complex. The 1541 has four
speed zones defined, which means the drive can write data at four
distinct speeds.  On a normal 1541 disk, these zones are as follows:

@multitable @columnfractions .5 .5
@item @b{Track Range}
@tab @b{Speed Zone}
@item 1-17
@tab 3  (highest writing speed)
@item 18-24
@tab 2
@item 25-30
@tab 1
@item 31 and up
@tab 0 (lowest writing speed)
@end multitable

Note that you can, through custom programming of the 1541, change the
speed zone of any track to something different (change the 3 to a 0) and
write data differently.  From the dump of the speed offset entries
above, we see that all the entries are in the range of 0-3. If any entry
is less than 4, this is not considered a speed offset but defines the
whole track to be recorded at that one speed.

In the example I had, there were no offsets defined, so no speed zone
dump can be shown.  However, I can define what should be there.  You
will have a block of data, 1982 bytes long.  Each byte is encoded to
represent the speed of 4 bytes in the track offset area, and is broken
down as follows:

@example
Speed entry $FF:  in binary %11111111
                             |'|'|'|'
                             | | | |
                             | | | +- 4'th byte speed (binary 11, 3 dec)
                             | | +--- 3'rd byte speed (binary 11, 3 dec)
                             | +----- 2'nd byte speed (binary 11, 3 dec)
                             +------- 1'st byte speed (binary 11, 3 dec)
@end example

It was very smart thinking to allow for two speed zone settings, one in
the offset block and another defining the speed on a per-byte basis.  If
you are working with a normal disk, where each track is one constant
speed, then you don't need the extra blocks of information hanging
around the image, wasting space.

What may not be obvious is the flexibility of this format to add tracks
and speed offset zones at will.  If a program decides to write a track
out with varying speeds, and no speed offset exist, a new block will be
created by appending it to the end of the image, and the offset pointer
for that track set to point to the new block.  If a track has no offset
yet, meaning it doesn't exist (like a half-track), and one needs to be
added, the same procedure applies.  The location of the actual track or
speed zone data is not important, meaning they do not have to be in any
particular order since they are all referenced by the offsets at the
beginning of the image.

@node Acknowledgments, Copyright, File formats, Top
@chapter 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:
@itemize @bullet
@c The Texinfo manual says we should not use @b though!

@item
@b{Daniel Sladic} started the work on hardware-level 1541 emulation
and wrote the new monitor introduced with VICE 0.15.

@item
@b{Andreas Boose} 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.  He also added cartridge support and
has been the main head behind the drive and datasette emulation
since version 0.15.  Also added several UI elements to the
MSDOS and MS-Windows ports. He rewrote the C128 emulation
adding Z80 mode, C64 mode and function ROM support.

@item
@b{Dag Lem} implemented the reSID SID emulation
engine.

@item
@b{Tibor Biczo} improved the MS-Windows port.

@item
@b{Andreas Dehmel} wrote the Acorn RISC OS port.

@item
@b{Thomas Bretz} responsible for the OS/2 port.

@item
@b{Andreas Matthies} improved the
datasette support, the VIC20 video emulation and some ui stuff
in the Win32 and MSDOS port. He also wrote the BeOS port.

@item
@b{Martin Pottendorfer}
Implemented Gnome Port based on Oliver Schaertels GTK+ port
Added support code for internationalization based on gettext
Translated the Unix Port to German
Implemented the fliplists + ui (unix).

@item
@b{Markus Brenner} added VDC emulation to x128
and added support for some more cartridges.

@item
@b{Spiro Trikaliotis} wrote the Win32
console implementation for the built-in monitor and provided
some further patches.

@item
@b{Marco van den Heuvel} Translated the UI to Dutch.
Internationalization support for the Win32 port. Wrote the
GEORAM and RamCart code. Wrote the c64 +60K and 256K
expansions code. Made the ethernet support for the Msdos
port. Maintains the QNX 6.x, Solaris and newly resurrected
OS/2 binary ports. Added new .crt carts support. Added
new screenshot formats. And lots of other fixes.

@end itemize

Former team members:

@itemize @bullet

@item
@b{Ettore Perazzoli}
Copyright @copyright{} 1996-1999
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.  He also wrote the MS-DOS
port and the initial MS-Windows port (well, somebody had to do
it).

@item
@b{Andr Fachat}
Copyright @copyright{} 1996-2001
Wrote the PET and CBM-II emulators, the CIA and VIA emulation,
the IEEE488 interface, implemented the IEC serial bus in `xvic'
and made tons of bug fixes.

@item
@b{Teemu Rantanen}
Copyright @copyright{} 1993-1994, 1997-1999
Implemented the SID emulation and the trap-based disk drive and
serial bus implementation; added support for multiple display
depths under X11.  Also wrote `c1541'

@item
@b{Jouko Valta}
Copyright @copyright{} 1993-1996
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.

@item
@b{Jarkko Sonninen}
Copyright @copyright{} 1993-1994
He 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.

@end itemize

External contributors:

@itemize @bullet

@item
@b{Michael Schwendt} 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.

@item
@b{Christian Bauer} 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.

@item
@b{Wolfgang Lorenz} wrote an excellent 6510 test suite that helped us
to debug the CPU emulation.

@item
@b{Giuliano Procida} is the maintainer
of the VICE @code{deb} package for the Debian distribution, and also
helped proofreading the documentation.

@item
@b{Marko Mkel} wrote lots of CPU documentation.

@item
@b{Chris Sharp} wrote the AIX sound driver.

@item
@b{Krister Walfridsson} implemented joystick and sound support for
NetBSD.

@item
@b{Mattias Engdegrd} got non-default depths to work.

@item
@b{Peter Andrew Felvegi aka Petschy}
fixed a couple of bugs in the fast serial emulation.

@item
@b{Olaf Seibert} contributed some PET, and disk drive patches.

@item
@b{Daniel Fandrich} contributed some disk drive patches.

@item
@b{Heiko Selber} contributed some VIC20 I/O patches.

@item
@b{Steven Tieu} added initial support for 16/24 bpp X11 displays.

@item
@b{Alexander Lehmann} added complete support for all the VIC20 memory
configurations for the old VICE 0.12.

@item
@b{Lionel Ulmer} implemented joystick support for Linux and a first
try of a SID emulation for SGI machines.

@item
@b{Bernhard Kuhn} made some joystick improvements for Linux.

@item
@b{Gerhard Wesp} contributed the
@code{extract} command in @code{c1541}.

@item
@b{Ricardo Ferreira} contributed the
@code{unlynx} and @code{system} commands in @code{c1541}.

@item
@b{Tomi Ollila} donated @code{findpath.c}.

@item
@b{Richard Hable} contributed the initial version of the REU
Emulation.

@item
@b{Vesa-Matti Puro} wrote the very first 6502 CPU
emulator in x64 0.1.0.  That was the beginning of the story@dots{}

@item
@b{Dan Miner} contributed some patches to the fast disk drive
emulation.

@item
@b{Frank Prindle} contributed some patches.

@item
@b{Peter Weighill} gave many ideas and contributed the ROM patcher.

@item
@b{Dominique Strigl}, @b{Craig Jackson} and @b{Lasse Jyrkinen}
contributed miscellaneous patches in the old X64 times.

@item
@b{Per Olofsson} digitalized the C64 colors used in the default
palette.

@item
@b{Paul David Doherty} wrote
@code{zip2disk}, on which the Zipcode support in @code{c1541} is based.

@item
@b{Robert H. Forsman Jr.}, @b{Brian Totty} and @b{Robert W. McMullen}
provided the widget set for implementing the @code{Xaw} GUI.

@item
@b{Shawn Hargreaves} wrote
Allegro, the graphics and audio library used in the MS-DOS version.

@item
@b{Peter Schepers} contributed a document describing the G64 image
format.

@item
@b{Oliver Schaertel} wrote the X11 full screen, parts of custom ROM
set support and 1351 mouse emulation for unix.

@item
@b{Luca Montecchiani} contributed a new Unix joystick driver.

@item
@b{Dirk Farin} rewrote the MITSHM code.

@item
@b{Manfred Spraul} wrote the MS-Windows text lister.

@item
@b{Eric} provided the french translation for the Unix ports.

@item
@b{Andrea Musuruane} provided the italian translation for the Unix
ports

@item
@b{Michael Klein} contributed the ESD sound driver and some patches.

@item
@b{David Holz} provided a label file which gives the built-in monitor
the labels for the C64.

@item
@b{Lasse rni} contributed the Windows Multimedia sound driver

@item
@b{Frank Knig} contributed the Win32 joystick autofire feature.

@item
@b{John Selck} wrote the fast PAL emulation.

@item
@b{webulator} provided win32 drag & drop support

@item
@b{ck!} provided a win32 cbm character font.
@end itemize

@itemize @bullet

@item
@b{Lutz Sammer}
@item
@b{Ralph Mason}
@item
@b{George Caswell}
@item
@b{Per Olofsson}
@item
@b{Jasper Phillips}
@item
@b{Luca Forcucci}
@item
@b{Asger Alstrup}
@item
@b{Bernhard Schwall}
@item
@b{Salvatore Valente}
@item
@b{Arthur Hagen}
@item
@b{Douglas Carmichael}
@item
@b{Ferenc Veres}
@item
@b{Andrea Musuruane}
@item
@b{Frank Reichel}
@item
@b{Ullrich von Bassewitz}
@item
@b{Holger Busse}
@end itemize

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


@node Copyright, Contacts, Acknowledgments, Top
@chapter Copyright

@itemize @bullet
@item
Copyright @copyright{} 1998-2006 Andreas Boose
@item
Copyright @copyright{} 1998-2006 Dag Lem
@item
Copyright @copyright{} 1998-2006 Tibor Biczo
@item
Copyright @copyright{} 1999-2006 Andreas Dehmel
@item
Copyright @copyright{} 1999-2006 Andreas Matthies
@item
Copyright @copyright{} 1999-2006 Martin Pottendorfer
@item
Copyright @copyright{} 2000-2006 Spiro Trikaliotis
@item
Copyright @copyright{} 2005-2006 Marco van den Heuvel
@item
Copyright @copyright{} 1999-2005 Thomas Bretz
@item
Copyright @copyright{} 2003-2005 David Hansel
@item
Copyright @copyright{} 2000-2004 Markus Brenner

@item
Copyright @copyright{} 1997-2001 Daniel Sladic
@item
Copyright @copyright{} 1996-1999 Ettore Perazzoli
@item
Copyright @copyright{} 1996-1999 Andr Fachat
@item
Copyright @copyright{} 1993-1994, 1997-1999 Teemu Rantanen
@item
Copyright @copyright{} 1993-1996 Jouko Valta
@item
Copyright @copyright{} 1993-1994 Jarkko Sonninen
@end itemize


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


@node Contacts, Concept Index, Copyright, Top
@chapter Contact information

@menu
* Home page::                   The official VICE WWW page.
* Sending feedback::            How to report impressions and
                                bugs to the authors.
* Contributing::                How to help developing VICE.
* Newsgroups::                  VICE-related Usenet groups.
* FAQs you should read::        VICE-related Frequently Asked Questions.
@end menu

@node Home page, Sending feedback, Contacts, Contacts
@section VICE home page

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

@example
@uref{http://www.viceteam.org/}
@end example

If you are going to report a bug, please check those pages @emph{first};
it is possible that the problem you encountered has already been
fixed with a newer version.

@node Sending feedback, Contributing, Home page, Contacts
@section How to send feedback

If you want to report bugs, make suggestions or contribute to
the project, please email the VICE team mailing list:

@itemize @bullet

@item
VICE Mailing List (@email{vice-devel@@firenze.linux.it}) for all
general questions, bug reports, suggestions.

@end itemize

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.

@itemize @bullet

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

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

@item
Please don't send @emph{any} binaries without asking first.

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

@itemize @bullet
@item
the VICE documentation (you are reading it!);
@item
the VICE FAQ (it is available on the Internet, and reachable from the
VICE home page:
@uref{http://www.viceteam.org/});
@item
the @code{comp.emulators.cbm} and @code{comp.sys.cbm} FAQs (@pxref{FAQs
you should read}).
@end itemize

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

@item
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
(@uref{http://sta.c64.org/sc.html}).  And no, you cannot read C64 disks
with your old 5"1/4 PC drive.

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

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

@item
Please write in English.

@end itemize

In any case, we would be @emph{really} glad to receive your comments
about VICE.  We cannot always answer all the email, but we surely read
all of it.

Thanks!


@node Contributing, Newsgroups, Sending feedback, Contacts
@section How to contribute

If you want to make a major contribution, please @emph{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 @emph{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:

@itemize @bullet
@item
a unified diff file containing all the changes you have made
@samp{diff -u} is fine; please don't use plain @samp{diff});
@item
GNU-style @file{ChangeLog} entries with a description of the changes you
have made (look at the @file{ChangeLog}s provided with the original VICE
sources for an example).
@end itemize

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

People willing to port VICE to other platforms are always welcome.
But notice from experience it will take at least a full year of
continious work to write a well working and stable port.

@node Newsgroups, FAQs you should read, Contributing, Contacts
@section Interesting newsgroups

There are some Usenet newsgroups you might be interested in:

@itemize @bullet

@item
@code{comp.emulators.cbm}, discussing about emulators of Commodore 8-bit
machines (definitely not Amiga emulators).

@item
@code{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).

@item
@code{comp.emulators.misc}, discussing emulators in general.

@end itemize

@node FAQs you should read,  , Newsgroups, Contacts
@section FAQs you should read

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

@node Concept Index, Resource Index, Contacts, Top
@unnumbered Concept Index

@printindex cp

@node Resource Index,  , Concept Index, Top
@unnumbered Index of Resources

@printindex vr

@contents

@bye