\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 global options
@setchapternewpage on
@firstparagraphindent none
@paragraphindent 0
@exampleindent 0

@c define platformall as the default
@ifclear platformall
@set platformall
@end ifclear

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

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

@c define platformamiga if any of the following are set:
@ifset platformamigaos3
@set platformamiga
@end ifset
@ifset platformamigaos4
@set platformamiga
@end ifset
@ifset platformmorphos
@set platformamiga
@end ifset
@ifset platformaros
@set platformamiga
@end ifset

@c define platformunix if any of the following are set:
@ifset platformxaw
@set platformunix
@end ifset
@ifset platformgtk2
@set platformunix
@end ifset
@ifset platformgtk3
@set platformunix
@end ifset

@c define platformgtk if any of the following are set:
@ifset platformgtk2
@set platformgtk
@end ifset
@ifset platformgtk3
@set platformgtk
@end ifset

@c define platformsdl if any of the following are set:
@ifset platformdingoo
@set platformsdl
@end ifset

@c define all amiga platforms is platformamigaall is set:
@ifset platformamigaall
@set platformamigaos3
@set platformamigaos4
@set platformmorphos
@set platformaros
@end ifset

@c undef platformall if any of the following are set:
@ifset platformamiga
@clear platformall
@end ifset
@ifset platformbeos
@clear platformall
@end ifset
@ifset platformdos
@clear platformall
@end ifset
@ifset platformos2
@clear platformall
@end ifset
@ifset platformsdl
@clear platformall
@end ifset
@ifset platformunix
@clear platformall
@end ifset
@ifset platformosx
@clear platformall
@end ifset
@ifset platformwindows
@clear platformall
@end ifset

@c set all platform defines if platformall is still defined
@ifset platformall
@set platformamiga
@set platformamigaall
@set platformamigaos3
@set platformamigaos4
@set platformmorphos
@set platformaros
@set platformbeos
@set platformdos
@set platformos2
@set platformsdl
@set platformdingoo
@set platformunix
@set platformxaw
@set platformgtk
@set platformgtk2
@set platformgtk3
@set platformosx
@set platformwindows
@end ifset

@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

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

@titlepage

@title VICE, the Versatile Commodore Emulator

@c page
@vskip 0pt plus 1filll
@c section used in file generation, keep to the format used.
@c ---vice-core-team---
Copyright @copyright{} 1999-2015 Andreas Matthies
Copyright @copyright{} 1999-2015 Martin Pottendorfer
Copyright @copyright{} 2005-2015 Marco van den Heuvel
Copyright @copyright{} 2007-2015 Fabrizio Gennari
Copyright @copyright{} 2007-2015 Daniel Kahlin
Copyright @copyright{} 2009-2015 Groepaz
Copyright @copyright{} 2009-2015 Errol Smith
Copyright @copyright{} 2010-2015 Olaf Seibert
Copyright @copyright{} 2011-2015 Marcus Sutton
Copyright @copyright{} 2011-2015 Kajtar Zsolt
@c ---vice-core-team-end---

@c ---ex-team---
Copyright @copyright{} 2012-2014 Benjamin 'BeRo' Rosseaux
Copyright @copyright{} 2011-2014 Ulrich Schulz
Copyright @copyright{} 2011-2014 Stefan Haubenthal
Copyright @copyright{} 2011-2014 Thomas Giesel
Copyright @copyright{} 2009-2014 Ingo Korb
Copyright @copyright{} 2008-2014 Antti S. Lankila
Copyright @copyright{} 2006-2014 Christian Vogelgsang
Copyright @copyright{} 1998-2014 Dag Lem
Copyright @copyright{} 2000-2011 Spiro Trikaliotis
Copyright @copyright{} 2007-2011 Hannu Nuotio
Copyright @copyright{} 1998-2010 Andreas Boose
Copyright @copyright{} 1998-2010 Tibor Biczo
Copyright @copyright{} 2007-2010 M. Kiesel
Copyright @copyright{} 1999-2007 Andreas Dehmel
Copyright @copyright{} 2003-2005 David Hansel
Copyright @copyright{} 2000-2004 Markus Brenner
Copyright @copyright{} 1999-2004 Thomas Bretz
Copyright @copyright{} 1997-2001 Daniel Sladic
Copyright @copyright{} 1996-2001 André Fachat
Copyright @copyright{} 1996-1999 Ettore Perazzoli
Copyright @copyright{} 1993-1994, 1997-1999 Teemu Rantanen
Copyright @copyright{} 1993-1996 Jouko Valta
Copyright @copyright{} 1993-1994 Jarkko Sonninen
@c ---ex-team-end---
@c end of file generation section.

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

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

* Platform-specific features::  Host platform specific features.

* 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@dots{}

* Concept Index::
* Resource Index::
* Command-line 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, C64DTV, C128, VIC20, PET, PLUS4, SCPU64 and CBM-II computers
within a single package.  The emulators run as separate programs, but have
the same user interface, share the same settings and support the same
file formats.

@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 C64DTV, C128, PET, PLUS4, SCPU64 and CBM-II emulators to
be as good as the C64 or VIC20 one, as they are still under construction.

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

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


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

As of version 2.3, two C64 emulators are provided: @samp{x64} (fast)
and @samp{x64sc} (accurate).

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

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

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

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


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

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

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


@node C128 emulator features, VIC20 emulator features, C64DTV 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, 2 MHz mode, Z80 emulation plus all the features of the
C64 emulation.


@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 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: add link to PETdoc.txt

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: add link to PETdoc.txt

The PET 8296-G is a 8296 with built-in 8250 low-profile dual disk drive.

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

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

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

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

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

Moreover, the secondary addresses used are now @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: add link to section


@node CBM-II emulator features, SCPU64 emulator features, 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 SCPU64 emulator features, Keyboard emulation, CBM-II emulator features, Preface
@section SCPU64 emulator features

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

@itemize @bullet
@item 20 MHz asynchronous single cycle 65816 CPU core with proper dummy and invalid cycle handling.
@item 128 KiB static RAM, 0-16 MiB SIMM RAM, 64-512 KiB EPROM emulated and their respective timing details.
@item All RAM optimization configurations supported with write buffer.
@item I/O area access delays, write through to SRAM implemented.
@item Memory mappings including cartridge and boot memory map and kernal shadow.
@item Hardware registers and switches implemented.
@item Replacement SCPU64 ROM compatible with the original to avoid distribution problems
@item It's using the single cycle VICII core for accurate simulation
@end itemize

Still to do:

@itemize @bullet
@item Measure and verify VICII interrupt phase shift
@item Measure and verify BA phase shift
@item SIMM RAM extra 7.5 cycle refresh delay every 10us missing.
@item CPU NMI support for ``reset'' button
@end itemize

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

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

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

@node Keyboard emulation, Joystick emulation, SCPU64 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 FIXME: add a detailed list of all keys

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

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

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

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

The drives 1001, 8050 and 8250 do actually have the very same DOS
ROM. Only the code in the FDC is different, which is taken care of by
VICE. So for all three of those disk drives, only @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{P64} NRZI flux pulse 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{D1M} FD2000/FD4000 DD disk image format

@item
@code{D2M} FD2000/FD4000 HD disk image format

@item
@code{D4M} FD4000 ED disk image format

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

@item
@code{P00} program files

@item
@code{CRT} C64 cartridge image 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.
 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{vsid}, the SID player

@item
@code{x64}, the fast C64 emulator

@item
@code{x64sc}, the accurate C64 emulator

@item
@code{x64dtv}, the C64DTV 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 (CRTC models)

@item
@code{xcbm5x0}, the CBM-II emulator (VIC-II models)

@item
@code{xscpu64}, the SCPU64 emulator

@end itemize

You can run each of them by simply typing the name from a shell or by configuring
your window manager for example to use them to open disk images.  

If you want to look at the log output, or use the monitor in a port which does
not have a dedicated monitor UI yet (such as the XAW port), you should always 
run them from a terminal window such as @code{xterm} or @code{rxvt}.  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 -config
@item -config <filename>
Specify config file

@findex -logfile
@item -logfile <name>
Specify log file name
(@code{LogFileName}).

@cindex -verbose
@item -verbose
Enable verbose log output.
@cindex -keybuf
@item -keybuf <string>
Put the specified string into the keyboard buffer.
@cindex -console
@item -console
Console mode (for music playback)
@cindex -chdir
@item -chdir <directory>
Change the working directory.
@cindex -autostart
@item -autostart <name>
Autostart <name> (@pxref{Command-line autostart}).
@cindex -autoload
@item -autoload <name>
Attach and autoload tape/disk image <name>

@cindex -1
@item -1 <Name>
Attach <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 <Name> as a disk image to device 8, 9, 10 or 11.

@findex -attach8ro
@findex -attach9ro
@findex -attach10ro
@findex -attach11ro
@item -attach8ro
@itemx -attach9ro
@itemx -attach10ro
@itemx -attach11ro
Attach disk image for drive #8-11 read only
(@code{AttachDevice8Readonly=1}, @code{AttachDevice9Readonly=1}, @code{AttachDevice10Readonly=1}, @code{AttachDevice11Readonly=1})
(all emulators except vsid).

@cindex -attach8rw
@cindex -attach9rw
@cindex -attach10rw
@cindex -attach11rw
@item -attach8rw
@itemx -attach9rw
@itemx -attach10rw
@itemx -attach11rw
Attach disk image for drive #8-11 read write (if possible)
(@code{AttachDevice8Readonly=0}, @code{AttachDevice9Readonly=0}, @code{AttachDevice10Readonly=0}, @code{AttachDevice11Readonly=0})
(all emulators except vsid).

@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{C64DTV}, @code{C128}, @code{PET},  @code{PLUS4}, @code{CBM-II}, @code{SCPU64}
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, SCPU64 and C64 emulators also need the following DOS ROMs for
the hardware-level emulation of the 1540, 1541, 1571, 1581, 2000 and 4000 disk
drives:

@itemize @bullet

@item
@file{dos1540}, the 1540 drive ROM (16 Kbytes)

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

@item
@file{dos2000}, the 2000 drive ROM (32 Kbytes)

@item
@file{dos4000}, the 4000 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
@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.

@item
@file{characters.901640-01.bin}, the SuperPET character generator ROM (4k).
The first half is the same as @file{chargen}, the second half contains,
instead of an upper and lower case set, an ASCII character set and an
APL character set. For these sets, the screen code is equal to the
ASCII/APL code.
@item
@file{waterloo-[abcdf]000.901898-0[1-5].bin},
@file{waterloo-e000.901897-01.bin}.
The Waterloo system ROMs.

@item
@file{hre-9000.324992-02.bin} HiRes Emulator (at $9000) and
@file{hre-a000.324993-02.bin} HiRes BASIC (at $A000).
These are the two roms for supporting the HRE on the 8296.
The ROMs are initialized by the command @code{SYS 36864}.
@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

The SCPU64 needs the following files:

@itemize @bullet

@item
@file{scpu64}, the SCPU64 ROM (128 Kbytes)

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

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

While a Romset file is processed, the directory where the Romset file
was found is temporarily prepended to the search path (@code{Directory}
resource). This also means that if you have a setting for
@code{Directory} in it, its effect is limited to the Romset file itself.

@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 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 DOS 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 DOS at
@uref{ftp://ftp.freesoftware.com/pub/infozip/MSDOS}. Don't use pkunzip
for DOS, 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.
* Monitor settings::            Settings for the built-in monitor.
* 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.

@c @node FIXME
@section Autostart settings

@c @node FIXME
@subsection Autostart resources

@b{All these resources are available for all emulators except vsid.}

@table @code

@vindex AutostartPrgDiskImage
@item AutostartPrgDiskImage
String specifying the filename of the disk image used when autostarting a prg file and "copy to D64" is enabled
(all emulators except vsid).

@vindex AutostartBasicLoad
@item AutostartBasicLoad
Boolean, if true load to basic start using ,8 when autostarting
(all emulators except vsid).

@vindex AutostartRunWithColon
@item AutostartRunWithColon
Boolean, if true put a colon after the load command when autostarting
(all emulators except vsid).

@vindex AutostartHandleTrueDriveEmulation
@item AutostartHandleTrueDriveEmulation
Boolean, if true handle (enable/disable) True Drive Emulation on autostart
(all emulators except vsid).

@vindex AutostartWarp
@item AutostartWarp
Boolean, if true temporarily enable warp mode when autostarting
(all emulators except vsid).

@vindex AutostartPrgMode
@item AutostartPrgMode
Integer specifying the autostart mode for prg files
(all emulators except vsid).
(0: virtual filesystem, 1: inject to RAM, 2: copy to D64)

@vindex AutostartDelayRandom
@item AutostartDelayRandom
Boolean, enables a short random delay on autostart
(all emulators except vsid).

@vindex AutostartDelay
@item AutostartDelay
Integer specifying the maximum delay in frames (0: use default)
(all emulators except vsid).
(0..1000)

@end table

@c @node FIXME
@subsection Autostart command-line options

@b{All these command-line options are available for all emulators except vsid.}

@table @code

@findex -autostartprgdiskimage
@item -autostartprgdiskimage <Name>
Set disk image for autostart of PRG files
(@code{AutostartPrgDiskImage})
(all emulators except vsid).

@findex -basicload, +basicload
@item -basicload
On autostart, load to BASIC start (without ',1')
(@code{AutostartBasicLoad=1})
(all emulators except vsid).
@item +basicload
On autostart, load with ',1'
(@code{AutostartBasicLoad=0})
(all emulators except vsid).

@findex -autostartwithcolon, +autostartwithcolon
@item -autostartwithcolon
On autostart, use the 'RUN' command with a colon, i.e., 'RUN:'
(@code{AutostartRunWithColon=1}).
(all emulators except vsid)
@item +autostartwithcolon
On autostart, do not use the 'RUN' command with a colon; i.e., 'RUN'
(@code{AutostartRunWithColon=0})
(all emulators except vsid).

@findex -autostart-handle-tde, +autostart-handle-tde
@item -autostart-handle-tde
@itemx +autostart-handle-tde
Handle/Do not handle True Drive Emulation on autostart
(@code{AutostartHandleTrueDriveEmulation=1}, @code{AutostartHandleTrueDriveEmulation=0})
(all emulators except vsid).

@findex -autostart-warp, +autostart-warp
@item -autostart-warp
@itemx +autostart-warp
Enable/disable warp mode during autostart
(@code{AutostartWarp=1}, @code{AutostartWarp=0})
(all emulators except vsid).

@findex -autostartprgmode
@item -autostartprgmode <Mode>
Set autostart mode for PRG files
(@code{AutostartPrgMode})
(all emulators except vsid).
(0: virtual filesystem, 1: inject to RAM, 2: copy to D64)

@findex -autostart-delay-random, +autostart-delay-random
@item -autostart-delay-random
@itemx +autostart-delay-random
Enable/disable random delay on autostart
(@code{AutostartDelayRandom})
(all emulators except vsid).

@findex -autostart-delay
@item -autostart-delay <seconds>
Set initial autostart delay (0: use default)
(@code{AutostartDelay})
(all emulators except vsid).
(0..1000)

@end table

@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

@findex -speed
@item -speed <percent>
Specifies the maximum speed as a percentage. @code{0} stands for ``no limit''
(@code{Speed}).

@findex -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
(@code{RefreshRate}).

@findex -warp, +warp
@item -warp
@itemx +warp
Enable/Disable 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::
@end menu

@c @node FIXME
@subsection using openGL Rastersynchronization under X11 

Warning: To get full retro experience with synchronization to the vertrical
raster retrace messing with X11 modelines (resolution and refresh frequencies) 
is necessary. This description is a suggestion - Follow this instructions at 
your own risk!

The following was tested under Ubuntu Linux (8.04) featuring Xorg Xserver 1:7.3+10ubuntu 
and mesa openGL including HW support (NVIDIA driver) supporting glx version 1.4
supplying GLX_SGI_video_sync.

It is assumed that this works also on other systems supporting the
required extensions.

Preconditions:
@itemize @bullet
@item openGL extension GLX_SGI_video_sync in your X11 setup.
  The availability of the extension is checked at startup.
  
@item XRandR extension to switch proper modes (50Hz for PAL, 60Hz for
NTSC) is mandatory, proper modelines in your /etc/X11/xorg.conf must be present.
@end itemize

If your systems lacks 50 or 60Hz modes you might try using
`gtf' (typcally shipped with Xorg, xserver) - see related man page.

You might need to add the output such as:
@example
# 800x600 #@ 50.00 Hz (GTF) hsync: 30.90 kHz; pclk: 31.15 MHz
Modeline "800x600_50.00" 31.15 800 824 904 1008 600 601 604 618 -HSync +Vsync
@end example
to you Monitor Section of /etc/X11/xorg.conf and add the resolution to the `Screen' section.

Sometimes some consistency checks within the display driver drop
this resolutions again.
To drop e.g. the autodetection features in the NVIDIA driver you
might add @code{Option "UseEDID" "FALSE"} in section @code{Device}. 

XRandR cannot cope properly with the DynamicTwinView feature of the
proprietary nvidia driver. You might need 

@code{Option         "DynamicTwinView" "False"}

to get proper results (in Screen or Device section of you xorg.conf).

ATTENTION: Disabling such features might allow X11 to access your HW
in a way that it gets damaged! You are at your own risk!

Enable fullscreen (not necessary, but makes sense):
@itemize @bullet
@item choose your preferred resolution/refresh XRandR Resolutions and 
enable XRandR as fullscreen device (50Hz/PAL or 60Hz/NTSC mode).
@item Activate fullscreen with `Alt-D'.
@item choose `OpenGL Rastersynchronization' in the
video chip menu (VIC-II Settings, VIC Setting, etc.)
@end itemize

Note that:
@itemize @bullet
@item the current implementation is dropping synchronization
silently in case the display frequency isn't aligned (50Hz
for PAL, 60Hz for NTSC). 

@item On some systems the XRandR system isn't informed about desktop
display frequency changes if you switch resolutions via hotkeys like 
CTRL-Alt-+ (Numpad), which is possible e.g. with the X11
implementation of Xorg.

In that case you can override/tell the current frequency via menu:
Settings->VICII Settings->Desktop Refreshrate (e.g. in x64)
(this shouldn't be necessary if you use fullscreen via XRandR.
@end itemize

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

The following resources affect the screen emulation.

@table @code

@vindex HwScalePossible
@item HwScalePossible
Boolean that indicates whether hardware scaling is possible or not.
@vindex openGL_sync
@item openGL_sync
Boolean, if true enable Open-GL frame sync.
@vindex openGL_no_sync
@item openGL_no_sync
Boolean, if true Open-GL sync is not available.

@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
Boolean specifying whether ``warp mode'' is turned on or not.

@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.
x128/xplus4/xvic: (0: symbolic, 1: positional)
x64/x64sc/xscpu64/x64dtv: (0: symbolic, 1: positional, 2: german positional)
xcbm2/xcbm5x0/xpet: (0: UK business symbolic, 1: UK business positional,
2: Graphics symbolic, 3: Graphics positional, 4: German business symbolic,
5: German business positional)

@vindex KeymapSymFile
@item KeymapSymFile
String specifying the name of the keymap file for the symbolic mapping
(@pxref{Keyboard emulation}
@c will be updated as check is done
(all emulators except xcbm2, xcbm5x0, xpet and vsid).

@vindex KeymapSymDeFile
@item KeymapSymDeFile
String specifying the name of the keymap file for the german symbolic mapping.
@c will be updated as check is done
(all emulators except x128, xcbm2, xcbm5x0, xpet, xplus4, xvic and vsid).

@vindex KeymapPosFile
@item KeymapPosFile
String specifying the name of the keymap file for the positional mapping
(@pxref{Keyboard emulation}
@c will be updated as check is done
(all emulators except xcbm2, xcbm5x0, xpet, xplus4 and vsid).

@vindex KeymapBusinessUKSymFile
@item KeymapBusinessUKSymFile
String specifying the name of the keymap file for the symbolic
mapping for the UK business keyboard
(@pxref{Keyboard emulation}
(xcbm2, xcbm5x0 and xpet only).

@vindex KeymapBusinessUKPosFile
@item KeymapBusinessUKPosFile
String specifying the name of the keymap file for the positional
mapping for the UK business keyboard
(@pxref{Keyboard emulation}
(xcbm2, xcbm5x0 and xpet only).

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
@item KeymapGraphicsSymFile
String specifying the name of the keymap file for the symbolic
mapping for the graphics keyboard (@pxref{Keyboard emulation}
(xcbm2, xcbm5x0 and xpet only).

@vindex KeymapGraphicsPosFile
@item KeymapGraphicsPosFile
String specifying the name of the keymap file for the
positional mapping for the graphics keyboard
(@pxref{Keyboard emulation}
(xcbm2, xcbm5x0 and xpet only).

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

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

@end table


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

@table @code

@findex -keymap
@item -keymap <number>
Specifies which keymap is being used
(@code{KeymapIndex}).
x128/xplus4/xvic: (0: symbolic, 1: positional)
x64/x64sc/xscpu64/x64dtv: (0: symbolic, 1: positional, 2: german positional)
xcbm2/xcbm5x0/xpet: (0: UK business symbolic, 1: UK business positional,
2: Graphics symbolic, 3: Graphics positional, 4: German business symbolic,
5: German business positional)

@findex -symkeymap
@item -symkeymap <Name>
Specify filename of the symbolic keymap file
(@code{KeymapSymFile})
@c will be updated as check is done
(all emulators except xcbm2, xcbm5x0, xpet and vsid).

@findex -poskeymap
@item -poskeymap <Name>
Specify filename of the positional keymap file
(@code{KeymapPosFile})
@c will be updated as check is done
(all emulators except xcbm2, xcbm5x0, xpet and vsid).

@findex -symdekeymap
@item -symdekeymap <Name>
Specify filename of the symbolic keymap file
(@code{KeymapSymDeFile})
@c will be updated as check is done
(all emulators except x128, xcbm2, xcbm5x0, xpet, xplus4, xvic and vsid).

@findex -buksymkeymap
@item -buksymkeymap <Name>
Specify filename for the symbolic keymap file for the
UK business keyboard
(@code{KeymapBusinessUKSymFile})
(xcbm2, xcbm5x0 and xpet only).

@findex -bukposkeymap
@item -bukposkeymap <Name>
Specify filename for the positional keymap file for the
UK business keyboard
(@code{KeymapBusinessUKPosFile})
(xcbm2, xcbm5x0 and xpet only).

@findex -grsymkeymap
@item -grsymkeymap <Name>
Specify filename for the symbolic keymap file for the
graphics keyboard
(@code{KeymapGraphicsSymFile})
(xcbm2, xcbm5x0, xpet only).

@findex -grposkeymap
@item -grposkeymap <Name>
Specify filename for the positional keymap file for the
graphics keyboard
(@code{KeymapGraphicsPosFile})
(xcbm2, xcbm5x0 and xpet only).

@findex -bdesymkeymap
@item -bdesymkeymap <Name>
Specify filename for the symbolic keymap file for the
German business keyboard
(@code{KeymapBusinessDESymFile})
(xcbm2, xcbm5x0 and xpet only).

@findex -bdeposkeymap
@item -bdeposkeymap <Name>
Specify filename for the positional keymap file for the
German business keyboard
(@code{KeymapBusinessDEPosFile})
(xcbm2, xcbm5x0 and xpet only).

@end table

@c @node FIXME
@section Joystick settings

@c @node FIXME
@subsection Joystick resources

@table @code

@vindex JoyDevice1
@vindex JoyDevice2
@vindex JoyDevice3
@vindex JoyDevice4
@item JoyDevice1
@itemx JoyDevice2
@itemx JoyDevice3
@itemx JoyDevice4
Integer specifying which joystick device the emulator should use for
joystick emulation for ports 1 - 4, respectively.
(0=None, 1=Joystick 1, 2=Joystick 2, 4=Numpad, 8=Keyset 1, 16=Keyset 2 on OS/2)
(0=None, 1=Numpad, 2=Keyset 1, 3=Keyset 2, 4=HID joystick 0, 5=HID joystick 1 on Mac OS X)
The available joysticks might differ depending on operating system and
joystick support in the OS (Linux joystick module must be
available for example).

@vindex JoyOpposite
@item JoyOpposite
Boolean, if true allow (usually impossible) bitcombinations for opposite directions.
(all emulators except vsid)

@vindex UserportJoy
@item UserportJoy
Boolean to enable/disable extra joysticks
(all emulators except xcbm5x0 and vsid).

@vindex UserportJoyType
@item UserportJoyType
Integer specifying the type of adapter used for the extra joysticks
(all emulators except xcbm5x0 and vsid).
(0: Classical Games/Protovision, 1: PET, 2: Hummer, 3: OEM, 4: Digital Excess/Hitmen, 5: Kingsoft, 6: Starbyte)
4, 5 and 6 are x64, x64sc, xscpu64 and x128 only.

@vindex Mouse
@item Mouse
Boolean, enables mouse emulation
@vindex Mousetype
@item Mousetype
Integer that specifies the type of emulated mouse. (0=1351, 1=NEOS, 2=Amiga,
3=Paddles, 4=Atari CX-22, 5=Atari ST, 6=Smart, 7=Micromys 8 = Koalapad)
@vindex Mouseport
@item Mouseport
Integer that specifies the joystick port the emulated mouse is connected to.
(1=port 1, 2=port 2)

@vindex Lightpen
@item Lightpen
Boolean to enable/disable lightpen emulation
(x64, x64sc, xscpu64, x128 and xvic only).

@vindex LightpenType
@item LightpenType
Integer specifying the type of lightpen
(x64, x64sc, xscpu64, x128 and xvic only).
(0: Pen with button Up, 1: Pen with button Left, 2: Datel Pen, 3: Magnum Light Phaser, 4: Stack Light Rifle)

@vindex KeySet1NorthWest
@vindex KeySet1North
@vindex KeySet1NorthEast
@vindex KeySet1East
@vindex KeySet1SouthEast
@vindex KeySet1South
@vindex KeySet1SouthWest
@vindex KeySet1West
@vindex KeySet1Fire
@item KeySet1NorthWest
@itemx KeySet1North
@itemx KeySet1NorthEast
@itemx KeySet1East
@itemx KeySet1SouthEast
@itemx KeySet1South
@itemx KeySet1SouthWest
@itemx KeySet1West
@itemx KeySet1Fire
Integers specifying the keycodes for keyset 1
(all emulators except vsid).

@vindex KeySet2NorthWest
@vindex KeySet2North
@vindex KeySet2NorthEast
@vindex KeySet2East
@vindex KeySet2SouthEast
@vindex KeySet2South
@vindex KeySet2SouthWest
@vindex KeySet2West
@vindex KeySet2Fire
@item KeySet2NorthWest
@itemx KeySet2North
@itemx KeySet2NorthEast
@itemx KeySet2East
@itemx KeySet2SouthEast
@itemx KeySet2South
@itemx KeySet2SouthWest
@itemx KeySet2West
@itemx KeySet2Fire
Integers specifying the keycodes for keyset 2
(all emulators except vsid).

@vindex KeySetEnable
@item KeySetEnable
Boolean that specifies whether user defined keysets are enabled
(all emulators except vsid).

@vindex KbdbufDelay
@item KbdbufDelay
Integer specifying the additional keyboard delay.
(0: use default)

@end table

@c @node FIXME
@subsection Joystick command-line options

@table @code

@cindex -joydev1
@cindex -joydev2
@item -joydev1 <range>
@itemx -joydev2 <range>
Set the device for joystick emulation of port 1 and 2, respectively.
(@code{JoyDevice1}, @code{JoyDevice2}).
The range for OS/2 is, valid numbers in the range are 0, 1, 2, 4, 8 and 16.
@cindex -extrajoydev1
@cindex -extrajoydev2
@item -extrajoydev1 <0-8>
@itemx -extrajoydev2 <0-8>
Set device for extra joystick port 1 and 2.

@findex -joyopposite, +joyopposite
@item -joyopposite
@itemx +joyopposite
Enable/disable opposite joystick directions
(@code{JoyOpposite=1}, @code{JoyOpposite=0}).
(all emulators except vsid)

@findex -userportjoy, +userportjoy
@item -userportjoy
@itemx +userportjoy
Enable/disable extra joystick(s)
(@code{UserportJoy=1}, @code{UserportJoy=0}).
(all emulators except xcbm5x0 and vsid).

@findex -userportjoytype
@item -userportjoytype <Type>
Set extra joystick type
(@code{UserportJoyType})
(all emulators except xcbm5x0 and vsid).
(0: Classical Games/Protovision, 1: PET, 2: Hummer, 3: OEM, 4: Digital Excess/Hitmen, 5: Kingsoft, 6: Starbyte)
4, 5 and 6 are x64, x64sc, xscpu64 and x128 only.

@cindex -mouse, +mouse
@item -mouse
@itemx +mouse
Enable/Disable mouse grab
@cindex -mousetype
@item -mousetype <value>
Select the mouse type (0 = 1351, 1 = NEOS, 2 = Amiga, 3 = Paddles, 4 = CX-22, 5 = ST, 6 = Smart))
@cindex -mouseport
@item -mouseport <value>
Select the joystick port the mouse is attached to

@findex -lightpen, +lightpen
@item -lightpen
@itemx +lightpen
Enable/disable lightpen emulation
(@code{Lightpen=1}, @code{Lightpen=0})
(x64, x64sc, xscpu64, x128 and xvic only).

@findex -lightpentype
@item -lightpentype <type>
Set lightpen type
(@code{LightpenType})
(x64, x64sc, xscpu64, x128 and xvic only).
(0: Pen with button Up, 1: Pen with button Left, 2: Datel Pen, 3: Magnum Light Phaser, 4: Stack Light Rifle)

@findex -keyset, +keyset
@item -keyset
@itemx +keyset
Enable/disable user defined keyset
(@code{KeySetEnable=1}, @code{KeySetEnable=0})
(all emulators except vsid).

@findex -keybuf-delay
@item -keybuf-delay <value>
Set additional keyboard buffer delay
(@code{KbdbufDelay}).
(0: use default)

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

@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.
(0: flexible, 1: adjusting, 2: exact)

@vindex SoundSampleRate
@item SoundSampleRate
Integer specifying the sampling frequency in Hz
(not all the sound cards and/or sound drivers can support all the
frequencies, so actually the nearest candidate will be chosen).
(8000..48000)

@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 SoundDeviceName
@item SoundDeviceName
String specifying the audio driver.

Implemented drivers are:

@itemize @bullet
@item
@code{ahi}, for the Amiga/Morphos/Aros sound driver.
@item
@code{aix}, for the IBM AIX sound driver.
@item
@code{allegro}, for the DOS Allegro sound driver.
@item
@code{alsa}, for the linux ALSA sound driver.
@item
@code{arts}, for the *nix ARTS sound driver.
@item
@code{beos}, for the BeOS/Zeta/Haiku sound driver.
@item
@code{bsp}, for the BeOS/Zeta/Haiku BeOS Media Kit sound driver.
@item
@code{coreaudio}, for the Mac OS X sound driver.
@item
@code{dart}, for the OS/2 sound driver.
@item
@code{dummy}, fully emulating the sound output chip(s), but not actually playing samples.
@item
@code{dx}, for the Windows Direct-X sound driver.
@item
@code{hpux}, for the HP-UX audio device (unfinished;
@code{SoundDeviceArg} specifies the audio device, @file{/dev/audio} by
default).
@item
@code{midas}, for the DOS Midas sound driver.
@item
@code{pulse}, for the Pulseaudio sound driver.
@item
@code{sdl}, for the Simple DirectMedia Layer audio driver.
@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 and NetBDS audio device (unfinished;
@code{SoundDeviceArg} specifies the audio device, @file{/dev/audio} by
default).
@item
@code{uss}, for the Linux/FreeBSD Universal Sound System driver
(@code{SoundDeviceArg} specifies the audio device, @file{/dev/dsp} by
default);
@item
@code{wmm}, for the Windows Multimedia Waveout sound device.
@end itemize

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

@item
@code{speed}, like @code{dummy} but also calculating samples (mainly
used to evaluate the speed of the sample generator);

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

@vindex SoundRecordDeviceName
@item SoundRecordDeviceName
String specifying the driver used for sound recording.

Implemented drivers are:

@itemize @bullet
@item
@code{aiff}, for the Apple Interchange File Format 16bit sound recorder driver.
@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{fs}, writing samples to a file (specified by
@code{SoundDeviceArg}; default is @file{vicesnd.raw});
@code{iff}, for the Amiga Interchange File Format (8SVX) 8bit sound recorder driver.
@item
@code{mp3}, for the MP3 sound recorder driver.
@item
@code{voc}, for the Creative Voice (VOC) sound recorder driver.
@item
@code{wav}, for the RIFF/WAV sound recorder driver.
@end itemize

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

@vindex SoundRecordDeviceArg
@item SoundRecordDeviceArg
String specifying additional arguments for sound recording.

@vindex SoundFragmentSize
@item SoundFragmentSize
Integer specifying the fragment size.
(0: very small, 1: small, 2: medium, 3: large, 4: very large)

@vindex SoundVolume
@item SoundVolume
Integer specifying the master volume in percent.
(0..100)

@vindex SoundOutput
@item SoundOutput
Integer specifying the type of sound output. Output is selectable between 'system' 
(system decides to use mono or stereo output based on the presence of a stereo sid), 
'always mono' (output is always mono, stereo streams are mixed into a mono stream) 
or 'always stereo' (output is always stereo, mono streams are multiplexed to a stereo 
stream).
(0: system, 1: mono, 2: stereo)

@end table

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

@table @code

@findex -sound, +sound
@item -sound
@itemx +sound
Enable/disable sound emulation
(@code{Sound=1}, @code{Sound=0}).

@findex -soundsync
@item -soundsync <sync>
Specify the sound speed adjustment method
(@code{SoundSpeedAdjustment}).
(0: flexible, 1: adjusting, 2: exact)

@findex -soundrate
@item -soundrate <value>
Specify the sound playback sample rate
(@code{SoundSampleRate}).
(8000..48000)

@findex -soundoutput 
@item -soundoutput <output mode>
Sound output mode
(@code{SoundOutput}).
(0: system decides mono/stereo, 1: always mono, 2: always stereo)

@findex -soundbufsize
@item -soundbufsize <value>
Specify the size of the audio buffer in milliseconds
(@code{SoundBufferSize}).

@findex -soundfragsize
@item -soundfragsize <value>
Set sound fragment size
(@code{SoundFragmentSize}).
(0: very small, 1: small, 2: medium, 3: large, 4: very large)

@findex -sounddev
@item -sounddev <Name>
Specifies the name of the audio device
(@code{SoundDeviceName}).
(ahi/aix/allegro/alsa/arts/beos/bsp/coreaudio/dart/dummy/dx/hpux/midas/pulse/sdl/sgi/sun/uss/wmm)

@findex -soundarg
@item -soundarg <args>
Specifies an additional parameter for the audio device
(@code{SoundDeviceArg}).

@findex -soundrecdev
@item -soundrecdev <name>
Specify recording sound driver
(@code{SoundRecordDeviceName}).
(aiff/dump/fs/iff/mp3/speed/voc/wav)

@findex -soundrecarg
@item -soundrecarg <args>
Specify initialization parameters for recording sound driver
(@code{SoundRecordDeviceArg}).

@findex -soundsuspend
@item -soundsuspend <seconds>
Specify the pause interval when audio underflows (clicks) happen. 0 means no pause is done
(@code{SoundSuspendTime}).

@findex -soundvolume
@item -soundvolume <volume>
Specify the sound volume
(@code{SoundVolume}).
(0..100)

@end table

@c @node FIXME
@section Tape settings

These settings are used to control the hardware-level emulation of the Tape
drive.

@c @node FIXME
@subsection Tape resources

@table @code

@vindex DatasetteResetWithCPU
@item DatasetteResetWithCPU
Boolean specifying whether to reset (rewind) the tape when resetting the CPU.

@vindex DatasetteZeroGapDelay
@item DatasetteZeroGapDelay
Integer specifying the delay in cycles for a zero in the tap.

@vindex DatasetteSpeedTuning
@item DatasetteSpeedTuning
Integer specifying the number of cycles added to each gap in the tap.

@vindex DatasetteTapeWobble
@item DatasetteTapeWobble
Integer specifying the maximum random number of cycles added to each gap in the tap.
@end table

@subsection Tape command-line options

@table @code

@findex -dsresetwithcpu, +dsresetwithcpu
@item -dsresetwithcpu
@itemx +dsresetwithcpu
Enable/disable automatic Datasette-Reset
(@code{DatasetteResetWithCPU=1}, @code{DatasetteResetWithCPU=0}).

@findex -dszerogapdelay
@item -dszerogapdelay <value>
Set delay in cycles for a zero in the tap
(@code{DatasetteZeroGapDelay}).

@findex -dsspeedtuning
@item -dsspeedtuning <value>
Set number of cycles added to each gap in the tap
(@code{DatasetteSpeedTuning}).

@findex -dstapewobble
@item -dstapewobble <value>
Set maximum random number of cycles added to each gap in the tap
(@code{DatasetteTapeWobble}).

@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 Disk
drives.  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 RawDriveDriver
@item RawDriveDriver
String specifying the name of the device to be used for raw block access.

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

@vindex DriveSoundEmulation
@item DriveSoundEmulation
Boolean controlling whether the drive noise emulation is turned on
(all emulators except vsid).

@vindex DriveSoundEmulationVolume
@item DriveSoundEmulationVolume
Integer specifying the volume of the drive noise emulation
(all emulators except vsid).
(0..4000)

@vindex Drive8Type
@vindex Drive9Type
@vindex Drive10Type
@vindex Drive11Type
@item Drive8Type
@itemx Drive9Type
@itemx Drive10Type
@itemx Drive11Type
Integers specifying the model number for drives 8 to 11.  Possible
values are @code{1541} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{1542} (1541-II) [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{1570} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{1571} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{1573} (1571CR) [x128 only],
@code{1551} [xplus4 only],
@code{1581} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{1001} [all emulators except x64dtv, xplus4 and vsid],
@code{2000} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{2031} [all emulators except x64dtv, xplus4 and vsid],
@code{2040} [all emulators except x64dtv, xplus4 and vsid],
@code{3040} [all emulators except x64dtv, xplus4 and vsid],
@code{4000} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{4040} [all emulators except x64dtv, xplus4 and vsid],
@code{8050} [all emulators except x64dtv, xplus4 and vsid],
@code{8250} [all emulators except x64dtv, xplus4 and vsid].

@vindex Drive8RTCSave
@item Drive8RTCSave
Integer specifying whether the RTC data of drive 8 should be saved when changed or not (drive type 2000/4000 only).

@vindex Drive9RTCSave
@item Drive9RTCSave
Integer specifying whether the RTC data of drive 9 should be saved when changed or not (drive type 2000/4000 only).

@vindex Drive10RTCSave
@item Drive10RTCSave
Integer specifying whether the RTC data of drive 10 should be saved when changed or not (drive type 2000/4000 only).

@vindex Drive11RTCSave
@item Drive11RTCSave
Integer specifying whether the RTC data of drive 11 should be saved when changed or not (drive type 2000/4000 only).

@vindex Drive8ParallelCable
@vindex Drive9ParallelCable
@vindex Drive10ParallelCable
@vindex Drive11ParallelCable
@item Drive8ParallelCable
@itemx Drive9ParallelCable
@itemx Drive10ParallelCable
@itemx Drive11ParallelCable
integers controlling what type of parallel cable is emulated for drives 8 to 11
(x64, x64sc, xscpu64, x128 and xplus4 only).
x64/x64sc/xscpu64/x128: (0: None, 1: Standard, 2: Professional DOS, 3: Formel64)
xplus4: (0: None, 1: Standard)

@vindex Drive8ProfDOS
@vindex Drive9ProfDOS
@vindex Drive10ProfDOS
@vindex Drive11ProfDOS
@item Drive8ProfDOS
@itemx Drive9ProfDOS
@itemx Drive10ProfDOS
@itemx Drive11ProfDOS
Booleans controlling whether Professional DOS is emulated or not for drives 8 to 11
(x64, x64sc, xscpu64 and x128 only).

@vindex Drive8SuperCard
@vindex Drive9SuperCard
@vindex Drive10SuperCard
@vindex Drive11SuperCard
@item Drive8SuperCard
@itemx Drive9SuperCard
@itemx Drive10SuperCard
@itemx Drive11SuperCard
Booleans controlling whether Super Card is emulated or not for drives 8 to 11
(x64, x64sc, xscpu64 and x128 only).

@vindex Drive8RAM2000
@vindex Drive8RAM4000
@vindex Drive8RAM6000
@vindex Drive8RAM8000
@vindex Drive8RAMA000
@vindex Drive9RAM2000
@vindex Drive9RAM4000
@vindex Drive9RAM6000
@vindex Drive9RAM8000
@vindex Drive9RAMA000
@vindex Drive10RAM2000
@vindex Drive10RAM4000
@vindex Drive10RAM6000
@vindex Drive10RAM8000
@vindex Drive10RAMA000
@vindex Drive11RAM2000
@vindex Drive11RAM4000
@vindex Drive11RAM6000
@vindex Drive11RAM8000
@vindex Drive11RAMA000
@item Drive8RAM2000
@itemx Drive8RAM4000
@itemx Drive8RAM6000
@itemx Drive8RAM8000
@itemx Drive8RAMA000
@itemx Drive9RAM2000
@itemx Drive9RAM4000
@itemx Drive9RAM6000
@itemx Drive9RAM8000
@itemx Drive9RAMA000
@itemx Drive10RAM2000
@itemx Drive10RAM4000
@itemx Drive10RAM6000
@itemx Drive10RAM8000
@itemx Drive10RAMA000
@itemx Drive11RAM2000
@itemx Drive11RAM4000
@itemx Drive11RAM6000
@itemx Drive11RAM8000
@itemx Drive11RAMA000
Booleans controlling whether a RAM block is emulated at the respective block or
not for drives 8 to 11 respectively.

@vindex Drive8ExtendImagePolicy
@vindex Drive9ExtendImagePolicy
@vindex Drive10ExtendImagePolicy
@vindex Drive11ExtendImagePolicy
@item Drive8ExtendImagePolicy
@itemx Drive9ExtendImagePolicy
@itemx Drive10ExtendImagePolicy
@itemx Drive11ExtendImagePolicy
Integer specifying the policy for 40-track support for drives 8 to 11.
(0: never extend, 1: ask on extend, 2: extend on access)

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

@vindex DosName1540
@vindex DosName1541
@vindex DosName1541ii
@vindex DosName1570
@vindex DosName1571
@vindex DosName1581
@vindex DosName2000
@vindex DosName4000
@item DosName1540
@itemx DosName1541
@itemx DosName1541ii
@itemx DosName1570
@itemx DosName1571
@itemx DosName1581
@itemx DosName2000
@itemx DosName4000
Strings specifying the names of the ROM images for the drive emulation.
(all emulators except xcbm2, xcbm5x0, xpet and vsid)

@vindex DosName1551
@item DosName1551
String specifying the name of the ROM image for the drive emulation.
(xplus4 only)

@vindex DosName1571cr
@item DosName1571cr
String specifying the name of the ROM image for the drive emulation.
(x128 only)

@vindex DosName2031
@vindex DosName2040
@vindex DosName3040
@vindex DosName4040
@vindex DosName1001
@item DosName2031
@itemx DosName2040
@itemx DosName3040
@itemx DosName4040
@itemx DosName1001
Strings specifying the names of the ROM images for the drive emulation.
(all emulators except x64dtv, xplus4 and vsid)

@vindex DriveProfDOS1571Name
@item DriveProfDOS1571Name
String specifying the filename of the 1571 professional DOS ROM image
(x64, x64sc, xscpu64 and x128 only).

@vindex DriveSuperCardName
@item DriveSuperCardName
String specifying the filename of the Super Card ROM image
(x64, x64sc, xscpu64 and x128 only).

@end table

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

@table @code

@findex -truedrive, +truedrive
@item -truedrive
@itemx +truedrive
Enable/disable true drive emulation
(@code{DriveTrueEmulation=1}, @code{DriveTrueEmulation=0}).

@findex -drivesound, +drivesound
@item -drivesound
@itemx +drivesound
Enable/disable drive sound emulation
(@code{DriveSoundEmulation=1}, @code{DriveSoundEmulation=0})
(all emulators except vsid).

@findex -drivesoundvolume
@item -drivesoundvolume <Volume>
Set the volume of the drive sound emulation
(@code{DriveSoundEmulationVolume=1}, @code{DriveSoundEmulationVolume=0})
(all emulators except vsid).

@findex -drive8type
@findex -drive9type
@findex -drive10type
@findex -drive11type
@item -drive8type <Type>
@itemx -drive9type <Type>
@itemx -drive10type <Type>
@itemx -drive11type <Type>
Specifies the drive types for drives 8-11, respectively.
Possible values for @code{TYPE} are
@code{1541} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{1542} (meaning 1541-II) [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{1551} [xplus4 only],
@code{1570} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{1571} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{1573} (meaning 1571cr) [x128 only],
@code{1581} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{2000} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{4000} [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{2031} [all emulators except x64dtv, xplus4 and vsid],
@code{2040} [all emulators except x64dtv, xplus4 and vsid],
@code{3040} [all emulators except x64dtv, xplus4 and vsid],
@code{4040} [all emulators except x64dtv, xplus4 and vsid],
@code{1001} [all emulators except x64dtv, xplus4 and vsid],
@code{8050} [all emulators except x64dtv, xplus4 and vsid]
and @code{8250} [all emulators except x64dtv, xplus4 and vsid].

@findex -drive8rtcsave / +drive8rtcsave
@item -drive8rtcsave
@itemx -drive8rtcsave
Enable/disable the saving of the RTC data for drive 8 when changed (drive type 2000/4000 only)
(@code{Drive8RTCSave=1}, @code{Drive8RTCSave=0}).

@findex -drive9rtcsave / +drive9rtcsave
@item -drive9rtcsave
@itemx -drive9rtcsave
Enable/disable the saving of the RTC data for drive 9 when changed (drive type 2000/4000 only)
(@code{Drive9RTCSave=1}, @code{Drive9RTCSave=0}).

@findex -drive10rtcsave / +drive10rtcsave
@item -drive10rtcsave
@itemx -drive10rtcsave
Enable/disable the saving of the RTC data for drive 10 when changed (drive type 2000/4000 only)
(@code{Drive10RTCSave=1}, @code{Drive10RTCSave=0}).

@findex -drive11rtcsave / +drive11rtcsave
@item -drive11rtcsave
@itemx -drive11rtcsave
Enable/disable the saving of the RTC data for drive 11 when changed (drive type 2000/4000 only)
(@code{Drive11RTCSave=1}, @code{Drive11RTCSave=0}).

@findex -parallel8
@findex -parallel9
@findex -parallel10
@findex -parallel11
@item -parallel8 <type>
@itemx -parallel9 <type>
@itemx -parallel10 <type>
@itemx -parallel11 <type>
Set parallel cable type for drives 8-11 respectively
(@code{Drive8ParallelCable}, @code{Drive9ParallelCable},
@code{Drive10ParallelCable}, @code{Drive11ParallelCable})
(x64, x64sc, xscpu64, x128 and xplus4 only).
x64/x64sc/xscpu64/x128: (0: None, 1: Standard, 2: Professional DOS, 3: Formel64)
xplus4: (0: None, 1: Standard)

@findex -drive8idle
@findex -drive9idle
@findex -drive10idle
@findex -drive11idle
@item -drive8idle <method>
@itemx -drive9idle <method>
@itemx -drive10idle <method>
@itemx -drive11idle <method>
Specifies <method> as the idling method for drives 8-11 respectively
(@code{Drive8IdleMethod}, @code{Drive9IdleMethod},
@code{Drive10IdleMethod}), @code{Drive11IdleMethod}).
(0: none, 1: skip cycles, 2: trap idle)

@findex -drive8extend
@findex -drive9extend
@findex -drive10extend
@findex -drive11extend
@item -drive8extend <method>
@itemx -drive9extend <method>
@itemx -drive10extend <method>
@itemx -drive11extend <method>
Specifies <method> as the track 40 extend policy in drives 8-11 respectively
(@code{Drive8ExtendImagePolicy}, @code{Drive9ExtendImagePolicy},
@code{Drive10ExtendImagePolicy}, @code{Drive11ExtendImagePolicy}).
(0: never extend, 1: ask on extend, 2: extend on access)

@findex -dos1540
@item -dos1540 <name>
Specify the ROM name for the 1540 emulation
(@code{DosName1540}).
(all emulators except xcbm2, xcbm5x0, xpet and vsid)

@findex -dos1541
@item -dos1541 <name>
Specify the ROM name for the 1541 emulation
(@code{DosName1541}).
(all emulators except xcbm2, xcbm5x0, xpet and vsid)

@findex -dos1541II
@item -dos1541II <name>
Specify the ROM name for the 1541-II emulation
(@code{DosName1541ii}).
(all emulators except xcbm2, xcbm5x0, xpet and vsid)

@findex -dos1551
@item -dos1551 <name>
Specify the ROM name for the 1551 emulation
(@code{DosName1551}).
(xplus4 only)

@findex -dos1570
@item -dos1570 <name>
Specify the ROM name for the 1570 emulation
(@code{DosName1570}).
(all emulators except xcbm2, xcbm5x0, xpet and vsid)

@findex -dos1571
@item -dos1571 <name>
Specify the ROM name for the 1571 emulation
(@code{DosName1571}).
(all emulators except xcbm2, xcbm5x0, xpet and vsid)

@findex -dos1571cr
@item -dos1571cr <name>
Specify the ROM name for the 1571 emulation
(@code{DosName1571CR}).
(x128 only)

@findex -dos1581
@item -dos1581 <name>
Specify the ROM name for the 1581 emulation
(@code{DosName1581}).
(all emulators except xcbm2, xcbm5x0, xpet and vsid)

@findex -dos2000
@item -dos2000 <name>
Specify the ROM name for the FD2000 emulation
(@code{DosName2000}).
(all emulators except xcbm2, xcbm5x0, xpet and vsid)

@findex -dos4000
@item -dos4000 <name>
Specify the ROM name for the FD4000 emulation
(@code{DosName4000}).
(all emulators except xcbm2, xcbm5x0, xpet and vsid)

@findex -dos2031
@item -dos2031 <name>
Specify the ROM name for the 2031 emulation
(@code{DosName2031}).
(all emulators except x64dtv, xplus4 and vsid)

@findex -dos2040
@item -dos2040 <name>
Specify the ROM name for the 2040 emulation
(@code{DosName2040}).
(all emulators except x64dtv, xplus4 and vsid)

@findex -dos3040
@item -dos3040 <name>
Specify the ROM name for the 3040 emulation
(@code{DosName3040}).
(all emulators except x64dtv, xplus4 and vsid)

@findex -dos4040
@item -dos4040 <name>
Specify the ROM name for the 4040 emulation
(@code{DosName4040}).
(all emulators except x64dtv, xplus4 and vsid)

@findex -dos1001
@item -dos1001 <name>
Specify the ROM name for the 1001, 8050 and 8250 emulations
(@code{DosName1001}).
(all emulators except x64dtv, xplus4 and vsid)

@findex -drive8ram2000, +drive8ram2000
@item -drive8ram2000, +drive8ram2000
Enable/disable 8KB RAM expansion at $2000-$3FFF for drive 8
(@code{Drive8RAM2000=1}, @code{Drive8RAM2000=0}).

@findex -drive9ram2000, +drive9ram2000
@item -drive9ram2000, +drive9ram2000
Enable/disable 8KB RAM expansion at $2000-$3FFF for drive 9
(@code{Drive9RAM2000=1}, @code{Drive9RAM2000=0}).

@findex -drive10ram2000, +drive10ram2000
@item -drive10ram2000, +drive10ram2000
Enable/disable 8KB RAM expansion at $2000-$3FFF for drive 10
(@code{Drive10RAM2000=1}, @code{Drive10RAM2000=0}).

@findex -drive11ram2000, +drive11ram2000
@item -drive11ram2000, +drive11ram2000
Enable/disable 8KB RAM expansion at $2000-$3FFF for drive 11
(@code{Drive11RAM2000=1}, @code{Drive11RAM2000=0}).

@findex -drive8ram4000, +drive8ram4000
@item -drive8ram4000, +drive8ram4000
Enable/disable 8KB RAM expansion at $4000-$5FFF for drive 8
(@code{Drive8RAM4000=1}, @code{Drive8RAM4000=0}).

@findex -drive9ram4000, +drive9ram4000
@item -drive9ram4000, +drive9ram4000
Enable/disable 8KB RAM expansion at $4000-$5FFF for drive 9
(@code{Drive9RAM4000=1}, @code{Drive9RAM4000=0}).

@findex -drive10ram4000, +drive10ram4000
@item -drive10ram4000, +drive10ram4000
Enable/disable 8KB RAM expansion at $4000-$5FFF for drive 10
(@code{Drive10RAM4000=1}, @code{Drive10RAM4000=0}).

@findex -drive11ram4000, +drive11ram4000
@item -drive11ram4000, +drive11ram4000
Enable/disable 8KB RAM expansion at $4000-$5FFF for drive 11
(@code{Drive11RAM4000=1}, @code{Drive11RAM4000=0}).

@findex -drive8ram6000, +drive8ram6000
@item -drive8ram6000, +drive8ram6000
Enable/disable 8KB RAM expansion at $6000-$7FFF for drive 8
(@code{Drive8RAM6000=1}, @code{Drive8RAM6000=0}).

@findex -drive9ram6000, +drive9ram6000
@item -drive9ram6000, +drive9ram6000
Enable/disable 8KB RAM expansion at $6000-$7FFF for drive 9
(@code{Drive9RAM6000=1}, @code{Drive9RAM6000=0}).

@findex -drive10ram6000, +drive10ram6000
@item -drive10ram6000, +drive10ram6000
Enable/disable 8KB RAM expansion at $6000-$7FFF for drive 10
(@code{Drive10RAM6000=1}, @code{Drive10RAM6000=0}).

@findex -drive11ram6000, +drive11ram6000
@item -drive11ram6000, +drive11ram6000
Enable/disable 8KB RAM expansion at $6000-$7FFF for drive 11
(@code{Drive11RAM6000=1}, @code{Drive11RAM6000=0}).

@findex -drive8ram8000, +drive8ram8000
@item -drive8ram8000, +drive8ram8000
Enable/disable 8KB RAM expansion at $8000-$9FFF for drive 8
(@code{Drive8RAM8000=1}, @code{Drive8RAM8000=0}).

@findex -drive9ram8000, +drive9ram8000
@item -drive9ram8000, +drive9ram8000
Enable/disable 8KB RAM expansion at $8000-$9FFF for drive 9
(@code{Drive9RAM8000=1}, @code{Drive9RAM8000=0}).

@findex -drive10ram8000, +drive10ram8000
@item -drive10ram8000, +drive10ram8000
Enable/disable 8KB RAM expansion at $8000-$9FFF for drive 10
(@code{Drive10RAM8000=1}, @code{Drive10RAM8000=0}).

@findex -drive11ram8000, +drive11ram8000
@item -drive11ram8000, +drive11ram8000
Enable/disable 8KB RAM expansion at $8000-$9FFF for drive 11
(@code{Drive11RAM8000=1}, @code{Drive11RAM8000=0}).

@findex -drive8rama000, +drive8rama000
@item -drive8rama000, +drive8rama000
Enable/disable 8KB RAM expansion at $A000-$BFFF for drive 8
(@code{Drive8RAMA000=1}, @code{Drive8RAMA000=0}).

@findex -drive9rama000, +drive9rama000
@item -drive9rama000, +drive9rama000
Enable/disable 8KB RAM expansion at $A000-$BFFF for drive 9
(@code{Drive9RAMA000=1}, @code{Drive9RAMA000=0}).

@findex -drive10rama000, +drive10rama000
@item -drive10rama000, +drive10rama000
Enable/disable 8KB RAM expansion at $A000-$BFFF for drive 10
(@code{Drive10RAMA000=1}, @code{Drive10RAMA000=0}).

@findex -drive11rama000, +drive11rama000
@item -drive11rama000, +drive11rama000
Enable/disable 8KB RAM expansion at $A000-$BFFF for drive 11
(@code{Drive11RAMA000=1}, @code{Drive11RAMA000=0}).

@findex -drive8profdos, +drive8profdos
@item -drive8profdos
@itemx +drive8profdos
Enable/disable Professional DOS for drive 8
(@code{Drive8ProfDOS=1}, @code{Drive8ProfDOS=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -drive9profdos, +drive9profdos
@item -drive9profdos
@itemx +drive9profdos
Enable/disable Professional DOS for drive 9
(@code{Drive9ProfDOS=1}, @code{Drive9ProfDOS=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -drive10profdos, +drive10profdos
@item -drive10profdos
@itemx +drive10profdos
Enable/disable Professional DOS for drive 10
(@code{Drive10ProfDOS=1}, @code{Drive10ProfDOS=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -drive11profdos, +drive11profdos
@item -drive11profdos
@itemx +drive11profdos
Enable/disable Professional DOS for drive 11
(@code{Drive11ProfDOS=1}, @code{Drive11ProfDOS=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -profdos1571
@item -profdos1571 <name>
Specify name of Professional DOS 1571 ROM image
(@code{DriveProfDOS1571Name})
(x64, x64sc, xscpu64 and x128).

@findex -drive8supercard, +drive8supercard
@item -drive8supercard
@itemx +drive8supercard
Enable/disable Super Card for drive 8
(@code{Drive8SuperCard=1}, @code{Drive8SuperCard=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -drive9supercard, +drive9supercard
@item -drive9supercard
@itemx +drive9supercard
Enable/disable Super Card for drive 9
(@code{Drive9SuperCard=1}, @code{Drive9SuperCard=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -drive10supercard, +drive10supercard
@item -drive10supercard
@itemx +drive10supercard
Enable/disable Super Card for drive 10
(@code{Drive10SuperCard=1}, @code{Drive10SuperCard=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -drive11supercard, +drive11supercard
@item -drive11supercard
@itemx +drive11supercard
Enable/disable Super Card for drive 11
(@code{Drive11SuperCard=1}, @code{Drive11SuperCard=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -supercard
@item -supercard <name>
Specify name of Super Card ROM image
(@code{DriveSuperCardName})
(x64, x64sc, xscpu64 and x128 only).

@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 create P00 files on save.

@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 IECDevice8
@vindex IECDevice9
@vindex IECDevice10
@vindex IECDevice11
@item IECDevice8
@itemx IECDevice9
@itemx IECDevice10
@itemx IECDevice11
Booleans that specify whether IEC device emulation for device #8 to #11 is enabled.

@vindex FileSystemDevice8
@vindex FileSystemDevice9
@vindex FileSystemDevice10
@vindex FileSystemDevice11
@item FileSystemDevice8
@itemx FileSystemDevice9
@itemx FileSystemDevice10
@itemx FileSystemDevice11
Integers specifying the device type for device 8-11 respectively
(all emulators except vsid).
(0: None, 1: Filesystem, 2: OpenCBM (Real), 3: Block Device (Raw))

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

@vindex FSDevice8SaveP00
@vindex FSDevice9SaveP00
@vindex FSDevice10SaveP00
@vindex FSDevice11SaveP00
@item FSDevice8SaveP00
@itemx FSDevice9SaveP00
@itemx FSDevice10SaveP00
@itemx FSDevice11SaveP00
Booleans specifying whether the drives should create P00 files instead of plain CBM ones for drives 8, 9, 10 and 11 respectively
(all emulators except vsid).

@vindex FSDevice8HideCBMFiles
@vindex FSDevice9HideCBMFiles
@vindex FSDevice10HideCBMFiles
@vindex FSDevice11HideCBMFiles
@item FSDevice8HideCBMFiles
@itemx FSDevice9HideCBMFiles
@itemx FSDevice10HideCBMFiles
@itemx FSDevice11HideCBMFiles
Booleans specifying whether non-P00 files should be invisible for drives 8, 9, 10 and 11 respectively
(all emulators except vsid).

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

@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

@findex -iecdevice8, +iecdevice8
@item -iecdevice8
@itemx +iecdevice8
Enable/disable IEC device emulation for device #8
(@code{IECDevice8=1}, @code{IECDevice8=0}).

@findex -iecdevice9, +iecdevice9
@item -iecdevice9
@itemx +iecdevice9
Enable/disable IEC device emulation for device #9
(@code{IECDevice9=1}, @code{IECDevice9=0}).

@findex -iecdevice10, +iecdevice10
@item -iecdevice10
@itemx +iecdevice10
Enable/disable IEC device emulation for device #10
(@code{IECDevice10=1}, @code{IECDevice10=0}).

@findex -iecdevice11, +iecdevice11
@item -iecdevice11
@itemx +iecdevice11
Enable/disable IEC device emulation for device #11
(@code{IECDevice11=1}, @code{IECDevice11=0}).

@findex -device8
@findex -device9
@findex -device10
@findex -device11
@item -device8 <type>
@itemx -device9 <type>
@itemx -device10 <type>
@itemx -device11 <type>
Set device type for device 8-11 respectively
(@code{FileSystemDevice8}, @code{FileSystemDevice9}, @code{FileSystemDevice10}, @code{FileSystemDevice11})
(all emulators except vsid).
(0: None, 1: Filesystem, 2: OpenCBM (Real), 3: Block device (Raw))

@findex -fs8
@findex -fs9
@findex -fs10
@findex -fs11
@item -fs8 <Name>
@itemx -fs9 <Name>
@itemx -fs10 <Name>
@itemx -fs11 <Name>
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})
(all emulators except vsid).

@findex -fs8convertp00 / +fs8convertp00
@item -fs8convertp00
@itemx +fs8convertp00
Enable/disable on-read support for P00 files on drive 8
(@code{FSDevice8ConvertP00=1}, @code{FSDevice8ConvertP00=0})
(all emulators except vsid).

@findex -fs9convertp00 / +fs9convertp00
@item -fs9convertp00
@itemx +fs9convertp00
Enable/disable on-read support for P00 files on drive 9
(@code{FSDevice9ConvertP00=1}, @code{FSDevice9ConvertP00=0})
(all emulators except vsid).

@findex -fs10convertp00 / +fs10convertp00
@item -fs10convertp00
@itemx +fs10convertp00
Enable/disable on-read support for P00 files on drive 10
(@code{FSDevice10ConvertP00=1}, @code{FSDevice10ConvertP00=0})
(all emulators except vsid).

@findex -fs11convertp00 / +fs11convertp00
@item -fs11convertp00
@itemx +fs11convertp00
Enable/disable on-read support for P00 files on drive 11
(@code{FSDevice11ConvertP00=1}, @code{FSDevice11ConvertP00=0})
(all emulators except vsid).

@findex -fs8savep00 / +fs8savep00
@item -fs8savep00
@itemx +fs8savep00
Enable/disable saving P00 files on drive 8
(@code{FSDevice8SaveP00=1}, @code{FSDevice8SaveP00=0})
(all emulators except vsid).

@findex -fs9savep00 / +fs9savep00
@item -fs9savep00
@itemx +fs9savep00
Enable/disable saving P00 files on drive 9
(@code{FSDevice9SaveP00=1}, @code{FSDevice9SaveP00=0})
(all emulators except vsid).

@findex -fs10savep00 / +fs10savep00
@item -fs10savep00
@itemx +fs10savep00
Enable/disable saving P00 files on drive 10
(@code{FSDevice10SaveP00=1}, @code{FSDevice10SaveP00=0})
(all emulators except vsid).

@findex -fs11savep00 / +fs11savep00
@item -fs11savep00
@itemx +fs11savep00
Enable/disable saving P00 files on drive 11
(@code{FSDevice11SaveP00=1}, @code{FSDevice11SaveP00=0})
(all emulators except vsid).

@findex -fs8hidecbm / +fs8hidecbm
@item -fs8hidecbm
@itemx +fs8hidecbm
Enable/disable hiding of CBM files for drive 8
(@code{FSDevice8HideCBMFiles=1}, @code{FSDevice8HideCBMFiles=0})
(all emulators except vsid).

@findex -fs9hidecbm / +fs9hidecbm
@item -fs9hidecbm
@itemx +fs9hidecbm
Enable/disable hiding of CBM files for drive 9
(@code{FSDevice9HideCBMFiles=1}, @code{FSDevice9HideCBMFiles=0})
(all emulators except vsid).

@findex -fs10hidecbm / +fs10hidecbm
@item -fs10hidecbm
@itemx +fs10hidecbm
Enable/disable hiding of CBM files for drive 10
(@code{FSDevice10HideCBMFiles=1}, @code{FSDevice10HideCBMFiles=0})
(all emulators except vsid).

@findex -fs11hidecbm / +fs11hidecbm
@item -fs11hidecbm
@itemx +fs11hidecbm
Enable/disable hiding of CBM files for drive 11
(@code{FSDevice11HideCBMFiles=1}, @code{FSDevice11HideCBMFiles=0})
(all emulators except vsid).

@findex -flipname
@item -flipname <name>
Specify name of the flip list file image
(@code{FliplistName})
(all emulators except vsid).

@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 IECDevice4
@vindex IECDevice5
@vindex IECDevice6
@vindex IECDevice7
@item IECDevice4
@itemx IECDevice5
@itemx IECDevice6
@itemx IECDevice7
Booleans that specify whether IEC device emulation for device #4, #5, #6 and #7 is enabled.

@vindex PrinterTextDevice1
@vindex PrinterTextDevice2
@vindex PrinterTextDevice3
@item PrinterTextDevice1
@itemx PrinterTextDevice2
@itemx PrinterTextDevice3
Strings specifying the printer devices (@pxref{Printer settings}).

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

@vindex Printer4
@vindex Printer5
@vindex Printer6
@item Printer4
@itemx Printer5
@itemx Printer6
Integer specifying how the printer (device 4-6) is being emulated.
(0: None, 1: Filesystem, 2: Real)

@vindex Printer7
@item Printer7
Integer specifying how printer 7 is being emulated.
(0: None, 2: Real)

@vindex Printer4Driver
@item Printer4Driver
String specifying the printer output driver.
(raw, ascii, mps803, nl10)

@vindex Printer5Driver
@item Printer5Driver
String specifying the printer output driver.
(raw, ascii, mps803, nl10)

@vindex Printer6Driver
@item Printer6Driver
String specifying the printer output driver.
(raw, 1520)

@vindex Printer4Output
@vindex Printer5Output
@vindex Printer6Output
@item Printer4Output
@itemx Printer5Output
@itemx Printer6Output
Strings specifying the IEC printer output device.
(text, graphics)

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

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

@vindex PrinterUserportDriver
@item PrinterUserportDriver
String specifying the user-port printer output driver.
(ascii/nl10/raw)

@vindex PrinterUserportOutput
@item PrinterUserportOutput
String specifying the user-port printer output device.
(text, graphics)

@end table

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

@table @code

@findex -iecdevice4, +iecdevice4
@item -iecdevice4
@itemx +iecdevice4
Enable/disable IEC device emulation for device #4
(@code{IECDevice4=1}, @code{IECDevice4=0}).

@findex -iecdevice5, +iecdevice5
@item -iecdevice5
@itemx +iecdevice5
Enable/disable IEC device emulation for device #5
(@code{IECDevice5=1}, @code{IECDevice5=0}).

@findex -iecdevice6, +iecdevice6
@item -iecdevice6
@itemx +iecdevice6
Enable/disable IEC device emulation for device #6
(@code{IECDevice6=1}, @code{IECDevice6=0}).

@findex -iecdevice7, +iecdevice7
@item -iecdevice7
@itemx +iecdevice7
Enable/disable IEC device emulation for device #7
(@code{IECDevice7=1}, @code{IECDevice7=0}).

@findex -device4
@item -device4 <type>
Set device type for device 4
(@code{Printer4}).
(0: None, 1: Filesystem, 2: Real)

@findex -device5
@item -device5 <type>
Set device type for device 5
(@code{Printer5}).
(0: None, 1: Filesystem, 2: Real)

@findex -device6
@item -device6 <type>
Set device type for device 6
(@code{Printer6}).
(0: None, 1: Filesystem, 2: Real)

@findex -device7
@item -device7 <type>
Set device type for device 7
(@code{Printer7}).
(0: None, 2: Real)

@findex -prtxtdev1
@findex -prtxtdev2
@findex -prtxtdev3
@item -prtxtdev1 <name>
@itemx -prtxtdev2 <name>
@itemx -prtxtdev3 <name>
Specify name of printer text device or dump file
(@code{PrinterTextDevice1}, @code{PrinterTextDevice2}, @code{PrinterTextDevice3}).

@findex -pr4txtdev
@findex -pr5txtdev
@findex -pr6txtdev
@item -pr4txtdev <0-2>
@itemx -pr5txtdev <0-2>
@itemx -pr6txtdev <0-2>
Specify printer text output device for IEC printer #4-6
(@code{Printer4TextDevice}, @code{Printer5TextDevice}, @code{Printer6TextDevice}).

@findex -pr4output
@item -pr4output <name>
Specify name of output device for device #4
(@code{Printer4Output}).
(text, graphics)

@findex -pr5output
@item -pr5output <name>
Specify name of output device for device #5
(@code{Printer5Output}).
(text, graphics)

@findex -pr6output
@item -pr6output <name>
Specify name of output device for device #6
(@code{Printer6Output}).
(text, graphics)

@findex -pr4drv
@item -pr4drv <name>
Specify name of printer driver for device #4
(@code{Printer4Driver}).
(raw, ascii, mps803, nl10)

@findex -pr5drv
@item -pr5drv <name>
Specify name of printer driver for device #5
(@code{Printer5Driver}).
(raw, ascii, mps803, nl10)

@findex -pr6drv
@item -pr6drv <name>
Specify name of printer driver for device #6
(@code{Printer6Driver}).
(raw, 1520)

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

@findex -prusertxtdev
@item -prusertxtdev <0-2>
Specify printer text output device for userport printer
(@code{PrinterUserportTextDevice}).

@findex -pruseroutput
@item -pruseroutput <name>
Specify name of output device for the userport printer
(@code{PrinterUserportOutput}).
(text, graphics)

@findex -pruserdrv
@item -pruserdrv <name>
Specify name of printer driver for the userport printer
(@code{PrinterUserportDriver}).

@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

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

@end table

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

@node RS232 settings, Monitor 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
@vindex RsDevice2
@vindex RsDevice3
@vindex RsDevice4
@item RsDevice1
@itemx RsDevice2
@itemx RsDevice3
@itemx RsDevice4
Strings specifying the RS232 devices (@pxref{RS232 settings}).

@vindex Acia1Dev
@item Acia1Dev
Integer specifying what RS232 device (@pxref{RS232 settings}) the ACIA is using
(all emulators except x64dtv and vsid, and only if RS232 support is enabled and supported at compile time).

@vindex Acia1Irq
@item Acia1Irq
Integer specifying which interrupt to use. 0 = none, 1 = IRQ, 2 = NMI
(C64, VIC20 and C128 only, and only if RS232 support is enabled and
supported at compile time)

@vindex RsUserEnable
@item RsUserEnable
Boolean specifying if the user-port RS232 interface is being emulated
(C64, C128 and VIC20).

@vindex RsUserBaud
@item RsUserBaud
Integer specifying the baudrate of the user-port RS232 interface
(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 <Name> as RS232 devices 1, 2, 3 and 4, respectively
(@code{RsDevice1}, @code{RsDevice2} @code{RsDevice3} and @code{RsDevice4}).

@findex -myaciadev
@item -myaciadev <0-3>
Specify RS232 device the ACIA should work on
(all emulators except x64dtv and vsid, and only if RS232 support is enabled and supported at compile time)

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

@cindex -rsuserbaud
@item -rsuserbaud <baud>
Set the baud rate of the RS232 userport emulation.

@cindex -rsuserdev
@item -rsuserdev <0-3>
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

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

This section lists command-line options specific to the built-in monitor.

@menu
* Monitor options::
@end menu

@node Monitor options,  ,  , Monitor settings

@c @node FIXME
@subsection Monitor resources

@table @code

@vindex KeepMonitorOpen
@item KeepMonitorOpen
Boolean, if true the monitor window may stay open when the emulation is running,
eg to look at trace-point output. (Not all ports/UIs support this, in that case
this setting has no effect.)

@vindex MonitorServer
@item MonitorServer
Boolean specifying whether the remote monitor server is enabled.
@vindex MonitorServerAddress
@item MonitorServerAddress
String specifying the address the remote monitor server listens to (ip4://127.0.0.1:6510)

@end table

@subsection Monitor command-line options

@table @code
@cindex -moncommands
@item -moncommands <Name>
Execute the commands from the file <Name> in the monitor after starting up. This
command line switch is mainly thought to load labels and to set breakpoints.
Not all other commands are useful to be executed in this way, some may even
lead to strange effects.

@cindex -initbreak
@item -initbreak <address>
Set an initial breakpoint for the monitor. Addresses with prefix "0x" are hexadecimal.

@findex -keepmonopen, +keepmonopen
@item -keepmonopen
@itemx +keepmonopen
Enable/disable keeping the monitor window open
(@code{KeepMonitorOpen=1}, @code{KeepMonitorOpen=0}).

@cindex -remotemonitor, +remotemonitor
@item -remotemonitor
@itemx +remotemonitor
Enable/Disable remote monitor

@cindex -remotemonitoraddress
@item -remotemonitoraddress <name>
The local address the remote monitor should bind to

@end table

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

@c @node FIXME
@section Memory settings

@c @node FIXME
@subsection Memory resources

@table @code

@vindex RAMInitStartValue
@item RAMInitStartValue
Integer specifying the value for the very first RAM address after powerup
(all emulators except vsid).
(0..255)

@vindex RAMInitValueInvert
@item RAMInitValueInvert
Integer specifying the length of the memory block initialized with the same value
(all emulators except vsid).

@vindex RAMInitPatternInvert
@item RAMInitPatternInvert
Integer specifying the length of the memory block initialized with the same pattern
(all emulators except vsid).

@end table

@c @node FIXME
@subsection Memory command-line options

@table @code

@findex -raminitstartvalue
@item -raminitstartvalue <value>
Set the value for the very first RAM address after powerup
(@code{RAMInitStartValue})
(all emulators except vsid).
(0..255)

@cindex -raminitvalueinvert
@item -raminitvalueinvert <num of bytes>
Length of memory block initialized with the same value
(@code{RAMInitValueInvert})
(all emulators except vsid).

@findex -raminitpatterninvert
@item -raminitpatterninvert <num of bytes>
Length of memory block initialized with the same pattern
(@code{RAMInitPatternInvert})
(all emulators except vsid).

@end table

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

@node Misc settings,  , Monitor 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 JAMAction
@item JAMAction
Integer specifying the action to take when the CPU encounters a 'JAM' opcode.
(0: show dialog, 1: continue emulation, 2: start monitor, 3: soft reset, 4: hard reset, 5: quit emulator)

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

@c FIXME: add the following section to archdep stuff:
@ifset dummy
, 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.

@end ifset
@vindex DoCoreDump
@item DoCoreDump
Boolean specifying whether the emulator should dump core when it gets a signal
(all emulators except vsid).

@vindex NetworkServerName
@item NetworkServerName
String specifying the name of the remote server.
@vindex NetworkServerBindAddress
@item NetworkServerBindAddress
String specifying the IP of the remote server.
@vindex NetworkServerPort
@item NetworkServerPort
Integer specifying the port used for network play.
@c FIXME: is this correct?
@vindex NetworkControl
@item NetworkControl
Integer specifying whether the emulator is running as server or client (0: client,
1: server)

@vindex LogFileName
@item LogFileName
String specifying the filename of the current log file.

@vindex FliplistName
@item FliplistName
String specifying the filename of the current flip list. (Drive 8 only)
(all emulators except vsid).

@vindex AttachDevice8Readonly
@vindex AttachDevice9Readonly
@vindex AttachDevice10Readonly
@vindex AttachDevice11Readonly
@item AttachDevice8Readonly
@itemx AttachDevice9Readonly
@itemx AttachDevice10Readonly
@itemx AttachDevice11Readonly
Booleans that specify whether to attach images on drives 8 to 11 read-only or not
(all emulators except vsid).

@vindex UserportRTC
@item UserportRTC
Boolean specifying whether the userport RTC is emulated or not
(x64, x64sc, xscpu64 and x128 only).

@vindex UserportRTCSave
@item UserportRTCSave
Boolean specifying whether the userport RTC data is saved when changed or not
(x64, x64sc, xscpu64 and x128 only).

@end table

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

@table @code
@findex -jamaction
@item -jamaction <Type>
Specify the action to take when the CPU encounters a 'JAM' opcode
(@code{JAMAction})
(0: Show dialog, 1: continue emulation, 2: start monitor, 3: soft reset, 4: hard reset, 5: quit emulator).

@findex -directory
@item -directory <Path>
Specify the system file search path
(@code{Directory}).

@findex -core, +core
@item -core
@itemx +core
Enable/disable generation of core dumps
(@code{DoCoreDump=1}, @code{DoCoreDump=0})
(all emulators except vsid).

@findex -debug, +debug
@item -debug
@itemx +debug
Disable/enable calling of the exception handler
(@code{DoCoreDump=1}, @code{DoCoreDump=0})
(all emulators except vsid).

@findex -userportrtc, +userportrtc
@item -userportrtc
@itemx +userportrtc
Enable/disable the userport RTC emulation
(@code{UserportRTC=1}, @code{UserportRTC=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -userportrtcsave, +userportrtcsave
@item -userportrtcsave
@itemx +userportrtcsave
Disable/enable saving of the userport RTC data when changed
(@code{UserportRTCSave=1}, @code{UserportRTCSave=0})
(x64, x64sc, xscpu64 and x128 only).

@end table


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

@menu
* C64/128-specific::            Commands and settings specific to the
                                C64/128 emulators
* C128-specific::               Commands and settings specific to the
                                C128 emulator
* C64DTV-specific::             Commands and settings specific to the
                                C64DTV emulator
* SCPU64-specific::             Commands and settings specific to the
                                SCPU64 emulator
* VIC20-specific::              Commands and settings specific to the
                                VIC20 emulator
* PLUS4-specific::              Commands and settings specific to the
                                PLUS4 emulator
* PET-specific::                Commands and settings specific to the
                                PET emulator
* CBM-II-specific::             Commands and settings specific to the
                                CBM-II emulator
* VSID-specific::               Commands and settings specific to the
                                VSID music player
@end menu

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

@node C64/128-specific, C128-specific, Machine-specific features, Machine-specific features
@section C64/128-specific commands and settings

@c FIXME: clean up "c64/128" vs "c64"

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 cartridges 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 system ROM settings::     Settings to control the C64 system ROMs.
@end menu

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

@subsection Using cartridges

The cartridge system is organized in "Slots" to allow more than one cartridge
connected at a time, like it can be done using an expansion port expander on
a real C64 (see below).

Generally a cartridge can be enabled by attaching its respective cartridge
image, or using the respective menu option for cartridges that do not
require an image.

x64, x64sc and x128 allow you to attach the following kinds of images:

@itemize @bullet
@item
@file{.crt} images, as used by the CCS64 emulator by Per Hĺkan Sundell
@item
raw @file{.bin} images, with or without load address
@end itemize

@dfn{Cartridge images} are like disk images, but contain the contents of
cartridge ROM and/or RAM images instead of disk images.

To attach cartridges, use the ``Attach a cartridge image'' submenu. When using
@file{.crt} images, this will work for every cartridge which is supported. For
raw @file{.bin} images you might have to use command line options.

When you have successfully attached a cartridge image,
you should then reset the machine to make sure the cartridge initializes
itself. (Or enable the "reset on cartridge change" option).

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.

The imaginary expansion port expander is organized in 4 slots, the
cartridges are associated with them like this:

@c @node FIXME
@subsubsection Slot 0

All carts that have a passthrough connector go here. Once a "Slot 0"
cartridge is enabled all further cartridges are connected to its respective
passthrough port.

Only one cartridge of this type can be active at a time.

"Slot 0" carts have individual "enable" switches, enabling means enabling permanently.

The following cartridges are emulated in this slot:

@itemize @bullet
@item
IEEE-488 Interface (@code{http://www.funet.fi/pub/cbm/schematics/cartridges/c64/ieee-488/eprom.bin})
@item
Magic Voice
@item
MMC64
@end itemize

@c @node FIXME
@subsubsection Slot 1

Mostly RAM based cartridges which for one reason or the other might make sense
to be enabled together with one of the "Main Slot" cartridges go here.

Only one cartridge of this type can be active at a time.

"Slot 1" carts have individual "enable" switches, enabling means enabling permanently

The following cartridges are emulated in this slot:

@itemize @bullet
@item
Double Quick Brown Box (DQBB)
@item
Expert Cartridge
@item
ISEPIC
@item
RamCart
@end itemize

@c @node FIXME
@subsubsection Main Slot

All other cartridges which are not pure i/o extensions go here.

Only one cartridge of this type can be active at a time.

Cartridges in the "Main Slot" must be explicitly set as default to enable them permanently.

The following cartridges are emulated in this slot:

@itemize @bullet
@item
generic 4K, 8K and 16K game- and ultimax cartridges
@item
Action Replay V5
@item
Action Replay MK2
@item
Action Replay MK3
@item
Action Replay MK4
@item
Atomic Power
@item
C64 Games System
@item
Capture
@item
Comal 80
@item
Dela EP64
@item
Dela EP7x8
@item
Dela EP256
@item
Diashow-Maker
@item
Dinamic
@item
EasyFlash
@item
Epyx FastLoad
@item
EXOS
@item
The Final Cartridge
@item
The Final Cartridge III
@item
Final Cartridge Plus
@item
Freeze Frame
@item
Freeze Machine
@item
Fun Play
@item
Game Killer
@item
IDE64 (@code{http://www.ide64.org/})
@item
KCS Power Cartridge
@item
MACH 5
@item
Magic Desk
@item
Magic Formel
@item
Mikro Assembler
@item
MMC Replay
@item
Ocean
@item
Prophet64
@item
REX 256k EPROM Cart
@item
REX Utility
@item
Retro Replay
@item
RGCD
@item
ROSS
@item
Simons' BASIC
@item
Snapshot 64
@item
Stardos
@item
Structured BASIC
@item
Super Explode V5.0
@item
Super Games
@item
Super Snapshot V4
@item
Super Snapshot V5
@item
Warp Speed
@item
Westermann Learning
@item
Zaxxon
@end itemize

@c @node FIXME
@subsubsection I/O Slot

All carts that are pure I/O extensions go here.

Any number of "I/O Slot" Carts may be active at a time.

"I/O Slot" carts have individual "enable" switches, enabling means enabling permanently.

The following cartridges are emulated in this slot:

@itemize @bullet
@item
ACIA (Swiftlink, Turbo232)
@item
DigiMAX
@item
DS12C887 RTC
@item
Ethernet (The Final Ethernet, RR-Net)
@item
GEO-RAM
@item
MIDI (Passport/Syntech, Datel/Siel/JMS/C-Lab, Maplin, Namesoft, Sequential)
@item
RAM Expansion Module (REU)
@item
SFX Sound Expander
@item
SFX Sound Sampler
@end itemize

@c @node FIXME
@subsubsection Expected behaviour

When the emulator is run without arguments, all settings from the config file
should be applied and arguments override settings from the config file.

When saving the settings to the config file it is expected that on the next run
of the emulator all settings will be in the same state as they were when saved.

There is an exception to this rule: the cartridge in the "Main Slot" must be
explicitly set as default before it gets saved to the config file.

@code{+cart} should disable ALL cartridges, including eventually activated REU,
Swithlink and all similar expansionport devices.

@code{-cartXYZ} options should generally attach AND activate a cart of type XYZ.
As a consequence, attaching carts this way which are NOT in the "Main Slot" will
also enable the cart permanently.

@c @node FIXME
@subsubsection Common problems

If attaching a cartridge does not work as expected, this may be because of various
reasons:

@itemize @bullet

@item Not seldomly the CRT type is incorrectly set in @code{.crt} files found "in the wild".
Make sure this is not the case (if in doubt use @code{cartconv} to verify and/or fix).

@item You may have unintentionally enabled more than one cartridge at once, for
example by saving the settings with REU enabled, and then later attaching a game
cartridge from the command-line. The cartridge system will allow certain combinations,
but (as on the real thing) not all do (can) actually work. To make sure this is
not the case, either detach all cartridges from the menus, or use @code{+cart}
on the command-line.

@item The cartridge image might be broken. Try one from a different source. If you
are sure the dump is ok (for example because you dumped it yourself) then make sure
it is in proper linear order (on some cartridges, for example "capture", address and/or
data lines at the eprom are shuffled around so a dump made with an eprom burner can not
be used as is).

@item Last not least you might have encountered a bug in the emulation. If you
suspect this is the case, and you can still reproduce the bug after checking the
things above, please file a bug report including the following information:

@itemize @bullet
@item attach your vicerc and a reference to the cartridge binaries
@item if you can, comment in the respective DEBUGXYZ macros prominently defined at the
top of these files: src/c64/cart/c64cart.c src/c64/cart/c64cartmem.c src/c64/c64io.c
src/c64/c64export.c and then recompile. this will add debug output that might make
it much easier to locate certain problems.
@end itemize

@end itemize

@c @node FIXME
@subsubsection IEEE-488 interface

To be able to use an IEEE drive, you need to enable IEEE emulation for the
emulator. To do this, follow the following steps:

Download the IEEE 488 ROM image from the CBM archives (formerly known as FUNET)
Attach that image with File/Attach cartridge image/IEEE488 interface image.

Make sure you have a one-drive system only (that is, go to Settings/Peripheral
Setting, uncheck "use IEC device" for all devices, go to Settings/Drive Settings
and select "Floppy type" as "none" for all drives other than drive 8.

After this, all drives can be selected in x64 and x128.

@c @node FIXME
@subsubsection The Final Cartridge 3
The Final Cartridge 3 detects whether a mouse is connected when it starts and
disables mouse support if it doesnt detect one. So to make mouse emulation
work you must either enable it on the command line, or reset the cartridge
after enabling it from the user interface.

@c @node FIXME
@subsection C64 cartridge settings

@c @node FIXME
@subsubsection C64 cartridge resources

@table @code

@vindex IOCollisionHandling
@item IOCollisionHandling
Integer specifying the way the I/O collisions should be handled.
(0: error message and detach all involved carts, 1: error message and detach last attached involved 
carts, 2: warning in log and 'AND' the valid return values)

@vindex CartridgeReset
@item CartridgeReset
Boolean specifying whether the machine should be reset when a cartridge is changed.

@vindex CartridgeType
@item CartridgeType
Integer specifying the type of cartridge emulated in the "main" slot.

The following cartridge types are valid:

@itemize @bullet
@item
-6: Ultimax
@item
-3: Generic 8k
@item
-2: Generic 16k
@item
-1: None
@item
 0: CRT
@item
 1: Action Replay V5
@item
 2: KCS Power Cartridge
@item
 3: The Final Cartridge III
@item
 4: Simons' BASIC
@item
 5: Ocean
@item
 6: Expert Cartridge
@item
 7: Fun Play
@item
 8: Super Games
@item
 9: Atomic Power / Nordic Power
@item
10: Epyx FastLoad
@item
11: Westermann Learning
@item
12: REX Utility
@item
13: The Final Cartridge
@item
14: Magic Formel
@item
15: C64 Games System
@item
16: Warp Speed
@item
17: Dinamic
@item
18: Zaxxon
@item
19: Magic Desk
@item
20: Super Snapshot V5
@item
21: Comal 80
@item
22: Structured BASIC
@item
23: ROSS
@item
24: Dela EP64
@item
25: Dela EP7x8
@item
26: Dela EP256
@item
27: REX 256k EPROM Cart
@item
28: Mikro Assembler
@item
29: Final Cartridge Plus
@item
30: Action Replay MK4
@item
31: Stardos
@item
32: EasyFlash
@item
33: EasyFlash Xbank
@item
34: Capture
@item
35: Action Replay MK3
@item
36: Retro Replay
@item
37: MMC64
@item
38: MMC Replay
@item
39: IDE64
@item
40: Super Snapshot V4
@item
41: IEEE-488 Interface
@item
42: Game Killer
@item
43: Prophet64
@item
44: EXOS
@item
45: Freeze Frame
@item
46: Freeze Machine
@item
47: Snapshot 64
@item
48: Super Explode V5.0
@item
49: Magic Voice
@item
50: Action Replay MK2
@item
51: MACH 5
@item
52: Diashow-Maker
@item
53: Pagefox
@item
54: Kingsoft
@item
55: Silverrock 128K Cartridge
@item
56: Formel 64
@item
57: RGCD
@end itemize

@vindex CartridgeFile
@item CartridgeFile
String specifying the filename of the image for the cartridge emulated in the "main" slot.

@vindex DQBB
@item DQBB
Boolean specifying whether the Double Quick Brown Box should be emulated or not.

@vindex DQBBfilename
@item DQBBfilename
String specifying the filename of the DQBB RAM image.

@vindex DQBBImageWrite
@item DQBBImageWrite
Boolean, if true write back the DQBB image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.

@vindex EasyFlashJumper
@item EasyFlashJumper
Boolean specifying whether the Easy Flash jumper is set.

@vindex EasyFlashWriteCRT
@item EasyFlashWriteCRT
Boolean, if true write back the Easy Flash image file automatically, incase the
contents changed, when detaching or quitting the emulator.

@vindex EasyFlashOptimizeCRT
@item EasyFlashOptimizeCRT
Boolean, if true omit empty (filled with $ff) banks from the .crt image when writing.

@vindex ExpertCartridgeEnabled
@item ExpertCartridgeEnabled
Boolean specifying whether the Expert Cartridge should be emulated or not.

@vindex Expertfilename
@item Expertfilename
String specifying the filename of the Expert Cartridge RAM image.

@vindex ExpertImageWrite
@item ExpertImageWrite
Boolean, if true write back the Expert Cartridge image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.

@vindex ExpertCartridgeMode
@item ExpertCartridgeMode
Integer specifying the state of the expert cartridge switch.
(0: off, 1: prg, 2: on)

@vindex IDE64version4
@item IDE64version4
Boolean specifying whether the emulated card version is V4.1 or V3.4. This is automatically
detected most of the time for .crt cartridge images.

@vindex IDE64Image1
@vindex IDE64Image2
@vindex IDE64Image3
@vindex IDE64Image4
@item IDE64Image1
@itemx IDE64Image2
@itemx IDE64Image3
@itemx IDE64Image4
Strings specifying the full path to the four harddisk images. If a file is non-existing the drive is not emulated.
Some older IDEDOS versions only support the first two harddisks.

@vindex IDE64Cylinders1
@vindex IDE64Cylinders2
@vindex IDE64Cylinders3
@vindex IDE64Cylinders4
@item IDE64Cylinders1
@itemx IDE64Cylinders2
@itemx IDE64Cylinders3
@itemx IDE64Cylinders4
Integers specifying the number of cylinders for the four harddisk images.
(1..65535)

@vindex IDE64Heads1
@vindex IDE64Heads2
@vindex IDE64Heads3
@vindex IDE64Heads4
@item IDE64Heads1
@itemx IDE64Heads2
@itemx IDE64Heads3
@itemx IDE64Heads4
Integers specifying the number of heads for the four harddisk images.
(1..16)

@vindex IDE64Sectors1
@vindex IDE64Sectors2
@vindex IDE64Sectors3
@vindex IDE64Sectors4
@item IDE64Sectors1
@itemx IDE64Sectors2
@itemx IDE64Sectors3
@itemx IDE64Sectors4
Integers specifying the number of sectors for the four harddisk images.
(1..63)

@vindex IDE64AutodetectSize1
@vindex IDE64AutodetectSize2
@vindex IDE64AutodetectSize3
@vindex IDE64AutodetectSize4
@item IDE64AutodetectSize1
@itemx IDE64AutodetectSize2
@itemx IDE64AutodetectSize3
@itemx IDE64AutodetectSize4
Booleans specifying whether the disk geometry should be auto detected based
on the disk image for the respective harddisk, or the cylinder/head/sector resources above should be used.

@vindex IDE64USBServerAddress
@item IDE64USBServerAddress
String specifying the address the IDE64 USB server listens to (ip4://127.0.0.1:64245)
@vindex IDE64USBServer
@item IDE64USBServer
Boolean specifying whether the IDE64 USB server is enabled.

@vindex IDE64RTCSave
@item IDE64RTCSave
Boolean specifying whether the IDE64 RTC data should be saved when changed or not.

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

@vindex IEEE488Image
@item IEEE488Image
String specifying the filename of the IEEE488 ROM image.

@vindex IsepicCartridgeEnabled
@item IsepicCartridgeEnabled
Boolean specifying whether ISEPIC should be emulated or not.

@vindex Isepicfilename
@item Isepicfilename
String specifying the filename of the ISEPIC RAM image.

@vindex IsepicSwitch
@item IsepicSwitch
Boolean specifying the status of the ISEPIC switch.
(0: off, 1: on)

@vindex IsepicImageWrite
@item IsepicImageWrite
Boolean, if true write back the ISEPIC image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.

@vindex MagicVoiceCartridgeEnabled
@item MagicVoiceCartridgeEnabled
Boolean specifying whether the Magic Voice should be emulated or not.

@vindex MagicVoiceImage
@item MagicVoiceImage
String specifying the filename of the Magic Voice ROM image.

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

@vindex MMC64BIOSfilename
@item MMC64BIOSfilename
String specifying the filename of the MMC64 Flash ROM image.

@vindex MMC64_bios_write
@item MMC64_bios_write
Boolean, if true write back the MMC64 Flash ROM image file automatically, incase the
contents changed, when detaching or quitting the emulator.

@vindex MMC64_flashjumper
@item MMC64_flashjumper
Boolean that specifies whether the MMC64 flash jumper is set.

@vindex MMC64_revision
@item MMC64_revision
Integer specifying the MMC64 hardware revision.
(0: Revision A, 1: Revision B)

@vindex MMC64imagefilename
@item MMC64imagefilename
String specifying the filename of the SD-Card image used by the MMC64 emulation.

@vindex MMC64_RO
@item MMC64_RO
Boolean, if true the SD-Card image is mounted read-only.

@vindex MMC64_sd_type
@item MMC64_sd_type
Integer that specifies the reported type for the emulated SD-Card.
(0: Auto, 1: MMC, 2: SD, 3: SDHC)

@vindex MMCRCardImage
@item MMCRCardImage
String specifying the filename of the SD-Card image used by the MMCR emulation.

@vindex MMCREEPROMImage
@item MMCREEPROMImage
String specifying the filename of the MMCR EEPROM image.

@vindex MMCRRescueMode
@item MMCRRescueMode
Boolean specifying if the rescue mode (both buttons pressed during powerup)
of the MMCR is active.

@vindex MMCRImageWrite
@item MMCRImageWrite
Boolean, if true write back the MMCR Flash ROM image file automatically, incase the
contents changed, when detaching or quitting the emulator.

@vindex MMCRCardRW
@item MMCRCardRW
Boolean specifying if the SD-Card image used by the MMCR emulation is writeable.

@vindex MMCRSDType
@item MMCRSDType
Integer that specifies the reported type for the emulated SD-Card.
(0: Auto, 1: MMC, 2: SD, 3: SDHC)

@vindex MMCREEPROMRW
@item MMCREEPROMRW
Boolean specifying if the MMCR EEPROM image is writeable.

@vindex RAMCART
@item RAMCART
Boolean specifying whether the RAMCart should be emulated or not.

@vindex RAMCARTfilename
@item RAMCARTfilename
String specifying the filename of the RAMCart RAM image.

@vindex RAMCARTImageWrite
@item RAMCARTImageWrite
Boolean, if true write back the RAMCart image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.

@vindex RAMCART_RO
@item RAMCART_RO
Boolean, if true the RAMCart contents are read only.

@vindex RAMCARTsize
@item RAMCARTsize
Integer specifying the size of the RAMCart in KB.
(64, 128)

@vindex RRrevision
@item RRrevision
Integer specifying the RR hardware revision.
(0: Retro Replay, 1: Nordic Replay)

@vindex RRFlashJumper
@item RRFlashJumper
Boolean specifying whether the RR flash jumper is set or not.

@vindex RRBankJumper
@item RRBankJumper
Boolean specifying whether the RR bank jumper is set or not.

@vindex RRBiosWrite
@item RRBiosWrite
Boolean, if true write back the RR Flash ROM image file automatically, incase the
contents changed, when detaching or quitting the emulator.
@end table

@c @node FIXME
@subsubsection C64 cartridge command-line options

@table @code

@findex -iocollision
@item -iocollision <method>
Select the way the I/O collisions should be handled
(@code{IOCollisionHandling}).
(0: error message and detach all involved carts, 1: error message and detach last attached involved 
carts, 2: warning in log and 'AND' the valid return values

@findex +cart
@item +cart
Disable all cartridges (which would eventually be enabled in the config file).

@findex -cartreset, +cartreset
@item -cartreset
@itemx +cartreset
Reset/Do not reset machine if a cartridge is attached or detached
(@code{CartridgeReset=1}, @code{CartridgeReset=0}).

@findex -cart8
@item -cart8 <name>
Attach generic 8KB cartridge image.

@findex -cart16
@item -cart16 <name>
Attach generic 16KB cartridge image.

@findex -cartultimax
@item -cartultimax <name>
Attach generic 16kB Ultimax cartridge image.

@findex -cartcrt
@item -cartcrt <name>
Attach CRT cartridge image.

@findex -cartap
@item -cartap <name>
Attach raw 32KB Atomic Power cartridge image.

@findex -cartar2
@item -cartar2 <name>
Attach raw 16kB Action Replay MK2 cartridge image.

@findex -cartar3
@item -cartar3 <name>
Attach raw 16KB Action Replay MK3 cartridge image.

@findex -cartar4
@item -cartar4 <name>
Attach raw 32KB Action Replay MK4 cartridge image.

@findex -cartar5
@item -cartar5 <name>
Attach raw 32KB Action Replay cartridge image.

@findex -cartcap
@item -cartcap <name>
Attach raw 8kB Capture cartridge image.

@findex -cartcomal
@item -cartcomal <name>
Attach raw 64kB Comal 80 cartridge image.

@findex -cartdep256
@item -cartdep256 <name>
Attach raw Dela EP256 cartridge image.

@findex -cartdep64
@item -cartdep64 <name>
Attach raw Dela EP64 cartridge image.

@findex -cartdep7x8
@item -cartdep7x8 <name>
Attach raw Dela EP7x8 cartridge image.

@findex -cartdin
@item -cartdin <name>
Attach raw 128kB Dinamic cartridge image.

@findex -cartdsm
@item -cartdsm <name>
Attach raw 8kB Diashow-Maker cartridge image.

@findex -cartdqbb
@item -cartdqbb <name>
Attach raw 16kB Double Quick Brown Box cartridge image.

@findex -dqbb, +dqbb
@item -dqbb
@itemx +dqbb
Enable/disable Double Quick Brown Box
(@code{DQBB=1}, @code{DQBB=0}).

@findex -dqbbimage
@item -dqbbimage <name>
Specify Double Quick Brown Box filename
(@code{DQBBfilename}).

@findex -dqbbimagerw, +dqbbimagerw
@item -dqbbimagerw
@itemx +dqbbimagerw
Allow/disallow writing to DQBB image
(@code{DQBBImageWrite=1}, @code{DQBBImageWrite=0}).

@findex -carteasy
@item -carteasy <name>
Attach raw EasyFlash cartridge image.

@findex -easyflashjumper, +easyflashjumper
@item -easyflashjumper
@itemx +easyflashjumper
Enable/disable EasyFlash jumper
(@code{EasyFlashJumper=1}, @code{EasyFlashJumper=0}).

@findex -easyflashcrtwrite, +easyflashcrtwrite
@item -easyflashcrtwrite
@itemx +easyflashcrtwrite
Allow/Disallow writing to EasyFlash .crt image
(@code{EasyFlashWriteCRT=1}, @code{EasyFlashWriteCRT=0}).

@findex -easyflashcrtoptimize, +easyflashcrtoptimize
@item -easyflashcrtoptimize
@itemx +easyflashcrtoptimize
Allow/Disallow EasyFlash .crt image optimizing (omitting of empty banks) on write
(@code{EasyFlashOptimizeCRT=1}, @code{EasyFlashOptimizeCRT=0}).

@findex -cartepyx
@item -cartepyx <name>
Attach raw 8KB Epyx FastLoad cartridge image.

@findex -cartexos
@item -cartexos <name>
Attach raw 8kB EXOS cartridge image.

@findex -cartexpert
@item -cartexpert <name>
Attach raw 8kB Expert Cartridge image.

@findex -expert, +expert
@item -expert
@itemx +expert
Enable/Disable the Expert Cartridge
(@code{ExpertCartridgeEnabled=1}, @code{ExpertCartridgeEnabled=0}).

@findex -expertimagename
@item -expertimagename <name>
Set Expert Cartridge image name
(@code{Expertfilename}).

@findex -expertimagerw, +expertimagerw
@item -expertimagerw
@itemx +expertimagerw
Allow/Disallow writing to Expert Cartridge image
(@code{ExpertImageWrite=1}, @code{ExpertImageWrite=0}).

@findex -expertmode
@item -expertmode <mode>
Set Expert Cartridge mode
(@code{ExpertCartridgeMode}).
(0: off, 1: prg, 2: on)

@findex -cartf64
@item -cartf64 <Name>
Attach raw 32kB Formel 64 image.

@findex -cartfc1
@item -cartfc1 <name>
Attach raw 16kB Final Cartridge image.

@findex -cartfc3
@item -cartfc3 <name>
Attach raw 64kB Final Cartridge III image.

@findex -cartfcplus
@item -cartfcplus <name>
Attach raw 32kB Final Cartridge Plus image.

@findex -cartff
@item -cartff <name>
Attach raw 8kB Freeze Frame image.

@findex -cartfm
@item -cartfm <name>
Attach raw 32kB Freeze Machine image.

@findex -cartfp
@item -cartfp <name>
Attach raw 128kB Fun Play/Power Play cartridge image.

@findex -cartgk
@item -cartgk <name>
Attach raw 8KB Game Killer cartridge image.

@findex -cartgs
@item -cartgs <name>
Attach raw 512kB Game System cartridge image.

@findex -cartide64
@item -cartide64 <name>
Attach raw 64KB or 128KB IDE64 cartridge image.

@findex -IDE64image1
@item -IDE64image1 <name>
@findex -IDE64image2
@item -IDE64image2 <name>
@findex -IDE64image3
@item -IDE64image3 <name>
@findex -IDE64image4
@item -IDE64image4 <name>
Specify path to the image files for IDE64 harddisks
(@code{IDE64Image1}, @code{IDE64Image2}, @code{IDE64Image3}, @code{IDE64Image4}).

@findex -IDE64cyl1
@item -IDE64cyl1 <value>
@findex -IDE64cyl2
@item -IDE64cyl2 <value>
@findex -IDE64cyl3
@item -IDE64cyl3 <value>
@findex -IDE64cyl4
@item -IDE64cyl4 <value>
Set number of cylinders for the IDE64 harddisk emulation
(@code{IDE64Cylinders1}, @code{IDE64Cylinders2}, @code{IDE64Cylinders3}, @code{IDE64Cylinders1}).
(1..65535)

@findex -IDE64hds1
@item -IDE64hds1 <value>
@findex -IDE64hds2
@item -IDE64hds2 <value>
@findex -IDE64hds3
@item -IDE64hds3 <value>
@findex -IDE64hds4
@item -IDE64hds4 <value>
Set number of heads for the IDE64 harddisk emulation
(@code{IDE64Heads1}, @code{IDE64Heads2}, @code{IDE64Heads3}, @code{IDE64Heads4}).
(1..16)

@findex -IDE64sec1
@item -IDE64sec1 <value>
@findex -IDE64sec2
@item -IDE64sec2 <value>
@findex -IDE64sec3
@item -IDE64sec3 <value>
@findex -IDE64sec4
@item -IDE64sec4 <value>
Set number of sectors for the IDE64 harddisk emulation
(@code{IDE64Sectors1}, @code{IDE64Sectors2}, @code{IDE64Sectors3}, @code{IDE64Sectors4}).
(1..63)

@findex -IDE64autosize1, +IDE64autosize1
@item -IDE64autosize1
@itemx +IDE64autosize1
Autodetect geometry of formatted image or do not autodetect and use specified geometry
(@code{IDE64AutodetectSize1=1}, @code{IDE64AutodetectSize1=0}).

@findex -IDE64autosize2, +IDE64autosize2
@item -IDE64autosize2
@itemx +IDE64autosize2
Autodetect geometry of formatted image or do not autodetect and use specified geometry
(@code{IDE64AutodetectSize2=1}, @code{IDE64AutodetectSize2=0}).

@findex -IDE64autosize3, +IDE64autosize3
@item -IDE64autosize3
@itemx +IDE64autosize3
Autodetect geometry of formatted image or do not autodetect and use specified geometry
(@code{IDE64AutodetectSize3=1}, @code{IDE64AutodetectSize3=0}).

@findex -IDE64autosize4, +IDE64autosize4
@item -IDE64autosize4
@itemx +IDE64autosize4
Autodetect geometry of formatted image or do not autodetect and use specified geometry
(@code{IDE64AutodetectSize4=1}, @code{IDE64AutodetectSize4=0}).

@findex -IDE64version4, +IDE64version4
@item -IDE64version4
@itemx +IDE64version4
Emulate version 4 hardware/Emulate pre version 4 hardware
(@code{IDE64version4=1}, @code{IDE64version4=0}).

@cindex -IDE64USB, +IDE64USB
@item -IDE64USB
@itemx +IDE64USB
Enable/Disable IDE64 USB server
@cindex -IDE64USBAddress
@item -IDE64USBAddress <name>
The local address the IDE64 USB server should bind to

@findex -IDE64rtcsave, +IDE64rtcsave
@item -IDE64rtcsave
@itemx +IDE64rtcsave
Enable/disable saving of IDE64 RTC data when changed
(@code{IDE64RTCSave=1}, @code{IDE64RTCSave=0}).

@findex -cartieee
@item -cartieee <name>
Attach CBM IEEE-488 cartridge image.

@findex -ieee488, +ieee488
@item -ieee488
@itemx +ieee488
Enable/disable emulation of the IEEE488 interface
(@code{IEEE488=1}, @code{IEEE488=0}).
.
@findex -ieee488image
@item -ieee488image <name>
Set IEEE488 interface image name
(@code{IEEE488Image}).

@findex -isepic, +isepic
@item -isepic
@itemx +isepic
Enable/disable the ISEPIC cart
(@code{IsepicCartridgeEnabled=1}, @code{IsepicCartridgeEnabled=0}).

@findex -isepicswitch, +isepicswitch
@item -isepicswitch
@itemx +isepicswitch
Enable/disable the ISEPIC switch
(@code{IsepicSwitch=1}, @code{IsepicSwitch=0}).

@findex -cartisepic
@item -cartisepic <name>
Attach raw 2kB ISEPIC cartridge image.

@findex -isepicimagename
@item -isepicimagename <name>
Set ISEPIC image name
(@code{Isepicfilename}).

@findex -isepicimagerw, +isepicimagerw
@item -isepicimagerw
@itemx +isepicimagerw
Allow/disallow writing to ISEPIC image
(@code{IsepicImageWrite=1}, @code{IsepicImageWrite=0}).

@findex -cartkcs
@item -cartkcs <name>
Attach raw 16kB KCS Power cartridge image.

@findex -cartks
@item -cartks <name>
Attach raw 24kB Kingsoft cartridge image.

@findex -cartmach5
@item -cartmach5 <name>
Attach raw 8kB MACH 5 cartridge image.

@findex -cartmd
@item -cartmd <name>
Attach raw 32/64/128kB Magic Desk cartridge image.

@findex -cartmf
@item -cartmf <name>
Attach raw Magic Formel cartridge image.

@findex -cartmikro
@item -cartmikro <name>
Attach raw 8kB Mikro Assembler cartridge image.

@findex -mmc64, +mmc64
@item -mmc64
@itemx +mmc64
Enable/disable the MMC64 expansion
(@code{MMC64=1}, @code{MMC64=0}).

@findex -cartmmc64
@item -cartmmc64 <name>
Attach raw 8kB MMC64 cartridge image.

@findex -mmc64bios
@item -mmc64bios <name>
Specify name of MMC64 BIOS image
(@code{MMC64BIOSfilename}).

@findex -mmc64image
@item -mmc64image <name>
Specify name of MMC64 image
(@code{MMC64imagefilename}).

@findex -mmc64readonly
@item -mmc64readonly
Set the MMC64 card to read-only
(@code{MMC64_RO=1}).

@findex -mmc64readwrite
@item -mmc64readwrite
Set the MMC64 card to read/write
(@code{MMC64_RO=0}).

@findex -mmc64flash, +mmc64flash
@item -mmc64flash
@itemx +mmc64flash
Enable/Disable the MMC64 flash jumper
(@code{MMC64_flashjumper=1}, @code{MMC64_flashjumper=0}).

@findex -mmc64bioswrite
@item -mmc64bioswrite
Save the MMC64 bios when changed
(@code{MMC64_bios_write}=1).

@findex -mmc64biosreadonly
@item -mmc64biosreadonly
Do not save the MMC64 bios when changed
(@code{MMC64_bios_write}=0).

@findex -mmc64rev
@item -mmc64rev <revision>
Specify MMC64 revision
(@code{MMC64_revision}).
(0: Revision A, 1: Revision B)

@findex -mmc64sdtype
@item -mmc64sdtype <type>
Specify MMC64 SD type
(@code{MMC64_sd_type}).
(0: Auto, 1: MMC, 2: SD, 3: SDHC)

@findex -cartmmcr
@item -cartmmcr <name>
Attach raw 512kB MMC Replay cartridge image.

@findex -mmcrrescue, +mmcrrescue
@item -mmcrrescue
@itemx +mmcrrescue
Enable/disable MMC Replay rescue mode
(@code{MMCRRescueMode=1}, @code{MMCRRescueMode=0}).

@findex -mmcrimagerw, +mmcrimagerw
@item -mmcrimagerw
@itemx +mmcrimagerw
Allow/disallow writing to MMC Replay image
(@code{MMCRImageWrite=1}, @code{MMCRImageWrite=0}).

@findex -mmcrsdtype
@item -mmcrsdtype <type>
Specify MMC Replay SD type
(@code{MMCRSDType}).
(0: Auto, 1: MMC, 2: SD, 3: SDHC)

@findex -mmcrcardimage
@item -mmcrcardimage <filename>
Specify MMC Replay card image filename
(@code{MMCRCardImage}).

@findex -mmcrcardrw, +mmcrcardrw
@item -mmcrcardrw
@itemx +mmcrcardrw
Allow/disallow writes to MMC Replay card image
(@code{MMCRCardRW=1}, @code{MMCRCardRW=0}).

@findex -mmcreepromimage
@item -mmcreepromimage <filename>
Specify MMC Replay EEPROM image filename
(@code{MMCREEPROMImage}).

@findex -mmcreepromrw, +mmcreepromrw
@item -mmcreepromrw
@itemx +mmcreepromrw
Allow/disallow writes to MMC Replay EEPROM image
(@code{MMCREEPROMRW=1}, @code{MMCREEPROMRW=0}).

@findex -cartmv
@item -cartmv <name>
Attach raw 16kB Magic Voice cartridge image.

@findex -magicvoiceimage
@item -magicvoiceimage <name>
Specify Magic Voice cartridge ROM image filename
(@code{MagicVoiceImage}).

@findex -magicvoice, +magicvoice
@item -magicvoice
@itemx +magicvoice
Enable/disable Magic Voice cartridge
(@code{MagicVoiceCartridgeEnabled=1}, @code{MagicVoiceCartridgeEnabled=0}).

@findex -cartocean
@item -cartocean <name>
Attach raw Ocean cartridge image.

@findex -cartp64
@item -cartp64 <name>
Attach raw 256KB Prophet 64 cartridge image.

@findex -cartpf
@item -cartpf <name>
Attach raw 64kb Pagefox cartridge image.

@findex -cartramcart
@item -cartramcart <name>
Attach raw RamCart cartridge image.

@findex -ramcart, +ramcart
@item -ramcart
@itemx +ramcart
Enable/disable the RAMCART expansion
(@code{RAMCART=1}, @code{RAMCART=0}).

@findex -ramcartsize
@item -ramcartsize <size in KB>
Size of the RAMCART expansion
(@code{RAMCARTsize}).
(64, 128)

@findex -ramcartimage
@item -ramcartimage <name>
Specify name of RAMCART image
(@code{RAMCARTfilename}).

@findex -ramcartimagerw, +ramcartimagerw
@item -ramcartimagerw
@itemx +ramcartimagerw
Allow/disallow writing to RAMCart image
(@code{RAMCARTImageWrite=1}, @code{RAMCARTImageWrite=0}).

@findex -ramcartro
@item -ramcartro
Set the RamCart switch to read-only
(@code{RAMCART_RO=1}).

@findex -ramcartrw
@item -ramcartrw
Set the RamCart switch to read-only
(@code{RAMCART_RO=0}).

@findex -cartrep256
@item -cartrep256 <name>
Attach raw REX EP256 cartridge image.

@findex -cartrgcd
@item -cartrgcd <Name>
Attach raw 64kB RGCD cartridge image.

@findex -cartross
@item -cartross <name>
Attach raw 16/32kB ROSS cartridge image.

@findex -cartrr
@item -cartrr <name>
Attach raw 64KB Retro Replay cartridge image.

@findex -rrbioswrite, +rrbioswrite
@item -rrbioswrite
@itemx +rrbioswrite
Enable/disable saving of the RR ROM at exit
(@code{RRBiosWrite=1}, @code{RRBiosWrite=0}).

@findex -rrbankjumper, +rrbankjumper
@item -rrbankjumper
@itemx +rrbankjumper
Set/unset RR Bank Jumper
(@code{RRBankJumper=1}, @code{RRBankJumper=0}).

@findex -rrflashjumper, +rrflashjumper
@item -rrflashjumper
@itemx +rrflashjumper
Set/unset RR Flash Jumper
(@code{RRFlashJumper=1}, @code{RRFlashJumper=0}).

@findex -rrrev
@item -rrrev <Revision>
Set the RR revision
(@code{RRrevision}).
(0: Retro Replay, 1: Nordic Replay)

@findex -cartru
@item -cartru <name>
Attach raw 8kB REX Utility cartridge image.

@findex -carts64
@item -carts64 <name>
Attach raw 4kB Snapshot 64 cartridge image.

@findex -cartsb
@item -cartsb <name>
Attach raw Structured Basic cartridge image.

@findex -cartse5
@item -cartse5 <name>
Attach raw 16kB Super Explode V5 cartridge image.

@findex -cartsg
@item -cartsg <name>
Attach raw 64kB Super Games cartridge image.

@findex -cartsilver
@item -cartsilver <Name>
Attach raw Silverrock 128 cartridge image.

@findex -cartsimon
@item -cartsimon <name>
Attach raw 16kB Simons Basic cartridge image.

@findex -cartss4
@item -cartss4 <name>
Attach raw 32KB Super Snapshot V4 cartridge image.

@findex -cartss5
@item -cartss5 <name>
Attach raw 64KB Super Snapshot V5 cartridge image.

@findex -cartstar
@item -cartstar <name>
Attach raw 16KB Stardos cartridge image.

@findex -cartwl
@item -cartwl <name>
Attach raw 16KB Westermann Learning cartridge image.

@findex -cartws
@item -cartws <name>
Attach raw 8kB Warp Speed cartridge image.

@findex -cartzaxxon
@item -cartzaxxon <name>
Attach raw 16kB Zaxxon cartridge image.
@end table

@c @node FIXME
@subsection CIA settings

@c @node FIXME
@subsubsection CIA resources

@table @code

@vindex CIA1Model
@item CIA1Model
@c the exceptions will be corrected as the resource list is implemented
Integer specifying CIA1 model (all emulators except x64dtv/xpet/xplus4/xvic).
(0: old 6526, 1: new 6526A)

@vindex CIA2Model
@item CIA2Model
@c the exceptions will be corrected as the resource list is implemented
Integer specifying CIA2 model (all emulators except x64dtv/xcbm2/xcbm5x0/xpet/xplus4/xvic).
(0: old 6526, 1: new 6526A)

@end table

@c @node FIXME
@subsubsection CIA command-line options

@table @code

@findex -ciamodel
@item -ciamodel <model>
Set both CIA models
(@code{CIA1Model}, @code{CIA2Model})
@c the exceptions will be corrected as the resource list is implemented
(all emulators except x64dtv/xcbm2/xcbm5x0/xpet/xplus4/xvic).
(0: old 6526, 1: new 6526A)

@findex -cia1model
@item -cia1model <model>
Set CIA1 model
(@code{CIA1Model})
@c the exceptions will be corrected as the resource list is implemented
(all emulators except x64dtv/xpet/xplus4/xvic).
(0: old 6526, 1: new 6526A)

@findex -cia2model
@item -cia2model <model>
Set CIA2 model
(@code{CIA2Model})
@c the exceptions will be corrected as the resource list is implemented
(all emulators except x64dtv/xcbm2/xcbm5x0/xpet/xplus4/xvic).
(0: old 6526, 1: new 6526A)

@end table

@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 Hĺkan 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 VICIIModel
@item VICIIModel
Integer that specifies VIC-II model
(x64sc/xscpu64 only).
(6569, 6569r1, 8565, 6567, 8562, 6567r56a, 6572)

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

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

@vindex VICIIVSPBug
@item VICIIVSPBug
Boolean specifying whether the "VSP Bug" must be emulated
(x64sc/xscpu64 only).

@vindex VICIIVideoCache
@item VICIIVideoCache
Boolean specifying whether the video cache is turned on.

@vindex VICIIDoubleSize
@item VICIIDoubleSize
Boolean specifying whether double-size mode is turned on.

@vindex VICIIDoubleScan
@item VICIIDoubleScan
Boolean specifying whether double-scan mode is turned on.

@vindex VICIINewLuminances
@item VICIINewLuminances
Boolean specifying whether to use new (9 steps) luminances.

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

@vindex VICIIExternalPalette
@item VICIIExternalPalette
Boolean specifying whether to use external palette file or not.

@vindex VICIIColorSaturation
@item VICIIColorSaturation
Integer specifying saturation of internal calculated palette.
(0..2000)

@vindex VICIIColorContrast
@item VICIIColorContrast
Integer specifying contrast of internal calculated palette.
(0..2000)

@vindex VICIIColorBrightness
@item VICIIColorBrightness
Integer specifying brightness of internal calculated palette.
(0..2000)

@vindex VICIIColorGamma
@item VICIIColorGamma
Integer specifying gamma of internal calculated palette.
(0..4000)

@vindex VICIIColorTint
@item VICIIColorTint
Integer specifying tint of internal calculated palette.
(0..2000)

@vindex VICIIPALScanLineShade
@item VICIIPALScanLineShade
Integer specifying amount of scan line shading for the CRT emulation.
(0..1000)

@vindex VICIIPALBlur
@item VICIIPALBlur
Integer specifying amount of horizontal blur for the CRT emulation.
(0..1000)

@vindex VICIIPALOddLinePhase
@item VICIIPALOddLinePhase
Integer specifying phase for color carrier in odd lines.
(0..2000)

@vindex VICIIPALOddLineOffset
@item VICIIPALOddLineOffset
Integer specifying phase offset for color carrier in odd lines.
(0..2000)

@vindex VICIIAudioLeak
@item VICIIAudioLeak
Boolean specifying whether to enable/disable video to audio leak emulation.

@vindex VICIIFilter
@item VICIIFilter
Integer specifying rendering filter.
(0: None, 1: CRT emulation, 2: Scale2x)

@vindex VICIIBorderMode
@item VICIIBorderMode
Integer specifying border display mode.
(0: normal, 1: full, 2: debug, 3: none)

@end table


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

@table @code

@findex -VICIIcheckss, +VICIIcheckss
@item -VICIIcheckss
@itemx +VICIIcheckss
Enable/disable emulation of hardware sprite-sprite collision detection
(@code{VICIICheckSsColl=1}, @code{VICIICheckSsColl=0}).

@findex -VICIIchecksb, +VICIIchecksb
@item -VICIIchecksb
@itemx +VICIIchecksb
Enable/disable emulation of hardware sprite-background collision detection
(@code{VICIICheckSbColl=1}, @code{VICIICheckSbColl=0}).

@findex -VICIIvspbug, +VICIIvspbug
@item -VICIIvspbug
@itemx +VICIIvspbug
Enable/disable emulation of the "VSP bug"
(@code{VICIIVSPBug=1}, @code{VICIIVSPBug=0})
(x64sc/xscpu64 only).

@findex -VICIIvcache, +VICIIvcache
@item -VICIIvcache
@itemx +VICIIvcache
Enable/disable the video cache
(@code{VICIIVideoCache=1}, @code{VICIIVideoCache=0}).

@findex -VICIIdsize, +VICIIdsize
@item -VICIIdsize
@itemx +VICIIdsize
Enable/disable the double size mode
(@code{VICIIDoubleSize=1}, @code{VICIIDoubleSize=0}).

@findex -VICIIdscan, +VICIIdscan
@item -VICIIdscan
@itemx +VICIIdscan
Enable/disable the double scan mode
(@code{VICIIDoubleScan=1}, @code{VICIIDoubleScan=0}).

@findex -VICIIfilter
@item -VICIIfilter <Mode>
Select rendering filter
(@code{VICIIFilter}).
(0: None, 1: CRT emulation, 2: Scale2x)

@findex -VICIIintpal
@item -VICIIintpal
Use an internal calculated palette
(@code{VICIIExternalPalette=0}).

@findex -VICIIextpal
@item -VICIIextpal
Use an external palette (file)
(@code{VICIIExternalPalette=1}).

@findex -VICIIpalette
@item -VICIIpalette <Name>
Specify the name of the palette file
(@code{VICIIPaletteFile}).

@cindex -VICIIXRANDRfullmode
@item -VICIIXRANDRfullmode <mode>
Select fullscreen mode
@cindex -VICIIVidmodefullmode
@item -VICIIVidmodefullmode <mode>
Select fullscreen mode

@findex -VICIIborders
@item -VICIIborders <mode>
Set VIC-II border display mode
(@code{VICIIBorderMode}).
(0: normal, 1: full, 2: debug, 3: none)

@findex -VICIImodel
@item -VICIImodel <model>
Set VIC-II model
(@code{VICIIModel})
(x64sc and xscpu64 only).
(6569, 6569r1, 8565, 6567, 8562, 6567r56a, 6572)

@findex -VICIInewluminance, +VICIInewluminance
@item -VICIInewluminance
@item +VICIInewluminance
Enable/disable new luminances
(@code{VICIINewLuminances=1}, @code{VICIINewLuminances=0}).

@findex -VICIIsaturation
@item -VICIIsaturation <0-2000>
Set saturation of internal calculated palette
(@code{VICIIColorSaturation}).

@findex -VICIIcontrast
@item -VICIIcontrast <0-2000>
Set contrast of internal calculated palette
(@code{VICIIColorContrast}).

@findex -VICIIbrightness
@item -VICIIbrightness <0-2000>
Set brightness of internal calculated palette
(@code{VICIIColorBrightness}).

@findex -VICIIgamma
@item -VICIIgamma <0-4000>
Set gamma of internal calculated palette
(@code{VICIIColorGamma}).

@findex -VICIItint
@item -VICIItint <0-2000>
Set tint of internal calculated palette
(@code{VICIIColorTint}).

@findex -VICIIoddlinesphase
@item -VICIIoddlinesphase <0-2000>
Set phase for color carrier in odd lines
(@code{VICIIPALOddLinePhase}).

@findex -VICIIoddlinesoffset
@item -VICIIoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines
(@code{VICIIPALOddLineOffset}).

@findex -VICIIcrtblur
@item -VICIIcrtblur <0-1000>
Amount of horizontal blur for the CRT emulation
(@code{VICIIPALBlur}).

@findex -VICIIcrtscanlineshade
@item -VICIIcrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation
(@code{VICIIPALScanLineShade}).

@findex -VICIIaudioleak, +VICIIaudioleak
@item -VICIIaudioleak
@item +VICIIaudioleak
Enable/disable video to audio leak emulation
(@code{VICIIAudioLeak=1}, @code{VICIIAudioLeak=0}).

@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
Integer specifying the amount of emulated extra SIDs.
(0: off, 1: 1 extra sid, 2: 2 extra sids)

@vindex SidStereoAddressStart
@item SidStereoAddressStart
Integer specifying the base address of the second SID
(x64, x64sc, xscpu64, x128 and vsid only).
(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0,
0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0,
0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0,
0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0)
(x64/x64sc/xscpu64/vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0,
0xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0,
0xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0,
0xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0,
0xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0,
0xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0,
0xDFC0, 0xDFE0)

@vindex SidTripleAddressStart
@item SidTripleAddressStart
Integer specifying the base address of the third SID
(x64, x64sc, xscpu64, x128 and vsid only).
(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0,
0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0,
0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0,
0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0)
(x64/x64sc/xscpu64/vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0,
0xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0,
0xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0,
0xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0,
0xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0,
0xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0,
0xDFC0, 0xDFE0)

@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.
(0: 6581, 1: 8580, 2: 8580D, 3: 6581R4, 4: DTVSID)

@vindex SidEngine
@item SidEngine
Integer specifying what SID engine will be used.
(0: FastSID, 1: ReSID, 2: Catweasel MKIII, 3: HardSID, 4: ParSID Port 1, 5: ParSID Port 2, 6: ParSID Port 3)

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

@vindex SidResidGain
@item SidResidGain
Integer that specifies reSID gain in percent [97] (90..100)
@vindex SidResidFilterBias
@item SidResidFilterBias
Integer that specifies reSID filter bias, which can be used to adjust DAC bias 
in millivolts. [0] (-5000..5000)

@end table


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

@table @code

@findex -sidstereo
@item -sidstereo
Specify the amount of extra SID chips to emulate
(@code{SidStereo}).
(0: off, 1: 1 extra sid, 2: 2 extra sids)

@findex -sidstereoaddress
@item -sidstereoaddress <Base address>
Specifies the start address for the second SID chip
(@code{SidStereoAddressStart})
(x64, x64sc, xscpu64, x128 and vsid only).
(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0,
0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0,
0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0,
0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0)
(x64/x64sc/xscpu64/vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0,
0xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0,
0xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0,
0xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0,
0xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0,
0xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0,
0xDFC0, 0xDFE0)

@findex -sidtripleaddress
@item -sidtripleaddress @code{ADDRESS}
Specifies the start address for the third SID chip
(@code{SidTripleAddressStart})
(x64, x64sc, xscpu64, x128 and vsid only).
(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0,
0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0,
0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0,
0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0)
(x64/x64sc/xscpu64/vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0,
0xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0,
0xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0,
0xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0,
0xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0,
0xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0,
0xDFC0, 0xDFE0)

@findex -sidenginemodel
@item -sidenginemodel <engine and model>
Specify engine and model for the emulated SID chip
(@code{SidEngine}, @code{SidModel}).
(FastSID 6581: 0/fast/fastold/fast6581,
FastSID 8580: 1/fastnew/fast8580,
ReSID 6581: 256/resid/residold/resid6581,
ReSID 8580: 257/residnew/resid8580,
ReSID 8580 + digiboost: 258/residdigital/residd/residnewd/resid8580d,
DTVSID: 260/dtv/c64dtv/dtvsid,
Catweasel MKIII: 512/catweaselmkiii/catweasel3/catweasel/cwmkiii/cw3/cw,
HardSID: 768/hardsid/hard/hs,
ParSID Port 1: 1024/parsid/parsid1/par1/lpt1,
ParSID Port 2: 1280/parsid2/par2/lpt2
ParSID Port 3: 1536/parsid3/par3/lpt3)

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

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

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

@cindex -residgain
@item -residgain @code{PERCENTAGE}
Specifies reSID gain in percent (90 - 100).

@cindex -residfilterbias
@item -residfilterbias <number>
reSID filter bias setting, which can be used to adjust DAC bias in millivolts.

@end table


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

I/O extensions are (usually) cartridges which do not map into ROM space,
but use only the I/O space at address range $DE00 @dots{} $DEFF and/or
$DF00 @dots{} $DFFF.

Please use these extensions only when needed, as they might cause
compatibility problems.

The following I/O extensions are available:

@itemize @bullet

@cindex ACIA (Swiftlink, Turbo232)
@item ACIA (Swiftlink, Turbo232)

@cindex DigiMAX
@item DigiMAX

@cindex DS12C887 RTC
@item DS12C887 RTC

@cindex Ethernet (The Final Ethernet, RR-Net)
@item Ethernet (The Final Ethernet, RR-Net)

@cindex GEO-RAM
@item GEO-RAM

@cindex MIDI (Passport, Datel, Maplin, Namesoft, Sequential)
@item MIDI (Passport, Datel, Maplin, Namesoft, Sequential)

@cindex REU
@item REU -
The ``RAM Expansion Module'' extension emulates a standard
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 SFX Sound Expander
@item SFX Sound Expander

@cindex SFX Sound Sampler
@item SFX Sound Sampler

@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 Acia1Enable
@item Acia1Enable
Boolean specifying whether the ACIA (Swiftlink, Turbo232) cartridge should be emulated or not.
@vindex Acia1Mode
@item Acia1Mode
Enum specifying the type of emulated RS232 interface (0: normal, 1: Swithlink, 2: Turbo232)
@vindex Acia1Base
@item Acia1Base
Integer specifying the base address for the emulated ACIA chip.

@vindex DIGIMAX
@item DIGIMAX
Boolean specifying whether the DigiMAX cartridge should be emulated or not.

@vindex DIGIMAXbase
@item DIGIMAXbase
Integer specifying the DigiMAX base address.
(0xDD00: useport, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0,
0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0)

@vindex DS12C887RTC
@item DS12C887RTC
Boolean specifying whether the DS12C887 RTC cartridge should be emulated or not.

@vindex DS12C887RTCbase
@item DS12C887RTCbase
Integer specifying the DS12C887 RTC base address.
x128: (0xD700, 0xDE00, 0xDF00)
x64/x64sc/xscpu64: (0xD500, 0xD600, 0xD700, 0xDE00, 0xDF00)

@vindex DS12C887RTCRunMode
@item DS12C887RTCRunMode
Boolean specifying whether the DS12C887 RTC cartridge starts out running or halted.
(0: halted, 1: running)

@vindex DS12C887RTCSave
@item DS12C887RTCSave
Boolean specifying whether the DS12C887 RTC data should be saved when changed or not.

@vindex ETHERNET_ACTIVE
@item ETHERNET_ACTIVE
Boolean that specifies whether the CS8900 ethernet interface emulation is active.
@vindex ETHERNET_INTERFACE
@item ETHERNET_INTERFACE
String specifying the device name of the ethernet device to use for the emulation.
@vindex ETHERNET_DISABLED
@item ETHERNET_DISABLED
Boolean that specified whether ethernet emulation has been disabled because it is
not available in the current configuration.
@vindex ETHERNET_AS_RR
@item ETHERNET_AS_RR
Boolean that specifies whether RR-Net compatible mapping is enabled.

@vindex GEORAM
@item GEORAM
Boolean specifying whether the GEO-RAM cartridge should be emulated or not.

@vindex GEORAMfilename
@item GEORAMfilename
String specifying the filename of the GEORAM image.

@vindex GEORAMImageWrite
@item GEORAMImageWrite
Boolean, if true write back the GEO-RAM image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.

@vindex GEORAMsize
@item GEORAMsize
Integer specifying the size of the emulated GEO-RAM in KB.
(64, 128, 256, 512, 1024, 2048, 4096).

@vindex MIDIEnable
@item MIDIEnable
Boolean specifying whether the MIDI cartridge should be emulated or not
(x64/x64sc/xscpu64/x128 only, and only if MIDI support is enabled and available at compile time).

@vindex MIDIMode
@item MIDIMode
Integer specifying the type of emulated MIDI interface
(x64, x64sc, xscpu64 and x128 only, and only if MIDI support is enabled and available at compile time).
(0: Sequential, 1: Passport/Syntech, 2: DATEL/Siel/JMS, 3: Namesoft, 4: Maplin)

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

@vindex REUfilename
@item REUfilename
String specifying the filename of the REU image.

@vindex REUImageWrite
@item REUImageWrite
Boolean, if true write back the REU image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.

@vindex REUsize
@item REUsize
Integer specifying the size of the emulated REU in KB.
(128, 256, 512, 1024, 2048, 4096, 8192, 16384)

@vindex SFXSoundExpander
@item SFXSoundExpander
Boolean specifying whether the SFX Sound Expander should be emulated or not.

@vindex SFXSoundExpanderChip
@item SFXSoundExpanderChip
Integer specifying which YM chip is emulated.
(3526, 3812)

@vindex SFXSoundSampler
@item SFXSoundSampler
Boolean specifying whether the SFX Sound Sampler 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 -acia1, +acia1
@item -acia1
@itemx +acia1
Enable/Disable the $DE** ACIA RS232 interface emulation

@findex -digimax, +digimax
@item -digimax
@itemx +digimax
Enable/disable the DigiMAX cartridge
(@code{DIGIMAX=1}, @code{DIGIMAX=0}).

@findex -digimaxbase
@item -digimaxbase <base address>
Base address of the DigiMAX cartridge
(@code{DIGIMAXbase}).
(0xDD00: useport, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0,
0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0)

@findex -ds12c887rtc, +ds12c887rtc
@item -ds12c887rtc
@itemx +ds12c887rtc
Enable/disable the DS12C887 RTC cartridge
(@code{DS12C887RTC=1}, @code{DS12C887RTC=0}).

@findex -ds12c887rtcbase
@item -ds12c887rtcbase <base address>
Base address of the DS12C887 RTC cartridge
(@code{DS12C887RTCbase}).
x128: (0xD700, 0xDE00, 0xDF00)
x64/x64sc/xscpu64: (0xD500, 0xD600, 0xD700, 0xDE00, 0xDF00)

@findex -ds12c887rtchalted, -ds12c887rtcrunning
@item -ds12c887rtchalted
Set the DS12C887 RTC oscillator to 'halted'
(@code{DS12C887RTCRunMode=0}).
@item +ds12c887rtcrunning
Set the DS12C887 RTC oscillator to 'running'
(@code{DS12C887RTCRunMode=1}).

@findex -ds12c887rtcsave, +ds12c887rtcsave
@item -ds12c887rtcsave
@itemx +ds12c887rtcsave
Enable/disable saving of the DS12C887 RTC data when changed
(@code{DS12C887RTCSave=1}, @code{DS12C887RTCSave=0}).

@findex -miditype
@item -miditype <0-4>
Set MIDI interface type
(@code{MIDIMode})
(x64, x64sc, xscpu64 and x128 only, and only if MIDI support is enabled and available at compile time).
(0: Sequential, 1: Passport/Syntech, 2: DATEL/Siel/JMS, 3: Namesoft, 4: Maplin)

@findex -midi, +midi
@item -midi
@itemx +midi
Enable/disable MIDI emulation
(@code{MIDIEnable=1}, @code{MIDIEnable=0})
(x64, x64sc, xscpu64 and x128 only, and only if MIDI support is enabled and available at compile time).
(0: Sequential, 1: Passport/Syntech, 2: DATEL/Siel/JMS, 3: Namesoft, 4: Maplin)

@findex -georam, +georam
@item -georam
@itemx +georam
Enable/disable the GEORAM expansion unit
(@code{GEORAM=1}, @code{GEORAM=0}).

@findex -cartgeoram
@item -cartgeoram <name>
Attach raw GEO-RAM cartridge image.

@findex -georamimage
@item -georamimage <name>
Specify name of GEORAM image
(@code{GEORAMfilename}).

@findex -georamimagerw, +georamimagerw
@item -georamimagerw
@itemx +georamimagerw
Allow/disallow writing to GEORAM image
(@code{GEORAMImageWrite=1}, @code{GEORAMImageWrite=0}).

@findex -georamsize
@item -georamsize <size in KB>
Size of the GEORAM expansion unit
(@code{GEORAMsize}).
(64, 128, 256, 512, 1024, 2048, 4096)

@findex -reu, +reu
@item -reu
@itemx +reu
Enable/disable emulation of the RAM Expansion Module
(@code{REU=1}, @code{REU=0}).

@findex -cartreu
@item -cartreu <name>
Attach raw REU cartridge image.

@findex -reuimage
@item -reuimage <name>
Specify name of REU image
(@code{REUfilename}).

@findex -reuimagerw, +reuimagerw
@item -reuimagerw
@itemx +reuimagerw
Allow/disallow writing to REU image
(@code{REUImageWrite=1}, @code{REUImageWrite=0}).

@findex -reusize
@item -reusize <size in KB>
Size of the RAM expansion unit
(@code{REUsize}).
(128, 256, 512, 1024, 2048, 4096, 8192, 16384)

@findex -sfxse, +sfxse
@item -sfxse
@itemx +sfxse
Enable/disable the SFX soundexpander cartridge
(@code{SFXSoundExpander=1}, @code{SFXSoundExpander=0}).

@findex -sfxsetype
@item -sfxsetype <type>
Set YM chip type
(@code{SFXSoundExpanderChip}).
(3526, 3812)

@findex -sfxss, +sfxss
@item -sfxss
@itemx +sfxss
Enable/disable the SFX Sound Sampler cartridge
(@code{SFXSoundSampler=1}, @code{SFXSoundSampler=0}).

@cindex -tfe, +tfe
@item -tfe
@itemx +tfe
Enable/Disable the TFE ("The Final Ethernet") unit
@cindex -tfeif
@item -tfeif <name>
Set the system ethernet interface for TFE emulation
@cindex -tferrnet, +tferrnet
@item -tferrnet
@itemx +tferrnet
Enable/Disable RRNet mode of TFE emulation

@findex -burstmod
@item -burstmod <value>
Set the kind of burst modification. This emulates the fast serial bus connection
as described at @uref{http://www.cs.tut.fi/~albert/Dev/burst/}, with the wire to
the tape port cut
(@code{BurstMod}).
(0: None, 1: CIA-1, 2: CIA-2)

@end table

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

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

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

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

@table @code

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

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

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

@vindex 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 system ROM options, , C64 system ROM resources, C64 system ROM settings
@subsubsection C64 system ROM command-line options

@table @code

@findex -basic
@item -basic <name>
Specify filename of the Basic ROM file
(@code{BasicName}).

@findex -chargen
@item -chargen <name>
Specify filename of the character generator ROM file
(@code{ChargenName}).

@findex -kernal
@item -kernal <name>
Specify filename of the Kernal ROM file
(@code{KernalName}).

@findex -kernalrev
@item -kernalrev <revision>
Specify Kernal revision
(@code{KernalRev}).
(1/2/3, 67/sx, 100/4064)
@end table

@c @node FIXME
@subsection C64 settings

@c @node FIXME
@subsubsection C64 resources

@table @code

@vindex GlueLogic
@item GlueLogic
Integer specifying the type of emulated glue-logic.
(0: discrete, 1: custom IC)

@vindex BurstMod
@item BurstMod
Integer specifying the kind of Burst-Mode modification.
(0: None, 1: CIA-1, 2: CIA-2)

@vindex BoardType
@item BoardType
Integer specifying the type of emulated board (not available in xscpu64).
(0: C64, 1: MAX)

@vindex IECReset
@item IECReset
Integer specifying if the IEC bus resets when the CPU resets.
(0: No, 1: Yes)

@vindex MemoryHack
@item MemoryHack
Integer specifying what memory expansion hack is active.
(0: None, 1: C64 256K, 2: PLUS60K, 3: PLUS256K)

@vindex PLUS60Kfilename
@item PLUS60Kfilename
String specifying the filename of the PLUS60K RAM image.

@vindex PLUS60Kbase
@item PLUS60Kbase
Integer that specifies the base address of the PLUS60K RAM expansion.
(0xD040, 0xD100)

@vindex PLUS256Kfilename
@item PLUS256Kfilename
String specifying the filename of the PLUS256K RAM image.

@vindex C64_256Kfilename
@item C64_256Kfilename
String specifying the filename of the 256K RAM image.

@vindex C64_256Kbase
@item C64_256Kbase
Integer that specifies the base address of the 256K RAM expansion.
(0xDE00/0xDE80/0xDF00/0xDF80)

@vindex MachineVideoStandard
@item MachineVideoStandard
Integer that specifies the video standard of the emulated machine
(-4: PAL-N, -3: Old NTSC, -1: PAL, -2: NTSC).

@end table

@c @node FIXME
@subsubsection C64 command-line options

@table @code

@findex -gluelogictype
@item -gluelogictype <type>
Set glue logic type
(@code{GlueLogic}).
(0: discrete, 1: 252535-01)

@findex -iecreset
@item -iecreset <value>
Set IEC reset bahaviour
(@code{IECReset}).
(0: Do not reset with CPU reset, 1: Reset with CPU reset)

@findex -memoryexphack
@item -memoryexphack <device>
Set active memory expansion hack
(@code{MemoryHack}).
(0: None, 1: C64 256K, 2: PLUS60K, 3: PLUS256K)

@findex -plus60kimage
@item -plus60kimage <name>
Specify name of PLUS60K image
(@code{PLUS60Kfilename}).

@findex -plus60kbase
@item -plus60kbase <base address>
Base address of the PLUS60K expansion
(@code{PLUS60Kbase}).
(0xD040/0xD100)


@findex -plus256kimage
@item -plus256kimage <name>
Specify name of PLUS256K image
(@code{PLUS256Kfilename}).

@findex -256kimage
@item -256kimage <name>
Specify name of 256K image
(@code{C64_256Kfilename}).

@findex -256kbase
@item -256kbase <base address>
Base address of the 256K expansion
(@code{C64_256Kbase}).
(0xDE00/0xDE80/0xDF00/0xDF80)

@findex -pal
@item -pal
Use PAL sync factor
(@code{MachineVideoStandard=-1}).

@findex -ntsc
@item -ntsc
Use NTSC sync factor
(@code{MachineVideoStandard=-2}).

@findex -ntscold
@item -ntscold
Use old NTSC sync factor
(@code{MachineVideoStandard=-3}).

@findex -paln
@item -paln
Use PAL-N sync factor
(@code{MachineVideoStandard=-4}).

@findex -model
@item -model <Model>
Set the C64 model
(@code{VICIIModel}, @code{CIA1Model}, @code{CIA2Model}, @code{GlueLogic}, @code{BoardType}, @code{IECReset}, @code{KernalName},
@code{ChargenName}, @code{SidEngine}, @code{SidModel})
(x64 and x64sc only).
(c64/c64c/c64old, ntsc/newntsc/oldntsc, drean, jap, c64gs, pet64, ultimax)

@end table

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

@node C128-specific, C64DTV-specific, C64/128-specific, Machine-specific features
@section C128-specific commands and settings

@c @node FIXME
@subsection VDC settings

@c @node FIXME
@subsubsection VDC resources

@table @code

@vindex VDC64KB
@item VDC64KB
Boolean to enabled/disable full 64k video ram.

@vindex VDCRevision
@item VDCRevision
Integer specifying the VDC hardware revision
(0: Rev 0, 1: Rev 1, 2: Rev 2).

@vindex VDCVideoCache
@item VDCVideoCache
Boolean specifying whether the video cache is turned on.

@vindex VDCDoubleSize
@item VDCDoubleSize
Boolean specifying whether double-size mode is turned on.

@vindex VDCDoubleScan
@item VDCDoubleScan
Boolean specifying whether double-scan mode is turned on.

@vindex VDCStretchVertical
@item VDCStretchVertical
Boolean specifying whether vertical stretching is turned on.

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

@vindex VDCExternalPalette
@item VDCExternalPalette
Boolean specifying whether to use external palette file or not.

@vindex VDCColorSaturation
@item VDCColorSaturation
Integer specifying saturation of internal calculated palette.
(0..2000)

@vindex VDCColorContrast
@item VDCColorContrast
Integer specifying contrast of internal calculated palette.
(0..2000)

@vindex VDCColorBrightness
@item VDCColorBrightness
Integer specifying brightness of internal calculated palette.
(0..2000)

@vindex VDCColorGamma
@item VDCColorGamma
Integer specifying gamma of internal calculated palette.
(0..4000)

@vindex VDCColorTint
@item VDCColorTint
Integer specifying tint of internal calculated palette.
(0..2000)

@vindex VDCPALScanLineShade
@item VDCPALScanLineShade
Integer specifying amount of scan line shading for the CRT emulation.
(0..1000)

@vindex VDCPALBlur
@item VDCPALBlur
Integer specifying amount of horizontal blur for the CRT emulation.
(0..1000)

@vindex VDCPALOddLinePhase
@item VDCPALOddLinePhase
Integer specifying phase for color carrier in odd lines.
(0..2000)

@vindex VDCPALOddLineOffset
@item VDCPALOddLineOffset
Integer specifying phase offset for color carrier in odd lines.
(0..2000)

@vindex VDCAudioLeak
@item VDCAudioLeak
Boolean specifying whether to enable/disable video to audio leak emulation.

@vindex VDCFilter
@item VDCFilter
Integer specifying rendering filter
(0: None, 1: CRT emulation, 2: Scale2x)
@end table

@c @node FIXME
@subsubsection VDC command-line options

@table @code
@findex -VDCvcache, +VDCvcache
@item -VDCvcache
@itemx +VDCvcache
Enable/disable the video cache
(@code{VDCVideoCache=1}, @code{VDCVideoCache=0}).

@findex -VDCdsize, +VDCdsize
@item -VDCdsize
@itemx +VDCdsize
Enable/disable double size
(@code{VDCDoubleSize=1}, @code{VDCDoubleSize=0}).

@findex -VDCstretchvertical, +VDCstretchvertical
@item -VDCstretchvertical
@itemx +VDCstretchvertical
Enable/Disable vertical stretching
(@code{VDCStretchVertical=1}, @code{VDCStretchVertical=0}).

@findex -VDCdscan, +VDCdscan
@item -VDCdscan
@itemx +VDCdscan
Enable/disable double scan
(@code{VDCDoubleScan=1}, @code{VDCDoubleScan=0}).

@findex -VDCintpal
@item -VDCintpal
Use an internal calculated palette
(@code{VDCExternalPalette=0}).

@findex -VDCextpal
@item -VDCextpal
Use an external palette (file)
(@code{VDCExternalPalette=1}).

@findex -VDCpalette
@item -VDCpalette <name>
Specify name of file of external palette
(@code{VDCPaletteFile}).

@cindex -VDCXRANDRfullmode
@item -VDCXRANDRfullmode <mode>
Select fullscreen mode
@cindex -VDCVidmodefullmode
@item -VDCVidmodefullmode <mode>
Select fullscreen mode

@findex -VDC16KB
@item -VDC16KB
Set the VDC memory size to 16KB
(@code{VDC64KB=0}).

@findex -VDC64KB
@item -VDC64KB
Set the VDC memory size to 64KB
(@code{VDC64KB=1}).

@findex -VDCRevision
@item -VDCRevision <number>
Set VDC revision
(@code{VDCRevision}).
(0..2)

@findex -VDCsaturation
@item -VDCsaturation <0-2000>
Set saturation of internal calculated palette
(@code{VDCColorSaturation}).

@findex -VDCcontrast
@item -VDCcontrast <0-2000>
Set contrast of internal calculated palette
(@code{VDCColorContrast}).

@findex -VDCbrightness
@item -VDCbrightness <0-2000>
Set brightness of internal calculated palette
(@code{VDCColorBrightness}).

@findex -VDCgamma
@item -VDCgamma <0-4000>
Set gamma of internal calculated palette
(@code{VDCColorGamma}).

@findex -VDCtint
@item -VDCtint <0-2000>
Set tint of internal calculated palette
(@code{VDCColorTint}).

@findex -VDCoddlinesphase
@item -VDCoddlinesphase <0-2000>
Set phase for color carrier in odd lines
(@code{VDCPALOddLinePhase}).

@findex -VDCoddlinesoffset
@item -VDCoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines
(@code{VDCPALOddLineOffset}).

@findex -VDCcrtblur
@item -VDCcrtblur <0-1000>
Amount of horizontal blur for the CRT emulation
(@code{VDCPALBlur}).

@findex -VDCcrtscanlineshade
@item -VDCcrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation
(@code{VDCPALScanLineShade}).

@findex -VDCaudioleak, +VDCaudioleak
@item -VDCaudioleak
@item +VDCaudioleak
Enable/disable video to audio leak emulation
(@code{VDCAudioLeak=1}, @code{VDCAudioLeak=0}).

@findex -VDCfilter
@item -VDCfilter <Mode>
Select rendering filter
(@code{VDCFilter}).
(0: None, 1: CRT emulation, 2: Scale2x)

@end table

@c @node FIXME
@subsection C128 system ROM settings

@c @node FIXME
@subsubsection C128 system ROM resources

@table @code

@vindex ChargenIntName
@item ChargenIntName
String specifying the filename of the international character generator ROM image.

@vindex ChargenDEName
@item ChargenDEName
String specifying the filename of the German character generator ROM image.

@vindex ChargenFRName
@item ChargenFRName
String specifying the filename of the French character generator ROM image.

@vindex ChargenSEName
@item ChargenSEName
String specifying the filename of the Swedish character generator ROM image.

@vindex ChargenCHName
@item ChargenCHName
String specifying the filename of the Swiss character generator ROM image.

@vindex KernalIntName
@item KernalIntName
String specifying the filename of the international Kernal ROM image.

@vindex KernalDEName
@item KernalDEName
String specifying the filename of the German Kernal ROM image.

@vindex KernalFIName
@item KernalFIName
String specifying the filename of the Finnish Kernal ROM image.

@vindex KernalFRName
@item KernalFRName
String specifying the filename of the French Kernal ROM image.

@vindex KernalITName
@item KernalITName
String specifying the filename of the Italian Kernal ROM image.

@vindex KernalNOName
@item KernalNOName
String specifying the filename of the Norwegian Kernal ROM image.

@vindex KernalSEName
@item KernalSEName
String specifying the filename of the Swedish Kernal ROM image.

@vindex KernalCHName
@item KernalCHName
String specifying the filename of the Swiss Kernal ROM image.

@vindex BasicLoName
@vindex BasicHiName
@item BasicLoName
@itemx BasicHiName
Strings specifying the filename of the Basic ROM images.

@vindex Kernal64Name
@item Kernal64Name
String specifying the filename of the C64 Kernal ROM image.

@vindex Basic64Name
@item Basic64Name
String specifying the filename of the C64 Basic ROM image.

@vindex InternalFunctionROM
@item InternalFunctionROM
Integer specifying the internal function ROM type
(0: None, 1: ROM, 2: RAM, 3: RTC).

@vindex InternalFunctionName
@item InternalFunctionName
String specifying the filename of the ROM image for the internal function ROM.

@vindex InternalFunctionROMRTCSave
@item InternalFunctionROMRTCSave
Boolean to enable/disable the saving of the Internal Function RTC data when changed.

@vindex ExternalFunctionROM
@item ExternalFunctionROM
Integer specifying the external function ROM type
(0: None, 1: ROM, 2: RAM, 3: RTC)

@vindex ExternalFunctionName
@item ExternalFunctionName
String specifying the filename of the ROM image for the external function ROM.

@vindex ExternalFunctionROMRTCSave
@item ExternalFunctionROMRTCSave
Boolean to enable/disable the saving of the External Function RTC data when changed.

@end table

@c @node FIXME
@subsubsection C128 system ROM command-line options

@table @code

@findex -basic64
@item -basic64 <name>
Specify name of C64 mode BASIC ROM image
(@code{Basic64Name}).

@findex -kernal64
@item -kernal64 <name>
Specify name of C64 mode Kernal ROM image
(@code{Kernal64Name}).

@findex -basiclo
@item -basiclo <name>
Specify name of BASIC ROM image (lower part)
(@code{BasicLoName}).

@findex -basichi
@item -basichi <name>
Specify name of BASIC ROM image (higher part)
(@code{BasicHiName}).

@findex -kernal
@item -kernal <name>
Specify name of international Kernal ROM image
(@code{KernalIntName}).

@findex -kernalde
@item -kernalde <name>
Specify name of German Kernal ROM image
(@code{KernalDEName}).

@findex -kernalfi
@item -kernalfi <name>
Specify name of Finnish Kernal ROM image
(@code{KernalFIName}).

@findex -kernalfr
@item -kernalfr <name>
Specify name of French Kernal ROM image
(@code{KernalFRName}).

@findex -kernalit
@item -kernalit <name>
Specify name of Italian Kernal ROM image
(@code{KernalITName}).

@findex -kernalno
@item -kernalno <name>
Specify name of Norwegian Kernal ROM image
(@code{KernalNOName}).

@findex -kernalse
@item -kernalse <name>
Specify name of Swedish Kernal ROM image
(@code{KernalSEName}).

@findex -kernalch
@item -kernalch <name>
Specify name of Swiss Kernal ROM image
(@code{KernalCHName}).

@findex -chargen
@item -chargen <name>
Specify name of international character generator ROM image
(@code{ChargenIntName}).

@findex -chargde
@item -chargde <name>
Specify name of German character generator ROM image
(@code{ChargenDEName}).

@findex -chargfr
@item -chargfr <name>
Specify name of French character generator ROM image
(@code{ChargenFRName}).

@findex -chargse
@item -chargse <name>
Specify name of Swedish character generator ROM image
(@code{ChargenSEName}).

@findex -chargch
@item -chargch <name>
Specify name of Swiss character generator ROM image
(@code{ChargenCHName}).

@findex -intfunc
@item -intfunc <type>
Set the internal Function ROM type
(@code{InternalFunctionROM}).
(0: None, 1: ROM, 2: RAM, 3: RTC)

@findex -intfrom
@item -intfrom <name>
Specify name of internal Function ROM image
(@code{InternalFunctionName}).

@findex -intfuncrtcsave, +intfuncrtcsave
@item -intfuncrtcsave
@itemx +intfuncrtcsave
Enable/disable the saving of the Internal Function RTC data when changed
(@code{InternalFunctionROMRTCSave=1}, @code{InternalFunctionROMRTCSave=0}).

@findex -extfunc
@item -extfunc <type>
Set the external Function ROM type
(@code{ExternalFunctionROM}).
(0: None, 1: ROM, 2: RAM, 3: RTC)

@findex -extfrom
@item -extfrom <name>
Specify name of external Function ROM image
(@code{ExternalFunctionName}).

@findex -extfuncrtcsave, +extfuncrtcsave
@item -extfuncrtcsave
@itemx +extfuncrtcsave
Enable/disable the saving of the External Function RTC data when changed
(@code{ExternalFunctionROMRTCSave=1}, @code{ExternalFunctionROMRTCSave=0}).

@end table

@c @node FIXME
@subsection C128 settings

@c @node FIXME
@subsubsection C128 resources

@table @code

@vindex 40/80ColumnKey
@item 40/80ColumnKey
Boolean specifying the status of the 40/80 columns key.
(0: Not pressed, 1: Pressed)

@vindex Go64Mode
@item Go64Mode
Boolean, if true enter C64 mode on reset.

@vindex C128FullBanks
@item C128FullBanks
Boolean to enable/disable RAM banks 2 and 3.

@vindex MachineType
@item MachineType
Integer specifying the C128 machine type.
(0: International, 1: Finnish, 2: French, 3: German, 4: Italian, 5: Norwegian, 6: Swedish)

@vindex MachineVideoStandard
@item MachineVideoStandard
Integer that specifies the video standard of the emulated machine
(-1: PAL, -2: NTSC).

@end table

@c @node FIXME
@subsubsection C128 command-line options

@table @code

@findex -40col
@item -40col
Activate 40 column mode
(@code{40/80ColumnKey=1}).

@findex -80col
@item -80col
Activate 80 column mode
(@code{40/80ColumnKey=0}).

@findex -go64, +go64
@item -go64
Always switch to C64 mode on reset
(@code{Go64Mode=1}.
@item +go64
Always switch to C128 mode on reset
(@code{Go64Mode=0}.

@findex -pal
@item -pal
Use PAL sync factor
(@code{MachineVideoStandard=-1}).

@findex -ntsc
@item -ntsc
Use NTSC sync factor
(@code{MachineVideoStandard=-2}).

@findex -model
@item -model <Model>
Set the C128 model
(@code{MachineVideoStandard}, @code{CIA1Model}, @code{CIA2Model}, @code{VICIINewLuminances}, @code{VDCRevision},
@code{VDC64KB}, @code{SidEngine}, @code{SidModel}).
(c128/c128dcr, pal/ntsc)

@findex -c128fullbanks, +c128fullbanks
@item -c128fullbanks
@itemx +c128fullbanks
Enable/disable RAM banks 2 and 3
(@code{C128FullBanks=1}, @code{C128FullBanks=0}).

@findex -machinetype
@item -machinetype <Type>
Set the C128 machine type
(@code{MachineType}).
(0: International, 1: Finnish, 2: French, 3: German, 4: Italian, 5: Norwegian, 6: Swedish)

@end table

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

@node C64DTV-specific, SCPU64-specific, C128-specific, Machine-specific features
@section C64DTV-specific commands and settings

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

@menu
* C64DTV ROM image::
* DTV revision::
* LumaFix::
* Userport::
* Debug::
* Monitor DTV features::
@end menu


@node C64DTV ROM image, DTV revision, C64DTV-specific, C64DTV-specific
@subsection C64DTV ROM image

The DTV has a 2MB Flash chip which contains the kernal, basic and
character set ROMs along with other data, such as games in the case of
the original C64DTV ROM.

The image file is a dump of the flash chip. It is exactly 2MB (2097152 bytes).

If you do not have a suitable image file, an image using the C64 kernal,
basic and charset is automatically created.

If writing to the C64DTV ROM is enabled, the image file is rewritten with
the current data when exiting x64dtv.

Note that x64dtv tries to load the image file from the C64DTV
directory first, and if it isn't found there, x64dtv tries to
load it from the current directory. If you do not have @file{dtvrom.bin}
in your C64DTV directory and writing to DTV ROM is enabled,
the @file{dtvrom.bin} file is created to the current directory.

NOTE: The original C64DTV ROM has somewhat distorted colors,
normally you should use a patched rom.

@table @code

@findex -c64dtvromimage
@item -c64dtvromimage <name>
Specify filename of the C64DTV ROM image
(@code{c64dtvromfilename}).

@findex -c64dtvromrw, +c64dtvromrw
@item -c64dtvromrw
@itemx +c64dtvromrw
Enable/disable writing to C64DTV ROM image
(@code{c64dtvromrw=1}, @code{c64dtvromrw=0}).

@end table

The trueflashfs option is analogous to True drive emulation.  If disabled,
any file access to the flash filesystem (device 1) will go to the local
file system instead.

@table @code

@findex -trueflashfs, +trueflashfs
@item -trueflashfs
@itemx +trueflashfs
Enable/disable true hardware flash file system
(@code{FlashTrueFS=1}, @code{FlashTrueFS=0}).

@findex -fsflash
@item -fsflash <name>
Specify the directory for the flash file system device
(@code{FSFlashDir}).

@end table


@node DTV revision, LumaFix, C64DTV ROM image, C64DTV-specific
@subsection DTV revision

The DTV revision 2 has a bug in the Blitter. Using revision 3
is recommended. Emulation of DTV revision 2 including Blitter
bug is intended for testing DTV software.

@table @code

@findex -dtvrev
@item -dtvrev <revision>
Specify DTV revision
(@code{DtvRevision}).
(2: DTV2, 3: DTV3)

@end table


@node LumaFix, Userport, DTV revision, C64DTV-specific
@subsection LumaFix

The PAL C64DTVs have wrong resistors in the video output circuit,
which causes incorrect luminances. Several hardware solutions
("LumaFixes") have been developed to fix this flaw.

The fixed video output is emulated by selecting "New Luminances".
The unmodified C64DTV video output can be emulated with "Old Luminances".

The default setting is "New Luminances".


@node Userport, Debug, LumaFix, C64DTV-specific
@subsection Userport

The C64DTV userport emulation currently supports three devices:
Hummer ADC, userport joystick and PS/2 mouse.

The joystick that controls either the Hummer ADC or userport joystick
can be selected using the same parameter or menu option.

While using the Hummer ADC, joystick UP and DOWN are mapped to
the Hummer buttons A and B respectively. LEFT and RIGHT set the ADCs
output to 0 and 255. Centering the joystick results in the ADC value of 128.

Currently the Hummer ADC and userport joystick are mutually exclusive.
This means that enabling one disables the other. PS/2 mouse emulation
can be used simultaneously with either Hummer ADC or userport joystick.

@table @code

@findex -hummeradc, +hummeradc
@item -hummeradc
@itemx +hummeradc
Enable/Disable Hummer ADC
(@code{HummerADC=1}, @code{HummerADC=0}).

@findex -ps2mouse, +ps2mouse
@item -ps2mouse
@itemx +ps2mouse
Enable/disable PS/2 mouse on userport
(@code{ps2mouse=1}, @code{ps2mouse=0}).

@end table


@node Debug, Monitor DTV features, Userport, C64DTV-specific
@subsection Debug

Debugging information on Blitter, DMA and Flash can be enabled with command
line parameters. This can be useful for DTV software development.

@table @code

@cindex -dtvblitterlog, +dtvblitterlog
@item -dtvblitterlog
@itemx +dtvblitterlog
Enable or disable DTV Blitter log

@cindex -dtvdmalog, +dtvdmalog
@item -dtvdmalog
@itemx +dtvdmalog
Enable or disable DTV DMA log

@cindex -dtvflashlog, +dtvflashlog
@item -dtvflashlog
@itemx +dtvflashlog
Enable or disable DTV Flash log

@end table


@node Monitor DTV features, , Debug, C64DTV-specific
@subsection Monitor DTV features

Currently the registers A, Y and X are registers R0, R1 and R2 regardless of
the mapping, which can be seen and modified via the registers ACM and XYM.

The monitor can access all 2MB of RAM and 2MB of Flash, but only 64 kB at a time.
The 64kB bank can be selected with "bank ram00".."ram1f" for RAM and
"bank rom00".."rom1f" for Flash.

The "load" command can load large files (>64kB) correctly if the bank is set
to "ramXX", where XX is the starting bank (usually "bank00").

@c @node FIXME
@subsection DTV resources

@table @code

@vindex DtvRevision
@item DtvRevision
Integer specifying the emulated DTV revision.
(2: DTV2, 3: DTV3)

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

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

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

@vindex c64dtvromfilename
@item c64dtvromfilename
String specifying the filename of the DTV Flash ROM image.

@vindex c64dtvromrw
@item c64dtvromrw
Boolean that specifies whether the emulated Flash ROM is writeable.

@vindex FSFlashDir
@item FSFlashDir
String specifying the working directory for the flash file system.

@vindex FlashTrueFS
@item FlashTrueFS
Boolean, enables true hardware flash file system.

@vindex HummerADC
@item HummerADC
Boolean to enable/disable the Hummer ADC emulation.

@vindex ps2mouse
@item ps2mouse
Boolean to enable/disable PS/2 Mouse emulation.

@vindex DtvBlitterLog
@item DtvBlitterLog
Boolean, enables Blitter logging.
@vindex DtvDMALog
@item DtvDMALog
Boolean, enables DMA logging.
@vindex DtvFlashLog
@item DtvFlashLog
Boolean, enables Flash ROM logging.

@vindex MachineVideoStandard
@item MachineVideoStandard
Integer that specifies the video standard of the emulated machine.
(-1: PAL, -2: NTSC)

@end table

@c @node FIXME
@subsection DTV command-line options

@table @code

@findex -model
@item -model <Model>
Set the DTV model
(@code{MachineVideoStandard}, @code{DtvRevision}, @code{HummerADC}).
(v2/v2pal/v2ntsc, v3/v3pal/v3ntsc, hummer)

@findex -pal
@item -pal
Use PAL sync factor
(@code{MachineVideoStandard=-1}).

@findex -ntsc
@item -ntsc
Use NTSC sync factor
(@code{MachineVideoStandard=-2}).

@findex -chargen
@item -chargen <name>
Specify filename of the character generator ROM file
(@code{ChargenName}).

@findex -kernal
@item -kernal <name>
Specify filename of the Kernal ROM file
(@code{KernalName}).

@findex -basic
@item -basic <name>
Specify the filename of the Basic ROM file
(@code{BasicName}).

@end table

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

@node SCPU64-specific, VIC20-specific, C64DTV-specific, Machine-specific features

@section SCPU64-specific commands and settings

@c @node FIXME
@subsection SCPU64 resources

@table @code

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

@vindex SCPU64Name
@item SCPU64Name
String specifying the name of the SCPU64 ROM (default @file{scpu64}).

@vindex MachineVideoStandard
@item MachineVideoStandard
Integer that specifies the video standard of the emulated machine
(-4: PAL-N, -3: Old NTSC, -1: PAL, -2: NTSC).

@vindex IECReset
@item IECReset
Integer specifying if the IEC bus resets when the CPU resets.
(0: No, 1: Yes)

@vindex BurstMod
@item BurstMod
Integer specifying the kind of Burst-Mode modification.
(0: None, 1: CIA-1, 2: CIA-2)

@vindex SIMMSize
@item SIMMSize
Integer specifying the size of the SIMM RAM.
(0, 1, 4, 8, 16)

@vindex JiffySwitch
@item JiffySwitch
Boolean to enable/disable the jiffy switch.

@vindex SpeedSwitch
@item SpeedSwitch
Boolean to enable/disable the speed switch.

@vindex GlueLogic
@item GlueLogic
Integer specifying the type of emulated glue-logic.
(0: discrete, 1: custom IC)

@end table

@c @node FIXME
@subsection SCPU64 command-line options

@table @code

@findex -chargen
@item -chargen <name>
Specify filename of the character generator ROM file
(@code{ChargenName}).

@findex -scpu64
@item -scpu64 <Name>
Specify filename of the SCPU64 ROM file
(@code{SCPU64Name}).

@findex -model
@item -model <Model>
Set the C64 model
(@code{MachineVideoStandard}, @code{CIA1Model}, @code{CIA2Model},
@code{VICIINewLuminances}, @code{IECReset}, @code{ChargenName},
@code{SidEngine}, @code{SidModel}).
(c64/c64c/c64old, ntsc/newntsc/oldntsc, drean, jap, c64gs)

@findex -pal
@item -pal
Use PAL sync factor
(@code{MachineVideoStandard=-1}).

@findex -ntsc
@item -ntsc
Use NTSC sync factor
(@code{MachineVideoStandard=-2}).

@findex -ntscold
@item -ntscold
Use old NTSC sync factor
(@code{MachineVideoStandard=-3}).

@findex -paln
@item -paln
Use PAL-N sync factor
(@code{MachineVideoStandard=-4}).

@findex -iecreset
@item -iecreset <value>
Set IEC reset bahaviour
(@code{IECReset}).
(0: Do not reset with CPU reset, 1: Reset with CPU reset)

@findex -burstmod
@item -burstmod <value>
Set the kind of burst modification. This emulates the fast serial bus connection
as described at @uref{http://www.cs.tut.fi/~albert/Dev/burst/}, with the wire to
the tape port cut
(@code{BurstMod}).
(0: None, 1: CIA-1, 2: CIA-2)

@findex -simmsize
@item -simmsize <number>
Set the size of the SIMM RAM
(@code{SIMMSize}).
(0, 1, 4, 8, 16)

@findex -jiffyswitch, +jiffyswitch
@item -jiffyswitch
@itemx +jiffyswitch
Enable/disable the jiffy swicth
(@code{JiffySwitch=1}, @code{JiffySwitch=0}).

@findex -speedswitch, +speedswitch
@item -speedswitch
@itemx +speedswitch
Enable/disable the speed swicth
(@code{SpeedSwitch=1}, @code{SpeedSwitch=0}).

@findex -gluelogictype
@item -gluelogictype <type>
Set glue logic type
(@code{GlueLogic}).
(0: discrete, 1: 252535-01)

@end table

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

@node VIC20-specific, PLUS4-specific, SCPU64-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.

@c @node FIXME
@subsection VIC20 cartridge settings

@c @node FIXME
@subsubsection VIC20 cartridge resources

@table @code

@vindex CartridgeReset
@item CartridgeReset
Boolean specifying whether the machine should be reset when a cartridge is
changed.

@vindex CartridgeType
@item CartridgeType
Integer specifying the type of cartridge emulated.

The following cartridge types are valid:

@itemize @bullet
@item
    -1: None
@item
     1: Generic
@item
     2: Megacart
@item
     3: Final Expansion
@item
     4: Vic Flash Plugin
@item
     5: IEEE-4888
@item
     6: SIDCart
@item
0x8000: Auto Detect
@item
0x8002: 4KB at $2000-$2FFF
@item
0x8003: 8KB at $2000-$3FFF
@item
0x8004: 4KB at $6000-$6FFF
@item
0x8005: 8KB at $6000-$7FFF
@item
0x8006: 4KB at $A000-$AFFF
@item
0x8007: 8KB at $A000-$BFFF
@item
0x8008: 4KB at $B000-$BFFF
@item
0x8009: 8KB at $4000-$5FFF
@item
0x800A: 4KB at $4000-$4FFF
@item
0x8013: 16KB at $2000-$5FFF
@item
0x8015: 16KB at $6000-$9FFF
@item
0x8019: 16KB at $4000-$7FFF
@end itemize

@vindex CartridgeFile
@item CartridgeFile
String specifying the filename of the image for the current cartridge.

@vindex IOCollisionHandling
@item IOCollisionHandling
Integer specifying the way the I/O collisions should be handled.
(0: error message and detach all involved carts,
1: error message and detach last attached involved carts,
2: warning in log and 'AND' the valid return values)

@vindex GenericCartridgeFile2000
@vindex GenericCartridgeFile4000
@vindex GenericCartridgeFile6000
@vindex GenericCartridgeFileA000
@vindex GenericCartridgeFileB000
@item GenericCartridgeFile2000
@itemx GenericCartridgeFile4000
@itemx GenericCartridgeFile6000
@itemx GenericCartridgeFileA000
@itemx GenericCartridgeFileB000
Strings specifying the name of the respective cartridge ROM images.

@vindex FinalExpansionWriteBack
@item FinalExpansionWriteBack
Boolean, if true write back the Flash ROM image file automatically, incase the
contents changed, when detaching or quitting the emulator.

@vindex VicFlashPluginWriteBack
@item VicFlashPluginWriteBack
Boolean, if true write back the Flash ROM image file automatically, incase the
contents changed, when detaching or quitting the emulator.

@vindex MegaCartNvRAMfilename
@item MegaCartNvRAMfilename
String specifying the filename of the MegaCart NvRAM image.

@vindex MegaCartNvRAMWriteBack
@item MegaCartNvRAMWriteBack
Boolean, if true write back the NvRAM image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.

@vindex TFEIOSwap
@item TFEIOSwap
Boolean, swap/don't swap io mapping (map cart I/O to VIC20 I/O-2)

@vindex SFXSoundExpander
@item SFXSoundExpander
Boolean specifying whether the SFX Sound Expander should be emulated or not.

@vindex SFXSoundExpanderChip
@item SFXSoundExpanderChip
Integer specifying which YM chip is emulated.
(3526, 3812)

@vindex SFXSoundExpanderIOSwap
@item SFXSoundExpanderIOSwap
Boolean, swap io mapping (map cart I/O to VIC20 I/O-2) or don't swap io mapping (map cart I/O to VIC20 I/O-3).

@vindex SFXSoundSampler
@item SFXSoundSampler
Boolean specifying whether the SFX Sound Sampler should be emulated or not.

@vindex SFXSoundSamplerIOSwap
@item SFXSoundSamplerIOSwap
Boolean, swap io mapping (map cart I/O to VIC20 I/O-2) or don't swap io mapping (map cart I/O to VIC20 I/O-3).

@vindex GEORAMfilename
@item GEORAMfilename
String specifying the filename of the GEORAM image.

@vindex GEORAM
@item GEORAM
Boolean specifying whether the GEO-RAM cartridge (using the MasC=uerade cartridge adapter) should be emulated or not.

@vindex GEORAMsize
@item GEORAMsize
Integer specifying the size of the emulated GEO-RAM in KB.
(64, 128, 256, 512, 1024, 2048, 4096).

@vindex GEORAMImageWrite
@item GEORAMImageWrite
Boolean, if true write back the GEO-RAM image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.

@vindex GEORAMIOSwap
@item GEORAMIOSwap
Boolean specifying whether the io mapping should be swapped
(map cart I/O-1 to VIC20 I/O-3 and cart I/O-2 to VIC20 I/O-2)
or not
(map cart I/O-2 to VIC20 I/O-2 and cart I/O-2 to VIC20 I/O-3).

@vindex SidCart
@item SidCart
Boolean specifying whether SID-Cart emulation is enabled or not.

@vindex SidAddress
@item SidAddress
Integer that specifies the base address of the emulated SID chip.
(0x9800, 0x9C00)

@vindex SidClock
@item SidClock
Integer specifying the clock rate used for the emulated SID chip
(0: C64, 1: VIC20)

@vindex DIGIMAX
@item DIGIMAX
Boolean specifying whether the DigiMAX cartridge (using the MasC=uerade cartridge adapter) should be emulated or not.

@vindex DIGIMAXbase
@item DIGIMAXbase
Integer specifying the DigiMAX base address.
(0x9800, 0x9820, 0x9840, 0x9860, 0x9880, 0x98A0, 0x98C0, 0x98E0,
0x9C00, 0x9C20, 0x9C40, 0x9C60, 0x9C80, 0x9CA0, 0x9CC0, 0x9CE0)

@vindex DS12C887RTC
@item DS12C887RTC
Boolean specifying whether the DS12C887 RTC cartridge (using the MasC=uerade cartridge adapter) should be emulated or not.

@vindex DS12C887RTCbase
@item DS12C887RTCbase
Integer specifying the DS12C887 RTC base address.
(0x9800, 0x9C00)

@vindex DS12C887RTCRunMode
@item DS12C887RTCRunMode
Boolean specifying whether the DS12C887 RTC cartridge starts out running or halted.
(0: halted, 1: running)

@vindex DS12C887RTCSave
@item DS12C887RTCSave
Boolean specifying whether the DS12C887 RTC data should be saved when changed or not.

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

@vindex MachineVideoStandard
@item MachineVideoStandard
Integer that specifies the video standard of the emulated machine
(-1: PAL, -2: NTSC).

@end table

@c @node FIXME
@subsubsection VIC20 cartridge command-line options

@table @code

@findex -iocollision
@item -iocollision <method>
Select the way the I/O collisions should be handled
(@code{IOCollisionHandling}).
(0: error message and detach all involved carts,
1: error message and detach last attached involved carts,
2: warning in log and 'AND' the valid return values

@findex -cartreset, +cartreset
@item -cartreset
@itemx +cartreset
Do/don't reset machine if a cartridge is attached or detached
(@code{CartridgeReset=1}, @code{CartridgeReset}).

@cindex -cart2
@item -cart2 <name>
Specify 4/8/16K extension ROM name at $2000
@cindex -cart4
@item -cart4 <name>
Specify 4/8/16K extension ROM name at $4000
@cindex -cart6
@item -cart6 <name>
Specify 4/8/16K extension ROM name at $6000
@cindex -cartA
@item -cartA <name>
Specify 4/8K extension ROM name at $A000
@cindex -cartB
@item -cartB <name>
Specify 4K extension ROM name at $B000
@cindex -cartgeneric
@item -cartgeneric <name>
Specify generic extension ROM name

@cindex -cartmega
@item -cartmega <name>
Specify Mega-Cart extension ROM name

@findex -mcnvramfile
@item -mcnvramfile <name>
Set Mega-Cart NvRAM filename
(@code{MegaCartNvRAMfilename}).

@findex -mcnvramwriteback, +mcnvramwriteback
@item -mcnvramwriteback
@itemx +mcnvramwriteback
Enable/Disable Mega-Cart NvRAM writeback
(@code{MegaCartNvRAMWriteBack=1}, @code{MegaCartNvRAMWriteBack=0}).

@cindex -cartfe
@item -cartfe <name>
Specify Final Expansion extension ROM name

@findex -fewriteback, +fewriteback
@item -fewriteback
@itemx +fewriteback
Enable/disable Final Expansion write back to ROM file
(@code{FinalExpansionWriteBack=1}, @code{FinalExpansionWriteBack=0}).

@cindex -cartfp
@item -cartfp <name>
Specify Vic Flash Plugin extension ROM name

@findex -fpwriteback, +fpwriteback
@item -fpwriteback
@itemx +fpwriteback
Enable/Disable Vic Flash Plugin write back to ROM file
(@code{VicFlashPluginWriteBack=1}, @code{VicFlashPluginWriteBack=0}).

@findex -ieee488, +ieee488
@item -ieee488
@itemx +ieee488
Enable/disable VIC-1112 IEEE488 interface
(@code{IEEE488=1}, @code{IEEE488=0}).

@findex -sidcart, +sidcart
@item -sidcart
@item +sidcart
Enable/disable SID Cartridge
(@code{SidCart=1}, @code{SidCart=0}).

@findex -sidcartaddress
@item -sidcartaddress <address>
Specify address of the SID Cartridge
(@code{SidAddress}).
(0x9800, 0x9C00)

@findex -sidcartclock
@item -sidcartclock <clock>
Specify clock of the SID Cartridge
(@code{SidClock}).
(0: C64, 1: VIC20)

@cindex -tfeioswap, +tfeioswap
@item -tfeioswap
@itemx +tfeioswap
Swap/don't swap io mapping (map cart I/O to VIC20 I/O-2)
@cindex -tfe, +tfe
@item -tfe
@itemx +tfe
Enable/Disable the TFE ("The Final Ethernet") unit
@cindex -tfeif
@item -tfeif <name>
Set the system ethernet interface for TFE emulation
@cindex -tferrnet, +tferrnet
@item -tferrnet
@itemx +tferrnet
Enable/Disable RRNet mode of TFE emulation

@findex -digimax, +digimax
@item -digimax
@itemx +digimax
Enable/disable the DigiMAX cartridge (using the MasC=uerade cartridge adapter)
(@code{DIGIMAX=1}, @code{DIGIMAX=0}).

@findex -digimaxbase
@item -digimaxbase <base address>
Base address of the DigiMAX cartridge
(@code{DIGIMAXbase}).
(0x9800, 0x9820, 0x9840, 0x9860, 0x9880, 0x98A0, 0x98C0, 0x98E0,
0x9C00, 0x9C20, 0x9C40, 0x9C60, 0x9C80, 0x9CA0, 0x9CC0, 0x9CE0)

@findex -ds12c887rtc, +ds12c887rtc
@item -ds12c887rtc
@itemx +ds12c887rtc
Enable/disable the DS12C887 RTC cartridge (using the MasC=uerade cartridge adapter)
(@code{DS12C887RTC=1}, @code{DS12C887RTC=0}).

@findex -ds12c887rtcbase
@item -ds12c887rtcbase <base address>
Base address of the DS12C887 RTC cartridge
(@code{DS12C887RTCbase}).
(0x9800, 0x9C00)

@findex -ds12c887rtchalted, -ds12c887rtcrunning
@item -ds12c887rtchalted
Set the DS12C887 RTC oscillator to 'halted'
(@code{DS12C887RTCRunMode=0}).
@item +ds12c887rtcrunning
Set the DS12C887 RTC oscillator to 'running'
(@code{DS12C887RTCRunMode=1}).

@findex -ds12c887rtcsave, +ds12c887rtcsave
@item -ds12c887rtcsave
@itemx +ds12c887rtcsave
Enable/disable saving of the DS12C887 RTC data when changed
(@code{DS12C887RTCSave=1}, @code{DS12C887RTCSave=0}).

@findex -sfxse, +sfxse
@item -sfxse
@itemx +sfxse
Enable/disable the SFX soundexpander cartridge (using the MasC=uerade cartridge adapter)
(@code{SFXSoundExpander=1}, @code{SFXSoundExpander=0}).

@findex -sfxsetype
@item -sfxsetype <type>
Set YM chip type
(@code{SFXSoundExpanderChip}).
(3526, 3812)

@findex -sfxseioswap, +sfxseioswap
@item -sfxseioswap
Swap io mapping (map cart I/O to VIC20 I/O-2)
(@code{SFXSoundExpanderIOSwap=1}).
@item +sfxseioswap
Swap io mapping (map cart I/O to VIC20 I/O-3)
(@code{SFXSoundExpanderIOSwap=0}).

@findex -sfxssioswap, +sfxssioswap
@item -sfxssioswap
Swap io mapping (map cart I/O to VIC20 I/O-2)
(@code{SFXSoundSamplerIOSwap=1}).
@item +sfxssioswap
Don't swap io mapping (map cart I/O to VIC20 I/O-3)
(@code{SFXSoundSamplerIOSwap=0}).

@findex -sfxss, +sfxss
@item -sfxss
@itemx +sfxss
Enable/disable the SFX Sound Sampler cartridge
(@code{SFXSoundSampler=1}, @code{SFXSoundSampler=0}).

@findex -georamioswap, +georamioswap
@item -georamioswap
Swap the io mapping (map cart I/O-1 to VIC20 I/O-3 and cart I/O-2 to VIC20 I/O-2)
(@code{GEORAMIOSwap=1}).
@item +georamioswap
Do not swap the io mapping (map cart I/O-2 to VIC20 I/O-2 and cart I/O-2 to VIC20 I/O-3)
(@code{GEORAMIOSwap=0}).

@findex -georam, +georam
@item -georam
@itemx +georam
Enable/disable the GEORAM expansion unit (using the MasC=uerade cartridge adapter)
(@code{GEORAM=1}, @code{GEORAM=0}).

@findex -georamimage
@item -georamimage <name>
Specify name of GEORAM image
(@code{GEORAMfilename}).

@findex -georamimagerw, +georamimagerw
@item -georamimagerw
@itemx +georamimagerw
Allow/disallow writing to GEORAM image
(@code{GEORAMImageWrite=1}, @code{GEORAMImageWrite=0}).

@findex -georamsize
@item -georamsize <size in KB>
Size of the GEORAM expansion unit
(@code{GEORAMsize}).
(64, 128, 256, 512, 1024, 2048, 4096)

@findex -model
@item -model <model>
Specify the VIC20 model you want to emulate
(@code{MachineVideoStandard}, @code{RamBlock0}, @code{RamBlock1}, @code{RamBlock2}, @code{RamBlock3} and @code{RamBlock5}).
(vic20/vic20pal/vic20ntsc, vic21)

@findex -pal
@item -pal
Use PAL sync factor
(@code{MachineVideoStandard=-1}).

@findex -ntsc
@item -ntsc
Use NTSC sync factor
(@code{MachineVideoStandard=-2}).

@end table

@c @node FIXME
@subsection VIC settings

@c @node FIXME
@subsubsection VIC resources

@table @code

@vindex VICVideoCache
@item VICVideoCache
Boolean specifying whether the video cache is turned on.

@vindex VICDoubleSize
@item VICDoubleSize
Boolean specifying whether double-size mode is turned on.

@vindex VICDoubleScan
@item VICDoubleScan
Boolean specifying whether double-scan mode is turned on.

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

@vindex VICExternalPalette
@item VICExternalPalette
Boolean specifying whether to use external palette file or not.

@vindex VICColorSaturation
@item VICColorSaturation
Integer specifying saturation of internal calculated palette.
(0..2000)

@vindex VICColorContrast
@item VICColorContrast
Integer specifying contrast of internal calculated palette,
(0..2000)

@vindex VICColorBrightness
@item VICColorBrightness
Integer specifying brightness of internal calculated palette.
(0..2000)

@vindex VICColorGamma
@item VICColorGamma
Integer specifying gamma of internal calculated palette.
(0..4000)

@vindex VICColorTint
@item VICColorTint
Integer specifying tint of internal calculated palette.
(0..2000)

@vindex VICPALScanLineShade
@item VICPALScanLineShade
Integer specifying amount of scan line shading for the CRT emulation.
(0..1000)

@vindex VICPALBlur
@item VICPALBlur
Integer specifying amount of horizontal blur for the CRT emulation.
(0..1000)

@vindex VICPALOddLinePhase
@item VICPALOddLinePhase
Integer specifying phase for color carrier in odd lines.
(0..2000)

@vindex VICPALOddLineOffset
@item VICPALOddLineOffset
Integer specifying phase offset for color carrier in odd lines.
(0..2000)

@vindex VICAudioLeak
@item VICAudioLeak
Boolean specifying whether to enable/disable video to audio leak emulation.

@vindex VICFilter
@item VICFilter
Integer specifying the rendering filter.
(0: None, 1: CRT emulation, 2: Scale2x)

@vindex VICBorderMode
@item VICBorderMode
Integer specifying border display mode
(0: normal, 1: full, 2: debug, 3: none)

@end table

@c @node FIXME
@subsubsection VIC command-line options

@table @code

@findex -VICvcache, +VICvcache
@item -VICvcache
@itemx +VICvcache
Enable/disable the video cache
(@code{VICVideoCache=1}, @code{VICVideoCache=0}).

@findex -VICdsize, +VICdsize
@item -VICdsize
@itemx +VICdsize
Enable/disable the double size mode
(@code{VICDoubleSize=1}, @code{VICDoubleSize=0}).

@findex -VICdscan, +VICdscan
@item -VICdscan
@itemx +VICdscan
Enable/disable the double scan mode
(@code{VICDoubleScan=1}, @code{VICDoubleScan=0}).

@findex -VICfilter
@item -VICfilter <Mode>
Select rendering filter
(@code{VICFilter}).
(0: None, 1: CRT emulation, 2: Scale2x)

@findex -VICpalette
@item -VICpalette NAME
Specify the name of the palette file
(@code{VICPaletteFile}).

@findex -VICintpal
@item -VICintpal
Use an internal calculated palette
(@code{VICExternalPalette=0}).

@findex -VICextpal
@item -VICextpal
Use an external palette (file)
(@code{VICExternalPalette=1}).

@cindex -VICXRANDRfullmode
@item -VICXRANDRfullmode <mode>
Select fullscreen mode
@cindex -VICVidmodefullmode
@item -VICVidmodefullmode <mode>
Select fullscreen mode

@findex -VICborders
@item -VICborders <mode>
Set VIC border display mode
(@code{VICBorderMode}).
(0: normal, 1: full, 2: debug, 3: none)

@findex -VICsaturation
@item -VICsaturation <0-2000>
Set saturation of internal calculated palette
(@code{VICColorSaturation}).

@findex -VICcontrast
@item -VICcontrast <0-2000>
Set contrast of internal calculated palette
(@code{VICColorContrast}).

@findex -VICbrightness
@item -VICbrightness <0-2000>
Set brightness of internal calculated palette
(@code{VICColorBrightness}).

@findex -VICgamma
@item -VICgamma <0-4000>
Set gamma of internal calculated palette
(@code{VICColorGamma}).

@findex -VICtint
@item -VICtint <0-2000>
Set tint of internal calculated palette
(@code{VICColorTint}).

@findex -VICoddlinesphase
@item -VICoddlinesphase <0-2000>
Set phase for color carrier in odd lines
(@code{VICPALOddLinePhase}).

@findex -VICoddlinesoffset
@item -VICoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines.
(@code{VICPALOddLineOffset}).

@findex -VICcrtblur
@item -VICcrtblur <0-1000>
Amount of horizontal blur for the CRT emulation
(@code{VICPALBlur}).

@findex -VICcrtscanlineshade
@item -VICcrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation
(@code{VICPALScanLineShade}).

@findex -VICaudioleak, +VICaudioleak
@item -VICaudioleak
@item +VICaudioleak
Enable/disable video to audio leak emulation
(@code{VICAudioLeak=1}, @code{VICAudioLeak=0}).

@end table


@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

@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
@vindex RAMBlock1
@vindex RAMBlock2
@vindex RAMBlock3
@vindex RAMBlock5
@item RAMBlock0
@itemx RAMBlock1
@itemx RAMBlock2
@itemx RAMBlock3
@itemx RAMBlock5
Booleans specifying whether RAM blocks 0, 1, 2, 3 and 5 must be enabled.

@end table

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

@table @code

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

@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

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

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

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

@end table

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

@table @code

@findex -kernal
@item -kernal <name>
Specify the filename of the Kernal ROM file
(@code{KernalName}).

@findex -basic
@item -basic <name>
Specify the filename of the Basic ROM file
(@code{BasicName}).

@findex -chargen
@item -chargen <name>
Specify the filename of 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}, @dots{}, @code{CartridgeFileB000}).

@end table

@c @node FIXME
@subsection VIC20 settings

@c @node FIXME
@subsubsection VIC20 command-line options

@table @code


@end table

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

@node PLUS4-specific, PET-specific, VIC20-specific, Machine-specific features
@section PLUS4-specific commands and settings

@c @node FIXME
@subsection TED settings

@c @node FIXME
@subsubsection TED resources

@table @code
@vindex TEDVideoCache
@item TEDVideoCache
Boolean specifying whether the video cache is turned on.

@vindex TEDDoubleSize
@item TEDDoubleSize
Boolean specifying whether double-size mode is turned on.

@vindex TEDDoubleScan
@item TEDDoubleScan
Boolean specifying whether double-scan mode is turned on.

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

@vindex TEDExternalPalette
@item TEDExternalPalette
Boolean specifying whether to use external palette file or not.

@vindex TEDColorSaturation
@item TEDColorSaturation
Integer specifying saturation of internal calculated palette.
(0..2000)

@vindex TEDColorContrast
@item TEDColorContrast
Integer specifying contrast of internal calculated palette.
(0..2000)

@vindex TEDColorBrightness
@item TEDColorBrightness
Integer specifying brightness of internal calculated palette.
(0..2000)

@vindex TEDColorGamma
@item TEDColorGamma
Integer specifying gamma of internal calculated palette.
(0..4000)

@vindex TEDColorTint
@item TEDColorTint
Integer specifying tint of internal calculated palette.
(0..2000)

@vindex TEDPALScanLineShade
@item TEDPALScanLineShade
Integer specifying amount of scan line shading for the CRT emulation.
(0..1000)

@vindex TEDPALBlur
@item TEDPALBlur
Integer specifying amount of horizontal blur for the CRT emulation.
(0..1000)

@vindex TEDPALOddLinePhase
@item TEDPALOddLinePhase
Integer specifying phase for color carrier in odd lines.
(0..2000)

@vindex TEDPALOddLineOffset
@item TEDPALOddLineOffset
Integer specifying phase offset for color carrier in odd lines.
(0..2000)

@vindex TEDAudioLeak
@item TEDAudioLeak
Boolean specifying whether to enable/disable video to audio leak emulation.

@vindex TEDFilter
@item TEDFilter
Integer specifying rendering filter.
(0: None, 1: CRT emulation, 2: Scale2x)

@vindex TEDBorderMode
@item TEDBorderMode
Integer specifying border display mode.
(0: normal, 1: full, 2: debug, 3: none)

@end table

@c @node FIXME
@subsubsection TED command-line options

@table @code
@findex -TEDvcache, +TEDvcache
@item -TEDvcache
@itemx +TEDvcache
Enable/disable the video cache
(@code{TEDVideoCache=1}, @code{TEDVideoCache=0}).

@findex -TEDdsize, +TEDdsize
@item -TEDdsize
@itemx +TEDdsize
Enable/disable double size
(@code{TEDDoubleSize=1}, @code{TEDDoubleSize=0}).

@findex -TEDdscan, +TEDdscan
@item -TEDdscan
@itemx +TEDdscan
Enable/disable double scan
(@code{TEDDoubleScan=1}, @code{TEDDoubleScan=0}).

@findex -TEDfilter
@item -TEDfilter <Mode>
Select rendering filter
(@code{TEDFilter}).
(0: None, 1: CRT emulation, 2: Scale2x)

@findex -TEDintpal
@item -TEDintpal
Use an internal calculated palette
(@code{TEDExternalPalette=0}).

@findex -TEDextpal
@item -TEDextpal
Use an external palette (file)
(@code{TEDExternalPalette=1}).

@findex -TEDpalette
@item -TEDpalette <name>
Specify name of the external palette file
(@code{TEDPaletteFile}).

@cindex -TEDXRANDRfullmode
@item -TEDXRANDRfullmode <mode>
Select fullscreen mode
@cindex -TEDVidmodefullmode
@item -TEDVidmodefullmode <mode>
Select fullscreen mode

@findex -TEDborders
@item -TEDborders <mode>
Set TED border display mode
(@code{TEDBorderMode}).
(0: normal, 1: full, 2: debug, 3: none)

@findex -TEDsaturation
@item -TEDsaturation <0-2000>
Set saturation of internal calculated palette
(@code{TEDColorSaturation}).

@findex -TEDcontrast
@item -TEDcontrast <0-2000>
Set contrast of internal calculated palette
(@code{TEDColorContrast}).

@findex -TEDbrightness
@item -TEDbrightness <0-2000>
Set brightness of internal calculated palette
(@code{TEDColorBrightness}).

@findex -TEDgamma
@item -TEDgamma <0-4000>
Set gamma of internal calculated palette
(@code{TEDColorGamma}).

@findex -TEDtint
@item -TEDtint <0-2000>
Set tint of internal calculated palette
(@code{TEDColorTint}).

@findex -TEDoddlinesphase
@item -TEDoddlinesphase <0-2000>
Set phase for color carrier in odd lines
(@code{TEDPALOddLinePhase}).

@findex -TEDoddlinesoffset
@item -TEDoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines
(@code{TEDPALOddLineOffset}).

@findex -TEDcrtblur
@item -TEDcrtblur <0-1000>
Amount of horizontal blur for the CRT emulation
(@code{TEDPALBlur}).

@findex -TEDcrtscanlineshade
@item -TEDcrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation
(@code{TEDPALScanLineShade}).

@findex -TEDaudioleak, +TEDaudioleak
@item -TEDaudioleak
@item +TEDaudioleak
Enable/disable video to audio leak emulation
(@code{TEDAudioLeak=1}, @code{TEDAudioLeak=0}).

@end table

@c @node FIXME
@subsection PLUS4 I/O extension settings

@c @node FIXME
@subsubsection PLUS4 I/O extension resources

@table @code

@vindex CartridgeReset
@item CartridgeReset
Boolean specifying whether the machine should be reset when a cartridge is changed.

@vindex DIGIBLASTER
@item DIGIBLASTER
Boolean to enable/disable the Digiblaster emulation.

@vindex SpeechEnabled
@item SpeechEnabled
Boolean to enable/disable the emulation of the V364 speech chip.

@vindex SpeechImage
@item SpeechImage
String specifying the filename of the speech ROM image.

@vindex SidCart
@item SidCart
Boolean specifying whether SID-Cart emulation is enabled or not.

@vindex SidAddress
@item SidAddress
Integer that specifies the base address of the emulated SID chip.
(0xFD40, 0xFE80)

@vindex SidClock
@item SidClock
Integer specifying the clock rate used for the emulated SID chip
(0: C64, 1: Plus4)

@vindex SIDCartJoy
@item SIDCartJoy
Boolean to enable/disable the emulation of the SID-Cart joystick.

@end table

@c @node FIXME
@subsubsection PLUS4 I/O extension command-line options

@table @code

@findex -cartreset, +cartreset
@item -cartreset
@itemx +cartreset
Do/don't reset machine if a cartridge is attached or detached
(@code{CartridgeReset=1}, @code{CartridgeReset}).

@cindex -cart
@item -cart <Name>
Smart-attach cartridge image
@cindex +cart
@item +cart
Disable default cartridge

@findex -digiblaster, +digiblaster
@item -digiblaster
@itemx +digiblaster
Enable/disable the digiblaster add-on
(@code{DIGIBLASTER=1}, @code{DIGIBLASTER=0}).

@findex -sidcart, +sidcart
@item -sidcart
@item +sidcart
Enable/disable SID Cartridge
(@code{SidCart=1}, @code{SidCart=0}).

@findex -sidcartjoy, +sidcartjoy
@item -sidcartjoy
@item +sidcartjoy
Enable/disable SID cartridge joystick
(@code{SIDCartJoy=1}, @code{SIDCartJoy=0}).

@findex -sidcartaddress
@item -sidcartaddress <address>
Specify address of the SID Cartridge
(@code{SidAddress}).
(0xFD40, 0xFE80)

@findex -sidcartclock
@item -sidcartclock <clock>
Specify clock of the SID Cartridge
(@code{SidClock}).
(0: C64, 1: Plus4)

@findex -speech, +speech
@item -speech
@itemx +speech
Enable/Disable the v364 speech add-on
(@code{SpeechEnabled=1}, @code{SpeechEnabled=0}).

@findex -speechrom
@item -speechrom <name>
Attach Speech ROM image
(@code{SpeechImage}, @code{SpeechEnabled}).

@end table

@c @node FIXME
@subsection PLUS4 system ROM settings

@c @node FIXME
@subsubsection PLUS4 system ROM resources

@table @code

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

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

@vindex FunctionLowName
@item FunctionLowName
String specifying the filename of the Lo Function ROM.

@vindex FunctionHighName
@item FunctionHighName
String specifying the filename of the High Function ROM.

@vindex c1loName
@item c1loName
String specifying the filename of cartridge 1 Lo ROM.

@vindex c1hiName
@item c1hiName
String specifying the filename of cartridge 1 High ROM.

@vindex c2loName
@item c2loName
String specifying the filename of cartridge 2 Lo ROM.

@vindex c2hiName
@item c2hiName
String specifying the filename of cartridge 2 High ROM.

@end table

@c @node FIXME
@subsubsection PLUS4 system ROM command-line options

@table @code

@findex -kernal <Name>
@item -kernal <Name>
Specify name of the Kernal ROM image
(@code{KernalName}).

@findex -basic <Name>
@item -basic <Name>
Specify name of the BASIC ROM image
(@code{BasicName}).

@findex -functionlo
@item -functionlo <name>
Specify name of Function low ROM image
(@code{FunctionLowName}).

@findex -functionhi
@item -functionhi <name>
Specify name of Function high ROM image
(@code{FunctionHighName}).

@findex -c1lo
@item -c1lo <name>
Specify name of Cartridge 1 low ROM image
(@code{c1loName}).

@findex -c1hi
@item -c1hi <name>
Specify name of Cartridge 1 high ROM image
(@code{c1HiName}).

@findex -c2lo
@item -c2lo <name>
Specify name of Cartridge 2 low ROM image
(@code{c2loName}).

@findex -c2hi
@item -c2hi <name>
Specify name of Cartridge 2 high ROM image
(@code{c2HiName}).

@end table

@c @node FIXME
@subsection PLUS4 settings

@c @node FIXME
@subsubsection PLUS4 resources

@table @code

@vindex MachineVideoStandard
@item MachineVideoStandard
Integer that specifies the video standard of the emulated machine
(-1: PAL, -2: NTSC).

@vindex RamSize
@item RamSize
Integer specifying the size of the memory in kByte.
(16, 32, 64)

@vindex MemoryHack
@item MemoryHack
Integer specifying what memory expansion hack is active.
(0: None, 1: C256K, 2: H256K, 3: H1024K, 4: H4096K)

@vindex Acia1Enable
@item Acia1Enable
Boolean specifying whether the ACIA should be emulated or not.

@end table

@c @node FIXME
@subsubsection PLUS4 command-line options

@table @code

@findex -model
@item -model <model>
Specify the PLUS4 model you want to emulate
(@code{MachineVideoStandard}, @code{RamSize}, @code{KernalName},
@code{BasicName}, @code{FunctionLowName}, @code{FunctionHighName},
@code{Acia1Enable}, @code{SpeechImage}, @code{SpeechEnabled}).
(c16/c16pal/c16ntsc, plus4/plus4pal/plus4ntsc, v364/cv364, c232)

@findex -pal
@item -pal
Use PAL sync factor
(@code{MachineVideoStandard=-1}).

@findex -ntsc
@item -ntsc
Use NTSC sync factor
(@code{MachineVideoStandard=-2}).

@findex -ramsize
@item -ramsize <ramsize>
Specify size of RAM installed in kb
(@code{RamSize}).
(16, 32, 64)

@findex -memoryexphack
@item -memoryexphack <device>
Set active memory expansion hack
(@code{MemoryHack}).
(0: None, 1: C256K, 2: H256K, 3: H1024K, 4: H4096K)

@cindex -acia, +acia
@item -acia
@itemx +acia
Enable/Disable the ACIA emulation

@end table

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

@node PET-specific, CBM-II-specific, PLUS4-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 settings::
* Colour PET::
* PET colors::
* PET DWW high resolution grapics::
* PET HRE (HiRes Emulator) high resolution grapics::
@end menu

@node PET model
@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

@vindex RamSize
@item RamSize
Integer specifying the size of the memory in kByte. 96k denotes a 8096, 128k a 8296.
(4, 8, 16, 32, 96, 128)

@vindex IOSize
@item IOSize
Integer specifying the size of the I/O area in Bytes for the 8296 model.
(256, 2048)

@vindex VideoSize
@item VideoSize
Integer specifying the number of columns on the screen.
(0: Automatic from ROM, 40: 40 columns, 80: 80 columns)

@vindex Ram9
@item Ram9
Boolean specifying if the 8296 can map RAM into the address range $9*** or not.

@vindex RamA
@item RamA
Boolean specifying if the 8296 can map RAM into the address range $A*** or not.

@vindex SuperPET
@item SuperPET
Boolean that enables/disables the SuperPET (MicroMainFrame 9000) I/O and 6809 CPU,
and disables/enables the 8x96 mappings.

@vindex Basic1
@item Basic1
Boolean to enable/disable the patching of a version 1 kernal ROM to make the IEEE488 interface work.

@vindex Basic1Chars
@item Basic1Chars
Boolean to enable/disable the exchanges of some characters in the character ROM
that have changed between the first PET 2001 and all newer versions.

@vindex EoiBlank
@item EoiBlank
Boolean to enable/disable the "blank screen on EOI" feature of the oldest PET 2001.

@vindex DiagPin
@item DiagPin
Boolean to enable/disable the diagnostic pin on the PET userport (see below).

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

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

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

@vindex EditorName
@item EditorName
String specifying the filename of the editor ROM file. This file contains
an overlay for the editor ROM at $E000-$E7FF if necessary.

@vindex RomModule9Name
@item RomModule9Name
String specifying the filename for the $9*** Expansion ROM file. This file contains
an expansion ROM image of 4k.

@vindex RomModuleAName
@item RomModuleAName
String specifying the filename for the $A*** Expansion ROM file. This file contains
an expansion ROM image of 4k.

@vindex RomModuleBName
@item RomModuleBName
String specifying the filename for 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.

@c @node FIXME
@subsection CRTC Settings

@c @node FIXME
@subsubsection CRTC resources

@table @code

@vindex Crtc
@item Crtc
Boolean specifying whether to enable/disable CRTC 6545 emulation (all models from 40xx and above).

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

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

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

@vindex CrtcStretchVertical
@item CrtcStretchVertical
Boolean specifying whether vertical stretching is turned on.

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

@vindex CrtcExternalPalette
@item CrtcExternalPalette
Boolean specifying whether to use external palette file or not.

@vindex CrtcColorSaturation
@item CrtcColorSaturation
Integer specifying saturation of internal calculated palette.
(0..2000)

@vindex CrtcColorContrast
@item CrtcColorContrast
Integer specifying contrast of internal calculated palette.
(0..2000)

@vindex CrtcColorBrightness
@item CrtcColorBrightness
Integer specifying brightness of internal calculated palette.
(0..2000)

@vindex CrtcColorGamma
@item CrtcColorGamma
Integer specifying gamma of internal calculated palette.
(0..4000)

@vindex CrtcColorTint
@item CrtcColorTint
Integer specifying tint of internal calculated palette.
(0..2000)

@vindex CrtcPALScanLineShade
@item CrtcPALScanLineShade
Integer specifying amount of scan line shading for the CRT emulation.
(0..1000)

@vindex CrtcPALBlur
@item CrtcPALBlur
Integer specifying amount of horizontal blur for the CRT emulation.
(0..1000)

@vindex CrtcPALOddLinePhase
@item CrtcPALOddLinePhase
Integer specifying phase for color carrier in odd lines
(0..2000)

@vindex CrtcPALOddLineOffset
@item CrtcPALOddLineOffset
Integer specifying phase offset for color carrier in odd lines.
(0..2000)

@vindex CrtcAudioLeak
@item CrtcAudioLeak
Boolean specifying whether to enable/disable video to audio leak emulation.

@vindex CrtcFilter
@item CrtcFilter
Integer specifying rendering filter.
(0: None, 2: CRT emulation, 3: Scale2x)

@end table

@c @node FIXME
@subsubsection CRTC command-line options

@table @code

@findex -crtc, +crtc
@item -crtc
@itemx +crtc
Enable/disable the 6545 CRTC emulation
(@code{Crtc=1}, @code{Crtc=0}).

@findex -Crtcvcache, +Crtcvcache
@item -Crtcvcache
@itemx +Crtcvcache
Enable/disable the video cache
(@code{CrtcVideoCache=1}, @code{CrtcVideoCache=0}).

@findex -Crtcdsize, +Crtcdsize
@item -Crtcdsize
@itemx +Crtcdsize
Enable/disable double size
(@code{CrtcDoubleSize=1}, @code{CrtcDoubleSize=0}).

@findex -CRTCstretchvertical, +CRTCstretchvertical
@item -CRTCstretchvertical
@itemx +CRTCstretchvertical
Enable/disable vertical stretching
(@code{CrtcStretchVertical=1}, @code{CrtcStretchVertical=0}).

@findex -Crtcdscan, +Crtcdscan
@item -Crtcdscan
@itemx +Crtcdscan
Enable/disable double scan
(@code{CrtcDoubleScan=1}, @code{CrtcDoubleScan=0}).

@findex -Crtcfilter
@item -Crtcfilter <Mode>
Select rendering filter
(@code{CrtcFilter}).
(0: None, 2: CRT emulation, 3: Scale2x)

@findex -Crtcintpal
@item -Crtcintpal
Use an internal calculated palette
(@code{CrtcExternalPalette=0}).

@findex -Crtcextpal
@item -Crtcextpal
Use an external palette (file)
(@code{CrtcExternalPalette=1}).

@findex -Crtcpalette
@item -Crtcpalette <name>
Specify the name of the palette file
(@code{CrtcPaletteFile}).

@cindex -CrtcVidmodefullmode
@item -CrtcVidmodefullmode <mode>
Select fullscreen mode

@findex -Crtcsaturation
@item -Crtcsaturation <0-2000>
Set saturation of internal calculated palette
(@code{CrtcColorSaturation}).

@findex -Crtccontrast
@item -Crtccontrast <0-2000>
Set contrast of internal calculated palette
(@code{CrtcColorContrast}).

@findex -Crtcbrightness
@item -Crtcbrightness <0-2000>
Set brightness of internal calculated palette
(@code{CrtcColorBrightness}).

@findex -Crtcgamma
@item -Crtcgamma <0-4000>
Set gamma of internal calculated palette
(@code{CrtcColorGamma}).

@findex -Crtctint
@item -Crtctint <0-2000>
Set tint of internal calculated palette
(@code{CrtcColorTint}).

@findex -Crtcoddlinesphase
@item -Crtcoddlinesphase <0-2000>
Set phase for color carrier in odd lines
(@code{CrtcPALOddLinePhase}).

@findex -Crtcoddlinesoffset
@item -Crtcoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines
(@code{CrtcPALOddLineOffset}).

@findex -Crtccrtblur
@item -Crtccrtblur <0-1000>
Amount of horizontal blur for the CRT emulation
(@code{CrtcPALBlur}).

@findex -Crtccrtscanlineshade
@item -Crtccrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation
(@code{CrtcPALScanLineShade}).

@findex -Crtcaudioleak, +Crtcaudioleak
@item -Crtcaudioleak
@item +Crtcaudioleak
Enable/disable video to audio leak emulation
(@code{CrtcAudioLeak=1}, @code{CrtcAudioLeak=0}).

@end table

@c @node FIXME
@subsection PET I/O extension settings

@c @node FIXME
@subsubsection PET I/O extension resources

@table @code

@vindex PETREU
@item PETREU
Boolean specifying whether PET REU emulation is enabled or not.

@vindex PETREUfilename
@item PETREUfilename
String specifying the filename of the PET REU image.

@vindex PETREUsize
@item PETREUsize
Integer specifying the size of the emulated PET REU in KB.
(128, 512, 1024, 2048)

@vindex PETDWW
@item PETDWW
Boolean specifying whether DWW emulation is enabled or not.

@vindex PETDWWfilename
@item PETDWWfilename
String specifying the filename of the DWW image RAM image.

@vindex PETHRE
@item PETHRE
Boolean specifying whether HRE emulation is enabled or not.

@vindex PETColour
@item PETColour
Integer selecting the colour extension.
(0: off, 1: RGBI, 2: Analog)

@vindex PETColourBG
@item PETColourBG
Iteger specifying the analog colour background on PET 4032.
(0..255)

@vindex UserportDAC
@item UserportDAC
Boolean specifying whether userport DAC emulation is enabled.

@vindex SidCart
@item SidCart
Boolean specifying whether SID Cart emulation is enabled or not.

@vindex SidAddress
@item SidAddress
Integer that specifies the base address of the emulated SID chip.
(0x8F00, 0xE900)

@vindex SidClock
@item SidClock
Integer specifying the clock rate used for the emulated SID chip.
(0: C64, 1: PET)

@end table

@c @node FIXME
@subsubsection PET I/O extension command-line options

@table @code

@findex -petreu, +petreu
@item -petreu
@itemx +petreu
Enable/disable the PET Memory Expansion Unit
(@code{PETREU=1}, @code{PETREU=0}).

@findex -petreuimage
@item -petreuimage <name>
Specify name of PET Ram and Expansion Unit image
(@code{PETREUfilename}).

@findex -petreuramsize
@item -petreuramsize <size in KB>
Size of the PET Ram and Expansion Unit
(@code{PETREUsize}).
(128, 512, 1024, 2048)

@findex -userportdac, +userportdac
@item -userportdac
@itemx +userportdac
Enable/disable the userport DAC
(@code{UserportDAC=1}, @code{UserportDAC=0}).

@findex -petdww, +petdww
@item -petdww
@itemx +petdww
Enable/disable the PET DWW hi-res board (30xx models only)
(@code{PETDWW=1}, @code{PETDWW=0}).

@findex -petdwwimage
@item -petdwwimage <name>
Specify name of PET DWW RAM image
(@code{PETDWWfilename}).

@findex -pethre, +pethre
@item -pethre
@itemx +pethre
Enable/disable the PET HRE extension (model 8296 only)
(@code{PETHRE=1}, @code{PETHRE=0}).

@findex -colour-rgbi
@item -colour-rgbi
Enable the RGBI colour extension to PET 4032
(@code{PETColour=1}).

@findex -colour-analog
@item -colour-analog
Enable the analog colour extension to PET 4032
(@code{PETColour=2}).

@findex -colour-analog-bg
@item -colour-analog-bg <Colour 0-255>
Select the analog colour background on PET 4032
(@code{PETColourBG}).

@findex -sidcart, +sidcart
@item -sidcart
@itemx +sidcart
Enable/disable the SID Cartridge
(@code{SidCart=1}, @code{SidCart=0}).

@findex -sidcartaddress
@item -sidcartaddress <address>
Specify address of the SID Cartridge
(@code{SidAddress}).
(0x8F00, 0xE900)

@findex -sidcartclock
@item -sidcartclock <clock>
Specify clock of the SID Cartridge
(@code{SidClock}).
(0: C64, 1: PET)

@end table

@c @node FIXME
@subsection PET system ROM settings

@c @node FIXME
@subsubsection PET system ROM resources

@table @code

@vindex H6809RomAName
@vindex H6809RomBName
@vindex H6809RomCName
@vindex H6809RomDName
@vindex H6809RomEName
@vindex H6809RomFName
@item H6809RomAName
@itemx H6809RomBName
@itemx H6809RomCName
@itemx H6809RomDName
@itemx H6809RomEName
@itemx H6809RomFName
Strings specifying the filenames of the respective H6809 ROM images,
relevant for the SuperPET.

@end table

@c @node FIXME
@subsubsection PET system ROM command-line options

@table @code

@findex -kernal
@item -kernal <name>
Specify filename of the Kernal ROM file
(@code{KernalName}).

@findex -basic
@item -basic <name>
Specify filename of the BASIC ROM file
(@code{BasicName}).

@findex -editor
@item -editor NAME
Specify the filename for the editor ROM file
(@code{EditorName}).

@findex -chargen
@item -chargen <name>
Specify filename of the character generator ROM file
(@code{ChargenName}).

@findex -rom9
@item -rom9 <name>
Specify the filename for the ROM image file for the $9***
cartridge area (@code{RomModule9Name}).

@findex -romA
@item -romA <name>
Specify the filename for the ROM image file for the $A***
cartridge area (@code{RomModuleAName}).

@findex -romB
@item -romB <name>
Specify the filename for the ROM image file for the $B***
cartridge area (@code{RomModuleBName}).

@findex -6809romA
@item -6809romA <Name>
Specify 4K to 24K ROM file name at $A000 for 6809
(@code{H6809RomAName}).

@cindex -6809romB
@item -6809romB <Name>
Specify 4K to 20K ROM file name at $B000 for 6809
(@code{H6809RomBName}).

@findex -6809romC
@item -6809romC <Name>
Specify 4K to 16K ROM file name at $C000 for 6809
(@code{H6809RomCName}).

@findex -6809romD
@item -6809romD <Name>
Specify 4K to 12K ROM file name at $D000 for 6809
(@code{H6809RomDName}).

@findex -6809romE
@item -6809romE <Name>
Specify 2K or 8K ROM file name at $E000 for 6809
(@code{H6809RomEName}).

@findex -6809romF
@item -6809romF <Name>
Specify 4K ROM file name at $F000 for 6809
(@code{H6809RomFName}).

@end table

@node PET diagnostic pin
@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 settings
@subsection PET settings

@c @node FIXME
@subsubsection PET resources

@table @code

@vindex MachineVideoStandard
@item MachineVideoStandard
Integer that specifies the video standard of the emulated machine
(-1: PAL, -2: NTSC).

@vindex CPUswitch
@item CPUswitch
Integer specifying the status of the SuperPET CPU switch
(0: 6502, 1: 6809, 2: Prog.)

@end table

@subsubsection PET command line options

These are the commandline options specific for the PET models.

@table @code

@findex -pal
@item -pal
Use PAL sync factor
(@code{MachineVideoStandard=-1}).

@findex -ntsc
@item -ntsc
Use NTSC sync factor
(@code{MachineVideoStandard=-2}).

@findex -model
@item -model <model>
Specify the PET model you want to emulate
(@code{Basic1}, @code{Basic1Chars}, @code{ChargenName}, @code{KernalName},
@code{BasicName}, @code{EditorName}, @code{RomModule9Name}, @code{RomModuleAName},
@code{RomModuleBName}, @code{H6809RomAName}, @code{H6809RomBName}, @code{H6809RomCName},
@code{H6809RomDName}, @code{H6809RomEName}, @code{H6809RomFName}).
(2001, 3008, 3016, 3032, 3032B, 4016, 4032, 4032B, 8032, 8096, 8296, SuperPET)

@findex -iosize
@item -iosize <size>
Specify size of I/O in Bytes
(@code{IOSize}).
(256, 2048)

@findex -ramsize
@item -ramsize <size>
Specify size of RAM in KB
(@code{RamSize}).
(8, 16, 32, 96, 128)

@findex -videosize
@item -videosize <size>
Specify video size
(@code{VideoSize}).
(0: Automatic from ROM, 40: 40 columns, 80: 80 columns)

@findex -petram9, +petram9
@item -petram9
@itemx +petram9
Switch on/off RAM mapping at address $9000-$9FFF
(@code{Ram9=1}, @code{Ram9=0}).

@findex -petramA, +petramA
@item -petramA
@itemx +petramA
Switch on/off RAM mapping at address $A000-$AFFF
(@code{RamA=1}, @code{RamA=0}).

@findex -superpet, +superpet
@item -superpet
@itemx +superpet
Enable/disable SuperPET I/O and CPU emulation
(@code{SuperPET}).

@findex -cpu6502
@item -cpu6502
Set SuperPET CPU switch to '6502'
(@code{CPUswitch=0}).

@findex -cpu6809
@item -cpu6809
Set SuperPET CPU switch to '6809'
(@code{CPUswitch=1}).

@findex -cpuprog
@item -cpuprog
Set SuperPET CPU switch to 'Prog'
(@code{CPUswitch=2}).

@findex -basic1, +basic1
@item -basic1
@itemx +basic1
Enable/disable patching the IEEE488 section of the PET2001 ROM when detected
(@code{Basic1=1}, @code{Basic1=0}).

@findex -basic1char, +basic1char
@item -basic1char
@itemx +basic1char
Enable/disable PET 2001 character generator
(@code{Basic1Chars=1}, @code{Basic1Chars=0}).

@findex -eoiblank, +eoiblank
@item -eoiblank
@itemx +eoiblank
Enable/disable EOI blanking the screen
(@code{EoiBlank=1}, @code{EoiBlank=0}).

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

@end table

@node Colour PET
@subsection Colour PET
The Colour PET is a simple extension by Steve Gray
@uref{http://www.6502.org/users/sjgray/projects/colourpet/}. It exploits
the similarities and differences between the 4032 and 8032 models, to
use memory at $8800 as colour RAM.

There are two versions of the extension:

with digital colour (RGBI), which can select 16 foreground and 16
background colours for each charcter cell. The The 8 colour bits are
used as RGBI RGBI, with the most significant bits for the background,
and the least significant bits for the foreground.

with analog colour, which can use 256 foreground colours for each
character cell. The 8 colour bits are used as RRR GGG BB.

@node PET colors
@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

@node PET DWW high resolution grapics

@subsection DWW high resolution grapics
@cindex DWW
The DWW, or Double-W
@footnote{Dubbel-W bord, designed by Ben de Winter and Pieter
Wolvekamp},
board is a high resolution graphics board for PET models 30xx. It
attaches to the internal expansion connector.  It would not physically
fit in 20xx, 40xx or 80xx models because their connectors are physically
and logically different. Apart from this, it requires address space at
$EC00-$EFFF, which makes it unfit to work in 40xx and 80xx models, which
have only 256 bytes of I/O space at $E800.

The DWW board consists of 8 KB of RAM and a PIA to control various
options. The RAM can be mapped either linearly at $9000-$AFFF,
or bank-switched in 8 banks of 8 KB each at $EC00-$EFFF.

It seems that in the demo programs, the BASIC versions like to
POKE in 60200, where the machine language programs use $EB00.
@verbatim
60200 Port A or DDR A           $EB28
$EBx0 1  0 \
      2  1 - RAM block at $EC00 (0-7)
      4  2 /
      8  3 charrom         0 = off 1 = on
      16 4 hires           0 = on  1 = off
      32 5 extra charrom   0 = on  1 = off

60201 Control Register A: bit #3 (worth 4) controls if 60200
$EBx1 accesses the Data Direction Register A (0) or Port A (1).

60202 Port B or DDR B
$EBx2 0 = RAM is visible from $9000 - $AFFF
      1 = RAM is bank-switched in blocks of 1 K in $EC00 - $EFFF

      [Control Register B is never mentioned, so putting 1 in this
       address would access the DDR, creating an output line, which
       after RESET is default 0...]
@end verbatim

Typical initialisation sequence:
@verbatim
    poke 60201,0        poke 60200,255          (all outputs)
    poke 60201,4        poke 60200,24 or 25 (16 + 8 + 1)
@end verbatim

Demo programs on disk PBE-110A, 110B, 111A, and 111B.
(PBE = PET Benelux Exchange, the Dutch PET user group)

The memory mapping is a bit strange. It seems each 1 K block contains
the pixeldata for 1 bit-line of each text line. This is probably so that
the addressing of the RAM can borrow part of the addressing
logic/signals of the text screen. (The screen addressing cycles through
0-39, then increases the line (= byte offset) which is fetched from
the character ROM; for the graphics, the screen position selects the
byte in a KB and the char ROM offset selects which KB of graphics RAM).

My notes say: to set a pixel:
@verbatim
RE = INT(Y/8): LY = Y - 8*RE    (or Y AND 7)
BY = INT(X/8): BI = X - 8*BY    (or X AND 7)
@end verbatim

when memory mapped to $9000:
@verbatim
    L = 36864 + 1024 * LY + 40 * RE + BY
    POKE L, PEEK(L) OR 2^BI
@end verbatim

when memory mapped to $EC00:
@verbatim
    POKE 60200,LY + 40 (or 8?)
    L = 60416 + RE * 40 + BY
    POKE L, PEEK(L) OR 2^BI
@end verbatim

Unfortunately there is no logical means of expanding the memory
to 16 K, so even in a 80 columns PET the resolution will be the same.

@node PET HRE (HiRes Emulator) high resolution grapics

@subsection HRE high resolution grapics

This information comes from @email{kontakt@@michau.name, Michal Pleban},
@uref{http://www.cbm-ii.com/}.

@cindex HRE
This is a short information about the HRE (HiRes Emulator) graphics
board for PET 8296. This is a small board that is installed on the
mainboard into sockets for the CRTC and character ROM. It adds the
ability to display 512x256 graphics on the built-in monitor.

The board is accompanied with two extension ROMs:

@itemize
@item
324992-02 HiRes Emulator (at $9000)
@item
324993-02 HiRes BASIC (at $A000)
@end itemize

The ROMs are initialized by the command
@code{SYS 36864}.

@cindex HRG
After that, the computer recognizes additional BASIC commands like
DISPLAY, PLOT and so on; these commands are identical to those of the
HiRes Graphics boards based on Thomson chips. All BASIC programs written
for the HRG boards should also work on the HRE (albeit much slower).

Upon initialization, the ROM code writes some routines into expansion
RAM as $8800 - they are used to manipulate the bitmap data. The actual
bitmap is located in expansion RAM at addresses $A000-$DFFF, and is
organized linearly (first 64 bytes form the first display line, then
comes the next line and so on).

The RAM is accessed for reading by writing the value #$83 into $E888.
This is a register in the CRTC memory space that is intercepted by the
board and serves as a latch to drive jumpers on the 8296D mainboard.
Because the ROMs are banked out this way, all video memory manipulation
must happen with interrupts disabled. Normal ROM operation is restored
by writing #$0F into $E888.

As usual with the 8296, the RAM can also be written even when the ROMs
are mapped normally.

The board is initialized into graphics mode by modifying the following
values in CRTC registers (it is done by the routine located at $8C1A):

@itemize @bullet
@item
Register $01 (horizontal displayed) = #$20
@item
Register $02 (horizontal sync position) = original + #$02
@item
Register $06 (vertical displayed) = #$20
@item
Register $07 (vertical sync position) = original + #$04
@item
Register $0C (RAM address high) = #$02
@end itemize

The last value causes the board to switch into graphics mode; former values set up propoer screen dimensions for 512x256 display.

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

@node CBM-II-specific, VSID-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} and @code{xcbm5x0}, 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

@vindex RamSize
@item RamSize
Size of memory in kByte.
xcbm2: (128, 256, 512, 1024)
xcbm5x0: (64, 128, 256, 512, 1024)

@vindex Ram08
@item Ram08
Boolean specifying whether the RAM should be mapped to the expansion ROM area at $0800-$0FFF or not.

@vindex Ram1
@item Ram1
Boolean specifying whether the RAM should be mapped to the expansion ROM area at $1000-$1FFF or not.

@vindex Ram2
@item Ram2
Boolean specifying whether the RAM should be mapped to the expansion ROM area at $2000-$3FFF or not.

@vindex Ram4
@item Ram4
Boolean specifying whether the RAM should be mapped to the expansion ROM area at $4000-$5FFF or not.

@vindex Ram6
@item Ram6
Boolean specifying whether the RAM should be mapped to the expansion ROM area at $6000-$7FFF or not.

@vindex RamC
@item RamC
Boolean specifying whether the RAM should be mapped to the expansion ROM area at $C000-$CFFF or not.

@vindex CartridgeReset
@item CartridgeReset
Boolean specifying whether the machine should be reset when a cartridge is changed.

@vindex Cart1Name
@item Cart1Name
String specifying the filename for the $1000-$1FFF expansion ROM file. This file contains an 8k ROM dump.

@vindex Cart2Name
@item Cart2Name
String specifying the filename for the $2000-$3FFF expansion ROM file. This file contains an 8k ROM dump.

@vindex Cart4Name
@item Cart4Name
String specifying the filename for the $4000-$5FFF expansion ROM file. This file contains an 8k ROM dump.

@vindex Cart6Name
@item Cart6Name
String specifying the filename for the $6000-$6FFF expansion ROM file. This file contains an 8k ROM dump.

@vindex 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.
xcbm2: (0: CBM 7x0 (50Hz), 1: 60Hz C6x0, 2: 50Hz C6x0)
xcbm5x0: (1: 60Hz C5x0, 2: 50Hz C5x0)

@vindex ChargenName
@item ChargenName
String specifying the name of the character generator ROM
(default for xcbm2: @file{chargen.600}, default for xcbm5x0: @file{chargen.500}).

@vindex KernalName
@item KernalName
String specifying the name of the Kernal ROM
(default for xcbm2: @file{kernal}, default for xcbm5x0: @file{kernal.500}).

@vindex BasicName
@item BasicName
String specifying the name of the Basic ROM
(default for xcbm2: @file{basic.128}, default for xcbm5x0: @file{basic.500}).

@vindex MachineVideoStandard
@item MachineVideoStandard
@c will be 'fixed' for xcbm2 later, for now xcbm5x0 only
Integer that specifies the video standard of the emulated machine
(-1: PAL, -2: NTSC).

@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 PAL or NTSC (128k RAM)
@item
C610 PAL or NTSC (128k RAM)
@item
C620 (256k RAM)
@item
C620+ (1024k RAM, expanded) PAL or NTSC
@item
C710 (128k RAM) NTSC
@item
C720 (256k RAM) NTSC
@item
C720+ (1024k RAM, expanded) NTSC
@end itemize

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

@b{Warning:} At this time the 5x0 and other machines are implemented
in different executables, so switching between those models is not possible.

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.

@c @node FIXME
@subsection CBM-II system ROM settings

@c @node FIXME
@subsubsection CBM-II system ROM resources

@c @node FIXME
@subsubsection CBM-II system ROM command line options

@table @code

@findex -kernal
@item -kernal <name>
Specify the name of the Kernal ROM file
(@code{KernalName}).

@findex -basic
@item -basic <name>
Specify the name of the Basic ROM file
(@code{BasicName}).

@findex -chargen
@item -chargen <name>
Specify the filename for the character generator ROM file
(@code{ChargenName}).

@findex +cart
@item +cart
Disable all cartridges (which would eventually be enabled in the config file).

@findex -cartreset, +cartreset
@item -cartreset
@itemx +cartreset
Reset/do not reset machine if a cartridge is attached or detached
(@code{CartridgeReset=1}, @code{CartridgeReset=0}).

@findex -cart1
@item -cart1 <name>
Specify the filename for the ROM image file for the cartridge area $1000-$1FFF
(@code{Cart1Name}).

@findex -cart2
@item -cart2 <name>
Specify the filename for the ROM image file for the cartridge area $2000-$2FFF
(@code{Cart2Name}).

@findex -cart4
@item -cart4 <name>
Specify the filename for the ROM image file for the cartridge area $4000-$5FFF
(@code{Cart4Name}).

@findex -cart6
@item -cart6 <name>
Specify the filename for the ROM image file for the cartridge area $6000-$7FFF
(@code{Cart6Name}).
@end table

@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

@findex -pal
@item -pal
Use PAL sync factor
(@code{MachineVideoStandard=-1}).

@findex -ntsc
@item -ntsc
Use NTSC sync factor
(@code{MachineVideoStandard=-2}).

@findex -ramsize
@item -ramsize <ramsize>
Specify size of RAM
(@code{RamSize}).
xcbm2: (128, 256, 512, 1024)
xcbm5x0: (64, 128, 256, 512, 1024)

@findex -ram08, +ram08
@item -ram08
@itemx +ram08
Enable/disable RAM mapping in bank 15 at address $0800-$0FFF
(@code{Ram08=1}, @code{Ram08=0}).

@findex -ram1, +ram1
@item -ram1
@itemx +ram1
Enable/disable RAM mapping in bank 15 at address $1000-$1FFF
(@code{Ram1=1}, @code{Ram1=0}).

@findex -ram2, +ram2
@item -ram2
@itemx +ram2
Enable/disable RAM mapping in bank 15 at address $2000-$3FFF
(@code{Ram2=1}, @code{Ram2=0}).

@findex -ram4, +ram4
@item -ram4
@itemx +ram4
Enable/disable RAM mapping in bank 15 at address $4000-$5FFF
(@code{Ram4=1}, @code{Ram4=0}).

@findex -ram6, +ram6
@item -ram6
@itemx +ram6
Enable/disable RAM mapping in bank 15 at address $6000-$7FFF
(@code{Ram6=1}, @code{Ram6=0}).

@findex -ramC, +ramC
@item -ramC
@itemx +ramC
Enable/disable RAM mapping in bank 15 at address $C000-$CFFF
(@code{RamC=1}, @code{RamC=0}).

@findex -model
@item -model <modelnumber>
Specify CBM-II model to emulate
(@code{ModelLine}, @code{MachineVideoStandard}, @code{RamSize}, @code{KernalName}, @code{BasicName}, @code{ChargenName}).
xcbm2: (610, 620, 620+, 710, 720, 720+)
xcbm5x0: (510)

@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 VSID-specific, , CBM-II-specific, Machine-specific features
@section VSID-specific commands and settings

@c @node FIXME
@subsection VSID settings

@c @node FIXME
@subsubsection VSID resources

@table @code

@vindex PSIDKeepEnv
@item PSIDKeepEnv
Boolean that specifies whether to override PSID settings for Video standard and 
SID model.

@vindex PSIDTune
@item PSIDTune
Integer that specifies the currently played sub tune.

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

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

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

@vindex 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

@vindex MachineVideoStandard
@item MachineVideoStandard
Integer that specifies the video standard of the emulated machine
(-4: PAL-N, -3: Old NTSC, -1: PAL, -2: NTSC).

@end table

@c @node FIXME
@subsubsection VSID command-line options

@table @code

@findex -keepenv
@item -keepenv
Override PSID settings for Video standard and SID model
(@code{PSIDKeepEnv=1}).

@findex -tune
@item -tune <number>
Specify PSID tune <number>
(@code{PSIDTune}).

@findex -chargen
@item -chargen <name>
Specify name of character generator ROM image
(@code{ChargenName}).

@findex -kernal
@item -kernal <name>
Specify name of the Kernal ROM image
(@code{KernalName}).

@findex -basic
@item -basic <name>
Specify name of the Basic ROM image
(@code{BasicName}).

@findex -pal
@item -pal
Use PAL sync factor
(@code{MachineVideoStandard=-1}).

@findex -ntsc
@item -ntsc
Use NTSC sync factor
(@code{MachineVideoStandard=-2}).

@findex -ntscold
@item -ntscold
Use old NTSC sync factor
(@code{MachineVideoStandard=-3}).

@findex -paln
@item -paln
Use PAL-N sync factor
(@code{MachineVideoStandard=-4}).

@end table

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

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

This section lists the settings and commands that are platform specific.

@menu
@ifset platformamiga
* AmigaOS-specific features::
@end ifset
@ifset platformbeos
* BeOS-specific features::
@end ifset
@ifset platformdos
* DOS-specific features::
@end ifset
@ifset platformos2
* OS2-specific features::
@end ifset
@ifset platformsdl
* SDL-specific features::
@end ifset
@ifset platformunix
* Unix-specific features::
@end ifset
@ifset platformosx
* Mac OS X-specific features::
@end ifset
@ifset platformwindows
* Windows-specific features::
@end ifset
@end menu

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

@ifset platformall
@node AmigaOS-specific features, BeOS-specific features, Platform-specific features, Platform-specific features
@section AmigaOS-specific features
@end ifset

@ifclear platformall
@ifset platformamiga
@node AmigaOS-specific features, , Platform-specific features, Platform-specific features
@section AmigaOS-specific features
@end ifset
@end ifclear

@ifset platformamiga
@menu
@ifset platformamigaos3
* AmigaOS3-specific features::
@end ifset
@ifset platformamigaos4
* AmigaOS4-specific features::
@end ifset
@ifset platformmorphos
* MorphOS-specific features::
@end ifset
@ifset platformaros
* AROS-specific features::
@end ifset
@end menu

This section lists the settings and commands that are common and specific to all Amiga based
platforms (this includes AmigaOS3, AmigaOS4, Morphos and AROS), and are thus not present in other platforms. 

@c @node FIXME
@subsection Amiga (AmigaOS3/AmigaOS4/MorphOS/AROS) specific resources

@table @code

@vindex InitialDefaultDir
@item InitialDefaultDir
String specifying the initial default directory, which is used by the generic file browser dialog.

@vindex InitialTapeDir
@item InitialTapeDir
String specifying the initial tape directory, which is used by the tape image file browser dialog
(all emulators except xscpu64, x64dtv and vsid).

@vindex InitialDiskDir
@item InitialDiskDir
String specifying the initial tape directory, which is used by the disk image file browser dialog
(all emulators except vsid).

@vindex InitialAutostartDir
@item InitialAutostartDir
String specifying the initial autostart directory, which is used by the autostart image file browser dialog
(all emulators except vsid).

@vindex InitialCartDir
@item InitialCartDir
String specifying the initial cartridge directory, which is used by the cartridge image file browser dialog
(all emulators except x64dtv and vsid).

@vindex InitialSnapshotDir
@item InitialSnapshotDir
String specifying the initial snapshots directory, which is used by the snapshots file browser dialog
(all emulators except vsid).

@vindex FullscreenEnabled
@item FullscreenEnabled
Boolean to enable/disable fullscreen mode.

@vindex StatusBarEnabled
@item StatusBarEnabled
Boolean to enable/disable the statusbar.

@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 ConfirmOnExit
@item ConfirmOnExit
Boolean specifying whether to show a confirmation dialog on exit.

@end table

@c @node FIXME
@subsection Amiga (AmigaOS3/AmigaOS4/MorphOS/AROS) specific command-line options

@table @code

@findex -initialdefaultdir
@item -initialdefaultdir <Name>
Select the initial default directory for the file browser dialog
(@code{InitialDefaultDir}).

@findex -initialtapedir
@item -initialtapedir <Name>
Select the initial tape images directory for the file browser dialog
(@code{InitialTapeDir})
(all emulators except xscpu64, x64dtv and vsid).

@findex -initialdiskdir
@item -initialdiskdir <Name>
Select the initial disk images directory for the file browser dialog
(@code{InitialDiskDir})
(all emulators except vsid).

@findex -initialautostartdir
@item -initialautostartdir <Name>
Select the initial autostart directory for the file browser dialog
(@code{InitialAutostartDir})
(all emulators except vsid).

@findex -initialcartdir
@item -initialcartdir <Name>
Select the initial cartridge images directory for the file browser dialog
(@code{InitialCartDir})
(all emulators except x64dtv and vsid).

@findex -initialsnapshotdir
@item -initialsnapshotdir <Name>
Select the initial snapshot directory for the file browser dialog
(@code{InitialSnapshotDir})
(all emulators except vsid).

@findex -fullscreen, +fullscreen
@item -fullscreen
@itemx +fullscreen
Enable/disable fullscreen mode
(@code{FullscreenEnabled=1}, @code{FullscreenEnabled=0}).

@findex -statusbar, +statusbar
@item -statusbar
@itemx +statusbar
Enable/Disable the statusbar
(@code{StatusBarEnabled=1}, @code{StatusBarEnabled=0}).

@findex -saveres, +saveres
@item -saveres
@itemx +saveres
Enable/disable automatic saving of settings on exit
(@code{SaveResourcesOnExit=1}, @code{SaveResourcesOnExit=0}).

@findex -confirmexit, +confirmexit
@item -confirmexit
Confirm quitting VICE
(@code{ConfirmOnExit=1}).
@item +confirmexit
Never confirm quitting VICE
(@code{ConfirmOnExit=0}).

@end table

@end ifset

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

@ifset platformamigaall
@node AmigaOS3-specific features, AmigaOS4-specific features, AmigaOS-specific features, AmigaOS-specific features
@subsection AmigaOS3-specific features
@end ifset

@ifclear platformamigaall
@ifset platformamigaos3
@node AmigaOS3-specific features, , AmigaOS-specific features, AmigaOS-specific features
@subsection AmigaOS3-specific features
@end ifset
@end ifclear

@ifset platformamigaos3

This section lists the settings and commands that are common and specific to AmigaOS3, and are thus not present in other platforms. 

The AmigaOS3 port uses the AHI sound system, the CGX or P96 graphics system, the LowLevel input system, the MUI GUI system, and
optionally the OpenPCI library for access to expansion cards like Catweasel or HardSID. Please note that access to the Catweasel
can also be done using catweaselsid.device.

@c @node FIXME
@subsubsection AmigaOS3 specific resources

@table @code

@vindex JoyFire1
@item JoyFire1
Integer specifying the code of the button to use for fire for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).

@vindex JoyFire2
@item JoyFire2
Integer specifying the code of the button to use for fire for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).

@vindex JoyFire3
@item JoyFire3
Integer specifying the code of the button to use for fire for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).

@vindex JoyFire4
@item JoyFire4
Integer specifying the code of the button to use for fire for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).

@vindex JoyDevice1
@item JoyDevice1
Integer specifying which joystick device the emulator should use for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@vindex JoyDevice2
@item JoyDevice2
Integer specifying which joystick device the emulator should use for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@vindex JoyDevice3
@item JoyDevice3
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@vindex JoyDevice4
@item JoyDevice4
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@end table

@b{The following resource is only present if the CGX video system is present and used at compile time, and
cgxvideo.library is present at runtime.}

@table @code

@vindex VideoOverlayEnabled
@item VideoOverlayEnabled
Boolean to enable/disable video overlay mode.

@end table

@c @node FIXME
@subsubsection AmigaOS3 specific command-line options

@table @code

@findex -joydev1
@item -joydev1 <0-5>
Set the device for joystick emulation of port 1
(@code{JoyDevice1})
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)
@findex -joydev2
@item -joydev2 <0-5>
Set the device for joystick emulation of port 2
(@code{JoyDevice2})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)
@findex -extrajoydev1
@item -extrajoydev1 <0-5>
Set device for extra joystick port 1
(@code{JoyDevice3})
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)
@findex -extrajoydev2
@item -extrajoydev2 <0-5>
Set device for extra joystick port 2
(@code{JoyDevice4})
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@end table

@b{The following command-line option is only present if the CGX video system is present and used at compile time, and
cgxvideo.library is present at runtime.}

@table @code

@findex -videooverlay, +videooverlay
@item -videooverlay
@itemx +videooverlay
Enable/Disable video overlay mode
(@code{VideoOverlayEnabled=1}, @code{VideoOverlayEnabled=0}).

@end table

@end ifset

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

@ifset platformamigaall
@node AmigaOS4-specific features, MorphOS-specific features, AmigaOS3-specific features, AmigaOS-specific features
@subsection AmigaOS4-specific features
@end ifset

@ifclear platformamigaall
@ifset platformamigaos4
@node AmigaOS4-specific features, , AmigaOS-specific features, AmigaOS-specific features
@subsection AmigaOS4-specific features
@end ifset
@end ifclear

@ifset platformamigaos4

This section lists the settings and commands that are common and specific to AmigaOS4, and are thus not present in other platforms. 

The AmigaOS4 port uses the AHI sound system, the P96 graphics system, the AmigaInput input system, the MUI GUI system, and
optionally the expansion library for access to expansion cards like Catweasel or HardSID.

@c @node FIXME
@subsubsection AmigaOS4 specific resources

These are all generic joystick related resources and are therefor present in all emulators except vsid.

@table @code

@vindex JOYAI1_ID
@item JOYAI1_ID
String specifying the AmigaInput ID of hardware joystick 1.

@vindex JOYAI2_ID
@item JOYAI2_ID
String specifying the AmigaInput ID of hardware joystick 2.

@vindex JOYAI1_Up
@item JOYAI1_Up
String specifying the AmigaInput event ID for the up direction of hardware joystick 1.

@vindex JOYAI2_Up
@item JOYAI2_Up
String specifying the AmigaInput event ID for the up direction of hardware joystick 2.

@vindex JOYAI1_Down
@item JOYAI1_Down
String specifying the AmigaInput event ID for the down direction of hardware joystick 1.

@vindex JOYAI2_Down
@item JOYAI2_Down
String specifying the AmigaInput event ID for the down direction of hardware joystick 2.

@vindex JOYAI1_Left
@item JOYAI1_Left
String specifying the AmigaInput event ID for the left direction of hardware joystick 1.

@vindex JOYAI2_Left
@item JOYAI2_Left
String specifying the AmigaInput event ID for the left direction of hardware joystick 2.

@vindex JOYAI1_Right
@item JOYAI1_Right
String specifying the AmigaInput event ID for the right direction of hardware joystick 1.

@vindex JOYAI2_Right
@item JOYAI2_Right
String specifying the AmigaInput event ID for the right direction of hardware joystick 2.

@vindex JOYAI1_Fire
@item JOYAI1_Fire
String specifying the AmigaInput event ID for the fire button of hardware joystick 1.

@vindex JOYAI2_Fire
@item JOYAI2_Fire
String specifying the AmigaInput event ID for the fire button of hardware joystick 2.

@end table

@table @code

@vindex JoyDevice1
@item JoyDevice1
Integer specifying which joystick device the emulator should use for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1/AI, 3: Keyset 2/AI)

@vindex JoyDevice2
@item JoyDevice2
Integer specifying which joystick device the emulator should use for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1/AI, 3: Keyset 2/AI)

@vindex JoyDevice3
@item JoyDevice3
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1/AI, 3: Keyset 2/AI)

@vindex JoyDevice4
@item JoyDevice4
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1/AI, 3: Keyset 2/AI)

@end table

@c @node FIXME
@subsubsection AmigaOS4 specific command-line options

@table @code

@findex -joydev1
@item -joydev1 <0-3>
Set the device for joystick emulation of port 1
(@code{JoyDevice1})
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1/AI, 3: Keyset 2/AI)

@findex -joydev2
@item -joydev2 <0-3>
Set the device for joystick emulation of port 2
(@code{JoyDevice2})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1/AI, 3: Keyset 2/AI)

@findex -extrajoydev1
@item -extrajoydev1 <0-3>
Set device for extra joystick port 1
(@code{JoyDevice3})
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1/AI, 3: Keyset 2/AI)

@findex -extrajoydev2
@item -extrajoydev2 <0-3>
Set device for extra joystick port 2
(@code{JoyDevice4})
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1/AI, 3: Keyset 2/AI)

@end table

@end ifset

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

@ifset platformamigaall
@node MorphOS-specific features, AROS-specific features, AmigaOS4-specific features, AmigaOS-specific features
@subsection MorphOS-specific features
@end ifset

@ifclear platformamigaall
@ifset platformmorphos
@node MorphOS-specific features, , AmigaOS-specific features, AmigaOS-specific features
@subsection MorphOS-specific features
@end ifset
@end ifclear

@ifset platformmorphos

This section lists the settings and commands that are common and specific to MorphOS, and are thus not present in other platforms. 

The MorphOS port uses the AHI or SDL sound system, the CGX graphics system, the LowLevel input system, the MUI GUI system, and
optionally the OpenPCI library for access to expansion cards like Catweasel or HardSID. Please note that access to the Catweasel
can also be done using catweaselsid.device.

@c @node FIXME
@subsubsection MorphOS specific resources

@table @code

@vindex JoyFire1
@item JoyFire1
Integer specifying the code of the button to use for fire for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).

@vindex JoyFire2
@item JoyFire2
Integer specifying the code of the button to use for fire for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).

@vindex JoyFire3
@item JoyFire3
Integer specifying the code of the button to use for fire for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).

@vindex JoyFire4
@item JoyFire4
Integer specifying the code of the button to use for fire for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).

@vindex JoyDevice1
@item JoyDevice1
Integer specifying which joystick device the emulator should use for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@vindex JoyDevice2
@item JoyDevice2
Integer specifying which joystick device the emulator should use for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@vindex JoyDevice3
@item JoyDevice3
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@vindex JoyDevice4
@item JoyDevice4
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@end table

@b{The following resource is only present if the CGX video system is present and used at compile time, and
cgxvideo.library is present at runtime.}

@table @code

@vindex VideoOverlayEnabled
@item VideoOverlayEnabled
Boolean to enable/disable video overlay mode.

@end table

@c @node FIXME
@subsubsection MorphOS specific command-line options

@table @code

@findex -joydev1
@item -joydev1 <0-5>
Set the device for joystick emulation of port 1
(@code{JoyDevice1})
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@findex -joydev2
@item -joydev2 <0-5>
Set the device for joystick emulation of port 2
(@code{JoyDevice2})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@findex -extrajoydev1
@item -extrajoydev1 <0-5>
Set device for extra joystick port 1
(@code{JoyDevice3})
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@findex -extrajoydev2
@item -extrajoydev2 <0-5>
Set device for extra joystick port 2
(@code{JoyDevice4})
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@end table

@b{The following command-line option is only present if the CGX video system is present and used at compile time, and
cgxvideo.library is present at runtime.}

@table @code

@findex -videooverlay, +videooverlay
@item -videooverlay
@itemx +videooverlay
Enable/Disable video overlay mode
(@code{VideoOverlayEnabled=1}, @code{VideoOverlayEnabled=0}).

@end table

@end ifset

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

@ifset platformamigaall
@node AROS-specific features, , MorphOS-specific features, AmigaOS-specific features
@subsection AROS-specific features
@end ifset

@ifclear platformamigaall
@ifset platformaros
@node AROS-specific features, , AmigaOS-specific features, AmigaOS-specific features
@subsection AROS-specific features
@end ifset
@end ifclear

@ifset platformaros

This section lists the settings and commands that are common and specific to AROS, and are thus not present in other platforms. 

The AROS port uses the AHI or SDL sound system, the CGX graphics system, the LowLevel input system, the MUI GUI system.

@c @node FIXME
@subsubsection AROS specific resources

@table @code

@vindex JoyFire1
@item JoyFire1
Integer specifying the code of the button to use for fire for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).

@vindex JoyFire2
@item JoyFire2
Integer specifying the code of the button to use for fire for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).

@vindex JoyFire3
@item JoyFire3
Integer specifying the code of the button to use for fire for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).

@vindex JoyFire4
@item JoyFire4
Integer specifying the code of the button to use for fire for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).

@vindex JoyDevice1
@item JoyDevice1
Integer specifying which joystick device the emulator should use for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@vindex JoyDevice2
@item JoyDevice2
Integer specifying which joystick device the emulator should use for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@vindex JoyDevice3
@item JoyDevice3
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@vindex JoyDevice4
@item JoyDevice4
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@end table

@b{The following resource is only present if the CGX video system is present and used at compile time, and
cgxvideo.library is present at runtime.}

@table @code

@vindex VideoOverlayEnabled
@item VideoOverlayEnabled
Boolean to enable/disable video overlay mode.

@end table

@c @node FIXME
@subsubsection AROS specific command-line options

@table @code

@findex -joydev1
@item -joydev1 <0-5>
Set the device for joystick emulation of port 1
(@code{JoyDevice1})
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@findex -joydev2
@item -joydev2 <0-5>
Set the device for joystick emulation of port 2
(@code{JoyDevice2})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@findex -extrajoydev1
@item -extrajoydev1 <0-5>
Set device for extra joystick port 1
(@code{JoyDevice3})
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@findex -extrajoydev2
@item -extrajoydev2 <0-5>
Set device for extra joystick port 2
(@code{JoyDevice4})
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Joy0, 3: Joy1, 4: Joy2, 5: Joy3)

@end table

@b{The following command-line option is only present if the CGX video system is present and used at compile time, and
cgxvideo.library is present at runtime.}

@table @code

@findex -videooverlay, +videooverlay
@item -videooverlay
@itemx +videooverlay
Enable/Disable video overlay mode
(@code{VideoOverlayEnabled=1}, @code{VideoOverlayEnabled=0}).

@end table

@end ifset

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

@ifset platformall
@node BeOS-specific features, DOS-specific features, AmigaOS-specific features, Platform-specific features
@section BeOS-specific features
@end ifset

@ifclear platformall
@ifset platformbeos
@node BeOS-specific features, , Platform-specific features, Platform-specific features
@section BeOS-specific features
@end ifset
@end ifclear

@ifset platformbeos

This section lists the settings and commands that are common and specific to BeOS, Zeta and Haiku, and are thus not present in other platforms. 

@c @node FIXME
@subsection BeOS specific resources

@table @code

@vindex JoystickDisplay
@item JoystickDisplay
Boolean to enable/disable displaying the joystick status in the emulator window.

@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 ConfirmOnExit
@item ConfirmOnExit
Boolean specifying whether to show a confirmation dialog on exit.

@vindex DirectWindow
@item DirectWindow
Boolean specifying whether to use the BeOS DirectWindow API.

@vindex JoyDevice1
@item JoyDevice1
Integer specifying which joystick device the emulator should use for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4..19: Hardware joysticks)

@vindex JoyDevice2
@item JoyDevice2
Integer specifying which joystick device the emulator should use for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4..19: Hardware joysticks)

@vindex JoyDevice3
@item JoyDevice3
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4..19: Hardware joysticks)

@vindex JoyDevice4
@item JoyDevice4
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4..19: Hardware joysticks)

@end table

@c @node FIXME
@subsection BeOS specific command-line options

@table @code

@findex -joydisplay, +joydisplay
@item -joydisplay
@itemx +joydisplay
Enable/Disable joystick display.
(@code{JoystickDisplay=1}, @code{JoystickDisplay=0}).

@findex -saveres, +saveres
@item -saveres
@itemx +saveres
Enable/disable automatic saving of settings on exit
(@code{SaveResourcesOnExit=1}, @code{SaveResourcesOnExit=0}).

@findex -confirmexit, +confirmexit
@item -confirmexit
Confirm quitting VICE
(@code{ConfirmOnExit=1}).
@item +confirmexit
Never confirm quitting VICE
(@code{ConfirmOnExit=0}).

@findex -directwindow, +directwindow
@item -directwindow
@itemx +directwindow
Enable/disable usage of the BeOS DirectWindow API
(@code{DirectWindow=1}, @code{DirectWindow=0}).

@findex -joydev1
@item -joydev1 <0-19>
Set the device for joystick emulation of port 1
(@code{JoyDevice1})
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4..19: Hardware joysticks)

@findex -joydev2
@item -joydev2 <0-19>
Set the device for joystick emulation of port 2
(@code{JoyDevice2})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4..19: Hardware joysticks)

@findex -extrajoydev1
@item -extrajoydev1 <0-19>
Set device for extra joystick port 1
(@code{JoyDevice3})
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4..19: Hardware joysticks)

@findex -extrajoydev2
@item -extrajoydev2 <0-19>
Set device for extra joystick port 2
(@code{JoyDevice4})
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4..19: Hardware joysticks)

@end table

@end ifset

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

@ifset platformall
@node DOS-specific features, OS2-specific features, BeOS-specific features, Platform-specific features
@section DOS-specific features
@end ifset

@ifclear platformall
@ifset platformdos
@node DOS-specific features, , Platform-specific features, Platform-specific features
@section DOS-specific features
@end ifset
@end ifclear

@ifset platformdos

This section lists the settings and commands that are common and specific to DOS, and are thus not present in other platforms. 

@c @node FIXME
@subsection DOS joystick hardware types

Here is a list of joystick hardware types that are supported

@table @code

@cindex JOY_TYPE_AUTODETECT
@item JOY_TYPE_AUTODETECT (0xFFFFFFFF, "auto")
Attempts to autodetect your joystick hardware. It isn't possible to reliably distinguish between all the possible input setups, so this routine can only ever choose the standard joystick, Sidewider, GamePad Pro, or GrIP drivers.
@cindex JOY_TYPE_NONE
@item JOY_TYPE_NONE (0x00000000, "none")
Dummy driver for machines without any joystick.
@cindex JOY_TYPE_STANDARD
@item JOY_TYPE_STANDARD (0x53544420, "standard")
A normal two button stick.
@cindex JOY_TYPE_2PADS
@item JOY_TYPE_2PADS (0x32504144, "dual")
Dual joystick mode (two sticks, each with two buttons).
@cindex JOY_TYPE_4BUTTON
@item JOY_TYPE_4BUTTON (0x34425554, "4button")
Enable the extra buttons on a 4-button joystick.
@cindex JOY_TYPE_6BUTTON
@item JOY_TYPE_6BUTTON (0x36425554, "6button")
Enable the extra buttons on a 6-button joystick.
@cindex JOY_TYPE_8BUTTON
@item JOY_TYPE_8BUTTON (0x38425554, "8button")
Enable the extra buttons on an 8-button joystick.
@cindex JOY_TYPE_FSPRO
@item JOY_TYPE_FSPRO (0x4650524F, "fspro")
CH Flightstick Pro or compatible stick, which provides four buttons, an analogue throttle control, and a 4-direction coolie hat.
@cindex JOY_TYPE_WINGEX
@item JOY_TYPE_WINGEX (0x57494E47, "wingex")
A Logitech Wingman Extreme, which should also work with any Thrustmaster Mk.I compatible joystick. It provides support for four buttons and a coolie hat. This also works with the Wingman Warrior, if you plug in the 15 pin plug (remember to unplug the 9-pin plug!) and set the tiny switch in front to the "H" position (you will not be able to use the throttle or the spinner though).
@cindex JOY_TYPE_SIDEWINDER
@item JOY_TYPE_SIDEWINDER (0x53572020, "sidewinder")
The Microsoft Sidewinder digital pad (supports up to four controllers, each with ten buttons and a digital direction control).
@cindex JOY_TYPE_SIDEWINDER_AG
@item JOY_TYPE_SIDEWINDER_AG (0x53574147, "sidewinderag")
An alternative driver to JOY_TYPE_SIDEWINDER. Try this if your Sidewinder isn't recognized with JOY_TYPE_SIDEWINDER.
@cindex JOY_TYPE_SIDEWINDER_PP
@item JOY_TYPE_SIDEWINDER_PP (0x53575050, "sidewinderpp")
The Microsoft Sidewinder 3D/Precision/Force Feedback Pro joysticks.
@cindex JOY_TYPE_GAMEPAD_PRO
@item JOY_TYPE_GAMEPAD_PRO (0x4750524F, "gamepadpro")
The Gravis GamePad Pro (supports up to two controllers, each with ten buttons and a digital direction control).
@cindex JOY_TYPE_GRIP
@item JOY_TYPE_GRIP (0x47524950, "grip")
Gravis GrIP driver, using the grip.gll driver file.
@cindex JOY_TYPE_GRIP4
@item JOY_TYPE_GRIP4 (0x47524934, "grip4")
Version of the Gravis GrIP driver that is constrained to only move along the four main axes.
@cindex JOY_TYPE_SNESPAD_LPT1
@cindex JOY_TYPE_SNESPAD_LPT2
@cindex JOY_TYPE_SNESPAD_LPT3
@item JOY_TYPE_SNESPAD_LPT1 (0x534E4531, "sneslpt1")
@itemx JOY_TYPE_SNESPAD_LPT2 (0x534E4532, "sneslpt2")
@itemx JOY_TYPE_SNESPAD_LPT3 (0x534E4533, "sneslpt3")
SNES joypads connected to LPT1, LPT2 and LPT3 respectively.
@cindex JOY_TYPE_PSXPAD_LPT1
@cindex JOY_TYPE_PSXPAD_LPT2
@cindex JOY_TYPE_PSXPAD_LPT3
@item JOY_TYPE_PSXPAD_LPT1 (0x50535831, "psxlpt1")
@itemx JOY_TYPE_PSXPAD_LPT2 (0x50535832, "psxlpt2")
@itemx JOY_TYPE_PSXPAD_LPT3 (0x50535833, "psxlpt3")
PSX joypads connected to LPT1, LPT2 and LPT3 respectively. See http://www.ziplabel.com/dpadpro/index.html for information about the parallel cable required. The driver automagically detects which types of PSX pads are connected out of digital, analog (red or green mode), NegCon, multi taps, Namco light guns, Jogcons (force feedback steering wheel) and the mouse. If the controller isn't recognised it is treated as an analog controller, meaning the driver should work with just about anything. You can connect controllers in any way you see fit, but only the first 8 will be used. The Sony Dual Shock or Namco Jogcon will reset themselves (to digital mode) after not being polled for 5 seconds. This is normal, the same thing happens on a Playstation, it's designed to stop any vibration in case the host machine crashes. Other mode switching controllers may have similar quirks. However, if this happens to a Jogcon controller the mode button is disabled. To reenable the mode button on the Jogcon you need to hold down the Start and Select buttons at the same time. The G-con45 needs to be connected to (and pointed at) a TV type monitor connected to your computer.
@cindex JOY_TYPE_N64PAD_LPT1
@cindex JOY_TYPE_N64PAD_LPT2
@cindex JOY_TYPE_N64PAD_LPT3
@item JOY_TYPE_N64PAD_LPT1 (0x4E363431, "n64lpt1")
@itemx JOY_TYPE_N64PAD_LPT2 (0x4E363432, "n64lpt2")
@itemx JOY_TYPE_N64PAD_LPT3 (0x4E363433, "n64lpt3")
N64 joypads connected to LPT1, LPT2 and LPT3 respectively. See http://www.st-hans.de/N64.htm for information about the necessary hardware adapter. It supports up to four controllers on a single parallel port. There is no need to calibrate the analog stick, as this is done by the controller itself when powered up. This means that the stick has to be centred when the controller is initialised. One possible issue people may have with this driver is that it is physically impossible to move the analog stick fully diagonal, but I can't see this causing any major problems. This is because of the shape of the rim that the analog stick rests against. Like the Gravis Game Pad Pro, this driver briefly needs to disable hardware interrupts while polling. This causes a noticeable performance hit on my machine in both drivers, but there is no way around it.
@cindex JOY_TYPE_DB9_LPT1
@cindex JOY_TYPE_DB9_LPT2
@cindex JOY_TYPE_DB9_LPT3
@item JOY_TYPE_DB9_LPT1 (0x44423931, "db9lpt1")
@itemx JOY_TYPE_DB9_LPT1 (0x44423932, "db9lpt2")
@itemx JOY_TYPE_DB9_LPT3 (0x44423933, "db9lpt3")
A pair of two-button joysticks connected to LPT1, LPT2 and LPT3 respectively. Port 1 is compatible with Linux joy-db9 driver (multisystem 2-button), and port 2 is compatible with Atari interface for DirectPad Pro. See the source file (src/dos/multijoy.c) for pinout information.
@cindex JOY_TYPE_TURBOGRAFIX_LPT1 
@cindex JOY_TYPE_TURBOGRAFIX_LPT2
@cindex JOY_TYPE_TURBOGRAFIX_LPT3
@item JOY_TYPE_TURBOGRAFX_LPT1 (0x54475831, "tgxlpt1")
@itemx JOY_TYPE_TURBOGRAFX_LPT2 (0x54475832, "tgxlpt2")
@itemx JOY_TYPE_TURBOGRAFX_LPT3 (0x54475833, "tgxlpt3")
These drivers support up to 7 joysticks, each one with up to 5 buttons, connected to LPT1, LPT2, and LPT3 respectively. They use the TurboGraFX interface by Steffen Schwenke: see http://www.burg-halle.de/~schwenke/parport.html for details on how to build this.
@cindex JOY_TYPE_WINGWARRIOR
@item JOY_TYPE_WINGWARRIOR (0x57574152, "wingwar")
A Wingman Warrior joystick.
@cindex JOY_TYPE_IFSEGA_ISA
@cindex JOY_TYPE_IFSEGA_PCI
@cindex JOY_TYPE_IFSEGA_PCI_FAST
@item JOY_TYPE_IFSEGA_ISA (0x53454749, "ifsegaisa")
@itemx JOY_TYPE_IFSEGA_PCI (0x53454750, "ifsegapci")
@itemx JOY_TYPE_IFSEGA_PCI_FAST (0x53475046, "ifsegapcifast")
Drivers for the IF-SEGA joystick interface cards by the IO-DATA company (these come in PCI, PCI2, and ISA variants). 

@end table

@c @node FIXME
@subsection DOS specific resources

@table @code

@vindex UseLeds
@item UseLeds
Boolean to enable/disable using the keyboard leds for status display.

@vindex ShowStatusbar
@item ShowStatusbar
Integer specifying the mode of the statusbar.
(0: Off, 1: On, 2: Auto)

@vindex VGAMode
@item VGAMode
Integer specifying the VGA mode.
(0: 320x200x8, 1: 360x240x8, 2: 360x270x8, 3: 376x282x8, 4: 400x300x8, 5: 640x480x8, 6: 800x600x8, 7: 1024x768x8, 8: 320x200x16, 9: 400x300x16, 10: 640x480x16, 11: 800x600x16, 12: 1024x768x16, 13: 640x480x32, 14: 800x600x32, 15: 1024x768x32)

@vindex HwJoyType
@item HwJoyType
Integer specifying the hardware type of the joystick
(all emulators except vsid).
See @code{'DOS joystick hardware types'} for the types.

@vindex JoyDevice1
@item JoyDevice1
Integer specifying which joystick device the emulator should use for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: Joystick 2)

@vindex JoyDevice2
@item JoyDevice2
Integer specifying which joystick device the emulator should use for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: Joystick 2)

@vindex JoyDevice3
@item JoyDevice3
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: Joystick 2)

@vindex JoyDevice4
@item JoyDevice4
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: Joystick 2)

@end table

@b{The following resource is only available if the midas sound driver is not used during compile time.}

@table @code

@vindex TripleBuffering
@item TripleBuffering
Boolean to enable/disable triple buffering if possible.

@end table

@c @node FIXME
@subsection DOS specific command-line options

@table @code

@findex -leds, +leds
@item -leds
@itemx +leds
Enable/disable usage of keyboard leds
(@code{UseLeds=1}, @code{UseLeds=0}).

@findex -statusbar
@item -statusbar <Mode>
Set the statusbar mode
(@code{ShowStatusbar}).
(0: Off, 1: On, 2: Auto)

@findex -vgamode
@item -vgamode <Mode>
Set the VGA mode
(@code{VGAMode}).
(0: 320x200x8, 1: 360x240x8, 2: 360x270x8, 3: 376x282x8, 4: 400x300x8, 5: 640x480x8, 6: 800x600x8, 7: 1024x768x8, 8: 320x200x16, 9: 400x300x16, 10: 640x480x16, 11: 800x600x16, 12: 1024x768x16, 13: 640x480x32, 14: 800x600x32, 15: 1024x768x32)

@findex -joyhwtype
@item -joyhwtype <type>
Set the joystick hardware type
(@code{HwJoyType})
(all emulators except vsid).
See @code{DOS joystick hardware types} for the types.

@findex -joydev1
@item -joydev1 <0-5>
Set the device for joystick emulation of port 1
(@code{JoyDevice1})
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: Joystick 2)

@findex -joydev2
@item -joydev2 <0-5>
Set the device for joystick emulation of port 2
(@code{JoyDevice2})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: Joystick 2)

@findex -extrajoydev1
@item -extrajoydev1 <0-5>
Set device for extra joystick port 1
(@code{JoyDevice3})
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: Joystick 2)

@findex -extrajoydev2
@item -extrajoydev2 <0-5>
Set device for extra joystick port 2
(@code{JoyDevice4})
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: Joystick 2)

@end table

@b{The following command-line option is only available if the midas sound driver is not used during compile time.}

@table @code

@findex -triplebuf, +triplebuf
@item -triplebuf
@itemx +triplebuf
Enable/Disable triple buffering
(@code{TripleBuffering=1}, @code{TripleBuffering=0}).

@end table

@end ifset

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

@ifset platformall
@node OS2-specific features, SDL-specific features, DOS-specific features, Platform-specific features
@section OS2-specific features
@end ifset

@ifclear platformall
@ifset platformos2
@node OS2-specific features, , Platform-specific features, Platform-specific features
@section OS2-specific features
@end ifset
@end ifclear

@ifset platformos2

@c TODO: OS/2 specific content

@end ifset

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

@ifset platformall
@node SDL-specific features, Unix-specific features, OS2-specific features, Platform-specific features
@section SDL-specific features
@end ifset

@ifclear platformall
@ifset platformsdl
@node SDL-specific features, , Platform-specific features, Platform-specific features
@section SDL-specific features
@end ifset
@end ifclear

@ifset platformsdl

This section lists the settings and commands that are common and specific to SDL, and are thus not present in other platforms. 

@c @node FIXME
@subsection SDL specific resources

@table @code

@vindex HotkeyFile
@item HotkeyFile
String specifying the name of the hotkey file
(all emulators except vsid).

@vindex MenuKey
@item MenuKey
Integer specifying the keycode for activating the SDL menu.

@vindex MenuKeyUp
@item MenuKeyUp
Integer specifying the keycode for 'up' in the SDL menu.

@vindex MenuKeyDown
@item MenuKeyDown
Integer specifying the keycode for 'down' in the SDL menu.

@vindex MenuKeyLeft
@item MenuKeyLeft
Integer specifying the keycode for 'left' in the SDL menu.

@vindex MenuKeyRight
@item MenuKeyRight
Integer specifying the keycode for 'right' in the SDL menu.

@vindex MenuKeySelect
@item MenuKeySelect
Integer specifying the keycode for 'select' in the SDL menu.

@vindex MenuKeyCancel
@item MenuKeyCancel
Integer specifying the keycode for 'cancel' in the SDL menu.

@vindex MenuKeyExit
@item MenuKeyExit
Integer specifying the keycode for 'exit' in the SDL menu.

@vindex MenuKeyMap
@item MenuKeyMap
Integer specifying the keycode for 'map' in the SDL menu.

@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 ConfirmOnExit
@item ConfirmOnExit
Boolean specifying whether to show a confirmation dialog on exit.

@vindex SDLStatusbar
@item SDLStatusbar
Boolean to enable/disable the statusbar
(all emulators except vsid).

@vindex SDLBitdepth
@item SDLBitdepth
Integer specifying the bitdepth used.
(0: current, 8, 15, 16, 24, 32)

@vindex SDLLimitMode
@item SDLLimitMode
Integer specifying the resolution limit mode.
(0: off, 1: max, 2: fixed)

@vindex SDLCustomWidth
@item SDLCustomWidth
Integer specifying the custom resolution width.

@vindex SDLCustomHeight
@item SDLCustomHeight
Integer specifying the custom resolution height.

@vindex JoyDevice1
@item JoyDevice1
Integer specifying which joystick device the emulator should use for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library))

@vindex JoyDevice2
@item JoyDevice2
Integer specifying which joystick device the emulator should use for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library))

@vindex JoyDevice3
@item JoyDevice3
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library))

@vindex JoyDevice4
@item JoyDevice4
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library))

@vindex CrtcSDLFullscreenMode
@item CrtcSDLFullscreenMode
Integer specifying the fullscreen mode
(xcbm2 and xpet only).

@vindex CrtcHwScale
@item CrtcHwScale
Boolean specifying whether to enable or disable hardware scaling
(xcbm2 and xpet only).

@vindex CrtcFullscreenDevice
@item CrtcFullscreenDevice
String specifying the fullscreen device
(xcbm2 and xpet only).

@vindex CrtcFullscreen
@item CrtcFullscreen
Boolean specifying whether to use fullscreen mode or not
(xcbm2 and xpet only).

@vindex CrtcFullscreenStatusbar
@item CrtcFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(xcbm2 and xpet only).

@vindex TEDSDLFullscreenMode
@item TEDSDLFullscreenMode
Integer specifying the fullscreen mode
(xplus4 only).

@vindex TEDHwScale
@item TEDHwScale
Boolean specifying whether to enable or disable hardware scaling
(xplus4 only).

@vindex TEDFullscreenDevice
@item TEDFullscreenDevice
String specifying the fullscreen device
(xplus4 only).

@vindex TEDFullscreen
@item TEDFullscreen
Boolean specifying whether to use fullscreen mode or not
(xplus4 only).

@vindex TEDFullscreenStatusbar
@item TEDFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(xplus4 only).

@vindex VDCSDLFullscreenMode
@item VDCSDLFullscreenMode
Integer specifying the fullscreen mode
(x128 only).

@vindex VDCHwScale
@item VDCHwScale
Boolean specifying whether to enable or disable hardware scaling
(x128 only).

@vindex VDCFullscreenDevice
@item VDCFullscreenDevice
String specifying the fullscreen device
(x128 only).

@vindex VDCFullscreen
@item VDCFullscreen
Boolean specifying whether to use fullscreen mode or not
(x128 only).

@vindex VDCFullscreenStatusbar
@item VDCFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(x128 only).

@vindex VICSDLFullscreenMode
@item VICSDLFullscreenMode
Integer specifying the fullscreen mode
(xvic only).

@vindex VICHwScale
@item VICHwScale
Boolean specifying whether to enable or disable hardware scaling
(xvic only).

@vindex VICFullscreenDevice
@item VICFullscreenDevice
String specifying the fullscreen device
(xvic only).

@vindex VICFullscreen
@item VICFullscreen
Boolean specifying whether to use fullscreen mode or not
(xvic only).

@vindex VICFullscreenStatusbar
@item VICFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(xvic only).

@vindex VICIISDLFullscreenMode
@item VICIISDLFullscreenMode
Integer specifying the fullscreen mode
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@vindex VICIIHwScale
@item VICIIHwScale
Boolean specifying whether to enable or disable hardware scaling
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@vindex VICIIFullscreenDevice
@item VICIIFullscreenDevice
String specifying the fullscreen device
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@vindex VICIIFullscreen
@item VICIIFullscreen
Boolean specifying whether to use fullscreen mode or not
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@vindex VICIIFullscreenStatusbar
@item VICIIFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@end table

@b{The following resources are only present if the OpenGL library is present and used at compile time.}

@table @code

@vindex AspectRatio
@item AspectRatio
String/float specifying the aspect ratio.
(0.5-2.0)

@vindex SDLGLAspectMode
@item SDLGLAspectMode
Integer specifying the OpenGL aspect mode.
(0: off, 1: custom, 2: true)

@vindex SDLGLFlipX
@item SDLGLFlipX
Boolean to enable/disable OpenGL horizontal screen flip.

@vindex SDLGLFlipY
@item SDLGLFlipY
Boolean to enable/disable OpenGL vertical screen flip.

@end table

@b{The following resources are only present if the SDL library has joystick support at compile time and applies to all emulators except vsid.}

@table @code

@vindex JoyMapFile
@item JoyMapFile
String specifying the name of the joystick map file.

@vindex JoyThreshold
@item JoyThreshold
Integer specifying the joystick threshold.
(0..32767)

@vindex JoyFuzz
@item JoyFuzz
Integer specifying the joystick fuzz.
(0..32767)

@end table

@ifset platformdingoo
@b{The following resource is only present if compiling for native dingoo.}

@table @code

@vindex OverClock
@item OverClock
Boolean to enable/disable overclocking.

@end table

@end ifset

@c @node FIXME
@subsection SDL specific command-line options

@table @code

@findex -hotkeyfile
@item -hotkeyfile <name>
Set the hotkey file name
(@code{HotkeyFile})
(all emulators except vsid).

@findex -menukey
@item -menukey <key>
Set the keycode of the SDL menu activation key
(@code{MenuKey}).

@findex -menukeyup
@item -menukeyup <key>
Set the keycode of the 'up' in the SDL menu
(@code{MenuKeyUp}).

@findex -menukeydown
@item -menukeydown <key>
Set the keycode of the 'down' in the SDL menu
(@code{MenuKeyDown}).

@findex -menukeyleft
@item -menukeyleft <key>
Set the keycode of the 'left' in the SDL menu
(@code{MenuKeyLeft}).

@findex -menukeyright
@item -menukeyright <key>
Set the keycode of the 'right' in the SDL menu
(@code{MenuKeyRight}).

@findex -menukeyselect
@item -menukeyselect <key>
Set the keycode of the 'select' in the SDL menu
(@code{MenuKeySelect}).

@findex -menukeycancel
@item -menukeycancel <key>
Set the keycode of the 'cancel' in the SDL menu
(@code{MenuKeyCancel}).

@findex -menukeyexit
@item -menukeyexit <key>
Set the keycode of the 'exit' in the SDL menu
(@code{MenuKeyExit}).

@findex -menukeymap
@item -menukeymap <key>
Set the keycode of the 'map' in the SDL menu
(@code{MenuKeyMap}).

@findex -saveres, +saveres
@item -saveres
@itemx +saveres
Enable/disable automatic saving of settings on exit
(@code{SaveResourcesOnExit=1}, @code{SaveResourcesOnExit=0}).

@findex -confirmexit, +confirmexit
@item -confirmexit
Confirm quitting VICE
(@code{ConfirmOnExit=1}).
@item +confirmexit
Never confirm quitting VICE
(@code{ConfirmOnExit=0}).

@findex -statusbar, +statusbar
@item -statusbar
@itemx +statusbar
Enable/disable the statusbar
(@code{SDLStatusbar=1}, @code{SDLStatusbar=0})
(all emulators except vsid).

@findex -sdlbitdepth
@item -sdlbitdepth <bpp>
Set the display bitdepth
(@code{SDLBitdepth}).
(0: current, 8, 15, 16, 24, 32)

@findex -sdllimitmode
@item -sdllimitmode <mode>
Set the resolution limit mode
(@code{SDLLimitMode}).
(0: off, 1: max, 2: fixed)

@findex -sdlcustomw
@item -sdlcustomw <width>
Set the custom resolution width
(@code{SDLCustomWidth}).

@findex -sdlcustomh
@item -sdlcustomh <height>
Set the custom resolution height
(@code{SDLCustomHeight}).

@findex -joydev1
@item -joydev1 <0-3> / <0-4>
Set the device for joystick emulation of port 1
(@code{JoyDevice1})
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library))

@findex -joydev2
@item -joydev2 <0-3> / <0-4>
Set the device for joystick emulation of port 2
(@code{JoyDevice2})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library))

@findex -extrajoydev1
@item -extrajoydev1 <0-3> / <0-4>
Set device for extra joystick port 1
(@code{JoyDevice3})
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library))

@findex -extrajoydev2
@item -extrajoydev2 <0-3> / <0-4>
Set device for extra joystick port 2
(@code{JoyDevice4})
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library))

@findex -CRTCSDLfullmode
@item -CRTCSDLfullmode <Mode>
Set the fullscreen mode
(@code{CrtcSDLFullscreenMode})
(xcbm2 and xpet only).

@findex -CRTChwscale, +CRTChwscale
@item -CRTChwscale
@itemx +CRTChwscale
Enable/Disable hardware scaling
(@code{CrtcHwScale=1}, @code{CrtcHwScale=0})
(xcbm2 and xpet only).

@findex -CRTCfulldevice
@item -CRTCfulldevice <device>
Select fullscreen device
(@code{CrtcFullscreenDevice})
(xcbm2 and xpet only).

@findex -CRTCfull, +CRTCfull
@item -CRTCfull
@itemx +CRTCfull
Enable/Disable fullscreen
(@code{CrtcFullscreen=1}, @code{CrtcFullscreen=0})
(xcbm2 and xpet only).

@findex -TEDSDLfullmode
@item -TEDSDLfullmode <Mode>
Set the fullscreen mode
(@code{TEDSDLFullscreenMode})
(xplus4 only).

@findex -TEDhwscale, +TEDhwscale
@item -TEDhwscale
@itemx +TEDhwscale
Enable/Disable hardware scaling
(@code{TEDHwScale=1}, @code{TEDHwScale=0})
(xplus4 only).

@findex -TEDfulldevice
@item -TEDfulldevice <device>
Select fullscreen device
(@code{TEDFullscreenDevice})
(xplus4 only).

@findex -TEDfull, +TEDfull
@item -TEDfull
@itemx +TEDfull
Enable/Disable fullscreen
(@code{TEDFullscreen=1}, @code{TEDFullscreen=0})
(xplus4 only).

@findex -VDCSDLfullmode
@item -VDCSDLfullmode <Mode>
Set the fullscreen mode
(@code{VDCSDLFullscreenMode})
(x128 only).

@findex -VDChwscale, +VDChwscale
@item -VDChwscale
@itemx +VDChwscale
Enable/Disable hardware scaling
(@code{VDCHwScale=1}, @code{VDCHwScale=1})
(x128 only).

@cindex -VDCfulldevice
@item -VDCfulldevice <device>
Select fullscreen device
(@code{VDCFullscreenDevice})
(x128 only).

@findex -VDCfull, +VDCfull
@item -VDCfull
@itemx +VDCfull
Enable/Disable fullscreen
(@code{VDCFullscreen=1}, @code{VDCFullscreen=0})
(x128 only).

@findex -VICSDLfullmode
@item -VICSDLfullmode <Mode>
Set the fullscreen mode
(@code{VICSDLFullscreenMode})
(xvic only).

@findex -VIChwscale, +VIChwscale
@item -VIChwscale
@item +VIChwscale
Enable/Disable hardware scaling
(@code{VICHwScale=1}, @code{VICHwScale=0})
(xvic only).

@findex -VICfulldevice
@item -VICfulldevice <device>
Select fullscreen device
(@code{VICFullscreenDevice})
(xvic only).

@findex -VICfull, +VICfull
@item -VICfull
@itemx +VICfull
Enable/Disable fullscreen
(@code{VICFullscreen=1}, @code{VICFullscreen=0})
(xvic only).

@findex -VICIISDLfullmode
@item -VICIISDLfullmode <Mode>
Set the fullscreen mode
(@code{VICIISDLFullscreenMode})
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@findex -VICIIhwscale, +VICIIhwscale
@item -VICIIhwscale
@itemx +VICIIhwscale
Enable/Disable hardware scaling
(@code{VICIIHwScale=1}, @code{VICIIHwScale=0})
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@findex -VICIIfulldevice
@item -VICIIfulldevice <device>
Select fullscreen device
(@code{VICIIFullscreenDevice})
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@findex -VICIIfull, +VICIIfull
@item -VICIIfull
@itemx +VICIIfull
Enable/Disable fullscreen
(@code{VICIIFullscreen=1}, @code{VICIIFullscreen=0})
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@end table

@b{The following command-line options are only present if the OpenGL library is present and used at compile time.}

@table @code

@findex -aspect
@item -aspect <aspect ratio>
Set the aspect ratio
(@code{AspectRatio}).
(0.5-2.0)

@findex -sdlaspectmode
@item -sdlaspectmode <mode>
Set the aspect mode
(@code{SDLGLAspectMode}).
(0: off, 1: custom, 2: true)

@findex -sdlflipx, +sdlflipx
@item -sdlflipx
@itemx +sdlflipx
Enable/disable OpenGL horizontal screen flip
(@code{SDLGLFlipX=1}, @code{SDLGLFlipX=0}).

@findex -sdlflipy, +sdlflipy
@item -sdlflipy
@itemx +sdlflipy
Enable/disable OpenGL vertical screen flip
(@code{SDLGLFlipY=1}, @code{SDLGLFlipY=0}).

@end table

@b{The following command-line options are only present if the SDL library has joystick support at compile time and applies
to all emulators except vsid.}

@table @code

@findex -joymap
@item -joymap <name>
Set the joystick map file name
(@code{JoyMapFile}).

@findex -joythreshold
@item -joythreshold <0-32767>
Set the joystick threshold
(@code{JoyThreshold}).

@findex -joyfuzz
@item -joyfuzz <0-32767>
Set the joystick fuzz
(@code{JoyFuzz}).

@end table

@end ifset

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

@ifset platformall
@node Unix-specific features, Mac OS X-specific features, SDL-specific features, Platform-specific features
@section Unix-specific features
@end ifset

@ifclear platformall
@ifset platformunix
@node Unix-specific features, , Platform-specific features, Platform-specific features
@section Unix-specific features
@end ifset
@end ifclear

@ifset platformunix
@menu
@ifset platformxaw
* XAW-specific features::
@end ifset
@ifset platformgtk
* GTK-specific features::
@end ifset
@end menu

This section lists the settings and commands that are common and specific to Unix, and are thus not present in other platforms. 

@c @node FIXME
@subsection Unix specific resources

@table @code

@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 ConfirmOnExit
@item ConfirmOnExit
Boolean specifying whether to show a confirmation dialog on exit.

@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 CrtcHwScale
@item CrtcHwScale
Boolean specifying whether to enable or disable hardware scaling
(xcbm2 and xpet only).

@vindex CrtcFullscreenDevice
@item CrtcFullscreenDevice
String specifying the fullscreen device
(xcbm2 and xpet only).

@vindex CrtcFullscreen
@item CrtcFullscreen
Boolean specifying whether to use fullscreen mode or not
(xcbm2 and xpet only).

@vindex CrtcFullscreenStatusbar
@item CrtcFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(xcbm2 and xpet only).

@vindex TEDHwScale
@item TEDHwScale
Boolean specifying whether to enable or disable hardware scaling
(xplus4 only).

@vindex TEDFullscreenDevice
@item TEDFullscreenDevice
String specifying the fullscreen device
(xplus4 only).

@vindex TEDFullscreen
@item TEDFullscreen
Boolean specifying whether to use fullscreen mode or not
(xplus4 only).

@vindex TEDFullscreenStatusbar
@item TEDFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(xplus4 only).

@vindex VDCHwScale
@item VDCHwScale
Boolean specifying whether to enable or disable hardware scaling
(x128 only).

@vindex VDCFullscreenDevice
@item VDCFullscreenDevice
String specifying the fullscreen device
(x128 only).

@vindex VDCFullscreen
@item VDCFullscreen
Boolean specifying whether to use fullscreen mode or not
(x128 only).

@vindex VDCFullscreenStatusbar
@item VDCFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(x128 only).

@vindex VICHwScale
@item VICHwScale
Boolean specifying whether to enable or disable hardware scaling
(xvic only).

@vindex VICFullscreenDevice
@item VICFullscreenDevice
String specifying the fullscreen device
(xvic only).

@vindex VICFullscreen
@item VICFullscreen
Boolean specifying whether to use fullscreen mode or not
(xvic only).

@vindex VICFullscreenStatusbar
@item VICFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(xvic only).

@vindex VICIIHwScale
@item VICIIHwScale
Boolean specifying whether to enable or disable hardware scaling
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@vindex VICIIFullscreenDevice
@item VICIIFullscreenDevice
String specifying the fullscreen device
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@vindex VICIIFullscreen
@item VICIIFullscreen
Boolean specifying whether to use fullscreen mode or not
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@vindex VICIIFullscreenStatusbar
@item VICIIFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@vindex JoyDevice1
@item JoyDevice1
Integer specifying which joystick device the emulator should use for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2)

@vindex JoyDevice2
@item JoyDevice2
Integer specifying which joystick device the emulator should use for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2)

@vindex JoyDevice3
@item JoyDevice3
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2)

@vindex JoyDevice4
@item JoyDevice4
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2)

@end table

@b{The available joysticks might differ depending on operating system and joystick support in the OS.}

@table @code

@item Devices 4..9
Only available if joystick support is available at compile time.

@item Devices 10 and 11
Only available if digital joystick support is available at compile time.

@item Devices 12 and 13
Only available if USB joystick support is available at compile time.

@end table

@b{The following resources are only available if MIDI support is available at compile time.}

@table @code

@vindex MIDIInDev
@item MIDIInDev
String specifying the MIDI input device
(x64, x64sc, xscpu64, x128 and xvic only).

@vindex MIDIOutDev
@item MIDIOutDev
String specifying the MIDI output device
(x64, x64sc, xscpu64, x128 and xvic only).

@end table

@b{The following resource is only available if MIDI support and ALSA support is available at compile time.}

@table @code

@vindex MIDIDriver
@item MIDIDriver
Enum specifying the MIDI driver
(x64, x64sc, xscpu64, x128 and xvic only).
(0: OSS, 1: ALSA)

@end table

@b{The following resources are only available if RS232 device support or RS232 network support is available at compile time.}

@table @code

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

@end table

@c @node FIXME
@subsection Unix specific command-line options

@table @code

@findex -saveres, +saveres
@item -saveres
@itemx +saveres
Enable/disable automatic saving of settings on exit
(@code{SaveResourcesOnExit=1}, @code{SaveResourcesOnExit=0}).

@findex -confirmexit, +confirmexit
@item -confirmexit
Confirm quitting VICE
(@code{ConfirmOnExit=1}).
@item +confirmexit
Never confirm quitting VICE
(@code{ConfirmOnExit=0}).

@findex -htmlbrowser
@item -htmlbrowser <Command>
Specify the command to run the HTML browser for the on-line help
(@code{HTMLBrowserCommand}).

@findex -CRTChwscale, +CRTChwscale
@item -CRTChwscale
@itemx +CRTChwscale
Enable/Disable hardware scaling
(@code{CrtcHwScale=1}, @code{CrtcHwScale=0})
(xcbm2 and xpet only).

@findex -CRTCfulldevice
@item -CRTCfulldevice <device>
Select fullscreen device
(@code{CrtcFullscreenDevice})
(xcbm2 and xpet only).

@findex -TEDhwscale, +TEDhwscale
@item -TEDhwscale
@itemx +TEDhwscale
Enable/Disable hardware scaling
(@code{TEDHwScale=1}, @code{TEDHwScale=0})
(xplus4 only).

@findex -TEDfulldevice
@item -TEDfulldevice <device>
Select fullscreen device
(@code{TEDFullscreenDevice})
(xplus4 only).

@findex -VDChwscale, +VDChwscale
@item -VDChwscale
@itemx +VDChwscale
Enable/Disable hardware scaling
(@code{VDCHwScale=1}, @code{VDCHwScale=1})
(x128 only).

@findex -VIChwscale, +VIChwscale
@item -VIChwscale
@item +VIChwscale
Enable/Disable hardware scaling
(@code{VICHwScale=1}, @code{VICHwScale=0})
(xvic only).

@findex -VICfulldevice
@item -VICfulldevice <device>
Select fullscreen device
(@code{VICFullscreenDevice})
(xvic only).

@findex -VICIIhwscale, +VICIIhwscale
@item -VICIIhwscale
@itemx +VICIIhwscale
Enable/Disable hardware scaling
(@code{VICIIHwScale=1}, @code{VICIIHwScale=0})
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@findex -VICIIfulldevice
@item -VICIIfulldevice <device>
Select fullscreen device
(@code{VICIIFullscreenDevice})
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@findex -joydev1
@item -joydev1 <0-3> / <0-9> / <0-11> / <0-13>
Set the device for joystick emulation of port 1
(@code{JoyDevice1})
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2)

@findex -joydev2
@item -joydev2 <0-3> / <0-9> / <0-11> / <0-13>
Set the device for joystick emulation of port 2
(@code{JoyDevice2})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2)

@findex -extrajoydev1
@item -extrajoydev1 <0-3> / <0-9> / <0-11> / <0-13>
Set device for extra joystick port 1
(@code{JoyDevice3})
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2)

@findex -extrajoydev2
@item -extrajoydev2 <0-3> / <0-9> / <0-11> / <0-13>
Set device for extra joystick port 2
(@code{JoyDevice4})
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2)

@end table

@b{The available joysticks might differ depending on operating system and joystick support in the OS.}

@table @code

@item Devices 4..9
Only available if joystick support is available at compile time.

@item Devices 10 and 11
Only available if digital joystick support is available at compile time.

@item Devices 12 and 13
Only available if USB joystick support is available at compile time.

@end table

@b{The following command-line options are only available if MIDI support is available at compile time.}

@table @code

@findex -midiin
@item -midiin <name>
Specify MIDI-In device
(@code{MIDIInDev})
(x64, x64sc, xscpu64, x128 and xvic only).

@findex -midiout
@item -midiout <name>
Specify MIDI-Out device
(@code{MIDIOutDev})
(x64, x64sc, xscpu64, x128 and xvic only).

@end table

@b{The following command-line option is only available if MIDI support and ALSA support is available at compile time.}

@table @code

@findex -mididrv
@item -mididrv <driver>
Specify MIDI driver
(@code{MIDIDriver})
(x64, x64sc, xscpu64, x128 and xvic only).
(0: OSS, 1: ALSA)

@end table

@b{The following command-line options are only available if RS232 device support or RS232 network support is available at compile time.}

@table @code

@findex -rsdev1baud
@item -rsdev1baud <baudrate>
@findex -rsdev2baud
@itemx -rsdev2baud <baudrate>
@findex -rsdev3baud
@itemx -rsdev3baud <baudrate>
@findex -rsdev4baud
@itemx -rsdev4baud <baudrate>
Specify <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})
(all emulators except vsid).

@end table

@end ifset

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

@ifset platformall
@node XAW-specific features, GTK-specific features, Unix-specific features, Unix-specific features
@subsection XAW-specific features
@end ifset

@ifclear platformall
@ifset platformxaw
@node XAW-specific features, , Unix-specific features, Unix-specific features
@subsection XAW-specific features
@end ifset
@end ifclear

@ifset platformxaw

This section lists the settings and commands that are common and specific to the XAW GUI, and are thus not present in other platforms. 

@c @node FIXME
@subsubsection XAW GUI specific resources

@table @code

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

@vindex PrivateColormap
@item PrivateColormap
Boolean specifying whether VICE should install a private colormap at
startup. This only makes sense for 8-bit displays that could run out of
colors if other color-hungry applications are running at the same time
(all emulators except vsid).

@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).
(-1: auto, 1: off, 2: on)

@vindex Window0Width
@vindex Window0Height
@vindex Window0Xpos
@vindex Window0Ypos
@item Window0Width
@itemx Window0Height
@itemx Window0Xpos
@itemx Window0Ypos
Integers specifying the position and size of the (first) emulator window
(all emulators except vsid).

@vindex Window1Width
@vindex Window1Height
@vindex Window1Xpos
@vindex Window1Ypos
@item Window1Width
@itemx Window1Height
@itemx Window1Xpos
@itemx Window1Ypos
Integers specifying the position and size of the (second) emulator window
(x128 only).

@end table

@b{The following resources are only available if Xvideo support is present at compile time.}

@table @code

@vindex AspectRatio
@item AspectRatio
String/float specifying the aspect ratio
(0.5-2.0).

@vindex KeepAspectRatio
@item KeepAspectRatio
Boolean specifying whether the aspect ratio of the output window should be preserved.
(0: free scaling, 1: scale with fixed aspect ratio)

@vindex TrueAspectRatio
@item TrueAspectRatio
Boolean specifying whether to use the true (non square pixels) aspect ratio.

@vindex FOURCC
@item FOURCC
String specifying the YUV FOURCC format to use.

@end table

@b{The following resources are only available if XRandr support is present at compile time.}

@table @code

@vindex UseFullscreen
@item UseFullscreen
Boolean specifying whether fullscreen mode is currently in use
(all emulators except vsid).

@vindex CrtcXRANDRFullscreenMode
@item CrtcXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode
(xcbm2 and xpet only).

@vindex TEDXRANDRFullscreenMode
@item TEDXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode
(xplus4 only).

@vindex VDCXRANDRFullscreenMode
@item VDCXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode
(x128 only).

@vindex VICXRANDRFullscreenMode
@item VICXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode
(xvic only).

@vindex VICIIXRANDRFullscreenMode
@item VICIIXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@end table

@b{The following resources are only available if VidMode support is present at compile time.}

@table @code

@vindex UseFullscreen
@item UseFullscreen
Boolean specifying whether fullscreen mode is currently in use.

@vindex CrtcVidmodeFullscreenMode
@item CrtcVidmodeFullscreenMode
integer specifying VidMode fullscreen mode
(xcbm2 and xpet only).

@vindex TEDVidmodeFullscreenMode
@item TEDVidmodeFullscreenMode
integer specifying VidMode fullscreen mode
(xplus4 only).

@vindex VDCVidmodeFullscreenMode
@item VDCVidmodeFullscreenMode
integer specifying VidMode fullscreen mode
(x128 only).

@vindex VICVidmodeFullscreenMode
@item VICVidmodeFullscreenMode
integer specifying VidMode fullscreen mode
(xvic only).

@vindex VICIIVidmodeFullscreenMode
@item VICIIVidmodeFullscreenMode
integer specifying VidMode fullscreen mode
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@end table

@c @node FIXME
@subsubsection XAW GUI specific command-line options

@table @code

@findex -displaydepth
@item -displaydepth <value>
Specify the display depth
(@code{DisplayDepth})
(all emulators except vsid).
(0..32)

@findex -colormap, +colormap
@item -colormap
@itemx +colormap
Enable/disable installation of a private colormap
(@code{PrivateColormap=1}, @code{PrivateColormap=0})
(all emulators except vsid).

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

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

@end table

@b{The following command-line options are only available if Xvideo support is present at compile time.}

@table @code

@findex -aspect
@item -aspect <aspect ratio>
Set the aspect ratio
(@code{AspectRatio}).
(0.5-2.0)

@findex -keepaspect, +keepaspect
@item -keepaspect
Enable keeping of the aspect ratio when scaling
(@code{KeepAspectRatio=1}).
@item +keepaspect
Disable keeping of the aspect ratio when scaling (freescaling)
(@code{KeepAspectRatio=0}).

@findex -trueaspect, +trueaspect
@item -trueaspect
@itemx +trueaspect
Enable/disable whether to use the true (non square pixels) aspect ratio
(@code{TrueAspectRatio=1}, (@code{TrueAspectRatio=0}).

@findex -fourcc
@item -fourcc <fourcc>
Set the YUV FOURCC format to use
(@code{FOURCC}).

@end table

@b{The following command-line options are only available if XRandr support is present at compile time.}

@table @code

@findex -fullscreen, +fullscreen
@item -fullscreen
@itemx +fullscreen
Enable/disable fullscreen mode
(@code{UseFullscreen=1}, (@code{UseFullscreen=0})
(all emulators except vsid).

@findex -CrtcXRANDRfullmode
@item -CrtcXRANDRfullmode <mode>
Select fullscreen mode
(@code{CrtcXRANDRFullscreenMode}).
(xcbm2 and xpet only)

@findex -TEDXRANDRfullmode
@item -TEDXRANDRfullmode <mode>
Select fullscreen mode
(@code{TEDXRANDRFullscreenMode}).
(xplus4 only)

@findex -VDCXRANDRfullmode
@item -VDCXRANDRfullmode <mode>
Select fullscreen mode
(@code{VDCXRANDRFullscreenMode}).
(x128 only)

@findex -VICXRANDRfullmode
@item -VICXRANDRfullmode <mode>
Select fullscreen mode
(@code{VICXRANDRFullscreenMode}).
(xvic only)

@findex -VICIIXRANDRfullmode
@item -VICIIXRANDRfullmode <mode>
Select fullscreen mode
(@code{VICIIXRANDRFullscreenMode}).
(all emulators except xcbm2, xpet, xplus4, xvic and vsid)

@end table

@b{The following command-line options are only available if VidMode support is present at compile time.}

@table @code

@findex -fullscreen, +fullscreen
@item -fullscreen
@itemx +fullscreen
Enable/disable fullscreen mode
(@code{UseFullscreen=1}, (@code{UseFullscreen=0}).

@findex -CrtcVidmodefullmode
@item -CrtcVidmodefullmode <mode>
Select fullscreen mode
(@code{CrtcVidmodeFullscreenMode}).
(xcbm2 and xpet only)

@findex -TEDVidmodefullmode
@item -TEDVidmodefullmode <mode>
Select fullscreen mode
(@code{TEDVidmodeFullscreenMode}).
(xplus4 only)

@findex -VDCVidmodefullmode
@item -VDCVidmodefullmode <mode>
Select fullscreen mode
(@code{VDCVidmodeFullscreenMode}).
(x128 only)

@findex -VICVidmodefullmode
@item -VICVidmodefullmode <mode>
Select fullscreen mode
(@code{VICVidmodeFullscreenMode}).
(xvic only)

@findex -VICIIVidmodefullmode
@item -VICIIVidmodefullmode <mode>
Select fullscreen mode
(@code{VICIIVidmodeFullscreenMode}).
(all emulators except xcbm2, xpet, xplus4, xvic and vsid)

@end table

@end ifset

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

@ifset platformall
@node GTK-specific features, , XAW-specific features, Unix-specific features
@subsection GTK-specific features
@end ifset

@ifclear platformall
@ifset platformgtk
@node GTK-specific features, , Unix-specific features, Unix-specific features
@subsection GTK-specific features
@end ifset
@end ifclear

@ifset platformgtk

This section lists the settings and commands that are common and specific to the GTK GUI, and are thus not present in other platforms. 

@c @node FIXME
@subsubsection GTK GUI specific resources

@table @code

@vindex KeepAspectRatio
@item KeepAspectRatio
Boolean specifying whether the aspect ratio of the output window should be preserved.
(0: free scaling, 1: scale with fixed aspect ratio)

@vindex TrueAspectRatio
@item TrueAspectRatio
Boolean specifying whether to use the true (non square pixels) aspect ratio.

@end table

@c @node FIXME
@subsubsection GTK GUI specific command-line options

@table @code

@findex -keepaspect, +keepaspect
@item -keepaspect
Enable keeping of the aspect ratio when scaling
(@code{KeepAspectRatio=1}).
@item +keepaspect
Disable keeping of the aspect ratio when scaling (freescaling)
(@code{KeepAspectRatio=0}).

@findex -trueaspect, +trueaspect
@item -trueaspect
@itemx +trueaspect
Enable/disable whether to use the true (non square pixels) aspect ratio
(@code{TrueAspectRatio=1}, (@code{TrueAspectRatio=0}).

@end table

@end ifset

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

@ifset platformall
@node Mac OS X-specific features, Windows-specific features, Unix-specific features, Platform-specific features
@section Mac OS X-specific features
@end ifset

@ifclear platformall
@ifset platformosx
@node Mac OS X-specific features, , Platform-specific features, Platform-specific features
@section Mac OS X-specific features
@end ifset
@end ifclear

@ifset platformosx

@c TODO: Mac OS X specific content

@end ifset

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

@ifset platformall
@node Windows-specific features, , Mac OS X-specific features, Platform-specific features
@section Windows-specific features
@end ifset

@ifclear platformall
@ifset platformwindows
@node Windows-specific features, , Platform-specific features, Platform-specific features
@section Windows-specific features
@end ifset
@end ifclear

@ifset platformwindows

This section lists the settings and commands that are common and specific to the Windows GUI, and are thus not present in other platforms. 

@c @node FIXME
@subsection Windows GUI specific resources

@table @code

@vindex MouseSensitivity
@item MouseSensitivity
Integer specifying the sensitivity of the mouse
(all emulators except xcbm2, xcbm5x0, xpet, xplus4 and vsid).
(0..40)

@vindex MonitorDimensions
@item MonitorDimensions
String that holds the dimensions and position in an encoded form.

@vindex InitialDefaultDir
@item InitialDefaultDir
String specifying the initial default directory, which is used by the generic file browser dialog.
@vindex InitialTapeDir

@item InitialTapeDir
String specifying the initial tape directory, which is used by the tape image file browser dialog
(all emulators except x64dtv, xscpu64 and vsid).

@vindex InitialDiskDir
@item InitialDiskDir
String specifying the initial tape directory, which is used by the disk image file browser dialog
(all emulators except vsid).

@vindex InitialAutostartDir
@item InitialAutostartDir
String specifying the initial autostart directory, which is used by the autostart image file browser dialog
(all emulators except vsid).

@vindex InitialCartDir
@item InitialCartDir
String specifying the initial cartridge directory, which is used by the cartridge image file browser dialog
(all emulators except x64dtv and vsid).

@vindex InitialSnapshotDir
@item InitialSnapshotDir
String specifying the initial snapshots directory, which is used by the snapshots file browser dialog (all emulators except vsid).

@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 ConfirmOnExit
@item ConfirmOnExit
Boolean specifying whether to show a confirmation dialog on exit.

@vindex SingleCPU
@item SingleCPU
Boolean specifying whether to use only the first CPU on an SMP system, or all CPUs.

@vindex Window0Xpos
@vindex Window0Ypos
@item Window0Xpos
@itemx Window0Ypos
Integers specifying the position and size of the (first) emulator window
(all emulators except vsid).

@vindex Window1Xpos
@vindex Window1Ypos
@item Window1Xpos
@itemx Window1Ypos
Integers specifying the position and size of the (second) emulator window
(x128 only).

@vindex AlwaysOnTop
@item AlwaysOnTop
Boolean specifying if the emulator window should stay on top of other windows.

@vindex JoyDevice1
@item JoyDevice1
Integer specifying which joystick device the emulator should use for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: joystick 2)

@vindex JoyDevice2
@item JoyDevice2
Integer specifying which joystick device the emulator should use for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: joystick 2)

@vindex JoyDevice3
@item JoyDevice3
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: joystick 2)

@vindex JoyDevice4
@item JoyDevice4
Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: joystick 2)

@vindex JoyAutofire1Speed
@item JoyAutofire1Speed
Integer specifying the autofire speed for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).
(0..32)

@vindex JoyAutofire2Speed
@item JoyAutofire2Speed
Integer specifying the autofire speed for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).
(0..32)

@vindex JoyAutofire3Speed
@item JoyAutofire3Speed
Integer specifying the autofire speed for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).
(0..32)

@vindex JoyAutofire4Speed
@item JoyAutofire4Speed
Integer specifying the autofire speed for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).
(0..32)

@vindex JoyAutofire1Button
@item JoyAutofire1Button
Integer specifying the the code of the button to use for autofire for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).

@vindex JoyAutofire2Button
@item JoyAutofire2Button
Integer specifying the the code of the button to use for autofire for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).

@vindex JoyAutofire3Button
@item JoyAutofire3Button
Integer specifying the the code of the button to use for autofire for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).

@vindex JoyAutofire4Button
@item JoyAutofire4Button
Integer specifying the the code of the button to use for autofire for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).

@vindex JoyFire1Button
@item JoyFire1Button
Integer specifying the the code of the button to use for fire for the emulation of joystick 1
(all emulators except xcbm2, xpet and vsid).

@vindex JoyFire2Button
@item JoyFire2Button
Integer specifying the the code of the button to use for fire for the emulation of joystick 2
(all emulators except xcbm2, xpet, xvic and vsid).

@vindex JoyFire3Button
@item JoyFire3Button
Integer specifying the the code of the button to use for fire for the emulation of extra joystick 1
(all emulators except xcbm5x0 and vsid).

@vindex JoyFire4Button
@item JoyFire4Button
Integer specifying the the code of the button to use for fire for the emulation of extra joystick 2
(all emulators except xcbm5x0, xplus4 and vsid).

@end table

@b{The following resources are only available if MIDI support is available at compile time.}

@table @code

@vindex MIDIInDev
@item MIDIInDev
Integer specifying the MIDI input device
(x64, x64sc, xscpu64, x128 and xvic only).

@vindex MIDIOutDev
@item MIDIOutDev
Integer specifying the MIDI output device
(x64, x64sc, xscpu64, x128 and xvic only).

@end table

@b{The following resources are only available if DirectX 9 support is available at compile time.}

@table @code

@vindex DX9Disable
@item DX9Disable
Boolean specifying whether to disable the DirectX 9 video driver and fall back on the GDI video driver
(all emulators except vsid).
(0: use GDI, 1: use DX9)

@vindex DXPrimarySurfaceRendering
@item DXPrimarySurfaceRendering
Boolean to enable/disable rendering to DirectX primary surface
(all emulators except vsid).

@vindex FullscreenEnabled
@item FullscreenEnabled
Boolean to enable/disable fullscreen mode
(all emulators except vsid).

@vindex FullscreenDevice
@item FullscreenDevice
Integer specifying the fullscreen device
(all emulators except vsid).

@vindex FullscreenWidth
@item FullscreenWidth
Integer specifying the width of the fullscreen display
(all emulators except vsid).

@vindex FullscreenHeight
@item FullscreenHeight
Integer specifying the height of the fullscreen display
(all emulators except vsid).

@vindex FullscreenRefreshRate
@item FullscreenRefreshRate
Integer specifying the refresh rate of the fullscreen display
(all emulators except vsid).

@vindex VBLANKSync
@item VBLANKSync
Boolean to enable/disable vertical blank sync
(all emulators except vsid).

@vindex KeepAspectRatio
@item KeepAspectRatio
Boolean specifying whether the aspect ratio of the output window should be preserved
(all emulators except vsid).
(0: free scaling, 1: scale with fixed aspect ratio)

@vindex TrueAspectRatio
@item TrueAspectRatio
Boolean specifying whether to use the true (non square pixels) aspect ratio
(all emulators except vsid).

@vindex AspectRatio
@item AspectRatio
Integer specifying the aspect ratio
(all emulators except vsid).
(500..2000)

@end table

@c @node FIXME
@subsection Windows GUI specific command-line options

@table @code

@findex -mousesensitivity
@item -mousesensitivity <sensitivity>
Set the sensitivity of the mouse
(@code{MouseSensitivity})
(all emulators except xcbm2, xcbm5x0, xpet, xplus4 and vsid).
(0..40)

@findex -initialdefaultdir
@item -initialdefaultdir <Name>
Select the initial default directory for the file browser dialog
(@code{InitialDefaultDir}).

@findex -initialtapedir
@item -initialtapedir <Name>
Select the initial tape images directory for the file browser dialog
(@code{InitialTapeDir})
(all emulators except x64dtv, xscpu64 and vsid).

@findex -initialdiskdir
@item -initialdiskdir <Name>
Select the initial disk images directory for the file browser dialog
(@code{InitialDiskDir})
(all emulators except vsid).

@findex -initialautostartdir
@item -initialautostartdir <Name>
Select the initial autostart directory for the file browser dialog
(@code{InitialAutostartDir})
(all emulators except vsid).

@findex -initialcartdir
@item -initialcartdir <Name>
Select the initial cartridge images directory for the file browser dialog
(@code{InitialCartDir})
(all emulators except x64dtv and vsid).

@findex -initialsnapshotdir
@item -initialsnapshotdir <Name>
Select the initial snapshot directory for the file browser dialog
(@code{InitialSnapshotDir})
(all emulators except vsid).

@findex -saveres, +saveres
@item -saveres
@itemx +saveres
Enable/disable automatic saving of settings on exit
(@code{SaveResourcesOnExit=1}, @code{SaveResourcesOnExit=0}).

@findex -confirmexit, +confirmexit
@item -confirmexit
Confirm quitting VICE
(@code{ConfirmOnExit=1}).
@item +confirmexit
Never confirm quitting VICE
(@code{ConfirmOnExit=0}).

@findex -singlecpu, +singlecpu
@item -singlecpu
Only use the first CPU on SMP systems
(@code{SingleCPU=1}).
@item +singlecpu
Use all CPUs on SMP systems
(@code{SingleCPU=0}).

@findex -alwaysontop, +alwaysontop
@item -alwaysontop
@itemx +alwaysontop
Enable/disable always on top feature
(@code{AlwaysOnTop=1}, @code{AlwaysOnTop=0}).

@findex -joydev1
@item -joydev1 <0-5>
Set the device for joystick emulation of port 1
(@code{JoyDevice1})
(all emulators except xcbm2, xpet and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: joystick 2)

@findex -joydev2
@item -joydev2 <0-5>
Set the device for joystick emulation of port 2
(@code{JoyDevice2})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: joystick 2)

@findex -extrajoydev1
@item -extrajoydev1 <0-5>
Set device for extra joystick port 1
(@code{JoyDevice3})
(all emulators except xcbm5x0 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: joystick 2)

@findex -extrajoydev2
@item -extrajoydev2 <0-5>
Set device for extra joystick port 2
(@code{JoyDevice4})
(all emulators except xcbm5x0, xplus4 and vsid).
(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick 1, 5: joystick 2)

@end table

@b{The following command-line options are only available if MIDI support is available at compile time.}

@table @code

@findex -midiin
@item -midiin <number>
Specify MIDI-In device
(@code{MIDIInDev})
(x64, x64sc, xscpu64, x128 and xvic only).

@findex -midiout
@item -midiout <number>
Specify MIDI-Out device
(@code{MIDIOutDev})
(x64, x64sc, xscpu64, x128 and xvic only).

@end table

@b{The following command-line options are only available if DirectX 9 support is available at compile time.}

@table @code

@findex -dx9disable
@item -dx9disable
Disable DirectX 9 video driver and fall back on the GDI video driver
(@code{DX9Disable=1})
(all emulators except vsid).

@findex -dx9enable
@item -dx9enable
Enable DirectX 9 video driver
(@code{DX9Disable=1})
(all emulators except vsid).

@findex -dxpsrender, +dxpsrender
@item -dxpsrender
@itemx +dxpsrender
Enable/disable rendering to DirectX primary surface
(@code{DXPrimarySurfaceRendering=1}, @code{DXPrimarySurfaceRendering=0})
(all emulators except vsid).

@findex -fullscreen, +fullscreen
@item -fullscreen
@itemx +fullscreen
Enable/Disable fullscreen mode
(@code{FullscreenEnabled=1}, @code{FullscreenEnabled=0})
(all emulators except vsid).

@findex -fullscreendevice
@item -fullscreendevice <number>
Specify fullscreen device
(@code{FullscreenDevice})
(all emulators except vsid).

@findex -vblanksync, +vblanksync
@item -vblanksync
@itemx +vblanksync
Enable/disable vertical blank sync
(@code{VBLANKSync=1}, @code{VBLANKSync=0})
(all emulators except vsid).

@findex -keepaspect, +keepaspect
@item -keepaspect
Enable keeping of the aspect ratio when scaling
(@code{KeepAspectRatio=1})
(all emulators except vsid).
@item +keepaspect
Disable keeping of the aspect ratio when scaling (freescaling)
(@code{KeepAspectRatio=0})
(all emulators except vsid).

@findex -trueaspect, +trueaspect
@item -trueaspect
@itemx +trueaspect
Enable/disable whether to use the true (non square pixels) aspect ratio
(@code{TrueAspectRatio=1}, (@code{TrueAspectRatio=0})
(all emulators except vsid).

@findex -aspect
@item -aspect <aspect ratio>
Set the aspect ratio
(@code{AspectRatio})
(all emulators except vsid).
(500..2000)

@end table

@end ifset

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

@node Snapshots, Monitor, Platform-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 and xcbm5x0 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 and xcbm5x0 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 DWWPIA
@tab 6520
@tab The PIA for the DWW hires board. 
@item CPU6809
@tab 6809
@tab The extra CPU in 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 and xcbm5x0 modules, Drive modules, xpet modules, Emulator modules
@subsubsection xcbm2 and xcbm5x0 modules

The modules in the xcbm2 and xcbm5x0 emulators 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

@node Drive modules,  , xcbm2 and xcbm5x0 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::
* CPU 6809 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, CPU 6809 module, Module framework, Module formats
@subsubsection CPU 6502 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 CPU 6809 module, CIA 6526 module, CPU 6502 module, Module formats
@subsubsection CPU 6809 module

This module saves the core 6809 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 WORD
@tab X
@tab The X register
@item WORD
@tab Y
@tab The Y register
@item WORD
@tab U
@tab The U register
@item WORD
@tab PC
@tab The Program Counter register
@item BYTE
@tab DP
@tab The Direct Page register
@item BYTE
@tab CC
@tab The Condition Code register
@item BYTE
@tab A
@tab The A register
@item BYTE
@tab B
@tab The B register
@item 
@tab 
@tab The following are for 6309 compatibility:
@item WORD
@tab V
@tab The V register
@item BYTE
@tab E
@tab The E register
@item BYTE
@tab F
@tab The F register
@end multitable

@node CIA 6526 module, VIA 6522 module, CPU 6809 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@dots{}
@item WORD
@tab HJITTER
@tab @dots{}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@dots{}
@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 three 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 "PETDWW" module is also
optional and contains the image of the hires expansion board (if
enabled).

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 3

@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.2
@item BYTE
@tab EOIBLANK
@tab bit 0=0 = EOI does not blank screen, bit 0=1 = EOI blanks screen.
@item --
@tab --
@tab The following items have been added in V1.3
@item WORD
@tab CPU_SWITCH
@tab 6502 / 6809 / PROG
@item BYTE
@tab VAL, PREVODD, WANTODD
@tab 6702 dongle state information
@item WORD[8]
@tab SHIFT
@item BYTE
@tab SuperPET config 2
@tab Extra bits due to the Super-OS/9 MMU. Bit 5: FIRQ disabled. Bit 6:
expansion memory in OS/9 flat mode.

@end multitable

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

In V1.3 the state for SuperPET has been added.

@b{The PETROM 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= $9*** ROM included. Bit 1: 1= $A*** ROM included. Bit 2: 1= $B*** ROM included. Bit 3: 1= $e900-$efff ROM included. Bit 4: 1= SuperPET ROMs 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)
@item --
@tab --
@tab The following items have been added in V1.1
@item ROM6809
@tab ROM6809
@tab 24k $A000-$FFFF ROM   (if CONFIG & 16)
@item ARRAY
@tab CHARGEN(2)
@tab upper half of CHARGEN (if CONFIG & 16)
@end multitable

@b{The PETDWW module}

For storing the state of the DWW hires expansion board, there is a
PETDWWPIA module, and a DWWMEM module.

The former has the same format as the PIA1.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item WORD
@tab SIZE
@tab The size of the memory dump that follows, or 0 if DWW disabled.
@item ARRAY
@tab MEM
@tab The memory in the DWW card, SIZE bytes.
@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 -----------------------------------------------------------------
@c @node FIXME
@chapter Media images

@c FIXME: add some info on making screenshots, wav- and avi recordings

@c @node FIXME
@section Media images resources

@table @code

@vindex DoodleOversizeHandling
@item DoodleOversizeHandling
Integer specifying the way the oversized input should be handled
(all emulators except vsid).
(0: scale down, 1: crop left top, 2: crop center top,
3: crop right top, 4: crop left center, 5: crop center,
6: crop right center, 7: crop left bottom, 8: crop center bottom, 
9: crop right bottom)

@vindex DoodleUndersizeHandling
@item DoodleUndersizeHandling
Integer specifying the way the undersized input should be handled
(all emulators except vsid).
(0: scale, 1: borderize)

@vindex DoodleMultiColorHandling
@item DoodleMultiColorHandling
Integer specifying the way the multicolor to hires should be handled
(all emulators except vsid).
(0: b&w, 1: 2 colors, 2: 4 colors, 3: gray scale,  4: best cell colors)

@vindex DoodleTEDLumHandling
@item DoodleTEDLumHandling
Integer specifying the way the TED luminosity should be handled
(all emulators except vsid).
(0: ignore, 1: dither)

@vindex DoodleCRTCTextColor
@item DoodleCRTCTextColor
Integer specifying the text color used when making screenshots from a CRTC window in doodle format
(all emulators except vsid).
(0: white, 1: amber, 2: green)

@vindex KoalaOversizeHandling
@item KoalaOversizeHandling
Integer specifying the way the oversized input should be handled
(all emulators except vsid).
(0: scale down, 1: crop left top, 2: crop center top,
3: crop right top, 4: crop left center, 5: crop center,
6: crop right center, 7: crop left bottom, 8: crop center bottom, 
9: crop right bottom)

@vindex KoalaUndersizeHandling
@item KoalaUndersizeHandling
Integer specifying the way the undersized input should be handled
(all emulators except vsid).
(0: scale, 1: borderize)

@vindex KoalaTEDLumHandling
@item KoalaTEDLumHandling
Integer specifying the way the TED luminosity should be handled
(all emulators except vsid).
(0: ignore, 1: dither)

@vindex KoalaCRTCTextColor
@item KoalaCRTCTextColor
Integer specifying the text color used when making screenshots from a CRTC window in doodle format
(all emulators except vsid).
(0: white, 1: amber, 2: green)

@vindex FFMPEGFormat
@item FFMPEGFormat
String specifying the current FFMPEG output driver.
@vindex FFMPEGAudioBitrate
@item FFMPEGAudioBitrate
Integer specifying the current FFMPEG audio bitrate.
@vindex FFMPEGVideoBitrate
@item FFMPEGVideoBitrate
Integer specifying the current FFMPEG video bitrate.
@vindex FFMPEGAudioCodec
@item FFMPEGAudioCodec
Integer specifying the current FFMPEG audio codec.
@vindex FFMPEGVideoCodec
@item FFMPEGVideoCodec
Integer specifying the current FFMPEG video codec.
@vindex FFMPEGVideoHalveFramerate
@item FFMPEGVideoHalveFramerate
Boolean, if true record only every other frame.

@end table

@c @node FIXME
@section Media images command-line options

@table @code

@findex -doodleoversize
@item -doodleoversize <method>
Select the way the oversized input should be handled
(@code{DoodleOversizeHandling})
(all emulators except vsid).
(0: scale down, 1: crop left top, 2: crop center top,
3: crop right top, 4: crop left center, 5: crop center,
6: crop right center, 7: crop left bottom,
8: crop center bottom, 9: crop right bottom)

@findex -doodleundersize
@item -doodleundersize <method>
Select the way the undersized input should be handled
(@code{DoodleUndersizeHandling})
(all emulators except vsid).
(0: scale, 1: borderize)

@findex -doodlemc
@item -doodlemc <method>
Select the way the multicolor to hires should be handled
(@code{DoodleMultiColorHandling})
(all emulators except vsid).
(0: b&w, 1: 2 colors, 2: 4 colors, 3: gray scale, 4: best cell colors)

@findex -doodletedlum
@item -doodletedlum <method>
Select the way the TED luminosity should be handled
(@code{DoodleTEDLumHandling})
(all emulators except vsid).
(0: ignore, 1: dither)

@findex -doodlecrtctextcolor
@item -doodlecrtctextcolor <color>
Select the CRTC text color
(@code{DoodleCRTCTextColor})
(all emulators except vsid).
(0: white, 1: amber, 2: green)

@findex -koalaoversize
@item -koalaoversize <method>
Select the way the oversized input should be handled
(@code{KoalaOversizeHandling})
(all emulators except vsid).
(0: scale down, 1: crop left top, 2: crop center top,
3: crop right top, 4: crop left center, 5: crop center,
6: crop right center, 7: crop left bottom,
8: crop center bottom, 9: crop right bottom)

@findex -koalaundersize
@item -koalaundersize <method>
Select the way the undersized input should be handled
(@code{KoalaUndersizeHandling})
(all emulators except vsid).
(0: scale, 1: borderize)

@findex -koalatedlum
@item -koalatedlum <method>
Select the way the TED luminosity should be handled
(@code{KoalaTEDLumHandling})
(all emulators except vsid).
(0: ignore, 1: dither)

@findex -koalacrtctextcolor
@item -koalacrtctextcolor <color>
Select the CRTC text color
(@code{KoalaCRTCTextColor})
(all emulators except vsid).
(0: white, 1: amber, 2: green)

@cindex -ffmpegaudiobitrate
@item -ffmpegaudiobitrate <value>
Set bitrate for audio stream in media file
@cindex -ffmpegvideobitrate
@item -ffmpegvideobitrate <value>
Set bitrate for video stream in media file

@end table

@c -----------------------------------------------------------------
@c @node FIXME
@chapter Event history

@c FIXME: the "Event history" section needs to be style-checked.

VICE supports recording an arbitrary session on the emulated machine and
playing back this session later. This is done by saving a snapshot at the beginning
of the recording session and then remembering all the user interaction such as
keyboard and joystick input. We call this an 'event history'.
The main purpose for having an event history is to create game sessions, e.g. recording 
how to solve a game. An example walkthrough for the well known game "Fort Apocalypse" is
available.

This brief chapter will advise you how to record and playback such a session.
Although it is based on the WinVICE x64 release and its user interface, histories may be
transferred to other machines and other ports that support event history, e.g. the
Unix port.

@c @node FIXME
@section Recommended Settings

When using the event history feature it is possible that the playback session
differs from what was done at recording time. This might arise due to a problem 
in the initial snapshot or settings.
Here are some suggestions to minimize the chance of failures in the session:
a. Reset to default settings.
b. Choose refresh rate 1/1.
c. Choose joystick and Video/Doublesize settings as desired or needed.
d. SID engine must be reSID (which is the default).
e. Choose Drive settings/Idle method: None
Do not change any settings during recording or playback!

@c @node FIXME
@section Recorded Events

The following is a list of the user interaction that will be recorded:
- Joystick movement and button
- Keyboard
- Resetting the machine (hard and soft)
- Attaching or detaching disk/tape images (see 8. Limitations)
- Datasette controls

@c @node FIXME
@section Recording an Event History

Recording an event history will create one or two files for a snapshot and
the list of the user events. First, create an empty directory in which these
files are to be saved and then select this directory and the name of the 
snapshot files via 'Snapshot//Select History files/directory'. 
Next, attach the disk or tape image with the game you want to record and load and
run the game.

Start recording via 'Snapshot//Start/Stop Recording History'.
Play the game. All actions will be recorded.
After the game is finished, stop recording via 'Snapshot//Start/Stop
Recording History'. The selected directory should now contain the two
snapshot files (default ist start.vsf and end.vsf). 

@c @node FIXME
@section Setting and Returning to Milestones

It is difficult to finish a game in one sitting and noone wants to
record all their mistakes and lost lives. Use the milestone feature in a
recording session in the following way:

Set a milestone when you have finished a level or completed a task
('Snapshot//Set recording milestone' or ALT-E). This will save the event
history and a snapshot of the machine to the file end.vsf but recording will
continue.

Return to the last milestone when you have made a mistake or lost a life
('Snapshot//Return to milestone' or ALT-U). This will reset the game and the
event history to the last milestone snapshot so that you can try again.

@c @node FIXME
@section Continuing an Event History

If you have stopped a recording session and want to continue it later, you
should create a backup of your start.vsf and end.vsf files first to avoid
overwriting them by accident.

Then change the event history start mode: 'Snapshot//Recording start mode//Load
existing snapshot'. When you start recording now, you will continue where the
session was stopped last time.

Another way of continuing an existing history is to start somewhere inside the
history (e.g. you have recorded 10 minutes of a game and later recognize that you
made a mistake after 6 minutes that makes it impossible to finish the game).
For this you have to select the start mode 'Overwrite playback'. Now you can
start the playback with 'Snapshot//Start/Stop Playback History' and when you
reach the point where you want to change the history you can directly switch to
recording via 'Snapshot//Start/Stop Recording History'.

@c @node FIXME
@section Playing Back an Event History

To play back an event history, select the directory with the history files
start.vsf and end.vsf via 'Snapshot//Select History directory' and start the
playback with 'Snapshot//Start/Stop Playback History'. Enjoy!
During playback any user interaction is disabled.
The playback stops when the end of the session is reached or if 
'Snapshot//Select History directory' is selected again.

@c @node FIXME
@section Limitations and Suggestions

a. Snapshot files will be quite big (>1MB) if a disk image has been attached. 
If possible, use PRG or T64 images to reduce the size of snapshot files.
b. Snapshots may not be 100% accurate even with all the recommended settings.


@c @node FIXME
@section Event history resources

@table @code

@vindex EventSnapshotDir
@item EventSnapshotDir
String specifying the directory used for loading and saving snapshots
(all emulators except vsid).

@vindex EventStartSnapshot
@item EventStartSnapshot
String specifying the filename for the start snapshot
(all emulators except vsid).

@vindex EventEndSnapshot
@item EventEndSnapshot
String specifying the filename for the end snapshot
(all emulators except vsid).

@vindex EventStartMode
@item EventStartMode
Integer specifying how to start event recording
(all emulators except vsid).
(0: save new snapshot, 1: load existing snapshot, 2: reset, 3: playback)

@vindex EventImageInclude
@item EventImageInclude
Boolean specifying whether to include ROM and Disk images in the snapshots
(all emulators except vsid).

@end table

@c @node FIXME
@section Event history command-line options

@table @code
@findex -playback
@item -playback
Playback recorded events
(all emulators except vsid).

@findex -eventsnapshotdir
@item -eventsnapshotdir <Name>
Set event snapshot directory
(@code{EventSnapshotDir})
(all emulators except vsid).

@findex -eventstartsnapshot
@item -eventstartsnapshot <Name>
Set event start snapshot filename
(@code{EventStartSnapshot})
(all emulators except vsid).

@findex -eventendsnapshot
@item -eventendsnapshot <Name>
Set event end snapshot filename
(@code{EventEndSnapshot})
(all emulators except vsid).

@findex -eventstartmode
@item -eventstartmode <Mode>
Set event start mode
(@code{EventStartMode})
(all emulators except vsid).
(0: save new snapshot, 1: load existing snapshot, 2: reset, 3: playback)

@findex -eventimageinc / +eventimageinc
@item -eventimageinc
@itemx +eventimageinc
Enable/disable the inclusion of disk images in the event
(@code{EventImageInclude=1}, @code{EventImageInclude=0})
(all emulators except vsid).

@end table

@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 in some
ports you have to run the emulator from a terminal emulation program (such as
@code{rxvt} or @code{xterm}) in order to use the monitor.

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

@item label
@code{label} is the name of a label. It must start with a dot (".")
in order for the monitor to recognize it as a label. Register names preceeded
by a dot (for example @code{.PC}) are special labels that evaluate to value of
the respective register at the time it is used, and thus can not be used as
a regular label.

@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 memmap
The memmap keeps track of RAM/ROM/IO read/write/execute
accesses. The feature must be enabled with "--enable-memmap"
configure option, as it might decrease performance notably on
slower hardware. The option also enables CPU history.

@item <@dots{}>
A data type.

@item *
Zero or more occurrences.

@item [@dots{}]
An optional argument.

@end table

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

@table @code

@item backtrace
@itemx bt
Print JSR call chain (most recent call first). Stack offset
relative to SP+1 is printed in parentheses. This is a best guess
only.

@item cpuhistory [<count>]
@itemx chis [<count>]
Show <count> last executed commands.
(disabled by default; configure with --enable-memmap to enable)

@item dump "<filename>"
Write a snapshot of the machine into the file specified.
This snapshot is compatible with a snapshot written out by the UI.
Note: No ROM images are included into the dump.

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

@item io [<address>]
Display i/o registers. Invoking without an address shows a dump of
the entire io range, if an address is given then details for the
chip at the respective (base-)address are displayed (if available).

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

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

@item reset [<type>]
Reset the machine or drive.
@code{type}: 0 = soft, 1 = hard, 8-11 = drive.

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

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

@item stopwatch [reset]
Print the CPU cycle counter of the current device. 'reset' sets the counter to 0.

@item undump "<filename>"
Read a snapshot of the machine from the file specified.

@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>
@itemx c <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>
@itemx f <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>
@itemx h <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.
The data list may have `xx' as a wildcard.

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

@item ii <address_opt_range>
Display memory contents as screen code text

@item mem [<data_type>] [<address_opt_range>]
@itemx 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 memmapshow [<mask>] [<address_opt_range>]
@itemx mmsh [<mask>] [<address_opt_range>]
Show the memmap. The mask can be specified to show only those
locations with accesses of certain type(s). The mask is a number
with the bits "ioRWXrwx", where RWX are for ROM and rwx for RAM.
Optionally, an address range can be specified.
(disabled by default; configure with --enable-memmap to enable)

@item memmapzap
@itemx mmzap
Clear the memmap.
(disabled by default; configure with --enable-memmap to enable)

@item memmapsave "<filename>" <format>
@itemx mmsave "<filename>" <format>
Save the memmap as a picture. @code{format}:
0 = BMP, 1 = PCX, 2 = PNG, 3 = GIF, 4 = IFF.
(disabled by default; configure with --enable-memmap to enable)

@item memchar [<data_type>] [<address_opt_range>]
@itemx 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 memsprite [<data_type>] [<address_opt_range>]
@itemx 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>
@itemx t <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 screen
@itemx sc
Displays the contents of the screen.

@item sidefx [on|off|toggle]
@itemx sfx [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 disass [<address> [<address>]]
@itemx 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 [load|store|exec] [address [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.
The "load|store|exec" parameter can be either "load", "store" or "exec"
(or any combination of these) to determine on which operation the
monitor breaks. If not specified, the monitor breaks on "exec".
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>
@itemx cond <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.

Currently, the cond_expr is very limited. You can use registers (.A, .X,
.Y, .PC, and .SP) and compare against other registers or absolute
values. For example, the following are all valid conditions:
.A == 0, .X == .Y, 8:.X == .X, .A != 5, .A < .X.

However, you cannot specify memory contents and compare that.


@item delete <checknum>
@itemx del <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 [load|store|exec] [address [address] [if <cond_expr>]]
@itemx tr [load|store|exec] [address [address] [if <cond_expr>]]
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.
If no addresses are given, a list of all the checkpoints is printed.
The "load|store|exec" parameter can be either "load", "store" or "exec"
(or any combination of these) to determine which operation the
monitor traces. If not specified, the monitor traces all operations.
A conditional expression can also be specified for the tracepoint.
For more information on conditions, see the CONDITION command.

@item until [<address>]
@itemx un [<address>]
If no address is given, the currently valid breakpoints are printed.
If an address is given, a temporary breakpoint is set for that address
and the breakpoint number is printed.  Control is returned to the
emulator by this command.  The breakpoint is deleted once it is hit.

@item watch [load|store|exec] [address [address] [if <cond_expr>]]
@itemx w [load|store|exec] [address [address] [if <cond_expr>]]
This command is similar to the @code{break} command except that it
operates on watchpoints.  A watchpoint differs from a breakpoint 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 checkpoints is printed.
The "load|store|exec" parameter can be either "load", "store" or "exec"
(or any combination of these) to determine on which operation the
monitor breaks. If not specified, the monitor breaks on "load" and
"store" operations.
A conditional expression can also be specified for the watchpoint.
For more information on conditions, see the CONDITION command.

@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:|8:|9:]
@itemx dev [c:|8:|9:]
Set the default address space to either the computer (@code{c:}) or
the disk (@code{8:|9:}).

@item dir [<directory>]
@itemx ls [<directory>]
Display the directory contents.

@item pwd
Show current working directory.

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

@end table


@node Disk commands, Command file commands, General commands, Monitor
@section Disk commands

@table @code

@item attach <filename> <device>
Attach file to device. (device 32 = cart)

@item block_read <track> <sector> [<address>]
@itemx 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 block_write <track> <sector> <address>
@itemx bw <track> <sector> <address>
Write a block of data at @code{address} to the specified track and
sector of disk in drive 8.

@item detach <device>
Detach file from device. (device 32 = cart)

@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>]
@itemx l "<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 list [<directory>]
List disk contents.

@item bload "<filename>" <device> <address>
@itemx bl "<filename>" <device> <address>
Load the specified file into memory at the specified address.
If device is 0, the file is read from the file system.

@item save "<filename>" <device> <address1> <address2>
@itemx s "<filename>" <device> <address1> <address2>
Save the memory from address1 to address2 to the specified file.
Write two-byte load address.
If device is 0, the file is written to the file system.

@item bsave "<filename>" <device> <address1> <address2>
@itemx bs "<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.

@end table


@node Command file commands, Label commands, Disk commands, Monitor
@section Command file commands


@table @code

@item playback "<filename>"
@itemx pb "<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>"
@itemx rec "<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>
@itemx al <address> <label>
Map a given address to a label.  This label can be used when entering
assembly code and is shown during disassembly.  Additionally, it can
be used whenever an address must be specified.

<label> is the name of the label; it must start with a dot (".") in
order for the monitor to recognize it as a label.

@item delete_label [<address_space>] <label>
@itemx dl [<address_space>] <label>
Remove the specified label from the label tables.  If no address space is
checked, all tables are checked.

@item load_labels [<address_space>] "<filename>"
@itemx ll [<address_space>] "<filename>"
Load a file containing a mapping of labels to addresses.  If no address
space is specified, the default readspace is used.

The file must contain commands the monitor understands, e.g. add_label. The
compiler cc65 can create such label files.

Vice can also load label files created by the Acme assembler. Their syntax is
e.g. "labelname = $1234 ; Maybe a comment". A dot will be added automatically
to label names assigned in this way to fit to the Vice label syntax. Normally
the semicolon seperates commands but after an assignment of this kind it may be
used to start a comment to end of line, so unchanged Acme label files can be
fed into Vice.

@item save_labels [<address_space>] "<filename>"
@itemx sl [<address_space>] "<filename>"
Save labels to a file.  If no address space is specified, all of the
labels are saved.

@item show_labels [<address_space>]
@itemx shl [<address_space>]
Display current label mappings.  If no address space is specified, show
all labels.

@end table


@node Miscellaneous commands,  , Label commands, Monitor
@section Miscellaneous commands


@table @code

@item cartfreeze
Use cartridge freeze.

@item cpu <type>
Specify the type of CPU currently used (6502/z80).

@item exit
@itemx x
Leave the monitor and return to execution.

@item export
@itemx exp
Print out list of attached expansion port devices.

@item help [<command>]
If no argument is given, prints out a list of all available commands.
If an argument is given, prints out specific help for that command.

@item keybuf "<string>"
Put the specified string into the keyboard buffer. Note that you can specify
specific keycodes by using C-style escaped hexcodes ("\x0a").

@item print <expression>
@itemx p <expression>
Evaluate the specified expression and output the result.

@item resourceget "<resource>"
@itemx resget "<resource>"
Displays the value of the @code{resource}.

@item resourceset "<resource>" "<value>"
@itemx resset "<resource>" "<value>"
Sets the value of the @code{resource}.

@item load_resources "<file>"
@itemx resload "<file>"
Load resources from @code{file}.

@item save_resources "<file>"
@itemx ressave "<file>"
Save resources to @code{file}.

@item screenshot "<filename>" [<format>]
@itemx scrsh "<filename>" [<format>]
Take a screenshot. @code{format}:
default = BMP, 1 = PCX, 2 = PNG, 3 = GIF, 4 = IFF.

@item tapectrl <command>
Control the datasette. @code{command}:
0 = stop, 1 = start, 2 = forward, 3 = rewind, 4 = record,
5 = reset, 6 = reset counter.

@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''
menu item which will open a new terminal window with a running
@code{c1541} in it.

The syntax is:

@example
c1541 [IMAGE1 [IMAGE2]] [COMMAND1 COMMAND2 @dots{} 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> @dots{} <sourceN>] <destination>
Copy @code{source1} @dots{} @code{sourceN} into destination.  If N > 1,
@code{destination} must be a simple drive specifier (@code{@@n:}).

@item delete <file1> [<file2> @dots{} <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 geosread <source> [<destination>]
Read GEOS <source> from the disk image and copy it as a Convert file into
<destination> in the file system.  If <destination> is not specified, copy
it into a file with the same name as <source>.

@item geoswrite <source>
Write GOES Convert file <source> from the file system on a disk image.

@item geosextract <source>
Extract all the files to the file system and GEOS Convert them.

@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>]
@item dir [<pattern>]
List files matching @code{pattern} (default is all files).

@item name <diskname>[,<id>] <unit>
Change image name.

@item p00save <enable> [<unit>]
Save P00 files to the file system.

@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 show [copying | warranty]
Show conditions for redistributing copies of C1541 (`copying') or the
various kinds of warranty you do not have with C1541 (`warranty').

@item tape <t64name> [<file1> @dots{} <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 verbose
Enable verbose output.

@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 @node FIXME
@section c1541 examples

@c FIXME: add more c1541 examples

@table @code
@item c1541 -attach test.d64 -list
Attach @code{test.d64} and show directory.

@item c1541 -attach test.d64 -write test.prg testfile
Write @code{test.prg} to @code{test.d64} as @code{testfile}.

@item c1541 -format "name,id" d64 disk.d64
Create a disk image in @code{d64} format, format it with the @code{name} and @code{id} and save it to @code{disk.d64}.
@end table

@c @node FIXME
@chapter cartconv

The cartconv program is a cartridge conversion utility, it can convert
between binary and .crt images and it can 'insert' binary and/or
.crt images into the EPROM type of cartridges.

@section cartconv command line options

The cartconv program has the following parameters:

@table @code
@cindex -i
@item -i "input name"
This parameter is mandatory, it should contain the name of the binary/.crt
file you want to convert. For the EPROM type of cartridges this parameter
can be used multiple times to insert images into the resulting file.
@cindex -o
@item -o "output name"
This parameter is mandatory, it should contain the name of the binary/.crt
file you want to convert the input file to.
@cindex -t
@item -t carttype
This parameter is optional. It is only needed when converting to a .crt
file. See below for the supported cartridge types.
@cindex -n
@item -n "cart name"
This parameter is optional and is used as the cartridge name when creating
a .crt file.
@cindex -l
@item -l loadaddress
This parameter is optional and is used as the load-address when converting
a .crt file to a .prg file, or when converting to a generic type .crt
file.
@cindex -f
@item -f "input name"
This parameter is optional, and is meant to output information about the
named file. It can't be used in conjuction with any of the other parameters.
@cindex -r
@item -r
This parameter is optional, it enables repair mode (accept broken input files)
@cindex -q
@item -q
This parameter is optional, it disables all non-error messages
@end table

The following cartridge types are supported:

@table @code
@item bin
Binary .bin file (Default crt->bin)
@item normal
Generic 8kB/12kB/16kB .crt file (Default bin->crt)
@item prg
Binary C64 .prg file with load-address
@item ulti
Ultimax mode 4kB/8kB/16kB .crt file
@item ap
Atomic Power .crt file
@item ar2
Action Replay MK2 .crt file
@item ar3
Action Replay MK3 .crt file
@item ar4
Action Replay MK4 .crt file
@item ar5
Action Replay V5 .crt file
@item cap
Capture .crt file
@item comal
Comal 80 .crt file
@item dep256
Dela EP256 .crt file, extra files can be inserted (1)(2)
@item dep64
Dela EP64 .crt file, extra files can be inserted (1)
@item dep7x8
Dela EP7x8 .crt file, extra files can be inserted (1)(2)(3)
@item din
Dinamic .crt file
@item dsm
Diashow-Maker .crt file
@item easy
EasyFlash .crt file
@item epyx
Epyx FastLoad .crt file
@item exos
EXOS .crt file
@item expert
Expert Cartridge .crt file
@item fc1
The Final Cartridge .crt file
@item fc3
The Final Cartridge III .crt file
@item fcp
Final Cartridge Plus .crt file
@item ff
Freeze Frame .crt file
@item fm
Freeze Machine .crt file
@item fp
Fun Play .crt file
@item gk
Game Killer .crt file
@item gs
C64 Games System .crt file
@item ide64
IDE64 .crt file
@item ieee
IEEE-488 Interface .crt file
@item kcs
KCS Power Cartridge .crt file
@item mach5
MACH 5 .crt file
@item md
Magic Desk .crt file
@item mf
Magic Formel .crt file
@item mikro
Mikro Assembler .crt file
@item mmc64
MMC64 .crt file
@item mmcr
MMC Replay .crt file
@item mv
Magic Voice .crt file
@item ocean
Ocean .crt file
@item p64
Prophet64 .crt file
@item rep256
REX 256k EPROM Cart .crt file, extra files can be inserted (1)(2)(3)
@item rgcd
RGCD .crt file
@item ross
ROSS .crt file
@item rr
Retro Replay .crt file
@item ru
REX Utility .crt file
@item s64
Snapshot 64 .crt file
@item sb
Structured BASIC .crt file
@item se5
Super Explode V5.0 .crt file
@item sg
Super Games .crt file
@item simon
Simons' BASIC .crt file
@item ss4
Super Snapshot V4 .crt file
@item ss5
Super Snapshot V5 .crt file
@item star
Stardos .crt file
@item wl
Westermann Learning .crt file
@item ws
Warp Speed .crt file
@item zaxxon
Zaxxon .crt file
@end table

@itemize @bullet
@item (1) insertion of 32kB EPROM files supported.
@item (2) insertion of 8kB .crt/binary files supported.
@item (3) insertion of 16kB .crt/binary files supported.
@end itemize

@c @node FIXME
@section cartconv examples

@table @code
@item cartconv -i foo.crt -o foo.bin
Convert a .crt file to a binary file with no load-address.
@item cartconv -t prg -i foo.crt -o foo.prg
Convert a .crt file to a .prg file with default load-address.
@item cartconv -t prg -l 49152 -i foo.crt -o foo.prg
Convert a .crt file to a .prg file with 49152 as the load-address.
@item cartconv -t ocean -i foo.bin -o foo.crt
Convert a binary file to an ocean type cartridge.
@item cartconv -t dep64 -i dep64.bin -i eprom.prg -o foo.crt
Inserting a 32kB EPROM file into an dep64 type cartridge.
@itemize @bullet
@item step 1 : use the dep64 binary file in VICE as a generic 8kB cartridge.
@item step 2 : generate an EPROM file.
@item step 3 : get the EPROM file to the host computer.
@item step 4 : insert the EPROM file into the final dep64 .crt file:
@end itemize
@item cartconv -t dep256 -i dep256.bin -i somegame.crt -o foo.crt
Insert an 8kB .crt file into a dep256 type cartridge.
@item cartconv -t rep256 -i rep256.bin -i foo1.crt -i foo2.crt -i foo3.crt -o foo.crt
Insert multiple 8kB .crt files into a rep256 type cartridge.
@item cartconv -f foo.crt
Get information about a .crt file.
@end table

@c @node FIXME
@chapter petcat

The petcat program is a text conversion utility, it can convert
between ASCII, PETSCII and tokenized BASIC.

@section petcat command line options

@table @code
@cindex -help
@item -help
Output help text
@cindex -?
@item -?
Same as above
@cindex -v
@item -v
verbose output
@cindex -c
@item -c
controls (interpret also control codes) (default if textmode)
@cindex -nc
@item -nc
no controls (suppress control codes in printout) (default if non-textmode)
@cindex -ic
@item -ic
interpret control codes case-insensitive
@cindex -d
@item -d
output raw codes in decimal
@cindex -h
@item -h
write header (default if output is stdout)
@cindex -nh
@item -nh
no header (default if output is a file)
@cindex -skip <n>
@item -skip <n>
Skip <n> bytes in the beginning of input file. Ignored on P00.
@cindex -text
@item -text
Force text mode
@c @cindex -<version> - this one breaks the index (?!)
@item -<version>
use keywords for <version> instead of the v7.0 ones
@cindex -w<version>
@item -w<version>
tokenize using keywords on specified Basic version.
@cindex -k<version>
@item -k<version>
list all keywords for the specified Basic version
@cindex -k
@item -k
list all Basic versions available.
@cindex -l
@item -l
Specify load address for program (in hex, no loading chars!).
@cindex -o <name>
@item -o <name>
Specify the output file name
@cindex -f
@item -f
Force overwritten the output file. The default depends on the BASIC version.
@end table

BASIC Versions:
@table @code
@item 1
PET Basic V1.0
@item 2
Basic v2.0
@item superexp
Basic v2.0 with Super Expander (VIC20)
@item turtle
Basic v2.0 with Turtle Basic by Craig Bruce (VIC20)
@item mighty
Basic v2.0 with Mighty Basic by Craig Bruce (VIC20)
@item a
Basic v2.0 with AtBasic (C64)
@item simon
Basic v2.0 with Simon's Basic extension (C64)
@item speech
Basic v2.0 with Speech Basic v2.7 (C64)
@item F
Basic v2.0 with Final Cartridge III (C64)
@item ultra
Basic v2.0 with Ultrabasic-64 (C64)
@item graph
Basic v2.0 with Graphics basic (C64)
@item WSB
Basic v2.0 with WS basic (C64)
@item WSBF
Basic v2.0 with WS basic final (C64)
@item Pegasus
Basic v2.0 with Pegasus basic 4.0 (C64)
@item Xbasic
Basic v2.0 with Xbasic (C64)
@item Drago
Basic v2.0 with Drago basic 2.2 (C64)
@item REU
Basic v2.0 with REU-basic (C64)
@item Lightning
Basic v2.0 with Basic Lightning (C64)
@item magic
Basic v2.0 with Magic Basic (C64)
@item easy
Basic v2.0 with Easy Basic (VIC20)
@item blarg
Basic v2.0 with Blarg (C64)
@item Game
Basic v2.0 with Game Basic (C64)
@item BSX
Basic v2.0 with Basex (C64)
@item superbas
Basic v2.0 with Super Basic (C64)
@item exp20
Basic 2.0 with Expanded Basic (VIC20)
@item exp64
Basic 2.0 with Expanded Basic (C64)
@item sxc
Basic 2.0 with Super Expander Chip (C64)
@item warsaw
Basic 2.0 with Warsaw Basic (C64)
@item 4v
Basic 2.0 with Basic 4.0 extensions (VIC20)
@item 4 -w4e
PET Basic v4.0 program (PET/C64)
@item 5
Basic 2.0 with Basic 5.0 extensions (VIC20)
@item 3
Basic v3.5 program (C16)
@item 70
Basic v7.0 program (C128)
@item 71
Basic v7.1 program (C128)
@item 10
Basic v10.0 program (C64DX)
@end table

@c @node FIXME
@section petcat examples

@table @code
@item petcat -2 -o outputfile.txt -- inputfile.prg
Convert inputfile.prg to a text file in outputfile.txt, using BASIC V2 only
@item petcat -wsimon -o outputfile.prg -- inputfile.txt
Convert inputfile.txt to a PRG file in outputfile.prg, using Simon's BASIC
@end table


@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
* D64::                         The D64 disk image format
* D71::                         The D71 disk image format
* D80::                         The D80 disk image format
* D81::                         The D81 disk image format
* D82::                         The D82 disk image format
* X64::                         The X64 disk image format
* P00::                         The P00 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

@c FIXME: add D67 CBM2040 (DOS1) disk image file structure
@c FIXME: add D1M FD2000/FD4000 DD disk image file structure
@c FIXME: add D2M FD2000/FD4000 HD disk image file structure
@c FIXME: add D4M FD4000 ED disk image file structure

@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, D64 , 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 Hĺkan 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 @dots{}
@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 @dots{}
@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@dots{}

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

@c @node FIXME
@section The P64 NRZI flux pulse disk image format

@c FIXME: the P64 section needs to be style-checked.

This section is taken from "P64 file format specification" by Benjamin 'BeRo' 
Rosseaux.

All values are in little endian order ! 

@c @node FIXME
@subsection P64 Header Layout

@example
        0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
      +---------------------------------------------------------------+
0000: |'P'|'6'|'4'|'-'|'1'|'5'|'4'|'1'|    Version    |     Flags     |   
      +---------------+---------------+-------------------------------+
0010: |     Size      | CRC32Checksum |
      +-------------------------------+
@end example

         Version:  File format version, current is 0x00000000
      
            Size   Size of the following whole chunk content stream
      
           Flags:  Bit    0 = Write protect
                   Bit 1-31 = Reserved, all set to 0 when creating a file, 
                              preserve existing value when updating
       
   CRC32CheckSum:  CRC32 checksum of the following whole chunk content stream                

@c @node FIXME
@subsection P64 Chunk Header Layout

@example
        0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
      +-----------------------------------------------+
0000: |Chunk Signature|      Size     | CRC32Checksum |   
      +-----------------------------------------------+
@end example

 Chunk signature:  Signature of chunk
      
            Size:  Size of the chunk data
      
   CRC32CheckSum:  CRC32 checksum of the chunk data                

@c @node FIXME
@subsection P64 Chunk 'HTPx' Layout

                          | x = half track index byte |
                          +---------------------------+
                          
       Track 18 = Half track 36 = Half track index byte decimal value 36
                          
              Half track NRZI transition flux pulse data chunk block                          
                                                                                         
@example
        0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
      +---------------------------------------------------------------+
0000: |  Count pulses |     Size      | ..... Range-encoded data .... |    
      +---------------------------------------------------------------+
@end example

    Count pulses:  Count of the NRZI transition flux pulses in half track 
      
            Size:  Size of the range-encoded data
            
@c @node FIXME
@subsection 'HTPx' Range encoded data format

             Hint: For a working C implememtation see p64.c and p64.h

The range coder is a FPAQ0-style range coder combined with 12-bit 0-order 
models, one model per byte with one bit per byte processing.

@example
 +--------------------------------------------------------------------------+
 |   Sub stream     | Count of models |  Size per model  | Total value bits |
 +------------------+-----------------+------------------+------------------+
 |     Position     |        4        |      65536       |        32        |
 +------------------+-----------------+------------------+------------------+
 |     Strength     |        4        |      65536       |        32        | 
 +------------------+-----------------+------------------+------------------+
 |   Position flag  |        1        |        2         |        1         |
 +------------------+-----------------+------------------+------------------+
 |   Strenth flag   |        1        |        2         |        1         | 
 +------------------+-----------------+------------------+------------------+
 +===Total models===|        10       |==================|==================|
 +--------------------------------------------------------------------------+
@end example

All initial model state values are initialized with zero.
 
All initial model probability values are initialized with 2048. 

These model probability values will be updating in a adaptive way on the
fly and not precalculated before the encoding and even not loaded before 
the decoding, see pseudo code below.

16000000 Hz / 5 rotations per second at 300 RPM = maximal 3200000 flux pulses 
        
So NRZI transition flux pulse positions are in the 0 .. 3199999 value range, 
which is also a exact single rotation, where each time unit is a cycle at 
16 MHz with 300 RPM as a mapping for the ideal case.    
  
The NRZI transition flux pulse stength are in the 0x00000000 .. 0xffffffff
value range, where 0xffffffff indices a strong flux pulse, that always 
triggers, and 0x00000001 indices a weak flux pulse, that almost never 
triggers, and 0x00000000 indices a flux pulse, that absolutly never 
triggers.            
        
For 32-bit values, the model sub streams are subdivided byte wide in a 
little-endian manner, and each byte is processed bitwise with model 
probability shifting of 4 bits, just as:

Pascal-Style pseudo code:
@example
procedure WriteDWord(Model, Value : longword);                             
var ByteValue, ByteIndex, Context, Bit : longword;                         
begin                                                                      
  for ByteIndex := 0 to 3 do begin                                         
    ByteValue := (Value shr (ByteIndex shl 3)) and $ff;                    
    Context := 1;                                                          
    for Bit := 7 downto 0 do begin                                         
      Context := (Context shl 1) or RangeCoderEncodeBit(                   
                    RangeCoderProbabilities[                               
                     RangeCoderProbabilityOffsets[Model + ByteIndex] +     
                     (((RangeCoderProbabilityStates[Model + ByteIndex]      
                     shl 8) or Context) and $ffff)], 4, (ByteValue shr     
                     Bit) and 1);                                          
    end;                                                                   
    RangeCoderProbabilityStates[Model+ByteIndex] := ByteValue;             
  end;                                                                     
end;                                                                       
@end example

And for 1-bit flag values it is much simpler, but also with model probability 
shifting of 4 bits, just as:

Pascal-Style pseudo code:
@example
procedure WriteBit(Model, Value : longword);                               
begin                                                                      
   RangeCoderProbabilityStates[Model] :=                                   
     RangeCoderEncodeBit(RangeCoderProbabilities[                          
       RangeCoderProbabilityOffsets[Model] +                               
         RangeCoderProbabilityStates[Model]], 4, Value and 1);             
end;                                                                       
@end example

The position and strength values are delta-encoded. If a value is equal to 
the last previous value, then the value will not encoded, instead, a flag for
this will encoded. First the position value will encoded, then the stength 
value. If the last position delta is 0, then it is a track stream end marker.

Pascal-Style pseudo code:
@example
LastPosition := 0;                                                         
PreviousDeltaPosition := 0                                                 
                                                                           
LastStrength := 0;                                                         
                                                                           
for PulseIndex := 0 to PulseCount - 1 do begin                             
                                                                           
  DeltaPosition := Pulses[PulseIndex].Position - LastPosition;             
  if PreviousDeltaPosition <> DeltaPosition then begin                     
    PreviousDeltaPosition := DeltaPosition;                                
    WriteBit(ModelPositionFlag, 1)                                         
    WriteDWord(ModelPosition, DeltaPosition);                              
  end else begin                                                           
    WriteBit(ModelPositionFlag, 0);                                        
  end;                                                                     
  LastPosition := Pulses[PulseIndex].Position;                              
                                                                           
  if LastStrength <> Pulses[PulseIndex].Strength then begin                
    WriteBit(ModelStrengthFlag, 1)                                         
    WriteDWord(ModelStrength, Pulses[PulseIndex].Strength - LastStrength);   
  end else begin                                                           
    WriteBit(ModelStrengthFlag, 0);                                         
  end;                                                                       
  LastStrength := Pulses^[PulseIndex].Strength;                            
                                                                           
end;                                                                       
                                                                           
// End code                                                                
WriteBit(ModelPositionFlag, 1);                                            
WriteDWord(ModelPosition, 0);                                              
@end example
 
The decoding is simply just in the another direction way.
  
Pseudo code for a FPAQ0-style carryless range coder:

Pascal-Style pseudo code:
@example
procedure RangeCoderInit; // At encoding and decoding start                
begin                                                                      
  RangeCode := 0;                                                          
  RangeLow := 0;                                                           
  RangeHigh := $ffffffff;                                                  
end;                                                                       
                                                                           
procedure RangeCoderStart; // At decoding start                            
var Counter : longword;                                                       
begin                                                                      
  for Counter := 1 to 4 do begin                                           
   RangeCode := (RangeCode shl 8) or ReadByteFromInput;                    
  end;                                                                     
end;                                                                       
                                                                           
procedure RangeCoderFlush; // At encoding end                              
var Counter : longword;                                                      
begin                                                                      
  for Counter := 1 to 4 do begin                                           
    WriteByteToOutput(RangeHigh shr 24);                                   
    RangeHigh := RangeHigh shl 8;                                          
  end;                                                                     
end;                                                                        
                                                                           
procedure RangeCoderEncodeNormalize;                                          
begin                                                                      
  while ((RangeLow xor RangeHigh) and $ff000000) = 0 do begin              
   WriteByteToOutput(RangeHigh shr 24);                                    
   RangeLow := RangeLow shl 8;                                             
   RangeHigh := (RangeHigh shl 8) or $ff;                                    
  end;                                                                      
end;                                                                        
                                                                           
function RangeCoderEncodeBit(var Probability : longword; Shift,            
                             BitValue : longword) : longword;               
begin                                                                      
  RangeMiddle := RangeLow + (((RangeHigh - RangeLow) shr 12) *             
                              Probability);                                  
  if BitValue <> 0 then begin                                               
    inc(Probability, ($fff - Probability) shr Shift);                      
    RangeHigh := RangeMiddle;                                                
  end else begin                                                           
    dec(Probability, Probability shr Shift);                               
    RangeLow := RangeMiddle + 1;                                           
  end;                                                                     
  RangeCoderEncodeNormalize;                                               
  result := BitValue;                                                      
end;                                                                       
                                                                            
procedure RangeCoderDecodeNormalize;                                        
begin                                                                      
  while ((RangeLow xor RangeHigh) and $ff000000) = 0 do begin              
    RangeLow := RangeLow shl 8;                                            
    RangeHigh := (RangeHigh shl 8) or $ff;                                 
    RangeCode := (RangeCode shl 8) or ReadByteFromInput;                   
  end;                                                                     
end;                                                                       
                                                                            
function RangeCoderDecodeBit(var Probability : longword;                   
                             Shift : longword) : longword;                 
begin                                                                      
  RangeMiddle := RangeLow + (((RangeHigh - RangeLow) shr 12) *             
                             Probability);                                 
  if RangeCode <= RangeMiddle then begin                                   
    inc(Probability, ($fff - Probability) shr Shift);                      
    RangeHigh := RangeMiddle;                                              
    result := 1;                                                           
  end else begin                                                           
    dec(Probability, Probability shr Shift);                               
    RangeLow := RangeMiddle + 1;                                           
    result := 0;                                                           
  end;                                                                     
  RangeCoderDecodeNormalize;                                               
end;                                                                       
@end example

The probability may be never zero! But that can't happen here with this 
adaptive model in this P64 file format, since the adaptive model uses a
shift factor of 4 bits and initial probabilities value of 2048, so the 
probability has a value range from 15 up to 4080 here. If you do want to use 
the above range coder routines for other stuff with other probability models, 
then you must to ensure that the probability output value is never zero, for 
example with  "probability |= (probability < 1); " in C.     
  
@c @node FIXME
@subsection P64 Chunk 'DONE' Layout

This is the last empty chunk for to signalize that the correct file end is
reached.


@node D64, X64 , G64, File formats
@section The D64 disk image format

@c FIXME: the D64 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel. Added 42 track info by groepaz)

First and foremost we have D64, which is basically a sector-for-sector
copy of a 1540/1541 disk. There are several versions of these which I
will cover shortly. The standard D64 is a 174848 byte file comprised
of 256 byte sectors arranged in 35 tracks with a varying number of
sectors per track for a total of 683 sectors. Track counting starts at
1, not 0, and goes up to 35. Sector counting starts at 0, not 1, for
the first sector, therefore a track with 21 sectors will go from 0 to 20.

The original media (a 5.25" disk) has the tracks laid out in circles,
with track 1 on the very outside of the disk (closest to the sides) to
track 35 being on the inside of the disk (closest to the inner hub ring).
Commodore, in their infinite wisdom, varied the number of sectors per
track and data densities across the disk to optimize available storage,
resulting in the chart below. It shows the sectors/track for a standard
D64. Since the outside diameter of a circle is the largest (versus closer
to the center), the outside tracks have the largest amount of storage.

@multitable @columnfractions .33 .33 .33
@item @b{Track}
@tab @b{Sectors/track}
@tab @b{# Sectors}
@item 1-17
@tab 21
@tab 357
@item 18-24
@tab 19
@tab 133
@item 25-30
@tab 18
@tab 108
@item 31-35
@tab 17
@tab 85
@item 36-40(*)
@tab 17
@tab 85
@item 41-42(*)
@tab 17
@tab 34
@end multitable

@multitable @columnfractions .25 .25 .25 .25
@item @b{Track}
@tab @b{#Sect}
@tab @b{#SectorsIn}
@tab @b{D64 Offset}
@item 1
@tab 21
@tab 0
@tab $00000
@item 2
@tab 21
@tab 21
@tab $01500
@item 3
@tab 21
@tab 42
@tab $02A00
@item 4
@tab 21
@tab 63
@tab $03F00
@item 5
@tab 21
@tab 84
@tab $05400
@item 6
@tab 21
@tab 105
@tab $06900
@item 7
@tab 21
@tab 126
@tab $07E00
@item 8
@tab 21
@tab 147
@tab $09300
@item 9
@tab 21
@tab 168
@tab $0A800
@item 10
@tab 21
@tab 189
@tab $0BD00
@item 11
@tab 21
@tab 210
@tab $0D200
@item 12
@tab 21
@tab 231
@tab $0E700
@item 13
@tab 21
@tab 252
@tab $0FC00
@item 14
@tab 21
@tab 273
@tab $11100
@item 15
@tab 21
@tab 294
@tab $12600
@item 16
@tab 21
@tab 315
@tab $13B00
@item 17
@tab 21
@tab 336
@tab $15000
@item 18
@tab 19
@tab 357
@tab $16500
@item 19
@tab 19
@tab 376
@tab $17800
@item 20
@tab 19
@tab 395
@tab $18B00
@item 21
@tab 19
@tab 414
@tab $19E00
@item 22
@tab 19
@tab 433
@tab $1B100
@item 23
@tab 19
@tab 452
@tab $1C400
@item 24
@tab 19
@tab 471
@tab $1D700
@item 25
@tab 18
@tab 490
@tab $1EA00
@item 26
@tab 18
@tab 508
@tab $1FC00
@item 27
@tab 18
@tab 526
@tab $20E00
@item 28
@tab 18
@tab 544
@tab $22000
@item 29
@tab 18
@tab 562
@tab $23200
@item 30
@tab 18
@tab 580
@tab $24400
@item 31
@tab 17
@tab 598
@tab $25600
@item 32
@tab 17
@tab 615
@tab $26700
@item 33
@tab 17
@tab 632
@tab $27800
@item 34
@tab 17
@tab 649
@tab $28900
@item 35
@tab 17
@tab 666
@tab $29A00
@item 36(*)
@tab 17
@tab 683
@tab $2AB00
@item 37(*)
@tab 17
@tab 700
@tab $2BC00
@item 38(*)
@tab 17
@tab 717
@tab $2CD00
@item 39(*)
@tab 17
@tab 734
@tab $2DE00
@item 40(*)
@tab 17
@tab 751
@tab $2EF00
@item 41(*)
@tab 17
@tab 768
@tab $30000
@item 42(*)
@tab 17
@tab 785
@tab $31100
@end multitable

(*) Tracks 36-40 apply to 40- and 42-track images only.
(*) Tracks 41-42 apply to 42-track images only.

The directory track should be contained totally on track 18. Sectors
1-18 contain the entries and sector 0 contains the BAM
(Block Availability Map) and disk name/ID. Since the directory is
only 18 sectors large (19 less one for the BAM), and each sector can
contain only 8 entries (32 bytes per entry), the maximum number of
directory entries is 18 * 8 = 144. The first directory sector is
always 18/1, even though the t/s pointer at 18/0 (first two bytes)
might point somewhere else. It then follows the same chain structure
as a normal file, using a sector interleave of 3. This makes the
chain links go 18/1, 18/4, 18/7 etc.

Note that you can extend the directory off of track 18, but only
when reading the disk or image. Attempting to write to a directory
sector not on track 18 will cause directory corruption. Each
directory sector has the following layout (18/1 partial dump):

@example
 00: 12 04 81 11 00 4E 41 4D 45 53 20 26 20 50 4F 53 <- notice the T/S link
 10: 49 54 A0 A0 A0 00 00 00 00 00 00 00 00 00 15 00 <- to 18/4 ($12/$04)
 20: 00 00 84 11 02 41 44 44 49 54 49 4F 4E 41 4C 20 <- and how its not here
 30: 49 4E 46 4F A0 11 0C FE 00 00 00 00 00 00 61 01 <- ($00/$00)
@end example

The first two bytes of the sector ($12/$04) indicate the location of
the next track/sector of the directory (18/4). If the track is set
to $00, then it is the last sector of the directory. It is possible,
however unlikely, that the directory may *not* be competely on track
18 (some disks do exist like this). Just follow the chain anyhow.

When the directory is done, the track value will be $00. The sector
link should contain a value of $FF, meaning the whole sector is
allocated, but the actual value doesn't matter. The drive will return
all the available entries anyways.

This is a breakdown of a standard directory sector:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First directory entry
@item $20-$3F
@tab Second dir entry
@item $40-$5F
@tab Third dir entry
@item $60-$7F
@tab Fourth dir entry
@item $80-$9F
@tab Fifth dir entry
@item $A0-$BF
@tab Sixth dir entry
@item $C0-$DF
@tab Seventh dir entry
@item $E0-$FF
@tab Eighth dir entry
@end multitable

This is a breakdown of a standard directory entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next directory sector ($00 $00 if not the first entry in the sector)
@item $02
@tab File type
@item $03-$04
@tab Track/sector location of first sector of file
@item $05-$14
@tab 16 character filename (in PETASCII, padded with $A0)
@item $15-$16
@tab Track/Sector location of first side-sector block (REL file only)
@item $17
@tab REL file record length (REL file only, max. value 254)
@item $18-$1D
@tab Unused (except with GEOS disks)
@item $1E-$1F
@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254
@end multitable

The file type field is used as follows:

@multitable @columnfractions .2 .8
@item @b{Bits}
@tab @b{Description}
@item 0-3
@tab The actual file type
@item 4
@tab Unused
@item 5
@tab Used only during SAVE-@@ replacement
@item 6
@tab Locked flag (Set produces ">" locked files)
@item 7
@tab Closed flag (Not set produces "*", or "splat" files)
@end multitable

The actual file type can be one of the following:

@multitable @columnfractions .2 .2 .6
@item @b{Binary}
@tab @b{Decimal}
@tab @b{File type}
@item 0000
@tab 0
@tab DEL
@item 0001
@tab 1
@tab SEQ
@item 0010
@tab 2
@tab PRG
@item 0011
@tab 3
@tab USR
@item 0100
@tab 4
@tab REL
@end multitable

Values 5-15 are illegal, but if used will produce very strange
results. The 1541 is inconsistent in how it treats these bits.
Some routines use all 4 bits, others ignore bit 3, resulting in
values from 0-7.

Files, on a standard 1541, are stored using an interleave of 10.
Assuming a starting track/sector of 17/0, the chain would run
17/0, 17/10, 17/20, 17/8, 17/18, etc.

@c @node FIXME
@subsection Non-Standard & Long Directories

Most Commdore floppy disk drives use a single dedicated
directory track where all filenames are stored. This limits the
number of files stored on a disk based on the number of sectors
on the directory track. There are some disk images that contain
more files than would normally be allowed. This requires extending
the directory off the default directory track by changing the last
directory sector pointer to a new track, allocating the new
sectors in the BAM, and manually placing (or moving existing) file
entries there. The directory of an extended disk can be read and
the files that reside there can be loaded without problems on a
real drive. However, this is still a very dangerous practice as
writing to the extended portion of the directory will cause
directory corruption in the non-extended part. Many of the floppy
drives core ROM routines ignore the track value that the directory
is on and assume the default directory track for operations.

To explain: assume that the directory has been extended from track
18 to track 19/6 and that the directory is full except for a few
slots on 19/6. When saving a new file, the drive DOS will find an
empty file slot at 19/6 offset $40 and correctly write the filename
and a few other things into this slot. When the file is done being
saved the final file information will be written to 18/6 offset $40
instead of 19/6 causing some directory corruption to the entry at
18/6. Also, the BAM entries for the sectors occupied by the new
file will not be saved and the new file will be left as a SPLAT (*)
file.

Attempts to validate the disk will result in those files residing
off the directory track to not be allocated in the BAM, and could
also send the drive into an endless loop. The default directory
track is assumed for all sector reads when validating so if the
directory goes to 19/6, then the validate code will read 18/6
instead. If 18/6 is part of the normal directory chain then the
validate routine will loop endlessly.

@c @node FIXME
@subsection BAM layout

The layout of the BAM area (sector 18/0) is a bit more complicated@dots{}

@example
     00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
     -----------------------------------------------
 00: 12 01 41 00 12 FF F9 17 15 FF FF 1F 15 FF FF 1F
 10: 15 FF FF 1F 12 FF F9 17 00 00 00 00 00 00 00 00
 20: 00 00 00 00 0E FF 74 03 15 FF FF 1F 15 FF FF 1F
 30: 0E 3F FC 11 07 E1 80 01 15 FF FF 1F 15 FF FF 1F
 40: 15 FF FF 1F 15 FF FF 1F 0D C0 FF 07 13 FF FF 07
 50: 13 FF FF 07 11 FF CF 07 13 FF FF 07 12 7F FF 07
 60: 13 FF FF 07 0A 75 55 01 00 00 00 00 00 00 00 00
 70: 00 00 00 00 00 00 00 00 01 08 00 00 03 02 48 00
 80: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01
 90: 53 48 41 52 45 57 41 52 45 20 31 20 20 A0 A0 A0
 A0: A0 A0 56 54 A0 32 41 A0 A0 A0 A0 00 00 00 00 00
 B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of the first directory sector (should be set to 18/1 but it doesn't matter, and don't trust what is there, always go to 18/1 for first directory entry)
@item $02
@tab Disk DOS version type (see note below) $41 ("A")
@item $03
@tab Unused
@item $04-$8F
@tab BAM entries for each track, in groups of four bytes per track, starting on track 1 (see below for more details)
@item $90-$9F
@tab Disk Name (padded with $A0)
@item $A0-$A1
@tab Filled with $A0
@item $A2-$A3
@tab Disk ID
@item $A4
@tab Usually $A0
@item $A5-$A6
@tab DOS type, usually "2A"
@item $A7-$AA
@tab Filled with $A0
@item $AB
@tab Unused ($00)
@item $AC-$BF
@tab For DOLPHIN DOS track 36-40 BAM entries, otherwise unused ($00)
@item $C0-$D3
@tab For SPEED DOS track 36-40 BAM entries, otherwise unused ($00)
@item $D4-$FF Unused ($00)
@end multitable

Note: The BAM entries for SPEED, DOLPHIN and ProLogic DOS use
the same layout as standard BAM entries. One of the interesting
things from the BAM sector is the byte at offset $02, the DOS
version byte. If it is set to anything other than $41 or $00,
then we have what is called "soft write protection". Any attempt
to write to the disk will return the "DOS Version" error code
73 ,"CBM DOS V 2.6 1541". The 1541 is simply telling you that it
thinks the disk format version is incorrect. This message will
normally come up when you first turn on the 1541 and read the
error channel. If you write a $00 or a $41 into 1541 memory
location $00FF (for device 0), then you can circumvent this type
of write-protection, and change the DOS version back to what it
should be.

The BAM entries require a bit (no pun intended) more of a
breakdown. Take the first entry at bytes $04-$07 ($12 $FF $F9 $17).
The first byte ($12) is the number of free sectors on that track.
Since we are looking at the track 1 entry, this means it has 18
(decimal) free sectors. The next three bytes represent the bitmap
of which sectors are used/free. Since it is 3 bytes (8 bits/byte)
we have 24 bits of storage. Remember that at most, each track only
has 21 sectors, so there are a few unused bits.

@multitable @columnfractions .2 .4 .4
@item @b{Bytes}
@tab @b{Data}
@tab @b{Description}
@item $04-$07
@tab $12 $FF $F9 $17
@tab Track 1 BAM
@item $08-$0B
@tab $15 $FF $FF $FF
@tab Track 2 BAM
@item $0C-$0F
@tab $15 $FF $FF $1F
@tab Track 3 BAM
@item @dots{}
@tab @dots{}
@tab @dots{}
@item $8C-$8F
@tab $11 $FF $FF $01
@tab Track 35 BAM
@end multitable

These entries must be viewed in binary to make any sense. We will
use the first entry (track 1) at bytes 04-07:

@example
 FF=11111111, F9=11111001, 17=00010111
@end example

In order to make any sense from the binary notation, flip the
bits around.

@example
            111111 11112222
 01234567 89012345 67890123
 --------------------------
 11111111 10011111 11101000
 ^                     ^
 sector 0           sector 20
@end example

Since we are on the first track, we have 21 sectors, and only
use up to the bit 20 position. If a bit is on (1), the sector
is free. Therefore, track 1 has sectors 9, 10 and 19 used,
all the rest are free. Any leftover bits that refer to
sectors that don't exist, like bits 21-23 in the above
example, are set to allocated.

Each filetype has its own unique properties, but most follow
one simple structure. The first file sector is pointed to by
the directory and follows a t/s chain, until the track value
reaches $00. When this happens, the value in the sector link
location indicates how much of the sector is used. For
example, the following chain indicates a file 6 sectors
long, and ends when we encounter the $00/$34 chain. At this
point the last sector occupies from bytes $02-$34.

@multitable @columnfractions .16 .16 .16 .16 .16 .16
@item 1
@tab 2
@tab 3
@tab 4
@tab 5
@tab 6
@item ----
@tab ----
@tab ----
@tab ----
@tab ----
@tab ----
@item 17/0
@tab 17/10
@tab 17/20
@tab 17/1
@tab 17/11
@tab 0/52
@item (11/00)
@tab (11/0A)
@tab (11/14)
@tab (11/01)
@tab (11/0B)
@tab (0/34)
@end multitable

@c @node FIXME
@subsection Variations on the D64 layout

These are some variations of the D64 layout:

1. Standard 35 track layout but with 683 error bytes added on
to the end of the file. Each byte of the error info
corresponds to a single sector stored in the D64, indicating
if the sector on the original disk contained an error. The
first byte is for track 1/0, and the last byte is for track
35/16.

2. A 40 track layout, following the same layout as a 35 track
disk, but with 5 extra tracks. These contain 17 sectors each,
like tracks 31-35. Some of the PC utilities do allow you to
create and work with these files. This can also have error
bytes attached like variant #1.

3. A 42 track layout, with two extra tracks of 17 sectors each.
This is extremely uncommon, since real drives often have problems
with accessing these tracks, software that uses them is very rare.

4. The Commodore 128 allowed for "auto-boot" disks. With this,
t/s 1/0 holds a specific byte sequence which the computer
recognizes as boot code.

Below is a small chart detailing the standard file sizes of
D64 images, 35, 40 or 42 tracks, with or without error bytes.

@multitable @columnfractions .5 .5
@item @b{Disk type}
@tab @b{Size}
@item 35 track, no errors
@tab 174848
@item 35 track, 683 error bytes
@tab 175531
@item 40 track, no errors
@tab 196608
@item 40 track, 768 error bytes
@tab 197376
@item 42 track, no errors
@tab 205312
@item 42 track, 802 error bytes
@tab 206114
@end multitable

The following table (provided by Wolfgang Moser) outlines
the differences between the standard 1541 DOS and the
various "speeder" DOS's that exist. The 'header 7/8'
category is the 'fill bytes' as the end of the sector
header of a real 1541 disk.

@multitable @columnfractions .5 .1 .1 .1 .2
@item @b{Disk format}
@tab @b{tracks}
@tab @b{header 7/8}
@tab @b{Dos type}
@tab @b{Diskdos vs. type}
@item Original CBM DOS v2.6
@tab 35
@tab $0f $0f
@tab "2A"
@tab $41/'A'
@item *SpeedDOS+
@tab 40
@tab $0f $0f
@tab "2A"
@tab $41/'A'
@item Professional DOS Initial
@tab 35
@tab $0f $0f
@tab "2A"
@tab $41/'A'
@item Professional DOS Version 1/Prototype
@tab 40
@tab $0f $0f
@tab "2A"
@tab $41/'A'
@item ProfDOS Release
@tab 40
@tab $0f $0f
@tab "4A"
@tab $41/'A'
@item Dolphin-DOS 2.0/3.0
@tab 35
@tab $0f $0f
@tab "2A"
@tab $41/'A'
@item Dolphin-DOS 2.0/3.0
@tab 40
@tab $0d $0f
@tab "2A"
@tab $41/'A'
@item PrologicDOS 1541
@tab 35
@tab $0f $0f
@tab "2A"
@tab $41/'A'
@item PrologicDOS 1541
@tab 40
@tab $0f $0f
@tab "2P"
@tab $50/'P'
@item ProSpeed 1571 2.0
@tab 35
@tab $0f $0f
@tab "2A"
@tab $41/'A'
@item ProSpeed 1571 2.0
@tab 40
@tab $0f $0f
@tab "2P"
@tab $50/'P'
@end multitable

*Note: There are also clones of SpeedDOS that exist, such as
RoloDOS and DigiDOS. Both are just a change of the DOS startup
string.

The location of the extra BAM information in sector 18/0, for
40 track images, will be different depending on what standard
the disks have been formatted with. SPEED DOS stores them from
$C0 to $D3, DOLPHIN DOS stores them from $AC to $BF and
PrologicDOS stored them right after the existing BAM entries
from $90-A3. PrologicDOS also moves the disk label and ID
forward from the standard location of $90 to $A4. 64COPY and
Star Commander let you select from several different types of
extended disk formats you want to create/work with.

All three of the speeder DOS's mentioned above don't alter the
standard sector interleave of 10 for files and 3 for
directories. The reason is that they use a memory cache
installed in the drive which reads the entire track in one
pass. This alleviates the need for custom interleave values.
They do seem to alter the algorithm that finds the next
available free sector so that the interleave value can deviate
from 10 under certain circumstances, but I don't know why they
would bother.

Below is a HEX dump of a Speed DOS BAM sector. Note the
location of the extra BAM info from $C0-D3.

@example
       00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
       -----------------------------------------------
 0070: 12 FF FF 03 12 FF FF 03 12 FF FF 03 11 FF FF 01
 0080: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01
 0090: A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0
 00A0: A0 A0 30 30 A0 32 41 A0 A0 A0 A0 00 00 00 00 00
 00B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 00C0: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01
 00D0: 11 FF FF 01 00 00 00 00 00 00 00 00 00 00 00 00
@end example

Below is a HEX dump of a Dolphin DOS BAM sector. Note
the location of the extra BAM info from $AC-BF.

@example
       00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
       -----------------------------------------------
 0070: 12 FF FF 03 12 FF FF 03 12 FF FF 03 11 FF FF 01
 0080: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01
 0090: A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0
 00A0: A0 A0 30 30 A0 32 41 A0 A0 A0 A0 00 11 FF FF 01
 00B0: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01
 00C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 00D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

Below is a HEX dump of a PrologicDOS BAM sector. Note
that the disk name and ID are now located at $A4 instead
of starting at $90.

@example
       00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
       -----------------------------------------------
 0070: 12 FF FF 03 12 FF FF 03 12 FF FF 03 11 FF FF 01
 0080: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01
 0090: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01
 00A0: 11 FF FF 01 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0
 00B0: A0 A0 A0 A0 A0 A0 30 30 A0 32 50 A0 A0 A0 A0 00
 00C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 00D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@c @node FIXME
@subsection Error codes

Here is the meaning of the error bytes added onto the end of
any extended D64. The CODE is the same as that generated by
the 1541 drive controller@dots{} it reports these numbers, not
the error code we usually see when an error occurs.

Some of what comes below is taken from Immers/Neufeld book
"Inside Commodore DOS". Note the descriptions are not
completely accurate as to what the drive DOS is actually
doing to seek/read/decode/write sectors, but serve as simple
examples only. The "type" field is where the error usually
occurs, whether it's searching for any SYNC mark, any header
ID, any valid header, or reading a sector.

@multitable @columnfractions .2 .2 .2 .2 .2
@item @b{Code}
@tab @b{Error}
@tab @b{Type}
@tab @b{D64}
@tab @b{Description}
@item $01
@tab 00
@tab N/A
@tab *
@tab No error.
@item $02
@tab 20
@tab Seek
@tab *
@tab Header block not found / Header descriptor byte not found
@item $03
@tab 21
@tab Seek
@tab *
@tab No SYNC sequence found
@item $04
@tab 22
@tab Read
@tab *
@tab Data descriptor byte not found
@item $05
@tab 23
@tab Read
@tab *
@tab Checksum error in data block
@item $06
@tab 24
@tab Write
@tab
@tab Write verify on format (never occurs on 1541)
@item $07
@tab 25
@tab Write
@tab
@tab Write verify error
@item $08
@tab 26
@tab Write
@tab
@tab Write protect on
@item $09
@tab 27
@tab Seek
@tab *
@tab Checksum error in header block
@item $0A
@tab 28
@tab Write
@tab
@tab Write error (never occurs on 1541)
@item $0B
@tab 29
@tab Seek
@tab *
@tab Disk sector ID mismatch
@item $0F
@tab 74
@tab Read
@tab
@tab Drive Not Ready (no disk in drive or no device 1)
@end multitable

Codes $0 and $C to $E are unused and never occur.

These first errors are "seek" errors, where the disk
controller is simply reading headers and looking at
descriptor bytes, checksums, format ID's and reporting what
errors it sees. These errors do *not* necessarily apply to
the exact sector being looked for. This fact makes
duplication of these errors very unreliable.

Code    : $03
Error   : 21
Type    : Seek
Message : No SYNC sequence found.

Each sector data block and header block are preceeded by
SYNC marks. If *no* sync sequence is found within 20
milliseconds (only ~1/10 of a disk rotation!) then this
error is generated. This error used to mean the entire
track is bad, but it does not have to be the case. Only
a small area of the track needs to be without a SYNC
mark and this error will be generated.

Converting this error to a D64 is very problematic
because it depends on where the physical head is on the
disk when a read attempt is made. If it is on valid
header/sectors then it won't occur. If it happens over
an area without SYNC marks, it will happen.

Code    : $02
Error   : 20
Type    : Seek
Message : Header descriptor byte not found (HEX $08, GCR $52)

Each sector is preceeded by an 8-byte GCR header block, which
starts with the value $52 (GCR). If this value is not found
after 90 attempts, this error is generated.

Basically, what a track has is SYNC marks, and possibly valid
data blocks, but no valid header descriptors.

Code    : $09
Error   : 27
Type    : Seek
Message : Checksum error in header block

The header block contains a checksum value, calculated by
XOR'ing the TRACK, SECTOR, ID1 and ID2 values. If this
checksum is wrong, this error is generated.

Code    : $0B
Error   : 29
Type    : Seek
Message : Disk sector ID mismatch

The ID's from the header block of the currently read sector are
compared against the ones from the low-level header of 18/0. If
there is a mismatch, this error is generated.

Code    : $02
Error   : 20
Type    : Seek
Message : Header block not found

This error can be reported again when searching for the correct
header block. An image of the header is built and searched for,
but not found after 90 read attempts. Note the difference from
the first occurance. The first one only searches for a valid
ID, not the whole header.

Note that error 20 occurs twice during this phase. The first
time is when a header ID is being searched for, the second is
when the proper header pattern for the sector being searched
for is not found.

From this point on, all the errors apply to the specific
sector you are looking for. If a read passed all the previous
checks, then we are at the sector being searched for.

Note that the entire sector is read before these errors are
detected. Therefore the data, checksum and off bytes are
available.

Code    : $04
Error   : 22
Type    : Read
Message : Data descriptor byte not found (HEX $07, GCR $55)

Each sector data block is preceeded by the value $07, the
"data block" descriptor. If this value is not there, this
error is generated. Each encoded sector has actually 260
bytes. First is the descriptor byte, then follows the
256 bytes of data, a checksum, and two "off" bytes.

Code    : $05
Error   : 23
Type    : Read
Message : Checksum error in data block

The checksum of the data read of the disk is calculated, and
compared against the one stored at the end of the sector. If
there's a discrepancy, this error is generated.

Code    : $0F
Error   : 74
Type    : Read
Message : Drive Not Ready (no disk in drive or no device 1)

These errors only apply when writing to a disk. I don't see the
usefulness of having these as they cannot be present when only
*reading* a disk.

Code    : $06
Error   : 24
Type    : Write
Message : Write verify (on format)

Code    : $07
Error   : 25
Type    : Write
Message : Write verify error

Once the GCR-encoded sector is written out, the drive waits for
the sector to come around again and verifies the whole 325-byte
GCR block. Any errors encountered will generate this error.

Code    : $08
Error   : 26
Type    : Write
Message : Write protect on

Self explanatory. Remove the write-protect tab, and try again.

Code    : $0A
Error   : 28
Type    : Write
Message : Write error

In actual fact, this error never occurs, but it is included
for completeness.

This is not an error at all, but it gets reported when the
read of a sector is ok.

Code    : $01
Error   : 00
Type    : N/A
Message : No error.

Self explanatory. No errors were detected in the reading
and decoding of the sector.

The advantage with using the 35 track D64 format, regardless of
error bytes, is that it can be converted directly back to a 1541
disk by either using the proper cable and software on the PC, or
send it down to the C64 and writing it back to a 1541. It is the
best documented format since it is also native to the C64, with
many books explaining the disk layout and the internals of the
1541.

@node X64, D71, D64, File formats
@section The X64 disk image format

@c FIXME: the X64 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

This file type, created by Teemu Rantanen, is used on the X64
emulator (a UNIX-based emulator) which has been superceeded by
VICE. Both VICE and X64 support the X64 file standard, with
VICE also supporting the regular D64 and T64 files.

X64 is not a specific type of file, but rather encompasses
*all* known C64 disk types (hard disk, floppies, etc). An X64
is created by prepending a 64-byte header to an existing image
(1541, 1571, etc) and setting specific bytes which describe
what type of image follows. This header has undergone some
revision, and this description is based on the 1.02 version,
which was the last known at the time of writing.

The most common X64 file you will see is the D64 variety,
typically 174912 bytes long (174848 for the D64 and 64 bytes
for the header, assuming no error bytes are appended). The
header layout (as used in 64COPY) is as follows:

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
0000: 43 15 41 64 01 02 01 23 00 00 00 00 00 00 00 00
0010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0040: XX XX XX <- standard C64 image starts here@dots{}.
@end example

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$03
@tab This is the "Magic header" ($43 $15 $41 $64)
@item $04
@tab Header version major ($01)
@item $05
@tab Header version minor ($01, now its up to $02)
@item $06
@tab Device type represented
@item $07
@tab Maximum tracks in image (only in version 1.02 or greater) 1540/41/70: 35 1571: 35 1581: 80 (Logical single-sided disk)
@item $08
@tab Number of disk sides in image. This value must be $00 for all 1541 and 1581 formats. $00=No second side $01=Second side
@item $09
@tab Error data flag.
@item $0A-$1F
@tab Unused, set to $00
@item $20-$3E
@tab Disk image description (in ASCII or ISO Latin/1)
@item $3F
@tab Always set to $00
@item $40-
@tab Standard C64 file begins here.
@end multitable

The device types are:

@multitable @columnfractions .2 .8
@item @b{Value}
@tab @b{Drive type}
@item $00
@tab 1540 See note below@dots{}
@item $01
@tab 1541 (Default)
@item $02
@tab 1542
@item $03
@tab 1551
@item $04
@tab 1570
@item $05
@tab 1571
@item $06
@tab 1572
@item $08
@tab 1581
@item $10
@tab 2031 or 4031
@item $11
@tab 2040 or 3040
@item $12
@tab 2041
@item $18
@tab 4040
@item $20
@tab 8050
@item $21
@tab 8060
@item $22
@tab 8061
@item $30
@tab SFD-1001
@item $31
@tab 8250
@item $32
@tab 8280
@end multitable

The first four bytes used for the device type at position $06
($00 to $03) are functionally the same, and are compatible with
older version of X64 files. Some old X64 files might have $00
for the device type (instead of $01), but it makes no real
difference.

As most instances of X64 files will be strictly 1541 images,
bytes $08-$3F are set to zero, and some versions of the X64
emulator don't use bytes $08-$3F.

@node D71, D81, X64, File formats
@section The D71 disk image format

@c FIXME: the D71 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

Similar to the D64 (1541), the 1571 drive can operate in either
single-sided (1541 compatible) mode or double-sided (1571) mode. In
this section I will be dealing with the double-sided mode only. For
the breakdown of the single-sided mode, see the D64 section.

The D71 has 70 tracks, double that of the 1541, with a DOS file
size of 349696 bytes. If the error byte block (1366 bytes) is
attached, this makes the file size 351062 bytes. The track range
and offsets into the D71 files are as follows:

@multitable @columnfractions .5 .25 .25
@item @b{Track}
@tab @b{Sec/trk}
@tab @b{# Sectors}
@item 1-17 (side 0)
@tab 21
@tab 357
@item 18-24 (side 0)
@tab 19
@tab 133
@item 25-30 (side 0)
@tab 18
@tab 108
@item 31-35 (side 0)
@tab 17
@tab 85
@item 36-52 (side 1)
@tab 21
@tab 357
@item 53-59 (side 1)
@tab 19
@tab 133
@item 60-65 (side 1)
@tab 18
@tab 108
@item 66-70 (side 1)
@tab 17
@tab 85
@end multitable

@multitable @columnfractions .25 .25 .25 .25
@item @b{Track}
@tab @b{#Sect}
@tab @b{#SectorsIn}
@tab @b{D71 Offset}
@item 1
@tab 21
@tab 0
@tab $00000
@item 2
@tab 21
@tab 21
@tab $01500
@item 3
@tab 21
@tab 42
@tab $02A00
@item 4
@tab 21
@tab 63
@tab $03F00
@item 5
@tab 21
@tab 84
@tab $05400
@item 6
@tab 21
@tab 105
@tab $06900
@item 7
@tab 21
@tab 126
@tab $07E00
@item 8
@tab 21
@tab 147
@tab $09300
@item 9
@tab 21
@tab 168
@tab $0A800
@item 10
@tab 21
@tab 189
@tab $0BD00
@item 11
@tab 21
@tab 210
@tab $0D200
@item 12
@tab 21
@tab 231
@tab $0E700
@item 13
@tab 21
@tab 252
@tab $0FC00
@item 14
@tab 21
@tab 273
@tab $11100
@item 15
@tab 21
@tab 294
@tab $12600
@item 16
@tab 21
@tab 315
@tab $13B00
@item 17
@tab 21
@tab 336
@tab $15000
@item 18
@tab 19
@tab 357
@tab $16500
@item 19
@tab 19
@tab 376
@tab $17800
@item 20
@tab 19
@tab 395
@tab $18B00
@item 21
@tab 19
@tab 414
@tab $19E00
@item 22
@tab 19
@tab 433
@tab $1B100
@item 23
@tab 19
@tab 452
@tab $1C400
@item 24
@tab 19
@tab 471
@tab $1D700
@item 25
@tab 18
@tab 490
@tab $1EA00
@item 26
@tab 18
@tab 508
@tab $1FC00
@item 27
@tab 18
@tab 526
@tab $20E00
@item 28
@tab 18
@tab 544
@tab $22000
@item 29
@tab 18
@tab 562
@tab $23200
@item 30
@tab 18
@tab 580
@tab $24400
@item 31
@tab 17
@tab 598
@tab $25600
@item 32
@tab 17
@tab 615
@tab $26700
@item 33
@tab 17
@tab 632
@tab $27800
@item 34
@tab 17
@tab 649
@tab $28900
@item 35
@tab 17
@tab 666
@tab $29A00
@item 36
@tab 21
@tab 683
@tab $2AB00
@item 37
@tab 21
@tab 704
@tab $2C000
@item 38
@tab 21
@tab 725
@tab $2D500
@item 39
@tab 21
@tab 746
@tab $2EA00
@item 40
@tab 21
@tab 767
@tab $2FF00
@item 41
@tab 21
@tab 788
@tab $31400
@item 42
@tab 21
@tab 809
@tab $32900
@item 43
@tab 21
@tab 830
@tab $33E00
@item 44
@tab 21
@tab 851
@tab $35300
@item 45
@tab 21
@tab 872
@tab $36800
@item 46
@tab 21
@tab 893
@tab $37D00
@item 47
@tab 21
@tab 914
@tab $39200
@item 48
@tab 21
@tab 935
@tab $3A700
@item 49
@tab 21
@tab 956
@tab $3BC00
@item 50
@tab 21
@tab 977
@tab $3D100
@item 51
@tab 21
@tab 998
@tab $3E600
@item 52
@tab 21
@tab 1019
@tab $3FB00
@item 53
@tab 19
@tab 1040
@tab $41000
@item 54
@tab 19
@tab 1059
@tab $42300
@item 55
@tab 19
@tab 1078
@tab $43600
@item 56
@tab 19
@tab 1097
@tab $44900
@item 57
@tab 19
@tab 1116
@tab $45C00
@item 58
@tab 19
@tab 1135
@tab $46F00
@item 59
@tab 19
@tab 1154
@tab $48200
@item 60
@tab 18
@tab 1173
@tab $49500
@item 61
@tab 18
@tab 1191
@tab $4A700
@item 62
@tab 18
@tab 1209
@tab $4B900
@item 63
@tab 18
@tab 1227
@tab $4CB00
@item 64
@tab 18
@tab 1245
@tab $4DD00
@item 65
@tab 18
@tab 1263
@tab $4EF00
@item 66
@tab 17
@tab 1281
@tab $50100
@item 67
@tab 17
@tab 1298
@tab $51200
@item 68
@tab 17
@tab 1315
@tab $52300
@item 69
@tab 17
@tab 1332
@tab $53400
@item 70
@tab 17
@tab 1349
@tab $54500
@end multitable

The directory structure is the same as a D64/1541. All the same
filetypes apply, the directory still only holds 144 files per
disk and should only exist on track 18.

The first two bytes of the sector ($12/$04 or 18/4) indicate
the location of the next track/sector of the directory. If the
track value is set to $00, then it is the last sector of the
directory. It is possible, however unlikely, that the directory
may *not* be competely on track 18 (some disks do exist like
this). Just follow the chain anyhow.

When the directory is done, the track value will be $00. The
sector link should contain a value of $FF, meaning the whole
sector is allocated, but the actual value doesn't matter. The
drive will return all the available entries anyways. This is a
breakdown of a standard directory sector and entry:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 12 04 82 11 00 4A 45 54 20 53 45 54 20 57 49 4C
10: 4C 59 A0 A0 A0 00 00 00 00 00 00 00 00 00 2B 00
20: 00 00 82 0F 01 4A 53 57 20 31 A0 A0 A0 A0 A0 A0
30: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 BF 00
40: 00 00 82 06 03 53 4F 4E 20 4F 46 20 42 4C 41 47
50: 47 45 52 A0 A0 00 00 00 00 00 00 00 00 00 AE 00
60: 00 00 82 15 0D 50 4F 54 54 59 20 50 49 47 45 4F
70: 4E A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 A2 00
80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First directory entry
@item $20-$3F
@tab Second dir entry
@item $40-$5F
@tab Third dir entry
@item $60-$7F
@tab Fourth dir entry
@item $80-$9F
@tab Fifth dir entry
@item $A0-$BF
@tab Sixth dir entry
@item $C0-$DF
@tab Seventh dir entry
@item $E0-$FF
@tab Eighth dir entry
@end multitable

This is a breakdown of a standard directory entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next directory sector ($00/$FF if its the last sector)
@item $02
@tab File type
@item $03-$04
@tab Track/sector location of first sector of file
@item $05-$14
@tab 16 character filename (in PETASCII, padded with $A0)
@item $15-$16
@tab Track/Sector location of first side-sector block (REL file only)
@item $17
@tab REL file record length (REL file only, max. value 254)
@item $18-$1D
@tab Unused (except with GEOS disks)
@item $1E-$1F
@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254
@end multitable

The file type field is used as follows:

@multitable @columnfractions .2 .8
@item @b{Bits}
@tab @b{Description}
@item 0-3
@tab The actual file type
@item 4
@tab Unused
@item 5
@tab Used only during SAVE-@@ replacement
@item 6
@tab Locked flag (Set produces ">" locked files)
@item 7
@tab Closed flag (Not set produces "*", or "splat" files)
@end multitable

The actual file type can be one of the following:

@multitable @columnfractions .2 .2 .6
@item @b{Binary}
@tab @b{Decimal}
@tab @b{File type}
@item 0000
@tab 0
@tab DEL
@item 0001
@tab 1
@tab SEQ
@item 0010
@tab 2
@tab PRG
@item 0011
@tab 3
@tab USR
@item 0100
@tab 4
@tab REL
@end multitable

Values 5-15 are illegal, but if used will produce very strange
results. The 1571 is inconsistent in how it treats these bits.
Some routines use all 4 bits, others ignore bit 3, resulting in
values from 0-7.

When the 1571 is in is native ("1571") mode, files are stored
with a sector interleave of 6, rather than 10 which the 1541
(and the 1571 in "1541" mode) uses. The directory still uses an
interleave of 3.

@c @node FIXME
@subsection Non-Standard & Long Directories

Most Commodore floppy disk drives use a single dedicated
directory track where all filenames are stored. This limits the
number of files stored on a disk based on the number of sectors
on the directory track. There are some disk images that contain
more files than would normally be allowed. This requires
extending the directory off the default directory track by
changing the last directory sector pointer to a new track,
allocating the new sectors in the BAM, and manually placing (or
moving existing) file entries there. The directory of an
extended disk can be read and the files that reside there can be
loaded without problems on a real drive. However, this is still
a very dangerous practice as writing to the extended portion of
the directory will cause directory corruption in the non-
extended part. Many of the floppy drives core ROM routines
ignore the track value that the directory is on and assume the
default directory track for operations.

To explain: assume that the directory has been extended from
track 18 to track 19/6 and that the directory is full except
for a few slots on 19/6. When saving a new file, the drive DOS
will find an empty file slot at 19/6 offset $40 and correctly
write the filename and a few other things into this slot. When
the file is done being saved the final file information will
be written to 18/6 offset $40 instead of 19/6 causing some
directory corruption to the entry at 18/6. Also, the BAM
entries for the sectors occupied by the new file will not be
saved and the new file will be left as a SPLAT (*) file.

Attempts to validate the disk will result in those files
residing off the directory track to not be allocated in the
BAM, and could also send the drive into an endless loop. The
default directory track is assumed for all sector reads when
validating so if the directory goes to 19/6, then the validate
code will read 18/6 instead. If 18/6 is part of the normal
directory chain then the validate routine will loop endlessly.

@c @node FIXME
@subsection Bam layout The BAM is somewhat different as it now has to
take 35 new tracks into account. In order to do this, most of
the extra BAM information is stored on track 53/0, and the
remaining sectors on track 53 are marked in the BAM as
allocated. This does mean that except for one allocated
sector on track 53, the rest of the track is unused and
wasted. (Track 53 is the equivalent to track 18, but on the
flip side of the disk). Here is a dump of the first BAM
sector@dots{}

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 12 01 41 80 12 FF F9 17 15 FF FF 1F 15 FF FF 1F
10: 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F
20: 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F
30: 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F
40: 15 FF FF 1F 15 FF FF 1F 11 FC FF 07 13 FF FF 07
50: 13 FF FF 07 13 FF FF 07 13 FF FF 07 13 FF FF 07
60: 13 FF FF 07 12 FF FF 03 12 FF FF 03 12 FF FF 03
70: 12 FF FF 03 12 FF FF 03 12 FF FF 03 11 FF FF 01
80: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01
90: A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0
A0: A0 A0 30 30 A0 32 41 A0 A0 A0 A0 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 15 15 15
E0: 15 15 15 15 15 15 15 15 15 15 15 15 15 15 00 13
F0: 13 13 13 13 13 12 12 12 12 12 12 11 11 11 11 11
@end example

@multitable @columnfractions .5 .5
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of the first directory sector (should be set to 18/1 but it doesn't matter, and don't trust what is there, always go to 18/1 for first directory entry)
@item $02
@tab Disk DOS version type (see note below) $41 ('A') = 1541
@item $03
@tab Double-sided flag $00 - Single sided disk $80 - Double sided disk
@item $04-8F
@tab BAM entries for each track, in groups of four bytes per track, starting on track 1.
@item $90-$9F
@tab Disk Name (padded with $A0)
@item $A0-$A1
@tab Filled with $A0
@item $A2-$A3
@tab Disk ID
@item $A4
@tab Usually $A0
@item $A5-$A6
@tab DOS type, usually "2A"
@item $A7-$AA
@tab Filled with $A0
@item $AB-$DC
@tab Not used ($00's)
@item $DD-$FF
@tab Free sector count for tracks 36-70 (1 byte/track).
@end multitable

The "free sector" entries for tracks 36-70 are likely included
here in the first BAM sector due to some memory restrictions in
the 1571 drive. There is only enough memory available for one
BAM sector, but in order to generate the "blocks free" value at
the end of a directory listing, the drive needs to know the
extra track "free sector" values. It does make working with the
BAM a little more difficult, though.

These are the values that would normally be with the 4-byte BAM
entry, but the rest of the entry is contained on 53/0.

Note: If the DOS version byte is set to anything other than $41
or $00, then we have what is called "soft write protection". Any
attempt to write to the disk will return the "DOS Version" error
code 73. The 1571 is simply telling you that it thinks the disk
format version is incorrect.

The BAM entries require some explanation. Take the first entry
at bytes $04-$07 ($12 $FF $F9 $17). The first byte ($12) is the
number of free sectors on that track. Since we are looking at the
track 1 entry, this means it has 18 (decimal) free sectors.

The next three bytes represent the bitmap of which sectors are
used/free. Since it is 3 bytes (8 bits/byte) we have 24 bits of
storage. Remember that at most, each track only has 21 sectors,
so there are a few unused bits. These entries must be viewed in
binary to make any sense. We will use the first entry (track 1)
at bytes 04-07:

@example
 FF=11111111, F9=11111001, 17=00010111
@end example

In order to make any sense from the binary notation, flip the
bits around.

@example
            111111 11112222
 01234567 89012345 67890123
 --------------------------
 11111111 10011111 11101000
 ^                     ^
 sector 0           sector 20
@end example

Since we are on the first track, we have 21 sectors, and only
use up to the bit 20 position. If a bit is on (1), the sector
is free. Therefore, track 1 has sectors 9,10 and 19 used, all
the rest are free.

In order to complete the BAM, we must check 53/0.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF
10: FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF
20: 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F
30: FF FF 1F 00 00 00 FF FF 07 FF FF 07 FF FF 07 FF
40: FF 07 FF FF 07 FF FF 07 FF FF 03 FF FF 03 FF FF
50: 03 FF FF 03 FF FF 03 FF FF 03 FF FF 01 FF FF 01
60: FF FF 01 FF FF 01 FF FF 01 00 00 00 00 00 00 00
70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

Each track from 36-70 has 3 byte entries, starting at
address $00.

@example
Byte: $00-$02: $FF $FF $1F - BAM map for track 36
      $03-$05: $FF $FF $1F - BAM map for track 37
      @dots{}
      $33-$35: $00 $00 $00 - BAM map for track 53
      @dots{}
      $66-$68: $FF $FF $01 - BAM map for track 70
      $69-$FF:             - Not used
@end example

You can break down the entries for tracks 36-70 the same way as
track 1, just combine the free sector bytes from 18/0 and the BAM
usage from 53 to get the full 4-byte entry.

Just like a D64, you can attach error bytes to the file, for
sector error information. This block is 1366 bytes long, 1 byte
for each of the 1366 sectors in the image. With the error bytes,
the file size is 351062 bytes.

@node D81, D80, D71, File formats
@section The D81 disk image format

@c FIXME: the D81 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

Like D64 and D71, this is a byte for byte copy of a physical 1581
disk. It consists of 80 tracks, 40 sectors each (0 to 39) for a
size of 819200 bytes, or 3200 sectors. If the error byte block is
attached, this makes the file size 822400 bytes.

There are three sectors on the directory track used for disk
internals (header and BAM), leaving 37 sectors for filename
entries, thus allowing for 296 files (37 * 8) to be stored at the
root level of the disk.

The actual physical layout on the disk is quite different from what
the user sees, but this is unimportant to the scope of this section.
One important difference from the D64 and D71 is all the sector
interleaves are now 1 for both files and directory storage (rather
than 3 for directory and 10 for file on a D64/D71). This is due to
the built-in buffering in the 1581. When reading a sector, the
whole track will be buffered in memory, and any sectors being
modified will be done in memory. Once it has to be written, the
whole track will be written out in one step.

The track range and offsets into the D81 files are as follows:

@multitable @columnfractions .25 .25 .25 .25
@item @b{Track}
@tab @b{#Sect}
@tab @b{#SectorsIn}
@tab @b{D81 Offset}
@item 1
@tab 40
@tab 0
@tab $00000
@item 2
@tab 40
@tab 40
@tab $02800
@item 3
@tab 40
@tab 80
@tab $05000
@item 4
@tab 40
@tab 120
@tab $07800
@item 5
@tab 40
@tab 160
@tab $0A000
@item 6
@tab 40
@tab 200
@tab $0C800
@item 7
@tab 40
@tab 240
@tab $0F000
@item 8
@tab 40
@tab 280
@tab $11800
@item 9
@tab 40
@tab 320
@tab $14000
@item 10
@tab 40
@tab 360
@tab $16800
@item 11
@tab 40
@tab 400
@tab $19000
@item 12
@tab 40
@tab 440
@tab $1B800
@item 13
@tab 40
@tab 480
@tab $1E000
@item 14
@tab 40
@tab 520
@tab $20800
@item 15
@tab 40
@tab 560
@tab $23000
@item 16
@tab 40
@tab 600
@tab $25800
@item 17
@tab 40
@tab 640
@tab $28000
@item 18
@tab 40
@tab 680
@tab $2A800
@item 19
@tab 40
@tab 720
@tab $2D000
@item 20
@tab 40
@tab 760
@tab $2F800
@item 21
@tab 40
@tab 800
@tab $32000
@item 22
@tab 40
@tab 840
@tab $34800
@item 23
@tab 40
@tab 880
@tab $37000
@item 24
@tab 40
@tab 920
@tab $39800
@item 25
@tab 40
@tab 960
@tab $3C000
@item 26
@tab 40
@tab 1000
@tab $3E800
@item 27
@tab 40
@tab 1040
@tab $41000
@item 28
@tab 40
@tab 1080
@tab $43800
@item 29
@tab 40
@tab 1120
@tab $46000
@item 30
@tab 40
@tab 1160
@tab $48800
@item 31
@tab 40
@tab 1200
@tab $4B000
@item 32
@tab 40
@tab 1240
@tab $4D800
@item 33
@tab 40
@tab 1280
@tab $50000
@item 34
@tab 40
@tab 1320
@tab $52800
@item 35
@tab 40
@tab 1360
@tab $55000
@item 36
@tab 40
@tab 1400
@tab $57800
@item 37
@tab 40
@tab 1440
@tab $5A000
@item 38
@tab 40
@tab 1480
@tab $5C800
@item 39
@tab 40
@tab 1520
@tab $5F000
@item 40
@tab 40
@tab 1560
@tab $61800
@item 41
@tab 40
@tab 1600
@tab $64000
@item 42
@tab 40
@tab 1640
@tab $66800
@item 43
@tab 40
@tab 1680
@tab $69000
@item 44
@tab 40
@tab 1720
@tab $6B800
@item 45
@tab 40
@tab 1760
@tab $6E000
@item 46
@tab 40
@tab 1800
@tab $70800
@item 47
@tab 40
@tab 1840
@tab $73000
@item 48
@tab 40
@tab 1880
@tab $75800
@item 49
@tab 40
@tab 1920
@tab $78000
@item 50
@tab 40
@tab 1960
@tab $7A800
@item 51
@tab 40
@tab 2000
@tab $7D000
@item 52
@tab 40
@tab 2040
@tab $7F800
@item 53
@tab 40
@tab 2080
@tab $82000
@item 54
@tab 40
@tab 2120
@tab $84800
@item 55
@tab 40
@tab 2160
@tab $87000
@item 56
@tab 40
@tab 2200
@tab $89800
@item 57
@tab 40
@tab 2240
@tab $8C000
@item 58
@tab 40
@tab 2280
@tab $8E800
@item 59
@tab 40
@tab 2320
@tab $91000
@item 60
@tab 40
@tab 2360
@tab $93800
@item 61
@tab 40
@tab 2400
@tab $96000
@item 62
@tab 40
@tab 2440
@tab $98800
@item 63
@tab 40
@tab 2480
@tab $9B000
@item 64
@tab 40
@tab 2520
@tab $9D800
@item 65
@tab 40
@tab 2560
@tab $A0000
@item 66
@tab 40
@tab 2600
@tab $A2800
@item 67
@tab 40
@tab 2640
@tab $A5000
@item 68
@tab 40
@tab 2680
@tab $A7800
@item 69
@tab 40
@tab 2720
@tab $AA000
@item 70
@tab 40
@tab 2760
@tab $AC800
@item 71
@tab 40
@tab 2800
@tab $AF000
@item 72
@tab 40
@tab 2840
@tab $B1800
@item 73
@tab 40
@tab 2880
@tab $B4000
@item 74
@tab 40
@tab 2920
@tab $B6800
@item 75
@tab 40
@tab 2960
@tab $B9000
@item 76
@tab 40
@tab 3000
@tab $BB800
@item 77
@tab 40
@tab 3040
@tab $BE000
@item 78
@tab 40
@tab 3080
@tab $C0800
@item 79
@tab 40
@tab 3120
@tab $C3000
@item 80
@tab 40
@tab 3160
@tab $C5800
@end multitable

The header sector is stored at 40/0, and contains the disk name,
ID and DOS version bytes, but the BAM is no longer contained here
(like the D64).

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 28 03 44 00 31 35 38 31 20 55 54 49 4C 49 54 59
10: 20 56 30 31 A0 A0 47 42 A0 33 44 A0 A0 00 00 00
20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of the first directory sector (should be set to 40/3 but it doesn't matter, and don't trust what is there, always go to 40/3 for first directory entry)
@item $02
@tab Disk DOS version type (see note below) $44 ('D')=1581
@item $03
@tab $00
@item $04-$13
@tab 16 character Disk Name (padded with $A0)
@item $14-$15
@tab $A0
@item $16-$17
@tab Disk ID
@item $18
@tab $A0
@item $19
@tab DOS Version ("3")
@item $1A
@tab Disk version ("D")
@item $1B-$1C
@tab $A0
@item $1D-$FF
@tab Unused (usually $00)
@end multitable

The following might be set if the disk is a GEOS format (this
info is based on the D64 layout, and might not prove to be true)

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $AB-$AC
@tab Border sector (GEOS only, else set to $00)
@item $AD-$BC
@tab GEOS ID string ("geos FORMAT V1.x" GEOS only, else $00)
@item $BD-$FF
@tab Unused (usually $00)
@end multitable

Note: If the DOS version byte is changed to anything other than
a $44 (or $00), then we have what is called "soft write
protection". Any attempt to write to the disk will return the
"DOS Version" error code 73. The drive is simply telling you
that it thinks the disk format version is incompatible.

The directory track should be contained totally on track 40.
Sectors 3-39 contain the entries and sector 1 and 2 contain the
BAM (Block Availability Map). Sector 0 holds the disk name and
ID. The first directory sector is always 40/3, even though the
t/s pointer at 40/0 (first two bytes) might point somewhere
else. It goes linearly up the sector count, 3-4-5-6-etc. Each
sector holds up to eight entries.

The first two bytes of the sector ($28/$04) indicate the location
of the next track/sector of the directory (40/4). If the track is
set to $00, then it is the last sector of the directory. It is
possible, however unlikely, that the directory may *not* be
competely on track 40. Just follow the chain anyhow.

When the directory is done (track=$00), the sector should contain
an $FF, meaning the whole sector is allocated. Theactual value
doesn't matter as all the entries will be returned anyways. Each
directory sector has the following layout:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 28 04 81 2B 00 53 43 52 45 45 4E 20 20 33 A0 A0
10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 02 00
20: 00 00 81 2B 01 53 43 52 45 45 4E 20 20 34 A0 A0
30: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 03 00
40: 00 00 81 2B 02 53 43 52 45 45 4E 20 20 35 A0 A0
50: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 07 00
60: 00 00 81 2B 08 53 43 52 45 45 4E 20 20 36 A0 A0
70: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 08 00
80: 00 00 81 2B 14 53 43 52 45 45 4E 20 20 37 A0 A0
90: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 07 00
A0: 00 00 81 24 00 53 43 52 45 45 4E 20 20 38 A0 A0
B0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0B 00
C0: 00 00 82 24 04 46 49 4C 45 34 32 39 33 36 39 30
D0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 07 00
E0: 00 00 82 24 06 46 49 4C 45 32 35 37 38 38 31 35
F0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 05 00
@end example


@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First directory entry
@item $20-$3F
@tab Second dir entry
@item $40-$5F
@tab Third dir entry
@item $60-$7F
@tab Fourth dir entry
@item $80-$9F
@tab Fifth dir entry
@item $A0-$BF
@tab Sixth dir entry
@item $C0-$DF
@tab Seventh dir entry
@item $E0-$FF
@tab Eighth dir entry
@end multitable

This is a breakdown of a standard directory entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next directory sector
@item $02
@tab File type
@item $03-$04
@tab Track/sector location of first sector of file or partition
@item $05-$14
@tab 16 character filename (in PETASCII, padded with $A0)
@item $15-$16
@tab Track/Sector location of first SUPER SIDE SECTOR block (REL file only)
@item $17
@tab REL file record length (REL file only)
@item $18-$1B
@tab Unused (except with GEOS disks)
@item $1C-$1D
@tab (Used during an SAVE or OPEN, holds the new t/s link)
@item $1E-$1F
@tab File or partition size in sectors, low/high byte order ($1E+$1F*256). The approx. file size in bytes is <= #sectors * 254
@end multitable

The file type field is used as follows:

@multitable @columnfractions .2 .8
@item @b{Bits}
@tab @b{Description}
@item 0-3
@tab The actual file type
@item 4
@tab Unused
@item 5
@tab Used only during SAVE-@@ replacement
@item 6
@tab Locked flag (Set produces ">" locked files)
@item 7
@tab Closed flag (Not set produces "*", or "splat" files)
@end multitable

The actual file type can be one of the following:

@multitable @columnfractions .2 .2 .6
@item @b{Binary}
@tab @b{Decimal}
@tab @b{File type}
@item 0000
@tab 0
@tab DEL
@item 0001
@tab 1
@tab SEQ
@item 0010
@tab 2
@tab PRG
@item 0011
@tab 3
@tab USR
@item 0100
@tab 4
@tab REL
@item 0101
@tab 5
@tab CBM (partition or sub-directory)
@end multitable

Values 6-15 are illegal, but if used will produce very strange results.

@c @node FIXME
@subsection Non-Standard & Long Directories

Most Commdore floppy disk drives use a single dedicated directory
track where all filenames are stored. This limits the number of
files stored on a disk based on the number of sectors on the
directory track. There are some disk images that contain more
files than would normally be allowed. This requires extending the
directory off the default directory track by changing the last
directory sector pointer to a new track, allocating the new
sectors in the BAM, and manually placing (or moving existing)
file entries there. The directory of an extended disk can be read
and the files that reside there can be loaded without problems on
a real drive. However, this is still a very dangerous practice as
writing to the extended portion of the directory will cause
directory corruption in the non-extended part. Many of the floppy
drives core ROM routines ignore the track value that the
directory is on and assume the default directory track for
operations.

@c @node FIXME
@subsection BAM layout

The BAM is located on 40/1 (for side 0, tracks 1-40) and 40/2
(for side 1, tracks 41-80). Each entry takes up six bytes, one
for the "free sector" count and five for the allocation bitmap.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 28 02 44 BB 47 42 C0 00 00 00 00 00 00 00 00 00
10: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
20: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
30: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
40: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
50: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
60: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
70: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
80: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
90: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
A0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
B0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
C0: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
D0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
E0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
F0: FF FF FF FF 28 FF FF FF FF FF 24 F0 FF 2D FF FE
@end example

@example
Bytes:
$00-$01: Track/sector of next bam sector (40/2)
    $02: Version # ('D')
    $03: One's complement of version# ($BB)
$04-$05: Disk ID bytes (same as 40/0 Disk ID)
    $06: I/O byte
         bit 7 set - Verify on
         bit 7 clear - Verify off
         bit 6 set - Check header CRC
         bit 6 clear - Don't check header CRC
    $07: Auto-boot-loader flag
$08-$0F: Reserved for future (set to $00)
$10-$15: BAM entry for track 1 (track 41, side 1)
$16-$1B: BAM entry for track 2 (track 42, side 1)
         @dots{}
$46-$4B: BAM entry for track 10 (track 50, side 1)
         @dots{}
$82-$87: BAM entry for track 20 (track 60, side 1)
         @dots{}
$BE-$C3: BAM entry for track 30 (track 70, side 1)
         @dots{}
$FA-$FF: BAM entry for track 40 (track 80, side 1)
@end example

The BAM entries require some explanation, so lets look at the
track 40 entry at bytes $FA-FF ($24 $F0 $FF $2D $FF $FE). The
first byte ($24, or 36 decimal) is the number of free sectors
on that track. The next five bytes represent the bitmap of
which sectors are used/free. Since it is five bytes
(8 bits/byte) we have 40 bits of storage. Since this format
has 40 sectors/track, the whole five bytes are used.

@example
 F0: .. .. .. .. .. .. .. .. .. .. 24 F0 FF 2D FF FE
@end example

The last five bytes of any BAM entry must be viewed in binary
to make any sense. We will once again use track 40 as our
reference:

@example
 F0=11110000, FF=11111111, 2D=00101101, FF=11111111, FE=11111110
@end example

In order to make any sense from the binary notation, flip the
bits around.

@example
                   111111 11112222 22222233 33333333
 Sector 01234567 89012345 67890123 45678901 23456789
        -------------------------- -------- --------
        00001111 11111111 10110100 11111111 01111111
@end example

Note that if a bit is on (1), the sector is free. Therefore,
track 40 has sectors 0-3, 17, 20, 22, 23 and 32 used, all the
rest are free.

The second BAM (for side 1) contains the entries for tracks
41-80.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 00 FF 44 BB 47 42 C0 00 00 00 00 00 00 00 00 00
10: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
20: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
30: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
40: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
50: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
60: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
70: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
80: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
90: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
A0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
B0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
C0: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
D0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
E0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
F0: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
@end example

It is laid out exactly as the side 0 BAM except for one
difference. The track/sector reference for the next sector
should be set to $00/$FF, indicating there is no next sector.

@c @node FIXME
@subsection REL files The REL filetype requires some extra explaining.
It was designed to make access to data *anywhere* on the disk
very fast. Take a look at this directory entry@dots{}

@example
 00: 00 FF 84 27 00 41 44 44 49 54 49 4F 4E 41 4C 20
 10: 49 4E 46 4F A0 27 02 FE 00 00 00 00 00 00 D2 0B
@end example

The third byte ($84) indicates this entry is a REL file and
that the three normally empty entries at offset $15, $16 and
$17 are now used as they are explained above. It's the
track/sector chain that this entry points to, called the SUPER
SIDE SECTOR, which is of interest here (in this case, 39/2).
The SUPER SIDE SECTOR is very different from the D64 format. If
you check the D64 entry for a REL file and do the calculations,
you will find that the maximum file size of the REL file is 720
data sectors. With the new SUPER SIDE SECTOR, you can now have
126 groups of these SIDE SECTORS chains, allowing for file
sizes up to (theoretically) 90720 sectors, or about 22.15
Megabytes.

Here is a dump of the beginning of the SUPER SIDE SECTOR@dots{}

@example
 00: 27 01 FE 27 01 15 09 03 0F 38 16 4A 1C 00 00 00
 10: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@example
Bytes:
$00-$01: Track/sector of first side sector in group 0
    $02: Always $FE
$03-$04: Track/sector of first side sector in group 0 (again)
         @dots{}
$FD-$FE: Track/sector of first side sector in group 125
    $FF: Unused (likely $00)
@end example

The side sector layout is the same as the D64/1571.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 12 0A 00 FE 15 09 12 0A 0F 0B 0C 0C 09 0D 06 0E
10: 15 07 15 08 15 0A 15 0B 15 0C 15 0D 15 0E 15 0F
20: 15 10 15 11 15 12 15 13 15 14 15 15 15 16 15 17
30: 15 18 15 19 15 1A 15 1B 15 1C 15 1D 15 1E 15 1F
40: 15 20 15 21 15 22 15 23 15 24 15 25 15 26 15 27
50: 14 00 14 01 14 02 14 03 14 04 14 05 14 06 14 07
60: 14 08 14 09 14 0A 14 0B 14 0C 14 0D 14 0E 14 0F
70: 14 10 14 11 14 12 14 13 14 14 14 15 14 16 14 17
80: 14 18 14 19 14 1A 14 1B 14 1C 14 1D 14 1E 14 1F
90: 14 20 14 21 14 22 14 23 14 24 14 25 14 26 14 27
A0: 13 00 13 01 13 02 13 03 13 04 13 05 13 06 13 07
B0: 13 08 13 09 13 0A 13 0B 13 0C 13 0D 13 0E 13 0F
C0: 13 10 13 11 13 12 13 13 13 14 13 15 13 16 13 17
D0: 13 18 13 19 13 1A 13 1B 13 1C 13 1D 13 1E 13 1F
E0: 13 20 13 21 13 22 13 23 13 24 13 25 13 26 13 27
F0: 12 00 12 01 12 02 12 03 12 04 12 05 12 06 12 07
@end example

@example
Bytes:
    $00: Track location of next side-sector ($00 if last sector)
    $01: Sector location of next side-sector
    $02: Side-sector block number (first sector is $00, the next is
         $01, then $02, etc)
    $03: REL file RECORD size (from directory entry)
$04-$0F: Track/sector locations of the six other side-sectors. Note
         the first entry is this very sector we have listed here.
         The next is the next t/s listed at the beginning of the
         sector. All of this information must be correct. If one of
         these chains is $00/$00, then we have no more side sectors.
         Also, all of these (up to six) side sectors must have the
         same values in this range.
$10-$FF: T/S chains of *each* sector of the data portion. When we
         get a $00/$00, we are at the end of the file.
@end example

@c @node FIXME
@subsection 1581 Partitions and Sub-directories

At the beginning of this section it was stated that the 1581 can
hold 296 entries "at the root level". The 1581 also has the
ability to partition areas of the disk. Under the right
conditions these can become sub-directories, acting as a small
diskette, complete with its own directory and BAM. When you are
inside of a sub-directory, no other files except those in that
directory are visible, or can be affected.

To the 1581, this file will show up as a "CBM" filetype in a
directory. All this does is tell the disk that a file, starting
at X/Y track/sector and Z sectors large exists. Doing a validate
will not harm these files as they have a directory entry, and
are fully allocated in the BAM.

There are two main uses for partitions. One is to simply
allocate a section of the disk to be used for direct-access
reads/writes, and lock it away from being overwritten after a
VALIDATE. The second is as a sub-directory, basically a small
"disk within a disk".

In order to use a partition as a sub-directory, it must adhere
to the following four rules:

@example
 1. If must start on sector 0
 2. It's size must be in multiples of 40 sectors
 3. It must be a minimum of 120 sectors long (3 tracks)
 4. If must not start on or cross track 40, which limits the
    biggest directory to 1600 sectors (tracks 1-39).
@end example

This is a dump of a sub-directory entry:

@example
 00: 00 FF 85 29 00 50 41 52 54 49 54 49 4F 4E 20 31
 10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 40 06
@end example

It is a partition starting on track 41/0, extends for 1600
sectors, and has been formatted as a sub-directory. Note that
when a partition is created, the area being allocated is not
touched in any way. If you want it set up as a sub-directory,
you must issue the FORMAT command to the 1581 to create the
central directory and BAM. Also note that from the directory
entry you can't tell whether it is a sub-directory or not, just
that it fits the sub-directory parameters.

The BAM track for the sub-directory exists on the first track of
the partition, and has the same layout as the disk BAM on track
40. The biggest difference is the "disk name" is what what given
when the partition was formatted rather than what the actual
disk name is. Also, except for the free sectors in the partition
area, all other sectors in the BAM will be allocated.

If the partition size doesn't match the above rules for a
sub-directory, it will simply exist as a "protected" area of the
disk, and can't be used as a sub-directory. Either way, it still
shows up as a "CBM" type in a directory listing. Below is a dump
of a 10-sector partition starting on track 5/1, which does not
qualify as a sub-directory@dots{}

@example
 00: 00 00 85 05 01 53 4D 41 4C 4C 50 41 52 54 20 32
 10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0A 00
@end example

The master BAM shows the entry for this partition on track 5@dots{}

@example
 00: 28 02 44 BB 43 44 C0 00 00 00 00 00 00 00 00 00
 10: 23 C1 FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
 20: FF FF 28 FF FF FF FF FF 1E 01 F8 FF FF FF 28 FF
                             ^^^^^^^^^^^^^^^^^
@end example

The breakdown of the BAM shows the allocation for this track,
with sectors 1-10 allocated, as it should be.

@example
 10000000 00011111 11111111 11111111 11111111
 ^          ^          ^         ^          ^
 0          10         20        30         39
@end example

Partitions and sub-directories share one very important trait.
When created, the sub-directory entry simply has the starting
track/sector and the size of the partition in sectors.
Partitions are created linearly, meaning if one starts on 30/1
and is of size 15 sectors, then the sector range from 1 through
15 on track 30 will be allocated. If a partition size crosses
a track boundary, the allocation will continue on the next
track starting on sector 0, and going up.

The section allocated will *not* have a track/sector chain like
a file would, but rather is dependant on the directory entry to
keep it from being overwritten. You can store whatever you want
to in the allocated area.

@c @node FIXME
@subsection AUTO-BOOT LOADER

If byte $07 in the BAM is set, then when the drive is reset
(and other circumstances) it will look for a USR file called
"COPYRIGHT CBM 86". This file will then be loaded into the
drive RAM and executed.

The format for this auto-loader file is fairly basic. It
starts with a two-byte load address, a size byte, program data,
and a checksum at the end.

@example
Bytes:
       $00-$01: Load address, low/high format
           $02: Size of program (SZ) (smaller than 256 bytes)
$03-($03+SZ-1): Program data
        $03+SZ: Checksum byte
@end example

@node D80, D82, D81, File formats
@section The D80 disk image format

@c FIXME: the D80 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

This is a sector-for-sector copy of an 8050 floppy disk. The
file size for an 8050 image is 533248 bytes. It is comprised
of 256-byte sectors arranged across 77 tracks, with a
varying number of sectors per track for a total of 2083
sectors. Track counting starts at 1 (not 0) and sector
counting starts at 0 (not 1), therefore a track with 29
sectors will go from 0 to 28.

The original media (a 5.25" disk) has the tracks laid out in
circles, with track 1 on the very outside of the disk
(closest to the sides) to track 77 being on the inside of
the disk (closest to the inner hub ring). Commodore, in
their infinite wisdom, varied the number of sectors per
track and data densities across the disk to optimize
available storage, resulting in the chart below. It shows
the sectors/track for a D80. Since the outside diameter of a
circle is the largest (versus closer to the center), the
outside tracks have the largest amount of storage.

@multitable @columnfractions .33 .33 .33
@item @b{Track Range}
@tab @b{Sectors/track}
@tab @b{# Sectors}
@item 1-39
@tab 29
@tab 1131
@item 40-53
@tab 27
@tab 378
@item 54-64
@tab 25
@tab 275
@item 65-77
@tab 23
@tab 299
@end multitable

@multitable @columnfractions .25 .25 .25 .25
@item @b{Track}
@tab @b{#Sect}
@tab @b{#SectorsIn}
@tab @b{D8x Offset}
@item 1
@tab 29
@tab 0
@tab $00000
@item 2
@tab 29
@tab 29
@tab $01D00
@item 3
@tab 29
@tab 58
@tab $03A00
@item 4
@tab 29
@tab 87
@tab $05700
@item 5
@tab 29
@tab 116
@tab $07400
@item 6
@tab 29
@tab 145
@tab $09100
@item 7
@tab 29
@tab 174
@tab $0AE00
@item 8
@tab 29
@tab 203
@tab $0CB00
@item 9
@tab 29
@tab 232
@tab $0E800
@item 10
@tab 29
@tab 261
@tab $10500
@item 11
@tab 29
@tab 290
@tab $12200
@item 12
@tab 29
@tab 319
@tab $13F00
@item 13
@tab 29
@tab 348
@tab $15C00
@item 14
@tab 29
@tab 377
@tab $17900
@item 15
@tab 29
@tab 406
@tab $19600
@item 16
@tab 29
@tab 435
@tab $1B300
@item 17
@tab 29
@tab 464
@tab $1D000
@item 18
@tab 29
@tab 493
@tab $1ED00
@item 19
@tab 29
@tab 522
@tab $20A00
@item 20
@tab 29
@tab 551
@tab $22700
@item 21
@tab 29
@tab 580
@tab $24400
@item 22
@tab 29
@tab 609
@tab $26100
@item 23
@tab 29
@tab 638
@tab $27E00
@item 24
@tab 29
@tab 667
@tab $29B00
@item 25
@tab 29
@tab 696
@tab $2B800
@item 26
@tab 29
@tab 725
@tab $2D500
@item 27
@tab 29
@tab 754
@tab $2F200
@item 28
@tab 29
@tab 783
@tab $30F00
@item 29
@tab 29
@tab 812
@tab $32C00
@item 30
@tab 29
@tab 841
@tab $34900
@item 31
@tab 29
@tab 870
@tab $36600
@item 32
@tab 29
@tab 899
@tab $38300
@item 33
@tab 29
@tab 928
@tab $3A000
@item 34
@tab 29
@tab 957
@tab $3BD00
@item 35
@tab 29
@tab 986
@tab $3DA00
@item 36
@tab 29
@tab 1015
@tab $3F700
@item 37
@tab 29
@tab 1044
@tab $41400
@item 38
@tab 29
@tab 1073
@tab $43100
@item 39
@tab 29
@tab 1102
@tab $44E00
@item 40
@tab 27
@tab 1131
@tab $46B00
@item 41
@tab 27
@tab 1158
@tab $48600
@item 42
@tab 27
@tab 1185
@tab $4A100
@item 43
@tab 27
@tab 1212
@tab $4BC00
@item 44
@tab 27
@tab 1239
@tab $4D700
@item 45
@tab 27
@tab 1266
@tab $4F200
@item 46
@tab 27
@tab 1293
@tab $50D00
@item 47
@tab 27
@tab 1320
@tab $52800
@item 48
@tab 27
@tab 1347
@tab $54300
@item 49
@tab 27
@tab 1374
@tab $55E00
@item 50
@tab 27
@tab 1401
@tab $57900
@item 51
@tab 27
@tab 1428
@tab $59400
@item 52
@tab 27
@tab 1455
@tab $5AF00
@item 53
@tab 27
@tab 1482
@tab $5CA00
@item 54
@tab 25
@tab 1509
@tab $5E500
@item 55
@tab 25
@tab 1534
@tab $5FE00
@item 56
@tab 25
@tab 1559
@tab $61700
@item 57
@tab 25
@tab 1584
@tab $63000
@item 58
@tab 25
@tab 1609
@tab $64900
@item 59
@tab 25
@tab 1634
@tab $66200
@item 60
@tab 25
@tab 1659
@tab $67B00
@item 61
@tab 25
@tab 1684
@tab $69400
@item 62
@tab 25
@tab 1709
@tab $6AD00
@item 63
@tab 25
@tab 1734
@tab $6C600
@item 64
@tab 25
@tab 1759
@tab $6DF00
@item 65
@tab 23
@tab 1784
@tab $6F800
@item 66
@tab 23
@tab 1807
@tab $70F00
@item 67
@tab 23
@tab 1830
@tab $72600
@item 68
@tab 23
@tab 1853
@tab $73D00
@item 69
@tab 23
@tab 1876
@tab $75400
@item 70
@tab 23
@tab 1899
@tab $76B00
@item 71
@tab 23
@tab 1922
@tab $78200
@item 72
@tab 23
@tab 1945
@tab $79900
@item 73
@tab 23
@tab 1968
@tab $7B000
@item 74
@tab 23
@tab 1991
@tab $7C700
@item 75
@tab 23
@tab 2014
@tab $7DE00
@item 76
@tab 23
@tab 2037
@tab $7F500
@item 77
@tab 23
@tab 2060
@tab $80C00
@end multitable

The BAM (Block Availability Map) is on track 38. The D80 is only
77 tracks and so the BAM is contained on 38/0 and 38/3. The BAM
interleave is 3.

The directory is on track 39, with 39/0 contains the header
(DOS type, disk name, disk ID's) and sectors 1-28 contain the
directory entries. Both files and the directory use an
interleave of 1. Since the directory is only 28 sectors large
(29 less one for the header), and each sector can contain only
8 entries (32 bytes per entry), the maximum number of directory
entries is 28 * 8 = 224. The first directory sector is always
39/1. It then follows a chain structure using a sector
interleave of 1 making the links go 39/1, 39/2, 39/3 etc.

When reading a disk, you start with 39/0 (disk label/ID) which
points to 38/0 (BAM0), 38/3 (BAM1), and finally to 39/1 (first
dir entry sector). When writing a file to a blank disk, it will
start at 38/1 because 38/0 is already allocated.

Below is a dump of the header sector 39/0:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 00 43 00 00 00 73 61 6D 70 6C 65 20 64 38 30
10: A0 A0 A0 A0 A0 A0 A0 A0 65 72 A0 32 43 A0 A0 A0
20: A0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@dots{}
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to first BAM sector (38/0)
@item $02
@tab $43 'C' is for DOS format version
@item $03
@tab Reserved
@item $04-$05
@tab Unused
@item $06-$16
@tab Disk name, padded with 0xA0 ("sample d80")
@item $17
@tab 0xA0
@item $18-$19
@tab Disk ID bytes "er"
@item $1A
@tab 0xA0
@item $1B-$1C
@tab DOS version bytes "2C"
@item $1D-$20
@tab 0xA0
@item $21-$FF
@tab Unused
@end multitable

Below is a dump of the first directory sector, 39/1

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 27 02 82 26 01 54 45 53 54 A0 A0 A0 A0 A0 A0 A0
10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
20: 00 00 82 26 02 54 45 53 54 32 A0 A0 A0 A0 A0 A0
30: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
40: 00 00 82 26 04 54 45 53 54 33 A0 A0 A0 A0 A0 A0
50: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 05 00
60: 00 00 82 26 0B 54 45 53 54 34 A0 A0 A0 A0 A0 A0
70: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 09 00
80: 00 00 82 26 14 54 45 53 54 35 A0 A0 A0 A0 A0 A0
90: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0C 00
A0: 00 00 82 28 00 54 45 53 54 36 A0 A0 A0 A0 A0 A0
B0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
C0: 00 00 82 28 01 54 45 53 54 37 A0 A0 A0 A0 A0 A0
D0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
E0: 00 00 82 28 02 54 45 53 54 38 A0 A0 A0 A0 A0 A0
F0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
@end example

The first two bytes of the directory sector ($27/$02) indicate
the location of the next track/sector of the directory (39/2).
If the track is set to $00, then it is the last sector of the
directory.

When the directory is done, the track value will be $00. The sector
link should contain a value of $FF, meaning the whole sector is
allocated, but the actual value doesn't matter. The drive will
return all the available entries anyways. This is a breakdown of a
standard directory sector:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First directory entry
@item $20-$3F
@tab Second dir entry
@item $40-$5F
@tab Third dir entry
@item $60-$7F
@tab Fourth dir entry
@item $80-$9F
@tab Fifth dir entry
@item $A0-$BF
@tab Sixth dir entry
@item $C0-$DF
@tab Seventh dir entry
@item $E0-$FF
@tab Eighth dir entry
@end multitable

This is a breakdown of a standard directory entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next directory sector ($00 $00 if not the first entry in the sector)
@item $02
@tab File type
@item $03-$04
@tab Track/sector location of first sector of file
@item $05-$14
@tab 16 character filename (in PETASCII, padded with $A0)
@item $15-$16
@tab Track/Sector location of first side-sector block (REL file only)
@item $17
@tab REL file record length (REL file only, max. value 254)
@item $18-$1D
@tab Unused
@item $1E-$1F
@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254
@end multitable

The file type field is used as follows:

@multitable @columnfractions .2 .8
@item @b{Bits}
@tab @b{Description}
@item 0-3
@tab The actual file type
@item 4
@tab Unused
@item 5
@tab Used only during SAVE-@@ replacement
@item 6
@tab Locked flag (Set produces ">" locked files)
@item 7
@tab Closed flag (Not set produces "*", or "splat" files)
@end multitable

The actual file type can be one of the following:

@multitable @columnfractions .2 .2 .6
@item @b{Binary}
@tab @b{Decimal}
@tab @b{File type}
@item 0000
@tab 0
@tab DEL
@item 0001
@tab 1
@tab SEQ
@item 0010
@tab 2
@tab PRG
@item 0011
@tab 3
@tab USR
@item 0100
@tab 4
@tab REL
@end multitable

Values 5-15 are illegal, but if used will produce very strange results.

@c @node FIXME
@subsection Non-Standard & Long Directories

Most Commdore floppy disk drives use a single dedicated
directory track where all filenames are stored. This limits the
number of files stored on a disk based on the number of sectors
on the directory track. There are some disk images that contain
more files than would normally be allowed. This requires
extending the directory off the default directory track by
changing the last directory sector pointer to a new track,
allocating the new sectors in the BAM, and manually placing (or
moving existing) file entries there. The directory of an
extended disk can be read and the files that reside there can
be loaded without problems on a real drive. However, this is
still a very dangerous practice as writing to the extended
portion of the directory will cause directory corruption in the
non-extended part. Many of the floppy drives core ROM routines
ignore the track value that the directory is on and assume the
default directory track for operations.

@c @node FIXME
@subsection BAM layout

The BAM only occupies up to four sectors on track 38, so the
rest of the track is empty and is available for file storage.
Below is a dump of the first BAM block, 38/0. A D80 will only
contain two BAM sectors, 38/0 and 38/3. Each entry takes 5
bytes, 1 for the free count on that track, and 4 for the BAM
bits.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 03 43 00 01 33 1D FF FF FF 1F 1D FF FF FF 1F
10: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
20: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
30: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
40: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
50: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
60: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
70: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
80: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
90: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
A0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
B0: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1B
C0: F6 FF FF 1F 1B FC FF FF 1F 1B FF FF FF 07 1B FF
D0: FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF
E0: FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF
F0: 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to second BAM sector (38/3)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x01=1)
@item $05
@tab Highest+1 track covered by this BAM (0x33=51)
@item $06-$0A
@tab BAM for track 1. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 2
@item @dots{}
@tab @dots{}
@item $FB-$FF
@tab BAM for track 50
@end multitable

Being bit-based, the BAM entries need some explanation. The
first track entry in the above BAM sector is at offset 06,
"1D FF FF FF 1F". The first number is how many blocks are
free on this track ($1D=29) and the remainder is the bit
representation of the usage map for the track. These
entries must be viewed in binary to make any sense. First
convert the values to binary:

@example
 FF=11111111, FF=11111111, FF=11111111, 1F=00011111
@end example

In order to make any sense from the binary notation, flip the
bits around.

@example
            111111 11112222 222222
 01234567 89012345 67890123 456789@dots{}
 -------------------------- ---------
 11111111 11111111 11111111 11111000
 ^                              ^
 sector 0                   sector 28
@end example

Since we are on the first track, we have 29 sectors, and only
use up to the bit 28 position. If a bit is on (1), the sector
is free. Therefore, track 1 is clean, all sectors are free.
Any leftover bits that refer to sectors that don't exist,
like bits 29-31 in the above example, are set to allocated.

Second BAM block 38/3.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 27 01 43 00 33 4E 1B FF FF FF 07 1B FF FF FF 07
10: 1B FF FF FF 07 19 FF FF FF 01 19 FF FF FF 01 19
20: FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF
30: FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF FF
40: FF 01 19 FF FF FF 01 19 FF FF FF 01 17 FF FF 7F
50: 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00
60: 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17
70: FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF
80: FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 00 00 00
90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to second BAM sector (39/1)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x33=51)
@item $05
@tab Highest+1 track covered by this BAM (0x43=78)
@item $06-$0A
@tab BAM for track 51. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 52
@item @dots{}
@tab @dots{}
@item $88-$8C
@tab BAM for track 77
@item $8D-$FF
@tab Not used
@end multitable

@node D82, P00, D80, File formats
@section The D82 disk image format

@c FIXME: the D82 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

This is a sector-for-sector copy of an 8250 floppy disk. The file
size for an 8250 image is 1066496 bytes. It is comprised of
256-byte sectors arranged across 154 tracks, with a varying
number of sectors per track for a total of 4166 sectors. Track
counting starts at 1 (not 0) and sector counting starts at 0
(not 1), therefore a track with 29 sectors will go from 0 to 28.

The original media (a 5.25" disk) has the tracks laid out in
circles, with track 1 on the very outside of the disk (closest
to the sides) to track 77 being on the inside of the disk
(closest to the inner hub ring). Commodore, in their infinite
wisdom, varied the number of sectors per track and data
densities across the disk to optimize available storage,
resulting in the chart below. It shows the sectors/track for a
D82. Since the outside diameter of a circle is the largest
(versus closer to the center), the outside tracks have the
largest amount of storage.


@multitable @columnfractions .33 .33 .33
@item @b{Track Range}
@tab @b{Sectors/track}
@tab @b{# Sectors}
@item 1-39
@tab 29
@tab 1131
@item 40-53
@tab 27
@tab 378
@item 55-64
@tab 25
@tab 275
@item 65-77
@tab 23
@tab 299
@item 78-116
@tab 29
@tab 1131
@item 117-130
@tab 27
@tab 378
@item 131-141
@tab 25
@tab 275
@item 142-154
@tab 23
@tab 299
@end multitable

@multitable @columnfractions .25 .25 .25 .25
@item @b{Track}
@tab @b{#Sect}
@tab @b{#SectorsIn}
@tab @b{D82 Offset}
@item 1
@tab 29
@tab 0
@tab $000000
@item 2
@tab 29
@tab 29
@tab $001D00
@item 3
@tab 29
@tab 58
@tab $003A00
@item 4
@tab 29
@tab 87
@tab $005700
@item 5
@tab 29
@tab 116
@tab $007400
@item 6
@tab 29
@tab 145
@tab $009100
@item 7
@tab 29
@tab 174
@tab $00AE00
@item 8
@tab 29
@tab 203
@tab $00CB00
@item 9
@tab 29
@tab 232
@tab $00E800
@item 10
@tab 29
@tab 261
@tab $010500
@item 11
@tab 29
@tab 290
@tab $012200
@item 12
@tab 29
@tab 319
@tab $013F00
@item 13
@tab 29
@tab 348
@tab $015C00
@item 14
@tab 29
@tab 377
@tab $017900
@item 15
@tab 29
@tab 406
@tab $019600
@item 16
@tab 29
@tab 435
@tab $01B300
@item 17
@tab 29
@tab 464
@tab $01D000
@item 18
@tab 29
@tab 493
@tab $01ED00
@item 19
@tab 29
@tab 522
@tab $020A00
@item 20
@tab 29
@tab 551
@tab $022700
@item 21
@tab 29
@tab 580
@tab $024400
@item 22
@tab 29
@tab 609
@tab $026100
@item 23
@tab 29
@tab 638
@tab $027E00
@item 24
@tab 29
@tab 667
@tab $029B00
@item 25
@tab 29
@tab 696
@tab $02B800
@item 26
@tab 29
@tab 725
@tab $02D500
@item 27
@tab 29
@tab 754
@tab $02F200
@item 28
@tab 29
@tab 783
@tab $030F00
@item 29
@tab 29
@tab 812
@tab $032C00
@item 30
@tab 29
@tab 841
@tab $034900
@item 31
@tab 29
@tab 870
@tab $036600
@item 32
@tab 29
@tab 899
@tab $038300
@item 33
@tab 29
@tab 928
@tab $03A000
@item 34
@tab 29
@tab 957
@tab $03BD00
@item 35
@tab 29
@tab 986
@tab $03DA00
@item 36
@tab 29
@tab 1015
@tab $03F700
@item 37
@tab 29
@tab 1044
@tab $041400
@item 38
@tab 29
@tab 1073
@tab $043100
@item 39
@tab 29
@tab 1102
@tab $044E00
@item 40
@tab 27
@tab 1131
@tab $046B00
@item 41
@tab 27
@tab 1158
@tab $048600
@item 42
@tab 27
@tab 1185
@tab $04A100
@item 43
@tab 27
@tab 1212
@tab $04BC00
@item 44
@tab 27
@tab 1239
@tab $04D700
@item 45
@tab 27
@tab 1266
@tab $04F200
@item 46
@tab 27
@tab 1293
@tab $050D00
@item 47
@tab 27
@tab 1320
@tab $052800
@item 48
@tab 27
@tab 1347
@tab $054300
@item 49
@tab 27
@tab 1374
@tab $055E00
@item 50
@tab 27
@tab 1401
@tab $057900
@item 51
@tab 27
@tab 1428
@tab $059400
@item 52
@tab 27
@tab 1455
@tab $05AF00
@item 53
@tab 27
@tab 1482
@tab $05CA00
@item 54
@tab 25
@tab 1509
@tab $05E500
@item 55
@tab 25
@tab 1534
@tab $05FE00
@item 56
@tab 25
@tab 1559
@tab $061700
@item 57
@tab 25
@tab 1584
@tab $063000
@item 58
@tab 25
@tab 1609
@tab $064900
@item 59
@tab 25
@tab 1634
@tab $066200
@item 60
@tab 25
@tab 1659
@tab $067B00
@item 61
@tab 25
@tab 1684
@tab $069400
@item 62
@tab 25
@tab 1709
@tab $06AD00
@item 63
@tab 25
@tab 1734
@tab $06C600
@item 64
@tab 25
@tab 1759
@tab $06DF00
@item 65
@tab 23
@tab 1784
@tab $06F800
@item 66
@tab 23
@tab 1807
@tab $070F00
@item 67
@tab 23
@tab 1830
@tab $072600
@item 68
@tab 23
@tab 1853
@tab $073D00
@item 69
@tab 23
@tab 1876
@tab $075400
@item 70
@tab 23
@tab 1899
@tab $076B00
@item 71
@tab 23
@tab 1922
@tab $078200
@item 72
@tab 23
@tab 1945
@tab $079900
@item 73
@tab 23
@tab 1968
@tab $07B000
@item 74
@tab 23
@tab 1991
@tab $07C700
@item 75
@tab 23
@tab 2014
@tab $07DE00
@item 76
@tab 23
@tab 2037
@tab $07F500
@item 77
@tab 23
@tab 2060
@tab $080C00
@item 78
@tab 29
@tab 2083
@tab $082300
@item 79
@tab 29
@tab 2112
@tab $084000
@item 80
@tab 29
@tab 2141
@tab $085D00
@item 81
@tab 29
@tab 2170
@tab $087A00
@item 82
@tab 29
@tab 2199
@tab $089700
@item 83
@tab 29
@tab 2228
@tab $08B400
@item 84
@tab 29
@tab 2257
@tab $08D100
@item 85
@tab 29
@tab 2286
@tab $08EE00
@item 86
@tab 29
@tab 2315
@tab $090600
@item 87
@tab 29
@tab 2344
@tab $092800
@item 88
@tab 29
@tab 2373
@tab $094500
@item 89
@tab 29
@tab 2402
@tab $096200
@item 90
@tab 29
@tab 2431
@tab $097F00
@item 91
@tab 29
@tab 2460
@tab $099C00
@item 92
@tab 29
@tab 2489
@tab $09B900
@item 93
@tab 29
@tab 2518
@tab $09D600
@item 94
@tab 29
@tab 2547
@tab $09F300
@item 95
@tab 29
@tab 2576
@tab $0A1000
@item 96
@tab 29
@tab 2605
@tab $0A2D00
@item 97
@tab 29
@tab 2634
@tab $0A4A00
@item 98
@tab 29
@tab 2663
@tab $0A6700
@item 99
@tab 29
@tab 2692
@tab $0A8400
@item 100
@tab 29
@tab 2721
@tab $0AA100
@item 101
@tab 29
@tab 2750
@tab $0ABE00
@item 102
@tab 29
@tab 2779
@tab $0ADB00
@item 103
@tab 29
@tab 2808
@tab $0AF800
@item 104
@tab 29
@tab 2837
@tab $0B1500
@item 105
@tab 29
@tab 2866
@tab $0B3200
@item 106
@tab 29
@tab 2895
@tab $0B4F00
@item 107
@tab 29
@tab 2924
@tab $0B6C00
@item 108
@tab 29
@tab 2953
@tab $0B8900
@item 109
@tab 29
@tab 2982
@tab $0BA600
@item 110
@tab 29
@tab 3011
@tab $0BC300
@item 111
@tab 29
@tab 3040
@tab $0BE000
@item 112
@tab 29
@tab 3069
@tab $0BFD00
@item 113
@tab 29
@tab 3098
@tab $0C1A00
@item 114
@tab 29
@tab 3137
@tab $0C3700
@item 115
@tab 29
@tab 3156
@tab $0C5400
@item 116
@tab 29
@tab 3185
@tab $0C7100
@item 117
@tab 27
@tab 3214
@tab $0C8E00
@item 118
@tab 27
@tab 3241
@tab $0CA900
@item 119
@tab 27
@tab 3268
@tab $0CC400
@item 120
@tab 27
@tab 3295
@tab $0CDF00
@item 121
@tab 27
@tab 3322
@tab $0CFA00
@item 122
@tab 27
@tab 3349
@tab $0D1500
@item 123
@tab 27
@tab 3376
@tab $0D3000
@item 124
@tab 27
@tab 3403
@tab $0D4B00
@item 125
@tab 27
@tab 3430
@tab $0D6600
@item 126
@tab 27
@tab 3457
@tab $0D8100
@item 127
@tab 27
@tab 3484
@tab $0D9C00
@item 128
@tab 27
@tab 3511
@tab $0DB700
@item 129
@tab 27
@tab 3538
@tab $0DD200
@item 130
@tab 27
@tab 3565
@tab $0DED00
@item 131
@tab 25
@tab 3592
@tab $0E0800
@item 132
@tab 25
@tab 3617
@tab $0E2100
@item 133
@tab 25
@tab 3642
@tab $0E3A00
@item 134
@tab 25
@tab 3667
@tab $0E5300
@item 135
@tab 25
@tab 3692
@tab $0E6C00
@item 136
@tab 25
@tab 3717
@tab $0E8500
@item 137
@tab 25
@tab 3742
@tab $0E9E00
@item 138
@tab 25
@tab 3767
@tab $0EB700
@item 139
@tab 25
@tab 3792
@tab $0ED000
@item 140
@tab 25
@tab 3817
@tab $0EE900
@item 141
@tab 25
@tab 3842
@tab $0F0200
@item 142
@tab 23
@tab 3867
@tab $0F1B00
@item 143
@tab 23
@tab 3890
@tab $0F3200
@item 144
@tab 23
@tab 3913
@tab $0F4900
@item 145
@tab 23
@tab 3936
@tab $0F6000
@item 146
@tab 23
@tab 3959
@tab $0F7700
@item 147
@tab 23
@tab 3982
@tab $0F8E00
@item 148
@tab 23
@tab 4005
@tab $0FA500
@item 149
@tab 23
@tab 4028
@tab $0FBC00
@item 150
@tab 23
@tab 4051
@tab $0FD300
@item 151
@tab 23
@tab 4074
@tab $0FEA00
@item 152
@tab 23
@tab 4097
@tab $100100
@item 153
@tab 23
@tab 4120
@tab $101800
@item 154
@tab 23
@tab 4143
@tab $102F00
@end multitable

The BAM (Block Availability Map) is on track 38. The D82 is 154
tracks and so the BAM is contained on 38/0, 38/3, 38/6 and 38/9.
The BAM interleave is 3.

The directory is on track 39, with 39/0 contains the header (DOS
type, disk name, disk ID's) and sectors 1-28 contain the
directory entries. Both files and the directory use an
interleave of 1. Since the directory is only 28 sectors large
(29 less one for the header), and each sector can contain only 8
entries (32 bytes per entry), the maximum number of directory
entries is 28 * 8 = 224. The first directory sector is always
39/1. It then follows a chain structure using a sector
interleave of 1 making the links go 39/1, 39/2, 39/3 etc.

When reading a disk, you start with 39/0 (disk label/ID) which
points to 38/0 (BAM0), 38/3 (BAM1), 38/6 (BAM2), 38/9 (BAM3, and
finally to 39/1 (first dir entry sector). When writing a file to
a blank disk, it will start at 38/1 because 38/0 is already
allocated.

Below is a dump of the header sector 39/0:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 00 43 00 00 00 73 61 6D 70 6C 65 20 64 38 30
10: A0 A0 A0 A0 A0 A0 A0 A0 65 72 A0 32 43 A0 A0 A0
20: A0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@dots{}
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to first BAM sector (38/0)
@item $02
@tab $43 'C' is for DOS format version
@item $03
@tab Reserved
@item $04-$05
@tab Unused
@item $06-$16
@tab Disk name, padded with 0xA0 ("sample d82")
@item $17
@tab 0xA0
@item $18-$19
@tab Disk ID bytes "er"
@item $1A
@tab 0xA0
@item $1B-$1C
@tab DOS version bytes "2C"
@item $1D-$20
@tab 0xA0
@item $21-$FF
@tab Unused
@end multitable

Below is a dump of the first directory sector, 39/1

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 27 02 82 26 01 54 45 53 54 A0 A0 A0 A0 A0 A0 A0
10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
20: 00 00 82 26 02 54 45 53 54 32 A0 A0 A0 A0 A0 A0
30: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
40: 00 00 82 26 04 54 45 53 54 33 A0 A0 A0 A0 A0 A0
50: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 05 00
60: 00 00 82 26 0B 54 45 53 54 34 A0 A0 A0 A0 A0 A0
70: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 09 00
80: 00 00 82 26 14 54 45 53 54 35 A0 A0 A0 A0 A0 A0
90: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0C 00
A0: 00 00 82 28 00 54 45 53 54 36 A0 A0 A0 A0 A0 A0
B0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
C0: 00 00 82 28 01 54 45 53 54 37 A0 A0 A0 A0 A0 A0
D0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
E0: 00 00 82 28 02 54 45 53 54 38 A0 A0 A0 A0 A0 A0
F0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
@end example

The first two bytes of the directory sector ($27/$02) indicate
the location of the next track/sector of the directory (39/2).
If the track is set to $00, then it is the last sector of the
directory.

When the directory is done, the track value will be $00. The
sector link should contain a value of $FF, meaning the whole
sector is allocated, but the actual value doesn't matter. The
drive will return all the available entries anyways. This is a
breakdown of a standard directory sector:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First directory entry
@item $20-$3F
@tab Second dir entry
@item $40-$5F
@tab Third dir entry
@item $60-$7F
@tab Fourth dir entry
@item $80-$9F
@tab Fifth dir entry
@item $A0-$BF
@tab Sixth dir entry
@item $C0-$DF
@tab Seventh dir entry
@item $E0-$FF
@tab Eighth dir entry
@end multitable

This is a breakdown of a standard directory entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next directory sector ($00 $00 if not the first entry in the sector)
@item $02
@tab File type
@item $03-$04
@tab Track/sector location of first sector of file
@item $05-$14
@tab 16 character filename (in PETASCII, padded with $A0)
@item $15-$16
@tab Track/Sector location of first side-sector block (REL file only)
@item $17
@tab REL file record length (REL file only, max. value 254)
@item $18-$1D
@tab Unused
@item $1E-$1F
@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254
@end multitable

The file type field is used as follows:

@multitable @columnfractions .2 .8
@item @b{Bits}
@tab @b{Description}
@item 0-3
@tab The actual file type
@item 4
@tab Unused
@item 5
@tab Used only during SAVE-@@ replacement
@item 6
@tab Locked flag (Set produces ">" locked files)
@item 7
@tab Closed flag (Not set produces "*", or "splat" files)
@end multitable

The actual file type can be one of the following:

@multitable @columnfractions .2 .2 .6
@item @b{Binary}
@tab @b{Decimal}
@tab @b{File type}
@item 0000
@tab 0
@tab DEL
@item 0001
@tab 1
@tab SEQ
@item 0010
@tab 2
@tab PRG
@item 0011
@tab 3
@tab USR
@item 0100
@tab 4
@tab REL
@end multitable

Values 5-15 are illegal, but if used will produce very strange results.

@c @node FIXME
@subsection Non-Standard & Long Directories

Most Commdore floppy disk drives use a single dedicated
directory track where all filenames are stored. This limits the
number of files stored on a disk based on the number of sectors
on the directory track. There are some disk images that contain
more files than would normally be allowed. This requires
extending the directory off the default directory track by
changing the last directory sector pointer to a new track,
allocating the new sectors in the BAM, and manually placing (or
moving existing) file entries there. The directory of an
extended disk can be read and the files that reside there can
be loaded without problems on a real drive. However, this is
still a very dangerous practice as writing to the extended
portion of the directory will cause directory corruption in the
non-extended part. Many of the floppy drives core ROM routines
ignore the track value that the directory is on and assume the
default directory track for operations.

@c @node FIXME
@subsection BAM layout

The BAM only occupies up to four sectors on track 38, so the
rest of the track is empty and is available for file storage.
Below is a dump of the first BAM block, 38/0. A D82 will
contain four BAM sectors, 38/0, 38/3, 38/6 and 38/9. Each
entry takes 5 bytes, 1 for the free count on that track, and
4 for the BAM bits.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 03 43 00 01 33 1D FF FF FF 1F 1D FF FF FF 1F
10: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
20: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
30: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
40: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
50: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
60: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
70: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
80: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
90: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
A0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
B0: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1B
C0: F6 FF FF 1F 1B FC FF FF 1F 1B FF FF FF 07 1B FF
D0: FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF
E0: FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF
F0: 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to second BAM sector (38/3)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x01=1)
@item $05
@tab Highest+1 track covered by this BAM (0x33=51)
@item $06-$0A
@tab BAM for track 1. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 2
@item @dots{}
@tab @dots{}
@item $FB-$FF
@tab BAM for track 50
@end multitable

Being bit-based, the BAM entries need some explanation. The
first track entry in the above BAM sector is at offset 06,
"1D FF FF FF 1F". The first number is how many blocks are free
on this track ($1D=29) and the remainder is the bit
representation of the usage map for the track. These entries
must be viewed in binary to make any sense. First convert the
values to binary:

@example
 FF=11111111, FF=11111111, FF=11111111, 1F=00011111
@end example

In order to make any sense from the binary notation, flip the
bits around.

@example
            111111 11112222 222222
 01234567 89012345 67890123 456789@dots{}
 -------------------------- ---------
 11111111 11111111 11111111 11111000
 ^                              ^
 sector 0                  sector 28
@end example

Since we are on the first track, we have 29 sectors, and only
use up to the bit 28 position. If a bit is on (1), the sector is
free. Therefore, track 1 is clean, all sectors are free. Any
leftover bits that refer to sectors that don't exist, like bits
29-31 in the above example, are set to allocated.

Second BAM block 38/3

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 06 43 00 33 65 1B FF FF FF 07 1B FF FF FF 07
10: 1B FF FF FF 07 19 FF FF FF 01 19 FF FF FF 01 19
20: FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF
30: FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF FF
40: FF 01 19 FF FF FF 01 19 FF FF FF 01 17 FF FF 7F
50: 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00
60: 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17
70: FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF
80: FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 1D FF FF
90: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
A0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
B0: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
C0: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
D0: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
E0: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
F0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to third BAM sector (38/6)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x33=51)
@item $05
@tab Highest+1 track covered by this BAM (0x65=101)
@item $06-$0A
@tab BAM for track 51. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 52
@item @dots{}
@tab @dots{}
@item $FB-$FF
@tab BAM for track 100
@end multitable

Third BAM block 38/6

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 09 43 00 65 97 1D FF FF FF 1F 1D FF FF FF 1F
10: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
20: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
30: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
40: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
50: 1F 1D FF FF FF 1F 1B FF FF FF 07 1B FF FF FF 07
60: 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B
70: FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF
80: FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF
90: FF 07 1B FF FF FF 07 1B FF FF FF 07 19 FF FF FF
A0: 01 19 FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01
B0: 19 FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19
C0: FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF
D0: FF FF 01 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF
E0: 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F
F0: 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to fourth BAM sector (38/9)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x65=101)
@item $05
@tab Highest+1 track covered by this BAM (0x97=151)
@item $06-$0A
@tab BAM for track 101. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 102
@item @dots{}
@tab @dots{}
@item $FB-$FF
@tab BAM for track 150
@end multitable

Fourth BAM block 38/9

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 27 01 43 00 97 9B 17 FF FF 7F 00 17 FF FF 7F 00
10: 17 FF FF 7F 00 17 FF FF 7F 00 00 00 00 00 00 00
20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to first directory sector (39/1)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x97=151)
@item $05
@tab Highest+1 track covered by this BAM (0x9B=155)
@item $06-$0A
@tab BAM for track 151. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 152
@item @dots{}
@tab @dots{}
@item $15-$19
@tab BAM for track 154
@item $1A-$FF
@tab Not used
@end multitable

@node P00, , D82, File formats
@section The P00 image format

@c FIXME: the P00 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

These files were created for use in the PC64 emulator, written
by Wolfgang Lorenz. Each one has the same layout with the
filetype being stored in the DOS extension (i.e. Pxx is a PRG,
Sxx is a SEQ, Uxx is a USR and Rxx is a RELative file), and the
header is only 26 bytes long.

This is a dump of a Pxx file (PRG)@dots{}

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
0000: 43 36 34 46 69 6C 65 00 43 52 49 53 49 53 20 4D
0010: 4F 55 4E 54 41 49 4E 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$06
@tab ASCII string "C64File"
@item $07
@tab Always $00
@item $08-$17
@tab Filename in PETASCII, padded with $00 (not $A0, like a D64)
@item $18
@tab Always $00
@item $19
@tab REL file record size ($00 if not a REL file)
@item $1A-??
@tab Program data
@end multitable

The 'xx' in the extension of the file is usually 00, except when
we have two DOS filenames which would be the same, but the C64
filenames are different! If we have two C64 filenames which are
the same, they *cannot* co-exist in the same directory. If we
have two files which do convert down to be the same DOS
filename, the extension is incremented until an unused one is
found (x01, x02, x03, up to x99). We can have up to 99 different
C64 files with the same corresponding DOS names as that's all
the extension will hold (from P00 to P99).

Each PC64 file only has one entry, there are no multi-file
containers allowed. This could result in a large number of
these files in a directory, even for only a few programs, as
each C64 file will result in a PC64 file entry. The best use
for a PC64 file is a single-file program, one which does not
load anything else.

@c FIXME: the CRT section needs to be style-checked.

@c @node FIXME
@section The CRT cartridge image format

This chapter is based on CRT.txt (rev1.14) compiled by Peter Schepers, with
additional contributions from Per Hakan Sundell, Markus Brenner,
Marco Van Den Heuvel, Groepaz.

  Cartridge files were introduced in the CCS64  emulator,  written  by  Per
Hakan Sundell, and use the ".CRT" file extension. This format  was  created
to handle the various ROM cartridges that exist, such as Action Replay, the
Power cartridge, and the Final Cartridge.

  Normal game cartridges can load  into  several  different  memory  ranges
($8000-9FFF,  $A000-BFFF  or  $E000-FFFF).  Newer   utility   and   freezer
cartridges were less intrusive, hiding themselves until  called  upon,  and
still others used bank-switching techniques to allow much larger ROM's than
normal. Because of these "stealthing" and bank-switching methods, a special
cartridge format  was  necessary,  to  let  the  emulator  know  where  the
cartridge should reside, the control line  states  to  enable  it  and  any
special hardware features it uses.

@subsection Header contents

  Here is a dump of a sample 8K normal cartridge,  "Attack  Of  The  Mutant
Camels"@dots{}

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 00 00 01 00 00 00 00 00 00   ???@@????????????
0020: 41 54 54 41 43 4B 20 4F 46 20 54 48 45 20 4D 55   ATTACK?OF?THE?MU
0030: 54 41 4E 54 20 43 41 4D 45 4C 53 00 00 00 00 00   TANT?CAMELS?????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: D3 9B BC FE C3 C2 CD 38 30 EA EA EA A9 01 85 13   .›?....80....?…?
0060: 4C B3 9B A9 08 85 5A 88 D0 FD C6 5A D0 F9 60 D0   Lł›.?…Z�...Z.?`.
@end example

@example
  Bytes:$0000-000F - 16-byte cartridge signature  "C64  CARTRIDGE"  (padded
                     with space characters)
         0010-0013 - File header length  ($00000040,  in  high/low  format,
                     calculated from offset $0000). The default  (also  the
                     minimum) value is $40.  Some  cartridges  exist  which
                     show a value of $00000020 which is wrong.
         0014-0015 - Cartridge version (high/low, presently 01.00)
         0016-0017 - Cartridge hardware type ($0000, high/low)
                       0 - Normal cartridge
                       1 - Action Replay
                       2 - KCS Power Cartridge
                       3 - Final Cartridge III
                       4 - Simons' BASIC
                       5 - Ocean type 1*
                       6 - Expert Cartridge
                       7 - Fun Play, Power Play
                       8 - Super Games
                       9 - Atomic Power
                      10 - Epyx Fastload
                      11 - Westermann Learning
                      12 - Rex Utility
                      13 - Final Cartridge I
                      14 - Magic Formel
                      15 - C64 Game System, System 3
                      16 - Warp Speed
                      17 - Dinamic**
                      18 - Zaxxon, Super Zaxxon (SEGA)
                      19 - Magic Desk, Domark, HES Australia
                      20 - Super Snapshot V5
                      21 - Comal-80
                      22 - Structured BASIC
                      23 - Ross
                      24 - Dela EP64
                      25 - Dela EP7x8
                      26 - Dela EP256
                      27 - Rex EP256
                      28 - Mikro Assembler
                      29 - Final Cartridge Plus
                      30 - Action Replay 4
                      31 - Stardos
                      32 - EasyFlash
                      33 - EasyFlash Xbank
                      34 - Capture
                      35 - Action Replay 3
                      36 - Retro Replay
                      37 - MMC64
                      38 - MMC Replay
                      39 - IDE64
                      40 - Super Snapshot V4
                      41 - IEEE-488
                      42 - Game Killer
                      43 - Prophet64
                      44 - EXOS
                      45 - Freeze Frame
                      46 - Freeze Machine
                      47 - Snapshot64
                      48 - Super Explode V5.0
                      49 - Magic Voice
                      50 - Action Replay 2
                      51 - MACH 5
                      52 - Diashow-Maker
                      53 - Pagefox
                      54 - Kingsoft
                      55 - Silverrock 128K Cartridge
                      56 - Formel 64
                      57 - RGCD
              0018 - Cartridge port EXROM line status
                      0 - active (lo)
                      1 - inactive (hi)
              0019 - Cartridge port GAME line status
                      0 - active (lo)
                      1 - inactive (hi)
         001A-001F - Reserved for future use
         0020-003F - 32-byte cartridge  name  "CCSMON"  (uppercase,  padded
                     with null characters)
         0040-xxxx - Cartridge contents (called CHIP PACKETS, as there  can
                     be more than one  per  CRT  file).  See  below  for  a
                     breakdown of the CHIP format.
@end example

  (*Note: Ocean type 1 includes Navy Seals, Robocop 2 & 3,  Shadow  of  the
    Beast, Toki, Terminator 2 and more)

  (**Note: Dinamic includes Narco Police and more)

@c @node FIXME
@subsection CHIP Contents


  The following is the contents of the CHIP packet, from position $0040  on
in the CRT file. Note I have re-adjusted the starting address to be  $0000,
since we are now looking at a file contained in the .CRT file, and all size
references are from where it starts.

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0010: D3 9B BC FE C3 C2 CD 38 30 EA EA EA A9 01 85 13   .›?....80....?…?
0020: 4C B3 9B A9 08 85 5A 88 D0 FD C6 5A D0 F9 60 D0   Lł›.?…Z�...Z.?`.
0030: F2 60 A9 04 85 49 A9 00 85 48 A2 00 A5 48 9D 40   ?`.?…I.?…H.?ĄHť@@
0040: 03 A5 49 9D 60 03 A5 48 18 69 28 85 48 A5 49 69   ?ĄIť`?ĄH?i(…HĄIi
0050: 00 85 49 E8 E0 18 D0 E4 60 A6 03 A4 02 BD 40 03   ?…I???.?`?????@@?
@end example

@example
  Bytes:$0000-0003 - Contained ROM signature "CHIP" (note there can be more
                     than one image in a .CRT file)
         0004-0007 - Total packet length ($00002010,  ROM  image  size  and
                     header combined) (high/low format)
         0008-0009 - Chip type
                      0 - ROM
                      1 - RAM, no ROM data
                      2 - Flash ROM
         000A-000B - Bank number ($0000 - normal cartridge)
         000C-000D - Starting load address (high/low format)
         000E-000F - ROM image size in bytes  (high/low  format,  typically
                     $2000 or $4000)
         0010-xxxx - ROM data
@end example

  The following is a chart taken from the "Commodore Programmers  Reference
Guide". It details the state of various areas of memory  depending  on  the
state of the control lines.


Legend:
L - ROML (low)
H - ROMH (high)
G - GAME
E - EXROM

@example
Addr       LHGE   LHGE   LHGE   LHGE   LHGE   LHGE   LHGE   LHGE   LHGE
Range
           1111   101X   1000   011X   001X   1110   0100   1100   XX01
         default                00X0                             Ultimax
-------------------------------------------------------------------------
E000-FFFF Kernal  RAM    RAM   Kernal  RAM   Kernal Kernal Kernal ROMH(*)
D000-DFFF IO/CHR IO/CHR IO/RAM IO/CHR  RAM   IO/CHR IO/CHR IO/CHR   I/O
C000-CFFF  RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM     -
A000-BFFF BASIC   RAM    RAM    RAM    RAM   BASIC   ROMH   ROMH    -
8000-9FFF  RAM    RAM    RAM    RAM    RAM    ROML   RAM    ROML  ROML(*)
4000-7FFF  RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM     -
1000-3FFF  RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM     -
0000-0FFF  RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM
@end example

(*) Internal memory does not respond to write accesses in these areas


  From the above chart, the following table can be built. It shows standard
cartridges, either 8K or 16K in size, and the memory ranges they load into.

@example
Type     Size   Game   EXRom  Low Bank  High Bank
         in K   Line   Line    (ROML)    (ROMH)
-------------------------------------------------
Normal    8k     hi     lo     $8000      ----
Normal    16k    lo     lo     $8000     $A000
Ultimax   8k     lo     hi     $E000      ----
@end example

  The ROMH and ROML lines are CPU-controlled status  lines,  used  to  bank
in/out RAM, ROM or I/O, depending on what is needed at the time.

  Ultimax cartridges typically are situated  in  the  $E000-FFFF  (8K)  ROM
address range. There are some cartridges  which  only  use  4K  of  the  8K
allocation. If the cartridge is 16K in size, then it will  reside  in  both
$8000-9FFF and $E000-FFFF.

@c @node FIXME
@subsection Cartridge Specifics

@c @node FIXME
@subsubsection 0 - Normal cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 00 00 01 00 00 00 00 00 00   ???@@????????????
0020: 41 54 54 41 43 4B 20 4F 46 20 54 48 45 20 4D 55   ATTACK?OF?THE?MU
0030: 54 41 4E 54 20 43 41 4D 45 4C 53 00 00 00 00 00   TANT?CAMELS?????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: D3 9B BC FE C3 C2 CD 38 30 EA EA EA A9 01 85 13   .›?....80....?…?
@end example

      The second sample below is a dump of "Music Machine", a  4Kb  ULTIMAX
    mode cartridge. It  is  still  identified  as  a  "standard  cartridge"
    according to the ID.

    Normal cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 4Kb (ULTIMAX mode)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $F000-F7FF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 00 01 00 00 00 00 00 00 00   ???@@????????????
0020: 4D 55 53 49 43 20 4D 41 43 48 49 4E 45 00 00 00   MUSIC?MACHINE???
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 10 10 00 00 00 00 F0 00 10 00   CHIP????????????
0050: 3C 66 C3 C3 66 3C FF FF 18 3C 66 7E 66 66 66 00   <f..f<???<f~fff?
@end example


      The third sample is a dump of "Adventure Creator",  a  16Kb  standard
    cartridge.

    Normal cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 00 00 00 00 00 00 00 00 00   ???@@????????????
0020: 41 64 76 65 6E 74 75 72 65 20 43 72 65 61 74 6F   Adventure?Creato
0030: 72 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   r???????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00   CHIP??@?????.?@@?
0050: 09 80 81 EA C3 C2 CD 38 30 A2 00 78 D8 8E 11 D0   ?.�....80.?x.Ž?.
@end example


@c @node FIXME
@subsubsection 1 - Action Replay

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb (4 banks of 8Kb each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF (all modules)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 01 00 00 00 00 00 00 00 00   ???@@????????????
0020: 41 63 74 69 6F 6E 20 52 65 70 6C 61 79 20 56 00   Action?Replay?V?
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 09 80 0C 80 C3 C2 CD 38 30 4C 60 80 4C 63 80 4C   ?.?....80L`.Lc.L
@end example

    This cart has 32Kb of ROM, and 8Kb of RAM. The bank switching  is  done
    by writing to the I/O-1 range as follows:

@example
    bit  meaning
    ---  -------
    7    extra ROM bank selector (A15) (unused)
    6    1 = resets FREEZE-mode (turns back to normal mode)
    5    1 = enable RAM at ROML ($8000-$9FFF) &
             I/O-2 ($DF00-$DFFF = $9F00-$9FFF)
    4    ROM bank selector high (A14)
    3    ROM bank selector low  (A13)
    2    1 = disable cartridge (turn off $DE00)
    1    1 = /EXROM high
    0    1 = /GAME low
@end example

    Additionally the RAM or ROM can be available through a  window  in  the
    I/O-2 range.


@c @node FIXME
@subsubsection 2 - KCS Power Cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8K each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab module #1 - $8000-9FFF
                   module #2 - $A000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 20 01 00 00 02 00 00 00 00 00 00 00 00   ????????????????
0020: 4B 43 53 20 50 6F 77 65 72 20 43 61 72 74 72 69   KCS?Power?Cartri
0030: 64 67 65 00 00 00 00 00 00 00 00 00 00 00 00 00   dge?????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 09 80 5E FE C3 C2 CD 38 30 78 D8 A2 FF 9A A9 27   ?.^....80x..?..'
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00   CHIP???????? ???
2060: 97 E3 16 A1 FF FF FF 20 13 A0 A5 01 09 01 85 01   —.?.????? Ą???…?
@end example


@c @node FIXME
@subsubsection 3 - Final Cartridge III

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-BFFF (all modules)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 03 01 01 00 00 00 00 00 00   ???@@????????????
0020: 46 69 6E 61 6C 20 43 61 72 74 72 69 64 67 65 20   Final?Cartridge?
0030: 49 49 49 20 31 39 38 37 00 00 00 00 00 00 00 00   III?1987????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00   CHIP??@@?????.?@@?
0050: 09 80 5E FE C3 C2 CD 38 30 4C 4C 80 4C 55 95 4C   ?.^....80LL.LU•L
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00   CHIP??@@?????.?@@?
4060: 01 02 00 81 5D 81 61 81 99 81 D8 81 0B 82 33 82   ???�]�a�™�.�?‚3‚
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00   CHIP??@@?????.?@@?
8070: 20 43 80 20 52 80 A9 4E 20 05 DE 20 FD BF AD 39   ?C.?R..N??.?..­9
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00   CHIP??@@?????.?@@?
C080: A2 06 BD DD 85 95 05 CA 10 F8 AE A0 02 E8 EC A2   .??.…•?.??® ???.
@end example

    A total of 64 kB of ROM memory  is  organized  into  four  $4000  banks
    located at $8000-$BFFF.

    The banks are arranged in the following way:

@example
    Bank 0:  BASIC, Monitor, Disk-Turbo
    Bank 1:  Notepad, BASIC (Menu Bar)
    Bank 2:  Desktop, Freezer/Print
    Bank 3:  Freezer, Compression
@end example

    The cartridges uses the entire I/O-1 and I/O-2 range. Bank switching is
    done by writing the bank number plus $40 into  memory  location  $DFFF.
    For instance, to select bank 2, $DFFF is set to $42.

    The CRT file contains four CHIP blocks, each block with a start address
    of $8000, length $4000 and the bank number in the bank  field.  In  the
    cartridge header, both EXROM ($18) and GAME  ($19)  are  set  to  1  to
    enable the 16 kB ROM configuration.

    The registers are arranged in the following way:

    One register at $DFFF:

@example
    bit  meaning
    ---  -------
    7      Hide this register (1 = hidden)
    6      NMI line  (0 = low = active) *1)
    5      GAME line  (0 = low = active) *2)
    4      EXROM line (0 = low = active)
    2-3    unassigned (usually set to 0)
    0-1    number of bank to show at $8000
@end example

    1) if either the freezer button is pressed, or bit 6 is 0, then an  NMI
       is generated

    2) if the freezer button is pressed, GAME is also forced low

    The rest of I/O-1/I/O-2 contain a mirror of the last  2  pages  of  the
    currently selected ROM bank (also at $dfff, contrary to what some other
    documents say)


@c @node FIXME
@subsubsection 4 - Simons' Basic

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8kb each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab module #1 - $8000-9FFF
                   module #2 - $A000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 04 00 01 00 00 00 00 00 00   ???@@????????????
0020: 53 69 6D 6F 6E 27 73 20 42 61 73 69 63 00 00 00   Simon's?Basic???
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 52 81 52 81 C3 C2 CD 38 30 41 4C 52 81 20 2C 81   R�R�...80ALR�?,�
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00   CHIP???????? ???
2060: 20 A4 A6 99 9E CB A0 05 A5 A8 91 20 A4 A6 99 A2   ???™ž. ?Ą?.???™.
@end example

    Simons' BASIC permanently uses 16 kB ($4000) bytes of cartridge  memory
    from $8000-$BFFF. However, through some custom bank-switching logic the
    upper area ($A000-$BFFF) may be disabled so Simons' BASIC may use it as
    additional RAM. Writing a value of $01 to address location $DE00  banks
    in ROM, $00 disables ROM and enables RAM.

    The CRT file contains two CHIP blocks of length $2000 each,  the  first
    block having a start address of $8000, the second block $A000.  In  the
    cartridge header, EXROM ($18) is set to 0, GAME ($19) is set  to  1  to
    indicate the RESET/power-up configuration of 8 kB ROM.


@c @node FIXME
@subsubsection 5 - Ocean type 1

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb, 128Kb, 256Kb or 512Kb sizes (4, 16, 32 or 64 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab Banks 00-15 - $8000-9FFF
                   Banks 16-31 - $A000-BFFF  (except Terminator 2)
@end multitable

@example
       00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
       -----------------------------------------------   ----------------
00000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
00010: 00 00 00 40 01 00 00 05 00 00 00 00 00 00 00 00   ???@@????????????
00020: 53 48 41 44 4F 57 20 4F 46 20 54 48 45 20 42 45   SHADOW?OF?THE?BE
00030: 41 53 54 00 00 00 00 00 00 00 00 00 00 00 00 00   AST?????????????
00040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
00050: 09 80 83 81 C3 C2 CD 38 30 4C 83 81 4C 76 82 80   ?.��...80L��Lv‚.
 @dots{}
02050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00   CHIP????????.???
02060: 59 6D 00 56 AD 00 55 AE F0 00 01 A0 FE 00 01 F8   Ym?V­?U®??? .???
 @dots{}
20140: 43 48 49 50 00 00 20 10 00 00 00 10 A0 00 20 00   CHIP???????? ???
20150: 0A 9A 55 FF 9B 69 57 FE AA 65 96 FE 65 0F D6 D9   ?.U?›iW.×e–.e?..
@end example

    Here is a list of the known OCEAN cartridges:

@example
    Batman The Movie    (128 kB)
    Battle Command      (128 kB)
    Double Dragon       (128 kB)
    Navy Seals          (128 kB)
    Pang                (128 kB)
    Robocop 3           (128 kB)
    Space Gun           (128 kB)
    Toki                (128 kB)
    Chase H.Q. II       (256 kB)
    Robocop 2           (256 kB)
    Shadow of the Beast (256 kB)
    Terminator 2        (512 kB)
@end example

    The 32Kb type of cart  has  4  banks  of  8Kb  ($2000),  banked  in  at
    $8000-$9FFF.

    The 128Kb type of cart has  16  banks of  8Kb  ($2000),  banked  in  at
    $8000-$9FFF.

    The 256Kb type of cart has 32 banks of 8Kb ($2000),  16  banked  in  at
    $8000-$9FFF, and 16 banked in at $A000-$BFFF.

    The 512Kb type of cart has 64  banks  of  8Kb  ($2000),  banked  in  at
    $8000-$9FFF.

    Bank switching is done by writing to $DE00. The lower six bits give the
    bank number (ranging from 0-63). Bit 7 in this selection word is always
    set.


@c @node FIXME
@subsubsection 6 - Expert Cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 06 01 01 00 00 00 00 00 00   ???@@????????????
0020: 45 78 70 65 72 74 20 43 61 72 74 72 69 64 67 65   Expert?Cartridge
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 40 10 00 02 00 00 80 00 20 00   CHIP??@@?????.???
0050: 00 00 00 0A F3 00 00 00 00 00 00 00 00 00 00 00   ????????????????
@end example


@c @node FIXME
@subsubsection 7 - Fun Play, Power Play

@multitable @columnfractions .3 .7
@item Size
@tab 128Kb (16 banks of 8Kb modules)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF (all modules)
@end multitable

@example
       00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
       -----------------------------------------------   ----------------
00000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
00010: 00 00 00 40 01 00 00 07 00 00 00 00 00 00 00 00   ???@@????????????
00020: 46 55 4E 20 50 4C 41 59 00 00 00 00 00 00 00 00   FUN?PLAY????????
00030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
00040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
00050: 1E 80 86 EA C3 C2 CD 38 30 1B 00 81 0D 08 80 00   ?.†....80??�??.?
 @dots{}
02050: 43 48 49 50 00 00 20 10 00 00 00 08 80 00 20 00   CHIP????????.???
02060: 78 A2 F0 86 01 BD 1D 08 9D F8 00 CA D0 F7 4C 00   x.?†????ť??..?L?
 @dots{}
04060: 43 48 49 50 00 00 20 10 00 00 00 10 80 00 20 00   CHIP????????.???
04070: 38 E5 68 85 03 B0 11 27 03 12 C0 18 69 27 42 90   8?h…?°?'??.?i'B�
 @dots{}
06070: 43 48 49 50 00 00 20 10 00 00 00 18 80 00 20 00   CHIP????????.???
06080: 44 D0 5E 06 02 C0 44 11 40 04 11 44 01 5F 1C 73   D.^??.D?@@??D?_?s
 @dots{}
1E130: 43 48 49 50 00 00 20 10 00 00 00 39 80 00 20 00   CHIP???????9.???
1E140: 85 EB 41 EA 9E 08 03 00 C0 06 18 01 00 C0 08 03   …?A.ž???.????.??
@end example

    The FUN PLAY Cartridge uses $DE00 for  bank  selection,  and  uses  8Kb
    banks ($2000) at $8000-$9FFF. There are 16 banks of ROM memory and  are
    referenced by the following values:

@example
    $00 -> Bank 0
    $08 -> Bank 1
    $10 -> Bank 2
    $18 -> Bank 3
    $20 -> Bank 4
    $28 -> Bank 5
    $30 -> Bank 6
    $38 -> Bank 7
    $01 -> Bank 8
    $09 -> Bank 9
    $11 -> Bank 10
    $19 -> Bank 11
    $21 -> Bank 12
    $29 -> Bank 13
    $31 -> Bank 14
    $39 -> Bank 15
@end example

    The bank field in the chip  headers  is  set  according  to  the  value
    written to $DE00. The following bits are  used  for  bank  decoding  in
    $DE00 (0 being the LSB, 3 being the MSB).

@example
        Bit# 76543210
             xx210xx3
@end example

    After copying memory from the ROM banks, the selection  program  writes
    a value of $86 to $DE00. This seems either  to  reset  or  disable  the
    cartridge ROM.


@c @node FIXME
@subsubsection 8 - Super Games

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Startup mode
@tab 16k game
@item Load address
@tab $8000-BFFF (all modules)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 08 00 00 00 00 00 00 00 00   ???@@????????????
0020: 53 55 50 45 52 20 47 41 4D 45 53 00 00 00 00 00   SUPER?GAMES?????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00   CHIP??@@?????.?@@?
0050: 0A 80 0A 80 C3 C2 CD 38 30 00 A9 80 A0 00 85 FB   ?.?....80?.. ?….
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00   CHIP??@@?????.?@@?
4060: 27 80 A8 80 C3 C2 CD 38 30 00 40 C0 40 C0 40 C0   '.?....80?@@.@@.@@.
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00   CHIP??@@?????.?@@?
8070: 00 00 00 49 4D C7 64 47 46 45 F3 48 DC 08 7E 0B   ???IM.dGFE?H.?~?
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00   CHIP??@@?????.?@@?
C080: D5 F9 F0 C1 D5 F7 F0 BD E8 B5 02 F0 FB C9 05 30   .??..????µ??..?0
@end example

    The Super Games cartridge  uses  4  16Kb  banks  ($8000-$BFFF)  of  ROM
    memory. Bank selecting is done by writing to $DF00.

    $DF00 register is as follows:

@example
    bit   meaning
    ---   -------
     0    bank bit 0
     1    bank bit 1
     2    mode (0 = EXROM/GAME (bridged on the same wire - 16k config) 1 = cartridge disabled)
     3    write-protect-latch  (1 = no more changes are possible until the next hardware-reset )
    4-7   unused
@end example

@c @node FIXME
@subsubsection 9 - Atomic Power

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb (4 banks of 8Kb modules)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF (all modules)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 09 00 00 00 00 00 00 00 00   ???@@????????????
0020: 41 74 6F 6D 69 63 20 50 6F 77 65 72 00 00 00 00   Atomic?Power????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 09 80 0C 80 C3 C2 CD 38 30 4C 41 80 4C 1E 80 4C   ?.?....80LA.L?.L
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00   CHIP????????.???
2060: 09 80 0C 80 C3 C2 CD 38 30 4C 3F 80 4C 91 80 4C   ?.?....80L?.L..L
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00   CHIP????????.???
4070: EF FC 09 80 C3 C2 CD 38 30 4C 27 80 4C DB 81 4C   ?.?....80L'.L.�L
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00   CHIP????????.???
6080: 09 80 0C 80 C3 C2 CD 38 30 4C 73 86 4C 30 80 4C   ?.?....80Ls†L0.L
@end example

    This cart has 32Kb of ROM and 8Kb of RAM

    Writing to I/O-1 will do the following:

@example
    bit  meaning
    ---  -------
    7    extra ROM bank selector (A15) (unused)
    6    1 = resets FREEZE-mode (turns back to normal mode)
    5    1 = enable RAM at ROML ($8000-$9FFF) &
             I/O-2 ($DF00-$DFFF = $9F00-$9FFF)
    4    ROM bank selector high (A14)
    3    ROM bank selector low  (A13)
    2    1 = disable cartridge (turn off $DE00)
    1    1 = /EXROM high
    0    1 = /GAME low
@end example

    If bit 5 (RAM enable) is 1, bit 0,1 (exrom/game) is ==  2  (cart  off),
    bit 2,6,7 (cart disable, freeze clear) are 0, then cart ROM (Bank 0..3)
    is mapped at 8000-9FFF, and cart RAM (Bank 0) is  mapped  at  A000-BFFF
    and cart RAM (Bank 0) is is enabled in the I/O-2 area using  16Kb  game
    config.

    The cart RAM or ROM is available through a window in the I/O-2 range.


@c @node FIXME
@subsubsection 10 - Epyx Fastload

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 0A 01 01 00 00 00 00 00 00   ???@@????????????
0020: 45 50 59 58 20 46 41 53 54 4C 4F 41 44 00 00 00   EPYX?FASTLOAD???
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 30 80 5E FE C3 C2 CD 38 30 20 04 90 4C 38 DF AB   0.^....80??�L8?«
@end example

    The Epyx FastLoad cart uses a simple capacitor to toggle the ROM on
    and off:

    the capacitor is discharged, and 8k game config enabled, by either
    reading ROML or reading I/O-1. If none of those accesses happen the
    capacitor will charge, and if it is charged (after 512 cycles) then
    the ROM will get disabled.

@c @node FIXME
@subsubsection 11 - Westermann Learning

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 0B 00 00 00 00 00 00 00 00   ???@@????????????
0020: 57 45 53 54 45 52 4D 41 4E 4E 00 00 00 00 00 00   WESTERMANN??????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 40 00   CHIP????????.?@@?
0050: 09 80 9C 80 C3 C2 CD 38 30 A2 00 8E 16 D0 20 84   ?.ś....80.?Ž?.?„
@end example

    Any read from the I/O-2 range will switch the cart off.


@c @node FIXME
@subsubsection 12 - Rex Utility

@multitable @columnfractions .3 .7
@item Size
@tab 8K
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 0C 00 01 00 00 00 00 00 00   ???@@????????????
0020: 52 45 58 00 00 00 00 00 00 00 00 00 00 00 00 00   REX?????????????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 08 80 C1 FE C3 C2 CD 38 30 6C 95 E3 20 A3 FD 20   ?......80l•.?Ł.?
@end example

    Reading from $DF00-DFBF disables ROM, reading from $DFC0-DFFF enables
    ROM (8k game config).


@c @node FIXME
@subsubsection 13 - Final Cartridge I

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 0D 01 01 00 00 00 00 00 00   ???@@????????????
0020: 54 68 65 20 46 69 6E 61 6C 20 43 61 72 74 72 69   The?Final?Cartri
0030: 64 67 65 20 49 00 00 00 00 00 00 00 00 00 00 00   dge?I???????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00   CHIP??@@?????.?@@?
0050: 80 BA 5E FE C3 C2 CD 38 30 00 A0 A0 20 2D FE 58   .÷^....80?  ?-.X
@end example

    Any access to I/O-1 turns cartridge ROM off. Any access to I/O-2  turns
    cartridge ROM on.

    The cart ROM is visible in I/O-1 and I/O-2.

@c @node FIXME
@subsubsection 14 - Magic Formel

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (8 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load Address
@tab $E000-FFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 0E 01 01 00 00 00 00 00 00  ???@@????????????
0020: 4D 61 67 69 63 20 46 6F 72 6D 65 6C 00 00 00 00  Magic?Formel????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00  CHIP????????????
0050: 4D 46 30 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF0Ť??`Ť??`Ť??`Ť
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 E0 00 20 00  CHIP????????????
2060: 4C 5F E4 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  L_?Ť??`Ť??`Ť??`Ť
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 E0 00 20 00  CHIP????????????
4070: 4D 46 32 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF2Ť??`Ť??`Ť??`Ť
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 E0 00 20 00  CHIP????????????
6080: 4D 46 33 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF3Ť??`Ť??`Ť??`Ť
@dots{}
8080: 43 48 49 50 00 00 20 10 00 00 00 04 E0 00 20 00  CHIP????????????
8090: 4D 46 34 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF4Ť??`Ť??`Ť??`Ť
@dots{}
A090: 43 48 49 50 00 00 20 10 00 00 00 05 E0 00 20 00  CHIP????????????
A0A0: 4D 46 35 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF5Ť??`Ť??`Ť??`Ť
@dots{}
C0A0: 43 48 49 50 00 00 20 10 00 00 00 06 E0 00 20 00  CHIP????????????
C0B0: 4D 46 36 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF6Ť??`Ť??`Ť??`Ť
..
E0B0: 43 48 49 50 00 00 20 10 00 00 00 07 E0 00 20 00  CHIP????????????
E0C0: 4D 46 37 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF7Ť??`Ť??`Ť??`Ť
@end example


@c @node FIXME
@subsubsection 15 - C64 Game System, System 3

@multitable @columnfractions .3 .7
@item Size
@tab 512Kb (64 banks of 8Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF (all modules)
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
000000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
000010: 00 00 00 40 01 00 00 0F 00 01 00 00 00 00 00 00  ???@@????????????
000020: 43 36 34 47 53 20 43 61 72 74 72 69 64 67 65 00  C64GS?Cartridge?
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
000040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
000050: 6D 80 C5 80 C3 C2 CD 38 30 4C CB 80 4C 36 84 4C  m......80L..L6„L
@dots{}
002050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
002060: 18 D0 A9 FF 8D 15 D0 8D 1D D0 8D 17 D0 A2 07 A9  ?..?Ť?.Ť?.Ť?..?.
@dots{}
004060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP????????.???
004070: E0 08 19 21 77 84 52 98 9F 80 A5 21 31 01 31 89  ???!w„R�ź.Ą!1?1‰
@dots{}
006070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP????????.???
006080: C0 08 1C 1D A0 92 03 03 D8 AA 04 C0 B8 01 40 EA  .??? .??.×?.??@@.
@dots{}
07E430: 43 48 49 50 00 00 20 10 00 00 00 3F 80 00 20 00  CHIP????????.???
07E440: 45 20 41 20 42 49 47 20 58 FE 4F 4E 20 54 48 49  E?A?BIG?X.ON?THI
@end example

    Here is a list of the known cartridges:

@example
    C64GS 4-in-1      (Commodore)  (512 kB)
    Last Ninja Remix  (System 3)   (512 kB)
    Myth              (System 3)   (512 kB)
@end example

    ROM memory is organized in 8Kb ($2000) banks  located  at  $8000-$9FFF.
    Bank switching is done by writing to address $DE00+X, where  X  is  the
    bank number (STA $DE00,X). For instance, to read from bank  3,  address
    $DE03 is written to. Reading from anywhere  in  the  I/O-1  range  will
    disable the cart.

    The CRT file contains a string of CHIP blocks, each block with a  start
    address of $8000, length $2000 and the bank number in the  bank  field.
    In the cartridge header, EXROM ($18) is set to 0, GAME ($19) is set  to
    1 to enable the 8 kB ROM configuration.


@c @node FIXME
@subsubsection 16 - Warp Speed

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 10 01 01 00 00 00 00 00 00  ???@@????????????
0020: 57 61 72 70 73 70 65 65 64 00 00 00 00 00 00 00  Warpspeed???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 4C 22 80 4C 22 80 FF 43 42 4D 20 53 E4 20 18 E5  L".L".?CBM?S????
@end example

    After  RESET  or  POWER  ON,  16kB  of  cartridge  ROM  is  visible  at
    $8000-$BFFF. Additionally,  ROM  normally  located  at  $9E00-$9FFF  is
    mirrored into I/O-1 and I/O-2 at $DE00-$DFFF.  ROM  at  $8000-$BFFF  is
    disabled by writing into the I/O-2 area (typically $DF00)  and  may  be
    re-enabled by writing into  I/O-1  ($DE00).  However,  the  $DE00-$DFFF
    (I/O-1/I/O-2) area itself always remains mapped to cartridge ROM.


@c @node FIXME
@subsubsection 17 - Dinamic

@multitable @columnfractions .3 .7
@item Size
@tab 128Kb (16 banks of 8Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF (all modules)
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
000000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
000010: 00 00 00 40 01 00 00 11 00 01 00 00 00 00 00 00  ???@@????????????
000020: 4E 61 72 63 6F 20 50 6F 6C 69 63 65 00 00 00 00  Narco?Police????
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
000040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
000050: 0B 80 0B 80 C3 C2 CD 38 30 00 00 78 A2 FF 9A D8  ?.?....80??x.?..
..
002050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
002060: 1C 8C 1B 8C 16 16 8F 16 16 88 1C 1C 86 1C 1C 89  ?Ś?Ś??Ź??�??†??‰
..
004060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP????????.???
004070: B6 02 07 08 07 07 00 0A 0A B6 00 05 0A 00 07 07  ¶????????¶??????
..
01E130: 43 48 49 50 00 00 20 10 00 00 00 0F 80 00 20 00  CHIP????????.???
01E140: 00 D5 70 03 F5 70 0F 5F 70 0F F7 70 35 FD F0 37  ?.p??p?_p??p5.?7
@end example

    Here is a list of the known DINAMIC cartridges:

@example
    Narco Police  (128 kB)
    Satan         (128 kB)
@end example

    ROM memory is organized in 8Kb ($2000) banks  located  at  $8000-$9FFF.
    Bank switching is done by reading from address $DE00+X, where X is  the
    bank number (LDA $DE00,X). For instance, to read from bank  3,  address
    $DE03 is accessed.

    The CRT file contains a string of CHIP blocks, each block with a  start
    address of $8000, length $2000 and the bank number in the  bank  field.
    In the cartridge header, EXROM ($18) is set to 0, GAME ($19) is set  to
    1 to enable the 8 kB ROM configuration.


@c @node FIXME
@subsubsection 18 - Zaxxon, Super Zaxxon (SEGA)

@multitable @columnfractions .3 .7
@item Size
@tab 20Kb (3 banks of different sizes)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-8FFF (mirrored in $9000-9FFF, module 0, chip U1)
                    $A000-BFFF (banked modules 1 and 2, chip U2)
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
000000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
000010: 00 00 00 40 01 00 00 12 00 00 00 00 00 00 00 00  ???@@????????????
000020: 5A 61 78 78 6F 6E 00 00 00 00 00 00 00 00 00 00  Zaxxon??????????
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
000040: 43 48 49 50 00 00 10 10 00 00 00 00 80 00 10 00  CHIP????????.???
000050: 0D 80 29 80 C3 C2 CD 38 30 78 4C 09 80 78 A9 00  ?.)....80xL?.x.?
..
001050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP???????? ???
001060: A2 0F BD 00 20 D0 04 CA 10 F8 60 BD 70 20 F0 0D  .????.?.??`?p???
..
003060: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00  CHIP???????? ???
003070: 65 A2 36 A3 E7 A3 CB A4 94 A5 86 A6 5E A7 35 A8  e.6Ł?Ł.?”Ą†?^§5?
@end example

    The (Super) Zaxxon carts use a 4Kb ($1000) ROM at $8000-$8FFF (mirrored
    in $9000-$9FFF) along with two 8Kb ($2000) cartridge banks  located  at
    $A000-$BFFF. One of the two banks is selected by doing a read access to
    either the $8000-$8FFF area (bank 0 is selected) or to $9000-$9FFF area
    (bank 1 is selected). EXROM ($18 = $00) and GAME ($19 = $00) lines  are
    always pulled to GND to select the 16 kB ROM configuration.

    The CRT file includes three CHIP blocks:
@example
    a) bank = 0, load address = $8000, size = $1000
    b) bank = 0, load address = $A000, size = $2000
    c) bank = 1, load address = $A000, size = $2000
@end example

@c @node FIXME
@subsubsection 19 - Magic Desk, Domark, HES Australia

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb, 64Kb or 128Kb sizes (4 to 16 banks of 8Kb each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8k Game
@item Load address
@tab (banks 00-15) - $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 13 00 01 00 00 00 00 00 00  ???@@????????????
0020: 4D 61 67 69 63 20 44 65 73 6B 00 00 00 00 00 00  Magic?Desk??????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 C6 CA C3 C2 CD 38 30 8E 16 D0 20 A3 FD 20  ?......80Ž?.?Ł.?
..
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 00 3F 0A 01 00 86 4E 24 28 31 30 29 3A 4A 4F 59  ?????†N$(10):JOY
..
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP????????.???
4070: 00 8B C9 28 4E 24 2C 31 29 B3 B1 22 FF 22 A7 32  ?‹.(N$,1)ł±"?"§2
..
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP????????.???
6080: AE 01 83 33 2C 37 2C 22 32 29 20 44 45 4C 20 4B  ®?�3,7,"2)?DEL?K
@end example

    This cartridge type is very similar to the OCEAN cart type: ROM  memory
    is  organized  in  8Kb  ($2000)  banks  located  at  $8000-$9FFF.  Bank
    switching is done by writing the bank number to $DE00. Deviant from the
    Ocean type, bit 7 is cleared for selecting one of the ROM banks. If bit
    7 is set ($DE00 = $80), the GAME/EXROM lines are disabled,  turning  on
    RAM at $8000-$9FFF instead of ROM.

    In the cartridge header, EXROM ($18) is set to 0, GAME ($19) is set  to
    1 to indicate the RESET/power-up configuration of 8 kB ROM.

    Here is a list of the known cartridges:

@example
    Ghosbusters        (HES Australia)   (32 kB)
    Magic Desk         (Commodore)       (32 kB)
    Badlands           (Domark)          (64 kB)
    Vindicators        (Domark)          (64 kB)
    Wonderboy          (HES Australia)   (64 kB)
    Cyberball          (Domark)         (128 kB)
@end example


@c @node FIXME
@subsubsection 20 - Super Snapshot V5

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 14 01 01 00 00 00 00 00 00  ???@@????????????
0020: 53 75 70 65 72 20 53 6E 61 70 73 68 6F 74 20 35  Super?Snapshot?5
0030: 20 4E 54 53 43 00 00 00 00 00 00 00 00 00 00 00  ?NTSC???????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 09 80 59 80 C3 C2 CD 38 30 20 03 9F 00 FA F4 20  ?.Y....80??ź????
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00  CHIP??@@?????.?@@?
4060: 79 DE BC FE C3 C2 CD 38 30 A9 05 8D 20 D0 8D 21  y.?....80.?Ť?.Ť!
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00  CHIP??@@?????.?@@?
8070: 50 DE BC FE C3 C2 CD 38 30 A9 0A 85 6A A9 0D 85  P.?....80.?…j.?…
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00  CHIP??@@?????.?@@?
C080: 50 DE BC FE C3 C2 CD 38 30 85 07 20 1A AD A5 76  P.?....80…???­Ąv
@end example

    The first page of the currently selected ROM bank is  mirrored  in  the
    I/O-1 range when reading.

    The control Register is the I/O-1 range when writing:

@example
    bit  meaning
    ---  -------
    7-5  unused
    4    ROM/RAM bank bit 1
    3    ROM enable
    2    ROM/RAM bank bit 0
    1    RAM enable, EXROM
    0    release freeze, !GAME
@end example


@c @node FIXME
@subsubsection 21 - Comal-80

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 15 01 01 00 00 00 00 00 00  ???@@????????????
0020: 43 6F 6D 61 6C 20 38 30 00 00 00 00 00 00 00 00  Comal?80????????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 87 87 70 CF C3 C2 CD 38 30 4C AA CF 4C 70 CF 4C  ..p....80L×.Lp.L
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00  CHIP??@@?????.?@@?
4060: AA CF 70 CF C3 C2 CD 38 30 01 29 01 28 01 2C 04  ×.p....80?)?(?,?
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00  CHIP??@@?????.?@@?
8070: AA CF 70 CF C3 C2 CD 38 30 91 92 92 92 92 92 92  ×.p....80.......
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00  CHIP??@@?????.?@@?
C080: 7B C8 7E C8 C3 C2 CD 38 30 43 4F 4D 41 4C 80 93  ..~....80COMAL..
@end example


    The Comal-80 Cartridge uses $DE00 for bank  selection,  and  uses  16Kb
    banks ($4000) at $8000-$BFFF. There are 4 banks of ROM memory  and  are
    referenced by the following values:

@example
       $80 -> Bank 0
       $81 -> Bank 1
       $82 -> Bank 2
       $83 -> Bank 3
@end example


@c @node FIXME
@subsubsection 22 - Structured Basic

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (0)
@item Load address
@tab $8000-9FFF
@end multitable

    No sample data/file available.

    Any read/write access to $DE00 or $DE01 will  switch  in  bank  0.  Any
    read/write access to $DE02 will switch in bank 1. Any read/write access
    to $DE03 will switch off EXROM.


@c @node FIXME
@subsubsection 23 - Ross

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb or 32Kb sizes (1 or 2 banks of 16Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 17 00 00 00 00 00 00 00 00  ???@@????????????
0020: 52 6F 73 73 20 31 34 00 00 00 00 00 00 00 00 00  Ross?14?????????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 09 80 09 80 C3 C2 CD 38 30 A2 00 BD 20 80 4D 0E  ?.?....80.???.M?
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00  CHIP??@@?????.?@@?
4060: 3F 5A 4D 4D 50 4D 8D 25 3F 1A 1F 77 3F CD E0 3F  ?ZMMPMŤ%???w?.??
@end example

    Any read access to $DE00 will switch in bank 1 (if cart is  32Kb).  Any
    read access to $DF00 will switch off EXROM and GAME.


@c @node FIXME
@subsubsection 24 - Dela EP64

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb to 72kb sizes (1 to 9 banks of 8Kb each,
                              or 1 bank of 8Kb and 1 or 2 banks
                              of 32Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 18 00 01 00 00 00 00 00 00  ???@@????????????
0020: 44 45 4C 41 20 45 50 36 34 00 00 00 00 00 00 00  DELA?EP64???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 00 85 5E FE C3 C2 CD 38 30 FF FF FF FF FF FF FF  ?…^....80???????
@dots{}
2050: 43 48 49 50 00 00 80 10 00 00 00 01 80 00 80 00  CHIP??.?????.?.?
2060: 54 45 53 54 0D 2A 0D 54 45 20 36 34 0D 00 00 00  TEST?*?TE?64????
@end example

    This is an eprom cartridge. It has 1 2764 (8Kb) which  holds  the  base
    eprom with the base menu, and 2 27256 eproms of  which  8Kb  parts  are
    banked into the $8000-9FFF area.

    The bank selecting is done by writing to $DE00. The following bits  are
    used for bank decoding in $DE00 (0 being the LSB, 3 being the MSB).

@example
         Bit# 76543210
              xx10xx32
@end example

    Any bank value below 4 or above 11 switches in the base bank (bank 0).

    The bit values for each eprom bank are :

@example
    eprom bank 1 : xx00xx01
    eprom bank 2 : xx01xx01
    eprom bank 3 : xx10xx01
    eprom bank 4 : xx11xx01
    eprom bank 5 : xx00xx10
    eprom bank 6 : xx01xx10
    eprom bank 7 : xx10xx10
    eprom bank 8 : xx11xx10
@end example

    Setting bit 7 high will switch off EXROM.


@c @node FIXME
@subsubsection 25 - Dela EP7x8

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb to 64kb sizes (1 to 8 banks of 8Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 19 00 01 00 00 00 00 00 00  ???@@????????????
0020: 44 45 4C 41 20 45 50 37 78 38 00 00 00 00 00 00  DELA?EP7x8??????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 5E FE C3 C2 CD 38 30 78 A2 FF 9A D8 8E 16  ?.^....80x.?..Ž?
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 94 83 A0 83 C3 C2 CD 38 30 02 BB 5A 30 5F EE 3D  ”� �...80?»Z0_?=
@end example

    This is an eprom cartridge. It has 8 8Kb banks of which the first holds
    the base menu, the other eproms can be banked into the $8000-9FFF area.

    The bank selecting is done by writing to $DE00. Each low bit is used to
    bank in the respective eprom. If all bits are high then  the  EXROM  is
    switched off.

    The bit values for each eprom bank is:

@example
    eprom bank 1 : 11111110 ($FE) (base eprom)
    eprom bank 2 : 11111101 ($FD)
    eprom bank 3 : 11111011 ($FB)
    eprom bank 4 : 11110111 ($F7)
    eprom bank 5 : 11101111 ($EF)
    eprom bank 6 : 11011111 ($DF)
    eprom bank 7 : 10111111 ($BF)
    eprom bank 8 : 01111111 ($7F)

    EXROM off    : 11111111 ($FF)
@end example

@c @node FIXME
@subsubsection 26 - Dela EP256

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb to 262kb sizes (1 to 33 banks of 8Kb each)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 1A 00 01 00 00 00 00 00 00  ???@@????????????
0020: 44 45 4C 41 20 45 50 32 35 36 00 00 00 00 00 00  DELA?EP256??????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 00 85 5E FE C3 C2 CD 38 30 93 0D 2B 2B 2B 20 45  ?…^....80.?+++?E
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 09 80 28 80 C3 C2 CD 38 30 78 A2 05 8E 16 D0 20  ?.(....80x.?Ž?.?
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP????????.???
4070: 0B 80 BC FE C3 C2 CD 38 30 DC 10 8E 16 D0 20 87  ?.?....80.?Ž?.?.
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP????????.???
6080: 09 80 F6 8E C3 C2 CD 38 30 A2 C8 8E 16 D0 20 ..  ?.?Ž...80..Ž?.?.
@dots{}
8080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00  CHIP????????.???
8090: 94 83 A0 83 C3 C2 CD 38 30 02 BB 5A 30 5F EE 3D  ”� �...80?»Z0_?=
@end example

    This is an eprom cartridge. It has 33 8Kb  banks  of  which  the  first
    holds the base menu, the other eproms can be banked into the $8000-9FFF
    area.

    The bank selecting is done by writing to $DE00.

    The values for the (extra) eprom banks are:

@example
    eprom banks  1- 8 : $38-3F
    eprom banks  9-16 : $28-2F
    eprom banks 17-24 : $18-1F
    eprom banks 25-32 : $08-0F
@end example

    Setting bit 7 high will switch off EXROM.


@c @node FIXME
@subsubsection 27 - Rex EP256

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb to 262kb sizes (1 bank of 8Kb and 1 to 8 banks of either
                               8Kb, 16Kb or 32Kb)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 1B 00 01 00 00 00 00 00 00  ???@@????????????
0020: 52 45 58 20 45 50 32 35 36 00 00 00 00 00 00 00  REX?EP256???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 C1 FE C3 C2 CD 38 30 20 A3 FD 20 50 FD 20  ?......80?Ł.?P.?
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 09 80 F2 8F C3 C2 CD 38 30 A2 C8 8E 16 D0 20 A3  ?.?Ź...80..Ž?.?Ł
@dots{}
4060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00  CHIP??@@?????.?@@?
4070: 09 80 09 80 C3 C2 CD 38 30 58 D8 20 84 FF 20 8A  ?.?....80X.?„??Š
@end example

    This is an eprom cartridge. It has 9 eprom sockets, of which the  first
    holds the base eprom with the base menu which  is  an  8Kb  eprom,  the
    other eprom sockets can handle 8Kb, 16Kb or 32Kb eproms, of  which  8kb
    can be banked into the $8000-9FFF area.

    The bank selecting is done by  writing  to  $DFA0.  Bits  2,  1  and  0
    determine which socket is used and bits 5 and 4 are used to  select  an
    8Kb piece of the eprom.

    The possible values for bits 5 and 4 for the (extra) eprom banks are:

@example
     8Kb        : 3, 2, 1, 0

    16Kb bank 0 : 2, 0
    16Kb bank 1 : 3, 1

    32Kb bank 0 : 0
    32Kb bank 1 : 1
    32Kb bank 2 : 2
    32Kb bank 3 : 3
@end example

    Reading from $DFC0 switches off the EXROM.
    Reading from $DFE0 switches on the EXROM.

@c @node FIXME
@subsubsection 28 - Mikro Assembler

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 1C 00 01 00 00 00 00 00 00  ???@@????????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 60 80 FE 80 C3 C2 CD 38 30 4C 07 87 4C CA 82 41  `......80L?.L.‚A
@end example


    The $9E00-$9EFF range is mirrored at $DE00-$DEFF. The $9F00-$9FFF range
    is mirrored at $DF00-$DFFF.

@c @node FIXME
@subsubsection 29 - Final Cartridge Plus

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb (1 bank of 32Kb)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $0000-$7FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 1D 00 01 00 00 00 00 00 00  ???@@????????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 80 10 00 00 00 00 00 00 80 00  CHIP??.???????.?
0050: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF  ????????????????
@end example


    This cart has 32Kb of ROM, bank 0 is in the cart image but is  unused.
    The first 8Kb of the cart image is unused, the second 8Kb of the  cart
    image is mapped to $E000-$FFFF, the third 8Kb of  the  cart  image  is
    mapped to $8000-$9FFF and the fourth 8Kb of the cart image  is  mapped
    to $A000-$BFFF. An NMI can be triggered by the cart, if address  $0001
    is written to and the cartridge is enabled. The cart can  be  disabled
    by software, by clearing bit 4 when writing to $DF00-$DFFF.  Cart  ROM
    at $E000-$FFFF can be disabled by setting bit 5 to 0 when  writing  to
    $DF00-$DFFF. Cart ROM at $8000-$BFFF can be disabled by setting bit  6
    to 1 when  writing  to  $DF00-$DFFF.  Bit  7  of  a  byte  written  to
    $DF00-$DFFF can be read back from the cartridge  if  enabled  (like  a
    memory cell).

@c @node FIXME
@subsubsection 30 - Action Replay 4

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb (4 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 1E 00 01 00 00 00 00 00 00  ???@@????????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: EA 78 48 A9 7F 8D 0D DD D0 0E 48 AD 0D DD 10 04  .xP.?Ť?..?P?.??
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 09 80 0C 80 C3 C2 CD 38 30 4C E9 80 4C 81 81 4C  ?.?....80L?.L��L
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP????????.???
4070: 09 80 0E 80 C3 C2 CD 38 30 A2 00 4C EF FC 20 BC  ?.?....80.?L?.??
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP????????.???
6080: 09 80 0C 80 C3 C2 CD 38 30 4C 70 88 4C 3F 80 4C  ?.?....80Lp�L?.L
@end example

    The control register is the I/O-1 range:

@example
    bit  meaning
    ---  -------
    0    Eprom banking bit 0 (bank address 13)
    1    Controls the GAME line (0 sets GAME low, 1 sets GAME high)
    2    Freeze-end bit (disables the register and hides any rom bank)
    3    Controls the Exrom line (1 sets EXROM low, 0 sets EXROM high)
    4    Eprom banking bit 1 (bank address 14)
    5-7  Unused
@end example

    The first page of the currently banked ROM block can be  read  in  the
    I/O-2 range.

@c @node FIXME
@subsubsection 31 - Stardos

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF (bank 0),
                   $E000-$FFFF (bank 1)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 1F 00 01 00 00 00 00 00 00  ???@@????????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: F9 80 B6 80 C3 C2 CD 38 30 FD 80 89 80 4C 0C 88  ?.¶....80..‰.L?�
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00  CHIP????????????
2060: 85 56 20 0F BC A5 61 C9 88 90 03 20 D4 BA 20 CC  …V???Ąa.��??.÷?.
@end example

    This cart has 16Kb of ROM, of which the first  8Kb  is  mapped  in  at
    $8000-$9FFF and the second 8Kb is used as a  kernel  replacement.  The
    kernel replacement is achieved by a clip that needs  to  be  installed
    inside the C64.

    Reading from I/O-1 causes a capacitor to get charged with every  read,
    once the capacitor is charged enough it switches the cart on.

    Reading from I/O-2 causes a different capacitor to  get  charged  with
    every read, once the capacitor is charged enough it switched the  cart
    off.

@c @node FIXME
@subsubsection 32 - EasyFlash

@multitable @columnfractions .3 .7
@item Size
@tab 1024Kb (64 banks of 2 * 8Kb)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-$9FFF (ROML), $A000-$BFFF or $E000-$FFFF (ROMH)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 20 00 01 00 00 00 00 00 00  ???@@????????????
0020: 45 61 73 79 46 6C 61 73 68 20 43 61 72 74 72 69  EasyFlash?Cartri
0030: 64 67 65 00 00 00 00 00 00 00 00 00 00 00 00 00  dge?????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
0050: 00 85 5E FE C3 C2 CD 38 30 93 0D 2B 2B 2B 20 45  ?…^....80.?+++?E
@end example


    EasyFlash is a 1 MByte Flash EPROM card with  multiple  configurations
    and banks possible, it also has 256 bytes of RAM which is mapped  into
    the I/O-2 range.

    There are two control registers, one at $DE00 and one at $DE02.

    The register at $DE00 does the following:

@example
    bit  meaning
    ---  -------
    7    LED control
    6-3  Unused
    2    Mode (0/1)
    1    Exrom line control
    0    Game line control
@end example

    The register at $DE02 controls which bank  is  mapped  into  ROMH  and
    ROML.

@c @node FIXME
@subsubsection 33 - EasyFlash Xbank

@multitable @columnfractions .3 .7
@item Size
@tab -
@item EXROM
@tab -
@item GAME
@tab -
@item Load address
@tab -
@end multitable

This CRT type is not actually related to a seperate hardware, it is used by some
EasyFlash related tools as a container format. Consequently VICE does (can) not
load files of this type.

@c @node FIXME
@subsubsection 34 - Capture

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $E000-$FFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 22 00 01 00 00 00 00 00 00  ???@@???"????????
0020: 4D 61 67 69 63 20 46 6F 72 6D 65 6C 00 00 00 00  Magic?Formel????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 01 E0 00 20 00  CHIP????????????
0050: 00 0A 0D 8A B4 A1 20 80 00 0A 82 8A 8D 20 9E 20  ???Š?.?.??‚ŠŤ?ž?
@end example


    This cart has 8Kb of ROM which is mapped to  $E000,  and  8Kb  of  RAM
    which is mapped to $6000. The cartridge is disabled after a reset.

    When the freeze button is pressed the following happens:

@itemize @bullet
@item an NMI is generated
@item as soon as the current adress is in bank 0xfe the cart  switches  to
      ultimax  mode.  The  cart  ROM  then  contains  one  page  full   of
      "jmp $eaea", which ultimately calls the freezer code.
@item the $FFF7/$FFF8 "register" logic is enabled and any access (read  or
      write) to $FFF7 will turn the cart_enabled off (leave ultimax mode),
      and an access to $FFF8 will turn the cart  back  on  (enter  ultimax
      mode). the "register logic" that causes this can  only  be  disabled
      again by a hardware reset.
@end itemize

@c @node FIXME
@subsubsection 35 - Action Replay 3

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 23 00 01 00 00 00 00 00 00  ???@@???#????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: EA A9 E3 48 A9 7B 48 08 4C 1A 80 EA EA EA 48 AD  ...H..H?L?....H
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 09 80 5E FE C3 C2 CD 38 30 78 A2 FB D8 9A A9 27  ?.^....80x.....'
@end example


    This cart has 16Kb of ROM of which 8Kb is mapped in at both  ROML  and
    ROMH. Bank switching and control register is done  through  the  I/O-1
    range:

@example
    bit  meaning
    ---  -------
    7-4  unused
    3    Exrom line control
    2    Disable cart
    1    Unused
    0    Bank
@end example

@c @node FIXME
@subsubsection 36 - Retro Replay

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb, 64Kb or 128Kb (4, 8 or 16 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 24 00 00 00 00 00 00 00 00  ???@@???$????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 0C 80 C3 C2 CD 38 30 4C 7F 81 4C 87 81 4C  ?.?....80L?�L.�L
@end example


    The Retro Replay has three registers: Two write-only ($DE00  &  $DE01)
    and one read-only register ($DE00 & $DE01 giving the same results).

    The register at $DE00 is reset to $00 on a hard reset if not in  flash
    mode. If in flash mode, it is set to  $02  in  order  to  prevent  the
    computer from starting the normal cartridge. Flash  mode  is  selected
    with a jumper.

    Register at $DE00:

@example
    bit  meaning
    ---  -------
    0    Controls the GAME line: A 1 asserts the line, a 0  will  deassert
         it.
    1    Controls the EXROM line: A 0 will assert it, a  1  will  deassert
         it.
    2    Writing a 1 will disable further write accesses to all  registers
         of the Retro Replay, and  set  the  memory  map  of  the  C64  to
         standard, as if there is no cartridge installed at all.
    3    Controls bank-address 13 for ROM and RAM banking.
    4    Controls bank-address 14 for ROM and RAM banking.
    5    Switches between ROM and RAM: 0=ROM, 1=RAM
    6    Must be written once to "1" after a successful freeze in order to
         set the correct memory map and  enable  bits  0  and  1  of  this
         register. Otherwise no effect.
    7    Controls bank-address 15 for ROM banking.
@end example

    The register at $DE01 is the extended  control  register.  If  not  in
    Flash mode, bits 1, 2 and 6 can only be  written  once.  If  in  Flash
    mode, the REUcomp bit cannot be set, but  the  register  will  not  be
    disabled by the first write. Bit 5 is always set to 0 if not in  Flash
    mode.

    Register at $DE01:

@example
    bit  meaning
    ---  -------
    0    Enable clockport connector.
    1    AllowBank (1 allows banking of RAM in $DF00/$DE02 area)
    2    NoFreeze (1 disables Freeze function)
    3    Bank-address 13 for RAM and ROM (mirror of $DE00)
    4    Bank-address 14 for RAM and ROM (mirror of $DE00)
    5    Bank-address 16 for ROM (only in flash mode)
    6    REU compatibility bit. 0=standard memory map, 1 = REU  compatible
         memory map
    7    Bank-address 15 for ROM (mirror of $DE00)
@end example

    Reading from the registers at either $DE00 or $DE01  will  return  the
    content of the status register.

    Status register:

@example
    bit  meaning
    ---  -------
    0    1=Flashmode active (jumper set)
    1    feedback of AllowBank bit
    2    1=Freeze button pressed
    3    feedback of banking bit 13
    4    feedback of banking bit 14
    5    feedback of banking bit 16
    6    1=REU compatible memory map active
    7    feedback of banking bit 15
@end example

    The following memory maps are available:

@itemize @bullet
@item standard - 
    $DE00 and $DE01 registers are active,  $DF00-$DFFF  contain  the  last
    page of the selected 8Kb bank  of  either  ROM  or  RAM,  whatever  is
    selected. RAM can only be accessed in $8000-$9FFF. ROM can  be  mapped
    to $8000, $A000 or $E000 with the corresponding  status  on  GAME  and
    EXROM.

    Note: If the AllowBank bit is  not  set,  the  $DF00-$DFFF  area  will
    always access bank 0 of the RAM, so the older  cartridge  images  will
    work. The AllowBank bit does not have any effect on the ROM mirror  in
    that area.

@item Freeze -
    ROM is mapped to $E000-$FFFF, bank 0 is active directly after  Freeze.
    Writing to bits 0 and 1 of the $DE00 register will have no  effect  on
    GAME and EXROM. RAM can be  selected  and  used  in  $DF00  or  $DE02,
    respectively, but not in $8000. Banking bits work, so  you  have  full
    read access to the ROM, and access to up to four RAM  pages  with  the
    AllowBank bit set (minus 2 bytes if REU compatible bit  is  set).  You
    should leave this memory map ASAP by setting bit 6 of  $DE00,  because
    C64 RAM in the $E000 area is not available, and you don't have control
    of the GAME and EXROM lines.

@item REU compatible -
    $DE00 and $DE01 registers are active, $DE02-$DEFF contain a mirror  of
    $9E02-$9EFF of the selected 8K-bank of either ROM or RAM, whatever  is
    selected. RAM can only be accessed in $8000-$9FFF. ROM can  be  mapped
    to $8000, $A000 or $E000 with the corresponding  status  on  GAME  and
    EXROM. The $DF00 stays free for use with the 1764 Ram  Expansion  Unit
    (REU).

    Note: If the AllowBank bit is  not  set,  the  $DE02-$DEFF  area  will
    always access bank 0 of the RAM, so the older  cartridge  images  will
    work. The AllowBank bit does not have any effect on the ROM mirror  in
    that area.
@end itemize

@c @node FIXME
@subsubsection 37 - MMC64

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 25 00 01 00 00 00 00 00 00  ???@@???%????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 64 97 C3 C2 CD 38 30 78 D8 A2 FF 9A 20 D4  ?.d—...80x..?.?.
@end example


    The clockport registers  of  this  cart  can  be  switched  to  either
    $DE01-$DE0F or $DF21-$DF2F. The control  registers  are  available  at
    $DF10-$DF13.

    The register at $DE01 / $DF21 is write only:

@example
    bit  meaning
    ---  -------
    7-1  Unused
    0    0 = disable clock port, 1 = enable clockport
@end example

    The registers at $DE02-$DE0F / $DF22-$DF2F are for the clock port  and
    are read/write.

    The register at $DF10 is the  MMC64  SPI  transfer  register,  a  byte
    written to this registers is sent to the card & response from the card
    is read here.

    The register at $DF11 is the MMC64 control register:

@example
    bit  meaning
    ---  -------
    0    0 = MMC64 BIOS active, 1 = external ROM active
    1    0 = card selected, 1 = card not selected
    2    0 = 250khz transfer, 1 = 8mhz transfer
    3    0 = clock port @@ $DE00, 1 = clock port @@ $DF20
    4    0 = normal Operation, 1 = flash mode (*)
    5    0 = allow external rom when BIOS is disabled,
         1 = disable external ROM
    6    0 = SPI write trigger mode, 1 = SPI read trigger mode
    7    0 = MMC64 is active, 1 = MMC64 is completely disabled (**)
@end example

    (*) bit can only be programmed when flash jumper is set
    (**) bit can only be modified after unlocking

    The  register  at  $DF12  is  the  MMC64  status  register,  which  is
    read-only:

@example
    bit  meaning
    ---  -------
    0    0 = SPI ready, 1 = SPI busy
    1    external GAME line
    2    external EXROM line
    3    0 = card inserted, 1 = no card inserted
    4    0 = card write enabled, 1 = card write disabled
    5    0 = flash jumper not set, 1 = flash jumper set
    6-7  unused
@end example

    The register at $DF13 is the MMC64 identification register, which when
    reading from it can have the following values:

    $64 when bit 1 of $DF11 is 0.
    $01 when bit 1 of $DF11 is 1 and REV A hardware is used.
    $02 when bit 1 of $DF11 is 1 and REV B hardware is used.

    when writing to it it can be used to unlock  bit  7  of  $DF11  or  to
    re-enable the cart:

    Write $55 & $AA into this register to unlock bit 7 of $DF11.
    Write $0A & $1C into this register to re-enable MMC64 hardware.

@c @node FIXME
@subsubsection 38 - MMC Replay

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb or 512Kb (8 or 64 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 26 00 00 00 00 00 00 00 00  ???@@???&????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 1A 80 6E 9E C3 C2 CD 38 30 4D 4D 43 52 45 50 4C  ?.nž...80MMCREPL
@end example


    The cart uses the following registers:

    $DE00 - RR control register write

@example
    bit  meaning
    ---  -------
    0    GAME line
    1    EXROM line
    2    1 = disable RR, bit can be reset by setting bit 6 of $DF12
    3    bank address 13
    4    bank address 14
    5    0 = rom enable, 1 = ram enable
    6    1 = exit freeze mode
    7    bank address 15
@end example

    $DE01 - extended RR control register write

@example
    bit  meaning
    ---  -------
    0    0 = disable clockport, 1 = enable clockport
    1    0 = disable I/O RAM banking, 1 = enable I/O RAM banking
    2    0 = enable freeze, 1 = disable freeze
    3    bank address 13 (mirror of $DE00)
    4    bank address 14 (mirror of $DE00)
    5    0 = enable MMC registers, 1 = disable MMC registers. Can only  be
         written when bit 6 of $DF12 is 1. Register becomes effective when
         bit 0 of $DF11 is 1.
    6    0 = RAM/ROM at $DFxx, 1 = RAM/ROM at $DExx
    7    bank address 15 (mirror of $DE00)
@end example

    $DE02-$DE0F - Clockport memory area (when enabled)

    $DF10 - MMC SPI transfer register, a byte written is sent to the  card
            & response from the card is read here.

    $DF11 - MMC control register

@example
    bit  meaning
    ---  -------
    0    0 = MMC BIOS enabled, 1 = MMC BIOS disabled.  Enabling  MMC  BIOS
         sets ROM banking to the last 64Kb bank.
    1    0 = card selected, 1 = card not selected. This bit also  controls
         the green activity LED.
    2    0 = 250khz transfer, 1 = 8mhz transfer
    3    ALWAYS 0
    4    ALWAYS 0
    5    (in RR-Mode:)
          0 = allow RR rom when MMC BIOS disabled , 1 = disable RR ROM
          (in mmcreplay bios mode:)
          RAM banking (0 = $E000 - $FFFF, 1 = $8000 - $9FFF)
          (in 16K mode:)
          enable RAM at $A000 - $BFFF
    6    0 = SPI write trigger mode, 1 = SPI read trigger mode
    7    ALWAYS 0
@end example

    $DF12 - MMC status register

@example
    bit  meaning
    ---  -------
    0    0 = SPI ready, 1 = SPI busy (read)
                        1 = forbid ROM  write  accesses  (write).  Setting
                        this bit will disable writes  to  ROM  until  next
                        reset
    1  feedback of $DE00 bit 0 (GAME)
    2  feedback of $DE00 bit 1 (EXROM)
    3  0 = card inserted, 1 = no card inserted
    4  0 = card write enabled, 1 = card write disabled
    5  EEPROM DATA line /  DDR  register.  Setting  DATA  to  "1"  enables
       reading data bit from EEPROM at this position.
    6  0 = RR compatibility mode, 1 = Extended mode
       Selecting RR compatibility mode limits RAM  to  32Kb  and  disables
       writes  to  extended  banking  register.  Selecting  Extended  mode
       enables full RAM banking and enables Nordic Power mode in RR mode.
    7  EEPROM CLK line
@end example


    $DF13 - Extended banking register
            Can only be read/written to when bit 6 of $DF12 is 1

@example
    bit  meaning
    ---  -------
    0    bank address 16
    1    bank address 17
    2    bank address 18
    3    ALWAYS 0
    4    ALWAYS 0
    5    16K rom mapping
    6    1 = enable  RR  register.  Disabling  RR  register  disables  ALL
         ROM/RAM banking too.
    7    ALWAYS 0
@end example

@c @node FIXME
@subsubsection 39 - IDE64

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb or 128Kb (4 or 8 banks of 16Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 27 00 01 00 00 00 00 00 00  ???@@???'????????
0020: 49 44 45 36 34 20 43 41 52 54 52 49 44 47 45 20  IDE64 CARTRIDGE?
0030: 49 44 45 44 4f 53 20 32 30 31 33 31 32 31 32 00  IDEDOS 20131212?
0040: 43 48 49 50 00 00 40 10 00 02 00 00 80 00 40 00  CHIP????????.???
0050: 63 80 5E FE C3 C2 CD 38 30 20 49 44 45 36 34 20  c.^....80?IDE64?
@end example

    The IDE64 cart uses the following registers:

@example
    $DE20 - $DE2F IDE BUS Registers
    $DE30 - Low Data HDD register
    $DE31 - High Data HDD register
@end example

    $DE32 register:

@example
    bit  meaning
    ---  -------
    7    unused (0)
    6    unused (0)
    5    unused (0)
    4    version number (1)
    3    romaddr15
    2    romaddr14
    1    game
    0    exrom
@end example

@example
    $DE32 - $DE35 = IDE64 ROM bank select registers
    $DE5F         = RTC access (bit 0 only to serial accessed RTC)
    $DE60 - $DEFF = ROM used by software
    $DEFB         = IDE64 clock reset, kill the cartridge
    $DEFC - $DEFF = IDE64 memory configuration registers
@end example

@c @node FIXME
@subsubsection 40 - Super Snapshot V4

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb (4 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 28 00 01 00 00 00 00 00 00  ???@@???(????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 80 AD B5 80 C3 C2 CD 38 30 08 48 A9 06 8D 00 DF  .µ....80?P.?Ť??
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP???????? ???
2060: 4C FA A0 A9 07 8D 00 DD 2C 00 DD 50 FB 2C 00 DD  L? .?Ť?.,?.P.,?.
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
4070: 13 80 BC FE C3 C2 CD 38 30 08 48 A9 02 8D 00 DF  ?.?....80?H.?Ť??
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00  CHIP???????? ???
6080: F0 8A 48 A9 00 85 22 85 23 8D 53 0F 20 0C A1 B0  ?ŠH.?…"…#ŤS???.°
@end example


    This cart has 32Kb of ROM and 8Kb of RAM, it uses I/O-1 as a mirror of
    the last page of cart RAM. It has the following registers in the I/O-2
    range:

    ROM config register at $DF00 (can only be written to):

@example
    bit  meaning
    ---  -------
    0    ?
    1    ? (write 1 to release freeze mode)
    2    ROM bank select
    3    write 1 to disable cartridge
    4-6  unused
    7    ?
@end example

    Note: if bit0, bit1, bit7 are all 0, then ultimax mapping is  selected
    and RAM is enabled at ROML, otherwise if bit 0 is 0, then 16Kb mapping
    is enabled, or if bit 0 is 1, then 8Kb mapping is enabled.

    RAM config register at $DF01 (read/write):

    If written value == last value - 1, then ultimax mapping  is  selected
    and RAM is enabled at ROML, if written value == last value +  1,  then
    ROM is enabled at ROML and exrom is deasserted (switch to either 8k or
    16k mapping)

    $DF02-$DFFF holds the last page of the first 8kb of the current bank.

@c @node FIXME
@subsubsection 41 - IEEE-488

@multitable @columnfractions .3 .7
@item Size
@tab 4Kb (1 bank of 4Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$8FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 29 00 01 00 00 00 00 00 00  ???@@???)????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 10 10 00 00 00 00 80 00 10 00  CHIP????????.???
0050: 09 80 7A 80 C3 C2 CD 38 30 8E 16 D0 20 84 FF 20  ?.z....80Ž?.?„??
@end example


    The cart uses a TPI for the  IEEE488  interface/communication  in  the
    I/O-2 range:

@example
    $DF00 - Port A Data
    $DF01 - Port B Data
    $DF02 - Port C Data
    $DF03 - Port A Direction
    $DF04 - Port B Direction
    $DF05 - Port C Direction
    $DF06 - Control register
    $DF07 - Active Interrupt register
@end example

@c @node FIXME
@subsubsection 42 - Game Killer

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $E000-$FFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 2A 00 00 00 00 00 00 00 00  ???@@???*????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00  CHIP????????????
0050: 00 25 08 CF 07 9E 32 30 38 38 20 4D 43 2E 43 52  ?%?.?ž2088?MC.CR
@end example


    When the cartridge is active, ultimax  is  enabled  when  the  address
    being accessed is is the $E000-$FFFF range, so the ROM is  visible  at
    $E000, below is normal C64 RAM. The cart can be disabled by writing to
    either I/O-1 or I/O-2 range. When the freezer button is  pressed,  the
    cartridge will be enabled and an NMI will be triggered.

@c @node FIXME
@subsubsection 43 - Prophet64

@multitable @columnfractions .3 .7
@item Size
@tab 256Kb (32 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 2B 00 01 00 00 00 00 00 00  ???@@???+????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 09 80 C3 C2 CD 38 30 78 A0 00 84 F8 84 FA  ?.?....80x ?„?„?
@end example


    The control register is the I/O-2 range:

@example
    bit  meaning
    ---  -------
    7-6  unused
    5    disable cart
    4-0  bank select
@end example

@c @node FIXME
@subsubsection 44 - EXOS

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $E000-$FFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 2C 01 00 00 00 00 00 00 00  ???@@???,????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00  CHIP????????????
0050: 85 56 20 0F BC A5 61 C9 88 90 03 20 D4 BA 20 CC  …V???Ąa.��??.÷?.
@end example


    This cart has 8Kb of ROM, mapped in at $E000-$FFFF only when hirom  is
    selected. The cart uses a clip that needs to be installed  inside  the
    C64.

@c @node FIXME
@subsubsection 45 - Freeze Frame

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 2D 00 01 00 00 00 00 00 00  ???@@???-????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 10 80 10 80 C3 C2 CD 38 30 20 00 00 00 00 00 00  ?.?....80???????
@end example


    When reading from the I/O-1 range the cart is  enabled,  when  reading
    from the I/O-2 range the cart is disabled. When the freeze  button  is
    pressed the ROM is mapped to both $8000-$9FFF and $E000-$FFFF.

@c @node FIXME
@subsubsection 46 - Freeze Machine

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb or 32Kb (2 or 4 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 2E 00 01 00 00 00 00 00 00  ???@@???.????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 3A 83 60 80 C3 C2 CD 38 30 20 00 00 40 00 00 00  :�`....80???@@???
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP???????? ???
2060: 78 A9 34 85 01 A0 00 B1 F8 91 F6 E6 F8 D0 02 E6  x.4…? ?±?.?µ?.?µ
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
4070: 3A 83 60 80 C3 C2 CD 38 30 20 00 00 40 00 00 00  :�`....80???@@???
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00  CHIP???????? ???
6080: 78 A9 34 85 01 A0 00 B1 F8 91 F6 E6 F8 D0 02 E6  x.4…? ?±?.?µ?.?µ
@end example


    Warning, the following information is based on guess-work and might be
    incorrect, any further information and/or corrections are appreciated.

    When reading from  the  I/O-1  range  ROM  bank  0(/2)  is  mapped  to
    $8000-$9FFF and ROM bank 1(/3) is mapped to $A000-$BFFF. When  reading
    from the I/O-2 range the cart is disabled. When a  reset  happens  the
    ROM banks get switched and ROM bank 0(/2) is  mapped  to  $8000-$9FFF.
    When a freeze happens ROM bank 0(/2) is mapped to both $8000-$9FFF and
    $E000-$FFFF.


@c @node FIXME
@subsubsection 47 - Snapshot 64

@multitable @columnfractions .3 .7
@item Size
@tab 4Kb (1 bank of 4Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $E000-$EFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 2F 00 00 00 00 00 00 00 00  ???@@???/????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 10 10 00 00 00 00 E0 00 10 00  CHIP????????????
0050: 78 D8 48 8A 48 98 48 AC 0D DD 10 03 4C EE F2 AD  x.HŠH�H??.??L??
@end example


    Warning, the following information is based on guess-work and might be
    incorrect, any further information and/or corrections are appreciated.

    The cart has a control bit (bit 0) in the I/O-2 range which is used to
    disable or enable the cart.


@c @node FIXME
@subsubsection 48 - Super Explode V5.0

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 30 00 01 00 00 00 00 00 00  ???@@???0????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: D7 86 5E FE C3 C2 CD 38 30 A9 00 2C A9 FF 85 FE  .†^....80.?,.?….
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: E8 96 5E FE C3 C2 CD 38 30 20 6C 81 A9 09 8D 99  ?–^....80?l�.?Ť™
@end example


    Warning, the following information is based on guess-work and might be
    incorrect, any further information and/or corrections are appreciated.

    The cart has 16Kb of ROM which are used as two banks of 8Kb, they  are
    mapped into $8000-$9FFF and the last page of the current ROM  bank  is
    mirrored in $DF00-$DFFF. The cart has a control bit (bit 7) at  $DF00,
    which is used to select what ROM bank is used.


@c @node FIXME
@subsubsection 49 - Magic Voice

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Load address
@tab $8000-$9FFF (bank 1),
                   $A000-$BFFF (bank 2)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 31 00 01 00 00 00 00 00 00  ???@@???1????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: EA 2C 80 DF 50 FB A0 00 8C 80 DF B9 E3 A3 29 0F  .,.?P. ?Ś.?ą.Ł)?
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP???????? ???
2060: 4A EB C0 49 6A EA BB FB 4E CA 43 1E 75 63 15 97  J?.Ij.».N.C?uc?—
@end example


    This cart has 16Kb of ROM, mapped in at reset at $8000-$BFFF. The cart
    is controled through a TPI at $DF80-$DF87:

@example
    $DF80 - Port A Data
    $DF81 - Port B Data
    $DF82 - Port C Data
    $DF83 - Port A Direction
    $DF84 - Port B Direction
    $DF85 - Port C Direction
    $DF86 - Control register
    $DF87 - Active Interrupt register
@end example

    The cart has a pass-through port and does the following at start-up:

@itemize @bullet
@item Program  starts  after  reset  at  $FFD3,  and  copies   code   from
      $FF36-$FFD2 to $0200-$029C (157 bytes)

@item Program continues at $021A, copies $A000-$BFFF from EPROM to RAM  at
      $A000-$BFFF  (8Kb),  copies  $E000-$FFFF  from  EPROM  to   RAM   at
      $E000-$FFFF (8Kb), copies $AE62-$B461 from RAM to RAM at $C000-$C5FF
      (Magic Voice Code)

@item Jump to beginning of Magic Voice code at $C000
@end itemize

@c @node FIXME
@subsubsection 50 - Action Replay 2

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8k Game
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 32 00 01 00 00 00 00 00 00  ???@@???2????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: EA EA 68 AA 68 85 94 68 85 95 68 85 96 68 85 97  ..h×h…”h…•h…–h…—
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 30 80 5E FE C3 C2 CD 38 30 20 04 90 4C 38 DF 1A  0.^....80??�L8??
@end example


    Warning, the following information is based on guess-work and might be
    incorrect, any further information and/or corrections are appreciated.

    I/O-1 is somehow used to enable the cart, the exact way in which  this
    is done is unknown. Reading from the I/O-2 range  will  give  you  the
    last page of the current ROM bank, and writing to it will disable  the
    cart.

@c @node FIXME
@subsubsection 51 - MACH 5

@multitable @columnfractions .3 .7
@item Size
@tab 4Kb or 8Kb (1 bank of 4Kb or 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8k Game
@item Load address
@tab $8000-$8FFF (4Kb),
                   $8000-$9FFF (8Kb)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 33 00 01 00 00 00 00 00 00  ???@@???3????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: AF 83 5E FE C3 C2 CD 38 30 4D 41 43 48 35 A5 93  »�^....80MACH5Ą.
@end example


    This cart has 8Kb ROM mapped at $8000-$9FFF, the $9E00-$9EFF range  is
    mirrored at $DE00-$DEFF and  the  $9F00-$9FFF  range  is  mirrored  at
    $DF00-$DFFF.


@c @node FIXME
@subsubsection 52 - Diashow maker

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8k Game
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 34 00 01 00 00 00 00 00 00  ???@@???4????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 09 80 C3 C2 CD 38 30 AD 11 D0 29 10 D0 62  ?.?....80?.)?.b
@end example


    Accessing I/O-1 (the software  uses  $DE00  only  it  seems)  disables
    cartridge ROM. A reset enables 8K game mode and the ROM bank is mapped
    to $8000. A freeze causes ROM to be mapped to $8000.


@c @node FIXME
@subsubsection 53 - Pagefox

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Startup mode
@tab 16k Game
@item Load address
@tab $8000-$BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 35 01 01 00 00 00 00 00 00  ???@@???5????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 31 80 BB 0E C3 C2 CD 38 30 50 46 20 56 31 2E 30  1.»?...80PF?V1.0
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00  CHIP??@@?????.?@@?
4060: A2 FE 9A 20 EC AE 20 82 80 20 74 86 20 A5 8B 4C  ...??®?‚.?t†?Ą‹L
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00  CHIP??@@?????.?@@?
8070: 5A 01 02 03 04 06 0A 0B 10 14 1E 28 3C 00 00 00  Z??????????(<???
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00  CHIP??@@?????.?@@?
C080: 1E 03 14 82 09 05 09 0F 0C 0D 0F 05 09 09 0B 0A  ???‚????????????
@end example


    This cart has 64Kb ROM (2 32Kb Eproms, mapped to $8000  and  $A000  in
    16Kb Game Mode), and 32Kb RAM (mapped to $8000 and $A000 in  16K  Game
    Mode). The cart has 1 (write-only)  bank  control  register  which  is
    located at $DE80 and mirrored throughout the $DE80-$DEFF range:

@example
    Bit 0: unused/don't care
    Bit 1: Bank select: 0=upper, 1=lower (not correct ?!)
    Bit 2: chip select 0
    Bit 3: chip select 1
    Bit 4: cartridge enable/disable: 0=enable, 1=disable
    Bits 5-7: unused/don't care
@end example

    Chip select combinations of 0/1 are:
@example
    00: Eprom "79"
    01: Eprom "ZS3"
    10: Ram
    11: empty space (reading returns VIC-II data)
@end example

    note: on the original hardware "disabling" the  cartridge  by  setting
          bit 4 of the control register does NOT prevent write accesses to
          the cartridge RAM!. So  to  actually  disable  the  RAM,  it  is
          suggested to write $FF to the register.

@c @node FIXME
@subsubsection 54 - Kingsoft

@c FIXME: todo

@multitable @columnfractions .3 .7
@item Size
@tab -
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Startup mode
@tab 16k Game
@item Load address
@tab -
@end multitable

@c @node FIXME
@subsubsection 55 - Silverrock 128

@c FIXME: todo

@multitable @columnfractions .3 .7
@item Size
@tab 128k (16 banks of 8k)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8k Game
@item Load address
@tab $8000-$9FFF
@end multitable

@c @node FIXME
@subsubsection 56 - Formel 64

@c FIXME: todo

@multitable @columnfractions .3 .7
@item Size
@tab 32kb (4 banks of 8k)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $E000-$FFFF
@end multitable

@c @node FIXME
@subsubsection 57 - RGCD

@c FIXME: todo

@multitable @columnfractions .3 .7
@item Size
@tab 64kb (8 banks of 8k)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8k Game
@item Load address
@tab $8000-$9FFF
@end multitable

    This cartridge type is very similar to the Magic Desk cart type: ROM  memory
    is  organized  in  8Kb  ($2000)  banks  located  at  $8000-$9FFF.  Bank
    switching is done by writing the bank number to $DE00.

@example
    bit 0-2   bank number
    bit 3     exrom (1 = cart disabled)
@end example


@c @node FIXME
@section The PSID image format for ripped SID tunes

This section describes the SID file format used for SID tunes in the HVSC
(High Voltage SID Collection - http://hvsc.de). It is based mostly on
Michael Schwendt's document that describes the file format and the PSID v2NG
extensions described by Simon White and Dag Lem and was further extended by
Wilfred Bos (PSID v3, RSID v3) and LaLa (assembled most of the following text) 
and last not least tweaked a bit by Groepaz to fit into the VICE documentation.

SID files use the .sid file extension.

Since PSID v2 is simply an extension of PSID v1, PSID v2NG is an extension of
PSID v2, RSID is a restricted version of PSID v2NG, PSID v3 and RSID v3 are
extentions of PSID v2NG and RSID v2, all of the formats are discussed together
below. RSID in specific is discussed in detail under the 'magicID' field
description.

The information presented here targets programmers or other people with
reasonable background. It is not suitable for newbies who have never before
used a machine code monitor, a disassembler, or a hexadecimal editor.


@c @node FIXME
@subsection The SID file header v1

The detailed structure of the SID header looks like the following. Header
offsets are in hexadecimal notation. Other integer values are decimal unless
explicitly marked otherwise. Any stored integer values are in big-endian
format:

@example
+00    magicID: ``PSID'' or ``RSID''
@end example

This is a four byte long ASCII character string containing the value
0x50534944 or 0x52534944. 'RSID' (Real SID) denotes that the file strictly
requires a true Commodore-64 environment to run properly. 'PSID' files will
generally run trouble-free on older PlaySID and libsidplay1 based emulators,
too.

Some words about the Real C64 SID file format (RSID):

The RSID format was designed to contain tunes that are not PlaySID compatible,
but strictly require a real C64 environment to run. Tunes that are multi-speed
and/or contain samples and/or use additional interrupt sources or do busy
looping will cause older SID emulators to lock up or play very wrongly (if at
all).

By using the name RSID for such rips all existing SID emulators will reject
these tunes safely until they can be upgraded to cope with the additional
requirements.

Due to the nature of these tunes, every effort must be made to make sure they
are directly runnable on an actual C64 computer. As such the tunes will only
be presented with the default C64 power-on environment and expected to
configure and use all hardware appropriately.

RSID is based on PSIDv2NG with the following modifications:

@itemize 
@item magicID = RSID
@item version = 2 and 3 only
@item loadAddress = 0 (reserved)
@item playAddress = 0 (reserved)
@item speed = 0 (reserved)
@item psidSpecific flag is called C64BASIC flag
@end itemize 

The above fields MUST be checked and if any differ from the above then the
tune MUST be rejected. The definitions above will force tunes to contain
proper hardware configuration code and install valid interrupt handlers.

The default C64 environment is as follows:

@itemize 
@item VIC - IRQ set to raster $137, but not enabled.
@item CIA 1 timer A - set to 60Hz with the counter running and IRQs active.
@item Other timers - disabled and loaded with $FFFF.
@item Bank register - $37
@end itemize 

A side effect of the bank register is that init MUST NOT be located under a
ROM/IO memory area (addresses $A000-$BFFF and $D000-$FFFF) or outside the
load image. Since every effort needs to be made to run the tune on a real
C64 the load address of the image MUST NOT be set lower than $07E8.

@example
+04    WORD version
@end example

Available version number can be 0001, 0002 or 0003. Headers of version 2 and 3
provide additional fields. RSID and PSID v2NG files must have 0002 or 0003 here.

@example
+06    WORD dataOffset
@end example

This is the offset from the start of the file to the C64 binary data area.
Because of the fixed size of the header, this is either 0x0076 for version 1
and 0x007C for version 2 and 3.

@example
+08    WORD loadAddress
@end example

The C64 memory location where to put the C64 data. 0 means the data are in
original C64 binary file format, i.e. the first two bytes of the data contain
the little-endian load address (low byte, high byte). This must always be true
for RSID files. Furthermore, the actual load address must NOT be less than
$07E8 in RSID files.

You must be absolutely sure what to enter here. There is no way to detect
automatically whether the first two bytes in a C64 data file are meant to be a
load address or some arbitrary bytes of code or data. Unless your C64 file is
not a normal binary file and thus has no load address in front, you need not
enter anything else than 0 here. The SID tune will not play if you specify a
load address which is present in the C64 file already.

Normal C64 binary data files have a load address in their first two bytes, so
they can be loaded to a pre-defined destination address by executing
LOAD"FILE",8,1, for instance. If a load address is explicitly specified in the
sidtune info file, some sidtune converters and utilities conjecture that the
C64 data don't have a load address in their first two bytes. Hence, the
explicit load address from the info file is moved in front of the C64 data to
create a valid C64 binary file which can be easily loaded on a C64, too. If
that C64 file were to be saved, it would contain two superfluous data bytes at
offset 2 if an original load address had been in the first two bytes of the
old file. This process of adding a duplicate load address can be repeated. The
file loader strips off the first two bytes (the used load address) and puts
the rest of the file contents (including the now obsolete load address at file
offset 2) into memory. If the new load address is the same than the old one
the two added bytes cause the whole data to be displaced by two bytes, which
most likely results in malfunctioning code. Also, superfluous bytes in memory
then can confuse disassemblers which start at the beginning of the file or
memory buffer.

@example
+0A    WORD initAddress
@end example

The start address of the machine code subroutine that initializes a song,
accepting the contents of the 8-bit 6510 Accumulator as the song number
parameter. 0 means the address is equal to the effective load address.

In RSID files initAddress must never point to a ROM area ($A000-$BFFF or
$D000-$FFFF) or be lower than $07E8. Also, if the C64 BASIC flag is set,
initAddress must be 0.

@example
+0C    WORD playAddress
@end example

The start address of the machine code subroutine that can be called frequently
to produce a continuous sound. 0 means the initialization subroutine is
expected to install an interrupt handler, which then calls the music player at
some place. This must always be true for RSID files.

@example
+0E    WORD songs
@end example

The number of songs (or sound effects) that can be initialized by calling the
init address. The minimum is 1. The maximum is 256.

@example
+10    WORD startSong
@end example

The song number to be played by default. This value is optional. It often
specifies the first song you would hear upon starting the program is has been
taken from. It has a default of 1.

@example
+12    LONGWORD speed
@end example

This is a 32 bit big endian number.

For version 1 and 2 and for version 2NG and 3 with PlaySID specific flag (+76)
set, the 'speed' should be handled as follows:

Each bit in 'speed' specifies the speed for the corresponding tune number,
i.e. bit 0 specifies the speed for tune 1. If there are more than 32 tunes,
the speed specified for tune 32 is the same as tune 1, for tune 33 it is the
same as tune 2, etc.

For version 2NG and 3 with PlaySID specific flag (+76) cleared, the 'speed'
should be handled as follows:

Each bit in 'speed' specifies the speed for the corresponding tune number,
i.e. bit 0 specifies the speed for tune 1. If there are more than 32 tunes,
the speed specified for tune 32 is also used for all higher numbered tunes.

For all version counts:

@itemize
@item A 0 bit specifies vertical blank interrupt (50Hz PAL, 60Hz NTSC), and a 1 bit
specifies CIA 1 timer interrupt (default 60Hz).
@item Surplus bits in 'speed' should be set to 0.
@item For RSID files 'speed' must always be set to 0.
@end itemize

Note that if 'play' = 0, the bits in 'speed' should still be set for backwards
compatibility with older SID players. New SID players running in a C64
environment will ignore the speed bits in this case.

WARNING: This field does not work in PlaySID for Amiga like it was intended,
therefore the above is a redefinition of the original 'speed' field in SID
v2NG! See also the 'clock' (video standard) field described below for 'flags'.

@example
+16    ``<name>''
+36    ``<author>''
+56    ``<released>'' (once known as ``<copyright>'')
@end example

These are 32 byte long ASCII character strings. Upon evaluating the header,
these fields may hold a character string of 32 bytes which is not zero
terminated. For less than 32 characters the string should be zero terminated.
The maximum number of available free characters is 32.

@example
+76    <data>
@end example

Version 1 of the SID header is complete at this point. The binary C64 data
starts here.

@c @node FIXME
@subsection The SID file header v2 and v3

Version 2 and 3 of the header incorporates the v1 header fields and provides
additional fields. Some of these are actually v2NG or v3 specific - those are
noted below.

@example
+76    WORD flags
@end example

This is a 16 bit big endian number containing the following bitfields:

@itemize
@item Bit 0 specifies format of the binary data (musPlayer):
  0 = built-in music player,
  1 = Compute!'s Sidplayer MUS data, music player must be merged.
@end itemize

If this bit is set, the appended binary data are in Compute!'s Sidplayer MUS
format, and does not contain a built-in music player. An external player
machine code must be merged to replay such a sidtune.

@itemize
@item Bit 1 specifies whether the tune is PlaySID specific, e.g. uses PlaySID
  samples (psidSpecific):
  0 = C64 compatible,
  1 = PlaySID specific (PSID v2NG, v3)
  1 = C64 BASIC flag (RSID)
@end itemize

This is a v2NG and RSID specific field.

PlaySID samples were invented to facilitate playback of C64 volume register
samples with the original Amiga PlaySID software. PlaySID samples made samples
a reality on slow Amiga hardware with a player that was updated only once a
frame.

Unfortunately, converting C64 volume samples to PlaySID samples means that
they can no longer be played on a C64, and furthermore the conversion might
potentially break the non-sample part of a tune if the timing between writes
to the SID registers is at all altered. This follows from the ADSR bugs in the
SID chip.

Today, the speed of common hardware and the sophistication of the SID players
is such that there is little need for PlaySID samples. However, with all the
PlaySID sample PSIDs in existence there's a need to differentiate between SID
files containing only original C64 code and PSID files containing PlaySID
samples or having other PlaySID specific issues. As stated above, bit 1 in
'flags' is reserved for this purpose.

Since RSID files do not have the need for PlaySID samples, this flag is used
for a different purpose: tunes that include a BASIC executable portion will
be played (with the BASIC portion executed) if the C64 BASIC flag is set. At
the same time, initAddress must be 0.

@itemize
@item Bits 2-3 specify the video standard (clock):
  00 = Unknown,
  01 = PAL,
  10 = NTSC,
  11 = PAL and NTSC.
@end itemize

This is a v2NG specific field.

As can be seen from the 'speed' field, it is not possible to specify NTSC C64
playback. This is unfortunate, since the different clock speeds means that a
tune written for the NTSC C64 will be slightly detuned if played back on a PAL
C64. Furthermore, NTSC C64 tunes driven by a vertical blank interrupt have to
be converted to use the CIA 1 timer to fit into this scheme. This can cause
severe problems, as the NTSC refresh rate is once every 17045 cycles, while
the CIA 1 timer A is latched with 17095 cycles. Apart from the difference in
timing itself, the SID ADSR bugs can actually break the tune.

The 'clock' (video standard) field was introduced to circumvent this problem.

@itemize
@item Bits 4-5 specify the SID version (sidModel):
  00 = Unknown,
  01 = MOS6581,
  10 = MOS8580,
  11 = MOS6581 and MOS8580.
@end itemize

This is a v2NG specific field.

@itemize
@item Bits 6-7 specify the SID version (sidModel) of the second SID:
  00 = Unknown,
  01 = MOS6581,
  10 = MOS8580,
  11 = MOS6581 and MOS8580.
@end itemize

This is a v3 specific field.

The MOS6581 and the MOS8580 have three notable differences. First, combined
waveforms are generally louder on a MOS8580, to the extent that some
combinations that are clearly audible on a MOS8580 are completely silent on a
MOS6581. Second, the internal DC levels in the MOS8580 are so small that
software or hardware tricks must be used to play volume samples. Third, the
MOS8580 analog filter has totally different characteristics from the MOS6581
analog filter.

To ensure that music specifically written for one of the two SID versions can
be played back correctly, bits 4-7 in 'flags' are used as stated above.

If bits 6-7 are set to Unknown then the second SID will be set to the same SID
model as the first SID.

@itemize
@item Bits 8-15 are reserved and should be set to 0.
@end itemize

@example
+78    BYTE startPage (relocStartPage)
@end example

This is a v2NG specific field.

This is an 8 bit number. If 'startPage' is 0, the SID file is clean, i.e. it
does not write outside its data range within the driver ranges. In this case
the largest free memory range can be determined from the start address and the
data length of the SID binary data. If 'startPage' is 0xFF, there is not even
a single free page, and driver relocation is impossible. Otherwise,
'startPage' specifies the start page of the single largest free memory range
within the driver ranges. For example, if 'startPage' is 0x1E, this free
memory range starts at $1E00.

@example
+79    BYTE pageLength (relocPages)
@end example

This is a v2NG specific field.

This is an 8 bit number indicating the number of free pages after 'startPage'.
If 'startPage' is not 0 or 0xFF, 'pageLength' is set to the number of free
pages starting at 'startPage'. If 'startPage' is 0 or 0xFF, 'pageLength' must
be set to 0.

The relocation range indicated by 'startPage' and 'pageLength' should never
overlap or encompass the load range of the C64 data. For RSID files, the
relocation range should also not overlap or encompass any of the ROM areas
($A000-$BFFF and $D000-$FFFF) or the reserved memory area ($0000-$03FF).

@example
+7A    BYTE secondSIDAddress
@end example

This is a v3 specific field. For v2NG, it should be set to 0.

This is an 8 bit number indicating the address of the second SID. It specifies
the middle part of the address, $Dxx0, starting from value $42 for $D420 to
$FE for $DFE0). Only even values are valid. Ranges $00-$41 ($D000-$D410) and
$80-$DF ($D800-$DDF0) are invalid. Any invalid value means that no second SID
is used, like $00.

@example
+7B    BYTE reserved
@end example

This is a 8 bit number and is reserved and should be set to 0.

@example
+7C    <data>
@end example

Version 2 and 3 of the SID header ends here. This offset is the start of the
binary C64 data. See also 'loadAddress' for what the first 2 bytes of 'data'
might indicate.

@c section used in file generation, keep to the format used.
@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{Andreas Matthies}
Improved the datasette support, the VIC20 video emulation and
some UI stuff in the Win32 and DOS ports. He also wrote the
BeOS port and implemented video/audio capture support. Improved
history recording/playback and implemented support for video
recording and the netlink feature. Made the Win32 user
changable keyboard shortcut system. Improved CIA and VIA
emulation. Worked on x64sc, especially interrupt timing. Wrote
test programs. Various bug(fixe)s. ;-)

@item
@b{Martin Pottendorfer}
Implemented the Gnome Port based on Oliver Schaertels GTK+
port. Added support code for internationalization based on
gettext. Improved the *nix fullscreen support. Translated the
UI to German. Implemented the fliplists + UI (*nix).

@item
@b{Marco van den Heuvel}
Translated the UI to Dutch. Made the internationalization
support for the Win32 and Amiga ports. Wrote the GEO-RAM and
RamCart cartridge code. Wrote the c64 +60K, +256K and 256K
memory expansions code. Wrote the pet REU code. Wrote the plus4
memory expansions code. Made the ethernet support for the DOS
port. Maintains the QNX 4.x, QNX 6.x, Solaris, Openserver,
Unixware, Minix 3.x, Amiga, Syllable and OS/2 binary ports.
Maintains the Win64 and Open Watcom project files. Maintains
the SDL port(s). Added new .crt support. Added new screenshot
formats. Added new sound recording support. Added SIDcart
support for xpet, xplus4 and xvic. Improved the MMC64
emulation. Added 2 MHz mode and banks 2/3 support for x128.
Added the various userport joystick emulations. Added text copy
and paste support to the Amiga and BeOS ports. Added DQBB and
ISEPIC cartridge support. Added SFX Sound Sampler and SFX Sound
Expander support. Added PCI support to the Amiga and DOS ports.
Rewrote the sound system into a modular one, added always mono
and always stereo support for the sound output. Added the RTC
system. Added digiblaster support. Added 3rd SID support. Added
the 6309 CPU emulation. Added the 65(S)C02 emulation. And
lots of other fixes and improvements.

@item
@b{Fabrizio Gennari}
Added some improvements to the DOS and GTK+ ports. Changed the
Windows video to use GDI as fallback, making it compile without
DX if needed. Fixed the t64 support. Added monitor window support
using VTE to the GTK+ GUI.

@item
@b{Daniel Kahlin}
Worked on DTV VIC emulation, palette, DTV SID support in resid,
better DMA/Blitter support and did lots of refactoring. Added
new monitor commands and features. Improved the VIC emulation
for xvic. Made MIDI driver code for Win32. Rewrote the xvic
cartridge system. Added Mega-Cart and Final Expansion V3.2
support to xvic. Wrote large parts of the new VIC-II emulation
used in x64sc, especially the dot clock domain emulation. Wrote
many test programs for hardware analysis.

@item
@b{Groepaz}
Added new more precise CRT emulation. Added support for the new
cartridge system and many new cartridges. Fixed up parts of
cartconv, c1541 and petcat. Added video to audio leak sound support.
Implemented many bug fixes. 
Wrote test programs. Updated this document after a long period
of outdated mess.

@item
@b{Errol Smith}
Improved VDC emulation.

@item
@b{Olaf Seibert}
Contributed some PET, including PET DWW hires, Xaw, lightpen,
hardware scaling, and disk drive patches. Added proper SuperPET
support, including 6809/6309 CPU emulation. Maintains the Xaw UI.

@item
@b{Marcus Sutton}
Made some console, dialog and joystick fixes for the BeOS port.
Maintains the BeOS port.

@item
@b{Kajtar Zsolt}
Wrote the IDE64 interface emulation, FD2000/4000 drive emulation, SCPU64
emulation and alot of fixes. Improved the mouse support. Added drive
burst modification support. Added 1541 drive sounds emulation. Improved
c64 cart emulation.

@end itemize

Former/inactive team members:

@itemize @bullet

@item
@b{Ulrich Schulz}
Maintains the Dingoo port(s).

@item
@b{Stefan Haubenthal}
Added some Amiga fixes.

@item
@b{Thomas Giesel}
Added new monitor commands, features and improvements.

@item
@b{Ingo Korb}
Corrected block allocation and interleave for c1541/vdrive,
added rudimentary xplus4 tape recording support, corrected a
case of missing Pi symbols in petcat, changed the trap opcode
byte, stopped the high-level serial drive code from responding
to addresses 16-30 and was forced to update this entry himself.

@item
@b{Antti S. Lankila}
Made the ReSID-fp engine, rewrote the PAL emulation code and
fixed the sound core for lower latency. Rewrote DTV SID support
(ReSID-dtv). Improved 1541 drive rotation emulation. Worked on
x64sc.

@item
@b{Christian Vogelgsang}
Maintained the Mac OS X port. Added Intel Mac support and
universal binary creation. Wrote the build scripts for all
external Mac libraries and the bindist bundle tool. Improved
the TFE chip emulation. Added some GTK+ fixes.

@item
@b{Dag Lem}
Implemented the reSID SID emulation engine and video hardware
scaling.

@item
@b{Spiro Trikaliotis}
Copyright @copyright{} 2000-2011
Wrote the Win32 console implementation for the built-in
monitor, corrected some REU related bugs, improved the CIA
emulation, added com-port CIA support to the Win32 port, added
text copy and paste support to the Win32 port, added support
for the TFE and RR-Net (cs8900a), and wrote some further
patches.

@item
@b{Hannu Nuotio}
Copyright @copyright{} 2007-2011
Implemented DTV flash emulation, DTV support in the monitor,
large parts of the DTV VIC, burst mode and skip cycle emulation
as well as many other things. Added NEOS and Amiga mouse,
paddle and light pen support. Added new monitor commands and
features, including memmap. Made MIDI support and OSS MIDI
driver. Implemented most of the SDL UI. Rewrote xvic CPU/VIC-I
core for cycle based emulation. Implemented C64 cartridge
snapshot support. Initiated and worked on all parts of
implementing x64sc. Wrote test programs.

@item
@b{Andreas Boose}
Copyright @copyright{} 1998-2010
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 DOS, Win32 and *nix ports. He rewrote the
C128 emulation adding Z80 mode, C64 mode and function ROM
support, wrote the screenshot and the event system and started
the plus4 emulator. Restructured the serial bus emulation and
added realdrive and rawdrive support.

@item
@b{Tibor Biczo}
Copyright @copyright{} 1998-2010
Improved the Win32 port and plus4 emulation.

@item
@b{M. Kiesel}
Copyright @copyright{} 2007-2010
Started implementing x64dtv. The C64DTV memory model and early
versions of the DMA and Blitter engine have been implemented by
him. Added new monitor commands and features.

@item
@b{Andreas Dehmel}
Copyright @copyright{} 1999-2007
Wrote the Acorn RISC OS port.

@item
@b{David Hansel}
Copyright @copyright{} 2003-2005
Wrote the Star NL10 printer driver, implemented IEC devices and
improved the tape emulation.

@item
@b{Markus Brenner}
Copyright @copyright{} 2000-2004
Added VDC emulation to x128 and added support for some more
cartridges.

@item
@b{Thomas Bretz}
Copyright @copyright{} 1999-2004
Started the OS/2 port.

@item
@b{Daniel Sladic}
Copyright @copyright{} 1997-2001
Started the work on hardware-level 1541 emulation and wrote the
new monitor introduced with VICE 0.15.

@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{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 DOS port
and the initial Win32 port (well, somebody had to do it).

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

@item
@b{Jouko Valta}
Copyright @copyright{} 1993-1996
Wrote @code{petcat} and @code{c1541}, @code{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

Internationalization Team:

@itemize @bullet

@item
@c ---translation-team---
@b{Mikkel Holm Olsen}
Copyright @copyright{} 2009-2015
Provided the Danish user interface translations and fixed a few monitor bugs.

@b{Martin Pottendorfer}
Copyright @copyright{} 2000-2015
Provided the German user interface translations.

@b{Manuel Antonio Rodriguez Bas}
Copyright @copyright{} 2011-2015
Provided the Spanish user interface translations.

@b{Paul Dubé}
Copyright @copyright{} 2004-2015
Provided the French user interface translations.

@b{Czirkos Zoltan}
Copyright @copyright{} 2006-2015
Provided the Hungarian user interface translations.

@b{Karai Csaba}
Copyright @copyright{} 2006-2015
Provided the Hungarian user interface translations.

@b{Andrea Musuruane}
Copyright @copyright{} 2001-2015
Provided the Italian user interface translations.

@b{Jesse Lee}
Copyright @copyright{} 2011-2015
Provided the Korean user interface translations.

@b{Marco van den Heuvel}
Copyright @copyright{} 2005-2015
Provided the Dutch user interface translations.

@b{Jarek Sobolewski}
Copyright @copyright{} 2011-2015
Provided the Polish user interface translations.

@b{Michael Litvinov}
Copyright @copyright{} 2010-2015
Provided the Russian user interface translations.

@b{Peter Krefting}
Copyright @copyright{} 2000-2015
Provided the Swedish user interface translations.

@b{Emir Akaydin}
Copyright @copyright{} 2008-2015
Provided the Turkish user interface translations.

@c ---translation-team-end---
@end itemize

Documentation Team:

@itemize @bullet

@item
@c ---documentation-team---
@b{Daniel Kahlin}

@b{Groepaz}

@b{Kajtar Zsolt}

@b{Marco van den Heuvel}

@b{Olaf Seibert}

@c ---documentation-team-end---

@end itemize

External contributors:

@itemize @bullet

@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 not have been possible.

@item
@b{Eliseo Bianchi}
Provided the italian Amiga translations.

@item
@b{ck!}
Provided a win32 cbm character font.

@item
@b{iAN CooG}
Added win32 vsid GUI and contributed various patches.

@item
@b{Mike Dawson}
Provided the GP2X port.

@item
@b{Paul David Doherty}
Wrote @code{zip2disk}, on which the Zipcode support in @code{c1541} is based.

@item
@b{Sven A. Droll}
Added Supergrafik support to petcat.

@item
@b{Peter Edwards}
Implemented the SDL UI slider control and fixed some
GP2X/Dingoo SDL UI issues.

@item
@b{Daniel Fandrich}
Contributed some disk drive patches.

@item
@b{Dirk Farin}
Rewrote the MITSHM code.

@item
@b{Georg Feil}
Added support for toggling CB2 sound output line in the PET
emulator.

@item
@b{Peter Andrew Felvegi aka Petschy}
Fixed a couple of bugs in the fast serial emulation.

@item
@b{Ricardo Ferreira}
Contributed the @code{unlynx} and @code{system} commands in @code{c1541} and
added aRts sound support.

@item
@b{Flooder}
Provided parts of the Polish user interface translations.

@item
@b{Robert H. Forsman Jr.}
Provided parts of the widget set for implementing the Xaw GUI.

@item
@b{Ian Gledhill}
Added support for the catweasel.device driver.

@item
@b{Peter Gordon}
Provided support for native AmigaOS4 compiling.

@item
@b{Richard Hable}
Contributed the initial version of the REU emulation.

@item
@b{Shawn Hargreaves}
Wrote Allegro, the graphics and audio library used in the DOS
version.

@item
@b{Ville-Matias Heikkila}
Rewrote the vic20 sound code.

@item
@b{David Holz}
Provided a label file which gives the built-in monitor the
labels for the C64.

@item
@b{Nathan Huizinga}
Added support for Expert and Super Snapshot carts.

@item
@b{Derrick Inksley}
Fixed loading of zip files with brackets ([]) in
the filename for the windows port. Added drive selection
functionality to the window sdl port.

@item
@b{Craig Jackson}
Contributed miscellaneous patches in the old X64 times.

@item
@b{Dirk Jagdmann}
Wrote the Catweasel sound driver.

@item
@b{Uffe Jakobsen}
Wrote the Silverrock cartridge emulation and fixed the
ocean cartridge bank wrap.

@item
@b{Lasse Jyrkinen}
Contributed miscellaneous patches in the old X64 times.

@item
@b{Peter Karlsson}
Provided the swedish UI translations in the past.

@item
@b{Greg King}
Added a working RTC to the emulation of the IDE64
cartridge. Provided some vdrive fixes.

@item
@b{Michael Klein}
Contributed the ESD sound driver, basic support for the OPENCBM
library and some other patches.

@item
@b{Frank König}
Contributed the Win32 joystick autofire feature.

@item
@b{Bernd Kortz}
Provided some fixes for ZETA and the ZETA binary package.

@item
@b{Bernhard Kuhn}
Made some joystick improvements for Linux.

@item
@b{Alexander Lehmann}
Added complete support for all the VIC20 memory configurations
for the old VICE 0.12.

@item
@b{Ilkka "itix" Lehtoranta}
Provided the routines for the cybergraphics support for the
Amiga ports.

@item
@b{Magnus Lind}
Atari ST mouse and Atari CX-22 trackball emulation and pixel
aspect fixes. Improved the Amiga mouse emulation. Improved
the vic20 sound output. Added windows POV hat support.
Improved sound fragment size handling.

@item
@b{Locnet}
Made the initial android port of x64.

@item
@b{Wolfgang Lorenz}
Wrote an excellent 6510 test suite that helped us to debug the
CPU emulation.

@item
@b{Marko Mäkelä}
Wrote lots of CPU documentation. Wrote the VIC Flash Plugin
cartridge emulation in xvic.

@item
@b{mar77i}
Fixed some resource handling issues.

@item
@b{Robert W. McMullen}
Provided parts of the widget set for implementing the Xaw GUI.

@item
@b{Jennifer Medkief}
Is in charge of checking up on the GUIs for elements that are
wrong, unaccessable, and missing.

@item
@b{Dan Miner}
Contributed some patches to the fast disk drive emulation.

@item
@b{Luca Montecchiani}
Contributed a new Unix joystick driver.

@item
@b{Wolfgang Moser}
Provided small optimization fixes to the GCR code, provided an
excellent REU test suite and added REU fixes, and is always the
good guy reviewing and commenting changes in the background.

@item
@b{Roberto Muscedere}
Improved support for REL files.

@item
@b{Tomi Ollila}
Donated @code{findpath.c}.

@item
@b{Per Olofsson}
Digitalized the C64 colors used in the (old) default palette.

@item
@b{Lasse Öörni}
Contributed the Windows Multimedia sound driver

@item
@b{Helfried Peyrl}
Supplied a patch that fixes REL file records larger 256 bytes
when using vdrive.

@item
@b{Frank Prindle}
Contributed some patches.

@item
@b{Giuliano Procida}
Used to maintain the VICE @code{deb} package for the Debian
distribution, and also helped proofreading the documentation.

@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{Rami Rasanen}
Rewrote the VIC20 sound code.

@item
@b{David Roden}
Fixed various issues related to ffmpeg settings.

@item
@b{Pablo Roldán}
Contributed initial patch for VIC-II PAL-N model selection.

@item
@b{Mathias Roslund}
Provided the AmigaOS4 port.

@item
@b{Gunnar Ruthenberg}
Provided some VIC-II enhancements and improved the Win32 port.

@item
@b{Johan Samuelsson}
Provided the Swedish Amiga translations.

@item
@b{Oliver Schaertel}
Wrote the X11 full screen, parts of custom ROM set support and
1351 mouse emulation for unix.

@item
@b{Peter Schepers}
Contributed a document describing the G64 image format.

@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{Heiko Selber}
Contributed some VIC20 I/O patches.

@item
@b{John Selck}
Improved the video rendering and added the fast PAL emulation.
Implemented new color generation based on P. Timmermanns
knowledge.

@item
@b{Chris Sharp}
Wrote the AIX sound driver.

@item
@b{Andr351 "JoBBo" Siegel}
Provided the native MorphOS icons.

@item
@b{Harry "Piru" Sintonen}
Provided lots of fixes and improvements for the Amiga ports.

@item
@b{Manfred Spraul}
Wrote the Win32 text lister.

@item
@b{Markus Stehr}
Provided the MMC64 emulation.

@item
@b{Dominique Strigl}
Contributed miscellaneous patches in the old X64 times.

@item
@b{Samuli Suominen}
Fixed XShm includes for newer xextproto versions and updated
libpng check for newer versions.

@item
@b{Steven Tieu}
Added initial support for 16/24 bpp X11 displays.

@item
@b{Philip Timmermann}
Did a lot of research about the VIC-II colors.

@item
@b{Brian Totty}
Provided parts of the widget set for implementing the Xaw GUI.

@item
@b{Mustafa "GnoStiC" Tufan}
Made improvements to the GP2x port.

@item
@b{Lionel Ulmer}
Implemented joystick support for Linux and a first try of a SID
emulation for SGI machines.

@item
@b{Krister Walfridsson}
Implemented joystick and sound support for NetBSD.

@item
@b{webulator}
Provided Win32 drag & drop support

@item
@b{Robert Willie}
Added some additional commands to the fsdevice emulation.

@item
@b{Peter Weighill}
Gave many ideas and contributed the ROM patcher.

@item
@b{Gerhard Wesp}
Contributed the @code{extract} command in @code{c1541}.

@item
@b{Maciej Witkowiak}
Did some IDE64 and C1541 fixes.

@item
@b{Peter Rittwage}
Made 1541 GCR hardware tests.

@item
@b{Robert McIntyre}
Bugged people enough to get the improved g64 support rolling, 
updated g64 support to allow variable-length tracks, and 
performed initial development of half-track support.

@item
@b{István Fábián}
Contributed a initial patch with the more correct 1541 bus
timing code and which gave us hints for to improving the 1541
emulation.

@end itemize

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

The people around the world providing results from running our
test programs on various machines deserve a special mention:

@itemize @bullet

@item
@b{hedning} (Drean C64 PAL-N, various C64 PAL boxes)
@item
@b{Jason Compton} (Various C64 and C128 NTSC boxes)
@item
@b{The Woz} (Drean C64 PAL-N)
@item
@b{Thierry} (Drean C64 PAL-N)
@item
@b{MOS6569} (C64C PAL)
@item
@b{Mike} (VIC-20 PAL)
@item
@b{Wilson} (VIC-20 NTSC)
@item
@b{Vicassembly} (VIC-20 NTSC)
@item
@b{David "jbevren" Wood} (C64 NTSC-OLD)
@end itemize

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

@itemize @bullet
@item
@b{Lutz Sammer}
@item
@b{Ralph Mason}
@item
@b{George Caswell}
@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{Frank Reichel}
@item
@b{Ullrich von Bassewitz}
@item
@b{Holger Busse}
@item
@b{David "jbevren" Wood}
@item
@b{Gary Glenn}
@end itemize

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

@c end of file generation section.
@node Copyright, Contacts, Acknowledgments, Top
@chapter Copyright

@itemize @bullet
@item
Copyright @copyright{} 1999-2015 Andreas Matthies
@item
Copyright @copyright{} 1999-2015 Martin Pottendorfer
@item
Copyright @copyright{} 2005-2015 Marco van den Heuvel
@item
Copyright @copyright{} 2007-2015 Fabrizio Gennari
@item
Copyright @copyright{} 2007-2015 Daniel Kahlin
@item
Copyright @copyright{} 2009-2015 Groepaz
@item
Copyright @copyright{} 2009-2015 Errol Smith
@item
Copyright @copyright{} 2010-2015 Olaf Seibert
@item
Copyright @copyright{} 2011-2015 Marcus Sutton
@item
Copyright @copyright{} 2011-2014 Kajtar Zsolt

@item
Copyright @copyright{} 2012-2014 Benjamin 'BeRo' Rosseaux
@item
Copyright @copyright{} 2011-2014 Ulrich Schulz
@item
Copyright @copyright{} 2011-2014 Stefan Haubenthal
@item
Copyright @copyright{} 2011-2014 Thomas Giesel
@item
Copyright @copyright{} 2009-2014 Ingo Korb
@item
Copyright @copyright{} 2006-2014 Christian Vogelgsang
@item
Copyright @copyright{} 1998-2014 Dag Lem
@item
Copyright @copyright{} 2000-2011 Spiro Trikaliotis
@item
Copyright @copyright{} 1998-2010 Tibor Biczo
@item
Copyright @copyright{} 1998-2010 Andreas Boose
@item
Copyright @copyright{} 2007-2010 M. Kiesel
@item
Copyright @copyright{} 2007-2011 Hannu Nuotio
@item
Copyright @copyright{} 1999-2007 Andreas Dehmel
@item
Copyright @copyright{} 2003-2005 David Hansel
@item
Copyright @copyright{} 2000-2004 Markus Brenner

@item
Copyright @copyright{} 1999-2004 Thomas Bretz
@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
@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://vice-emu.sourceforge.net/}
@end example

VICE has moved its source repository to public services provided by
SourceForge. You can find it at
@example
@uref{http://sf.net/projects/vice-emu}.
@end example

We would like to thank the SourceForge staff for that help.

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

Before contacting us, have a look at this manual and see if your question is answered
there. Keep in mind that we work on VICE in our spare-time, so the more
time we don't need to answer the same questions over and over again, the
more time we have to improve the emulation itself. On the other hand,
that does not mean that you should not contact us, especially if you
find bugs or have suggestions which might improve the emulation.

Bug reports, suggestions, support requests should be directed to the
SourceForge trackers at

@itemize @bullet

@item
@uref{http://sourceforge.net/tracker/?group_id=223021}.
@end itemize

This way, you, the users, and we, the developers, can track what has
been reported and what has been already fixed. Ideally, also sent the
report to the mailing address of the Vice team at

@itemize @bullet

@item
VICE Mailing List (@email{vice-emu-mail@@lists.sourceforge.net}) for all
general questions, bug reports, suggestions.

@end itemize

You can also contact (some of) us on IRC, at #vice-dev on freenode.

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://vice-emu.sourceforge.net/});
@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}) on DOS, and OpenCBM
(@uref{http://www.trikaliotis.net/opencbm}) on Windows and Linux.  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
Make sure you are giving us a diff against the latest Subversion
trunk version of VICE. For instructions on accessing the Subversion
repository, first read @uref{http://sourceforge.net/svn/?group_id=223021} and
get it with the command:
@example
@samp{svn co https://vice-emu.svn.sourceforge.net/svnroot/vice-emu/trunk vice-src}
@end example
@item
send a unified diff file against the trunk version of VICE (see above
bullet point) by using the command: @samp{svn diff} inside of the
SVN workspace you checked out before.

@item
If you cannot use SVN for one or the other reason, send a unified diff
file containing all the changes you have made @samp{diff -u};
please don't use plain @samp{diff}), as it adds much work for us to get
it working;
@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
continuous 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, Command-line Index, Concept Index, Top
@unnumbered Index of Resources

@printindex vr

@node Command-line Index, , Resource Index, Top
@unnumbered Index of Command-line options

@printindex fn

@contents

@bye
