\input texinfo @c -*- texinfo -*-
@c %**start of header
@settitle VICE Manual
@documentencoding ISO-8859-15
@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
@ifset txicommandconditionals
@ifcommanddefined firstparagraphindent
@firstparagraphindent none
@end ifcommanddefined
@end ifset
@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 platformunix if any of the following are set:
@c        platformgtk3
@ifset platformgtk3
@set platformunix
@end ifset

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

@c undef platformall if any of the following are set:
@c       platformos2 platformsdl platformgtk3 platformunix platformosx
@ifset platformos2
@clear platformall
@end ifset
@ifset platformsdl
@clear platformall
@end ifset
@ifset platformgtk3
@clear platformall
@end ifset
@ifset platformunix
@clear platformall
@end ifset
@ifset platformosx
@clear platformall
@end ifset

@c set all platform defines if platformall is still defined
@ifset platformall
@set platformgtk3
@set platformos2
@set platformosx
@set platformsdl
@set platformunix
@end ifset

@ifset txicommandconditionals
@ifcommanddefined uref
@set urefdefined
@end ifcommanddefined
@end ifset

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

@c -----------------------------------------------------------------------------
@c this disables the ugly black boxes at the end of each line on overfull hboxes
@finalout

@c -----------------------------------------------------------------------------
@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 The Versatile Commodore Emulator

@center @image{html/images/vice-logo-black}

@end titlepage

@page
@c @vskip 0pt plus 1filll

@c section used in file generation, keep to the format used.
@c ---vice-core-team---
Copyright @copyright{} 1999-__VICE_CURRENT_YEAR__ Martin Pottendorfer
Copyright @copyright{} 2005-__VICE_CURRENT_YEAR__ Marco van den Heuvel
Copyright @copyright{} 2007-__VICE_CURRENT_YEAR__ Fabrizio Gennari
Copyright @copyright{} 2009-__VICE_CURRENT_YEAR__ Groepaz
Copyright @copyright{} 2009-__VICE_CURRENT_YEAR__ Errol Smith
Copyright @copyright{} 2009-__VICE_CURRENT_YEAR__ Ingo Korb
Copyright @copyright{} 2010-__VICE_CURRENT_YEAR__ Olaf Seibert
Copyright @copyright{} 2011-__VICE_CURRENT_YEAR__ Marcus Sutton
Copyright @copyright{} 2011-__VICE_CURRENT_YEAR__ Kajtar Zsolt
Copyright @copyright{} 2016-__VICE_CURRENT_YEAR__ AreaScout
Copyright @copyright{} 2016-__VICE_CURRENT_YEAR__ Bas Wassink
Copyright @copyright{} 2017-__VICE_CURRENT_YEAR__ Michael C. Martin
Copyright @copyright{} 2018-__VICE_CURRENT_YEAR__ Christopher Phillips
Copyright @copyright{} 2019-__VICE_CURRENT_YEAR__ David Hogan
Copyright @copyright{} 2020-__VICE_CURRENT_YEAR__ Empathic Qubit
Copyright @copyright{} 2020-__VICE_CURRENT_YEAR__ Roberto Muscedere
Copyright @copyright{} 2021-__VICE_CURRENT_YEAR__ June Tate-Gans
Copyright @copyright{} 2021-__VICE_CURRENT_YEAR__ Pablo Roldan
@c ---vice-core-team-end---

@c ---ex-team---
Copyright @copyright{} 2011-2016 Stefan Haubenthal
Copyright @copyright{} 2015-2016 BSzili
Copyright @copyright{} 1999-2016 Andreas Matthies
Copyright @copyright{} 2007-2015 Daniel Kahlin
Copyright @copyright{} 2012-2014 Benjamin 'BeRo' Rosseaux
Copyright @copyright{} 2011-2014 Ulrich Schulz
Copyright @copyright{} 2011-2014 Thomas Giesel
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.

@c @end titlepage

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

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

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

@ifinfo

This is the documentation for 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.
* Media images::                Saving audio and/or video.
* Event history::               Recording and replaying a session.
* Monitor::                     The VICE built-in monitor.
* Binary monitor::              For remote control.
* c1541::                       The disk-image maintenance utility.
* Cartconv::                    Cartridge conversion utility.
* Petcat::                      Text conversion 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.
@end enumerate

@iftex
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

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

@section Emulator features

@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
@subsection C64 emulator features

As of version 2.3, two C64 emulators are provided: @samp{x64} (fast)
and @samp{x64sc} (accurate). As of version 3.4 @samp{x64} will no more get
built by default and is not contained in the default binary packages.

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

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


@node PET emulator features, CBM-II emulator features, VIC20 emulator features, Preface
@subsection 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 @uref{https://sourceforge.net/p/vice-emu/code/HEAD/tree/techdocs/PET/PETdoc.txt?format=raw, PETDoc} file.

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

The PET 8096 is basically a PET 8032 with a 64KiB extension board which
allows remapping the upper 32KiB 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 128KiB RAM in
total.  Of the additional 32KiB RAM you can use only some in blocks of 4KiB,
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 32KiB for BASIC
text and 32KiB for variables.  See @uref{https://sourceforge.net/p/vice-emu/code/HEAD/tree/techdocs/PET/PETdoc.txt?format=raw, PETDoc} for more information.

The PET 8296D is an 8296 with built-in 8250 low-profile dual disk drive.

The PET 8296GD is an 8296D 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 4KiB
at a time out of 64KiB 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
@subsection 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 128KiB
RAM, the others 256KiB. This implies some banking scheme, as the 6502 can
only address 64KiB.  And indeed those machines use a 6509, that can
address 1 MiB 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 1MiB.  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
@subsection 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 fundamentally different ways of emulating the keyboard in VICE,
both of which have their individual shortcomings and strengths:

@b{Symbolic Mapping}

The default way (@dfn{symbolic mapping}) is to map every key - as far as possible -
 in a way that inside the emulation the symbol that is printed on the host key is
 produced.
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. @dfn{The key printed on the 
host keyboard will be pressed in the emulator}. 
 
 Note that while these mappings will allow easier typing if you are used
 to your host keymap, it might cause various problems in the emulation and not all
 emulated keys are accessible. If you encounter such problems, try the positional
 mapping.

@itemize
@item
Some keys really
need to be mapped specially regardless (those that do not exist on a PC
keyboard).  Some examples are the @key{Commodore} key, @key{RUN/STOP}, 
@key{Clear/Home}. The exact mapping depends on your host layout, but should
follow mostly the layouts shown below. If in doubt, you can read the keyboard
mapping files.

@item
the emulator has
to "de-shift" (remove the shift modifier) from some keys. For example, if you
want to get a ":" on a german keyboard, you have to press "." and shift simulaneously.
Then, the emulator sees the events "shift pressed" and ":" pressed. At the moment
you have pressed shift, the emulator does not know what key you are using next
(or even if you are actually going to use another key before releasing shift again),
so it has to deliver this state to the keyboard matrix. If you press ".", then shift,
to achive a ":", the emulator has to take back the shift key although it is still
pressed, as the ":" is an unshifted key in the c64/c128 keyboard matrix.

@item
A similar problem exists when you press a key that is unshifted on the host keyboard,
and the emulator must "shift" (add the shift modifier) for the emulated keyboard. For
example on a US keyboard the brackets ([,]) are such a case. Unlike what would happen
on the real C64 when typing, 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 (eg x128 in CP/M mode) 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).
@end itemize

Yes, we know this is a bug. Unfortunately it is less than trivial to fix 100%. If
you encounter any problems, please use a positional keymap as a workaround - that
should always work as expected.

PROs:
@itemize @bullet
@item Mostly intuitive typing if your muscle memory is conditioned strong to your host keyboard.
@end itemize
CONs:
@itemize @bullet
@item Does not preserve the position of the keys.
@item Due to how the key mapping may add or remove the SHIFT flag from individual
keys, strange side effects may occur (see above).
@item SHIFT/LOCK is added to the emulated keys - which may give unexpected results
depending on your host OS and keymap (It is really emulating the SHIFT-LOCK key and
not working as a CAPS-LOCK like in your host OS anymore).
@end itemize

@b{Positional Mapping}

For the @dfn{positional mapping}s first all keys are mapped at their exact positions,
as far as possible, and then the remaining few (usually 2 or 3) will be mapped
to other, yet unused, keys. @b{This is the recommended mapping for playing games or
other programs that require keys+modifiers (shift/control/cbm) to work exactly
like on the emulated machine.} This way the keyboard is more comfortable to use 
in those programs (such as some games) that require the keys to be in the 
correct positions. On the other hand it can be quite confusing if you are not
very familiar with the original emulated keyboards. Also not all keys can be
mapped exactly this way either, which means some of them still need to be
mapped to other keys (see further down).

Like with symbolic mapping, some keys really need to be mapped specially
regardless (eg @key{RUN/STOP}). The exact mapping depends on your host layout,
but should follow mostly the layouts shown below. If in doubt, you can read the
keyboard mapping files.

PROs:
@itemize @bullet
@item Mostly intuitive typing if your muscle memory is conditioned strong to your (eg) C64 keyboard.
@item Does preserve the position of (most of) the keys.
@item Natural SHIFT and SHIFT/LOCK behaviour
@end itemize
CONs:
@itemize @bullet
@item Weird to use if you are not familiar with the emulated (eg) C64 keyboard.
@end itemize

@b{Notes}

We depend a lot on your support to improve the keyboard maps, as we can not
test all emulators in all possible configurations and using all host keyboard
mappings. Please report any problems to us so we can fix them!

If you experience problems with 'accent' keys such as acute, grave, tilde, 
circumflex, diaresis (and possibly more/other, depending on your host keyboard
layout) try switching to a "no deadkeys" layout in your OS. Note that @b{currently
SDL requires using a "no deadkeys" keyboard layout!} In any case, please
also report these problems so we can fix them!

For more information on making your own keymaps (or helping to fix/update the
existing ones), see @pxref{Keymap files}.

@subsection C64 & VIC20 Keyboard Map

@image{html/images/c64-layout-small}

This mapping applies to the C64, SCPU, VIC20 and DTV emulators.

@subsubsection Symbolic (US)
@image{html/images/vice-c64-symbolic-keymap-us-small}
@subsubsection Positional (US)
@image{html/images/vice-c64-positional-keymap-us-small}

@subsubsection Symbolic (DE)
@image{html/images/vice-c64-symbolic-keymap-de-small}
@subsubsection Positional (DE)
@image{html/images/vice-c64-positional-keymap-de-small}

@subsection C128 Keyboard Map

@image{html/images/c128-layout-small}

This mapping applies to the C128 emulator. It is for a large part identical with
the respective C64 mapping, plus the added function- and extra keys.

@subsubsection Symbolic (US)
@image{html/images/vice-c128-symbolic-keymap-us-small}
@subsubsection Positional (US)
@image{html/images/vice-c128-positional-keymap-us-small}

@subsubsection Symbolic (DE)
@image{html/images/vice-c128-symbolic-keymap-de-small}
@subsubsection Positional (DE)
@image{html/images/vice-c128-positional-keymap-de-small}

@subsection C16 & Plus4 Keyboard Map

TODO

@subsection PET Graphics Keyboard Map

The PET2001 uses the original graphics keyboard made from "chiclet" keys:

@image{html/images/pet-chiclet-layout-small}

The 3032 and 4032 use "real" graphics keyboard, which is based on the same keyboard
matrix and looks like this:

@image{html/images/pet-graphical-layout-small}

For practical reasons, there is no extra keymap for the chiclet keyboard - any
attempt to somehow reproduce that would end up too similar to what we are using
now for the graphics keyboard anyway:

@subsubsection Symbolic (US)
@image{html/images/vice-pet-graphical-symbolic-keymap-us-small}
@subsubsection Positional (US)
@image{html/images/vice-pet-graphical-positional-keymap-us-small}

@subsubsection Symbolic (DE)
@image{html/images/vice-pet-graphical-symbolic-keymap-de-small}
@subsubsection Positional (DE)
@image{html/images/vice-pet-graphical-positional-keymap-de-small}

@subsection PET Business Keyboard Map

This Layout is used for the "big" PET models, like the 8032. The matrix is not
compatible to the graphics keyboard:

@image{html/images/pet-business-uk-layout-small}

@subsubsection Symbolic (US)
@image{html/images/vice-pet-business-uk-symbolic-keymap-us-small}
@subsubsection Positional (US)
@image{html/images/vice-pet-business-uk-positional-keymap-us-small}

@subsubsection Symbolic (DE)
@image{html/images/vice-pet-business-uk-symbolic-keymap-de-small}
@subsubsection Positional (DE)
@image{html/images/vice-pet-business-uk-positional-keymap-de-small}

@subsection CBM2 Keyboard Map

TODO


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

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 is configurable to your liking.

For some of the emulators there can be extra joysticks besides the built-in
joystick ports, the following list provides the mappings for the currently
supported joystick/joypad ports:

The internal joystick port 1 [x64/xscpu64/x64dtv/x128/xvic/xplus4/xcbm5x0] is mapped to joystick device #1.

The internal joystick port 2 [x64/xscpu64/x64dtv/x128/xplus4/xcbm5x0] is mapped to joystick device #2.

The CGA userport joystick adapter ports 1 and 2 (x64/xscpu64/x128/xvic/xpet/xcbm2) are mapped to extra joystick devices #1 & #2 respectively.

The PET userport joystick adapter ports 1 and 2 (x64/xscpu64/x128/xvic/xplus4/xpet/xcbm2) are mapped to extra joystick devices #1 & #2 respectively.

The C64DTV HUMMER userport joystick adapter port (x64/xscpu64/x128/xvic/xplus4/xpet/xcbm2) is mapped to extra joystick device #1.

The OEM userport joystick adapter port (x64/xscpu64/x128/xvic/xplus4/xpet/xcbm2) is mapped to extra joystick device #1.

The HIT userport joystick adapter ports 1 & 2 (x64/xscpu64/x128) are mapped to extra joystick devices #1 & #2 respectively.

The KingSoft userport joystick adapter ports 1 & 2 (x64/xscpu64/x128) are mapped to extra joystick devices #1 & #2 respectively.

The StarByte userport joystick adapter ports 1 & 2 (x64/xscpu64/x128) are mapped to extra joystick devices #1 & #2 respectively.

The Petscii userport SNES pad adapter port (x64/xscpu64/x128/xvic/xcbm2) is mapped to extra joystick device #1.

The Superpad64 userport SNES pad adapter ports 1, 2, 3, 4, 5, 6, 7 & 8 (x64/xscpu64/x128/xvic/xcbm2) are mapped to extra joystick devices #1, #2, #3, #4, #5, #6, #7 & #8 respectively.

The Inception joystick adapter ports 1, 2, 3, 4, 5, 6, 7 & 8 (x64/x64sc/xscpu64/x64dtv/x128/xcbm5x0/xvic) are mapped to extra joystick devices #1, #2, #3, #4, #5, #6, #7 & #8 respectively.

The MultiJoy joystick adapter ports 1, 2, 3, 4, 5, 6, 7 & 8 (x64/x64sc/xscpu64/x64dtv/x128/xcbm5x0) are mapped to extra joystick devices #1, #2, #3, #4, #5, #6, #7 & #8 respectively.

The SpaceBalls joystick adapter ports 1, 2, 3, 4, 5, 6, 7 & 8 (x64/x64sc/xscpu64/x64dtv/x128/xcbm5x0) are mapped to extra joystick devices #1, #2, #3, #4, #5, #6, #7 & #8 respectively.

The Ninja SNES pad adapter ports 1, 2 & 3 (x64/x64sc/xscpu64/x64dtv/x128/xcbm5x0/xplus4) are mapped to extra joystick devices #1, #2 & #3 respectively.

The Stupid Pet Tricks joystick adapter port (x64/x64sc/xscpu64/x128/xcbm2/xpet/xvic) is mapped to port extra joystick device #3. 

The ProtoPad SNES pad adapter port is mapped to the same port it is attached to.

The Trap-Them SNES pad adapter port is mapped to the same port it is attached to.

The MicroFlyte analog joystick is mapped to the same port it is attached to.

The SID cartridge joystick port (xplus4) is mapped to extra joystick device #4.

@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, 8250,
and D9090/60 drives in one of the following ways:

@itemize @bullet

@item
using disk images, i.e., files that contain a dump of all the blocks
contained in a real floppy disk;
@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.
@item
accessing a real device connected to the host machine. This works using the 
OpenCBM library. You can get it from @uref{https://spiro.trikaliotis.net/opencbm}.
Make sure to pick the right library (32 or 64bit) for your system. 
@itemize @bullet
@item To use it in the emulators, go to the drive tab in the settings and choose
"IEC Device" and "Real Drive (OpenCBM)". Note that this will not work with all
emulators right now.
@item If you want to use OpenCBM with c1541, start it with c1541 /dev/cbm (on Linux).
@end itemize

@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 access it is required to enable
this type of emulation.

The IEEE488 drives (2031, 2040, 3040, 4040, 1001, 8050, 8250, and D9090/60)
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 units 2040, 3040, 4040, 8050 and 8250 are Dual Drive
Floppy Disks.  This means that these devices handle two disks.
The drives are numbered 0 and 1.

The Commodore 2040, 3040, 4040, 1001, 8050, 8250, and D9090/60 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.

The D9090/60 is the only Commodore branded hard drive produced for
the PET series computers, and were often used by C64 and C128 users for
their significant storage capacity (29162/19441 free blocks).
Just like the other IEEE drives before it, it uses a separate
CPU as the FDC which in turn communicates with the SASI-to-ST506 bridge
(which is controlled by an AM2910). The hardware design is very similar
to the 8050/8250 drive.

Creative Micro Designs (CMD) produced the last drives for the
Commodore 8-bit systems. They first released the hard drive (HD) line,
and later the floppy drive (FD) line. The CMD HD series can support up
to 4 GiB HDs with 255 separate partitions, while the CMD FD series can
support up to 3.3 MB extended density floppy disks with 31 separate
partitions. The FD series are also backwards compatible with 1581
media. The DOS for the FD series is stored on a ROM (@code{dos2000}
and @code{dos4000}, the latest versions being 1.40).

The CMD HD uses a small boot ROM (@code{dosCMDHD}, the latest version
is 2.80) which loads the primary DOS (latest is 1.92) off the HD
itself. This allows for easy upgrades and expandability. This is also
the only drive to use the front panel buttons to control the mode of
the drive on reset. There are three modes of operation: normal,
configuration, and installation. VICE supports placing the drive in
either of these modes through the "Reset" sub-menu on the status bar
for the GTK3 interface, and the "Reset" menu in the SDL interface.
When creating a new DHD image, simply create an EMPTY file and VICE
will automatically place the drive in installation mode.
The DOS will detect the drive as the size specified by "Drive#FixedSize"
(or "-drive#fixedsize") which is 8GB by default.
To use a specific sized disk, set this value to the maximum size, or
set this value to "0" and set the image file on disk to the desired size
(it should be a multiple of 512 bytes).
Once the DOS is installed, the CMD "hd-tools" program can be used to
configure various settings and partition the drive; this is done in
configuration mode for safety.
When in either configuration or installation mode, the device number is
set to 30.
Therefore, it is not suggested to place two or more CMD HDs in either
of these modes on the same bus at the same time.
When migrating from real CMD hardware, use any HDD imaging software ("dd"
or GNU "ddrescue" on Linux) to copy the raw contents of a device to a file.
The destination file should have a "DHD" extension.
For those users with multiple disks, SCSI ID 0, LUN 0 should have the
extension "DHD", but any other drives should have ".S<ID><LUN>" where <ID>
is the SCSI ID and <LUN> is the LUN or logical unit.
Place all the files in the same folder when attaching to the "DHD" file.
The other files will automatically be scanned for and connected as well.
The CMD HD boot ROM is used for partition management, and ALL versions have
a known bug which corrupts data when deleting paritions across multiple
SCSI drives.
To avoid this scenario, it is highly suggested that another full DHD
image be created in VICE (on another unit) and all the files be copied
over from multi-disk configurations, using CMD "fcopy" for example, to
the new unit.
This will allow the user to take advantage of all the CMD HD features
without the potential for data loss.

@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} 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} lowlevel 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{D90} CBM D9090/60 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{DHD} CMD HD disk image format

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

@item
@code{TAP} lowlevel tape image files

@item
@code{P00} program files

@item
@code{CRT} C64 cartridge image files

@item
@code{TCRT} tapecart image files

@end itemize

A 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 deprecated 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::
* Video problems::
* Printer problems::
* PET keyboard problems::
@end menu

@node Sound problems, Video problems, Common problems, Common problems
@subsection Sound problems

VICE should compile and run without major problems on many systems,
but there are some known issues related to the sound driver.

If you are having sound problems, such as skipping, first monitor how much CPU
time the respective emulator is taking on your system. To run smoothly, on a
modern system, it should really never go over 50% or so, except for very short
peaks that should also stay well beyond 90%. If you see it takes more, try
disabling some of the most CPU intense features (disable CRT emulation, use
fastsid instead of reSID, disable true drive emulation).

If the CPU usage is ok, try using a different sound driver. You may also try
increasing the sound buffer size (although the default should be ok for modern
systems).

All platforms that can run the SDL port (like Amiga, BeOS, etc) should be able
to play sound via SDL.

@node Video problems, Printer problems , Sound problems, Common problems
@subsection Video problems

If you don't get video output, the problem may be that your system has no
suitable Open-GL driver - which is strictly required for the GTK3 port. Have
a look at the logfile to see if this is the problem.

@node Printer problems, PET keyboard problems ,Video 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 run them from a terminal window such as 
@code{xterm} or @code{rxvt}.  For example, you could do

@example
xterm -e x64sc
@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
@findex -help
@item -help
@findex -?
@itemx -?
List all the available command-line options and their meaning.

@findex -version
@item -version
Show the program name and version.

@findex -features
@item -features
List all compile time features

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

@findex -config
@item -config <filename>
Specify config file

@findex -addconfig
@item -addconfig <filename>
Specify extra config file for loading additional resources. This can be used to
add "patch sets" for various configurations.

@findex -dumpconfig
@item -dumpconfig <filename>
Write the complete config into file. Normally only resources that have been
changed from their default value would be written to the config file, however
with this option you can see all resources and their current values.

@findex -settings-node
@item -settings-node <path>
Activate settings dialog at node <path> after starting the emulator (Gtk3 only).
Meant for use during development, the <path> is string pointing to a node in the
settings tree (see src/arch/gtk3/uisettings.c).

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

@findex -verbose
@item -verbose
Enable verbose log output.

@findex -silent
@item -silent
Disable all log output (except errors).

@findex -seed
@item -seed <value>
Set the random seed (for debugging).

@findex -keybuf
@item -keybuf <string>
Put the specified string into the keyboard buffer.

@findex -console
@item -console
Console mode (for music playback, or for running the emulator test programs)

@findex -limitcycles
@item -limitcycles <cycles>
Automatically exit the emulator after a given number of cycles.

@findex -chdir
@item -chdir <directory>
Change the working directory.

@findex -autostart
@item -autostart <name>
Autostart <name> (@pxref{Command-line autostart}).

@findex -autoload
@item -autoload <name>
Attach and autoload tape/disk image <name>

@findex -1
@item -1 <Name>
Attach <Name> as a tape image file.
@findex -2
@item -2 <Name>
Attach <Name> as a tape image file for datasette #2 (PET)

@findex -8
@item -8 <Name>
@findex -9
@itemx -9 <Name>
@findex -10
@itemx -10 <Name>
@findex -11
@itemx -11 <Name>
Attach <Name> as a disk image to device 8, 9, 10 or 11.

@findex -8d1
@item -8d1 <Name>
@findex -9d1
@itemx -9d1 <Name>
@findex -10d1
@itemx -10d1 <Name>
@findex -11d1
@itemx -11d1 <Name>
Attach <Name> as a disk image to the second drive of a dual-drive 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{AttachDevice8d0Readonly=1}, @code{AttachDevice9d0Readonly=1}, @code{AttachDevice10d0Readonly=1}, @code{AttachDevice11d0Readonly=1})
(all emulators except vsid).

@findex -attach8d1ro
@findex -attach9d1ro
@findex -attach10d1ro
@findex -attach11d1ro
@item -attach8d1ro
@itemx -attach9d1ro
@itemx -attach10d1ro
@itemx -attach11d1ro
Attach disk image for second drive of a dual-drive #8-11 read only
(@code{AttachDevice8d1Readonly=1}, @code{AttachDevice9d1Readonly=1}, @code{AttachDevice10d1Readonly=1}, @code{AttachDevice11d1Readonly=1})
(all emulators except vsid).

@findex -attach8rw
@findex -attach9rw
@findex -attach10rw
@findex -attach11rw
@item -attach8rw
@itemx -attach9rw
@itemx -attach10rw
@itemx -attach11rw
Attach disk image for drive #8-11 read write (if possible)
(@code{AttachDevice8d0Readonly=0}, @code{AttachDevice9d0Readonly=0}, @code{AttachDevice10d0Readonly=0}, @code{AttachDevice11d0Readonly=0})
(all emulators except vsid).

@findex -attach8d1rw
@findex -attach9d1rw
@findex -attach10d1rw
@findex -attach11d1rw
@item -attach8d1rw
@itemx -attach9d1rw
@itemx -attach10d1rw
@itemx -attach11d1rw
Attach disk image for second drive of a dual-drive #8-11 read write (if possible)
(@code{AttachDevice8d1Readonly=0}, @code{AttachDevice9d1Readonly=0}, @code{AttachDevice10d1Readonly=0}, @code{AttachDevice11d1Readonly=0})
(all emulators except vsid).

@findex -exitscreenshot
@item -exitscreenshot <name>
Specify name of a screenshot file that will be written when the emulator exits.
(@code{ExitScreenshotName}).

@findex -exitscreenshotvicii
@item -exitscreenshotvicii <name>
Specify name of a screenshot file that will be written when the emulator exits.
(@code{ExitScreenshotName1}). (x128)

@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
x64sc lovelygame.d64
@end example

will start the C64 emulator, attaching @file{lovelygame.d64} 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
x64sc "lovelygame.d64:run me"
@end example

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

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

@example
x64sc -autostart "lovelygame.d64:run me"
@end example

Note that if you specify a raw CBM or P00 file, the emulator will load the file,
and after doing so revert all settings to what they were before autostarting.

If you want to allow the started program to access the host file system, you will
have to enable "virtual device traps". If you want the autostart logic to disable
true drive emulation temporarily to speed up the autostart, then enable "handle
TDE at autostart.

@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
$HOME/.local/share/vice/EMU:PREFIX/lib/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
$HOME/.local/share/vice/C64:/usr/local/lib/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{$HOME/.local/share/vice/C64}
@item
@code{/usr/local/lib/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.
* Gtk3 Hotkeys files::          Files defining Gtk3 UI hotkeys.
* Palette files::               Files defining the machine's colors.
* Romset files::                Files defining the machine's ROM set.
@end menu

@node ROM files, Keymap files, Gtk3 Hotkeys 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 KiB)

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

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

@end itemize

The C128 needs the following files:

@itemize @bullet

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

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

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

@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, as well as the CMD hard drive:

@itemize @bullet

@item
@file{dos1540-325302+3-01.bin}, the 1540 drive ROM (16 KiB)
(DOS 2.6 V170, Commodore ROM images 325302-01 and 325303-01)

@item
@file{dos1541-325302-01+901229-05.bin}, the 1541 drive ROM (16 KiB)
(DOS 2.6, Commodore ROM images 325302-01 and 901229-05.bin)

@item
@file{dos1541ii-251968-03.bin}, the 1541-II drive ROM (16 KiB)
(DOS 2.6, Commodore ROM image 251968-03)

@item
@file{dos1551-318008-01.bin}, the 1551 drive ROM (16 KiB)
(DOS 2.6 TDISK, Commodore ROM image 318008-01)

@item
@file{dos1570-315090-01.bin}, the 1570 drive ROM (32 KiB)
(DOS 3.0, Commodore ROM image 315090-01)

@item
@file{dos1571-310654-05.bin}, the 1571 drive ROM (32 KiB)
(DOS 3.0, Commodore ROM image 310654-05)

@item
@file{dos1571cr-318047-01.bin}, the 1571CR drive ROM (32 KiB)
(DOS 3.0, Commodore ROM image 318047-01)

@item
@file{dos1581-318045-02.bin}, the 1581 drive ROM (32 KiB)
(DOS 10, Commodore ROM image 318045-02)

@item
@file{dos2000-cs-33cc6f.bin}, the CMD FD-2000 drive ROM (32 KiB)
(CMD FD DOS 1.4, CMD ROM image cs-33cc6f)

@item
@file{dos4000-fd-350022.bin}, the CMD FD-4000 drive ROM (32 KiB)
(CMD FD DOS 1.4, CMD ROM image fd-350022.bin)

@item
@file{bootromCMDHD-v2-80.bin}, the CMD HD boot ROM (16 KiB)
(Boot ROM V2.80, CMD ROM image)

@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-901484-03+05.bin}, the 2031 drive ROM (16 KiB)
(DOS 2.6, Commodore ROM images 901484-03 and 901484-05)

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

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

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

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

@item
@file{dos9000-300516+7-revC.bin}, the D9090/60 drive ROM (16 KiB)
(DOS 3.0, Commodore ROM images 300516-RevC and 300517-RevC)

@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{kernal-1.901439-04-07.bin}, the PET2001 Kernal ROM (4 KiB)
(Commodore ROM images 901447-06 and 901447-07, same as 901439-04 and 901439-07)
@item
@file{kernal-2.901465-03.bin}, the PET3032 Kernal ROM (4 KiB)
(Commodore ROM image 901465-03)
@item
@file{kernal-4.901465-22.bin}, the PET4032/8032 Kernal ROM (4 KiB)
(Commodore ROM image 901465-22)

@item
@file{basic-1.901439-09-05-02-06.bin}, the PET2001 Basic 1 ROM (8 KiB)
(Commodore ROM images 901447-09, 901447-02, 901447-03, 901447-04.bin.
The -09 ROM is the revised -01 ROM.
Same as images 901439-09, 901439-05, 901439-02, 901439-06.
The -09 ROM is the revised -01 ROM)
@item
@file{basic-2.901465-01-02.bin}, the PET3032 Basic 2 ROM (8 KiB)
(Commodore ROM images 901465-01 and 901465-01)
@item
@file{basic-4.901465-23-20-21.bin}, the PET4032/8032 Basic 4 ROM (12 KiB)
(Commodore ROM images 901465-23, 901465-20 and 901465-21.
The -23 ROM is a revised -19 ROM)

@item
@file{edit-1-n.901439-03.bin}, the PET2001 editor for graphics keyboards (2 KiB)
(Commodore ROM image 901447-05, same as 901439-03)
@item
@file{edit-2-b.901474-01.bin}, the PET3032 editor for business keyboards (2 KiB)
(Commodore ROM image 901474-01)
@item
@file{edit-2-n.901447-24.bin}, the PET3032 editor for graphics keyboards (2 KiB)
(Commodore ROM image 901447-24)
@item
@file{edit-4-40-n-50Hz.901498-01.bi}, the PET4032 editor for graphics keyboards (2 KiB)
(Commodore ROM image 901498-01)
@item
@file{edit-4-40-b-50Hz.ts.bin}, the PET4032 editor for business keyboards (2 KiB)
(Said to be "901498-01 modified to use a business keyboard on a 50Hz 4032")

@item
@file{edit-4-80-b-50Hz.901474-04_.bin}, the PET8032 editor for business keyboards (2 KiB)
(Commodore ROM image 901474-04-?)

@item
@file{characters-1.901447-08.bin}, the character generator ROM (2KiB)
for the PET 2001.
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.
Compared to the character ROMs for later models, it has the upper case
and lower case letters swapped: to get lower case letters, you need to
use the shift key (so the basic abbreviation for "LIST" looks like "Li",
instead of "lI" for "list".
(Commodore ROM image 901447-08)

@item
@file{characters-2.901447-10.bin}, the character generator ROM (2KiB).
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 (2KiB). 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 (4KiB).
The first half is the same as @file{characters-2.901447-10.bin}, 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 for the 6809 CPU in the SuperPET.

@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 128KiB RAM version
(C610, C710, B128) uses one bank of 64KiB for the BASIC text and another
one for all the variables.  The 256KiB 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 larger 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 (8KiB) for the business machines (6xx/7xx)

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

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

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

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

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

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

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

@end itemize

The SCPU64 needs the following files:

@itemize @bullet

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

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

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

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

To find out the keycodes to use, incase you want to edit the keymaps yourself,
you can enable showing the keycodes in the status bar in the settings.

@subsection Comments

@itemize @bullet

@item
Any line starting with the @code{#} sign, is completely ignored.
@item
Any characters in "C-style" comments is ignored (/* this is a comment */).

@end itemize

When creating new keymaps, please copy over the usual set of leading comments
(have a look at the default US keymaps).

In particular each file at the very least should contain a line indicating what
type of mapping it is supposed to be, for what host layout, what emulator, and
which UI, like this:

@example
# Symbolic Mapping, US Layout, C64, GTK
@end example

@subsection Control commands

There are some special commands you can put into the keyboard file, these usually
appear at the beginning of the file, before any actual keycode definitions;
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{!INCLUDE} followed by "filename" reads (inserts) file as mapping file. This is useful
when adding local mappings to an otherwise generic file (so you dont have to
copy the while file, but just add/modify a few keys).

@item
@code{!UNDEF} followed by keysym removes keysym from mapping table.
@end itemize

@itemize @bullet
@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

@item
@code{!VSHIFT}, followed by a shiftkey (RSHIFT or LSHIFT), specify what key will
be used as a virtual shift key when the shift flag is set.

@item
@code{!SHIFTL}, followed by a shiftkey (RSHIFT or LSHIFT), specify what key will
be used as a virtual shift-lock key; for example, C64 default keymaps will specify
@example
!VSHIFT LSHIFT
!SHIFTL LSHIFT
@end example
@end itemize

For emulated keyboards that have only one shift key, set both @code{!LSHIFT} and @code{!RSHIFT}
 to the same row/col and use RSHIFT for @code{!VSHIFT} and @code{!SHIFTL}.

@itemize @bullet
@item
@code{!LCTRL}, followed by a row and a column value, specifiy where the left 
control key is located on the emulated keyboard.

@item
@code{!LCBM}, followed by a row and a column value, specifiy where the left 
CBM key is located on the emulated keyboard.

@item
@code{!VCTRL}, followed by a ctrlkey (LCTRL), specify what key will
be used as a virtual control key.

@item
@code{!VCBM}, followed by a cbmkey (LCBM), specify what key will
be used as a virtual CBM key.

@end itemize

For example, a C64 keymap would usually start with this block:

@example
!CLEAR
!LSHIFT 1 7
!RSHIFT 6 4
!VSHIFT RSHIFT
!SHIFTL LSHIFT
!LCBM 7 5
!VCBM LCBM
!LCTRL 7 2
!VCTRL LCTRL
@end example

When creating new keymaps, make sure to create the respective set of commands
first and make sure the row/column values are correct.

Before you fix the rest of your mapping, make sure to create mappings for all
modifier keys that relate to the used row/column pairs and update their
@code{SHIFTFLAG} accordingly. Getting those right is the key to making more
complex mappings possible later.

For a example a typical GTK C64 symbolic mapping would contain something like this:

@example
Shift_R         6 4 0x0004    /* right SHIFT -> right SHIFT */
Shift_L         1 7 0x0002    /* left SHIFT  -> left SHIFT */
Caps_Lock       1 7 0x0040    /* CAPS lock   -> SHIFT lock */
Tab             7 5 0x2008    /* TAB         -> CBM (can be combined with SHIFT) */
Control_L       7 2 0x4008    /* left CTRL   -> CTRL (can be combined with SHIFT) */
@end example

@subsection Key mappings

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

@example
KEYSYM ROW COLUMN SHIFTFLAG /* COMMENT */
@end example

Where:

@itemize @bullet

@item
@code{KEYSYM} identifying the keysym: In (GTK) it is a literal keyboard symbol
as a string (for example "space"), in (SDL) it is a numeric keycode (for example
"32").

You can use the "show keycodes in statusbar" feature to see what keysym is bound
to any key.

@item
@code{ROW} and @code{COLUMN} refer to the row and column of the emulated key on the
emulated keyboard - all existing keymaps have the respective keyboard matrix in
them in comments, have a look.

@item
The @code{SHIFTFLAG} controls various aspects of how a host key is mapped to the
emulated keyboard. For example you may want to artificially add or remove certain
modifiers to/from the emulated keypress.

@end itemize

A keymap is parsed line by line. More complex mappings can be created by mapping
the same key with different @code{SHIFTFLAG} to different emulated keys in multiple lines:

@itemize @bullet

@item
A key mapping is found when the key symbol matches

@item
and when none of the following reject conditions apply:

@multitable @columnfractions .1 .1 .4 .4
@item @b{Value}
@tab @b{Hex}
@tab @b{Description}
@tab @b{Action}
@item @code{0}
@tab @code{0x0000}
@tab The key is never shifted.
@tab If any SHIFT modifiers pressed, then reject key.
@item @code{8}
@tab @code{0x0008}
@tab The key can be (optionally) shifted by the user.
@tab If any SHIFT modifiers pressed on the host, and this flag @b{is not} set, then reject key.
@item @code{128}
@tab @code{0x0080}
@tab SHIFT modifier required on host.
@tab If SHIFT modifier(s) @b{not} pressed on the host, and this flag @b{is} set, then reject key.
@item @code{256}
@tab @code{0x0100}
@tab Key is used for an alternative keyboard mapping
@tab if no alternative mapping is enabled (eg C64 mode in x128), reject key.
@item @code{512}
@tab @code{0x0200}
@tab ALT-R (ALT-GR) modifier required on host.
@tab If ALT-R modifier @b{not} pressed on the host, and this flag @b{is} set, then reject key.
@item @code{1024}
@tab @code{0x0400}
@tab CTRL modifier required on host.
@tab If CTRL modifier @b{not} pressed on the host, and this flag @b{is} set, then reject key.
@end multitable

@item
If no reject condition was true then we found a possible match. If no other mapping
will be found, this is the one that will be used. We may or may not look for
another match, depending on:

@multitable @columnfractions .1 .1 .8
@item @b{Value}
@tab @b{Hex}
@tab @b{Description}
@item @code{32}
@tab @code{0x0020}
@tab Another definition for this keysym/scancode follows later in the file. If this flag @b{is not} set, stop looking for another match.
@end multitable

@item
Once a match was found, the virtual modifiers are applied:

@multitable @columnfractions .1 .1 .4 .4
@item @b{Value}
@tab @b{Hex}
@tab @b{Description}
@tab @b{Action}
@item @code{1}
@tab @code{0x0001}
@tab The key is shifted on the emulated keyboard
@tab virtual shift will be used when it is not shifted on the host keyboard.
@item @code{16}
@tab @code{0x0010}
@tab Deshift key for this keysym/scancode.
@tab When the key is pressed with shift on the host keyboard, shift will @b{not} be used on the emulated keyboard.
@item @code{2048}
@tab @code{0x0800}
@tab Key is combined with CBM for this keysym/scancode
@tab virtual CBM will be used when it is not combined with CBM via another mapped key.
@item @code{4096}
@tab @code{0x1000}
@tab Key is combined with CTRL for this keysym/scancode
@tab virtual CTRL will be used when it is not combined with CTRL via another mapped key.
@end multitable

@item
and last not least these are the flags left:

@multitable @columnfractions .1 .1 .8
@item @b{Value}
@tab @b{Hex}
@tab @b{Description}
@item @code{32768}
@tab @code{0x8000}
@tab Do @b{not} emulate a "locked" switch for this key. This can be useful when your host keyboard provides physical locking by itself. (currently works only for the C128 40/80 and CAPS-lock keys)
@end multitable

@end itemize

For example this is is from the SDL C64 symbolic DE mapping:

@example
# 32+1 not shifted on host, shifted on c64
60 5 7 0x0021          /*             < -> <            */
# 32+128 shifted on host, shifted on c64
60 5 4 0x00a0          /*             > -> >            */
# 512+16 alt-gr on host, deshift for c64
60 6 0 0x0210          /*        altr+< -> pound        */
@end example

@subsubsection Special Rows

Besides the keyboard matrix of the emulated keyboard, there are a bunch of
special keys available in the negative rows as below:

@multitable @columnfractions .1 .1 .8
@item @b{Row}
@tab @b{Column}
@tab @b{Description}
@item @code{-1}
@tab @code{n}
@tab Joystick keymap A, direction n
@item @code{-2}
@tab @code{n}
@tab Joystick keymap B, direction n
@item @code{-3}
@tab @code{0}
@tab First RESTORE key
@item @code{-3}
@tab @code{1}
@tab Second RESTORE key
@item @code{-4}
@tab @code{0}
@tab 40/80 column key (x128)
@item @code{-4}
@tab @code{1}
@tab CAPS (ASCII/DIN) key (x128)
@item @code{-5}
@tab @code{n}
@tab Joyport keypad, key n (not supported in x128)
@end multitable

For example, a lot of (GTK) keymaps would map RESTORE like this:

@example
# Restore key mapping
F12     -3 0
Page_Up -3 1
@end example

Joystick keymap direction column values for rows -1 and -2:

@multitable @columnfractions .2 .2 .2
@item
@tab
@tab
@item @b{6} (N/W)
@tab  @b{7} (North)
@tab  @b{8} (N/E)
@item @b{4} (West)
@tab  @b{0} (Fire)
@tab  @b{5} (East)
@item @b{1} (S/W)
@tab  @b{2} (South)
@tab  @b{3} (S/E)
@end multitable


Joyport keypad direction column values for row -5:

@multitable @columnfractions .1 .1 .1 .1 .1
@item
@tab
@tab
@tab
@tab
@item @b{0}
@tab  @b{1}
@tab  @b{2}
@tab  @b{3}
@tab  @b{4}
@item @b{5}
@tab  @b{6}
@tab  @b{7}
@tab  @b{8}
@tab  @b{9}
@item @b{10}
@tab  @b{11}
@tab  @b{12}
@tab  @b{13}
@tab  @b{14}
@item @b{15}
@tab  @b{16}
@tab  @b{17}
@tab  @b{18}
@tab  @b{19}
@end multitable

When a bigger spaced key is used, it uses the upper left most column value.

@subsubsection Modifier Flags

The @code{SHIFTFLAG} can have one of the following values. Flags can be combined by simply ORing (or adding) them together:

@multitable @columnfractions .1 .1 .8
@item @b{Value}
@tab @b{Hex}
@tab @b{Description}
@item @code{0}
@tab @code{0x0000}
@tab The key is never shifted.
@item @code{1}
@tab @code{0x0001}
@tab The key is shifted on the emulated keyboard, virtual shift will be used when  it is not shifted on the host keyboard.
@item @code{2}
@tab @code{0x0002}
@tab The key is the left shift key.
@item @code{4}
@tab @code{0x0004}
@tab The key is the right shift key. Use only this flag for emulated keyboards that have only one shift key.
@item @code{8}
@tab @code{0x0008}
@tab The key can be (optionally) shifted by the user.
@item @code{16}
@tab @code{0x0010}
@tab Deshift key for this keysym/scancode. That means when the key is pressed with shift on the host keyboard, shift will @b{not} be used on the emulated keyboard.
@item @code{32}
@tab @code{0x0020}
@tab Another definition for this keysym/scancode follows later in the file
@item @code{64}
@tab @code{0x0040}
@tab Key is SHIFT-lock on the emulated machine. Usually you'd use this for the CAPS lock key on the host keyboard.
@item @code{128}
@tab @code{0x0080}
@tab SHIFT modifier required on host.
@item @code{256}
@tab @code{0x0100}
@tab Key is used for an alternative keyboard mapping (e.g. C64 mode in x128). Note that @b{any alternative mappings must occur before the normal mappings for the same key/symbol in the file}.
@item @code{512}
@tab @code{0x0200}
@tab ALT-R (ALT-GR) modifier required on host.
@item @code{1024}
@tab @code{0x0400}
@tab CTRL modifier required on host.
@item @code{2048}
@tab @code{0x0800}
@tab Key is combined with CBM for this keysym/scancode.
@item @code{4096}
@tab @code{0x1000}
@tab Key is combined with CTRL for this keysym/scancode.
@item @code{8192}
@tab @code{0x2000}
@tab Key is (left) CBM on emulated machine.
@item @code{16384}
@tab @code{0x4000}
@tab Key is (left) CTRL on emulated machine.
@item @code{32768}
@tab @code{0x8000}
@tab Do @b{not} emulate a "locked" switch for this key. This can be useful when your host keyboard provides physical locking by itself. (currently works only for the C128 40/80 and CAPS-lock keys)
@end multitable

The @code{SHIFTFLAG} can be used to control various aspects of how the host key
will map to the emulated keyboard. For example it is useful if you want certain
keys to be ``artificially'' shifted by the emulator, and not by the user. Or the
other way around, a key can be ``deshifted''.

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. For example, a
typical C64 keymap would contain the following:

@example
F1 0 4 8        /* F1 -> F1 (+SHIFT allowed) */
F2 0 4 1        /* F2 -> F1 + SHIFT */
F3 0 5 8        /* F3 -> F3 (+SHIFT allowed) */
F4 0 5 1        /* F4 -> F3 + SHIFT */
F5 0 6 8        /* F5 -> F5 (+SHIFT allowed) */
F6 0 6 1        /* F6 -> F5 + SHIFT */
F7 0 3 8        /* F7 -> F7 (+SHIFT allowed) */
F8 0 3 1        /* F8 -> F7 + SHIFT */
@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.


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

@c FIXME @node
@subsection Romset command line options

@table @code

@findex -romsetfile
@item -romsetfile <File>
load the given romset file

@findex -romsetarchive
@item -romsetarchive <File>
load the given romset archive

@findex -romsetarchiveselect
@item -romsetarchiveselect <Item number>
select the given item from the current romset archive

@end table


@node Gtk3 Hotkeys files
@section Gtk3 Hotkeys files
@anchor{#gtk3-hotkeys-files}
The Gtk3 port of VICE allows setting custom keyboard shortcuts, which we
refer to as hotkeys. These hotkeys can be set either through the user
interface or by editing hotkeys files, which are stored either in the
VICE data directory or in the user's VICE configuration directory.

VICE's hotkeys files are read from VICE's data directory, which we'll
refer to as @code{$VICEDIR} and the (optional) user's hotkeys will be in
the user's VICE configuration directory, which we'll refer to as
@code{$USERDIR}.

On Unix, @code{$VICEDIR} will point to @code{/usr/local/share/vice/},
when using the default install prefix, and @code{$USERDIR} will point to
@code{$HOME/.config/vice/}. On Windows, @code{$VICEDIR} will point to
the root directory of the bindist and @code{$USERDIR} will point to
@code{%APPDATA%\vice}, which usually is
@code{C:\Users\%USERNAME%\AppData\Roaming\vice}.

A custom path can be specified by using the command line interface:
@code{x64sc -hotkeyfile <some-file>}, or by using the UI
(@strong{TODO}).

@menu
* Syntax of the hotkeys files::
@end menu

@node Syntax of the hotkeys files
@section Syntax of the hotkeys files
@anchor{#syntax-of-the-hotkeys-files}
The syntax of the hotkeys files is pretty straightforward, a file can
contain mappings, directives and comments. Leading and trailing
whitespace is ignored by the parser.

@menu
* Comments::
* Directives::
* Hotkey mappings::
* Syntax highlighting::
@end menu

@node Comments
@subsection Comments
@anchor{#comments}
Comments are started with either @code{;} or @code{#} and occupy the
rest of the line, they can also appear inline after a directive or
mapping.

For example:

@verbatim
# This is a comment

monitor-open    <Alt>h      # This is an inline comment
@end verbatim

@node Directives
@subsection Directives
@anchor{#directives}
Directives are special commands for the parser. They start with
@strong{@code{!}} and are case-insensitive.

@menu
* !CLEAR::
* !DEBUG::
* !INCLUDE::
* !UNDEF::
@end menu

@node !CLEAR
@subsubsection !CLEAR
@anchor{#clear}
Syntax
@quotation

@verbatim
!clear
@end verbatim

@end quotation
Clear all registered hotkeys. Best used as the first directive in the
(main) hotkeys file.

@node !DEBUG
@subsubsection !DEBUG
@anchor{#debug}
Syntax
@quotation

@verbatim
!debug <enable|disable|on|off>
@end verbatim

@end quotation
Enable or disable debugging messages via VICE's log system. Messages
will be prefixed with 'Hotkeys:'. Debugging is disabled by default.

@node !INCLUDE
@subsubsection !INCLUDE
@anchor{#include}
Syntax
@quotation

@verbatim
!include <file>
@end verbatim

@end quotation
Process @code{<file>} as if its contents were injected into the current
file being processed. This can be used recursively. The @code{<file>}
argument can be inside quotes (@code{"}) to be able to use paths or
filenames with spaces in them, and quotes inside quotes can be used by
escaping them with @code{\}, for example:
@code{!include "foo \"bar\".vhk"}.
Special variables
As mentioned before, a few special variables exist to use in the
argument to the @code{!include} directive: @code{$VICEDIR} and
@code{$USERDIR}. These can be used to avoid hardcoded, absolute paths.

For example:

@verbatim
!include "$VICEDIR/common/gtk3-hotkeys-drive.vhk"
@end verbatim

will include @code{/usr/local/share/vice/common/gtk3-hotkeys-drive.vhk},
assuming the default install prefix for VICE was used.

@node !UNDEF
@subsubsection !UNDEF
@anchor{#undef}
Syntax
@quotation

@verbatim
!undef [<modifier>..]<keyname>
@end verbatim

@end quotation
Remove a hotkey from whatever action it is mapped to.

For example:

@verbatim
!undef      <Alt>r      # Unmap Alt+r from 'restore display'
reset-soft  <Alt>r      # Map Alt+r to soft reset
@end verbatim

@node Hotkey mappings
@subsection Hotkey mappings
@anchor{#hotkey-mappings}

@menu
* Syntax::
@end menu

@node Syntax
@subsubsection Syntax
@anchor{#syntax-4}
@quotation

@verbatim
<action-name>   [<modifier>...]<keyname>
@end verbatim

@end quotation
Create a mapping of a hotkey to an action, where @code{<action-name>} is
a string refering to an operation triggered by a menu item -- such as
toggling Warp Mode, or attaching a disk to a drive -- followed by a
keyname, optionally prefixed with one or more modifiers.

For example:

@verbatim
monitor-open    <Alt>m
settings-open   KP_Divide       # map '/' on the keypad to the settings dialog
edit-paste      <Control><Alt>Insert
@end verbatim

The key names are case-sensitive and map directly to the symbolic
constants GDK uses, but without the leading @code{GDK_KEY_} component.
In the above example the string 'Insert' would map to
@code{GDK_KEY_Insert}.

For a list of available symbolic key names, see the @code{gdkkeysyms.h}
header of the GDK development headers. On a Debian system the file is
located at @code{/usr/include/gtk-3.0/gdk/gdkkeysyms.h}. It can also be
viewed online at
@uref{https://gitlab.gnome.org/GNOME/gtk/blob/master/gdk/gdkkeysyms.h,https://gitlab.gnome.org/GNOME/gtk/blob/master/gdk/gdkkeysyms.h}

@subsection List of modifiers
@multitable @columnfractions 0.33 0.33 0.33 
@headitem 
Windows/Unix
 @tab MacOS
 @tab GDK symbolic constant
@item 
@code{<Alt>}
 @tab @code{<Option>}
 @tab @code{GDK_MOD1_MASK}
@item 
@code{<Control>}
 @tab @code{<Command>}
 @tab @code{GDK_CONTROL_MASK}
@item 
@code{<Hyper>}
 @tab @code{GDK_HYPER_MASK}
@item 
@code{<Shift>}
 @tab @code{<Shift>}
 @tab @code{GDK_SHIFT_MASK}
@item 
@code{<Super>}
 @tab @code{<Super>}
 @tab @code{GDK_SUPER_MASK}
@end multitable

@quotation
Please be aware that some modifier+key combinations are either mapped to
the emulated machine's keyboard -- such as @code{<Control>1} being
mapped to CBM+1 when using a positional keymap -- or to the operating
system/window manager. Mappings using @code{<Alt>} or
@code{<Alt><Shift>} are usually fine.
@end quotation

@subsection List of action names
@multitable @columnfractions 0.5 0.5
@headitem name
 @tab description
@item 
@code{advance-frame}
 @tab Advance emulation one frame
@item 
@code{cart-attach}
 @tab Attach cartridge
@item 
@code{cart-detach}
 @tab Detach cartridge
@item 
@code{cart-freeze}
 @tab Press cartridge freeze button
@item 
@code{debug-autoplayback-frames}
 @tab Set autoplayback frames
@item 
@code{debug-core-dump-toggle}
 @tab Toggle saving core dump
@item 
@code{debug-trace-cpu-toggle}
 @tab Toggle CPU trace
@item 
@code{debug-trace-drive-10-toggle}
 @tab Toggle Drive 10 CPU trace
@item 
@code{debug-trace-drive-11-toggle}
 @tab Toggle Drive 11 CPU trace
@item 
@code{debug-trace-drive-8-toggle}
 @tab Toggle Drive 8 CPU trace
@item 
@code{debug-trace-drive-9-toggle}
 @tab Toggle Drive 9 CPU trace
@item 
@code{debug-trace-iec-toggle}
 @tab Toggle IEC bus trace
@item 
@code{drive-attach-8:1}
 @tab Attach disk to unit 8, drive 1
@item 
@code{drive-attach-9:0}
 @tab Attach disk to unit 9, drive 0
@item 
@code{drive-attach-9:1}
 @tab Attach disk to unit 9, drive 1
@item 
@code{drive-create}
 @tab Create and attach empty disk image
@item 
@code{drive-detach-10:0}
 @tab Detach disk from unit 10, drive 0
@item 
@code{drive-detach-10:1}
 @tab Detach disk from unit 10, drive 1
@item 
@code{drive-detach-11:0}
 @tab Detach disk from unit 11, drive 0
@item 
@code{drive-detach-11:1}
 @tab Detach disk from unit 11, drive 1
@item 
@code{drive-detach-8:0}
 @tab Detach disk from unit 8, drive 0
@item 
@code{drive-detach-8:1}
 @tab Detach disk from unit 8, drive 1
@item 
@code{drive-detach-9:0}
 @tab Detach disk from unit 9, drive 0
@item 
@code{drive-detach-9:1}
 @tab Detach disk from unit 9, drive 1
@item 
@code{drive-detach-all}
 @tab Detach all disks
@item 
@code{edit-copy}
 @tab Copy screen content to clipboard
@item 
@code{edit-paste}
 @tab Paste clipboard content into machine
@item
@code{fliplist-add-8:0}
 @tab Add current disk to fliplist of unit 8, drive 0
@item
@code{fliplist-add-8:1}
 @tab Add current disk to fliplist of unit 8, drive 1
@item
@code{fliplist-add-9:0}
 @tab Add current disk to fliplist of unit 9, drive 0
@item
@code{fliplist-add-9:1}
 @tab Add current disk to fliplist of unit 9, drive 1
@item
@code{fliplist-add-10:0}
 @tab Add current disk to fliplist of unit 10, drive 0
@item
@code{fliplist-add-10:1}
 @tab Add current disk to fliplist of unit 10, drive 1
@item
@code{fliplist-add-11:0}
 @tab Add current disk to fliplist of unit 11, drive 0
@item
@code{fliplist-add-11:1}
 @tab Add current disk to fliplist of unit 11, drive 1
@item
@code{fliplist-clear-8:0}
 @tab Clear fliplist of unit 8, drive 0
@item
@code{fliplist-clear-8:1}
 @tab Clear fliplist of unit 8, drive 1
@item
@code{fliplist-clear-9:0}
 @tab Clear fliplist of unit 9, drive 0
@item
@code{fliplist-clear-9:1}
 @tab Clear fliplist of unit 9, drive 1
@item
@code{fliplist-clear-10:0}
 @tab Clear fliplist of unit 10, drive 0
@item
@code{fliplist-clear-10:1}
 @tab Clear fliplist of unit 10, drive 1
@item
@code{fliplist-clear-11:0}
 @tab Clear fliplist of unit 11, drive 0
@item
@code{fliplist-clear-11:1}
 @tab Clear fliplist of unit 11, drive 1
@item
@code{fliplist-load-8:0}
 @tab Load fliplist for unit 8, drive 0
@item
@code{fliplist-load-8:1}
 @tab Load fliplist for unit 8, drive 1
@item
@code{fliplist-load-9:0}
 @tab Load fliplist for unit 9, drive 0
@item
@code{fliplist-load-9:1}
 @tab Load fliplist for unit 9, drive 1
@item
@code{fliplist-load-10:0}
 @tab Load fliplist for unit 10, drive 0
@item
@code{fliplist-load-10:1}
 @tab Load fliplist for unit 10, drive 1
@item
@code{fliplist-load-11:0}
 @tab Load fliplist for unit 11, drive 0
@item
@code{fliplist-load-11:1}
 @tab Load fliplist for unit 11, drive 1
@item
@code{fliplist-next-8:0}
 @tab Attach next disk in fliplist of unit 8, drive 0
@item
@code{fliplist-next-8:1}
 @tab Attach next disk in fliplist of unit 8, drive 1
@item
@code{fliplist-next-9:0}
 @tab Attach next disk in fliplist of unit 9, drive 0
@item
@code{fliplist-next-9:1}
 @tab Attach next disk in fliplist of unit 9, drive 1
@item
@code{fliplist-next-10:0}
 @tab Attach next disk in fliplist of unit 10, drive 0
@item
@code{fliplist-next-10:1}
 @tab Attach next disk in fliplist of unit 10, drive 1
@item
@code{fliplist-next-11:0}
 @tab Attach next disk in fliplist of unit 11, drive 0
@item
@code{fliplist-next-11:1}
 @tab Attach next disk in fliplist of unit 11, drive 1
@item
@code{fliplist-previous-8:0}
 @tab Attach previous disk in fliplist of unit 8, drive 0
@item
@code{fliplist-previous-8:1}
 @tab Attach previous disk in fliplist of unit 8, drive 1
@item
@code{fliplist-previous-9:0}
 @tab Attach previous disk in fliplist of unit 9, drive 0
@item
@code{fliplist-previous-9:1}
 @tab Attach previous disk in fliplist of unit 9, drive 1
@item
@code{fliplist-previous-10:0}
 @tab Attach previous disk in fliplist of unit 10, drive 0
@item
@code{fliplist-previous-10:1}
 @tab Attach previous disk in fliplist of unit 10, drive 1
@item
@code{fliplist-previous-11:0}
 @tab Attach previous disk in fliplist of unit 11, drive 0
@item
@code{fliplist-previous-11:1}
 @tab Attach previous disk in fliplist of unit 11, drive 1
@item
@code{fliplist-remove-8:0}
 @tab Remove current disk from fliplist of unit 8, drive 0
@item
@code{fliplist-remove-8:1}
 @tab Remove current disk from fliplist of unit 8, drive 1
@item
@code{fliplist-remove-9:0}
 @tab Remove current disk from fliplist of unit 9, drive 0
@item
@code{fliplist-remove-9:1}
 @tab Remove current disk from fliplist of unit 9, drive 1
@item
@code{fliplist-remove-10:0}
 @tab Remove current disk from fliplist of unit 10, drive 0
@item
@code{fliplist-remove-10:1}
 @tab Remove current disk from fliplist of unit 10, drive 1
@item
@code{fliplist-remove-11:0}
 @tab Remove current disk from fliplist of unit 11, drive 0
@item
@code{fliplist-remove-11:1}
 @tab Remove current disk from fliplist of unit 11, drive 1
@item
@code{fliplist-save-8:0}
 @tab Save fliplist of unit 8, drive 0
@item
@code{fliplist-save-8:1}
 @tab Save fliplist of unit 8, drive 1
@item
@code{fliplist-save-9:0}
 @tab Save fliplist of unit 9, drive 0
@item
@code{fliplist-save-9:1}
 @tab Save fliplist of unit 9, drive 1
@item
@code{fliplist-save-10:0}
 @tab Save fliplist of unit 10, drive 0
@item
@code{fliplist-save-10:1}
 @tab Save fliplist of unit 10, drive 1
@item
@code{fliplist-save-11:0}
 @tab Save fliplist of unit 11, drive 0
@item
@code{fliplist-save-11:1}
 @tab Save fliplist of unit 11, drive 1
@item
@code{fullscreen-decorations-toggle}
 @tab Show menu/status in fullscreen
@item 
@code{fullscreen-toggle}
 @tab Toggle fullscreen
@item 
@code{help-about}
 @tab Show about dialog
@item 
@code{help-command-line}
 @tab Command line options
@item 
@code{help-compile-time}
 @tab Compile time features
@item 
@code{help-hotkeys}
 @tab Hotkeys
@item 
@code{help-manual}
 @tab Browse VICE manual
@item 
@code{history-milestone-reset}
 @tab Return to recording milestone
@item 
@code{history-milestone-set}
 @tab Set recording milestone
@item 
@code{history-playback-start}
 @tab Start playing back events
@item 
@code{history-playback-stop}
 @tab Stop playing back events
@item 
@code{history-record-start}
 @tab Start recording events
@item 
@code{history-record-stop}
 @tab Stop recording events
@item 
@code{keyset-joystick-enable}
 @tab Allow keyset joystick
@item 
@code{media-record}
 @tab Record media
@item 
@code{media-stop}
 @tab Stop media recording
@item 
@code{monitor-open}
 @tab Open monitor
@item 
@code{mouse-grab-toggle}
 @tab Toggle Mouse Grab
@item 
@code{pause-toggle}
 @tab Toggle Pause
@item
@code{hotkeys-clear}
 @tab Clear all hotkeys
@item
@code{hotkeys-default}
 @tab Load default hotkeys
@item
@code{hotkeys-load}
 @tab Load hotkeys from current file
@item
@code{hotkeys-load-from}
 @tab Load hotkeys from custom file
@item
@code{hotkeys-save}
 @tab Save hotkeys to current file
@item
@code{hotkeys-save-to}
 @tab Save hotkeys to custom file
@item
@code{psid-load}
 @tab Load PSID file
@item
@code{psid-override-toggle}
 @tab Override PSID settings
@item
@code{psid-subtune-1}
 @tab Play PSID subtune #1
@item
@code{psid-subtune-2}
 @tab Play PSID subtune #2
@item
@code{psid-subtune-3}
 @tab Play PSID subtune #3
@item
@code{psid-subtune-4}
 @tab Play PSID subtune #4
@item
@code{psid-subtune-5}
 @tab Play PSID subtune #5
@item
@code{psid-subtune-6}
 @tab Play PSID subtune #6
@item
@code{psid-subtune-7}
 @tab Play PSID subtune #7
@item
@code{psid-subtune-8}
 @tab Play PSID subtune #8
@item
@code{psid-subtune-9}
 @tab Play PSID subtune #9
@item
@code{psid-subtune-10}
 @tab Play PSID subtune #10
@item
@code{psid-subtune-11}
 @tab Play PSID subtune #11
@item
@code{psid-subtune-12}
 @tab Play PSID subtune #12
@item
@code{psid-subtune-13}
 @tab Play PSID subtune #13
@item
@code{psid-subtune-14}
 @tab Play PSID subtune #14
@item
@code{psid-subtune-15}
 @tab Play PSID subtune #15
@item
@code{psid-subtune-16}
 @tab Play PSID subtune #16
@item
@code{psid-subtune-17}
 @tab Play PSID subtune #17
@item
@code{psid-subtune-18}
 @tab Play PSID subtune #18
@item
@code{psid-subtune-19}
 @tab Play PSID subtune #19
@item
@code{psid-subtune-20}
 @tab Play PSID subtune #20
@item
@code{psid-subtune-21}
 @tab Play PSID subtune #21
@item
@code{psid-subtune-22}
 @tab Play PSID subtune #22
@item
@code{psid-subtune-23}
 @tab Play PSID subtune #23
@item
@code{psid-subtune-24}
 @tab Play PSID subtune #24
@item
@code{psid-subtune-25}
 @tab Play PSID subtune #25
@item
@code{psid-subtune-26}
 @tab Play PSID subtune #26
@item
@code{psid-subtune-27}
 @tab Play PSID subtune #27
@item
@code{psid-subtune-28}
 @tab Play PSID subtune #28
@item
@code{psid-subtune-29}
 @tab Play PSID subtune #29
@item
@code{psid-subtune-30}
 @tab Play PSID subtune #30
@item
@code{psid-subtune-next}
 @tab Play next subtune
@item
@code{psid-subtune-previous}
 @tab Play previous subtune
@item
@code{psid-play}
 @tab Play
@item
@code{psid-pause}
 @tab Pause playback
@item
@code{psid-stop}
 @tab Stop playback
@item
@code{psid-ffwd}
 @tab Fast forward
@item
@code{psid-loop-toggle}
 @tab Toggle looping
@item
@code{psid-playlist-first}
 @tab Play first tune in the playlist
@item
@code{psid-playlist-previous}
 @tab Play previous tune in the playlist
@item
@code{psid-playlist-next}
 @tab Play next tune in the playlist
@item
@code{psid-playlist-last}
 @tab Play last tune in the playlist
@item
@code{psid-playlist-add}
 @tab Show dialog to add files to the playlist
@item
@code{psid-playlist-load}
 @tab Show dialog to load a platlist
@item
@code{psid-playlist-save}
 @tab Show dialog to save the playlist
@item
@code{psid-playlist-clear}
 @tab Clear the playlist
@item
@code{quit}
 @tab Quit emulator
@item 
@code{reset-drive-10}
 @tab Reset drive 10
@item 
@code{reset-drive-11}
 @tab Reset drive 11
@item 
@code{reset-drive-8}
 @tab Reset drive 8
@item 
@code{reset-drive-9}
 @tab Reset drive 9
@item 
@code{reset-hard}
 @tab Hard reset the machine
@item 
@code{reset-soft}
 @tab Soft reset the machine
@item 
@code{restore-display}
 @tab Resize application window to fit contents
@item 
@code{screenshot-quicksave}
 @tab Save screenshot in current working directory
@item 
@code{settings-default}
 @tab Restore default settings
@item 
@code{settings-dialog}
 @tab Open settings dialog
@item 
@code{settings-load}
 @tab Load settings
@item 
@code{settings-load-extra}
 @tab Load additional settings
@item 
@code{settings-load-from}
 @tab Load settings from alternate file
@item 
@code{settings-save}
 @tab Save settings
@item 
@code{settings-save-to}
 @tab Save settings to alternate file
@item 
@code{smart-attach}
 @tab Attach a medium to the emulator inspecting its type
@item 
@code{snapshot-load}
 @tab Load snapshot file
@item 
@code{snapshot-quickload}
 @tab Quickload snapshot
@item 
@code{snapshot-quicksave}
 @tab Quicksave snapshot
@item 
@code{snapshot-save}
 @tab Save snapshot file
@item 
@code{swap-controlport-toggle}
 @tab Swap controlport joysticks
@item 
@code{tape-attach-1}
 @tab Attach tape to datasette 1
@item 
@code{tape-attach-2}
 @tab Attach tape to datasette 2
@item 
@code{tape-create-1}
 @tab Create tape and attach to datasette 1
@item 
@code{tape-create-2}
 @tab Create tape and attach to datasette 2
@item 
@code{tape-detach-1}
 @tab Detach tape from datasette 1
@item 
@code{tape-detach-2}
 @tab Detach tape from datasette 2
@item 
@code{tape-ffwd-1}
 @tab Press FFWD on datasette 1
@item 
@code{tape-ffwd-2}
 @tab Press FFWD on datasette 2
@item 
@code{tape-play-1}
 @tab Press PLAY on datasette 1
@item 
@code{tape-play-2}
 @tab Press PLAY on datasette 2
@item 
@code{tape-record-1}
 @tab Press RECORD on datasette 1
@item 
@code{tape-record-2}
 @tab Press RECORD on datasette 2
@item 
@code{tape-reset-1}
 @tab Reset datasette 1
@item 
@code{tape-reset-1}
 @tab Reset datasette 2
@item 
@code{tape-reset-counter-1}
 @tab Reset datasette 1 counter
@item 
@code{tape-reset-counter-2}
 @tab Reset datasette 2 counter
@item 
@code{tape-rewind-1}
 @tab Press REWIND on datasette 1
@item 
@code{tape-rewind-2}
 @tab Press REWIND on datasette 2
@item 
@code{tape-stop-1}
 @tab Press STOP on datasette 1
@item 
@code{tape-stop-2}
 @tab Press STOP on datasette 2
@item 
@code{warp-mode-toggle}
 @tab Toggle Warp Mode
@end multitable

To see which emulators support which actions please look at
@code{doc/gtk3-hotkeys.md} or @code{src/arch/gtk3/uiactions.h}.

@node Syntax highlighting
@subsection Syntax highlighting
@anchor{#syntax-highlighting}
Vim syntax highlighting files can be found in doc/vim/. Currently there
are two files: @code{syntax/vhk.vim} and @code{ftdetect/vhk.vim}, these
can be copied to @code{$VIMFILES/} to enable hotkeys syntax highlighting
in Vim.




@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 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: most emulation settings can be changed in
the @dfn{options menu}. Additionally clicking on the various widgets in the
status bar gives access to related settings.
Settings can be saved and later used with the ``Save settings'' and ``Load settings'' 
menu items, respectively. Also by default, settings will get saved when exiting
the emulator. ``Restore default settings'' restores the factory defaults.
See @xref{Settings and resources} for more information about how settings
work in VICE.

A lot of settings and actions 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 (from the help
menu).  This will open either the PDF or popup a browser and open the HTML
version of the documentation.  

Notice that on Linux this requires VICE to be properly (and fully) installed,
eg with a @samp{make install}.

@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 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}, @code{G64}, @code{P64} for disk images
(devices 8, 9, 10 and 11) and @code{T64} and @code{TAP} for tape images.  

The ancient @code{X64} format is deprecated and subject for removal.

Notice that @code{T64} support is @emph{read-only}, and that the cassette is 
automatically rewound when you reach its end. Most importantly @code{T64} support
is only available via virtual device traps, which have to be permanently enabled
for multiload programs running from these containers. For actually emulating tape, the
@code{TAP} format is highly recommended.

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
* Autostart::                   Starting a program automagically.
* Compressed files::            Dealing with compressed files.
* Zipcode and Lynx::            Using Zipcoded ([1-4]!*) and Lynx files.
@end menu

@node Autostart, Compressed files, Disk and tape images, 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.

If true drive emulation is turned on, and the @dfn{Handle TDE at Autostart}
setting is enabled, true drive emulation 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, which is why
it is disabled by default.

@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 and for DOS at
@uref{http://infozip.sourceforge.net}. Don't use pkunzip
for DOS, it doesn't work. The programs to use BZip2 archives may be
found at @uref{https://sourceware.org/bzip2/}.
Just put the programs (@code{unzip.exe}, @code{gzip.exe}, @code{bzip2.exe}) into a directory
of your search path (e.g. @code{C:\DOS} or @code{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} 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{-unzip} 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.

@section Using printer emulation

@itemize @bullet
@item
Start the emulator (x64sc, for example) with default settings.
@item
go to "Preferences -> Peripheral devices -> Printer", select "Printer 4"
@item
Enable Virtual Device
@item
set "Printer Emulation" to "File system access".
@item
Print something, for example:
@example
open4,4
cmd4:list
print#4,"test":close4
@end example
@item
Close the emulator or disable printer emulation. This is needed to flush the data to the file.
@item
Have a look at the file print.dump in your VICE working directory with your favourite editor.
@end itemize

@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 file 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 the
@dfn{options} menu, via command-line options, using monitor commands, or via 
the @dfn{resource file}.

The @dfn{resource file} is a human-readable file containing resource
values: On windows systems it is called @file{vice.ini} and is usually stored
in the users roaming profile directory (something like 
@file{C:\Users\}<username>@file{\AppData\Roaming\vice}). Additionally the emulators
will look in the program directory at startup, and use @file{vice.ini} if it
exists there. On unix systems the resource file is called @file{vicerc} and is 
stored in the users config directory according to the XDG specification (usually
@file{/home/}<username>@file{/.config/vice/}). Additionally the emulators will look
if @file{.vicerc} exists in the users home directory, and use that if so.

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 save the current
(changed) settings before exiting, and can be toggled with the ``Save
settings on exit'' item from the options menu.

@c @menu
@c * Resource files::              Format of resource files.
@c * Resources and command-line::  Specifying settings from the
@c                                 command-line
@c 
@c * Performance settings::        Settings that affect speed of execution.
@c * Video settings::              Settings dealing with the video output.
@c * Keyboard settings::           Settings relative to the keyboard emulation.
@c * Control port settings::       Settings that control what device is emulated on available control ports.
@c * Sound settings::              Settings that control audio playback
@c * Drive settings::              Settings that control disk-drive emulation.
@c * Peripheral settings::         Settings for emulated external devices.
@c * RS232 settings::              Settings for the RS232 emulation.
@c * Ethernet settings::           Settings for the Ethernet emulation.
@c * Monitor settings::            Settings for the built-in monitor.
@c * Misc settings::               Other settings.
@c @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]
SaveResourcesOnExit=0
FileSystemDevice8=1
FSDevice8ConvertP00=1
FSDevice8Dir="/home/ettore/cbm/stuff/vic20p00"
FSDevice8SaveP00=1
FSDevice8HideCBMFiles=1
[C64]
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{-warp} enables initial warp mode, while @code{+warp}
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 from disk, else
use ,8,1 to load absolute.
(all emulators except vsid).

@vindex AutostartTapeBasicLoad
@item AutostartTapeBasicLoad
Boolean, if true load to basic start using ,1 when autostarting from tape, else
use ,1,1 to load absolute.
(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). This is disabled by default to ensure maximum
compatibility.

@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 (0-10 frames) random delay on autostart. This is added
to the @code{AutostartDelay}
(all emulators except vsid).

@vindex AutostartDelay
@item AutostartDelay
Integer specifying the delay in seconds required to wait for the kernal reset
routine before autostart. (0: use builtin value for standard kernal)
When tweaking this value start with 'large' values and then lower it, a value
that is too small results in autostart not happening.
(all emulators except vsid).
(0..1000)

@vindex AutostartOnDoubleClick
@item AutostartOnDoubleClick
Use autostart when double clicking on a file in the file list.
(only in the GTK3 GUI) (all emulators except vsid)

@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 from disk, load to BASIC start (without ',1')
(@code{AutostartBasicLoad=1})
(all emulators except vsid).
@item +basicload
On autostart from disk, load with ',1'
(@code{AutostartBasicLoad=0})
(all emulators except vsid).

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

@findex -autostarttapoffset
@item -autostarttapoffset <Offset>
Set initial offset in the .tap file (useful for emulator frontends)

@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 in seconds for the kernal reset
routine before autostart. (0: use builtin value for standard kernal).
When tweaking this value start with 'large' values and then lower it, a value
that is too small results in autostart not happening.
(@code{AutostartDelay})
(all emulators except vsid).
(0..1000)

@findex -autostart-on-doubleclick, +autostart-on-doubleclick
@item -autostart-on-doubleclick
@itemx +autostart-on-doubleclick
Enable/disable using autostart when double clicking on a file in the file list.
(@code{AutostartOnDoubleClick}) (only in the GTK3 GUI) (all emulators except vsid)


@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'' item in the speed setting.  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. A specific FPS may also be targeted.

@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 output
off and use a 1/10 refresh rate, so that it will run at the maximum
possible speed.

@c @menu
@c * Performance resources::
@c * Performance options::
@c @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 InitialWarpMode
@item InitialWarpMode
Booolean specifying whether ``warp mode'' is initially enabled.

@end table


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

@table @code

@findex -speed
@item -speed <value>
A positive <value> specifies the maximum speed as a percentage. A negative
<value> results in a target FPS of 0 - <value>
(@code{Speed}).

@findex -warp, +warp
@item -warp
@itemx +warp
Enable/Disable the initial warp mode.

@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 exist twice, once for each chip.

@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.  It also selects a more accurate CRT emulation
renderer with scanlines.

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

@end itemize

@node Keyboard settings, Control port 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 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


@c @menu
@c * Keyboard resources::
@c * Keyboard options::
@c @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.
(0: symbolic, 1: positional, 2: symbolic (user), 3: positional (user)).

@vindex KeymapSymFile
@item KeymapSymFile
String specifying the name of the keymap file for the symbolic mapping
(@pxref{Keyboard emulation}
(this will be set indirectly by changing @code{KeymapIndex},
@code{KeyboardMapping} or @code{KeyboardType}).

@vindex KeymapPosFile
@item KeymapPosFile
String specifying the name of the keymap file for the positional mapping
(@pxref{Keyboard emulation}
(this will be set indirectly by changing @code{KeymapIndex},
@code{KeyboardMapping} or @code{KeyboardType}).

@vindex KeymapUserSymFile
@item KeymapUserSymFile
String specifying the name of the user keymap file for symbolic mapping
(@pxref{Keyboard emulation}

@vindex KeymapUserPosFile
@item KeymapUserPosFile
String specifying the name of the user keymap file for positional mapping
(@pxref{Keyboard emulation}

@vindex KeyboardMapping
@item KeyboardMapping
Integer specifying the keyboard layout of the host.
(0: American 1: British 2: Danish 3: Dutch 4: Finnish 5: French 6: German 7: Italian
 8: Norwegian 9: Spanish 10: Swedish 11: Swiss 12: Turkish).

@vindex KeyboardType
@item KeyboardType
Integer specifying the emulated type of keyboard.
(machine specific, currently always 0 except for xpet: 0: Business (us)
1: Business (uk) 2: Business (de) 3: Business (jp) 4: Graphics (us)).

@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}
0: symbolic, 1: positional, 2: symbolic (user), 3: positional (user)).

@findex -symkeymap
@item -symkeymap <Name>
Specify filename of the symbolic user keymap file
(@code{KeymapUserSymFile}).

@findex -poskeymap
@item -poskeymap <Name>
Specify filename of the positional user keymap file
(@code{KeymapUserPosFile}).

@findex -keyboardmapping
@item -keyboardmapping <number>
Specifies the keyboard layout of the host
(@code{KeyboardMapping}
(0: American 1: British 2: Danish 3: Dutch 4: Finnish 5: French 6: German 7: Italian
 8: Norwegian 9: Spanish 10: Swedish 11: Swiss 12: Turkish).

@findex -keyboardtype
@item -keyboardtype <number>
Specifies the emulated type of keyboard
(@code{KeyboardType}
machine specific, currently always 0 except for xpet: 0: Business (us)
1: Business (uk) 2: Business (de) 3: Business (jp) 4: Graphics (us)).


@end table

@node Control port settings, Sound settings, Keyboard settings, Settings and resources

The control port settings submenu allows you to select which control
port device is connected to a control port.

@c @menu
@c * Control port resources::
@c * Control port options::
@c * Control port and devices::
@c @end menu

@node Control port resources, Control port options, Control port settings, Control port settings
@subsection Control port resources

@table @code

@vindex JoyPort1Device
@item JoyPort1Device
Set the device attached to:
control port 1 (x64, x64sc, x64dtv, xscpu64, x128, xcbm5x0, xplus4)
control port (xvic).
(@ref{Control port and devices}).

@vindex JoyPort2Device
@item JoyPort2Device
Set the device attached to:
control port 2 (x64, x64sc, x64dtv, xscpu64, x128, xcbm5x0, xplus4)
(@ref{Control port and devices}).

@vindex JoyPort3Device
@item JoyPort3Device
Set the device attached to:
joystick adapter port 1 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xpet, xvic, xplus4)
(@ref{Control port and devices}).

@vindex JoyPort4Device
@item JoyPort4Device
Set the device attached to:
joystick adapter port 2 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xpet, xvic, xplus4)
(@ref{Control port and devices}).

@vindex JoyPort5Device
@item JoyPort5Device
Set the device attached to:
joystick adapter port 3 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xpet, xvic, xplus4)
(@ref{Control port and devices}).

@vindex JoyPort6Device
@item JoyPort6Device
Set the device attached to:
joystick adapter port 4 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
Sid Cartridge on the Plus4 (xplus4)
(@ref{Control port and devices}).

@vindex JoyPort7Device
@item JoyPort7Device
Set the device attached to:
joystick adapter port 5 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
(@ref{Control port and devices}).

@vindex JoyPort8Device
@item JoyPort8Device
Set the device attached to:
joystick adapter port 6 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
(@ref{Control port and devices}).

@vindex JoyPort9Device
@item JoyPort9Device
Set the device attached to:
joystick adapter port 7 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
(@ref{Control port and devices}).

@vindex JoyPort10Device
@item JoyPort10Device
Set the device attached to:
joystick adapter port 8 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
(@ref{Control port and devices}).

@vindex BBRTCSave
@item BBRTCSave
Enable saving of the battery-backed real time clock data.

@end table

@node Control port options, Control port and devices, Control port resources, Control port settings
@subsection Control port command-line options

@table @code

@findex -controlport1device
@item -controlport1device <device>
Set the device attached to:
control port 1 (x64, x64sc, x64dtv, xscpu64, x128, xcbm5x0, xplus4)
control port (xvic)
(@code{JoyPort1Device})
(@ref{Control port and devices}).

@findex -controlport2device
@item -controlport2device <device>
Set the device attached to:
control port 2 (x64, x64sc, x64dtv, xscpu64, x128, xcbm5x0, xplus4)
(@code{JoyPort2Device})
(@ref{Control port and devices}).

@findex -controlport3device
@item -controlport3device <device>
Set the device attached to:
joystick adapter port 1 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xpet, xvic, xplus4)
(@code{JoyPort3Device})
(@ref{Control port and devices}).

@findex -controlport4device
@item -controlport4device <device>
Set the device attached to:
joystick adapter port 2 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xpet, xvic, xplus4)
(@code{JoyPort4Device})
(@ref{Control port and devices}).

@findex -controlport5device
@item -controlport5device <device>
Set the device attached to:
joystick adapter port 3 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xpet, xvic, xplus4)
(@code{JoyPort5Device})
(@ref{Control port and devices}).

@findex -controlport6device
@item -controlport6device <device>
Set the device attached to:
joystick adapter port 4 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
Sid Cartridge on the Plus4 (xplus4)
(@code{JoyPort6Device})
(@ref{Control port and devices}).

@findex -controlport7device
@item -controlport7device <device>
Set the device attached to:
joystick adapter port 5 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
(@code{JoyPort7Device})
(@ref{Control port and devices}).

@findex -controlport8device
@item -controlport8device <device>
Set the device attached to:
joystick adapter port 6 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
(@code{JoyPort8Device})
(@ref{Control port and devices}).

@findex -controlport9device
@item -controlport9device <device>
Set the device attached to:
joystick adapter port 7 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
(@code{JoyPort9Device})
(@ref{Control port and devices}).

@findex -controlport10device
@item -controlport10device <device>
Set the device attached to:
joystick adapter port 8 (x64, x64sc, xscpu64, x128, x64dtv, xcbm2, xcbm5x0, xvic)
(@code{JoyPort10Device})
(@ref{Control port and devices}).

@findex -bbrtcsave, +bbrtcsave
@item -bbrtcsave
@itemx +bbrtcsave
Enable/Disable saving of the battery-backed real time clock data
(@code{BBRTCSave}).

@end table

@node Control port and devices,  , Control port options, Control port settings
@subsection Control port and devices

x64/x64sc/xscpu64/x128 control ports and devices:

@multitable @columnfractions .05 .33 .05 .05 .05 .05 .05 .05 .05 .05 .05 .05
@headitem nr
@tab device
@tab N1
@tab N2
@tab E1
@tab E2
@tab E3
@tab E4
@tab E5
@tab E6
@tab E7
@tab E8
@item 0
@tab None
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 1
@tab Joystick
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 2
@tab Paddles
@tab X
@tab X
@item 3
@tab Mouse (1351)
@tab X
@tab X
@item 4
@tab Mouse (NEOS)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 5
@tab Mouse (AMIGA)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 6
@tab Trackball (CX22)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 7
@tab Mouse (ST)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 8
@tab Mouse (SmartMouse)
@tab X
@tab X
@item 9
@tab Mouse (Micromys)
@tab X
@tab X
@item 10
@tab KoalaPad
@tab X
@tab X
@item 11
@tab Lightpen (up trigger)
@tab X
@item 12
@tab Lightpen (left trigger)
@tab X
@item 13
@tab Lightpen (Datel)
@tab X
@item 14
@tab Lightgun (Magnum Phaser)
@tab X
@item 15
@tab Lightgun (Stack Rifle)
@tab X
@item 16
@tab Lightpen (Inkwell)
@tab X
@item 18
@tab Sampler (2bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 19
@tab Sampler (4bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 20
@tab RTC (BBRTC)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 21
@tab Dongle (Paperclip64)
@tab X
@tab X
@item 22
@tab Keypad (Coplin)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 23
@tab Keypad (Cardco)
@tab X
@tab X
@item 24
@tab Keypad (CX85)
@tab X
@tab X
@item 25
@tab Keypad (RushWare)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 26
@tab Keypad (CX21)
@tab X
@tab X
@item 27
@tab Dongle (Script 64)
@tab X
@tab X
@item 28
@tab Dongle (VizaWrite 64)
@tab X
@tab X
@item 29
@tab Dongle (WaaSoft)
@tab X
@tab X
@item 30
@tab SNES Pad (TrapThem)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 31
@tab SNES Pad (Ninja)
@tab X
@tab X
@item 32
@tab Spaceballs joy adapter
@tab X
@tab X
@item 33
@tab Inception joy adapter
@tab X
@tab X
@item 34
@tab MultiJoy adapter
@tab X
@tab X
@item 36
@tab ProtoPad
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 37
@tab I/O Simulation device
@tab X
@tab X
@item 38
@tab Microflyte joystick
@tab X
@tab X
@end multitable

x64dtv control ports and devices:

@multitable @columnfractions .05 .33 .05 .05 .05 .05 .05 .05 .05 .05 .05 .05
@headitem nr
@tab device
@tab N1
@tab N2
@tab E1
@tab E2
@tab E3
@tab E4
@tab E5
@tab E6
@tab E7
@tab E8
@item 0
@tab None
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 1
@tab Joystick
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 4
@tab Mouse (NEOS)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 5
@tab Mouse (AMIGA)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 6
@tab Trackball (CX22)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 7
@tab Mouse (ST)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 18
@tab Sampler (2bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 19
@tab Sampler (4bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 20
@tab RTC (BBRTC)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 21
@tab Dongle (Paperclip64)
@tab X
@tab X
@item 22
@tab Keypad (Coplin)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 25
@tab Keypad (RushWare)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 30
@tab SNES Pad (TrapThem)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 31
@tab SNES Pad (Ninja)
@tab X
@tab X
@item 33
@tab Inception joy adapter
@tab X
@tab X
@item 34
@tab MultiJoy adapter
@tab X
@tab X
@item 36
@tab ProtoPad
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 37
@tab I/O Simulation device
@tab X
@tab X
@end multitable

xcbm2 can handle the following devices on all control ports:

@multitable @columnfractions .05 .33
@headitem nr
@tab device
@item 0
@tab None
@item 1
@tab Joystick
@item 4
@tab Mouse (NEOS)
@item 5
@tab Mouse (AMIGA)
@item 6
@tab Trackball (CX22)
@item 7
@tab Mouse (ST)
@item 18
@tab Sampler (2bit)
@item 19
@tab Sampler (4bit)
@item 20
@tab RTC (BBRTC)
@end multitable

xcbm5x0 control ports and devices:

@multitable @columnfractions .05 .33 .05 .05 .05 .05 .05 .05 .05 .05 .05 .05
@headitem nr
@tab device
@tab N1
@tab N2
@tab E1
@tab E2
@tab E3
@tab E4
@tab E5
@tab E6
@tab E7
@tab E8
@item 0
@tab None
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 1
@tab Joystick
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 2
@tab Paddles
@tab X
@tab X
@item 3
@tab Mouse (1351)
@tab X
@tab X
@item 4
@tab Mouse (NEOS)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 5
@tab Mouse (AMIGA)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 6
@tab Trackball (CX22)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 7
@tab Mouse (ST)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 8
@tab Mouse (SmartMouse)
@tab X
@tab X
@item 9
@tab Mouse (Micromys)
@tab X
@tab X
@item 10
@tab KoalaPad
@tab X
@tab X
@item 18
@tab Sampler (2bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 19
@tab Sampler (4bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 20
@tab RTC (BBRTC)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 30
@tab SNES Pad (TrapThem)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 31
@tab SNES Pad (Ninja)
@tab X
@tab X
@item 33
@tab Inception joy adapter
@tab X
@tab X
@item 34
@tab MultiJoy adapter
@tab X
@tab X
@item 36
@tab ProtoPad
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 37
@tab I/O Simulation device
@tab X
@tab X
@item 38
@tab Microflyte joystick
@tab X
@tab X
@end multitable

xpet can handle the following devices on all control ports:

@multitable @columnfractions .05 .33
@headitem nr
@tab device
@item 0
@tab None
@item 1
@tab Joystick
@item 4
@tab Mouse (NEOS)
@item 5
@tab Mouse (AMIGA)
@item 6
@tab Trackball (CX22)
@item 7
@tab Mouse (ST)
@item 18
@tab Sampler (2bit)
@item 19
@tab Sampler (4bit)
@item 20
@tab RTC (BBRTC)
@end multitable

xplus4 control ports and devices:

@multitable @columnfractions .05 .33 .05 .05 .05 .05
@headitem nr
@tab device
@tab N1
@tab N2
@tab E1
@tab E2
@tab E3
@tab SC
@item 0
@tab None
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 1
@tab Joystick
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 2
@tab Paddles
@tab
@tab
@tab
@tab
@tab
@tab X
@item 3
@tab Mouse (1351)
@tab
@tab
@tab
@tab
@tab
@tab X
@item 4
@tab Mouse (NEOS)
@tab
@tab
@tab
@tab
@tab
@tab X
@item 5
@tab Mouse (AMIGA)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 6
@tab Trackball (CX22)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 7
@tab Mouse (ST)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 8
@tab Mouse (SmartMouse)
@tab
@tab
@tab
@tab
@tab
@tab X
@item 9
@tab Mouse (Micromys)
@tab
@tab
@tab
@tab
@tab
@tab X
@item 10
@tab KoalaPad
@tab
@tab
@tab
@tab
@tab
@tab X
@item 18
@tab Sampler (2bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 19
@tab Sampler (4bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 20
@tab RTC (BBRTC)
@tab
@tab
@tab
@tab
@tab
@tab X
@item 22
@tab Keypad (Coplin)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 23
@tab Keypad (Cardco)
@tab
@tab
@tab
@tab
@tab
@tab X
@item 24
@tab Keypad (CX85)
@tab
@tab
@tab
@tab
@tab
@tab X
@item 25
@tab Keypad (RushWare)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 26
@tab Keypad (CX21)
@tab
@tab
@tab
@tab
@tab
@tab X
@item 30
@tab SNES Pad (TrapThem)
@tab
@tab
@tab
@tab
@tab
@tab X
@item 36
@tab ProtoPad
@tab
@tab
@tab
@tab
@tab
@tab X
@item 37
@tab I/O Simulation device
@tab X
@tab X
@item 38
@tab Microflyte joystick
@tab
@tab
@tab
@tab
@tab
@tab X
@end multitable

xvic control ports and devices:

@multitable @columnfractions .05 .33 .05 .05 .05 .05 .05 .05 .05 .05 .05
@headitem nr
@tab device
@tab N1
@tab E1
@tab E2
@tab E3
@tab E4
@tab E5
@tab E6
@tab E7
@tab E8
@item 0
@tab None
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 1
@tab Joystick
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 2
@tab Paddles
@tab X
@item 3
@tab Mouse (1351)
@tab X
@item 4
@tab Mouse (NEOS)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 5
@tab Mouse (AMIGA)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 6
@tab Trackball (CX22)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 7
@tab Mouse (ST)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 8
@tab Mouse (SmartMouse)
@tab X
@item 9
@tab Mouse (Micromys)
@tab X
@item 10
@tab KoalaPad
@tab X
@item 11
@tab Lightpen (up trigger)
@tab X
@item 12
@tab Lightpen (left trigger)
@tab X
@item 13
@tab Lightpen (Datel)
@tab X
@item 14
@tab Lightgun (Magnum Phaser)
@tab X
@item 15
@tab Lightgun (Stack Rifle)
@tab X
@item 16
@tab Lightpen (Inkwell)
@tab X
@item 18
@tab Sampler (2bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 19
@tab Sampler (4bit)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 20
@tab RTC (BBRTC)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 22
@tab Keypad (Coplin)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 23
@tab Keypad (Cardco)
@tab X
@item 24
@tab Keypad (CX85)
@tab X
@item 25
@tab Keypad (RushWare)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 26
@tab Keypad (CX21)
@tab X
@item 30
@tab SNES Pad (TrapThem)
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 31
@tab SNES Pad (Ninja)
@tab X
@item 32
@tab Spaceballs joy adapter
@tab X
@item 33
@tab Inception joy adapter
@tab X
@item 36
@tab ProtoPad
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@tab X
@item 37
@tab I/O Simulation device
@tab X
@item 38
@tab Microflyte joystick
@tab X
@end multitable

Meaning of abreviations used in the tables above:

@multitable @columnfractions .05 .33
@headitem abr
@tab meaning
@item N1
@tab Native control port 1
@item N2
@tab Native control port 2
@item E1
@tab Joystick adapter port 1
@item E2
@tab Joystick adapter port 2
@item E3
@tab Joystick adapter port 3
@item E4
@tab Joystick adapter port 4
@item E5
@tab Joystick adapter port 5
@item E6
@tab Joystick adapter port 6
@item E7
@tab Joystick adapter port 7
@item E8
@tab Joystick adapter port 8
@item SC
@tab xplus4 SidCart joystick port
@end multitable

@c @node FIXME
@section Joystick settings

@c @node FIXME
@subsection Joystick resources

@table @code

@vindex JoyDevice1
@vindex JoyDevice2
@vindex JoyDevice3
@vindex JoyDevice4
@vindex JoyDevice5
@vindex JoyDevice6
@vindex JoyDevice7
@vindex JoyDevice8
@vindex JoyDevice9
@vindex JoyDevice10
@item JoyDevice1
@itemx JoyDevice2
@itemx JoyDevice3
@itemx JoyDevice4
@itemx JoyDevice5
@itemx JoyDevice6
@itemx JoyDevice7
@itemx JoyDevice8
@itemx JoyDevice9
@itemx JoyDevice10
Integer specifying which joystick device the emulator should use for
joystick emulation for ports 1 - 10, 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 JoyStick1AutoFire
@vindex JoyStick2AutoFire
@vindex JoyStick3AutoFire
@vindex JoyStick4AutoFire
@vindex JoyStick5AutoFire
@vindex JoyStick6AutoFire
@vindex JoyStick7AutoFire
@vindex JoyStick8AutoFire
@vindex JoyStick9AutoFire
@vindex JoyStick10AutoFire
@item JoyStick1AutoFire
@itemx JoyStick2AutoFire
@itemx JoyStick3AutoFire
@itemx JoyStick4AutoFire
@itemx JoyStick5AutoFire
@itemx JoyStick6AutoFire
@itemx JoyStick7AutoFire
@itemx JoyStick8AutoFire
@itemx JoyStick9AutoFire
@itemx JoyStick10AutoFire
Boolean, enables autofire for joystick emulation for ports 1 - 10, respectively.
(0=Off, 1=On)

@vindex JoyStick1AutoFireMode
@vindex JoyStick2AutoFireMode
@vindex JoyStick3AutoFireMode
@vindex JoyStick4AutoFireMode
@vindex JoyStick5AutoFireMode
@vindex JoyStick6AutoFireMode
@vindex JoyStick7AutoFireMode
@vindex JoyStick8AutoFireMode
@vindex JoyStick9AutoFireMode
@vindex JoyStick10AutoFireMode
@item JoyStick1AutoFireMode
@itemx JoyStick2AutoFireMode
@itemx JoyStick3AutoFireMode
@itemx JoyStick4AutoFireMode
@itemx JoyStick5AutoFireMode
@itemx JoyStick6AutoFireMode
@itemx JoyStick7AutoFireMode
@itemx JoyStick8AutoFireMode
@itemx JoyStick9AutoFireMode
@itemx JoyStick10AutoFireMode
Integer specifying the autofire mode to be used for for joystick emulation for ports 1 - 10, respectively.
(0=Autofire when fire is pressed, 1=Permanent autofire except when fire is pressed)

@vindex JoyStick1AutoFireSpeed
@vindex JoyStick2AutoFireSpeed
@vindex JoyStick3AutoFireSpeed
@vindex JoyStick4AutoFireSpeed
@vindex JoyStick5AutoFireSpeed
@vindex JoyStick6AutoFireSpeed
@vindex JoyStick7AutoFireSpeed
@vindex JoyStick8AutoFireSpeed
@vindex JoyStick9AutoFireSpeed
@vindex JoyStick10AutoFireSpeed
@item JoyStick1AutoFireSpeed
@itemx JoyStick2AutoFireSpeed
@itemx JoyStick3AutoFireSpeed
@itemx JoyStick4AutoFireSpeed
@itemx JoyStick5AutoFireSpeed
@itemx JoyStick6AutoFireSpeed
@itemx JoyStick7AutoFireSpeed
@itemx JoyStick8AutoFireSpeed
@itemx JoyStick9AutoFireSpeed
@itemx JoyStick10AutoFireSpeed
Integer specifying the amount of fire button presses per second for autofire for joystick emulation for ports 1 - 10, respectively.
(1-255)

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

@vindex Mouse
@item Mouse
Boolean, enables mouse emulation

@vindex SmartMouseRTCSave
@item SmartMouseRTCSave
Boolean, specified whether to save real time clock data for the SmartMouse

@vindex PaddlesInput1
@item PaddlesInput1
Integer speciftying the host input for the potentiometers of joystick port 1
(all emulators except xcbm2 and xpet)
(0: Mouse, 1: Joystick axis)

@vindex PaddlesInput2
@item PaddlesInput2
Integer speciftying the host input for the potentiometers of joystick port 2
(all emulators except xcbm2, xplus4 and xvic)
(0: Mouse, 1: Joystick axis)

@vindex KeySet1NorthWest
@vindex KeySet1North
@vindex KeySet1NorthEast
@vindex KeySet1East
@vindex KeySet1SouthEast
@vindex KeySet1South
@vindex KeySet1SouthWest
@vindex KeySet1West
@vindex KeySet1Fire
@vindex KeySet1Fire2
@vindex KeySet1Fire3
@vindex KeySet1Fire4
@vindex KeySet1Fire5
@vindex KeySet1Fire6
@vindex KeySet1Fire7
@vindex KeySet1Fire8
@item KeySet1NorthWest
@itemx KeySet1North
@itemx KeySet1NorthEast
@itemx KeySet1East
@itemx KeySet1SouthEast
@itemx KeySet1South
@itemx KeySet1SouthWest
@itemx KeySet1West
@itemx KeySet1Fire
@itemx KeySet1Fire2
@itemx KeySet1Fire3
@itemx KeySet1Fire4
@itemx KeySet1Fire5
@itemx KeySet1Fire6
@itemx KeySet1Fire7
@itemx KeySet1Fire8
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
@vindex KeySet2Fire2
@vindex KeySet2Fire3
@vindex KeySet2Fire4
@vindex KeySet2Fire5
@vindex KeySet2Fire6
@vindex KeySet2Fire7
@vindex KeySet2Fire8
@item KeySet2NorthWest
@itemx KeySet2North
@itemx KeySet2NorthEast
@itemx KeySet2East
@itemx KeySet2SouthEast
@itemx KeySet2South
@itemx KeySet2SouthWest
@itemx KeySet2West
@itemx KeySet2Fire
@itemx KeySet2Fire2
@itemx KeySet2Fire3
@itemx KeySet2Fire4
@itemx KeySet2Fire5
@itemx KeySet2Fire6
@itemx KeySet2Fire7
@itemx KeySet2Fire8
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

@findex -joydev1
@findex -joydev2
@item -joydev1 <range>
@itemx -joydev2 <range>
Set the device for joystick emulation of port 1 and 2, respectively.
(@code{JoyDevice1}, @code{JoyDevice2}).
@findex -extrajoydev1
@findex -extrajoydev2
@findex -extrajoydev3
@findex -extrajoydev4
@findex -extrajoydev5
@findex -extrajoydev6
@findex -extrajoydev7
@findex -extrajoydev8
@item -extrajoydev1 <0-8>
@itemx -extrajoydev2 <0-8>
@itemx -extrajoydev3 <0-8>
@itemx -extrajoydev4 <0-8>
@itemx -extrajoydev5 <0-8>
@itemx -extrajoydev6 <0-8>
@itemx -extrajoydev7 <0-8>
@itemx -extrajoydev8 <0-8>
Set device for extra joystick port 1, 2, 3, 4, 5, 6, 7 and 8.
(@code{JoyDevice3}, @code{JoyDevice4}, @code{JoyDevice5}, @code{JoyDevice6}, @code{JoyDevice7}, @code{JoyDevice8}, @code{JoyDevice9}, @code{JoyDevice10}).

@findex -joystick1autofire, +joystick1autofire
@item -joystick1autofire
@itemx +joystick1autofire
Enable/disable autofire for native joystick port 1
(@code{JoyStick1AutoFire=1}, @code{JoyStick1AutoFire=0}).
(all emulators except xcbm2, xpet and vsid)

@findex -joystick2autofire, +joystick2autofire
@item -joystick2autofire
@itemx +joystick2autofire
Enable/disable autofire for native joystick port 2
(@code{JoyStick2AutoFire=1}, @code{JoyStick2AutoFire=0}).
(all emulators except xcbm2, xpet, xvic and vsid)

@findex -extrajoystick1autofire, +extrajoystick1autofire
@item -extrajoystick1autofire
@itemx +extrajoystick1autofire
Enable/disable autofire for joystick adapter port 1
(@code{JoyStick3AutoFire=1}, @code{JoyStick3AutoFire=0}).
(all emulators except vsid)

@findex -extrajoystick2autofire, +extrajoystick2autofire
@item -extrajoystick2autofire
@itemx +extrajoystick2autofire
Enable/disable autofire for joystick adapter port 2
(@code{JoyStick4AutoFire=1}, @code{JoyStick4AutoFire=0}).
(all emulators except vsid)

@findex -extrajoystick3autofire, +extrajoystick3autofire
@item -extrajoystick3autofire
@itemx +extrajoystick3autofire
Enable/disable autofire for joystick adapter port 3 or plus4 sidcard joystick port
(@code{JoyStick5AutoFire=1}, @code{JoyStick5AutoFire=0}).
(all emulators except xpet and vsid)

@findex -extrajoystick4autofire, +extrajoystick4autofire
@item -extrajoystick4autofire
@itemx +extrajoystick4autofire
Enable/disable autofire for joystick adapter port 4
(@code{JoyStick6AutoFire=1}, @code{JoyStick6AutoFire=0}).
(all emulators except xpet, xplus4 and vsid)

@findex -extrajoystick5autofire, +extrajoystick5autofire
@item -extrajoystick5autofire
@itemx +extrajoystick5autofire
Enable/disable autofire for joystick adapter port 5
(@code{JoyStick7AutoFire=1}, @code{JoyStick7AutoFire=0}).
(all emulators except xpet, xplus4 and vsid)

@findex -extrajoystick6autofire, +extrajoystick6autofire
@item -extrajoystick6autofire
@itemx +extrajoystick6autofire
Enable/disable autofire for joystick adapter port 6
(@code{JoyStick8AutoFire=1}, @code{JoyStick8AutoFire=0}).
(all emulators except xpet, xplus4 and vsid)

@findex -extrajoystick7autofire, +extrajoystick7autofire
@item -extrajoystick7autofire
@itemx +extrajoystick7autofire
Enable/disable autofire for joystick adapter port 7
(@code{JoyStick9AutoFire=1}, @code{JoyStick9AutoFire=0}).
(all emulators except xpet, xplus4 and vsid)

@findex -extrajoystick8autofire, +extrajoystick8autofire
@item -extrajoystick8autofire
@itemx +extrajoystick8autofire
Enable/disable autofire for joystick adapter port 8
(@code{JoyStick10AutoFire=1}, @code{JoyStick10AutoFire=0}).
(all emulators except xpet, xplus4 and vsid)

@findex -joystick1autofiremode
@item -joystick1autofiremode <Mode>
Set autofire mode for native joystick port 1
(@code{JoyStick1AutoFireMode})
(all emulators except xcbm2, xpet and vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -joystick2autofiremode
@item -joystick2autofiremode <Mode>
Set autofire mode for native joystick port 2
(@code{JoyStick2AutoFireMode})
(all emulators except xcbm2, xpet, xvic and vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -extrajoystick1autofiremode
@item -extrajoystick1autofiremode <Mode>
Set autofire mode for joystick adapter port 1
(@code{JoyStick3AutoFireMode})
(all emulators except vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -extrajoystick2autofiremode
@item -extrajoystick2autofiremode <Mode>
Set autofire mode for joystick adapter port 2
(@code{JoyStick4AutoFireMode})
(all emulators except vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -extrajoystick3autofiremode
@item -extrajoystick3autofiremode <Mode>
Set autofire mode for joystick adapter port 3 or plus4 sidcard joystick port
(@code{JoyStick5AutoFireMode})
(all emulators except xpet and vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -extrajoystick4autofiremode
@item -extrajoystick4autofiremode <Mode>
Set autofire mode for joystick adapter port 4
(@code{JoyStick6AutoFireMode})
(all emulators except xpet, xplus4 and vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -extrajoystick5autofiremode
@item -extrajoystick5autofiremode <Mode>
Set autofire mode for joystick adapter port 5
(@code{JoyStick7AutoFireMode})
(all emulators except xpet, xplus4 and vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -extrajoystick6autofiremode
@item -extrajoystick6autofiremode <Mode>
Set autofire mode for joystick adapter port 6
(@code{JoyStick8AutoFireMode})
(all emulators except xpet, xplus4 and vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -extrajoystick7autofiremode
@item -extrajoystick7autofiremode <Mode>
Set autofire mode for joystick adapter port 7
(@code{JoyStick9AutoFireMode})
(all emulators except xpet, xplus4 and vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -extrajoystick8autofiremode
@item -extrajoystick8autofiremode <Mode>
Set autofire mode for joystick adapter port 8
(@code{JoyStick10AutoFireMode})
(all emulators except xpet, xplus4 and vsid).
(0: Autofire when fire is pressed, 1: Permanent autofire except when fire is pressed)

@findex -joystick1autofirespeed
@findex -joystick2autofirespeed
@item -joystick1autofirespeed <1-255>
@itemx -joystick2autofirespeed <1-255>
Set the amount of presses per second for autofire for joystick emulation of port 1 and 2, respectively.
(@code{JoyStick1AutoFireSpeed}, @code{JoyStick2AutoFireSpeed}).
@findex -extrajoystick1autofirespeed
@findex -extrajoystick2autofirespeed
@findex -extrajoystick3autofirespeed
@findex -extrajoystick4autofirespeed
@findex -extrajoystick5autofirespeed
@findex -extrajoystick6autofirespeed
@findex -extrajoystick7autofirespeed
@findex -extrajoystick8autofirespeed
@item -extrajoystick1autofirespeed <1-255>
@itemx -extrajoystick2autofirespeed <1-255>
@itemx -extrajoystick3autofirespeed <1-255>
@itemx -extrajoystick4autofirespeed <1-255>
@itemx -extrajoystick5autofirespeed <1-255>
@itemx -extrajoystick6autofirespeed <1-255>
@itemx -extrajoystick7autofirespeed <1-255>
@itemx -extrajoystick8autofirespeed <1-255>
Set the amount of presses per second for autofire for extra joystick port 1, 2, 3, 4, 5, 6, 7 and 8.
(@code{JoyStick3AutoFireSpeed}, @code{JoyStick4AutoFireSpeed}, @code{JoyStick5AutoFireSpeed}, @code{JoyStick6AutoFireSpeed}, @code{JoyStick7AutoFireSpeed}, @code{JoyStick8AutoFireSpeed}, @code{JoyStick9AutoFireSpeed}, @code{JoyStick10AutoFireSpeed}, ).

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

@findex -mouse, +mouse
@item -mouse
@itemx +mouse
Enable/Disable mouse grab

@findex -smartmousertcsave, +smartmousertcsave
@item -smartmousertcsave
@itemx +smartmousertcsave
Enable/Disable saving of the real time clock data for the SmartMouse
(@code{SmartMouseRTCSave=1}, @code{SmartMouseRTCSave=0})

@findex -paddles1inputmouse
@item -paddles1inputmouse
Set the host input for the potentiometers of joystick port 1 to the mouse.
(@code{PaddlesInput1=0})

@findex -paddles1inputjoyaxis
@item -paddles1inputmouse
Set the host input for the potentiometers of joystick port 1 to a joystick axis.
(@code{PaddlesInput1=1})

@findex -paddles2inputmouse
@item -paddles2inputmouse
Set the host input for the potentiometers of joystick port 2 to the mouse.
(@code{PaddlesInput2=0})

@findex -paddles2inputjoyaxis
@item -paddles2inputmouse
Set the host input for the potentiometers of joystick port 2 to a joystick axis.
(@code{PaddlesInput2=1})

@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, Control port 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.

The following menu items control sound input:

@cindex Sampler Device
@item
``Sampler Device'' specifies the host device/method used for sampling/sound input,
currently portaudio (if linked in) and file methods are supported.

@cindex Sampler Gain
@item
``Sampler Gain'' specifies the amount of gain (increase the input volume if above 100
or decrease the input volume if below 100) for the input of the sampler device.

@cindex Sampler File
@item
``Sampler File'' specifies the name of the file to be uses as an input source for
the 'file' method/device.

@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 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 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 (@code{SoundDeviceArg}
specifies the audio device, default system output by default).
@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{speed}, like @code{dummy} but also calculating samples (mainly
used to evaluate the speed of the sample generator);
@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.

@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{flac}, for the FLAC sound recorder driver.
@item
@code{ogg}, for the ogg/vorbis 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)

@vindex SamplerDevice
@item SamplerDevice
Integer specifying the device/method to be used for sound input.
(0: sample file device, 1: PortAudio device)

@vindex SamplerGain
@item SamplerGain
Integer specifying the gain to be used for sound input.
(>100 increase input volume, <100: decrease input volume)

@vindex SampleName
@item SampleName
String specifying the name of the file/sample to be used as the input
source for the 'file' sampler device.

@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 -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, flac, ogg, speed, voc, wav)

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

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

@findex -samplerdev
@item -samplerdev <device number>
Specify the device to use for audio input
(@code{SamplerDevice}).
(0: file device, 1: portaudio device)

@findex -samplergain
@item -samplergain <percent>
Specify the amount of gain (volume increase/decrease) for the audio input device
(@code{SamplerGain}).
(0..200)

@findex -samplename
@item -samplename <name>
Specify the name of the file to use for the 'file' audio input device
(@code{SampleFile}).

@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 gap length in the tap. Mostly
relevant for v0 .tap files which could not properly encode gaps > 255.

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

@vindex DatasetteTapeWobbleFrequency
@item DatasetteTapeWobbleFrequency
Integer specifying the tape wobble frequency

@vindex DatasetteTapeWobbleAmplitude
@item DatasetteTapeWobbleAmplitude
Integer specifying the tape wobble amplitude

@vindex DatasetteTapeAzimuthError
@item DatasetteTapeAzimuthError
Integer specifying the amount of azimuth alignment error

@vindex DatasetteSound
@item DatasetteSound
Boolean specifying whether to produce audible sound when playing a tape on the datasette

@vindex DatasetteSoundVolume
@item DatasetteSoundVolume
Integer specifying the volume of the tape sound. Meaningful values are in the range 1-32767
@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 gap in the tap. Mostly relevant for v0 .tap files
which could not properly encode gaps > 255.
(@code{DatasetteZeroGapDelay}).

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

@findex -dstapewobblefreq
@item -dstapewobblefreq <value>
Set tape wobble frequency
(@code{DatasetteTapeWobbleFrequency}).

@findex -dstapewobbleamp
@item -dstapewobbleamp <value>
Set tape wobble amplitude
(@code{DatasetteTapeWobbleAmplitude}).

@findex -dstapeerror
@item -dstapeerror <value>
Set tape alignment error
(@code{DatasetteTapeAzimuthError}).

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

@findex -dssoundvolume
@item -dssoundvolume <value>
Set the volume of the Datasette sound
(@code{DatasetteSoundVolume}).

@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 Drive8TrueEmulation
@vindex Drive9TrueEmulation
@vindex Drive10TrueEmulation
@vindex Drive11TrueEmulation
@item Drive8TrueEmulation
@itemx Drive9TrueEmulation
@itemx Drive10TrueEmulation
@itemx Drive11TrueEmulation
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{4844} (CMD HD) [all emulators except xcbm2, xcbm5x0, xpet and vsid],
@code{8050} [all emulators except x64dtv, xplus4 and vsid],
@code{8250} [all emulators except x64dtv, xplus4 and vsid].
@code{9000} [all emulators except x64dtv, xplus4 and vsid].

@vindex Drive8RTCSave
@vindex Drive9RTCSave
@vindex Drive10RTCSave
@vindex Drive11RTCSave
@item Drive8RTCSave
@itemx Drive9RTCSave
@itemx Drive10RTCSave
@itemx Drive11RTCSave
Integer specifying whether the RTC data of drive 8 to 11 should be saved when changed or not (drive type 2000/4000/4844 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: Dolphin DOS 3, 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 Supercard is emulated or not for drives 8 to 11
(x64, x64sc, xscpu64 and x128 only).

@vindex Drive8StarDos
@vindex Drive9StarDos
@vindex Drive10StarDos
@vindex Drive11StarDos
@item Drive8StarDos
@itemx Drive9StarDos
@itemx Drive10StarDos
@itemx Drive11StarDos
Booleans controlling whether StarDOS is emulated or not for drives 8 to 11
(x64, x64sc, xscpu64 and x128 only).

@vindex Drive8RAM2000
@vindex Drive9RAM2000
@vindex Drive10RAM2000
@vindex Drive11RAM2000
@item Drive8RAM2000
@itemx Drive9RAM2000
@itemx Drive10RAM2000
@itemx Drive11RAM2000
Booleans controlling whether a RAM block is emulated at $2000-$3FFF for
drive 8 to 11.

@vindex Drive8RAM4000
@vindex Drive9RAM4000
@vindex Drive10RAM4000
@vindex Drive11RAM4000
@item Drive8RAM4000
@itemx Drive9RAM4000
@itemx Drive10RAM4000
@itemx Drive11RAM4000
Booleans controlling whether a RAM block is emulated at $4000-$5FFF for
drive 8 to 11.

@vindex Drive8RAM6000
@vindex Drive9RAM6000
@vindex Drive10RAM6000
@vindex Drive11RAM6000
@item Drive8RAM6000
@itemx Drive9RAM6000
@itemx Drive10RAM6000
@itemx Drive11RAM6000
Booleans controlling whether a RAM block is emulated at $6000-$7FFF for
drive 8 to 11.

@vindex Drive8RAM8000
@vindex Drive9RAM8000
@vindex Drive10RAM8000
@vindex Drive11RAM8000
@item Drive8RAM8000
@itemx Drive9RAM8000
@itemx Drive10RAM8000
@itemx Drive11RAM8000
Booleans controlling whether a RAM block is emulated at $8000-$9FFF for
drive 8 to 11.

@vindex Drive8RAMA000
@vindex Drive9RAMA000
@vindex Drive10RAMA000
@vindex Drive11RAMA000
@item Drive8RAMA000
@itemx Drive9RAMA000
@itemx Drive10RAMA000
@itemx Drive11RAMA000
Booleans controlling whether a RAM block is emulated at $A000-$BFFF for
drive 8 to 11.

@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 Drive8RPM
@vindex Drive9RPM
@vindex Drive10RPM
@vindex Drive11RPM
@item Drive8RPM
@itemx Drive9RPM
@itemx Drive10RPM
@itemx Drive11RPM
Integers specifying the rotation speed of the drive, multiplied by 100, so
300rpm equals 30000.

@vindex Drive8WobbleFrequency
@vindex Drive9WobbleFrequency
@vindex Drive10WobbleFrequency
@vindex Drive11WobbleFrequency
@item Drive8WobbleFrequency
@itemx Drive9WobbleFrequency
@itemx Drive10WobbleFrequency
@itemx Drive11WobbleFrequency
Integers specifying the drive wobble frequency

@vindex Drive8WobbleAmplitude
@vindex Drive9WobbleAmplitude
@vindex Drive10WobbleAmplitude
@vindex Drive11WobbleAmplitude
@item Drive8WobbleAmplitude
@itemx Drive9WobbleAmplitude
@itemx Drive10WobbleAmplitude
@itemx Drive11WobbleAmplitude
Integers specifying the drive wobble amplitude

@vindex Drive8FixedSize
@vindex Drive9FixedSize
@vindex Drive10FixedSize
@vindex Drive11FixedSize
@item Drive8FixedSize
@itemx Drive9FixedSize
@itemx Drive10FixedSize
@itemx Drive11FixedSize
Integer specifying the size of the diskimage (in bytes) returned to SCSI
capacity inquiries for CMD HDs.
A disk image must be attached for a valid size to be returned.
A value of "0" will report back the current image size.
Values may also be followed by the suffix "K", "M", or "G" for kilobyte,
megabyte, and gigabyte respectively. Default is "8G".

@vindex DosName1540
@vindex DosName1541
@vindex DosName1541ii
@vindex DosName1570
@vindex DosName1571
@vindex DosName1581
@vindex DosName2000
@vindex DosName4000
@vindex DosNameCMDHD
@item DosName1540
@itemx DosName1541
@itemx DosName1541ii
@itemx DosName1570
@itemx DosName1571
@itemx DosName1581
@itemx DosName2000
@itemx DosName4000
@itemx DosNameCMDHD
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
@vindex DosName9000
@item DosName2031
@itemx DosName2040
@itemx DosName3040
@itemx DosName4040
@itemx DosName1001
@itemx DosName9000
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 Supercard ROM image
(x64, x64sc, xscpu64 and x128 only).

@vindex DriveStarDosName
@item DriveStarDosName
String specifying the filename of the image of the lower half of the StarDOS ROM
(x64, x64sc, xscpu64 and x128 only).

@end table

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

@table @code

@findex -drive8truedrive, +drive8truedrive
@findex -drive9truedrive, +drive9truedrive
@findex -drive10truedrive, +drive10truedrive
@findex -drive11truedrive, +drive11truedrive
@item -drive8truedrive, +drive8truedrive
@itemx -drive9truedrive, +drive9truedrive
@itemx -drive10truedrive, +drive10truedrive
@itemx -drive11truedrive, +drive11truedrive
Enable/disable true drive emulation
(@code{Drive8TrueEmulation=1}, @code{Drive8TrueEmulation=0},
 @code{Drive9TrueEmulation=1}, @code{Drive9TrueEmulation=0},
 @code{Drive10TrueEmulation=1}, @code{Drive10TrueEmulation=0},
 @code{Drive11TrueEmulation=1}, @code{Drive11TrueEmulation=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{4844} (meaning CMD HD) [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]
@code{8250} [all emulators except x64dtv, xplus4 and vsid].
and @code{9000} [all emulators except x64dtv, xplus4 and vsid].

@findex -drive8rtcsave, +drive8rtcsave
@findex -drive9rtcsave, +drive9rtcsave
@findex -drive10rtcsave, +drive10rtcsave
@findex -drive11rtcsave, +drive11rtcsave
@item -drive8rtcsave, +drive8rtcsave
@itemx -drive9rtcsave, +drive9rtcsave
@itemx -drive10rtcsave, +drive10rtcsave
@itemx -drive11rtcsave, +drive11rtcsave
Enable/disable the saving of the RTC data for drive 8 to 11 when changed
(drive type 2000/4000/4844 only)
(@code{Drive8RTCSave=1}, @code{Drive8RTCSave=0}, @code{Drive9RTCSave=1},
@code{Drive9RTCSave=0}, @code{Drive10RTCSave=1}, @code{Drive10RTCSave=0},
@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 -drive8rpm
@findex -drive9rpm
@findex -drive10rpm
@findex -drive11rpm
@item -drive8rpm <rpm>
@itemx -drive9rpm <rpm>
@itemx -drive10rpm <rpm>
@itemx -drive11rpm <rpm>
Specifies the rotation speed of the drive, multiplied by 100 so 300rpm
equal 30000.

@findex -drive8wobblefrequency
@findex -drive9wobblefrequency
@findex -drive10wobblefrequency
@findex -drive11wobblefrequency
@item -drive8wobblefrequency <frequency>
@itemx -drive9wobblefrequency <frequency>
@itemx -drive10wobblefrequency <frequency>
@itemx -drive11wobblefrequency <frequency>
Specifies frequency of the drive wobble

@findex -drive8wobbleamplitude
@findex -drive9wobbleamplitude
@findex -drive10wobbleamplitude
@findex -drive11wobbleamplitude
@item -drive8wobbleamplitude <amplitude>
@itemx -drive9wobbleamplitude <amplitude>
@itemx -drive10wobbleamplitude <amplitude>
@itemx -drive11wobbleamplitude <amplitude>
Specifies amplitude of the drive wobble

@findex -drive8fixedsize
@findex -drive9fixedsize
@findex -drive10fixedsize
@findex -drive11fixedsize
@item -drive8fixedsize
@itemx -drive9fixedsize
@itemx -drive10fixedsize
@itemx -drive11fixedsize
Specifies the size of the diskimage (in bytes) returned to SCSI
capacity inquiries for CMD HDs.
A disk image must be attached for a valid size to be returned.
A value of "0" will report back the current image size.
Values may also be followed by the suffix "K", "M", or "G" for kilobyte,
megabyte, and gigabyte respectively. Default is "8G".

@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 -dosCMDHD
@item -dosCMDHD <name>
Specify the boot ROM name for the CMD HD emulation
(@code{DosNameCMDHD}).
(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 -dos9000
@item -dos9000 <name>
Specify the ROM name for the D9090/60 emulations
(@code{DosName9000}).
(all emulators except x64dtv, xplus4 and vsid)

@findex -drive8ram2000, +drive8ram2000
@findex -drive9ram2000, +drive9ram2000
@findex -drive10ram2000, +drive10ram2000
@findex -drive11ram2000, +drive11ram2000
@item -drive8ram2000, +drive8ram2000
@itemx -drive9ram2000, +drive9ram2000
@itemx -drive10ram2000, +drive10ram2000
@itemx -drive11ram2000, +drive11ram2000
Enable/disable 8KiB RAM expansion at $2000-$3FFF for drive 8 to 11
(@code{Drive8RAM2000=1}, @code{Drive8RAM2000=0},
@code{Drive9RAM2000=1}, @code{Drive9RAM2000=0},
@code{Drive10RAM2000=1}, @code{Drive10RAM2000=0},
@code{Drive11RAM2000=1}, @code{Drive11RAM2000=0}).

@findex -drive8ram4000, +drive8ram4000
@findex -drive9ram4000, +drive9ram4000
@findex -drive10ram4000, +drive10ram4000
@findex -drive11ram4000, +drive11ram4000
@item -drive8ram4000, +drive8ram4000
@itemx -drive9ram4000, +drive9ram4000
@itemx -drive10ram4000, +drive10ram4000
@itemx -drive11ram4000, +drive11ram4000
Enable/disable 8KiB RAM expansion at $4000-$5FFF for drive 8 to 11
(@code{Drive8RAM4000=1}, @code{Drive8RAM4000=0},
@code{Drive9RAM4000=1}, @code{Drive9RAM4000=0},
@code{Drive10RAM4000=1}, @code{Drive10RAM4000=0},
@code{Drive11RAM4000=1}, @code{Drive11RAM4000=0}).

@findex -drive8ram6000, +drive8ram6000
@findex -drive9ram6000, +drive9ram6000
@findex -drive10ram6000, +drive10ram6000
@findex -drive11ram6000, +drive11ram6000
@item -drive8ram6000, +drive8ram6000
@itemx -drive9ram6000, +drive9ram6000
@itemx -drive10ram6000, +drive10ram6000
@itemx -drive11ram6000, +drive11ram6000
Enable/disable 8KiB RAM expansion at $6000-$7FFF for drive 8 to 11
(@code{Drive8RAM6000=1}, @code{Drive8RAM6000=0},
@code{Drive9RAM6000=1}, @code{Drive9RAM6000=0},
@code{Drive10RAM6000=1}, @code{Drive10RAM6000=0},
@code{Drive11RAM6000=1}, @code{Drive11RAM6000=0}).

@findex -drive8ram8000, +drive8ram8000
@findex -drive9ram8000, +drive9ram8000
@findex -drive10ram8000, +drive10ram8000
@findex -drive11ram8000, +drive11ram8000
@item -drive8ram8000, +drive8ram8000
@itemx -drive9ram8000, +drive9ram8000
@itemx -drive10ram8000, +drive10ram8000
@itemx -drive11ram8000, +drive11ram8000
Enable/disable 8KiB RAM expansion at $8000-$9FFF for drive 8 to 11
(@code{Drive8RAM8000=1}, @code{Drive8RAM8000=0},
@code{Drive9RAM8000=1}, @code{Drive9RAM8000=0},
@code{Drive10RAM8000=1}, @code{Drive10RAM8000=0},
@code{Drive11RAM8000=1}, @code{Drive11RAM8000=0}).

@findex -drive8rama000, +drive8rama000
@findex -drive9rama000, +drive9rama000
@findex -drive10rama000, +drive10rama000
@findex -drive11rama000, +drive11rama000
@item -drive8rama000, +drive8rama000
@itemx -drive9rama000, +drive9rama000
@itemx -drive10rama000, +drive10rama000
@itemx -drive11rama000, +drive11rama000
Enable/disable 8KiB RAM expansion at $A000-$BFFF for drive 8 to 11
(@code{Drive8RAMA000=1}, @code{Drive8RAMA000=0},
@code{Drive9RAMA000=1}, @code{Drive9RAMA000=0},
@code{Drive10RAMA000=1}, @code{Drive10RAMA000=0},
@code{Drive11RAMA000=1}, @code{Drive11RAMA000=0}).

@findex -drive8profdos, +drive8profdos
@findex -drive9profdos, +drive9profdos
@findex -drive10profdos, +drive10profdos
@findex -drive11profdos, +drive11profdos
@item -drive8profdos, +drive8profdos
@itemx -drive9profdos, +drive9profdos
@itemx -drive10profdos, +drive10profdos
@itemx -drive11profdos, +drive11profdos
Enable/disable Professional DOS for drive 8 to 11
(@code{Drive8ProfDOS=1}, @code{Drive8ProfDOS=0},
@code{Drive9ProfDOS=1}, @code{Drive9ProfDOS=0},
@code{Drive10ProfDOS=1}, @code{Drive10ProfDOS=0},
@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
@findex -drive9supercard, +drive9supercard
@findex -drive10supercard, +drive10supercard
@findex -drive11supercard, +drive11supercard
@item -drive8supercard, +drive8supercard
@itemx -drive9supercard, +drive9supercard
@itemx -drive10supercard, +drive10supercard
@itemx -drive11supercard, +drive11supercard
Enable/disable Supercard for drive 8 to 11
(@code{Drive8SuperCard=1}, @code{Drive8SuperCard=0},
@code{Drive9SuperCard=1}, @code{Drive9SuperCard=0},
@code{Drive10SuperCard=1}, @code{Drive10SuperCard=0},
@code{Drive11SuperCard=1}, @code{Drive11SuperCard=0})
(x64, x64sc, xscpu64 and x128 only).

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

@findex -drive8stardos, +drive8stardos
@findex -drive9stardos, +drive9stardos
@findex -drive10stardos, +drive10stardos
@findex -drive11stardos, +drive11stardos
@item -drive8stardos, +drive8stardos
@itemx -drive9stardos, +drive9stardos
@itemx -drive10stardos, +drive10stardos
@itemx -drive11stardos, +drive11stardos
Enable/disable StarDOS for drive 8 to 11
(@code{Drive8StarDos=1}, @code{Drive8StarDos=0},
@code{Drive9StarDos=1}, @code{Drive9StarDos=0},
@code{Drive10StarDos=1}, @code{Drive10StarDos=0},
@code{Drive11StarDos=1}, @code{Drive11StarDos=0})
(x64, x64sc, xscpu64 and x128 only).

@findex -stardos
@item -stardos <name>
Specify name of the image of the lower half of the StarDOS ROM. (Attach the upper
half using the -dos1541 option.)
(@code{DriveStarDosName})
(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.

@c @menu
@c * File system device settings::  Settings for file system devices.
@c * Printer settings::            Settings for emulating a printer.
@c * No kernal traps::             Disabling kernal traps completely.
@c @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.

@c @menu
@c * File system device resources::
@c * File system device options::
@c @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))

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

@vindex FSDeviceLongNames
@item FSDeviceLongNames
Boolean specifying whether filenames will get converted to 16 character long short names
or not. Disabled by default.

@vindex FSDeviceOverwrite
@item FSDeviceOverwrite
Boolean specifying whether files in the file system can be overwritten without
using @code{"@@:name"}, or not.
Disabled by default.

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

@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 -fslongnames, +fslongnames
@item -fslongnames
@itemx +fslongnames
Enable/disable whether filenames will get converted to 16 character long short names
(@code{FSDeviceLongNames=1}, @code{FSDeviceLongNames=0})
(all emulators except vsid).

@findex -fsoverwrite, +fsoverwrite
@item -fsoverwrite
@itemx +fsoverwrite
Enable/disable whether existing files in the file system can be overwritten
by default. Using @code{OPEN} or @code{SAVE"@@:name"} this is always possible.
(@code{FSDeviceOverwrite=1}, @code{FSDeviceOverwrite=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}.


@c @menu
@c * Printer resources::
@c * Printer options::
@c @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 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 -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 (t64) support.

Since the 3.0 release kernal traps have been disabled by default to ensure
maximum compatibility.

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

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

@table @code

@vindex VirtualDevice1
@vindex VirtualDevice2
@vindex VirtualDevice4
@vindex VirtualDevice5
@vindex VirtualDevice6
@vindex VirtualDevice7
@vindex VirtualDevice8
@vindex VirtualDevice9
@vindex VirtualDevice10
@vindex VirtualDevice11
@item VirtualDevice1
@itemx VirtualDevice2
@itemx VirtualDevice4
@itemx VirtualDevice5
@itemx VirtualDevice6
@itemx VirtualDevice7
@itemx VirtualDevice8
@itemx VirtualDevice9
@itemx VirtualDevice10
@itemx VirtualDevice11
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 -virtualdev1, +virtualdev1
@findex -virtualdev2, +virtualdev2
@findex -virtualdev4, +virtualdev4
@findex -virtualdev5, +virtualdev5
@findex -virtualdev6, +virtualdev6
@findex -virtualdev7, +virtualdev7
@findex -virtualdev8, +virtualdev8
@findex -virtualdev9, +virtualdev9
@findex -virtualdev10, +virtualdev10
@findex -virtualdev11, +virtualdev11
@item -virtualdev1, +virtualdev1
@itemx -virtualdev2, +virtualdev2
@itemx -virtualdev4, +virtualdev4
@itemx -virtualdev5, +virtualdev5
@itemx -virtualdev6, +virtualdev6
@itemx -virtualdev7, +virtualdev7
@itemx -virtualdev8, +virtualdev8
@itemx -virtualdev9, +virtualdev9
@itemx -virtualdev10, +virtualdev10
@itemx -virtualdev11, +virtualdev11
Enable/disable virtual devices
(@code{VirtualDevice1=1}, @code{VirtualDevice1=0},
 @code{VirtualDevice2=1}, @code{VirtualDevice2=0},
 @code{VirtualDevice4=1}, @code{VirtualDevice4=0},
 @code{VirtualDevice5=1}, @code{VirtualDevice5=0},
 @code{VirtualDevice6=1}, @code{VirtualDevice6=0},
 @code{VirtualDevice7=1}, @code{VirtualDevice7=0},
 @code{VirtualDevice8=1}, @code{VirtualDevice8=0},
 @code{VirtualDevice9=1}, @code{VirtualDevice9=0},
 @code{VirtualDevice10=1}, @code{VirtualDevice10=0},
 @code{VirtualDevice11=1}, @code{VirtualDevice11=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 from 300 to 57600 baud.  The C64 can also use the UP9600 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 Swiftlink, Datapump
or Turbo232 for example) as extension at @code{$de**}, @code{$df**} or @code{$d7**} (C128 only).

Emulation can be achieved by either:

@itemize @bullet
@item
connecting a real serial device/port;
@item
dumping to a file;
@item
piping through a process.
@item
connect through a network socket.
@end itemize

It is possible to define up to four 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, a network address, or a command name preceeded 
by a pipe symbol @samp{|}.  
If the path specifies a special device (e.g. @file{/dev/ttyS0} or @file{com1}) 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.

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{127.0.0.1:25232};
@item
device 4, whose default value is @code{|nc 127.0.0.1:25232}.
@end itemize

(Only) when using physical RS232 ports, you'll also have to specify it on the
commandline or in the menu.

@c @menu
@c * RS232 resources::
@c * RS232 options::
@c * RS232 usage::
@c @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}).

The windows driver understands various options passed in the so called "mode string"
after a colon after the ports name: @code{COMx[:]} @code{[baud=b]} @code{[parity=p]}
@code{[data=d]} @code{[stop=s]} @code{[to={on|off}]} @code{[xon={on|off}]} @code{[odsr={on|off}]}
@code{[octs={on|off}]} @code{[dtr={on|off|hs}]} @code{[rts={on|off|hs|tg}]} @code{[idsr={on|off}]}
@end table

@table @code

@vindex RsDevice1ip232
@vindex RsDevice2ip232
@vindex RsDevice3ip232
@vindex RsDevice4ip232
@item RsDevice1ip232
@itemx RsDevice2ip232
@itemx RsDevice3ip232
@itemx RsDevice4ip232
Boolean specifying whether the respective RS232 devices (@pxref{RS232 settings}) 
use the IP232 protocol supported by tcpser.
This only works with Socket connections.

@end table

@table @code

@vindex Acia1Enable
@item Acia1Enable
Boolean specifying whether the ACIA (Swiftlink, Turbo232) cartridge should be emulated or not
(x64, x64sc, xscpu64, x128 and xvic only, and only if RS232 support is enabled and supported at compile time).

@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 Acia1Base
@item Acia1Base
Integer specifying the base address for the emulated ACIA chip (x64, x64sc, xscpu64, xvic and x128 only, and only if RS232 support is enabled and supported at compile time).
(xvic: $9800/$9C00, x128: $D700/$DE00/$DF00, x64, x64sc, xscpu64: $DE00/$DF00)

@vindex Acia1Mode
@item Acia1Mode
Integer specifying the type of emulated RS232 interface (x64, x64sc, xscpu64, xvic and x128 only, and only if RS232 support is enabled and supported at compile time).
(0: normal, 1: Swiftlink, 2: Turbo232)

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

@end table

@table @code

@vindex RsUserUP9600
@item RsUserUP9600
Boolean specifying if the user-port RS232 interface is of the UP9600 type.
(C64 only).

@vindex RsUserRTSInv
@item RsUserRTSInv
Boolean specifying if the user-port RS232 Request to Send (RTS) flow control line is inverted.
(C64, C128 and VIC20).

@vindex RsUserCTSInv
@item RsUserCTSInv
Boolean specifying if the user-port RS232 Clear to Send (CTS) flow control line is inverted.
(C64, C128 and VIC20).

@vindex RsUserDSRInv
@item RsUserDSRInv
Boolean specifying if the user-port RS232 Data Set Ready (DSR) control line is inverted.
(C64, C128 and VIC20).

@vindex RsUserDCDInv
@item RsUserDCDInv
Boolean specifying if the user-port RS232 Data Carrier Detect (DCD) control line is inverted.
(C64, C128 and VIC20).

@vindex RsUserDTRInv
@item RsUserDTRInv
Boolean specifying if the user-port RS232 Data Terminal Ready (DTR) control line is inverted.
(C64, C128 and VIC20).

@vindex RsUserBaud
@item RsUserBaud
Integer specifying the baudrate of the user-port RS232 interface
(C64, C128 and VIC20). This must match the baudrate the emulated user port is
being used with, and needs to be set up by the user because automatically detecting
it can not be done easily (like when using ACIA)

@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

@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} or @file{com1}, ie the serial device is a physical
RS232 port of the host computer; @pxref{RS232 settings})
(all emulators except vsid).

@end table

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

@table @code

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

The windows driver understands various options passed in the so called "mode string"
after a colon after the ports name: @code{COMx[:]} @code{[baud=b]} @code{[parity=p]}
@code{[data=d]} @code{[stop=s]} @code{[to={on|off}]} @code{[xon={on|off}]} @code{[odsr={on|off}]}
@code{[octs={on|off}]} @code{[dtr={on|off|hs}]} @code{[rts={on|off|hs|tg}]} @code{[idsr={on|off}]}
@end table

@table @code

@findex -rsdev1ip232, +rsdev1ip232
@item -rsdev1ip232
@itemx +rsdev1ip232
@findex -rsdev2ip232, +rsdev2ip232
@item -rsdev2ip232
@itemx +rsdev2ip232
@findex -rsdev3ip232, +rsdev3ip232
@item -rsdev3ip232
@itemx +rsdev3ip232
@findex -rsdev4ip232, +rsdev4ip232
@item -rsdev4ip232
@itemx +rsdev4ip232
Enable/Disable whether the respective RS232 devices (@pxref{RS232 settings}) 
use the IP232 protocol supported by tcpser.
This only works with Socket connections.

@end table

@table @code

@findex -acia1, +acia1
@item -acia1
@itemx +acia1
Enable/Disable the $DE** ACIA RS232 interface emulation
(@code{Acia1Enable=1}, @code{Acia1Enable=0})
(x64, x64sc, xscpu64, x128 and xvic only, and only if RS232 support is enabled and supported at compile time).

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


@findex -acia1base
@item -acia1base <Base address>
Set the base address of the ACIA cartridge
(@code{Acia1Base})
(x64, x64sc, xscpu, x128 and xvic only, and only if RS232 support is enabled and supported at compile time).
(xvic: $9800/$9C00, x128: $D700/$DE00/$DF00, x64, x64sc, xscpu: $DE00/$DF00)

@findex -acia1mode
@item -acia1mode <mode>
Set the ACIA mode
(@code{Acia1Mode})
(x64, x64sc, xscpu64, xvic and x128 only, and only if RS232 support is enabled and supported at compile time).
(0: Normal, 1: Swiftlink, 2: Turbo232)

@findex -acia1irq
@item -acia1irq <interrupt>
Set the ACIA interrupt
(@code{Acia1Irq})
(x64, x64sc, xscpu64, xvic and x128 only, and only if RS232 support is enabled and supported at compile time).
(0: None, 1: NMI, 2: IRQ)

@end table

@table @code

@findex -rsuserup9600, +rsuserup9600
@item -rsuserup9600
@itemx +rsuserup9600
Enable or disable the userport RS232 UP9600 emulation (@code{RsUserUP9600}; C64 only)

@findex -rsuserrtsinv, +rsuserrtsinv
@item -rsuserrtsinv
@itemx +rsuserrtsinv
Enable or disable inversion of the userport RS232 emulation Request To Send (RTS) flow control line.

@findex -rsuserctsinv, +rsuserctsinv
@item -rsuserctsinv
@itemx +rsuserctsinv
Enable or disable inversion of the userport RS232 emulation Clear To Send (CTS) flow control line.

@findex -rsuserdsrinv, +rsuserdsrinv
@item -rsuserdsrinv
@itemx +rsuserdsrinv
Enable or disable inversion of the userport RS232 emulation Data Set Ready (DSR) control line.

@findex -rsuserdcdinv, +rsuserdcdinv
@item -rsuserdcdinv
@itemx +rsuserdcdinv
Enable or disable inversion of the userport RS232 emulation Data Carrier Detect (DCD) control line.

@findex -rsuserdtrinv, +rsuserdtrinv
@item -rsuserdtrinv
@itemx +rsuserdtrinv
Enable or disable inversion of the userport RS232 emulation Data Terminal Ready (DTR) control line.

@findex -rsuserbaud
@item -rsuserbaud <baud>
Set the baud rate of the RS232 userport emulation. This must match the baudrate the emulated userport
is being used at.

@findex -rsuserdev
@item -rsuserdev <0-3>
Specify device for the userport RS232 emulation (@code{RsUserDev};
C64, C128 and VIC20).

@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>
If the serial device is a physical RS232 port, specify <baudrate> as baudrate,
@pxref{RS232 settings};
@code{RsDevice1Baud}, @code{RsDevice2Baud} @code{RsDevice3Baud} and
@code{RsDevice4Baud})
(all emulators except vsid).

@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, 2400 or 9600 according
  to what you enabled in the VICE menu for the userport.

@end table

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

@c @node FIXME
@section Ethernet emulation

To use the ethernet emulation features, VICE must be configured with --enable-ethernet
before compiling, and the system headers for libpcap, libnet and/or tuntap must
be present.

In Windows you will have to install the npcap driver, which is available from
@uref{https://npcap.com/#download} (select winpcap compatibility mode when installing).

It should be clear to you that it may pose a security problem using these 
libraries in a network. Using libpcap can result in disclosure of any information
that is available on your network which is not secured by other means! Furthermore,
libnet might allow even further attacks on your infrastructure!

Installing libpcap and libnet, you acknowledge that you're well aware of these
security problems and that the VICE team cannot be made responsible for any
problems and/or damage which may arise from the use of these libraries! If you
don't acknowledge this, don't install the tools and/or use VICE networking.

@c @node FIXME
@subsection Ethernet usage example

@itemize @bullet
@item
Go to Preferences -> Peripherial Devices -> Ethernet and select the driver and
network interface you want to use. If this option is not present at all, then
VICE was compiled without ethernet support or the respective libraries could not
be found on your system (see note above). If the option exists but is not
enabled, you may not have the required permissions to use the raw ethernet device -
you can try to run VICE as root/Administrator (the usual precautions apply), on
*nix platforms VICE also supports the "capabilities" mechanism.

@item
Go to Preferences -> Cartridges - Ethernet Cartridge and select "Enable ethernet cartridge".
Most likely you want to enable "RR-Net compatibility mode", too. (If this option is not set,
the ethernet emulation runs in "The Final Ethernet" mode). The cartridge I/O base should be
at its default value of $de00.

@item
Run the RR-Net enabled C64 program.

@item 
If the program can not access the network, check your router setup. The raw
ethernet emulation works exactly like a "real" ethernet device in the network,
eg the emulated ethernet device gets its own MAC adress, which you may have to
allow to access the internet at your router.
@end itemize

@c @node FIXME
@subsection Ethernet resources

The following are the generic ethernet resources, some more may exist for the
individual emulators:

@table @code

@vindex ETHERNET_INTERFACE
@item ETHERNET_INTERFACE
String specifying the device name of the ethernet device to use for the emulation.

@vindex ETHERNET_DRIVER
@item ETHERNET_DRIVER
String specifying the low-level ethernet driver for Ethernet Cartridge emulation
(tuntap, pcap).

@vindex ETHERNET_DISABLED
@item ETHERNET_DISABLED
Boolean that specified whether ethernet emulation has been disabled because it is
not available in the current configuration.

@end table

@c @node FIXME
@subsection Ethernet command line options

@table @code

@findex -ethernetioif
@item -ethernetioif <name>
Set the system ethernet interface for Ethernet Cartridge emulation
(@code{ETHERNET_INTERFACE}).

@findex -ethernetiodriver
@item -ethernetiodriver <name>
Set the low-level ethernet driver for Ethernet Cartridge emulation
(@code{ETHERNET_DRIVER}).
(tuntap, pcap)

@end table

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

@c @node FIXME
@section Tape port devices

@c @node FIXME
@subsection Tape port resources

@table @code

@vindex TapePort1Device
@item TapePort1Device
Set the device attached to the (first) tape port (see table below):

@vindex TapePort2Device
@item TapePort2Device
Set the device attached to the second tape port (xpet only, see table below):

@end table

@multitable @columnfractions .005 .37 .8
@item 0
@tab None
@tab x64, x64sc, x128, xvic, xplus4, xpet, xcbm2
@item 1
@tab Datasette
@tab x64, x64sc, x128, xvic, xplus4, xpet, xcbm2
@item 2
@tab Tape RTC (PCF8583)
@tab x64, x64sc, x128, xvic, xplus4, xpet, xcbm2
@item 3
@tab DTL BASIC dongle
@tab x64, x64sc, x128
@item 4
@tab Sense dongle
@tab x64, x64sc, x128, xvic, xplus4, xpet, xcbm2
@item 6
@tab tapecart
@tab x64, x64sc, x128
@end multitable

@table @code

@vindex CPClockF83Save
@item CPClockF83Save
Boolean specifying whether the CP Clock F83 (PCF8583 RTC) data is saved when changed.

@vindex TapecartUpdateTCRT
@item TapecartUpdateTCRT
Boolean, if true write back the tapecart memory contents back to the
.tcrt file when detaching the image or quitting the emulator.

@vindex TapecartOptimizeTCRT
@item TapecartOptimizeTCRT
Boolean, when set to true the .tcrt image will be optimized by leaving
out blank space at the end when saving.

@vindex TapecartLogLevel
@item TapecartLogLevel
Integer that specifies the tapecart emulation log level. At the default
level of 0, only errors are logged. Level 1 additionally logs mode
changes and command bytes and level 2 adds details of command
parameters.

@vindex TapecartTCRTFilename
@item TapecartTCRTFilename
String specifying the file name of the current tapecart image.

@end table

@c @node FIXME
@subsection Tape port command line options

@table @code

@findex -tapeport1device
@item -tapeport1device <device>
Set the device attached to the (first) tape port:
(see table for @code{TapePort1Device} above).

@findex -tapeport2device
@item -tapeport2device <device>
Set the device attached to the second tape port:
(see table for @code{TapePort2Device} above).

@findex -cpclockf83save, +cpclockf83save
@item -cpclockf83save
@itemx +cpclockf83save
Enable/Disable saving of the CP Clock F83 (PCF8583 RTC) data when changed
 (@code{CPClockF83Save=1}, @code{CPClockF83Save=0}).

@findex -tcrt
@item -tcrt <name>
Specify tapecart .tcrt image filename
(@code{TapecartTCRTFilename})

@findex -tapecartupdatetcrt, +tapecartupdatetcrt
@item -tapecartupdatetcrt
@itemx +tapecartupdatetcrt
Specify if the attached .tcrt image should be updated when the emulated
tapecart is written to.
(@code{TapecartUpdateTCRT=1}, @code{TapecartUpdateTCRT=0})

@findex -tapecartoptimizetcrt, +tapecartoptimizetcrt
@item -tapecartoptimizetcrt
@itemx +tapecartoptimizetcrt
Specify if writing to a .tcrt file should optimize its size by leaving
out blank space at the end.
(@code{TapecartOptimizeTCRT=1}, @code{TapecartOptimizeTCRT=0})

@findex -tapecartloglevel
@item -tapecartloglevel <number>
Specify the tapecart log level. The default level of 0 only logs
errors. Level 1 additionally logs mode changes and command bytes and
level 2 adds details of command parameters.

@end table

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

@c @node FIXME
@section Userport devices

@c @node FIXME
@subsection Userport resources

@table @code

@vindex UserportDevice
@item UserportDevice
Set the device attached to the userport (see table below):

@end table

@multitable @columnfractions .005 .37 .8
@item 0
@tab None
@tab x64, x64sc, x128, xscpu64, x64dtv, xvic, xplus4, xpet, xcbm2
@item 1
@tab Userport printer
@tab x64, x64sc, x128, xscpu64, xvic, xpet, xcbm2
@item 2
@tab Userport RS232/Modem
@tab x64, x64sc, x128, xscpu64, xvic
@item 3
@tab CGA userport joy adapter
@tab x64, x64sc, x128, xscpu64, xvic, xpet, xcbm2
@item 4
@tab PET userport joy adapter
@tab x64, x64sc, x128, xscpu64, xvic, xplus4, xpet, xcbm2
@item 5
@tab Hummer userport joy adapter
@tab x64, x64sc, x128, xscpu64, x64dtv, xvic, xplus4, xpet, xcbm2
@item 6
@tab OEM userport joy adapter
@tab x64, x64sc, x128, xscpu64, xvic, xplus4, xpet, xcbm2
@item 7
@tab HIT userport joy adapter
@tab x64, x64sc, x128, xscpu64
@item 8
@tab KingSoft userport joy adapter
@tab x64, x64sc, x128, xscpu64
@item 9
@tab StarByte userport joy adapter
@tab x64, x64sc, x128, xscpu64
@item 10
@tab Synergy userport joy adapter
@tab x64, x64sc, x128, xscpu64, xvic, xplus4, xpet, xcbm2
@item 11
@tab Userport DAC
@tab x64, x64sc, x128, xscpu64, xvic, xplus4, xpet, xcbm2
@item 12
@tab Userport DigiMAX
@tab x64, x64sc, x128, xscpu64, xcbm2
@item 13
@tab Userport 4bit sampler
@tab x64, x64sc, x128, xscpu64, xcbm2
@item 14
@tab Userport 8bit stereo sampler
@tab x64, x64sc, x128, xscpu64, xcbm2
@item 15
@tab Userport RTC (RTC58321A)
@tab x64, x64sc, x128, xscpu64, xvic, xpet, xcbm2
@item 16
@tab Userport RTC (DS1307)
@tab x64, x64sc, x128, xscpu64, xvic, xpet, xcbm2
@item 17
@tab Userport Petscii SNES pad
@tab x64, x64sc, x128, xscpu64, xvic, xpet, xcbm2
@item 18
@tab Userport SuperPad64
@tab x64, x64sc, x128, xscpu64, xcbm2
@item 20
@tab Userport parallel drive cable
@tab x64, x64sc, x128, xscpu64, xplus4
@item 21
@tab Userport I/O Simulation
@tab x64, x64sc, x128, xscpu64, x64dtv, xvic, xplus4, xpet, xcbm2
@item 23
@tab Joystick Adapter (Spaceballs)
@tab x64, x64sc, x128, xscpu64, xvic
@item 24
@tab Userport Stupid Pet Tricks joystick adapter
@tab x64, x64sc, x128, xscpu64, xcbm2, xpet, xvic
@end multitable

@table @code

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

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

@end table

@c @node FIXME
@subsection Userport command line options

@table @code

@findex -userportdevice
@item -userportdevice <device>
Set the device attached to the userport (see table for @code{UserportDevice} above).

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

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

@end table

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

@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 RefreshOnBreak
@item RefreshOnBreak
Boolean, if true, the emulated display(s) will update as the monitor is entered
and also after each command executed via the monitor. Not entirely accurate yet,
as updates become visible one scanline at a time. In addtion, the image can be not
quite right around the raster line being updated.

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

@vindex BinaryMonitorServer
@item BinaryMonitorServer
Boolean specifying whether the binary monitor server is enabled.

@vindex BinaryMonitorServerAddress
@item BinaryMonitorServerAddress
String specifying the address the binary monitor server listens to (ip4://127.0.0.1:6502)

@vindex NativeMonitor
@item NativeMonitor
Boolean specifying whether the native monitor is enabled. When enabled, the monitor
 will not run in the interface of the emulator, but instead work in the spawning
 terminal.

@vindex MonitorLogEnabled
@item MonitorLogEnabled
Boolean specifying whether the output of the monitor will be logged to a file.

@vindex MonitorLogFileName
@item MonitorLogFileName
String specifying the logfile name for the monitor.

@vindex MonitorChisLines
@item MonitorChisLines
Integer specifying the number of lines to keep in the cpu history. (only when enabled in configure)

@vindex MonitorScrollbackLines
@item MonitorScrollbackLines
Integer specifying the number of lines to keep in the monitor scrollback buffer (-1 for no limit).

@vindex MonitorFont
@item MonitorFont
String specifying the font to use in the Gtk3 UI's VTE monitor window. Should be
in the form accepted by Pango, for example "Liberation Mono 11".

@vindex MonitorFG
@item MonitorFG
String specifying the foreground color to use in the Gtk3 UI's VTE monitor window.
Should be in form accepted by Pango: either a CSS color name (for example 'limegreen'),
three/six digit hex string ("#rgb"/"#rrggbb") or three decimal values in the range 0-255 
("rbg(red,green,blue"), for example "rgb(27,180,33)").

@vindex MonitorBG
@item MonitorBG
String specifying the background color to use in the Gtk3 UI's VTE monitor window.
Should be in form accepted by Pango: either a CSS color name (for example 'limegreen'),
three/six digit hex string ("#rgb"/"#rrggbb") or three decimal values in the range 0-255 
("rbg(red,green,blue"), for example "rgb(27,180,33)").

@vindex MonitorXPos
@item MonitorXPos
Integer specifying the Gtk3 VTE-monitor window's X position.

@vindex MonitorYPos
@item MonitorYPos
Integer specifying the Gtk3 VTE-monitor window's Y position.

@vindex MonitorWidth
@item MonitorWidth
Integer specifying the Gtk3 VTE-monitor window's width.

@vindex MonitorHeight
@item MonitorHeight
Integer specifying the Gtk3 VTE-monitor window's height.

@end table

@subsection Monitor command-line options

@table @code
@findex -moncommands
@item -moncommands <Name>
Execute the commands from the file <Name> in the monitor after starting up. All
monitor commands are supported, including playback of other command files via
@code{pb}. By default, the monitor opens and starts executing the commands just
before the kernal reset routine starts. The kernal starup sequence may interfere
with what you are trying to achieve, for example by clearing any basic listing
you may have loaded. In this case, use the @code{-initbreak} option to control
when the monitor will open and execute your script. You can choose an address,
or use @code{-initbreak ready} to attempt to detect when the kernel is ready
and execute the script then.

@findex -initbreak
@item -initbreak <address>
@item -initbreak reset
@item -initbreak ready
Set an initial breakpoint for the monitor. Addresses with prefix "0x" are hexadecimal.
@code{-initbreak reset} will break just before the reset routine starts.
@code{-initbreak ready} will attempt to break when the kernal is 'ready'.

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

@findex -refreshonbreak, +refreshonbreak
@item -refreshonbreak
@itemx +refreshonbreak
Enable/Disable refresh display when entering monitor and after each monitor command.
(@code{RefreshOnBreak=1}, @code{RefreshOnBreak=0}).

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

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

@findex -binarymonitor, +binarymonitor
@item -binarymonitor
@itemx +binarymonitor
Enable/Disable binary monitor

@findex -binarymonitoraddress
@item -binarymonitoraddress <name>
The local address the binary monitor should bind to

@findex -nativemonitor, +nativemonitor
@item -nativemonitor
@itemx +nativemonitor
Enable/Disable native monitor.
(@code{NativeMonitor=1}, @code{NativeMonitor=0}).

@findex -monlog, +monlog
@item -monlog
@itemx +monlog
Enable/Disable logging monitor output to a file.
(@code{MonitorLogEnabled=1}, @code{MonitorLogEnabled=0}).

@findex -monlogname
@item -monlogname <name>
Specify logfile name for the monitor.
(@code{MonitorLogFileName}).

@findex -monchislines
@item -monchislines <value>
Set number of lines to keep in the cpu history. (only when enabled in configure)
(@code{MonitorChisLines}).

@findex -monscrollbacklines
@item -monscrollbacklines <value>
Set number of lines to keep in the monitor scrollback buffer (-1 for no limit).
(@code{MonitorScrollbackLines}).

@findex -monitorfont
@item -monitorfont <font-description>
Set the monitor font for the Gtk3 UI's VTE-monitor.
(@code{MonitorFont}).

@findex -monitorfg
@item -monitorfg <colour-description>
Set the monitor foreground colour for the Gtk3 UI's VTE-monitor.
(@code{MonitorFG}).

@findex -monitorbg
@item -monitorbg <colour-description>
Set the monitor background colour for the Gtk3 UI's VTE-monitor.
(@code{MonitorFG}).

@findex -monitorxpos
@item -monitorxpos <X-position>
Set window X position for the Gtk3 UI's VTE-monitor.
(@code{MonitorXPos}).

@findex -monitorypos
@item -monitorxpos <Y-position>
Set window Y position for the Gtk3 UI's VTE-monitor.
(@code{MonitorYPos}).

@findex -monitorwidth
@item -monitorwidth <width>
Set window width for the Gtk3 UI's VTE-monitor.
(@code{MonitorWidth}).

@findex -monitorheight
@item -monitorheight <height>
Set window height for the Gtk3 UI's VTE-monitor.
(@code{MonitorHeight}).


@end table

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

@c @node FIXME
@section RAM init pattern settings

The initial content of uninitialized RAM depends on many factors, the inner
workings of the RAM chip, the motherboard, etc. Generally, many RAM chips are
build in a way that - however - at powerup about half the bits turn out 1, and
about the other half turns out 0. As a consequence, and depending on what kind
of RAM chips have been used in what kind of way, the typical patterns can be
"seen" by the CPU right after powerup.

VICE tries to model (some of) the real patterns accurately. Please be aware of
the fact that there is - technically buggy - software out there that will only
work with a certain RAM init pattern.

How generating the pattern works is easily described in three simple steps:

1. A base pattern is created using blocks of @code{RAMInitStartValue}, which
   is inverted every @code{RAMInitValueInvert} bytes. This pattern can be offset
   ("rotated") by @code{RAMInitValueOffset} bytes. This step creates the typical
   00 00 ff ff ff ff 00 00 etc patterns.

2. Every @code{RAMInitPatternInvert} bytes the base pattern is inverted 
   ("xored") by @code{RAMInitPatternInvertValue}. This step creates the inverted
   pattern every $4000 or so bytes that is typical for some boards/ICs. It may
   also create the 0x99, 0x66 based patterns that show up on other setups.

3. Every @code{RAMInitRepeatRandom} bytes @code{RAMInitStartRandom} bytes are
   randomly inverted ("xored"). Additionally every bit is randomly inverted with
   a @code{RAMInitRandomChance} : 4096 chance. This step creates the typical
   random bytes that have been observed with some boards/ICs.

@c @node FIXME
@subsection RAM init pattern resources

@table @code

@vindex RAMInitStartValue
@item RAMInitStartValue
Integer specifying the first value of the base pattern
(all emulators except vsid).
(0..255)

@vindex RAMInitValueInvert
@item RAMInitValueInvert
Integer specifying the number of bytes until the base pattern is inverted
(all emulators except vsid).

@vindex RAMInitValueOffset
@item RAMInitValueOffset
Integer specifying the number of bytes to offset the base pattern
(all emulators except vsid).

@vindex RAMInitPatternInvert
@item RAMInitPatternInvert
Integer specifying the length of the memory block when inverting the base pattern
(all emulators except vsid).

@vindex RAMInitPatternInvertValue
@item RAMInitPatternInvertValue
Integer specifying the value to use for inverting the base pattern with
(all emulators except vsid).

@vindex RAMInitStartRandom
@item RAMInitStartRandom
Integer specifying the number of random bytes in the random pattern
(all emulators except vsid).

@vindex RAMInitRepeatRandom
@item RAMInitRepeatRandom
Integer specifying the number of bytes after which to repeat the random pattern
(all emulators except vsid).

@vindex RAMInitRandomChance
@item RAMInitRandomChance
Integer specifying the chance of any bit to randomly toggle (0-4096)
(all emulators except vsid).

@end table

@c @node FIXME
@subsection RAM init pattern command-line options

@table @code

@findex -raminitstartvalue
@item -raminitstartvalue <value>
Set the first value of the base pattern
(@code{RAMInitStartValue})
(all emulators except vsid).
(0..255)

@findex -raminitvalueinvert
@item -raminitvalueinvert <num of bytes>
Set the number of bytes until the base pattern is inverted
(@code{RAMInitValueInvert})
(all emulators except vsid).

@findex -raminitvalueoffset
@item -raminitvalueoffset <num of bytes>
Offset the first pattern by <num> of bytes
(@code{RAMInitValueOffset})
(all emulators except vsid).

@findex -raminitpatterninvert
@item -raminitpatterninvert <num of bytes>
Set the length of the memory block when inverting the base pattern
(@code{RAMInitPatternInvert})
(all emulators except vsid).

@findex -raminitpatterninvertvalue
@item -raminitpatterninvertvalue <value>
Set the value to invert the base pattern with
(@code{RAMInitPatternInvertValue})
(all emulators except vsid).

@findex -raminitstartrandom
@item -raminitstartrandom <num of bytes>
Set the number of random bytes in the random pattern
(@code{RAMInitStartRandom})
(all emulators except vsid).

@findex -raminitrepeatrandom
@item -raminitrepeatrandom <num of bytes>
Set the number of bytes after which to repeat the random pattern
(@code{RAMInitRepeatRandom})
(all emulators except vsid).

@findex -raminitrandomchance
@item -raminitrandomchance <value>
Set the chance of any bit to randomly toggle (0-4096)
(@code{RAMInitRandomChance})
(all emulators except vsid).

@end table

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

@c @node FIXME
@section Debug settings

@c @node FIXME
@subsection Debug resources

@table @code

@vindex DebugCartEnable
@item DebugCartEnable
Boolean specifying whether the debug "cartridge" used for the test suite is enabled.

@b{The following are only available when the emulators were compiled in DEBUG mode:}

@vindex TraceMode
@item TraceMode
Integer specifying the trace mode (0=normal 1=small 2=history)

@vindex AutoPlaybackFrames
@item AutoPlaybackFrames
Amount of automatic playback frames

@vindex MainCPU_TRACE
@item MainCPU_TRACE
Trace the main CPU / Do not trace the main CPU
@vindex Drive0CPU_TRACE
@item Drive0CPU_TRACE
Trace the drive 0 CPU / Do not trace the drive 0 CPU
@vindex Drive1CPU_TRACE
@item Drive1CPU_TRACE
Trace the drive 1 CPU / Do not trace the drive 1 CPU
@vindex Drive2CPU_TRACE
@item Drive2CPU_TRACE
Trace the drive 2 CPU / Do not trace the drive 2 CPU
@vindex Drive3CPU_TRACE
@item Drive3CPU_TRACE
Trace the drive 3 CPU / Do not trace the drive 3 CPU

@vindex IEC_TRACE
@item IEC_TRACE
Trace IEC bus activity / Do not trace IEC bus activity

@end table

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

@table @code

@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 -debugcart, +debugcart
@item -debugcart
@itemx +debugcart
Enable/disable the debug "cartridge" used for the test suite.

@b{The following are only available when the emulators were compiled in DEBUG mode:}

@findex -trace_maincpu, +trace_maincpu
@item -trace_maincpu
@itemx +trace_maincpu
Trace the main CPU / Do not trace the main CPU (@code{MainCPU_TRACE=1}, @code{MainCPU_TRACE=0})

@findex -trace_drive0, +trace_drive0
@item -trace_drive0
@itemx +trace_drive0
Trace the drive 0 CPU / Do not trace the drive 0 CPU (@code{Drive0CPU_TRACE=1}, @code{Drive0CPU_TRACE=0})

@findex -trace_drive1, +trace_drive1
@item -trace_drive1
@itemx +trace_drive1
Trace the drive 1 CPU / Do not trace the drive 1 CPU (@code{Drive1CPU_TRACE=1}, @code{Drive1CPU_TRACE=0})

@findex -trace_drive2, +trace_drive2
@item -trace_drive2
@itemx +trace_drive2
Trace the drive 2 CPU / Do not trace the drive 2 CPU (@code{Drive2CPU_TRACE=1}, @code{Drive2CPU_TRACE=0})

@findex -trace_drive3, +trace_drive3
@item -trace_drive3
@itemx +trace_drive3
Trace the drive 3 CPU / Do not trace the drive 3 CPU (@code{Drive3CPU_TRACE=1}, @code{Drive3CPU_TRACE=0})

@findex -trace_iec, +trace_iec
@item -trace_iec
@itemx +trace_iec
Trace IEC bus activity / Do not trace IEC bus activity (@code{IEC_TRACE=1}, @code{IEC_TRACE=0})

@findex -trace_mode
@item -trace_mode <value>
Trace mode (0=normal 1=small 2=history)

@findex -autoplaybackframes
@item -autoplaybackframes <frames>
Set the amount of automatic playback frames

@end table

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

@c @node FIXME
@section Network Play settings

Note network play code is still experimental and unstable in some corners and
can be a bit tricky to setup and made work:

@itemize @bullet
@item First make sure both client and server can actually use the port you want
to use. This might require poking holes into your firewall. On the server side,
this often requires configuring port forwarding.
@item Choose a port you want to use. Usually the default (6502) is fine.
@item Setup the server address, usually you can leave it blank - if that
does not work you might have to use the actual IP of your machine. Start the
server and leave the settings before you continue.
@item On the client setup the remote address of the server (use 127.0.0.1 to
connect to another VICE instance running on the same machine) and connect to the server.
@end itemize

The experimental nature of this feature also means that you might require both
involved parties to use the exact same version of VICE.

@c @node FIXME
@subsection Network Play resources

@table @code

@vindex NetworkServerName
@item NetworkServerName
String specifying the name of the remote server. The client specifies here to what
remote machine it wants to connect. To connect to another instance of VICE running
on the same machine use 127.0.0.1.

@vindex NetworkServerBindAddress
@item NetworkServerBindAddress
String specifying the IP of the remote server. The server specifies here at what
IP it listens. This can be blank in common setups.

@vindex NetworkServerPort
@item NetworkServerPort
Integer specifying the port used for network play. This must be a number > 1023
(non privileged) and must be the same on both server and client.

@vindex NetworkControl
@item NetworkControl
Integer containing a bitfield that specifies which resources are controlled by
either the server or the client:
@multitable @columnfractions .05 .2 .2
@item Bit
@tab Resource
@tab controlled by
@item 0
@tab Keyboard
@tab Server
@item 1
@tab Joystick port 1
@tab Server
@item 2
@tab Joystick port 2
@tab Server
@item 3
@tab Devices
@tab Server
@item 4
@tab Resources
@tab Server
@item 5
@tab Keyboard
@tab Client
@item 6
@tab Joystick port 1
@tab Client
@item 7
@tab Joystcik port 2
@tab Client
@item 8
@tab Devices
@tab Client
@item 9
@tab Resources
@tab Client
@end multitable

@end table

@c @node FIXME
@subsection Network Play command-line options

@table @code

@findex -netplayserver
@item -netplayserver <name>
Set the name of the remote server (@code{NetworkServerName}).

@findex -netplaybind
@item -netplaybind <ip>
Set the IP of the remote server (@code{NetworkServerBindAddress}).

@findex -netplayport
@item -netplayport <port>
Set the port used for network play (@code{NetworkServerPort}).

@findex -netplayctrl
@item -netplayctrl <flag>
Specify what resources are controlled by the server or the client (see above)
(@code{NetworkControl}).

@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 LogFileName
@item LogFileName
String specifying the filename of the current log file.

@vindex ExitScreenshotName
@item ExitScreenshotName
String specifying the filename of a screenshot file that will be written when the emulator exits.

@vindex ExitScreenshotName1
@item ExitScreenshotName1
String specifying the filename of a screenshot file that will be written when the emulator exits. (x128)

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

@vindex AttachDevice8d0Readonly
@vindex AttachDevice9d0Readonly
@vindex AttachDevice10d0Readonly
@vindex AttachDevice11d0Readonly
@item AttachDevice8d0Readonly
@itemx AttachDevice9d0Readonly
@itemx AttachDevice10d0Readonly
@itemx AttachDevice11d0Readonly
Booleans that specify whether to attach images on drives 8 to 11 read-only or not
(all emulators except vsid).

@vindex AttachDevice8d1Readonly
@vindex AttachDevice9d1Readonly
@vindex AttachDevice10d1Readonly
@vindex AttachDevice11d1Readonly
@item AttachDevice8d1Readonly
@itemx AttachDevice9d1Readonly
@itemx AttachDevice10d1Readonly
@itemx AttachDevice11d1Readonly
Booleans that specify whether to attach images on the second drive of dual-drives 8 to 11 read-only or not
(all emulators except vsid).

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

@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

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.

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

@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

Use cartconv to convert .bin images to .crt format.

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 will have to select the correct type of cartridge first,
or 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 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).

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
CMD RAMlink
@item
IEEE-488 Interface 
(@uref{http://www.funet.fi/pub/cbm/schematics/cartridges/c64/ieee-488/eprom.bin})
@item
IEEE Flash 64! interface
@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 4KiB, 8KiB and 16KiB game- and ultimax cartridges
@item
Action Replay V5
@item
Action Replay MK2
@item
Action Replay MK3
@item
Action Replay MK4
@item
Atomic Power
@item
BIS-Plus
@item
Blackbox V3
@item
Blackbox V4
@item
Blackbox V8
@item
Blackbox V9
@item
C64 Games System
@item
Capture
@item
Comal 80
@item
Dela EP64
@item
Dela EP7x8
@item
Dela EP256
@item
Diashow-Maker
@item
Dinamic
@item
Easy Calc
@item
EasyFlash
@item
Epyx FastLoad
@item
EXOS
@item
The Final Cartridge
@item
The Final Cartridge III
@item
Final Cartridge Plus
@item
Formel 64
@item
Freeze Frame
@item
Freeze Frame MK2
@item
Freeze Machine
@item
Fun Play / Powerplay
@item
Game Killer
@item
GMod2
@item
GMod3
@item
H.E.R.O. bootleg
@item
IDE64 (@uref{http://www.ide64.org})
@item
KCS Power Cartridge
@item
Kingsoft
@item
Lt. Kernal Host Adaptor
@item
MACH 5
@item
Magic Desk
@item
Magic Formel
@item
MAX Basic
@item
Mikro Assembler
@item
MMC Replay
@item
Ocean
@item
Pagefox
@item
Prophet64
@item
REX 256KiB EPROM Cart
@item
REX RAM-Floppy
@item
REX Utility
@item
Retro Replay
@item
RGCD
@item
RR-Net MK3
@item
ROSS
@item
SD-BOX
@item
Silverrock 128
@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
Turtle Graphics II
@item
Warp Speed
@item
Westermann Learning
@item
Zaxxon
@item
ZIPP-CODE 48
@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,
Swiftlink 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 an IEEE interface for the
emulator. You can use the Commodore IEEE-488 interface, or the Skyles Electric
Works IEEE Flash! 64 interface.

To use the Commodore interface, follow these 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.

To use the IEEE Flash! 64 interface, follow these steps:

Download the IEEE Flash! 64 ROM image (uploaded to the CBM archives but not yet
in place).  Set the path to the ROM image using the UI under Cartridges/IEEE
Flash! 64 settings, the commandline argument -ieeeflash64image, or the
IEEEFlash64Image resource setting.  Then you can Enable the interface and choose
which devices to route to the IEEE bus using the other IEEE Flash! 64 settings.
With this interface, you can mix and match IEC and IEEE drives.

@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
@subsubsection CMD RAMLink
The CMD RAMLink can operate standalone using its own RAMCard or with an REU,
GEORAM, or RAMDrive (only one) which is inserted into the RAM port.
The RAMLink is essentially a builtin high capacity RAMDOS with battery backup
support.
This "backup" support can be emulated through the use of images.
Initially it will "format" the memory so each has their own native parition
on drive 16.
Paritions and the device number can be changed with the CMD "RAM-tools".
The latest RAMLink firmware (2.01) can not handle REU sizes greater than 8 MiB,
or GEORAM sizes beyond 2 MiB, as the firmware will hang on size detection.

The RAMLink also features a parallel port (similar to IEEE-488 interface)
which allows faster transfers to the CMD HD series drives.
The "cabling" is automatically performed by VICE and the RAMLink firmware will
detect the cable presence and use it automatically.
However, some programs may have compatibility issues (notably the CMD HD-tools
with older HD boot roms).
When connecting an empty image, or an image without a HD-DOS signature, the
cable will be automatically disconnected.
Although documented in the RAMLink manual, the JiffyDOS command "@@P0" to
disable, or "@@P1" to enable parallel transfers will hang as they try to
communicate the HD boot rom and fail.
To resolve this, use the "Drive#ParallelCable" or command line switch
"-parallel#" and set it to 0, to disable transfers; any other value will
enable them.

The RAMLink features an "Enable/Disable" switch that can be changed at
anytime using the GUI options.
Prior to disabling, the JiffyDOS "@@Q" command should be issued to remove the
JiffyDOS system vectors. See the manual for how to reactivate JiffyDOS.
It is not recommended to change the REU, GEORAM, or RAMCard size as the
CMD RAMDOS was not designed to detect this. Any changes should be followed
by a machine reset.

The RAMLink also has a "Normal/Disable" switch which can also be changed at
anytime.
Normal, the default, only allows RAMLink access to the RAM port (REU, GEORAM,
and RAMDrive); their registers are hidden otherwise.
Direct exposes their registers all the time. This can lead to potential
data corruption of the data on the RAM expansion devices as RAMLink can not
guarantee its access is exclusive.

RAMLink is also compatible with the CMD SuperCPU 64, however it requires the
official SuperCPU ROM (2.04) along with the RAMLink ROM to properly detect and
utilize all the RAMLink features.

@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 the default cartridge.

The following cartridge types are valid:

@itemize @bullet
@item
- 6: Ultimax
@item
- 3: Generic 8KiB
@item
- 2: Generic 16KiB
@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 256KiB 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 128KiB Cartridge
@item
56: Formel 64
@item
57: RGCD
@item
58: RR-Net MK3
@item
59: EasyCalc
@item
60: GMod2
@item
61: MAX Basic
@item
62: GMod3
@item
63: ZIPP-CODE 48
@item
64: Blackbox V8
@item
65: Blackbox V3
@item
66: Blackbox V4
@item
67: REX RAM-Floppy
@item
68: BIS-Plus      
@item
69: SD-BOX
@item
70: MultiMAX
@item
71: Blackbox V9
@item
72: Lt. Kernal Host Adaptor
@item
73: RAMLink
@item
74: H.E.R.O. bootleg
@item
75: IEEE Flash! 64
@item
76: Turtle Graphics II
@item
77: Freeze Frame MK2
@item
78: Partner 64
@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 GMod2EEPROMImage
@item GMod2EEPROMImage
String that specifies the name of the raw GMod2 EEPROM image.

@vindex GMod2FlashWrite
@item GMod2FlashWrite
Boolean that specifies wether writes to GMod2 EEPROM image are enabled.

@vindex GMod2EEPROMRW
@item GMod2EEPROMRW
Boolean that specifies wether the GMod2 ROM is saved at exit

@vindex GMod3FlashWrite
@item GMod3FlashWrite
Boolean that specifies wether changes to GMod3 EEPROM image are written back to the cartridge image.

@vindex IDE64version
@item IDE64version
Integer specifying whether the emulated card version is V3.4, V4.1 or V4.2. 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 IDE64ClockPort
@item IDE64ClockPort
Integer that specifies the enabled IDE64 Clockport device. (0: None, 2: RRNet, 4: MP3@@64)

@vindex SBDIGIMAX
@item SBDIGIMAX
Boolean that specifies whether the Short Bus DigiMAX expansion is enabled.

@vindex SBDIGIMAXbase
@item SBDIGIMAXbase
Integer specifying the Base address of the Short Bus DigiMAX expansion. (0xDE40/0xDE48)

@vindex SBETFE
@item SBETFE
Boolean specifying whether the Short Bus ETFE expansion is enabled

@vindex SBETFEbase
@item SBETFEbase
Integer specifying the Base address of the Short Bus ETFE expansion. ($de00, $de10, $df00)

@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 IEEEFlash64
@item IEEEFlash64
Boolean specifying whether the IEEE Flash! 64 interface should be emulated or not.

@vindex IEEEFlash64Image
@item IEEEFlash64Image
String specifying the filename of the IEEE Flash! 64 KERNAL ROM image.

@vindex IEEEFlash64Dev8
@vindex IEEEFlash64Dev910
@vindex IEEEFlash64Dev4
@item IEEEFlash64Dev8
@itemx IEEEFlash64Dev910
@itemx IEEEFlash64Dev4
Booleans indicating whether to route devices 8, 9 and 10, and 4 respectively to the
IEEE bus (1) or IEC bus (0).

@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 LTKimage0
@vindex LTKimage1
@vindex LTKimage2
@vindex LTKimage3
@vindex LTKimage4
@vindex LTKimage5
@vindex LTKimage6
@item LTKimage0
@itemx LTKimage1
@itemx LTKimage2
@itemx LTKimage3
@itemx LTKimage4
@itemx LTKimage5
@itemx LTKimage6
Strings specifying the full path to up to seven harddisk images. If a file is 
non-existing the drive is not emulated. The first drive is necessary.

@vindex LTKio
@item LTKio
Integer specifying the Base address of the I/O interface. (1: $de00, 2: $df00) 
Default is $df00.

@vindex LTKport
@item LTKport
Integer specifying the port number in multiplexed multi-computer/single-disk 
configurations. (0 to 15) Default is 0, the master.

@vindex LTKserial
@item LTKserial
String specifying the serial number. It must be in the form "00000000" with all 
numeric digits. Default is 87000000. LTK DOS install disks are locked to their 
respective LTK host adapor boot ROM. This setting will override the boot ROM 
value.  The floppy disk serial number can be changed with a sector editor on 
track 18, sector 18.

@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 MMC64ClockPort
@item MMC64ClockPort
Integer that specifies the clockport device used.
(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID)

@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 MMCRClockPort
@item MMCRClockPort
Integer that specifies the clockport device.
(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID)

@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 KiB.
(64, 128)

@vindex RAMLINK 
@item RAMLINK 
Boolean specifying whether the RAMLink module should be emulated or not.
This option emulates the behavior of the enable/disable switch on the unit.

@vindex RAMLINKBIOSfilename
@item RAMLINKBIOSfilename
String specifying the filename of the RAMLINK ROM image.

@vindex RAMLINKfilename
@item RAMLINKfilename
String specifying the filename of the RAMCard image.

@vindex RAMLINKImageWrite
@item RAMLINKImageWrite
Boolean, if true write back the RAMCard image file automatically, in case the
RAM contents changed, when detaching or quitting the emulator.

@vindex RAMLINKsize
@item RAMLINKsize
Integer specifying the size of the RAMCard in MiB. (0..16; default is 0)

@vindex RAMLINKmode
@item RAMLINKmode
Integer specifying the mode of the RAMLink. "1", the default, (Normal) only
allows RAMLink access to the RAM port (REU, GEORAM, and RAMDrive); their
registers are hidden otherwise. "0" (Direct) exposes their registers all the
time. This option emulates the behavior of the Normal/Direct switch on the unit.

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

@vindex RRFfilename
@item RRFfilename
String that specifies the filename for the REX RAM-Floppy RAM image

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

@vindex RGCDrevision
@item RGCDrevision
Integer specifying the RGCD-cartridge hardware variant.
(0: RGCD 64k, 1: Hucky's EPROM Cartridge)

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

@vindex RRClockPort
@item RRClockPort
Integer that specifies the clockport device.
(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID)

@vindex RRNETMK3_flashjumper
@item RRNETMK3_flashjumper
Boolean specifying whether the RRNETMK3 Flash Jumper is set.

@vindex RRNETMK3_bios_write
@item RRNETMK3_bios_write
Boolean specifying whether to save the RRNETMK3 bios when changed.

@vindex SSRamExpansion
@item SSRamExpansion
Boolean, if true enable the 32KiB addon RAM of the Supersnapshot V5

@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 8KiB cartridge image.

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

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

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

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

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

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

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

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

@findex -cartbis
@item -cartbis <name>
Attach raw 8KiB BIS-Plus cartridge image.

@findex -cartbb3
@item -cartbb3 <name>
Attach raw 8KiB Blackbox V3 cartridge image.

@findex -cartbb4
@item -cartbb4 <name>
Attach raw 16KiB Blackbox V4 cartridge image.

@findex -cartbb8
@item -cartbb8 <name>
Attach raw 32/64KiB Blackbox V8 cartridge image.

@findex -cartbb9
@item -cartbb9 <name>
Attach raw 32KiB Blackbox V9 cartridge image.

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

@findex -cartcomal
@item -cartcomal <name>
Attach raw 64KiB 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 128KiB Dinamic cartridge image.

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

@findex -cartdqbb
@item -cartdqbb <name>
Attach raw 16KiB 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 -carteasycalc
@item -carteasycalc <name>
Attach raw 24KiB Easy Calc Result 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 8KiB Epyx FastLoad cartridge image.

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

@findex -cartexpert
@item -cartexpert <name>
Attach raw 8KiB 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 32KiB Formel 64 image.

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

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

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

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

@findex -cartff2
@item -cartff2 <name>
Attach raw 16KiB Freeze Frame MK2 image.

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

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

@findex -cartgmod2
@item -cartgmod2 <name>
Attach raw GMod2 cartridge image.

@findex -gmod2eepromimage
@item -gmod2eepromimage <name>
Attach raw GMod2 EEPROM image (@code{GMod2EEPROMImage}).

@findex -gmod2eepromrw, +gmod2eepromrw
@item -gmod2eepromrw
@itemx +gmod2eepromrw
Enable/Disable writes to GMod2 EEPROM image (@code{GMod2EEPROMRW=1}, @code{GMod2EEPROMRW=0}).

@findex -gmod2flashwrite, +gmod2flashwrite
@item -gmod2flashwrite
@itemx +gmod2flashwrite
Enable/Disable saving of the GMod2 ROM at exit (@code{GMod2FlashWrite=1}, @code{GMod2FlashWrite=0}).

@findex -cartgmod3
@item -cartgmod3 <name>
Attach raw GMod3 cartridge image.

@findex -gmod3flashwrite, +gmod3flashwrite
@item -gmod3flashwrite
@itemx +gmod3flashwrite
Enable/Disable saving of the GMod3 ROM at exit (@code{GMod3FlashWrite=1}, @code{GMod3FlashWrite=0}).

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

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

@findex -cartdrean
@item -cartdrean <name>
Attach raw 32KiB H.E.R.O. bootleg cartridge image

@findex -cartide64
@item -cartide64 <name>
Attach raw 64KiB or 128KiB 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 -IDE64version
@item -IDE64version <value>
Select IDE64 version V3 (0), V4.1 (1) or V4.2 (2).
(@code{IDE64version}).
(0..2)

@findex -IDE64USB, +IDE64USB
@item -IDE64USB
@itemx +IDE64USB
Enable/Disable IDE64 USB server
@findex -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 -ide64clockportdevice
@item -ide64clockportdevice
Enable IDE64 Clockport device (0: None, 2: RRNet, 4: MP3@@64)
(@code{IDE64ClockPort}).

@findex -sbdigimax, +sbdigimax
@item -sbdigimax
@itemx +sbdigimax
Enable/Disable the Short Bus DigiMAX expansion (@code{SBDIGIMAX}).

@findex -sbdigimaxbase
@item -sbdigimaxbase
Set Base address of the Short Bus DigiMAX expansion (0xDE40/0xDE48) (@code{SBDIGIMAXbase}).

@findex -sbetfe, +sbetfe
@item -sbetfe
@itemx +sbetfe
Enable/Disable the Short Bus ETFE expansion (@code{SBETFE}).

@findex -sbetfebase
@item -sbetfebase
Set Base address of the Short Bus ETFE expansion (56832: $de00, 56848: $de10, 57088: $df00) (@code{SBETFEbase}).

@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 -ieeeflash64, +ieeeflash64
@item -ieeeflash64
@itemx +ieeeflash64
Enable/disable IEEE Flash! 64 interface
(@code{IEEEFlash64}).

@findex -ieeeflash64image
@item -ieeeflash64image
Set IEEE Flash! 64 ROM image name
(@code{IEEEFlash64Image}).

@findex -ieeeflash64dev8, +ieeeflash64dev8
@item -ieeeflash64dev8
@itemx +ieeeflash64dev8
Route/do not route device 8 to IEEE bus of IEEE Flash! 64 interface
(@code{IEEEFlash64Dev8}).

@findex -ieeeflash64dev910, +ieeeflash64dev910
@item -ieeeflash64dev910
@itemx +ieeeflash64dev910
Route/do not route devices 9 and 10 to IEEE bus of IEEE Flash! 64 interface
(@code{IEEEFlash64Dev910}).

@findex -ieeeflash64dev4, +ieeeflash64dev4
@item -ieeeflash64dev4
@item +ieeeflash64dev4
Route/do not route device 4 to IEEE bus of IEEE Flash! 64 interface
(@code{IEEEFlash64Dev4}).

@findex -cartieeeflash64
@item -cartieeeflash64 <Name>
Attach raw 8KiB IEEE Flash! 64 cartridge image

@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 2KiB 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 16KiB KCS Power cartridge image.

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

@findex -cartltk
@item -cartltk <name>
Attach raw Lt. Kernal Host Adaptor cartridge image.

@findex -ltkimage0
@item -ltkimage0 <name>
@findex -ltkimage1
@item -ltkimage1 <name>
@findex -ltkimage2
@item -ltkimage2 <name>
@findex -ltkimage3
@item -ltkimage3 <name>
@findex -ltkimage4
@item -ltkimage4 <name>
@findex -ltkimage5
@item -ltkimage5 <name>
@findex -ltkimage6
@item -ltkimage6 <name>
Strings specifying the full path to up to seven harddisk images. If a file is 
non-existing the drive is not emulated. The first drive is necessary.
(@code{ltkimage0}, @code{ltkimage1}, @code{ltkimage2}, @code{ltkimage3}, 
@code{ltkimage4}, @code{ltkimage5}, @code{ltkimage6}).

@findex -ltkio
@item -ltkio <value>
Integer specifying the Base address of the I/O interface. (1: $de00, 2: $df00) 
Default is $df00.

@findex -ltkport
@item -ltkport <value>
Integer specifying the port number in multiplexed multi-computer/single-disk 
configurations. (0..15) Default is 0, the master.

@findex -ltkserial
@item -ltkserial <name>
String specifying the serial number. It must be in the form "00000000" with all 
numeric digits. Default is 87000000. LTK DOS install disks are locked to their 
respective LTK host adapor boot ROM. This setting will override the boot ROM 
value.  The floppy disk serial number can be changed with a sector editor on 
track 18, sector 18.

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

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

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

@findex -cartmax
@item -cartmax <name>
Attach raw MAX Basic cartridge image.

@findex -cartmm
@item -cartmm <name>
Attach raw MultiMAX cartridge image.

@findex -cartmikro
@item -cartmikro <name>
Attach raw 8KiB 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 8KiB 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 -mmc64clockportdevice
@item -mmc64clockportdevice <device>
Set MMC64 clockport device
(@code{MMC64ClockPort})
(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID)

@findex -cartmmcr
@item -cartmmcr <name>
Attach raw 512KiB 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 -mmcrclockportdevice
@item -mmcrclockportdevice <id>
Set MMC Replay clockport device
(@code{MMCRClockPort}).
(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID)

@findex -cartmv
@item -cartmv <name>
Attach raw 16KiB 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 256KiB Prophet 64 cartridge image.

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

@findex -cartpartner64
@item -cartpartner64 <name>
Attach raw 16KiB Partner 64 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 KiB>
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 -ramlink, +ramlink
@item -ramlink
@itemx +ramlink
Enable/disable emulation of the RAMLink module. This option emulates the
behavior of the enable/disable switch on the unit
(@code{RAMLINK=1}, @code{RAMLINK=0}).

@findex -cartramlink
@item -cartramlink <name>
Attach the raw 64 KiB ROM image.

@findex -ramlinkbios
@item -ramlinkbios <name>
Specify name of RAMLink BIOS image
(@code{RAMLINKBIOSfilename}).

@findex -ramlinkbios
@item -ramlinkbios <name>
Specify name of RAMLink BIOS image
(@code{RAMLINKBIOSfilename}).

@findex -ramlinkimage
@item -ramlinkimage <name>
Specify name of RAMLink RAMCard image
(@code{RAMLINKfilename}).

@findex -ramlinkimagerw, +ramlinkimagerw
@item -ramlinkimagerw
@itemx +ramlinkimagerw
Allow/disallow writing to RAMCard image on detach
(@code{RAMLINKImageWrite=1}, @code{RAMLINKImageWrite=0}).

@findex -ramlinksize
@item -ramlinksize <size in MiB>
Size of the RAMCard unit
(@code{RAMLINKsize}).
(0..16; default is 0)

@findex -ramlinkmode
@item -ramlinkmode <value>
Sets the RAM port mode of the unit. "1", the default, (Normal) only
allows RAMLink access to the RAM port (REU, GEORAM, and RAMDrive); their
registers are hidden otherwise. "0" (Direct) exposes their registers all the
time. This option emulates the behavior of the Normal/Direct switch on the unit.
(@code{RAMLINKmode}).
(1:normal (default), 0:direct)

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

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

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

@findex -rgcdrev
@item -rgcdrev <Revision>
Set the RGCD-cartridge hardware variant.
(@code{RGCDrevision}).
(0: RGCD 64k, 1: Hucky's EPROM Cartridge)

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

@findex -cartrrnet
@item -cartrrnet <name>
Attach raw 8KiB RR-Net MK3 cartridge image.

@findex -cartrr
@item -cartrr <name>
Attach raw 64KiB 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 -rrclockportdevice
@item -rrclockportdevice <device>
Set the RR clockport device
(@code{RRClockPort})
(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID)

@findex -rrnetmk3flash,+rrnetmk3flash
@item -rrnetmk3flash
@itemx +rrnetmk3flash
SetRemove the RRNETMK3 Flash Jumper
(@code{RRNETMK3_flashjumper=1}, @code{RRNETMK3_flashjumper=0}).

@findex -rrnetmk3bioswrite, +rrnetmk3bioswrite
@item -rrnetmk3bioswrite
@itemx +rrnetmk3bioswrite
Save/Do not save the RRNETMK3 bios when changed
(@code{RRNETMK3_bios_write=1}, @code{RRNETMK3_bios_write=0}).

@findex -cartrrf
@item -cartrrf <name>
Attach raw 8KiB REX RAM-Floppy cartridge image.

@findex -rexramfloppyimage
@item -rexramfloppyimage <name>
Set filename for the REX RAM-Floppy RAM image
(@code{RRFfilename}).

@findex -rexramfloppyimagerw, +rexramfloppyimagerw
@item -rexramfloppyimagerw
@itemx +rexramfloppyimagerw
Save/Do not save the REX RAM-Floppy RAM when changed
(@code{RRFImageWrite=1}, @code{RRFImageWrite=0}).

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

@findex -cartsdbox
@item -cartsdbox <name>
Attach raw 128KiB SD-BOX cartridge image.

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

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

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

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

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

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

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

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

@findex -ssramexpansion, +ssramexpansion
@item -ssramexpansion
@itemx +ssramexpansion
Enable/disable 32KiB addon RAM.
(@code{SSRamExpansion=1}, @code{SSRamExpansion=0}).

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

@findex -cartturtle
@item -cartturtle <name>
Attach raw 16KiB Turtle Graphics II cartridge image.

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

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

@findex -cartzaxxon
@item -cartzaxxon <name>
Attach raw 16KiB Zaxxon cartridge image.

@findex -cartzipp
@item -cartzipp <name>
Attach raw 8KiB ZIPP-CODE 48 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, for example:

@itemize @bullet
@item
@file{pepto-pal.vpl} (``Pepto PAL''), a Palette calculated by Philip "Pepto" Timmermann
(@uref{http://www.pepto.de/projects/colorvic/}). (This is the default)
@item
@file{vice.vpl} (``VICE''), the old 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{https://frodo.cebix.net/}).
@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{https://www.godot64.de}).
@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 VICIIPALDelaylineType
@item VICIIPALDelaylineType
Integer specifying the type of delay line used in the CRT (0: normal, 1: U only (1084 style))

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

@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 -VICIIcrtdelaylinetype
@item -VICIIcrtscanlineshade <type>
Type of delay line used in the CRT (0: normal, 1: U only (1084 style))
(@code{VICIIPALDelaylineType}).

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

@findex -VICIIshowstatusbar, +VICIIshowstatusbar
@item -VICIIshowstatusbar
@item +VICIIshowstatusbar
Show/hide status bar
(@code{VICIIShowStatusbar=1}, @code{VICIIShowStatusbar=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. Additionally there is "8580D", which refers to MOS8580 with added
"Digifix" modification, which adds a DC offset to audio-in, which makes classic
samples audible also on the 8580.

@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, 3: three extra sids, 4: four extra sids, 5: five extra sids, 6: six extra sids, 7: seven extra sids)

@vindex Sid2AddressStart
@item Sid2AddressStart
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 Sid3AddressStart
@item Sid3AddressStart
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 Sid4AddressStart
@item Sid4AddressStart
Integer specifying the base address of the fourth 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 Sid5AddressStart
@item Sid5AddressStart
Integer specifying the base address of the fifth 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 Sid6AddressStart
@item Sid6AddressStart
Integer specifying the base address of the sixth 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 Sid7AddressStart
@item Sid7AddressStart
Integer specifying the base address of the seventh 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 Sid8AddressStart
@item Sid8AddressStart
Integer specifying the base address of the eigth 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: 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, @code{3}: Fast Resampling)

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

@vindex SidResidGain
@item SidResidGain
Integer that specifies reSID gain in percent [97] (90..100) for 6581.

@vindex SidResidFilterBias
@item SidResidFilterBias
Integer that specifies reSID filter bias for 6581, which can be used to adjust DAC bias
in millivolts. [0] (-5000..5000)

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

@vindex SidResid8580Gain
@item SidResid8580Gain
Integer that specifies reSID gain in percent [97] (90..100) for 8580.

@vindex SidResid8580FilterBias
@item SidResid8580FilterBias
Integer that specifies reSID filter bias for 8580, which can be used to adjust DAC bias
in millivolts. [0] (-5000..5000)

@vindex SidResidEnableRawOutput
@item SidResidEnableRawOutput
Boolean specifying whether raw debug output is enabled. When enabled, the raw -
 not downsampled - audio data is written to a file called resid.raw in the current
 working directory.

@end table


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

@table @code

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

@findex -sid2address
@item -sid2address <Base address>
Specifies the start address for the second SID chip
(@code{Sid2AddressStart})
(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 -sid3address
@item -sid3address @code{ADDRESS}
Specifies the start address for the third SID chip
(@code{Sid3AddressStart})
(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 -sid4address
@item -sid4address @code{ADDRESS}
Specifies the start address for the fourth SID chip
(@code{Sid4AddressStart})
(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 -sid5address
@item -sid5address @code{ADDRESS}
Specifies the start address for the fifth SID chip
(@code{Sid5AddressStart})
(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 -sid6address
@item -sid6address @code{ADDRESS}
Specifies the start address for the sixth SID chip
(@code{Sid6AddressStart})
(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 -sid7address
@item -sid7address @code{ADDRESS}
Specifies the start address for the seventh SID chip
(@code{Sid7AddressStart})
(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 -sid8address
@item -sid8address @code{ADDRESS}
Specifies the start address for the eight SID chip
(@code{Sid8AddressStart})
(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}).

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

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

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

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

@findex -resid8580pass
@item -residpass @code{PERCENTAGE}
Specifies the resampling filter passband in percentage of the total
bandwidth (@code{SidResid8580Passband=0-90}) for 8580.

@findex -resid8580gain
@item -residgain @code{PERCENTAGE}
Specifies reSID gain in percent (90 - 100) for 8580.

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

@findex -residrawoutput, +residrawoutput
@item -residrawoutput
@itemx +residrawoutput
Boolean specifying whether raw debug output is enabled. When enabled, the raw -
 not downsampled - audio data is written to a file called resid.raw in the current
 working directory.

@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 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 ETHERNETCART_ACTIVE
@item ETHERNETCART_ACTIVE
Boolean that specifies whether the CS8900 ethernet interface emulation is active.
@vindex ETHERNETCARTMode
@item ETHERNETCARTMode
Boolean that specifies whether RR-Net compatible mapping is enabled.
@vindex ETHERNETCARTBase
@item ETHERNETCARTBase
Integer specifying the I/O base address of the emulated ethernet cartridge,

@vindex GEORAM
@item GEORAM
Boolean specifying whether the GEO-RAM cartridge should be emulated or not.
(x64, x64sc, x128).

@vindex GEORAMfilename
@item GEORAMfilename
String specifying the filename of the GEORAM image.
(x64, x64sc, x128).

@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.
(x64, x64sc, x128).

@vindex GEORAMsize
@item GEORAMsize
Integer specifying the size of the emulated GEO-RAM in KiB.
(512, 1024, 2048, 4096).
(x64, x64sc, x128).

@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, in case the RAM
contents changed, when detaching or quitting the emulator.

@vindex REUsize
@item REUsize
Integer specifying the size of the emulated REU in KiB.
(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

@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: userport, 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 KiB>
Size of the GEORAM expansion unit
(@code{GEORAMsize}).
(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 KiB>
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}).

@findex -ethernetcart, +ethernetcart
@item -ethernetcart
@itemx +ethernetcart
Disable/Enable the Ethernet Cartridge 
(@code{ETHERNETCART_ACTIVE}).
(TFE/RR-Net/64NIC/FB-NET)

@findex -ethernetcartmode
@item -ethernetcartmode <Mode>
Mode of Ethernet Cartridge
(@code{ETHERNETCARTMode}).
(0: TFE, 1: RR-Net)

@findex -ethernetcartbase
@item -ethernetcartbase <Base address>
Base address of the Ethernet Cartridge. 
(@code{ETHERNETCARTBase}) (0xDE00, 0xDE10, 0xDE20, 0xDE30, 0xDE40,
0xDE50, 0xDE60, 0xDE70, 0xDE80, 0xDE90, 0xDEA0, 0xDEB0, 0xDEC0, 0xDED0, 0xDEE0,
0xDEF0, 0xDF00, 0xDF10, 0xDF20, 0xDF30, 0xDF40, 0xDF50, 0xDF60, 0xDF70, 0xDF80,
0xDF90, 0xDFA0, 0xDFB0, 0xDFC0, 0xDFD0, 0xDFE0, 0xDFF0)

@findex -tfe
@item -tfe
Enable the Ethernet Cartridge in TFE ("The Final Ethernet") compatible mode and set default I/O address

@findex -rrnet
@item -rrnet
Enable the Ethernet Cartridge in RR-Net compatible mode and set default I/O address

@findex -burstmod
@item -burstmod <value>
Set the kind of burst modification. This emulates the fast serial bus connection
as described at @uref{https://a1bert.kapsi.fi/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-901227-03.bin}).

@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; Changing this resource
equals loading one of the provided kernal ROM files. It will be adjusted when
changing @code{KernalName}.

Valid values are:

@table @code
@item -1
Unknown kernal. This value can not be set by the user, it will be set when loading
a custom kernal via changing @code{KernalName}.
@item -2
No kernal. This is used by the MAX Machine.
@item 0
Kernal revision 0 (Japanese, 906145-02)
@item 1
Kernal revision 1 (901227-01)
@item 2
Kernal revision 2 (901227-02)
@item 3
Kernal revision 3 (901227-03)
@item 39
C64 GS (390852-01)
@item 67
SX-64 (251104-04)
@item 100
Commodore 4064 (also known as ``PET64'' or ``Educator 64'') (901246-01)
@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}).
(0/jap: japanese 1: rev. 1, 2: rev. 2, 3: rev. 3, 39/gs: C64 GS, 67/sx: sx64, 100/4064: 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 256KiB RAM image.

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

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

@vindex CPMCart
@item CPMCart
Boolean that specifies if a CP/M cartridge is attached.

@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 256KiB 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{KernalRev},
@code{ChargenName}, @code{SidEngine}, @code{SidModel})
(x64 and x64sc only).
(c64/c64c/c64old, ntsc/newntsc/oldntsc, drean, jap, c64gs, pet64, ultimax)

@findex -cpmcart, +cpmcart
@item -cpmcart
@itemx +cpmcart
Enable/disable the CP/M cartridge
(@code{CPMCart=1}, @code{CPMCart=0})

@end table

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

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

@c @node FIXME
@subsection C128 cartridge settings

x128 reuses the cartridge system from the C64 emulation, so all options listed
there apply as well. The following only lists what is different and/or additional.

@c @node FIXME
@subsubsection C128 cartridge resources

@table @code

@vindex CartridgeType
@item CartridgeType
Integer specifying the type of the default cartridge.

Additional to the C64 types, the following types are valid C128 CRT ID:

@itemize @bullet
@item
1: Warpspeed 128
@item
2: Partner 128
@item
3: Comal 80
@item
4: Magic Desk 128
@item
5: Gmod2-C128
@end itemize

Note: The actual value will be this ID added to the highest C64 CRT ID, so both
can coexist.

@vindex GMod128EEPROMImage
@item GMod128EEPROMImage
String that specifies the name of the raw GMod2-C128 EEPROM image.

@vindex GMod128FlashWrite
@item GMod128FlashWrite
Boolean that specifies wether writes to GMod2-C128 EEPROM image are enabled.

@vindex GMod128EEPROMRW
@item GMod128EEPROMRW
Boolean that specifies wether the GMod2-C128 ROM is saved at exit

@end table

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

@table @code

@findex -cartfrom
@item -cartfrom <name>
Attach generic external function ROM cartridge image.

@findex -cartcomal128
@item -cartcomal128 <name>
Attach 96k Comal 80 cartridge image.

@findex -cartgmod128
@item -cartgmod128 <name>
Attach 512k Gmod2-C128 cartridge image.

@findex -cartmd128
@item -cartmd128 <name>
Attach 16/32/64/128/256/512k/1M Magic Desk 128 cartridge image.

@findex -cartpartner128
@item -cartpartner128 <name>
Attach 16KiB Partner 128 cartridge image.

@findex -cartws128
@item -cartws128 <name>
Attach 16KiB Warpspeed 128 cartridge image.

@findex -gmod128eepromimage
@item -gmod128eepromimage <filename>
Specify Gmod2-C128 EEPROM image filename (@code{GMod128EEPROMImage}).

@findex -gmod128eepromrw, +gmod128eepromrw
@item -gmod128eepromrw
@itemx +gmod128eepromrw
Enable/Disable writes to Gmod2-C128 EEPROM image (@code{GMod128EEPROMRW=1}, @code{GMod128EEPROMRW=0}).

@findex -gmod128flashwrite, +gmod128flashwrite
@item -gmod128flashwrite
@itemx +gmod128flashwrite
Enable/Disable saving of the Gmod2-C128 ROM at exit (@code{GMod128FlashWrite=1}, @code{GMod128FlashWrite=0}).

@end table

@c @node FIXME
@subsection VDC settings

@c @node FIXME
@subsubsection VDC resources

@table @code

@vindex VDC64KB
@item VDC64KB
Boolean to enabled/disable full 64KiB 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}).

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

@findex -VDC64KB
@item -VDC64KB
Set the VDC memory size to 64KiB
(@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)

@findex -VDCshowstatusbar, +VDCshowstatusbar
@item -VDCshowstatusbar
@item +VDCshowstatusbar
Show/hide status bar
(@code{VDCShowStatusbar=1}, @code{VDCShowStatusbar=0}).

@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 ChargenNOName
@item ChargenNOName
String specifying the filename of the Norwegian 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.

@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 -chargno
@item -chargno <name>
Specify name of Norwegian character generator ROM image
(@code{ChargenNOName}).

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

@end table

@c @node FIXME
@subsection C128 settings

@c @node FIXME
@subsubsection C128 resources

@table @code

@c Rename to C128ColumnSwitch or so
@vindex C128ColumnKey
@item C128ColumnKey
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).

@vindex C128HideVDC
@item C128HideVDC
Boolean to enable/disable the VDC display window.

@vindex DualWindow
@item DualWindow
Boolean to turn on dual-window rendering, opening two windows, one for each display.

@end table

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

@table @code

@findex -40col
@item -40col
Activate 40 column mode
(@code{C128ColumnKey=1}).

@findex -80col
@item -80col
Activate 80 column mode
(@code{C128ColumnKey=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)

@findex -hidevdcwindow, +hidevdcwindow
@item -hidevdcwindow
@itemx +hidevdcwindow
Hide/show the VDC display window
(@code{C128HideVDC=1}, @code{C128HideVDC=0}).

@findex -dualwindow, +dualwindow
@item -dualwindow
Turn on dual-window rendering, opening two windows, one for each display.
(@code{DualWindow}).

@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 2MiB 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 2MiB (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

@findex -dtvblitterlog, +dtvblitterlog
@item -dtvblitterlog
@itemx +dtvblitterlog
Enable or disable DTV Blitter log

@findex -dtvdmalog, +dtvdmalog
@item -dtvdmalog
@itemx +dtvdmalog
Enable or disable DTV DMA log

@findex -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 2MiB of RAM and 2MiB of Flash, but only 64 KiB at a time.
The 64KiB bank can be selected with "bank ram00".."ram1f" for RAM and
"bank rom00".."rom1f" for Flash.

The "load" command can load large files (>64KiB) 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{https://a1bert.kapsi.fi/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 switch
(@code{JiffySwitch=1}, @code{JiffySwitch=0}).

@findex -speedswitch, +speedswitch
@item -speedswitch
@itemx +speedswitch
Enable/disable the speed switch
(@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

@subsection Using prg files

It's not alway easy to get VIC-20 games to work due to its different configurations.
To run VIC-20 games, you can try the following:

@itemize @bullet
@item
Try to autorun with different memory sets: "no expansion", "3KiB" and "Full"
@item
Load the file in a hex editor and have a look at the first two bytes. If they
are e.g. @code{00 A0} the file should probably be attached as a cartridge image at @code {$A000}.
@item
Some programs, (eg the loadable Scott Adams text adventures) have to be loaded
into the expanded memory blocks, and then run with the expansion disabled via
software, like this:

@itemize @bullet
@item
Enable the full memory expansion
@item
Disable the expanded memory
@example
POKE44,16:POKE56,30:POKE4096,0:new
POKE648,30
@end example
@item
Press @code{RUN/STOP + RESTORE} (which is @code{ESC + F12} on the default keymap)
@item
Load the program
@example
LOAD"4.Voodoo Castle",8,1
@end example
@item
Start the program (other programs may have a different start address)
@example
SYS32592
@end example
@end itemize

@end itemize

@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 KiB cartridges located at $2000;
@item
4 or 8 KiB cartridges located at $4000;
@item
4 or 8 KiB cartridges located at $6000;
@item
4 or 8 KiB cartridges located at $A000;
@item
4 KiB cartridges located at $B000.
@end itemize

This can all be done via the ``Attach cartridge image@dots{}'' command in
the 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.

Also notice that surprisingly often it is required for the user to start VIC20
cartridges manually by typing a BASIC "SYS" command.

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 16KiB image. Vice can attach such concatenated files 
at the start address $2000, $4000, and $6000. The second half of such an image is
moved to the memory block following the first block. It is also possible to 
concatenate four 8KiB files, the resulting file will load into all 4 cartridge blocks.

If you encounter 16KiB images that have the second half at eg $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. Alternatively you can
create a 32KiB file with padding blocks in between.

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 the default cartridge.

The following cartridge types are valid:

@itemize @bullet
@item
   - 1: None
@item
   - 2: Generic
@item
     1: Megacart
@item
     2: Behrbonz
@item
     3: Vic Flash Plugin
@item
     4: Ultimem
@item
     5: Final Expansion
@item
  - 10: SID Cartridge
@item
  - 11: IEEE-4888
@item
  - 12: IO ram cart (IO2)
@item
  - 13: IO ram cart (IO3)
@item
0x8000: Auto Detect
@item
0x8002: 4KiB at $2000-$2FFF
@item
0x8003: 8KiB at $2000-$3FFF
@item
0x8004: 4KiB at $6000-$6FFF
@item
0x8005: 8KiB at $6000-$7FFF
@item
0x8006: 4KiB at $A000-$AFFF
@item
0x8007: 8KiB at $A000-$BFFF
@item
0x8008: 4KiB at $B000-$BFFF
@item
0x8009: 8KiB at $4000-$5FFF
@item
0x800A: 4KiB at $4000-$4FFF
@item
0x8013: 16KiB at $2000-$5FFF
@item
0x8015: 16KiB at $6000-$9FFF
@item
0x8019: 16KiB 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 UltiMemWriteBack
@item UltiMemWriteBack
Boolean, if true write back the Flash ROM image file automatically, incase the
contents changed, when detaching or quitting the emulator.

@vindex IO2RAM
@item IO2RAM
Boolean specifying whether the I/O-2 ($9800-$9BFF) RAM cartridge should be emulated or not.

@vindex IO3RAM
@item IO3RAM
Boolean specifying whether the I/O-3 ($9C00-$9FFF) RAM cartridge should be emulated or not.

@vindex VFLImod
@item VFLImod
Boolean specifying whether the VFLI modification should be enabled.

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

@findex -cart2
@item -cart2 <name>
Specify 4/8/16KiB extension ROM name at $2000
@findex -cart4
@item -cart4 <name>
Specify 4/8/16KiB extension ROM name at $4000
@findex -cart6
@item -cart6 <name>
Specify 4/8/16KiB extension ROM name at $6000
@findex -cartA
@item -cartA <name>
Specify 4/8KiB extension ROM name at $A000
@findex -cartB
@item -cartB <name>
Specify 4KiB extension ROM name at $B000
@findex -cartgeneric
@item -cartgeneric <name>
Specify generic extension ROM name

@findex -cartbb
@item -cartbb <name>
Specify Behr-Bonz extension ROM name

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

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

@findex -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 -ultimem
@item -ultimem <name>
Specify Ultimem extension ROM name

@findex -umwriteback, +umwriteback
@item -umwriteback
@itemx +umwriteback
Enable/disable UltiMem write back to ROM file
(@code{UltiMemWriteBack=1}, @code{UltiMemWriteBack=0}).

@findex -io2ram, +io2ram
@item -io2ram
@itemx +io2ram
Enable/disable the I/O-2 ($9800-$9BFF) RAM cartridge
(@code{IO2RAM=1}, @code{IO2RAM=0}).

@findex -io3ram, +io3ram
@item -io3ram
@itemx +io3ram
Enable/disable the I/O-3 ($9C00-$9FFF) RAM cartridge
(@code{IO3RAM=1}, @code{IO3RAM=0}).

@findex -ieee488, +ieee488
@item -ieee488
@itemx +ieee488
Enable/disable VIC-1112 IEEE488 interface
(@code{IEEE488=1}, @code{IEEE488=0}).

@findex -vflimod, +vflimod
@item -vflimod
@itemx +vflimod
Enable/disable VIC-20 VFLI modification
(@code{VFLImod=1}, @code{VFLImod=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)

@findex -ethernetcart, +ethernetcart
@item -ethernetcart
@itemx +ethernetcart
Disable/Enable the Ethernet Cartridge 
(@code{ETHERNETCART_ACTIVE}).
(TFE/RR-Net/64NIC/FB-NET)

@findex -ethernetcartmode
@item -ethernetcartmode <Mode>
Mode of Ethernet Cartridge
(@code{ETHERNETCARTMode}).
(0: TFE, 1: RR-Net)

@findex -ethernetcartbase
@item -ethernetcartbase <Base address>
Base address of the Ethernet Cartridge.
(@code{ETHERNETCARTBase}) (0x9800, 0x9810, 0x9820, 0x9830, 0x9840,
0x9850, 0x9860, 0x9870, 0x9880, 0x9890, 0x98A0, 0x98B0, 0x98C0, 0x98D0, 0x98E0,
0x98F0, 0x9C00, 0x9C10, 0x9C20, 0x9C30, 0x9C40, 0x9C50, 0x9C60, 0x9C70, 0x9C80,
0x9C90, 0x9CA0, 0x9CB0, 0x9CC0, 0x9CD0, 0x9CE0, 0x9CF0)

@findex -tfe
@item -tfe
Enable the Ethernet Cartridge in TFE ("The Final Ethernet") compatible mode and set default I/O address

@findex -rrnet
@item -rrnet
Enable the Ethernet Cartridge in RR-Net compatible mode and set default I/O address

@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 KiB>
Size of the GEORAM expansion unit
(@code{GEORAMsize}).
(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 VICPALDelaylineType
@item VICPALDelaylineType
Integer specifying the type of delay line used in the CRT (0: normal, 1: U only (1084 style))

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

@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 -VICcrtdelaylinetype
@item -VICcrtscanlineshade <type>
Type of delay line used in the CRT (0: normal, 1: U only (1084 style))
(@code{VICPALDelaylineType}).

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

@findex -VICshowstatusbar, +VICshowstatusbar
@item -VICshowstatusbar
@item +VICshowstatusbar
Show/hide status bar
(@code{VICShowStatusbar=1}, @code{VICShowStatusbar=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 KiB at $0400-$0FFF);
@item
block 1 (8 KiB at $2000-$3FFF);
@item
block 2 (8 KiB at $4000-$5FFF);
@item
block 3 (8 KiB at $6000-$7FFF);
@item
block 5 (8 KiB 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 select:

@itemize @bullet
@item
no RAM expansion blocks at all;
@item
all RAM expansion blocks enabled;
@item
3KiB expansion (only block 0 is enabled);
@item
8KiB expansion (only block 1 is enabled);
@item
16KiB expansion (only blocks 1 and 2 are enabled);
@item
24KiB 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} (3KiB space in block 0);
@item
@code{8k} (first 8KiB extension block);
@item
@code{16k} (first and second 8KiB 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
16KiB 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.

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

@findex -cart2
@findex -cart4
@findex -cart6
@findex -cartA
@findex -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 Using cartridge images

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

@c @node FIXME
@subsection PLUS4 cartridge settings

@c @node FIXME
@subsubsection PLUS4 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 the default cartridge.

The following cartridge types are valid:

@itemize @bullet
@item
   - 1: None
@item
   - 2: Generic
@item
     1: c264 magic cart
@item
     2: Plus4 multi cart
@item
     3: 1MB Cartridge
@end itemize

@vindex CartridgeFile
@item CartridgeFile
String specifying the filename of the image for the current cartridge.

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

@end table

@c @node FIXME
@subsubsection PLUS4 cartridge 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}).

@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 -cart, +cart
@item -cart <Name>
@itemx +cart
Smart-attach cartridge image / Start without cartridge

@findex -cartjacint
@item -cartjacint <name>
Attach a 1MiB "1MB Cartridge" image

@findex -cartmagic
@item -cartmagic <name>
Attach a 128kiB/256kiB/512kiB/1MiB/2MiB "c264 magic cart" image

@findex -cartmulti
@item -cartmulti <name>
Attach a 1MiB/2MiB "Plus4 multi cart" image. The binary should contain all c1lo
banks first, then all c1hi banks.

@end table

@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 TEDPALDelaylineType
@item TEDPALDelaylineType
Integer specifying the type of delay line used in the CRT (0: normal, 1: U only (1084 style))

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

@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 -TEDcrtdelaylinetype
@item -TEDcrtscanlineshade <type>
Type of delay line used in the CRT (0: normal, 1: U only (1084 style))
(@code{TEDPALDelaylineType}).

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

@findex -TEDshowstatusbar, +TEDshowstatusbar
@item -TEDshowstatusbar
@item +TEDshowstatusbar
Show/hide status bar
(@code{TEDShowStatusbar=1}, @code{TEDShowStatusbar=0}).

@end table

@c @node FIXME
@subsection PLUS4 I/O extension settings

@c @node FIXME
@subsubsection PLUS4 I/O extension resources

@table @code

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

@end table

@c @node FIXME
@subsubsection PLUS4 I/O extension command-line options

@table @code

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

@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 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 -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 KiB.
(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{c2loName},
@code{Acia1Enable}, @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 KiB
(@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)

@findex -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::
* CRTC Settings::
* PET I/O extensions::
* PET system ROM::
* PET diagnostic pin::
* PET settings::
* Colour PET::
* PET colors::
* PET DWW high resolution graphics::
* PET HRE (HiRes Emulator) high resolution graphics::
@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 KiB. 96KiB denotes an 8096, 128KiB an 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 EoiBlank
@item EoiBlank
Boolean to enable/disable the "blank screen on EOI" feature of the oldest PET 2001.

@vindex Screen2001
@item Screen2001
Boolean specifying if the screen memory should have "mirrors" like on
the oldest PET 2001: $8000-$83FF is visible 3 more times, up to $8FFF.
Otherwise, mirrors (if any) only go up to $87FF.

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

@vindex RomModuleAName
@item RomModuleAName
String specifying the filename for the $A*** Expansion ROM file. This file contains
an expansion ROM image of 4KiB.

@vindex RomModuleBName
@item RomModuleBName
String specifying the filename for the $B*** Expansion ROM file. This file contains
an expansion ROM image of 4KiB. This file overlays the lowest 4KiB of a BASIC 4 ROM.

@end table

Choosing a common PET model is done from the setting dialog,
by choosing an item from the ``Model'' selection.  Available
models are:

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

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

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

@node CRTC Settings
@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, 1: CRT emulation, 2: 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}).

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

@findex -Crtcshowstatusbar, +Crtcshowstatusbar
@item -Crtcshowstatusbar
@item +Crtcshowstatusbar
Show/hide status bar
(@code{CrtcShowStatusbar=1}, @code{CrtcShowStatusbar=0}).

@end table

@node PET I/O extensions
@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 KiB.
(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 SidCart
@item SidCart
Boolean specifying whether SID Cartridge 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 KiB>
Size of the PET Ram and Expansion Unit
(@code{PETREUsize}).
(128, 512, 1024, 2048)

@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

@node PET system ROM
@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 4KiB to 24KiB ROM file name at $A000 for 6809
(@code{H6809RomAName}).

@findex -6809romB
@item -6809romB <Name>
Specify 4KiB to 20KiB ROM file name at $B000 for 6809
(@code{H6809RomBName}).

@findex -6809romC
@item -6809romC <Name>
Specify 4KiB to 16KiB ROM file name at $C000 for 6809
(@code{H6809RomCName}).

@findex -6809romD
@item -6809romD <Name>
Specify 4KiB to 12KiB ROM file name at $D000 for 6809
(@code{H6809RomDName}).

@findex -6809romE
@item -6809romE <Name>
Specify 2KiB or 8KiB ROM file name at $E000 for 6809
(@code{H6809RomEName}).

@findex -6809romF
@item -6809romF <Name>
Specify 4KiB 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.)

@vindex CB2Lowpass
@item CB2Lowpass
Integer specifying the frequency of the low-pass filter that is
applied to the CB2 sound signal.
Default: 16000

@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{EoiBlank}, @code{Screen2001},
@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 KiB
(@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 -eoiblank, +eoiblank
@item -eoiblank
@itemx +eoiblank
Model-2001-only quirk:
Enable/disable EOI blanking the screen.
(@code{EoiBlank=1}, @code{EoiBlank=0}).

@findex -screen2001, +screen2001
@item -screen2001
@itemx +screen2001
Model-2001-only quirk:
the 1 KiB of screen memory is mirrored all the way through the $8*** block.
This option is incompatible with 80 columns and the Colour PET extension.
(@code{Screen2001=1}, @code{Screen2001=0}).

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

@findex -cb2lowpass
@item -cb2lowpass
Integer specifying the frequency of the low-pass filter that is
applied to the CB2 sound signal.
(@code{CB2Lowpass})

@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 character cell. 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 graphics

@subsection DWW high resolution graphics
@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 KiB 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 1 KiB 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 KiB and the char ROM offset selects which KiB 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 an 80 columns PET the resolution will be the same.

@node PET HRE (HiRes Emulator) high resolution graphics

@subsection HRE high resolution graphics

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 (ASSY No. 324890-01).  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 proper 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 KiB.
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 a 4KiB ROM dump.

@vindex Cart2Name
@item Cart2Name
String specifying the filename for the $2000-$3FFF expansion ROM file. This file contains an 8KiB ROM dump.

@vindex Cart4Name
@item Cart4Name
String specifying the filename for the $4000-$5FFF expansion ROM file. This file contains an 8KiB ROM dump.

@vindex Cart6Name
@item Cart6Name
String specifying the filename for the $6000-$7FFF expansion ROM file. This file contains an 8KiB 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 (128KiB RAM)
@item
C610 PAL or NTSC (128KiB RAM)
@item
C620 (256KiB RAM)
@item
C620+ (1024KiB RAM, expanded) PAL or NTSC
@item
C710 (128KiB RAM) NTSC
@item
C720 (256KiB RAM) NTSC
@item
C720+ (1024KiB 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 HVSCRoot
@item HVSCRoot
String specifying the location of the HVSC root directory, overriding the
environment variable @code{HVSC_BASE}.

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

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

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

@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; Changing this resource
equals loading one of the provided kernal ROM files. It will be adjusted when
changing @code{KernalName}.

Valid values are:

@table @code
@item -1
Unknown kernal. This value can not be set by the user, it will be set when loading
a custom kernal via changing @code{KernalName}.
@item -2
No kernal. This is used by the MAX Machine.
@item 0
Kernal revision 0 (Japanese, 906145-02)
@item 1
Kernal revision 1 (901227-01)
@item 2
Kernal revision 2 (901227-02)
@item 3
Kernal revision 3 (901227-03)
@item 39
C64 GS (390852-01)
@item 67
SX-64 (251104-04)
@item 100
Commodore 4064 (also known as ``PET64'' or ``Educator 64'') (901246-01)
@end table

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

@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 -hvsc-root
@item -hvsc-root <path>
Specify the location of the HVSC root directory, overriding the environment
variable @code{HVSC_BASE}.

(@code{HVSCRoot}).

@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 -kernalrev
@item -kernalrev <revision>
Specify Kernal revision
(@code{KernalRev}).
(0/jap: japanese 1: rev. 1, 2: rev. 2, 3: rev. 3, 39/gs: C64 GS, 67/sx: sx64, 100/4064: 4064)

@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 platformsdl
* SDL-specific features::
@end ifset
@ifset platformgtk3
* GTK3 specific features::
@end ifset
@end menu

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

@ifset platformsdl
@node SDL-specific features
@section SDL-specific features

This section lists the settings and commands that are common and specific to SDL, and are thus not present in other platforms.

@c -----------------------------------------------------------------
@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 MenuKeyPageUp
@item MenuKeyPageUp
Integer specifying the keycode for 'page up' in the SDL menu.

@vindex MenuKeyPageDown
@item MenuKeyPageDown
Integer specifying the keycode for 'page down' in the SDL menu.

@vindex MenuKeyHome
@item MenuKeyHome
Integer specifying the keycode for 'home' in the SDL menu.

@vindex MenuKeyEnd
@item MenuKeyEnd
Integer specifying the keycode for 'end' 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 PauseOnSettings
@item PauseOnSettings
Boolean specifying wheter to pause the emulation when triggering the settings
dialog. If set, the emulation will pause when triggering the settings dialog.
When closing the settings dialog the pause state will revert to its state before
triggering the settings UI.

@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 fullscreen resolution width.

@vindex SDLCustomHeight
@item SDLCustomHeight
Integer specifying the custom fullscreen resolution height.

@vindex KbdStatusbar
@item KbdStatusbar
Boolean specifying whether the keyboard-status bar is enabled.

@vindex SDL2Backend
@item SDL2Backend
String specifying the preferred SDL2 backend.
(See startup log for available backends, valid ones might be eg: software, opengl,
direct3d, direct3d11, opengles2)

@vindex Window0Width
@item Window0Width
Integer specifying the SDL window width.

@vindex Window0Height
@item Window0Height
Integer specifying the SDL window height.

@vindex SDLGLFilter
@item SDLGLFilter
Integer specifying the OpenGL filtering mode.

@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 CrtcFullscreenMode
@item CrtcFullscreenMode
Integer specifying the fullscreen mode
(xcbm2 and xpet only).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

@vindex CrtcFullscreen
@item CrtcFullscreen
Boolean specifying whether to use fullscreen mode or not
(xcbm2 and xpet only).

@vindex TEDFullscreenMode
@item TEDFullscreenMode
Integer specifying the fullscreen mode
(xplus4 only).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

@vindex TEDFullscreen
@item TEDFullscreen
Boolean specifying whether to use fullscreen mode or not
(xplus4 only).

@vindex VDCFullscreenMode
@item VDCFullscreenMode
Integer specifying the fullscreen mode
(x128 only).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

@vindex VDCFullscreen
@item VDCFullscreen
Boolean specifying whether to use fullscreen mode or not
(x128 only).

@vindex VICFullscreenMode
@item VICFullscreenMode
Integer specifying the fullscreen mode
(xvic only).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

@vindex VICFullscreen
@item VICFullscreen
Boolean specifying whether to use fullscreen mode or not
(xvic only).

@vindex VICIIFullscreenMode
@item VICIIFullscreenMode
Integer specifying the fullscreen mode
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

@vindex VICIIFullscreen
@item VICIIFullscreen
Boolean specifying whether to use fullscreen mode or not
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).

@vindex CrtcShowStatusbar
@item CrtcShowStatusbar
Boolean specifying whether to show the status bar or not
(xcbm2 and xpet only).

@vindex TEDShowStatusbar
@item TEDShowStatusbar
Boolean specifying whether to show the status bar or not
(xplus4 only).

@vindex VDCShowStatusbar
@item TEDShowStatusbar
Boolean specifying whether to show the status bar or not
(x128 only).

@vindex VICShowStatusbar
@item VICShowStatusbar
Boolean specifying whether to show the status bar or not
(xvic only).

@vindex VICIIShowStatusbar
@item VICIIShowStatusbar
Boolean specifying whether to show the status bar or not
(x64, x64sc, x64dtv, xscpu64, x128 and xcbm5x0).


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

@vindex JoyMenuControl
@item JoyMenuControl
Boolean to enable/disable controlling the SDL menu using a joystick.

@end table

@c -----------------------------------------------------------------
@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' key in the SDL menu
(@code{MenuKeyUp}).

@findex -menukeydown
@item -menukeydown <key>
Set the keycode of the 'down' key in the SDL menu
(@code{MenuKeyDown}).

@findex -menukeyleft
@item -menukeyleft <key>
Set the keycode of the 'left' key in the SDL menu
(@code{MenuKeyLeft}).

@findex -menukeyright
@item -menukeyright <key>
Set the keycode of the 'right' key in the SDL menu
(@code{MenuKeyRight}).

@findex -menukeypageup
@item -menukeypageup <key>
Set the keycode of the 'page up' key in the SDL menu
(@code{MenuKeyPageUp}).

@findex -menukeypagedown
@item -menukeypagedown <key>
Set the keycode of the 'page down' key in the SDL menu
(@code{MenuKeyPageDown}).

@findex -menukeyhome
@item -menukeyhome <key>
Set the keycode of the 'home' key in the SDL menu
(@code{MenuKeyHome}).

@findex -menukeyend
@item -menukeyend <key>
Set the keycode of the 'end' key in the SDL menu
(@code{MenuKeyEnd}).

@findex -menukeyselect
@item -menukeyselect <key>
Set the keycode of the 'select' key in the SDL menu
(@code{MenuKeySelect}).

@findex -menukeycancel
@item -menukeycancel <key>
Set the keycode of the 'cancel' key in the SDL menu
(@code{MenuKeyCancel}).

@findex -menukeyexit
@item -menukeyexit <key>
Set the keycode of the 'exit' key in the SDL menu
(@code{MenuKeyExit}).

@findex -menukeymap
@item -menukeymap <key>
Set the keycode of the 'map' key 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 -confirmonexit, +confirmonexit
@item -confirmonexit
Confirm quitting VICE
(@code{ConfirmOnExit=1}).
@item +confirmonexit
Never confirm quitting VICE
(@code{ConfirmOnExit=0}).

@findex -pauseonsettings, +pauseonsettings
@item -pauseonsettings
Pause emulation when enabling the settings dialog.
(@code{PauseOnSettings=1}).
@item +pauseonsettings
Do not pause emulation when enabling the settings dialog.
(@code{PauseOnSettings=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 fullscreen resolution width
(@code{SDLCustomWidth}).

@findex -sdlcustomh
@item -sdlcustomh <height>
Set the custom fullscreen resolution height
(@code{SDLCustomHeight}).

@findex -sdlinitialw
@item -sdlinitialw <width>
Set initial window width.

@findex -sdlinitialh
@item -sdlinitialh <height>
Set initial window height.

@findex -sdlinitialw1
@item -sdlinitialw1 <width>
Set initial window width for the second window (C128),

@findex -sdlinitialh1
@item -sdlinitialh1 <height>
Set initial window height for the second window (C128),

@c Move to generic options
@findex -kbdstatusbar, +kbdstatusbar
@item -kbdstatusbar
@itemx +kbdstatusbar
Enable/Disable keyboard-status bar (when status bar is enabled)
(@code{KbdStatusbar=1}, @code{KbdStatusbar=0}).

@findex -sdlglfilter
@item -sdlglfilter <mode>
Set OpenGL filtering mode (0 = nearest, 1 = linear)
(@code{SDLGLFilter}).

@findex -sdl2backend
@item -sdl2backend <renderer name>
Set the preferred SDL2 backend
(@code{SDL2Backend}).
See startup log for available backends, valid ones might be eg: software, opengl,
direct3d, direct3d11, opengles2)

@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 -CRTCfullmode
@item -CRTCfullmode <Mode>
Set the fullscreen mode
(@code{CrtcFullscreenMode})
(xcbm2 and xpet only).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

@findex -CRTCfull, +CRTCfull
@item -CRTCfull
@itemx +CRTCfull
Enable/Disable fullscreen
(@code{CrtcFullscreen=1}, @code{CrtcFullscreen=0})
(xcbm2 and xpet only).

@findex -TEDfullmode
@item -TEDfullmode <Mode>
Set the fullscreen mode
(@code{TEDFullscreenMode})
(xplus4 only).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

@findex -TEDfull, +TEDfull
@item -TEDfull
@itemx +TEDfull
Enable/Disable fullscreen
(@code{TEDFullscreen=1}, @code{TEDFullscreen=0})
(xplus4 only).

@findex -VDCfullmode
@item -VDCfullmode <Mode>
Set the fullscreen mode
(@code{VDCFullscreenMode})
(x128 only).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

@findex -VDCfull, +VDCfull
@item -VDCfull
@itemx +VDCfull
Enable/Disable fullscreen
(@code{VDCFullscreen=1}, @code{VDCFullscreen=0})
(x128 only).

@findex -VICfullmode
@item -VICfullmode <Mode>
Set the fullscreen mode
(@code{VICFullscreenMode})
(xvic only).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

@findex -VICfull, +VICfull
@item -VICfull
@itemx +VICfull
Enable/Disable fullscreen
(@code{VICFullscreen=1}, @code{VICFullscreen=0})
(xvic only).

@findex -VICIIfullmode
@item -VICIIfullmode <Mode>
Set the fullscreen mode
(@code{VICIIFullscreenMode})
(all emulators except xcbm2, xpet, xplus4, xvic and vsid).
(0: use desktop resolution, 1: switch to @code{SDLCustomWidth}, @code{SDLCustomHeight})

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

@findex -joymenucontrol, +joymenucontrol
@item -joymenucontrol
@itemx +joymenucontrol
Enable/disable controlling the SDL menu with a joystick
(@code{JoyMenuControl=1}, @code{JoyMenuControl=0}).

@end table

@end ifset
@c end platformsdl
@c -----------------------------------------------------------------

@ifset platformgtk3
@node GTK3 specific features
@section GTK3 specific features

This section lists the settings and commands that are common and specific to Unix, and are thus not present in other platforms.

@c -----------------------------------------------------------------
@c @node FIXME
@subsection GTK3 specific resources

@table @code

@vindex GTKFilter
@item GTKFilter
Rendering filter to use for the Gtk3 UI
(0: Nearest neighbor, 1: Bilinear, 2: Bicubic).

@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 VSync
@item VSync
Boolean specifying whether to enable vsync to prevent screen tearing.
(0: vsync off, 1: vsync on)

@vindex StartMinimized
@item StartMinimized
Boolean specifying whether the emulator should start minimized

@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 FullscreenDecorations
@item FullscreenDecorations
Boolean specifying whether the menu and statusbar are shown in full screen mode.

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

@vindex CrtcFullscreen
@item CrtcFullscreen
Boolean specifying whether to use fullscreen mode or not
(xcbm2 and xpet only).

@vindex TEDFullscreen
@item TEDFullscreen
Boolean specifying whether to use fullscreen mode or not
(xplus4 only).

@vindex VDCFullscreen
@item VDCFullscreen
Boolean specifying whether to use fullscreen mode or not
(x128 only).

@vindex VICFullscreen
@item VICFullscreen
Boolean specifying whether to use fullscreen mode or not
(xvic only).

@vindex VICIIFullscreen
@item VICIIFullscreen
Boolean specifying whether to use 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 MIDIName
@item MIDIName
String specifying the name of the MIDI client (default:"VICE")
(ALSA and macOS only, x64, x64sc, xscpu64, x128 and xvic only).

@vindex MIDIInDev
@item MIDIInDev
String specifying the OSS MIDI input device
(Windows and OSS, x64, x64sc, xscpu64, x128 and xvic only).

@vindex MIDIOutDev
@item MIDIOutDev
String specifying the OSS MIDI output device
(Windows and OSS, x64, x64sc, xscpu64, x128 and xvic only).

@vindex MIDIInName
@item MIDIInName
String specifying the name of the MIDI input port (default:"VICEInput")
(macOS only, x64, x64sc, xscpu64, x128 and xvic only).

@vindex MIDIOutName
@item MIDIOutName
String specifying the name of the MIDI output port (default:"VICEOutput")
(macOS only, 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
(Unix - x64, x64sc, xscpu64, x128 and xvic only).
(0: OSS, 1: ALSA)

@end table

@c @node FIXME
@subsection GTK3 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 -minimized, +minimized
@item -minimized
@itemx +minimized
Start/Do not start with minimized window
(@code{StartMinimized=1}, @code{StartMinimized=0}).

@findex -aspect
@item -aspect <aspect ratio>
Set the aspect ratio
(@code{AspectRatio}).
(0.5-2.0)

@findex -gtkfilter
@item -gtkfilter <filter>
(@code{GTKFilter})
(0: Nearest neighbor, 1: Bilinear 2: Bicubic).

@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 -vsync, +vsync
@item -vsync
Enable vsync to prevent screen tearing
(@code{VSync=1}).
@item +vsync
Disable vsync to allow screen tearing
(@code{VSync=0}).

@findex -confirmonexit, +confirmonexit
@item -confirmonexit
Confirm quitting VICE
(@code{ConfirmOnExit=1}).
@item +confirmonexit
Never confirm quitting VICE
(@code{ConfirmOnExit=0}).

@findex -fullscreen-decorations, +fullscreen-decorations
@item -fullscreen-decorations
@itemx +fullscreen-decorations
Enable/disable fullscreen decorations

@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 -midiname
@item -midiname <name>
Specify the name of the MIDI client (default:"VICE")
(@code{MIDIName})
(ALSA and macOS only, x64, x64sc, xscpu64, x128 and xvic only).

@findex -midiin
@item -midiin <name>
Specify OSS MIDI-In device
(@code{MIDIInDev})
(Windows and OSS, x64, x64sc, xscpu64, x128 and xvic only).

@findex -midiout
@item -midiout <name>
Specify OSS MIDI-Out device
(@code{MIDIOutDev})
(Windows and OSS, x64, x64sc, xscpu64, x128 and xvic only).

@findex -midiinname
@item -midiinname <name>
Specify the name of the MIDI input port (default:"VICEInput")
(@code{MIDIInName})
(macos, x64, x64sc, xscpu64, x128 and xvic only).

@findex -midioutname
@item -midioutname <name>
Specify the name of the MIDI output port (default:"VICEOutput")
(@code{MIDIOutName})
(macos, 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})
(Unix - x64, x64sc, xscpu64, x128 and xvic only).
(0: OSS, 1: ALSA)

@end table

@end ifset
@c platformunix

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

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

Important note: In the past the idea was that snapshots with the same major
version can be exchanged with later versions of the emulator. However, this 
proved to be too difficult to maintain, and insanely hard to test for
correctness, which is why now the emulator will reject the snapshot when it
finds a module that is too old. @b{Because of this you should not use snapshots
for permanent/long term storage.}

@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, and sometimes additional
state of the emulator.  In the past we tried to make the format as 
implementation-independent as possible, to allow reuse of snapshots in later 
versions of the emulator, that however proved to be very impractical and 
insanely hard to maintain.

@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 .2 .3 .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.
@item 13 BYTE
@tab VERSION MAGIC
@tab "VICE Version\032", padded with 0
@item 4 BYTE
@tab VERSION
@tab Release version (major, minor, micro). Byte 4 is always zero.
@item DWORD
@tab SVNVERSION
@tab SVN revision (or 0 if not available)
@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.  In the past the
idea was that modules with the same VMAJOR should be able to be exchanged. This
however proved to be too difficult to maintain, and insanely hard to test for
correctness, which is why now the emulator will reject the snapshot when it
finds a module that is too old. @b{Because of this you should not use snapshots
for permanent/long term storage.}

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

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

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

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

@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

@c FIXME: add description

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

@c FIXME: add description

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

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.

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 64KiB RAM dump
@end multitable

@b{The C64ROM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item ARRAY
@tab KERNAL
@tab 8KiB dump of the kernal ROM
@item ARRAY
@tab BASIC
@tab 8KiB dump of the basic ROM
@item ARRAY
@tab CHARGEN
@tab 4KiB 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 128KiB 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 8KiB dump of the kernal ROM
@item ARRAY
@tab BASIC
@tab 32KiB dump of the basic ROM
@item ARRAY
@tab EDITOR
@tab 4KiB dump of the editor ROM
@item ARRAY
@tab 4KiB 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 1KiB RAM dump $0000-$03ff
@item ARRAY
@tab RAM1
@tab 4KiB RAM dump $1000-$1fff
@item ARRAY
@tab COLORRAM
@tab 2KiB Color RAM, $9400-$9bff
@item ARRAY
@tab BLK0
@tab if CONFIG & 1 then: 3KiB RAM dump $0400-$0fff
@item ARRAY
@tab BLK1
@tab if CONFIG & 2 then: 8KiB RAM dump $2000-$3fff
@item ARRAY
@tab BLK2
@tab if CONFIG & 4 then: 8KiB RAM dump $4000-$5fff
@item ARRAY
@tab BLK3
@tab if CONFIG & 8 then: 8KiB RAM dump $6000-$7fff
@item ARRAY
@tab BLK5
@tab if CONFIG & 32 then: 8KiB 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 8KiB KERNAL ROM image $e000-$ffff
@item ARRAY
@tab BASIC
@tab 16KiB BASIC ROM image $c000-$dfff
@item ARRAY
@tab CHARGEN
@tab 4KiB CHARGEN ROM image
@item ARRAY
@tab BLK1A
@tab 4KiB ROM image $2*** (if CONFIG & 1)
@item ARRAY
@tab BLK1B
@tab 4KiB ROM image $3*** (if CONFIG & 2)
@item ARRAY
@tab BLK3A
@tab 4KiB ROM image $6*** (if CONFIG & 16)
@item ARRAY
@tab BLK3B
@tab 4KiB ROM image $7*** (if CONFIG & 32)
@item ARRAY
@tab BLK5A
@tab 4KiB ROM image $A*** (if CONFIG & 64)
@item ARRAY
@tab BLK5B
@tab 4KiB ROM image $B*** (if CONFIG & 128)
@item ARRAY
@tab BLK2A
@tab 4KiB ROM image $4*** (if CONFIG & 4; added in V1.1)
@item ARRAY
@tab BLK2B
@tab 4KiB 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 32KiB 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-32KiB RAM (not 8296, size depends on MEMSIZE)
@item ARRAY
@tab VRAM
@tab 2/4KiB RAM (not 8296, size depends on CONFIG)
@item ARRAY
@tab EXTRAM
@tab 64KiB expansion RAM (SuperPET and 8096 only)
@item ARRAY
@tab RAM
@tab 128KiB 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 4KiB KERNAL ROM image $f000-$ffff
@item ARRAY
@tab EDITOR
@tab 2KiB EDITOR ROM image $e000-$e7ff
@item ARRAY
@tab CHARGEN
@tab 2KiB CHARGEN ROM image
@item ARRAY
@tab ROM9
@tab 4KiB $9*** ROM image (if CONFIG & 1)
@item ARRAY
@tab ROMA
@tab 4KiB $A*** ROM image (if CONFIG & 2)
@item ARRAY
@tab ROMB
@tab 4KiB $B*** ROM image (if CONFIG & 4)
@item ARRAY
@tab ROMC
@tab 4KiB $C*** ROM image
@item ARRAY
@tab ROMD
@tab 4KiB $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 24KiB $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 128KiB blocks (1=128KiB, 2=256KiB, 4=512KiB, 8=1024KiB)
@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 2KiB system RAM $f0000-$f07ff
@item ARRAY
@tab VIDEO
@tab 2KiB video RAM $fd000-$fd7ff
@item ARRAY
@tab RAM
@tab RAM dump, size according to MEMSIZE
@item ARRAY
@tab RAM08
@tab if memsize < 1MiB and CONFIG & 1 : 2KiB RAM $f0800-$f0fff
@item ARRAY
@tab RAM1
@tab if memsize < 1MiB and CONFIG & 2 : 4KiB RAM $f1000-$f1fff
@item ARRAY
@tab RAM2
@tab if memsize < 1MiB and CONFIG & 4 : 8KiB RAM $f2000-$f3fff
@item ARRAY
@tab RAM4
@tab if memsize < 1MiB and CONFIG & 8 : 8KiB RAM $f4000-$f5fff
@item ARRAY
@tab RAM6
@tab if memsize < 1MiB and CONFIG & 16 : 8KiB RAM $f6000-$f7fff
@item ARRAY
@tab RAMC
@tab if memsize < 1MiB and CONFIG & 32 : 4KiB RAM $fc000-$fcfff
@end multitable

The RAM* arrays are only saved if the RAM itself is less than 1MiB.
If the memory size is 1MiB 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 512KiB,
or at $00000 if 512KiB 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 4KiB CHARGEN ROM image
@item ARRAY
@tab ROM1
@tab 4KiB cartridge ROM image for $1*** (if CONFIG & 2)
@item ARRAY
@tab ROM2
@tab 8KiB cartridge ROM image for $2000-$3fff (if CONFIG & 4)
@item ARRAY
@tab ROM4
@tab 8KiB cartridge ROM image for $4000-$5fff (if CONFIG & 8)
@item ARRAY
@tab ROM6
@tab 8KiB cartridge ROM image for $6000-$7fff (if CONFIG & 16)
@end multitable

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

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

Version numbers: Major 0, Minor 0

@b{The C500DATA module}

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

@c -----------------------------------------------------------------
@node Media images
@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 OCPOversizeHandling
@item OCPOversizeHandling
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 OCPUndersizeHandling
@item OCPUndersizeHandling
Integer specifying the way the undersized input should be handled
(all emulators except vsid).
(0: scale, 1: borderize)

@vindex OCPMultiColorHandling
@item OCPMultiColorHandling
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 OCPTEDLumHandling
@item OCPTEDLumHandling
Integer specifying the way the TED luminosity should be handled
(all emulators except vsid).
(0: ignore, 1: dither)

@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 MinipaintOversizeHandling
@item MinipaintOversizeHandling
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 MinipaintUndersizeHandling
@item MinipaintUndersizeHandling
Integer specifying the way the undersized input should be handled
(all emulators except vsid).
(0: scale, 1: borderize)

@vindex MinipaintTEDLumHandling
@item MinipaintTEDLumHandling
Integer specifying the way the TED luminosity should be handled
(all emulators except vsid).
(0: ignore, 1: dither)

@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 -ocpoversize
@item -ocpoversize <method>
Select the way the oversized input should be handled
(@code{OCPOversizeHandling})
(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 -ocpundersize
@item -ocpundersize <method>
Select the way the undersized input should be handled
(@code{OCPUndersizeHandling})
(all emulators except vsid).
(0: scale, 1: borderize)

@findex -ocpmc
@item -ocpmc <method>
Select the way the multicolor to hires should be handled
(@code{OCPMultiColorHandling})
(all emulators except vsid).
(0: b&w, 1: 2 colors, 2: 4 colors, 3: gray scale, 4: best cell colors)

@findex -ocptedlum
@item -ocptedlum <method>
Select the way the TED luminosity should be handled
(@code{OCPTEDLumHandling})
(all emulators except vsid).
(0: ignore, 1: dither)

@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 -minipaintoversize
@item -minipaintoversize <method>
Select the way the oversized input should be handled
(@code{MinipaintOversizeHandling})
(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 -minipaintundersize
@item -minipaintundersize <method>
Select the way the undersized input should be handled
(@code{MinipaintUndersizeHandling})
(all emulators except vsid).
(0: scale, 1: borderize)

@findex -minipainttedlum
@item -minipainttedlum <method>
Select the way the TED luminosity should be handled
(@code{MinipaintTEDLumHandling})
(all emulators except vsid).
(0: ignore, 1: dither)

@findex -ffmpegaudiobitrate
@item -ffmpegaudiobitrate <value>
Set bitrate for audio stream in media file
@findex -ffmpegvideobitrate
@item -ffmpegvideobitrate <value>
Set bitrate for video stream in media file

@end table

@c -----------------------------------------------------------------
@node Event history
@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.

@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 (>1MiB) 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
@chapter Monitor

The 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
``Activate monitor'' from the menu.  The monitor will either run in a 
seperate window, or in a terminal emulation program (such as
@code{rxvt} or @code{xterm}) when ``native monitor'' has been enabled in
the settings.

@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 64KiB 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 radix_type
Radix for the output, H for hex, D for decimal, O for octal, or B for binary.

@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-cpuhistory"
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>] [c:] [8:] [9:] [10:] [11:]
@itemx chis [<count>] [c:] [8:] [9:] [10:] [11:]
Show <count> last executed commands on up to five devices.
If no devices are specified, then the default device is shown.
VICE emulation runs each CPU for a variable number of cycles before switching
between them. They will be synchronized when communication between
them occurs.
(disabled by default; configure with --enable-cpuhistory 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(s).  COUNT allows stepping
more than a single instruction at a time. Subroutines are
treated as a single instruction ("step over").

@item registers [<reg_name> = <number> [, <reg_name> = <number>]*]
@itemx r [<reg_name> = <number> [, <reg_name> = <number>]*]
Assign respective registers (use FL for status flags).  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 ("step out").

@item step [<count>]
@itemx z [<count>]
Single step through instructions.  An optional count allows stepping
more than a single instruction at a time ("step into").

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

@item warp [on|off|toggle]
Turn warp mode on or off. If the argument is 'toggle' then the current mode
is toggled. When no argument is given the current mode is displayed.

@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:|10:|11:]
@itemx dev [c:|8:|9:|10:|11:]
Set the default address space to either the computer `c:' or the
specified drive `8:', `9:', `10:' or `11:'.
Switches to computer when not given a device.

@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 [<radix_type>] [<address_opt_range>]
@itemx m [<radix_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-cpuhistory to enable)

@item memmapzap
@itemx mmzap
Clear the memmap.
(disabled by default; configure with --enable-cpuhistory 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-cpuhistory to enable)

@item memchar [<radix_type>] [<address_opt_range>]
@itemx mc [<radix_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 [<radix_type>] [<address_opt_range>]
@itemx ms [<radix_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 ignored.  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.

The condition can use registers (A, X, Y, PC, SP, FL and other cpu
specific registers (see manual)) and compare them (==, !=, <, >, <=, >=)
against other registers or constants. RL can be used to refer to the 
current rasterline, and CY refers to the current cycle in the line.

Full expressions are also supported (+, -, *, /, &, |, &&, ||). This lets
you for example check specific bits in the FL register using the bitwise
boolean operators (& and |). Parentheses are also supported in the expression.
Registers can be the registers of other devices; this is denoted by
a memspace prefix (i.e., c:, 8:, 9:, 10:, 11:
Examples: A == $0, X == Y, 8:X == X)
You can also compare against the value of a memory location in a specific
bank, i.e you can break only if the vic register $d020 is $f0.
use the form @@[bankname]:[$<address>] | [.label].
Note this is for the C : memspace only.
Examples : if @@io:$d020 == $f0, if @@io:.vicBorder == $f0

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

@item dummy [on|off|toggle]
Control whether the checkpoints will trigger on dummy accesses.
If the argument is 'on' then dummy accesses will cause checkpoints
to trigger. If the argument is 'off' then dummy accesses will not
trigger any checkpoints. If the argument is 'toggle' then the current
mode is switched.  No argument displays the current state.

@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 mkdir <directory>
Create directory.

@item rmdir <directory>
Remove 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.

@item log [on|off|toggle]
Control whether the monitor output is logged into a logfile. If the
argument is 'on' then all output will be written into the logfile. If
the argument is 'off' then no log is produced. If the argument is
'toggle' then the current mode is switched. No argument displays the
current state.

@item logname "<filename>"
Sets the filename of the logfile.

@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 virtual
drive 8.

@item list [<directory>]
List disk contents.

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

@item verify "<filename>" <device> [<address>]
@itemx v "<filename>" <device> [<address>]
Compare the specified file with memory.  If no address is given, the 
address is specified by the first two bytes read from
the file.  If address is given, the specified address is used and the 
first two bytes read from the file are skipped.  If
device is 0, the file is read from the file system.

@item bverify "<filename>" <device> <address>
@itemx bv "<filename>" <device> <address>
Compare the specified file with memory at the specified address.
If device is 0, the file is read from 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 from default address space.

@item clear_labels [<address_space>]
@itemx cl [<address_space>]
Clear current label mappings.  If no address space is specified, clear
all labels from default address space.

@end table


@node Miscellaneous commands,  , Label commands, Monitor
@section Miscellaneous commands


@table @code

@item ; <text>
Add a comment to a file to be read by the monitor. For example:
@example
; Set border and background to black
> d020 00 00
@end example

@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
@itemx q
Exit the emulator immediately.

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

@end table

@node Binary monitor
@chapter Binary monitor
The binary remote monitor commands are sent over a dedicated connection, specified
with the command line options @code{-binarymonitor} & @code{-binarymonitoraddress}. @xref{Monitor settings}.
The remote monitor detects a binary command because it starts with ASCII STX
(0x02). Note that there is no termination character. The command length acts as
synchronisation point.

All multibyte values are in little endian order unless otherwise specified.

@menu
* Binary Command Structure::
* Binary Response Structure::
* Binary Monitor Example Exchange::
* Binary Commands::
* Binary Responses::
* Binary Example Projects::
@end menu

@node Binary Command Structure
@section Command Structure

@table @strong

@item byte 0: 0x02 (STX)
@item byte 1: API version ID (currently 0x02)
The API version identifies incompatible changes, such as modifying the header
structure, or rearranging or changing the meaning of existing response fields.
The API version does not need to be incremented for additional fields. If all
the variable length fields are prefixed with their lengths then you should be
able to add new ones to any response. The server can assume default values for
older clients, and for newer clients with longer commands
it should be able to ignore the extra fields safely.

@item byte 2-5: length
Note that the command length does *not* count the STX, the command length, 
the command byte, or the request ID. Basically nothing in the header, 
just the body.

@item byte 6-9: request id
In little endian order. All multibyte values are in little endian order,
unless otherwise specified. There is no requirement for this to be unique,
but it makes it easier to match up the responses if you do.

@item byte 10: The numeric command type
@xref{Binary Commands}.

@item byte 11+: The command body. 
@xref{Binary Commands}.

@end table

@node Binary Response Structure
@section Response Structure

@table @strong

@item byte 0: 0x02 (STX)
@item byte 1: API version ID (currently 0x02)
The API version identifies incompatible changes, such as modifying the header
structure, or rearranging or changing the meaning of existing response fields.
The API version does not need to be incremented for additional fields. If all
the variable length fields are prefixed with their lengths then you should be
able to add new ones to any response. The client can assume default values for
older versions of VICE, and for newer versions of VICE with longer responses 
it should be able to ignore the extra fields safely.

@item byte 2-5: response body length. Does not include any header fields

@item byte 6: response type
This is usually the same as the command ID

@item byte 7: error code

@table @code
@item 0x00
OK, everything worked

@item 0x01
The object you are trying to get or set doesn't exist.

@item 0x02
The memspace is invalid

@item 0x80
Command length is not correct for this command

@item 0x81
An invalid parameter value was present

@item 0x82
The API version is not understood by the server

@item 0x83
The command type is not understood by the server

@item 0x8f
The command had parameter values that passed basic checks, but a general failure occurred
@*
@*
@xref{Binary Commands} for other error codes

@end table

@item byte 8-11: request ID
This is the request ID given to initiate this response.
If the value is 0xffffffff, Then the response was initiated by an event,
such as hitting a checkpoint.

@item byte 12+: response body.
@xref{Binary Commands}.

@end table

@node Binary Monitor Example Exchange
@section Example Exchange

@enumerate

@item Client connects to ip4://127.0.0.1:6502

@item Client sends a command to set a temporary checkpoint:
@*
@* @code{02 | 02 | 08 00 00 00 | ad de 34 12 | 12 | e2 fc | e3 fc | 01 | 01 | 04 | 01 }
@*
@*

@table @code
@item 0x02
Begin command

@item 0x02
API version 2

@item 0x00000008
The command excluding the header is 8 bytes long.

@item 0x1234dead
The request ID is 0x1234dead. The response will contain this ID.

@item 0x12
@xref{MON_CMD_CHECKPOINT_SET}.

@item 0xfce2
The address range of the checkpoint starts at 0xfce2.

@item 0xfce3
The address range of the checkpoint ends at 0xfce3.

@item 0x01
The checkpoint will cause the emulator to stop.

@item 0x01
The checkpoint is enabled.

@item 0x04
The checkpoint will trigger on exec from 0xfce2 - 0xfce3.

@item 0x01
The checkpoint is temporary.

@end table

@item The transmission of any command causes the emulator to stop, similar to
the regular monitor. This causes the server to respond with a list of register
values. @*
@*
@code{02 | 02 | 26 00 00 00 | 31 | 00 | ff ff ff ff | 09 00 [ 03 @{ 03 | cf e5 @} 03 @{ 00 | 00 00 @} ... ] } @*
@*

@table @code
@item 0x02
Begin response

@item 0x02
API Version 2

@item 0x00000026
Response length is 38

@item 0x31
@xref{MON_RESPONSE_REGISTER_INFO}.

@item 0x00
No error occurred

@item 0xffffffff
This response was not directly triggered by a command from the client.

@item 0x0009
The register array is 9 items long

@item @strong{PC:}
@table @code
@item 0x03
The register array item is 3 bytes long

@item 0x03
The register is the PC (ID 3) Note: you should find the names to these IDs using
the MON_CMD_REGISTERS_AVAILABLE command. @xref{MON_CMD_REGISTERS_AVAILABLE}.
Do not rely on them being consistent.

@item 0xe5cf
The register value is 0xe5cf

@end table

@item @strong{A:}
@table @code
@item 0x03
The register array item is 3 bytes long

@item 0x00
The register is A (ID 0) Note: you should find the names to these IDs using
the MON_CMD_REGISTERS_AVAILABLE command. @xref{MON_CMD_REGISTERS_AVAILABLE}.
Do not rely on them being consistent.

@item 0x0000
The register value is 0x0000

@end table

@end table

@item After the register information, the server sends a stopped event to indicate that the emulator is stopped. @*
@*
@code{02 | 02 | 02 00 00 00 | 62 | 00 | ff ff ff ff | cf e5 } @*
@*

@table @code
@item 0x02
Begin response

@item 0x02
API Version 2

@item 0x00000002
Response is two bytes long.

@item 0x62
Response type is 0x62, MON_RESPONSE_STOPPED.

@item 0xffffffff
This response was not directly triggered by a command from the client.

@item 0xe5cf
The current program counter

@end table

@item The server processes the checkpoint set command, and sends a response to the client. @*
@*
@code{ ... | 11 | ... | 02 00 00 00 | 00 | e2 fc | e3 fc | 01 | 01 | 04 | 01 | 00 00 00 00 | 00 00 00 00 | 00}@*
(Some response header fields are omitted (...) for brevity.)@*
@*

@table @code
@item 0x11
@xref{MON_RESPONSE_CHECKPOINT_INFO}.

@item 0x00000002
Checkpoint number is 2

@item 0x00
Checkpoint was not hit (as it was just created)

@item 0xfce2
Checkpoint start address

@item 0xfce3
Checkpoint end address

@item 0x01
The checkpoint will cause the emulator to stop.

@item 0x01
The checkpoint is enabled.

@item 0x04
The checkpoint will trigger on exec from 0xfce2 - 0xfce3.

@item 0x01
The checkpoint is temporary.

@item 0x00000000
The checkpoint has been hit zero times.

@item 0x00000000
The checkpoint has been ignored zero times.

@end table

@item Client sends a command to continue:@*
@*
@code{ ... | aa }@*
(Some command header fields are omitted (...) for brevity.)@*
@*

@table @code
@item 0xaa
@xref{MON_CMD_EXIT}.

@end table

@item Server acknowledges the command:@*
@*
@code{ ... | aa | ... } @*
(Some response header fields are omitted (...) for brevity.)@*
@*

@table @code
@item 0xaa
@xref{MON_CMD_EXIT}.

@end table

@item Server resumes execution and sends a resume event:@*
@*
@code{ ... | 63 | ... | cf e5 } @*
(Some response header fields are omitted (...) for brevity.)@*
@*

@table @code
@item 0x63
@xref{MON_RESPONSE_RESUMED}.

@item 0xe5cf
Program counter is currently at 0xe5cf

@end table

@item Some time later, the server hits the breakpoint. This causes it to emit
a checkpoint response. This is identical to the previous checkpoint response,
except that it is marked as "hit" and the hit and ignore counts are updated.

@item The server emits the register information and the stopped event when
reentering the monitor, as seen previously.

@end enumerate

@node Binary Commands
@section Commands

These are the possible command types and responses, without the header portions
mentioned above.

@menu
* MON_CMD_MEM_GET::
* MON_CMD_MEM_SET::
* MON_CMD_CHECKPOINT_GET::
* MON_CMD_CHECKPOINT_SET::
* MON_CMD_CHECKPOINT_DELETE::
* MON_CMD_CHECKPOINT_LIST::
* MON_CMD_CHECKPOINT_TOGGLE::
* MON_CMD_CONDITION_SET::
* MON_CMD_REGISTERS_GET::
* MON_CMD_REGISTERS_SET::
* MON_CMD_DUMP::
* MON_CMD_UNDUMP::
* MON_CMD_RESOURCE_GET::
* MON_CMD_RESOURCE_SET::
* MON_CMD_ADVANCE_INSTRUCTIONS::
* MON_CMD_KEYBOARD_FEED::
* MON_CMD_EXECUTE_UNTIL_RETURN::
* MON_CMD_PING::
* MON_CMD_BANKS_AVAILABLE::
* MON_CMD_REGISTERS_AVAILABLE::
* MON_CMD_DISPLAY_GET::
* MON_CMD_VICE_INFO::
* MON_CMD_PALETTE_GET::
* MON_CMD_JOYPORT_SET::
* MON_CMD_USERPORT_SET::
* MON_CMD_EXIT::
* MON_CMD_QUIT::
* MON_CMD_RESET::
* MON_CMD_AUTOSTART::
@end menu

@node MON_CMD_MEM_GET
@subsection Memory get (0x01)

Reads a chunk of memory from a start address to an end address (inclusive).

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: side effects?
Should the read cause side effects?

@item byte 1-2: start address

@item byte 3-4: end address

@item byte 5: memspace
Describes which part of the computer you want to read:

@itemize
@item 0x00: main memory
@item 0x01: drive 8
@item 0x02: drive 9
@item 0x03: drive 10
@item 0x04: drive 11
@end itemize

@item byte 6-7: bank ID
Describes which bank you want. This is dependent on your
machine. @xref{MON_CMD_BANKS_AVAILABLE}.  If the memspace selected
doesn't support banks, this value is ignored.

@end table

Response type:

0x01: MON_RESPONSE_MEM_GET

Response body:

@table @strong
@item byte 0-1: The length of the memory segment. Will be zero for start 0x0000, end 0xffff.

@item byte 2+: The memory at the address.

@end table

@node MON_CMD_MEM_SET
@subsection Memory set (0x02)

Writes a chunk of memory from a start address to an end address (inclusive).

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: side effects?
Should the write cause side effects?

@item byte 1-2: start address

@item byte 3-4: end address

@item byte 5: memspace
Describes which part of the computer you want to write:

@itemize
@item 0x00: main memory
@item 0x01: drive 8
@item 0x02: drive 9
@item 0x03: drive 10
@item 0x04: drive 11
@end itemize

@item byte 6-7: bank ID
Describes which bank you want. This is dependent on your machine. 
@xref{MON_CMD_BANKS_AVAILABLE}.  
If the memspace selected doesn't support banks, this byte is ignored.

@item byte 8+: Memory contents to write

@end table

Response type:

0x02: MON_RESPONSE_MEM_SET

Response body:

Currently empty.

@node MON_CMD_CHECKPOINT_GET
@subsection Checkpoint get (0x11)

Gets any type of checkpoint. (break, watch, trace)

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0-3: checkpoint number

@end table

@xref{MON_RESPONSE_CHECKPOINT_INFO}.

@node MON_CMD_CHECKPOINT_SET
@subsection Checkpoint set (0x12)

Sets any type of checkpoint. This combines the functionality of several
textual commands (break, watch, trace) into one, as they are all the same
with only minor variations. To set conditions, @pxref{MON_CMD_CONDITION_SET} after
executing this one.

Command body:

@table @strong
@item byte 0-1: start address

@item byte 2-3: end address

@item byte 4: stop when hit
>=0x01: true, 0x00: false

@item byte 5: enabled
>=0x01: true, 0x00: false

@item byte 6: CPU operation
>=0x01: load, 0x02: store, 0x04: exec

@item byte 7: temporary
    Deletes the checkpoint after it has been hit once. This is similar to
    "until" command, but it will not resume the emulator.

@item byte 8 (optional): memspace
Describes which part of the computer to checkpoint:

@itemize
@item 0x00: main memory
@item 0x01: drive 8
@item 0x02: drive 9
@item 0x03: drive 10
@item 0x04: drive 11
@end itemize

@end table

@xref{MON_RESPONSE_CHECKPOINT_INFO}.

@node MON_CMD_CHECKPOINT_DELETE
@subsection Checkpoint delete (0x13)

Deletes any type of checkpoint. (break, watch, trace)

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0-3: checkpoint number

@end table

Response type:

0x13: MON_RESPONSE_CHECKPOINT_DELETE

Response body:

Currently empty.

@node MON_CMD_CHECKPOINT_LIST
@subsection Checkpoint list (0x14)

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

Emits a series of MON_RESPONSE_CHECKPOINT_INFO responses
(@pxref{MON_RESPONSE_CHECKPOINT_INFO}) followed by

0x14: MON_RESPONSE_CHECKPOINT_LIST

Response body:

@table @strong
@item byte 0-3: The total number of checkpoints

@end table

@node MON_CMD_CHECKPOINT_TOGGLE
@subsection Checkpoint toggle (0x15)

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0-3: Checkpoint number

@item byte 4: Enabled?
0x00: disabled, 0x01: enabled

@end table

Response type:

0x15: MON_RESPONSE_CHECKPOINT_TOGGLE

Response body:

Currently empty.

@node MON_CMD_CONDITION_SET
@subsection Condition set (0x22)

Sets a condition on an existing checkpoint. It is not currently possible to
retrieve conditions after setting them.

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0-3: checkpoint number

@item byte 4: condition expression length

@item byte 5+: condition expression string
This is the same format used on the command line. Not null terminated.

@end table

Response type:

0x22: MON_RESPONSE_CONDITION_SET

Response body:

Currently empty.

@node MON_CMD_REGISTERS_GET
@subsection Registers get (0x31)

Get details about the registers

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: memspace
Describes which part of the computer you want to read:

@itemize
@item 0x00: main memory
@item 0x01: drive 8
@item 0x02: drive 9
@item 0x03: drive 10
@item 0x04: drive 11
@end itemize

@end table

@xref{MON_RESPONSE_REGISTER_INFO}.

@node MON_CMD_REGISTERS_SET
@subsection Registers set (0x32)

Set the register values

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: memspace
Describes which part of the computer you want to write:

@itemize
@item 0x00: main memory
@item 0x01: drive 8
@item 0x02: drive 9
@item 0x03: drive 10
@item 0x04: drive 11
@end itemize

@item byte 1-2: The count of the array items

@item byte 3+: An array with items of structure:

@table @strong
@item byte 0: Size of the item, excluding this byte
@item byte 1: ID of the register
@item byte 2-3: register value
@end table

@end table

@xref{MON_RESPONSE_REGISTER_INFO}.

@node MON_CMD_DUMP
@subsection Dump (0x41)

Saves the machine state to a file.

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: Save ROMs to snapshot file?
>=0x01: true, 0x00: false

@item byte 1: Save disks to snapshot file?
>=0x01: true, 0x00: false

@item byte 2: Length of filename

@item byte 3+: Filename
The filename to save the snapshot to.

@end table

Response type:

0x41: MON_RESPONSE_DUMP

Response body:

Currently empty.

@node MON_CMD_UNDUMP
@subsection Undump (0x42)

Loads the machine state from a file.

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: Length of filename

@item byte 1+: Filename
The filename to load the snapshot from.

@end table

Response type:

0x42: MON_RESPONSE_UNDUMP

Response body:

@table @strong
@item byte 0-1: The current program counter position

@end table

@node MON_CMD_RESOURCE_GET
@subsection Resource Get (0x51)

Get a resource value from the emulator. @xref{Resource files, Resources and command-line, Settings and resources, Settings and resources}.

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: Length of resource name

@item byte 1+: Resource name

@end table

Response type:

0x51: MON_RESPONSE_RESOURCE_GET

Response body:

@table @strong
@item byte 0: Type of the resource
0x00: String, 0x01: Integer

@item byte 1: Length of the value

@item byte 2+: The value

@end table

@node MON_CMD_RESOURCE_SET
@subsection Resource Set (0x52)

Set a resource value in the emulator. @xref{Resource files, Resources and command-line, Settings and resources, Settings and resources}.

Minimum VICE version: 3.5

Command body:

@table @strong
@item 1 byte: Type of the resource value
0x00: String, 0x01: Integer@*
Strings will be interpreted if the destination is an Integer.

@item 1 byte: Resource name length = (&name)

@item (*name) bytes: The resource name

@item 1 byte: Resource value length = (&value)

@item (*value) bytes: The resource value

@end table

Response type:

0x52: MON_RESPONSE_RESOURCE_SET

Response body:

Currently empty.

@node MON_CMD_ADVANCE_INSTRUCTIONS
@subsection Advance Instructions (0x71)

Step over a certain number of instructions.

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: Step over subroutines?
Should subroutines count as a single instruction?

@item byte 1-2: How many instructions to step over.

@end table

Response type:

0x71: MON_RESPONSE_ADVANCE_INSTRUCTIONS

Response body:

Currently empty.

@node MON_CMD_KEYBOARD_FEED
@subsection Keyboard feed (0x72)

Add text to the keyboard buffer.

Minimum VICE version: 3.5

Minimum API version: 2

Command body:

@table @strong
@item byte 0: Length of text

@item byte 1+: The text, in PETSCII

@end table

Response type:

0x72: MON_RESPONSE_KEYBOARD_FEED

Response body:

Currently empty.

@node MON_CMD_EXECUTE_UNTIL_RETURN
@subsection Execute until return (0x73)

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

This command is the same as "return" in the text monitor.

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

0x73: MON_RESPONSE_EXECUTE_UNTIL_RETURN

Response body:

Currently empty.

@node MON_CMD_PING
@subsection Ping (0x81)

Get an empty response

Minimum VICE version: 3.5

Command body:

Always empty

Response type:

0x81: MON_RESPONSE_PING

Response body:

Always empty

@node MON_CMD_BANKS_AVAILABLE
@subsection Banks available (0x82)

Gives a listing of all the bank IDs for the running machine with their names.

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

0x82: MON_RESPONSE_BANKS_AVAILABLE

Response body:

@table @strong
@item byte 0-1: The count of the array items
@item byte 2+: An array with items of structure:

@table @strong
@item byte 0: Size of the item, excluding this byte

@item byte 1-2: bank ID

@item byte 3: Name length

@item byte 4+: Name

@end table

@end table

@node MON_CMD_REGISTERS_AVAILABLE
@subsection Registers available (0x83)

Gives a listing of all the registers for the running machine with their names.

Minimum VICE version: 3.5

Command body:

@table @strong

@item byte 0: memspace
Describes which part of the computer you want to read:

@itemize
@item 0x00: main memory
@item 0x01: drive 8
@item 0x02: drive 9
@item 0x03: drive 10
@item 0x04: drive 11
@end itemize

@end table

Response type:

0x82: MON_RESPONSE_REGISTERS_AVAILABLE

Response body:

@table @strong
@item byte 0-1: The count of the array items
@item byte 2+: An array with items of structure:

@table @strong

@item byte 0: Size of the item, excluding this byte

@item byte 1: ID of the register

@item byte 2: Size of the register in bits

@item byte 3: Length of name

@item byte 4+: Name

@end table

@end table

@node MON_CMD_DISPLAY_GET
@subsection Display Get (0x84)

Gets the current screen in a requested bit format.

Minimum VICE version: 3.5

Minimum API version: 2

Command body:

@table @strong
@item byte 0: USE VIC-II? 
Must be included, but ignored for all but the C128. If true, (>=0x01) the screen
returned will be from the VIC-II. If false (0x00), it will be from the VDC.

@item byte 1: Format
0x00: Indexed, 8 bit@*

@end table

Response type:

0x84: MON_RESPONSE_DISPLAY_GET

Response body:

@table @strong
@item 4 bytes: Length of the fields before the display buffer

@item 2 bytes: Debug width of display buffer (uncropped)
The largest width the screen gets.

@item 2 bytes: Debug height of display buffer (uncropped)
The largest height the screen gets.

@item 2 bytes: X offset
X offset to the inner part of the screen.

@item 2 bytes: Y offset 
Y offset to the inner part of the screen.

@item 2 bytes: Width of the inner part of the screen.

@item 2 bytes: Height of the inner part of the screen.

@item 1 byte: Bits per pixel of display buffer, 8


@item 4 bytes: Length of display buffer = (&buffer)

@item (*buffer) bytes: Display buffer data

@end table

@node MON_CMD_VICE_INFO
@subsection VICE info (0x85)

Get general information about VICE. Currently returns the versions.

Minimum VICE version: 3.6

Command body:

Always empty

Response type:

0x85: MON_RESPONSE_VICE_INFO

Response body:

@table @strong
@item 1 byte: Length of main version = (&main)

@item (*main) bytes: Main version
In linear format. For example 0x03, 0x05, 0x00, 0x00 for 3.5.0.0

@item 1 byte: Length of SVN revision = (&rev)

@item (*rev) bytes: SVN revision
In little endian format. Returns zero if it's not an SVN build.

@end table

@node MON_CMD_PALETTE_GET
@subsection Palette get (0x91)

Get the colors in the current palette

Minimum VICE version: 3.6

Command body:

@table @strong
@item byte 0: USE VIC-II? 
Must be included, but ignored for all but the C128. If true, (>=0x01) the screen
returned will be from the VIC-II. If false (0x00), it will be from the VDC.

@end table

Response type:

0x91: MON_RESPONSE_PALETTE_GET

Response body:

@table @strong
@item byte 0-1: The number of palette items.

@item byte 2+: An array with items of structure:

@table @strong
@item byte 0: Size of the item, excluding this byte

@item byte 1: Red

@item byte 2: Green

@item byte 3: Blue

@end table

@end table

@node MON_CMD_JOYPORT_SET
@subsection Joyport set (0xa2)

Set the simulated joyport value.

Minimum VICE version: 3.6

Command body:

@table @strong
@item byte 0-1: The port to set the value on
@item byte 2-3: The value to set

@end table

Response type:

0xa2: MON_RESPONSE_JOYPORT_SET

Response body:

Currently empty.


@node MON_CMD_USERPORT_SET
@subsection Userport set (0xb2)

Set the simulated userport value.

Minimum VICE version: 3.6

Command body:

@table @strong
@item byte 0-1: The value to set

@end table

Response type:

0xb2: MON_RESPONSE_USERPORT_SET

Response body:

Currently empty.

@node MON_CMD_EXIT
@subsection Exit (0xaa)

Exit the monitor until the next breakpoint.

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

0xaa: MON_RESPONSE_EXIT

Response body:

Currently empty.

@node MON_CMD_QUIT
@subsection Quit (0xbb)

Quits VICE.

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

0xbb: MON_RESPONSE_QUIT

Response body:

Currently empty.

@node MON_CMD_RESET
@subsection Reset (0xcc)

Reset the system or a drive

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: What to reset

@itemize
@item 0x00: Soft reset system
@item 0x01: Hard reset system
@item 0x08 - 0x0b: Reset drives 8 - 11
@end itemize

@end table

Response type:

0xcc: MON_RESPONSE_RESET

Response body:

Currently empty.

@node MON_CMD_AUTOSTART
@subsection Autostart / autoload (0xdd)

Load a program then return to the monitor

Minimum VICE version: 3.5

Command body:

@table @strong
@item byte 0: Run after loading?
>=0x01: true, 0x00: false

@item byte 1-2: File index
The index of the file to execute, if a disk image. 0x00 is the default value.

@item byte 3: Length of filename

@item byte 4+: Filename
The filename to autoload.

@end table

Response type:

0xdd: MON_RESPONSE_AUTOSTART

Response body:

Currently empty.

@node Binary Responses
@section Responses

These responses are generated by many different commands, or by certain events.
Events are generated with a request ID of 0xffffffff, so that they can be easily
distinguished from regular requests.

@menu
* MON_RESPONSE_INVALID::
* MON_RESPONSE_CHECKPOINT_INFO::
* MON_RESPONSE_REGISTER_INFO::
* MON_RESPONSE_JAM::
* MON_RESPONSE_STOPPED::
* MON_RESPONSE_RESUMED::
@end menu

@node MON_RESPONSE_INVALID
@subsection Invalid Response (0x00)

This response type is returned for errors.

Response type:

0x00: MON_RESPONSE_INVALID

Response body:

Usually empty

@node MON_RESPONSE_CHECKPOINT_INFO
@subsection Checkpoint Response (0x11)

This response is generated by hitting a checkpoint, or by many of the checkpoint
commands.

@xref{MON_CMD_CHECKPOINT_GET}.

@xref{MON_CMD_CHECKPOINT_SET}.

@xref{MON_CMD_CHECKPOINT_LIST}.

Response type:

0x11: MON_RESPONSE_CHECKPOINT_INFO

Response body:

@table @strong
@item byte 0-3: Checkpoint number

@item byte 4: Currently hit?
>=0x01: true, 0x00: false

@item byte 5-6: start address

@item byte 7-8: end address

@item byte 9: stop when hit
>=0x01: true, 0x00: false

@item byte 10: enabled
>=0x01: true, 0x00: false

@item byte 11: CPU operation
0x01: load, 0x02: store, 0x04: exec

@item byte 12: temporary
Deletes the checkpoint after it has been hit once. This is similar to
"until" command, but it will not resume the emulator.

@item byte 13-16: hit count

@item byte 17-20: ignore count

@item byte 21: Has condition?
>=0x01: true, 0x00: false

@item byte 22: memspace

@itemize
@item 0x00: main memory
@item 0x01: drive 8
@item 0x02: drive 9
@item 0x03: drive 10
@item 0x04: drive 11
@end itemize

@end table

@node MON_RESPONSE_REGISTER_INFO
@subsection Register Response (0x31)

Response type:

0x31: MON_RESPONSE_REGISTER_INFO

Response body:

@table @strong
@item byte 0-1: The count of the array items

@item byte 2+: An array with items of structure:

@table @strong
@item byte 0: Size of the item, excluding this byte

@item byte 1: ID of the register

@item byte 2-3: register value

@end table

@end table


@node MON_RESPONSE_JAM
@subsection JAM Response (0x61)

When the CPU jams

Response type:

0x61: MON_RESPONSE_JAM

Response body:

@table @strong
@item byte 0-1: The current program counter position

@end table

@node MON_RESPONSE_STOPPED
@subsection Stopped Response (0x62)

When the machine stops for the monitor, 
either due to hitting a checkpoint or stepping.

Response type:

0x62: MON_RESPONSE_STOPPED

Response body:

@table @strong
@item byte 0-1: The current program counter position

@end table

@node MON_RESPONSE_RESUMED
@subsection Resumed Response (0x63)

When the machine resumes execution for any reason.

Response type:

0x63: MON_RESPONSE_RESUMED

Response body:

@table @strong
@item byte 0-1: The current program counter position

@end table


@node Binary Example Projects
@section Example Projects

Here's a short list of some projects using the binary monitor interface:
@sp 1

@multitable @columnfractions .25 .75
@item C64 Studio
@tab IDE for assembly and BASIC projects, geared toward game development.
@* @url{https://github.com/GeorgRottensteiner/C64Studio}

@item VICE Binary Monitor Bridge for .NET
@tab A cross platform .NET 5 library that implements a bridge for communication
with the VICE binary monitor.
@* @url{https://github.com/MihaMarkic/vice-bridge-net}

@item IceBro Lite
@tab IceBro Lite is a source-level debugger with a graphical user interface
(GUI).
@* @url{https://github.com/Sakrac/IceBroLite}

@item VS65 Debugger
@tab Visual Studio Code extension to debug CC65 projects.
@* @url{https://github.com/empathicqubit/vscode-cc65-debugger}

@item VS64
@tab The VS64 extension makes it easy to build, debug, inspect and run C64
assembly code from Visual Studio Code.
@* @url{https://github.com/rolandshacks/vs64}

@end multitable


@node c1541
@chapter c1541

VICE is provided with a complete stand-alone disk image maintenance
utility, called @code{c1541}.

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

@node c1541 file specification
@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
@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
@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 bam [<unit>] | <track-min> <track-max> [<unit>]
Show the BAM of @code{unit}, optionally displaying only the entries for
@code{track-min} to @code{track-max}

@item bcopy <src-trk> <src-sec> <dst-trk> <dst-sec> [<src-unit> [<dst-unit>]]
Copy a block to another block, optionally specifying different source and
destination units. The block is copied using all 256 bytes.

@item bfill <track> <sector> <value> [<unit>]
Fill a block with a single value.

@item block <track> <sector> [<offset> [<unit>]]
Show specified disk block in hex form.

@item bpoke [@@unit:<unit>] <track> <sector> <offset> <data @dots{}>
Store one or more bytes of @code{data} into a block. The @code{data} can be
specified using prefixes:
@table @code
@item 0b or %
binary value (`%11111111`)
@item &
octal value (`&377`)
@item 0x or $
hexadecimal value (`$ff`)
@end table
The <unit> is optional, and when used must use the CBM DOS notation for the
unit number, for example `@@9:`.

@item bpeek [@@unit:<unit>] <track> <sector> [<start> [<end>]]
Print one or more bytes of @code{track,sector}.

@item bread <filename> <track> <sector> [<unit>]
Read a block from a disk image and write it to the host filesystem as
@code{filename}.

@item bwrite <filename> <track> <sector> [<unit>]
Write data from the host filesystem using @code{filename} as input. At most 256
bytes are written to the disk image.

@item cd <dir>
Change the current working directory to @code{dir}.

@item chain <track> <sector> [<unit>] | <filename>
Show block chain starting at (@code{track}, @code{sector}), or alternatively use @code{filename} to show the block chain of a file in the directory. The last number
shown is the number of bytes used in the final block.

@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:}).
To copy a REL file, specify the <source> with a @code{,L} file type suffix.

@item delete <file1> [<file2> @dots{} <fileN>]
Delete the specified files.

@item disable-libdebug-output
Disable output of src/lib.c's leak list. This is a debug hook for the c1541
test bench.

@item exit
Exit (same as @code{quit}).

@item entry [+side] <file1> [<file2> @dots{} <fileN>]
Show the directory entries of the given files in full detail.
If the @code{+side} option is present, and it is a RELative file,
it also shows all side sectors.

@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{g71} (VC1571 but in GCR coding), @code{d81}
(VC1581), @code{d80} (CBM8050), @code{d82} (CBM8250/1001),
or @code{d90} (CBM D9090).
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 pwd
Print current working directory.

@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}.
By default PRG files are copied. To copy SEQ files add @code{,s}
(i.e. the usual DOS file specification syntax).
REL files can be copied by adding @code{,l}. Don't specify the record length,
@code{c1541} will determine it automatically.

@item rename <oldname> <newname>
Rename @code{oldname} into @code{newname}.  The files must be on the
same drive.

@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 ["off"]
Enable or disable verbose output.

@item version
Show C1541 version string

@item write <source> [<destination>]
Write @code{source} from the file system into @code{destination} on a
disk image.

To create a REL file, you must specify the @code{destination} including the
record length.
As a special convenience, you can give it in decimal.
Example: @code{write fsname imgname,l,100}
Note that the size of the file may be rounded up to fill the last sector.

@item unzip <d64name> <zipname> [<label,id>]
Create a D64 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
@section Executing shell commands

If you want to execute a shell command from within @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.

@node c1541 examples
@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

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

@example
convert:    cartconv [-r] [-q|-v] [-t cart type] [-s cart revision] -i "input name" -o "output name" [-n "cart name"] [-l load address]
print info: cartconv [-r] [-q|-v] -f "input name"
check file: cartconv [-r] [-q|-v] -c "input name"

-f <name>                   print info on file
-c --check <name>           check file
-r                          repair mode (accept broken/invalid input files)
-p                          accept non padded binaries as input
-b                          output all banks (do not optimize the .crt file)
-t <type> or <crtid>        output cart type
-s <rev>                    output cart revision/subtype
-i <name>                   input filename
-o <name>                   output filename
-n <name>                   crt cart name
-l <addr>                   load address
-q                          quiet
-v --verbose                verbose
--types                     show the supported cart types
--version                   print cartconv version
--options-file <filename>   write options for reverting the conversion into a file (for test script)
@end example

@section cartconv command line options

The cartconv program has the following parameters:

@table @code
@findex -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.
@findex -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.
@findex -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.
@findex -s
@item -s revision
This parameter is optional. It is only needed when converting to a .crt
file. See the detailed description of the .crt format for which types support
subtypes/revisions.
@findex -n
@item -n "cart name"
This parameter is optional and is used as the cartridge name when creating
a .crt file. By default the cartridge name will be set to the cartridge type.
@findex -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.
@findex -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.
@findex -c
@item -c "input name"
@findex --check
@item --check "input name"
Works similar to -f, but does not output anything except on errors. On errors it
will also make cartconv exit with an exitcode of -1.
@findex -r
@item -r
This parameter is optional, it enables repair mode (accept broken input files)
@findex -p
@item -p
This parameter is optional, when it is given cartconv will accept input files that
do not match the cartridge sizes (useful for development).
@findex -b
@item -b
This parameter is optional, when it is given cartconv will not omit banks that
are empty (filled with $ff).
@findex -q
@item -q
This parameter is optional, it disables all non-error messages
@findex -v
@item -v
@findex --verbose
@item --verbose
This parameter is optional, it enables more verbose messages
@findex --types
@item --types
This parameter is optional. It shows all supported cartridge types (see below).
@findex --version
@item --version
Show cartconv version string and exit
@findex --options-file
@item --options-file <filename>
This parameter is optional. If present, cartconv writes options for reverting
the conversion into a file, this is mostly useful for the test script.
@end table

@c @node FIXME
@section cartconv supported cartridge types

The following cartridge types are supported:

@table @code
@item bin
Binary .bin file (Default crt->bin)
@item prg
Binary C64 .prg file with load-address
@end table

@b{C64 cartridges:}

@table @code
@item normal
Generic 8KiB/12KiB/16KiB .crt file (Default bin->crt)
@item ulti
Ultimax mode 4KiB/8KiB/16KiB .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 bis
BIS-Plus .crt file
@item bb3
Blackbox V3 .crt file
@item bb4
Blackbox V4 .crt file
@item bb8
Blackbox V8 .crt file
@item bb9
Blackbox V9 .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 ecr
Easy Calc Result .crt file
@item epyx
Epyx FastLoad .crt file
@item exos
EXOS .crt file
@item expert
Expert Cartridge .crt file
@item f64
Formel 64 .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 ff2
Freeze Frame MK2 .crt file
@item fm
Freeze Machine .crt file
@item fp
Fun Play .crt file
@item gk
Game Killer .crt file
@item gmod2
GMod2 .crt file
@item gmod3
GMod3 .crt file
@item gs
C64 Games System .crt file
@item ide64
IDE64 .crt file
@item ieee
IEEE-488 Interface .crt file
@item ieeeflash64
IEEE Flash! 64 interface .crt file
@item kcs
KCS Power Cartridge .crt file
@item ks
Kingsoft .crt file
@item ltk
Lt. Kernal Host Adaptor .crt file
@item mach5
MACH 5 .crt file
@item md
Magic Desk .crt file
@item mf
Magic Formel .crt file
@item max
MAX Basic .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 mm
MultiMAX .crt file
@item ocean
Ocean .crt file
@item p64
Prophet64 .crt file
@item pf
Pagefox .crt file
@item partner64
Partner 64 .crt file
@item rep256
REX 256KiB 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 rrnet
RR-Net MK3 .crt file
@item rrf
REX RAM-Floppy .crt file
@item ru
REX Utility .crt file
@item sdbox
SD-BOX .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 silver
Silverrock 128KiB Cartridge .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 turtle
Turtle Graphics II .crt file
@item wl
Westermann Learning .crt file
@item ws
Warp Speed .crt file
@item zaxxon
Zaxxon .crt file
@item zipp
ZIPP-CODE 48 .crt file
@end table

@itemize @bullet
@item (1) insertion of 32KiB EPROM files supported.
@item (2) insertion of 8KiB .crt/binary files supported.
@item (3) insertion of 16KiB .crt/binary files supported.
@end itemize

@b{C128 cartridges:}

@table @code
@item c128
generic C128 cartridge ("external function ROM")
@item comal128
Comal 80
@item gmod128
Gmod2-C128
@item md128
Magic Desk 128
@item partner128
Partner 128
@item ws128
Warpspeed128
@end table

@b{VIC20 cartridges:}

@table @code
@item vic20
Generic 8KiB/12KiB/16KiB cartridge
@item bb
Behr Bonz
@item fe3
Final Expansion
@item mega
Mega-Cart
@item um
UltiMem
@item vicfp
Vic Flash Plugin
@end table

@b{PLUS4 cartridges:}

@table @code
@item plus4
Generic 4KiB/8KiB/16KiB/32KiB cartridge
@item c1lo
Generic 4KiB/8KiB/16KiB C1LO cartridge
@item c1hi
Generic 4KiB/8KiB/16KiB C1HI cartridge
@item c2lo
Generic 4KiB/8KiB/16KiB C2LO cartridge
@item c2hi
Generic 4KiB/8KiB/16KiB C2HI cartridge
@item jacint
1MB Cartridge
@item magic
c264 magic cart
@item multi
Plus4 multi cart
@end table

@b{CBM2 cartridges:}

@b{TODO - not implemented yet}

@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 32KiB EPROM file into an dep64 type cartridge.
@itemize @bullet
@item step 1 : use the dep64 binary file in VICE as a generic 8KiB 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 8KiB .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 8KiB .crt files into a rep256 type cartridge.
@item cartconv -f foo.crt
Get information about a .crt file.
@end table

@node Petcat
@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
@findex -help
@item -help
Output help text
@findex -?
@item -?
Same as above
@findex -version
@item -version
show petcat version string and exit
@findex -v
@item -v
verbose output
@findex -c
@item -c
controls (interpret also control codes) (default if textmode)
@findex -nc
@item -nc
no controls (suppress control codes in printout) (default if non-textmode)
@findex -qc
@item -qc
convert all non alphanumeric characters inside quotes into controlcodes
@findex -ic
@item -ic
interpret control codes case-insensitive
@findex -d
@item -d
output raw codes in decimal
@findex -h
@item -h
write header (default if output is stdout)
@findex -nh
@item -nh
no header (default if output is a file)
@findex -skip <n>
@item -skip <n>
Skip <n> bytes in the beginning of input file. Ignored on P00.
@findex -text
@item -text
Force text mode
@c @findex -<version> - this one breaks the index (?!)
@item -<version>
use keywords for <version> instead of the v7.0 ones
@findex -w<version>
@item -w<version>
tokenize using keywords on specified Basic version.
@findex -k<version>
@item -k<version>
list all keywords for the specified Basic version
@findex -k
@item -k
list all Basic versions available.
@findex -l
@item -l
Specify load address for program (in hex, no loading chars!).
@findex -o <name>
@item -o <name>
Specify the output file name
@findex -f
@item -f
Force overwritten the output file. The default depends on the BASIC version.
@end table

BASIC Versions:
@table @code
@item 10
Basic v10.0 (C65/C64DX)
@item 1p
Basic v1.0 (PET)
@item 2
Basic v2.0 (C64/VIC20/PET)
@item 3
Basic v3.5 (C16)
@item 40
Basic v4.0 (PET/CBM2)
@item 4e
Basic v2.0 with Basic v4.0 extension (C64)
@item 4v
Basic v2.0 with Basic v4.0 extension (VIC20)
@item 5
Basic v2.0 with Basic v5.0 extension (VIC20)
@item 65
Basic v65.0 (Mega65)
@item 70
Basic v7.0 (C128)
@item 71
Basic v7.0 with Basic v7.1 extension (C128)
@item a
Basic v2.0 with AtBasic (C64)
@item bk
Basic v2.0 with Kipper Basic (C64)
@item blarg
Basic v2.0 with Blarg (C64)
@item bob
Basic v2.0 with Basic on Bails (C64)
@item bsx
Basic v2.0 with Basex (C64)
@item bwarsaw
Basic v2.0 with Warsaw Basic (C64)
@item bws
Basic v2.0 with WS Basic (C64)
@item bwsf
Basic v2.0 with WS Basic final (C64)
@item drago
Basic v2.0 with Drago basic v2.2 (C64)
@item easy
Basic v2.0 with Easy Basic (VIC20)
@item eve
Basic v2.0 with Eve Basic (C64)
@item exp20
Basic v2.0 with Expanded Basic (VIC20)
@item exp64
Basic v2.0 with Expanded Basic (C64)
@item f
Basic v2.0 with Final Cartridge III (C64)
@item game
Basic v2.0 with Game Basic (C64)
@item graph
Basic v2.0 with Graphics basic (C64)
@item lightning
Basic v2.0 with Basic Lightning (C64)
@item magic
Basic v2.0 with Magic Basic (C64)
@item mighty
Basic v2.0 with Mighty Basic by Craig Bruce (VIC20)
@item pegasus
Basic v2.0 with Pegasus Basic v4.0 (C64)
@item reu
Basic v2.0 with REU-Basic (C64)
@item simon
Basic v2.0 with Simons' Basic extension (C64)
@item speech
Basic v2.0 with Speech Basic v2.7 (C64)
@item superbas
Basic v2.0 with Super Basic (C64)
@item superexp
Basic v2.0 with Super Expander (VIC20)
@item supergra
Basic v2.0 with Supergrafik 64 (C64)
@item sxc
Basic v2.0 with Super Expander Chip (C64)
@item tt64
Basic v2.0 with The Tool 64 (C64)
@item turtle
Basic v2.0 with Turtle Basic by Craig Bruce (VIC20)
@item ultra
Basic v2.0 with Ultrabasic-64 (C64)
@item xbasic
Basic v2.0 with Xbasic (C64)
@end table

@c @node FIXME
@section petcat examples

@table @code
@item @code{petcat -2 -o outputfile.txt -- inputfile.prg}
De-tokenize, Convert inputfile.prg to a text file in outputfile.txt, using BASIC V2 only
@item @code{petcat -wsimon -o outputfile.prg -- inputfile.txt}
Tokenize, Convert inputfile.txt to a PRG file in outputfile.prg, using Simons' BASIC
@item @code{petcat -text -o outputfile.txt -- inputfile.seq}
Convert inputfile.seq to a Ascii text file in outputfile.txt.
@item @code{petcat -text -w2 -o outputfile.seq -- inputfile.txt}
Convert inputfile.txt to a Petscii text SEQ file in outputfile.seq.
@end table

@node File formats
@chapter The emulator file formats

This chapter gives a technical description of the various files
supported by the emulators.

@menu
* TAP::                         The raw tape image format
* 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
* D90::                         The D90 disk image format
* X64::                         The X64 disk image format
* DHD::                         The DHD disk image format
* P00::                         The P00 image format
@end menu

@node TAP, T64, File formats, File formats
@section The raw tape image format

(This section is based on v1.1 TAP specification by Per Hakan Sundell and Markus 
Brenner, additional format v2 expansion by Markus Brenner, plus some editing
by groepaz, with some more VICE extensions)

Designed by Per Hakan Sundell (author of the CCS64 C64 emulator) in 1997, this
format attempts to duplicate the data stored on a cassette tape, bit for bit.
Since it is simply a representation of the raw serial data from a tape, it
should handle *any* custom tape loaders that exist.

The TAP images are generally very large, being a minimum of eight times, and up
to sixteen times as large as what a raw PRG file would be. This is due to the
way the data is stored, with each bit of the original file now being one byte
large in the TAP file. The layout is fairly simple, with a small 14-byte header
followed by file data.

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 2D 54 41 50 45 2D 52 41 57 00 00 00 00   C64-TAPE-RAW????
0010: 51 21 08 00 2F 0F 0D 31 64 1D 26 0D 07 21 0A 12   Q!??/??1d?&??!??
0020: 4A 2F 2C 34 07 18 0D 31 07 04 23 04 0D 42 0D 1E   J/,4???1??#??B??
0030: 34 04 42 0D 20 15 5E 04 0D 18 61 0D 26 29 34 0D   4?B???^???a?&)4?
0040: 23 0D 07 0A 3F 55 04 0A 13 3F 07 0D 12 2B 18 0A   #????U???????+??
@end example

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $0000-000B
@tab File signature (@code{C64-TAPE-RAW} (v0 and v1) or @code{C16-TAPE-RAW} (v2 only))
@item $000C
@tab @code{TAP} version (see below for description), $00 - Original layout, 
$01 - Updated, $02 - Halfwave Extension
@item $000D
@tab Computer Platform (0 = C64, 1 = VIC-20, 2 = C16, Plus/4, 3 = PET, 4 = C5x0, 5 = C6x0, C7x0)
@item $000E
@tab Video Standard (0 = PAL, 1 = NTSC, 2 = OLD NTSC, 3 = PALN)
@item $000F
@tab reserved for future expansion
@item $0010-0013
@tab File data size (not including this header, in LOW/HIGH format) i.e. The
above example image is $00082151  bytes long.
@item $0014-xxxx
@tab File data
@end multitable

In TAP version $00 files, each data byte in the file data area represents the
length of a pulse, when the hardware will trigger again. This pulse length is
determined by the following formula:
@example
    pulse length (in seconds) = (8 * data byte) / (clock cycles)
@end example
A data value of $00 represents an "overflow" condition, any pulse length which
is more that 255 * 8 in length.

For example, assuming the image was made on a PAL C64, a data value of $2F (47
in decimal) would be:
@example
    (47 * 8) / 985248 = .00038975 seconds.
@end example

The number of clock cycles per second refer to the clock rate the timers used
for the tape routines in the respective computer system count with, and can be
derived from the given computer platform and video standard, as in the following table:

@multitable @columnfractions .3 .3 .4
@item @b{Computer platform}
@tab @b{Video standard}
@tab @b{Timer clock speed}
@item 0 = C64
@tab 0 = PAL
@tab 985248 kHz
@item
@tab 1 = NTSC
@tab 1022730 kHz
@item
@tab 2 = OLD NTSC
@tab 1022730 kHz
@item
@tab 3 = PAL N
@tab 1023440 kHz
@item 1 = VIC-20
@tab 0 = PAL
@tab 1108405 kHz
@item
@tab 1 = NTSC
@tab 1022727 kHz
@item 2 = C16 / Plus4 (*)
@tab 0 = PAL
@tab 886724 kHz
@item
@tab 1 = NTSC
@tab 894886 kHz
@item 3 = PET
@tab 0 = PAL
@tab 1000000 kHz
@item
@tab 1 = NTSC
@tab 1000000 kHz
@item 4 = C5x0
@tab 0 = PAL
@tab 985248 kHz
@item
@tab 1 = NTSC
@tab 1022730 kHz
@item 5 = C6x0 / C7x0
@tab 0 = PAL
@tab 2000000 kHz
@item
@tab 1 = NTSC
@tab 2000000 kHz
@end multitable

(*) The TED timers always run with the slower clock rate (886724 Hz for PAL
machines), so the length of one TAP pulse should be relative to this frequency.

The original format did not include the "computer platform" and "video system"
field, and the number of clock cycles per second was assumed to always be 985248,
as if the tape was recorded on a PAL C64.

In TAP version $01 files, the data value of $00 has been re-purposed to
represent cycle exact values, which may also be greater than 255 * 8. When a $00
is encountered, three bytes will follow which are the actual time (in cycles)
of a pulse, and the above formula does not apply. The three bytes are stored in
LOW/HIGH format.

TAP Version 2 is an extension made by Markus Brenner for C16 tapes. It is
version 1, but each value represents a halfwave, starting with a '0'->'1'
transition. The time encoding doesn't change.

The actual interpretation of the serial data takes a little more work to
explain. The typical ROM tape loader (and some of the turbo loaders) will
initialize a timer with a specified value and start it counting down. If either
the tape data changes or the timer runs out, an IRQ will occur. The loader will
determine which condition caused the IRQ. If the tape data changed before the
timer ran out, we have a short pulse, or a "0" bit. If the timer ran out first,
we have a long pulse, or a  "1"  bit. Doing this continuously and we decode the
entire file.

Plus4 implementation hints: When playing back a TAP on a Plus/4 emulator,
you should write a routine that sets the CAS_READ line to '0' for half of the
time and '1' for the other half. This should be easy to implement, as your
emulator probably counts in units of clock cycles anyway :) As for writing to
a TAP file, you need to watch the CAS_WRITE register (processor port, bit 0x02)
and start counting whenever a 0->1 transition happens.

@node T64, G64, TAP, 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 .1 .1 .8
@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 .1 .1 .8
@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 .1 .1 .8
@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 .1 .9
@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
@subsection The original 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.

@subsection An extension for double sided disks (Commodore VIC 1571)

Given that a Commodore VIC 1541/1570/1571 can read/write at most 42
tracks per side, it is quite natural to use the half-tracks from 1
to 84 for the first side and the following 84 half-tracks (i. e.
half-track 85 to 168) for the second side.

In order for this to work, byte 9 of the image (i. e. the maximum
number of tracks) usually contains 168 for double sided disks.

To make identifying such images easy, the file signature in the first 8 bytes of
such files is @code{GCR-1571}).

@subsection Extra mastering info (SPS extension)

G64s created by the DTC tool from Kryoflux dumps contain extra info for each
track, usually at offset $02ac right after the speedzone entries.

First comes the extra info tag:

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $00-$02
@tab extra info tag (@b{EXT}) $45,$58,$54
@item $03
@tab extra info version ($01)
@end multitable

Followed by 16 bytes of extra info for each track in the image:

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $00
@tab write splice position
@item $04
@tab write area size
@item $08
@tab bitcell size in nanoseconds (eg 3500 means 3.5us)
@item $0c
@tab track fill value
@item $0d
@tab n/a
@item $0e
@tab format code
@item $0f
@tab format extension
@end multitable

A zero value in any of these fields means that the respective default/standard
value applies.

Format codes:

@multitable @columnfractions .2 .8
@item @b{ID}
@tab @b{Description}
@item 0
@tab Unknown format
@item 1
@tab GCR Data
@item 2
@tab CBM DOS
@item 3
@tab CBM DOS Extended
@item 4
@tab MicroProse
@item 5
@tab RapidLok
@item 6
@tab Datasoft
@item 7
@tab Vorpal
@item 8
@tab V-MAX!
@item 9
@tab Teque
@item 10
@tab TDP
@item 11
@tab Big Five
@item 12
@tab OziSoft
@end multitable

Format Extensions:

@multitable @columnfractions .2 .8
@item @b{ID}
@tab @b{Description}
@item 0
@tab Unknown protection
@item 1
@tab Datasoft with Weak bits
@item 2
@tab CBM DOS with Cyan loader, Weak bits
@item 3
@tab CBM DOS with Datasoft, Weak bits
@item 4
@tab RapidLok Key
@item 5
@tab Data Duplication
@item 6
@tab Melbourne House
@item 7
@tab Melbourne House, Weak bits
@item 8
@tab PirateBusters v1.0
@item 9
@tab PirateBusters v2.0, Track A
@item 10
@tab PirateBusters v2.0, Track B
@item 11
@tab PirateSlayer
@item 12
@tab CBM DOS, XEMAG
@end multitable

@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 = Number of sides (0 for single sided,
                              1 for double sided)
                   Bit 2-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 |
                          +---------------------------+
       Bit 7 of the half track index byte contains the side.

       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 .15 .15 .15 .15 .4
@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, was 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.

Note that this ancient format is deprecated and subject for removal. It never
got any momentum in the emulation community, and VICE never supported it for
anything but 1541 disks.

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, D90, 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 D90, DHD, D82, File formats
@section The D90 disk image format

@c FIXME: the D90 section needs to be style-checked.

@c ROB

The D90 image is bit-for-bit copy of the hard drives in the D9090 and
D9060.
The specifications are as follows:

@multitable @columnfractions .4 .3 .3
@item @b{Specifications}
@tab @b{D9060}
@tab @b{D9090}
@item Hard Disk Mechanism
@tab Tandom TM602S
@tab Tandom TM603S
@item Cylinders
@tab 153
@tab 153
@item Heads
@tab 4
@tab 6
@item Sectors
@tab 32
@tab 32
@item Sector Size
@tab 256
@tab 256
@item Disk Interface
@tab ST-506
@tab ST-506
@item Unformatted Capacity
@tab 6.4 MB
@tab 9.6 MB
@item Formatted Capacity
@tab 5.01 MB
@tab 7.52 MB
@item Available Physical Sectors
@tab 19584
@tab 29376
@item Usable CBM Blocks
@tab 19441
@tab 29162
@end multitable

Note that the unformatted capacity is simply the total raw storage and makes
no accommodation for the management of the information.
A disk needs to be low-level formatted to include sync bits, sector
identifiers, error checking, and correcting bits to reliably find and hold
data.
This results in an overall loss of about 22% of space, which wasn't unusual
for ST-506 MFM hard disks at the time.
Modern drives use more advanced storage techniques to reduce this overhead.
Earlier published information stating these drives didn't use their full
capacity was incorrect.

It can be seen that the only difference between this two mechanisms was the
number of heads.
In fact the only difference between the two D9090/60 models is the hard drive
mechanism and the setting of the J14 configuration jumper which reflects
which head count to use. Jumper J13 is connected to the FDC, but in the latest
ROM it has no function.

The slight difference between the physical sectors and available blocks is
due to the overhead of the CBM filing system (BAM, directory sectors, and
bad block list).

The D9090/60 hard disk is the only Commodore drive which uses a "track 0".
Sector 0 of this track contains the track and sector information for the
header, directory, beginning of the BAM, and the beginning of the bad
sector list.

Below is a dump of the configuration sector (track 0, sector 0):

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 00 01 00 FF 4C 0A 4C 14 01 00 49 44 00 00 00 00
10: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@dots{}
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to bad blocks list
@item $02
@tab Always 0x00
@item $03
@tab Always 0xff (DOS version?)
@item $04-$05
@tab T/S pointer to first directory entry
@item $06-$07
@tab T/S pointer to header
@item $08-$08
@tab T/S pointer to first BAM sector
@item $0A-$0B
@tab Disk ID, "ID" in this example
@item $0C-$FF
@tab Always 0x00
@end multitable

This sector is the same for both the D9090 and D9060 as the two hard drives
had the same number of cylinders.
The the header and directory are placed in the middle of the disk (track 76)
to minimize access times.
The on-board DOS was designed to accommodate for different cylinder
configurations so it was easy to install larger disks by only modifying the
FDC ROM.
The number of sectors can not exceed 32, and the number of heads can not
exceed 7 as they would cause unhandled numeric overflow in the DOS.
This variation in configuration values makes it difficult to determine them
based solely on the D90 file size.
At this point only the stock image sizes of 5,013,504, and 7,520,256 will be
attachable in VICE.

Regardless of the size, access to the drive is translated from CHS
(cylinder, head, sector) to LBA (logical block address) in the FDC.
Although the drive mechanism interface is ST-506, the AM2910 bridges
the SASI communication from the FDC.

Since most hard disks of that era had some type of physical defect, and no
defect management system, a bad blocks list is included in the DOS.
This list begins at track 0, sector 1 as seen from the configuration sector.
Below is a dump of an empty bad blocks list (track 0, sector 1):

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
@dots{}
@end example

The list begins as a typical T/S linking sector, however, it is terminated
with a T/S of $FF/$FF unlike the typical $00/$xx normally seen in other
standard files.
The following is a more practical example:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 00 02 10 20 FF 02 30 40 FF 08 50 60 FF 14 70 80
@dots{}
@end example

The actual information starts at offset $02.
"Bad" blocks are simply marked as "allocated" in the BAM so the DOS doesn't
try to put any new data in them.
This file is processed by setting the "working" track to 0.
Starting at the beginning (offset $02), a byte is read.
If this value is not $FF, it is interpreted as the "working" sector.
The "working" track/sector is marked as bad (used).
We continue on by reading the next byte as the "working" sector and marking
it until a $FF is encountered.
In the above example, track $0/$10 and $0/$20 would be marked as bad.
Once the $FF is found, the next byte is the new "working" track if it is
not $FF; if it is, the list is finished.
Otherwise we continue processing the list just as we did when the "working"
track was 0.
In the above example, track $2/$30, $2/$40, $8/$50, $8/$60, $14/70, and
$14/$80 would be marked as bad.
Note that the list in this example would continue onto track 0, sector 2
at offset $2 as the T/S link is set.
This list is processed during a "validation" as the current BAM is erased
and rebuilt. It also appears to be processed after a format, but it is
not certain if the DOS generates the list or if it was generated in
factory by a diagnostic system prior to the drives distribution.

The BAM (Block Availability Map) generally begins on track 1, sector 0,
and continues on as necessary based on the disk configuration.
Below is a dump of that first BAM sector with a configuration of 32 sectors
per head, and 6 heads:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 09 00 FF FF 00 08 00 00 00 00 00 00 00 00 00 00
10: 1E FC FF FF FF 20 FF FF FF FF 20 FF FF FF FF 20
20: FF FF FF FF 20 FF FF FF FF 20 FF FF FF FF 1F FE
30: FF FF FF 20 FF FF FF FF 20 FF FF FF FF 20 FF FF
@dots{}
F0: FF 20 FF FF FF FF 20 FF FF FF FF 20 FF FF FF FF
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to next BAM sector ($9/$0)
@item $02-$03
@tab T/S pointer to previous BAM sector ($FF/$FF)
@item $04
@tab Lowest track covered by this BAM ($0)
@item $05
@tab Highest+1 track covered by this BAM ($8)
@item $06
@tab Possible start of bitmap data
@item $10-$14 (first entry based on this example)
@tab BAM for track 0, head 0. The first byte shows the "blocks free" for this head, the remaining 4 show the BAM for this track and head.
@item $24-$08
@tab BAM for track 0, head 1.
@item @dots{}
@tab @dots{}
@item $2E-$32
@tab BAM for track 1, head 0.
@item @dots{}
@tab @dots{}
@item $FB-$FF
@tab BAM for track 7, head 5.
@end multitable

If the T/S pointer is $FF/$FF, it means the end of the BAM.
So in this case, there is no previous BAM sector, whereas in the last
BAM sector, bytes $01-$02 will be $FF/$FF indicating that there is no
next BAM sector.

Bytes $4 and $5 show the range of which tracks this BAM sector applies to.
There are 250 bytes to hold this information.
The size of each bitmap entry is calculated by
"ceiling(sectors_per_head/8)+1"; the "1" is to include the block count.
This value is then multipled by the head number and divided into 250.
The remainder is added to 6 (the offset for the start of bitmap data).
For this example, the bitmap entry size would be "ceiling(32/8)+1" which is 5
bytes.
The offset is "(250%(5*6))+6" which is 16 or $10.
The goal of this calculation is to place the maximum number of whole tracks
inside each BAM.
In this case, "int(250/(5*6))" is 8, so we can store 8 tracks per BAM sector.
Therefore the lowest track is 0, and the highest is 0 + 8.
The next BAM sector will handle tracks 8 to 15 (16 - 1).
The position of the BAMs will start at track 1, and the second will be at
track 9 (8 + 1), the third will be at track 17 (2 * 8 + 1), and so on.
For this example with 153 tracks, we will need at least 20 (153 divided by 8)
BAM sectors.
BAM sectors are always placed on sector 0.
The header and directory will never start on sector 0, so we don't have to
worry if one of the BAM sectors will end up on track 76 for example.

Being bit-based, the BAM entries need some explanation.
The first track (track 0) entry in the above BAM sector is at offset $10,
"1E FC FF FF FF".
The first number is how many blocks are free on this track and head ($1E=30)
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
 FC=11111100, FF=11111111, FF=11111111, FF=11111111
@end example

In order to make any sense from the binary notation, flip the bits around.

@example
            111111 11112222 22222233
 01234567 89012345 67890123 45678901
 -------------------------- ---------
 00111111 11111111 11111111 11111111
 ^                                 ^
 sector 0                  sector 31
@end example

If a bit is on (1), the sector is free.
We can see all but sectors 0 and 1 are free here as it holds the configuration
sector, and one sector for the bad block list respectively.

At offset $24, "1F FE FF FF FF" describes the allocation at track 1, sector 0.
The first value is the number of free blocks ($1F=31) and the next 4 indicate
which sectors are used (or available); in this case sector 0 is allocated
as it is used by the first BAM sector.

Below is the dump of the last BAM sector (track 152, sector 0):

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: FF FF 91 00 98 99 00 00 00 00 00 00 00 00 00 00
10: 1F FE FF FF FF 20 FF FF FF FF 20 FF FF FF FF 20
20: FF FF FF FF 20 FF FF FF FF 20 FF FF FF FF 00 00
30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@dots{}
@end example

Here we can see it only covers tracks 152 ($98) to 152 ($99-1).
So only 6 entries are valid, and the rest are all zeros.
The next T/S pointer is $FF/$FF indicating this is the last BAM sector.

When the blocks free is calculated, only track 0 is excluded.
Other Commodore drives exclude the dedicated directory track.

The directory is generally on track 76 (152 divided by 2), with sector 20
containing the header (disk name, disk ID's).
The directory entries begin at sector 10.
The drives interleave is 10 sectors and it appears the directory entry is
allocated before the header on a format.
Once the directory grows, the interleave becomes 3, as on most Commodore
drives.
Unlike most Commodore drives, the directory is not limited to track 76,
nor is file data limited to be else where.
Once track 76 is filled with directory entries, it will look in other tracks
to place more entries.
Filling the disk to capacity will also place data into track 76.
Be warned though as the directory listing can exceed the amount of memory
available on the Commodore machine which is "loading" the directory.
It is wise to use a DOS wedge which displays the directory as it is being
read but doesn't store it in memory.

The D9090/60 emulation in VICE was tested to see how many one block files
could be created on a D9090 image.
The disk was filled with 25922 files which required 3241 blocks for the
directory entries.

Below is a dump of the header at track 76, sector 20:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 4C 0A 00 00 00 00 54 45 53 54 A0 A0 A0 A0 A0 A0
10: A0 A0 A0 A0 A0 A0 A0 A0 49 44 A0 33 41 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

This is very similar to the D80/D82 header in placement but without the DOS
version value.
Also note that the dos version bytes are "3A".
For the D90, it is believed that the $FF at offset $3 in the configuration
sector dictates the DOS version.

The directory entry generally starts at track 76, sector 10.
It has the identical layout as all other Commodore drives.
There are no files specific to the D90 image other than super side
sectors for larger REL files.

@node DHD, P00, D90, File formats
@section The DHD disk image format

The DHD image is bit-for-bit copy of a Creative Micro Designs (CMD)
Hard Drive (HD). CMD designed their DOS so that it could co-exist with
other operating systems from other computer platforms. At the time,
SCSI HDs were very expensive, making this a likely scenario for some.
In this section, a block refers to a SCSI HD data block which is 512
bytes. A SCSI HD refers to the location of a blocks on the disk as
logical block address (LBA). A sector refers to a commodore disk
sector which is 256 bytes. SCSI, being a smarter disk system (compared
to earlier ones), translates the LBAs into physical head, sector,
cylinder coordinates internally thus simplifying the host's interface.
So, for example, a 40 MB HD of that era would have had 82332 (or
$1419C) LBAs. As HD technology improved, the number of sectors per
cylinder became variable depending on the cylinder which allowed for
greater capacity. The host therefore has no information about the HD
geometry other than the total number of LBAs.
Most operating systems place their partition tables or boot code near
the beginning of the HD. Because of this variability, CMD designed
their DOS to begin at any location in increments of 128 blocks. It was
therefore possible to configure foreign partitions on various
operating system so that the CMD data was ignored. The starting
location of the CMD whole disk partition will be referred to as X
blocks.

Upon reset, the boot ROM looks for the CMD whole partition by
examining LBA X+2 (starting at X=0) and checking for a special
signature in the block. If it does not find it, X will increase by
128, and it will try again. It will do this until it finds the
signature, or until it gets a read error from the HD signaling the end
of disk space. The device will the switch to installation mode.

The following is an example configuration block of a 40 MB drive:

@example
X *     00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
$200 +  -----------------------------------------------   ----------------
000400: 94 6C 00 0E 7D E7 00 00 00 00 00 00 00 00 00 00
000410: 20 20 20 20 31 2E 39 32 30 33 2F 32 32 2F 39 36   ....1.9203/22/96
000420: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
000430: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
000440: 03 02 00 7E C9 55 00 00 00 00 00 00 00 00 00 00
000450: 20 20 20 20 32 2E 30 30 30 33 2F 32 32 2F 39 36   ....2.0003/22/96
000460: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
...
000500: 00 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
000510: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
000530: FF FF FF FF FF FF FF FF 00 01 FF FF FF FF FF FF
000540: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
000570: 00 41 FF FF FF FF FF FF FF FF FF FF FF FF FF FF
000580: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0005A0: FF FF FF FF FF FF FF FF 00 9C FF FF FF FF FF FF
0005B0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0005E0: 00 0C 01 01 0C 80 01 00 00 00 00 00 00 00 00 00
0005F0: 43 4D 44 20 48 44 20 20 8D 03 88 8E 02 88 EA 60   CMD HD..........
...
000E00: < start of first OS, n=0, CMD DOS, see $402-$403 >
007E00: < start of second OS, n=1, GEOS overlay, see $442-$443 >
010000: < start of partition table, see $5E6-$5E7 >
@end example

The first 256 bytes of the configuration block appear to be a list of
loadable operating systems for the drive. Each entry, "n", uses 64
bytes, so there can be at most 4. The first is the standard CMD DOS,
while the second is an overlay for GEOS. The boot ROM explicitly loads
the first (n=0).

The CMD DOS supports up to 56 connected HDs: 7 devices with 8 logical
units (LUNs) each. For that era, most HDs only supported a single LUN
(0), whereas more exotic array devices would allow for multiple LUNs.
The relative location of the disk, "d", in the whole drive map, is
stored in the next 224 bytes. For example, the first disk would start
at location 0. The next disk following the first, would start at LBA
$01419C (the size of the first disk plus its starting point in the
map). The 24-bit values used here for the placement are adequate since
a fully populated CMD HD can only access 255 16 MB partitions, which
his just under 4 GiB.

The last portion of the configuration block holds the device parameters
(device number, partition location, default partition) as well as the
CMD HD signature.

@multitable @columnfractions .35 .65
@item @b{Bytes}
@tab @b{Description}
@item (X*$200)+($400-$4FF)
@tab Operating System Table
@item (X*$200+$400+n*$40)+$00
@tab Destination memory page
@item (X*$200+$400+n*$40)+$01
@tab Number of pages
@item (X*$200+$400+n*$40)+$02-$03
@tab Location of data offset from X in sectors (256 bytes); MSB format
@item (X*$200+$400+n*$40)+$04-$05
@tab Checksum of data; MSB format
@item (X*$200+$400+n*$40)+$06-$0F
@tab All 0x00
@item (X*$200+$400+n*$40)+$10-$17
@tab ASCII of version number
@item (X*$200+$400+n*$40)+$18-$1F
@tab ASCII of date
@item (X*$200+$400+n*$40)+$20-$3F
@tab All 0x00
@item (X*$200+$500+d*$38)+$00
@tab SCSI ID of HD in bits 7-4, LUN in bits 3-0; $FF means not present
@item (X*$200+$500+d*$38)+$38
@tab MSB of disk location in drive map
@item (X*$200+$500+d*$38)+$70
@tab Middle byte of disk location in drive map
@item (X*$200+$500+d*$38)+$A8
@tab LSB of disk location in drive map
@item (X*$200+$500)+$E0
@tab 0x00 (unknown)
@item (X*$200+$500)+$E1
@tab Device number (12 or 0x0C by default)
@item (X*$200+$500)+$E2
@tab 0x01 (unknown)
@item (X*$200+$500)+$E3
@tab 0x01 (unknown)
@item (X*$200+$500)+$E4
@tab Device number (12 or 0x0C by default)
@item (X*$200+$500)+$E5
@tab 0x80: 2 to the power of the SCSI ID of host (which is always 7)
@item (X*$200+$500)+$E6-$E7
@tab Location of CMD partition table offset from X in sectors (256 bytes); MSB format
@item (X*$200+$500)+$E8
@tab Default partition number
@item (X*$200+$500)+$E9-$EF
@tab All 0x00
@item (X*$200+$500)+$F0-$F7
@tab 0x43 0x4D 0x44 0x20 0x48 0x44 0x20 0x20: First half of signature
@item (X*$200+$500)+$F8-$FF
@tab 0x8D 0x03 0x88 0x8E 0x02 0x88 0xEA 0x60: Second half of signature; decodes to STA $8803, STX $8802, NOP, RTS
@end multitable

The CMD partition table is a special disk image with one track and 32
sectors. It is very similar the standard directory structure of most
CBM drives.  The first two bytes of the sector indicate the location of
the next track/sector of the partition table; it is usually in sequence.
If the next track is set to $00 (the next sector will be $ff), then it
is the last sector of the partition table.

The standard partition table sectors:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First partition entry for this sector
@item $20-$3F
@tab Second partition entry for this sector
@item $40-$5F
@tab Third partition entry for this sector
@item $60-$7F
@tab Fourth partition entry for this sector
@item $80-$9F
@tab Fifth partition entry for this sector
@item $A0-$BF
@tab Sixth partition entry for this sector
@item $C0-$DF
@tab Seventh partition entry for this sector
@item $E0-$FF
@tab Eighth partition entry for this sector
@end multitable

The standard partition entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next partition sector ($00 $00 if not the first entry in the sector)
@item $02
@tab Partition type: 0x00=none, 0x01=native, 0x02=1541, 0x03=1571, 0x04=1581, 0x05=1581CPM, 0x06=Print Queue, 0x07=Foreign, 0xFF=System.  Only partition 0 can be a system type, and type 6 isn't known to be implemented on any CMD DOS.
@item $03-$04
@tab 0x00 0x00
@item $05-$14
@tab 16 character partition name (in PETASCII, padded with $A0)
@item $15-$17
@tab Location of the partition data offset from X in sectors (256 bytes); MSB format; partition 0, the system partition always starts a 0.
@item $18-$1D
@tab All 0x00
@item $1E-$1F
@tab Size of partition (in blocks) in MSB format. Partition 0, the system partition is always 0x90 blocks, which includes blocks from X to the end of the partition table.
@end multitable

When a partition is deleted, its entry is removed and all others stay
in their existing place. The partition data following the deleted
partition is moved back to fill in the gap from the deletion;
this can be very time consuming. So, when deleting a partition, it is
suggested to start with the one with the highest start LBA.

The data at the starting LBA is simply the associated disk image of
the partition type. It follows the formats (D64, D71, and D81)
documented previously.

@node P00, , DHD, 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.

  The file format was extended to support other CBM machines by the VICE
team in version 2.0

  Normal game cartridges can load  into  several  different  memory  ranges
(on the C64 this is $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
ROMs 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

  For example, here is a dump of a sample 8KiB generic C64 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
$0000-$000F - 16-byte cartridge signature (padded with space characters)
              "C64 CARTRIDGE   " - indicates a C64 cartridge
              "C128 CARTRIDGE  " - indicates a C128 cartridge (added in v2.0)
              "CBM2 CARTRIDGE  " - indicates a CBMII cartridge (added in v2.0)
              "VIC20 CARTRIDGE " - indicates a VIC20 cartridge (added in v2.0)
              "PLUS4 CARTRIDGE " - indicates a C16/PLUS4 cartridge (added in v2.0)

$0010-$0013 - File header length (in high/low format, counting from offset $0000).
              The default (and also the minimum) value is $40, which should always
              be used for compatibility reasons. Some cartridge images exist which
              use a value of $00000020, which is wrong.
              
$0014-$0015 - Cartridge version (high/low, presently 02.00)
              $01 $00 - original v1.0 specs
              $01 $01 - VICE v1.1 specs (adds CRT sub type/hardware revision)
              $02 $00 - VICE v2.0 specs (introduces VIC20, PLUS4, C128, CBM2)
              
$0016-$0017 - Cartridge hardware type ($0000, high/low) - see below for details

      $0018 - Cartridge port EXROM line status (C64 only)
      $0019 - Cartridge port GAME line status (C64 only)

              Determines the mode the cartridge starts in:

              exrom / game
              0       0    - 16k Game
              0       1    -  8k Game
              1       0    -  ultimax
              1       1    -  ram/off

              Emulators should only use this field with "generic" C64 cartridges
              (type 0), for all others the startup mode is implied by the type
              of the cartridge. It should still be filled correctly in the crt
              file, but a lot of files with wrong values exist "in the wild".

      $001A - Cartridge Hardware Revision/Subtype (usually 0) (added in v1.01)
      
$001B-$001F - Reserved for future use

$0020-$003F - 32-byte cartridge  name  (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

@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
$0000-$0003 - Contained ROM signature "CHIP" (note there can be more than one
              CHIP image in a .CRT file)

$0004-$0007 - Total packet length (high/low format)
              Length of ROM image size and header combined, this should
              always be equal to "ROM image size" + $10

$0008-$0009 - Chip type

              0 - ROM
              1 - RAM
              2 - Flash ROM
              3 - EEPROM

              This is informal only. A RAM chunk may be empty, but doesn't
              have to be.

$000A-$000B - Bank number ($0000 - normal cartridge)

              Number of the bank this CHIP package appears in. This should be
              a logical bank number, not the value stored into some banking
              register which might have its bit-order rearranged.

$000C-$000D - Starting load address (high/low format)

              The load address tells the loader which part of the given bank
              is to be used for this chunk. It is only really important in
              formats where actually more than one CHIP chunk exists for each
              bank - most notable the "generic" (type 0) cartridges.

$000E-$000F - ROM image size in bytes  (high/low format, typically $2000 or $4000)

$0010- xxxx - ROM data
@end example

@c @node FIXME
@subsection C64 Cartridge Specifics

@multitable @columnfractions .1 .9
@item @b{CRT ID}
@tab @b{Cartridge Type}
@item 0
@tab generic cartridge
@item 1
@tab Action Replay
@item 2
@tab KCS Power Cartridge
@item 3
@tab Final Cartridge III
@item 4
@tab Simons' BASIC
@item 5
@tab Ocean type 1*
@item 6
@tab Expert Cartridge
@item 7
@tab Fun Play, Power Play
@item 8
@tab Super Games
@item 9
@tab Atomic Power
@item 10
@tab Epyx Fastload
@item 11
@tab Westermann Learning
@item 12
@tab Rex Utility
@item 13
@tab Final Cartridge I
@item 14
@tab Magic Formel
@item 15
@tab C64 Game System, System 3
@item 16
@tab Warp Speed
@item 17
@tab Dinamic**
@item 18
@tab Zaxxon, Super Zaxxon (SEGA)
@item 19
@tab Magic Desk, Domark, HES Australia
@item 20
@tab Super Snapshot V5
@item 21
@tab Comal-80
@item 22
@tab Structured BASIC
@item 23
@tab Ross
@item 24
@tab Dela EP64
@item 25
@tab Dela EP7x8
@item 26
@tab Dela EP256
@item 27
@tab Rex EP256
@item 28
@tab Mikro Assembler
@item 29
@tab Final Cartridge Plus
@item 30
@tab Action Replay 4
@item 31
@tab Stardos
@item 32
@tab EasyFlash
@item 33
@tab EasyFlash Xbank
@item 34
@tab Capture
@item 35
@tab Action Replay 3
@item 36
@tab Retro Replay (Subtype 1: Nordic Replay)
@item 37
@tab MMC64
@item 38
@tab MMC Replay
@item 39
@tab IDE64
@item 40
@tab Super Snapshot V4
@item 41
@tab IEEE-488
@item 42
@tab Game Killer
@item 43
@tab Prophet64
@item 44
@tab EXOS
@item 45
@tab Freeze Frame
@item 46
@tab Freeze Machine
@item 47
@tab Snapshot64
@item 48
@tab Super Explode V5.0
@item 49
@tab Magic Voice
@item 50
@tab Action Replay 2
@item 51
@tab MACH 5
@item 52
@tab Diashow-Maker
@item 53
@tab Pagefox
@item 54
@tab Kingsoft
@item 55
@tab Silverrock 128K Cartridge
@item 56
@tab Formel 64
@item 57
@tab RGCD (Subtype 1: Hucky)
@item 58
@tab RR-Net MK3
@item 59
@tab EasyCalc
@item 60
@tab GMod2
@item 61
@tab MAX Basic
@item 62
@tab GMod3
@item 63
@tab ZIPP-CODE 48
@item 64
@tab Blackbox V8
@item 65
@tab Blackbox V3
@item 66
@tab Blackbox V4
@item 67
@tab REX RAM-Floppy
@item 68
@tab BIS-Plus
@item 69
@tab SD-BOX
@item 70
@tab MultiMAX
@item 71
@tab Blackbox V9
@item 72
@tab Lt. Kernal Host Adaptor
@item 73
@tab RAMLink
@item 74
@tab H.E.R.O.
@item 75
@tab IEEE Flash! 64
@item 76
@tab Turtle Graphics II
@item 77
@tab Freeze Frame MK2
@item 78
@tab Partner 64
@end multitable

(*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
@subsubsection 0 - generic cartridge

generic cartridges can contain one or two 8k CHIP packets, one for ROML and one
for ROMH. ROML start address is always $8000, ROMH start address is either $a000
or $e000 depending on the GAME/EXROM config.

  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 8KiB or 16KiB 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    8KiB    hi     lo     $8000      ----
Normal    16KiB   lo     lo     $8000     $A000
Ultimax   8KiB    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.

@b{generic 8K GAME cartridge}

@multitable @columnfractions .3 .7
@item Size
@tab 8KiB
@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

@b{generic 16K GAME cartridge}

This sample is a dump of "Adventure Creator",  a  16KiB  standard cartridge.

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB
@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

@b{ULTIMAX cartridge}

Ultimax cartridges typically are situated  in  the  $E000-FFFF  (8KiB)  ROM
address range. There are some cartridges  which  only  use  4KiB  of  the  8KiB
allocation. If the cartridge is 16KiB in size, then it will  reside  in  both
$8000-9FFF and $E000-FFFF.

This sample below is a dump of "Music Machine", a  4KiB  ULTIMAX mode cartridge.
It is still identified as a "generic cartridge" according to the ID.

@multitable @columnfractions .3 .7
@item Size
@tab 4KiB (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

@c @node FIXME
@subsubsection 1 - Action Replay

@multitable @columnfractions .3 .7
@item Size
@tab 32KiB (4 banks of 8KiB each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@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 01 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 32KiB of ROM, and 8KiB 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 16KiB (2 banks of 8KiB 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 64KiB (4 banks of 16KiB 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 00 00 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 KiB 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 KiB 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 16KiB (2 banks of 8KiB 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 00 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 KiB ($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 KiB ROM.


@c @node FIXME
@subsubsection 5 - Ocean type 1

@multitable @columnfractions .3 .7
@item Size
@tab 32KiB, 128KiB, 256KiB or 512KiB sizes (4, 16, 32 or 64 banks of 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@* inactive (hi) (1) for 512KiB variant (Terminator 2)
@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 KiB)
    Battle Command      (128 KiB)
    Double Dragon       (128 KiB)
    Navy Seals          (128 KiB)
    Pang                (128 KiB)
    Robocop 3           (128 KiB)
    Space Gun           (128 KiB)
    Toki                (128 KiB)
    Chase H.Q. II       (256 KiB)
    Robocop 2           (256 KiB)
    Shadow of the Beast (256 KiB)
    Terminator 2        (512 KiB)
@end example

    The 32KiB type of cart  has  4  banks  of  8KiB  ($2000),  banked  in  at
    $8000-$9FFF.

    The 128KiB type of cart has  16  banks of  8KiB  ($2000),  banked  in  at
    $8000-$9FFF.

    The 256KiB type of cart has 32 banks of 8KiB ($2000),  16  banked  in  at
    $8000-$9FFF, and 16 banked in at $A000-$BFFF.

    The 512KiB type of cart has 64  banks  of  8KiB  ($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 8KiB
@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 06 01 00 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 01 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 128KiB (16 banks of 8KiB modules)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@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 01 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  8KiB
    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 64KiB (4 banks of 16KiB each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Startup mode
@tab 16KiB 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  16KiB  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 - 16KiB 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 32KiB (4 banks of 8KiB modules)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@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 01 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 32KiB of ROM and 8KiB 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  16KiB  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 8KiB
@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 0A 00 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 8KiB 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 16KiB
@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 8KiB
@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 (8KiB game config).


@c @node FIXME
@subsubsection 13 - Final Cartridge I

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB
@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 0D 00 00 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 64KiB (8 banks of 8KiB)
@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 0E 01 00 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...`...`...`.
@dots{}
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 512KiB (64 banks of 8KiB each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@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 0F 00 01 00 00 00 00 00 00  ...@@............
00020: 43 36 34 47 53 20 43 61 72 74 72 69 64 67 65 00  C64GS Cartridge.
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: 6D 80 C5 80 C3 C2 CD 38 30 4C CB 80 4C 36 84 4C  m......80L..L6.L
@dots{}
02050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP.. ....... .
02060: 18 D0 A9 FF 8D 15 D0 8D 1D D0 8D 17 D0 A2 07 A9  ................
@dots{}
04060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP.. ....... .
04070: E0 08 19 21 77 84 52 98 9F 80 A5 21 31 01 31 89  ...!w.R....!1.1.
@dots{}
06070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP.. ....... .
06080: C0 08 1C 1D A0 92 03 03 D8 AA 04 C0 B8 01 40 EA  ..............@@.
@dots{}
7E430: 43 48 49 50 00 00 20 10 00 00 00 3F 80 00 20 00  CHIP.. ....?.. .
7E440: 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 KiB)
    Last Ninja Remix  (System 3)   (512 KiB)
    Myth              (System 3)   (512 KiB)
@end example

    ROM memory is organized in 8KiB ($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 KiB ROM configuration.


@c @node FIXME
@subsubsection 16 - Warp Speed

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB
@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 00 00 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,  16KiB  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 128KiB (16 banks of 8KiB each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@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 11 00 01 00 00 00 00 00 00  ...@@............
00020: 4E 61 72 63 6F 20 50 6F 6C 69 63 65 00 00 00 00  Narco Police....
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: 0B 80 0B 80 C3 C2 CD 38 30 00 00 78 A2 FF 9A D8  .......80..x....
..
02050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP.. ....... .
02060: 1C 8C 1B 8C 16 16 8F 16 16 88 1C 1C 86 1C 1C 89  ................
..
04060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP.. ....... .
04070: B6 02 07 08 07 07 00 0A 0A B6 00 05 0A 00 07 07  ................
..
1E130: 43 48 49 50 00 00 20 10 00 00 00 0F 80 00 20 00  CHIP.. ....... .
1E140: 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 KiB)
    Satan         (128 KiB)
@end example

    ROM memory is organized in 8KiB ($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 KiB ROM configuration.


@c @node FIXME
@subsubsection 18 - Zaxxon, Super Zaxxon (SEGA)

@multitable @columnfractions .3 .7
@item Size
@tab 20KiB (3 banks of different sizes)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@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
      -----------------------------------------------  ----------------
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 12 00 00 00 00 00 00 00 00  ...@@............
0020: 5A 61 78 78 6F 6E 00 00 00 00 00 00 00 00 00 00  Zaxxon..........
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: 0D 80 29 80 C3 C2 CD 38 30 78 4C 09 80 78 A9 00  ..)....80xL..x..
..
1050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP.. ....... .
1060: A2 0F BD 00 20 D0 04 CA 10 F8 60 BD 70 20 F0 0D  .... .....`.p ..
..
3060: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00  CHIP.. ....... .
3070: 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 4KiB ($1000) ROM at $8000-$8FFF (mirrored
    in $9000-$9FFF) along with two 8KiB ($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 KiB 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 32KiB, 64KiB or 128KiB sizes (4 to 16 banks of 8KiB each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB 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  8KiB  ($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 KiB ROM.

    Here is a list of the known cartridges:

@example
    Ghosbusters        (HES Australia)   (32 KiB)
    Magic Desk         (Commodore)       (32 KiB)
    Badlands           (Domark)          (64 KiB)
    Vindicators        (Domark)          (64 KiB)
    Wonderboy          (HES Australia)   (64 KiB)
    Cyberball          (Domark)         (128 KiB)
@end example


@c @node FIXME
@subsubsection 20 - Super Snapshot V5

@multitable @columnfractions .3 .7
@item Size
@tab 64KiB or 128KiB (4 or 8 banks of 16KiB each)
@item EXROM
@tab inactive (hi) (1)
@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 14 00 00 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-6  unused
    5    ROM/RAM bank bit 2 (usually unused, for 128KiB ROM)
    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 64KiB (4 banks of 16KiB each)
@item EXROM
@tab active (low) (0)
@item GAME
@tab active (low) (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 15 00 00 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 16KiB banks ($4000) at $8000-$BFFF. There are 4
    banks of ROM memory and the cart has 1 (write-only) bank control register which
    is located at $DE00 and mirrored throughout the $DE00-$DEFF range.

@example
    bit  meaning
    ---  -------
    7    exrom?
    6    game?
    5    unknown function (used by the software to disable the cartridge)
    4    unused?
    3    unused?
    2    unknown function (used by the software however)
    0-1  selects bank
@end example


@c @node FIXME
@subsubsection 22 - Structured Basic

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB (2 banks of 8KiB each)
@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 16 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: 0d 80 a2 80 c3 c2 cd 38 30 00 4c a0 84 a2 05 8e  .......80.L.....
0060: 16 d0 20 a3 fd 20 50 fd 20 5b ff 20 7e 80 58 20  .. .. P. [. ~.X 
0070: 53 e4 20 bf e3 20 ed 83 8d f4 07 a5 2b a4 2c 20  S. .. ......+., 
0080: 08 a4 20 80 91 a9 00 85 14 a9 80 85 15 20 75 93  .. .......... u.
0090: a9 8f a0 8a 20 2d e4 a2 0b bd 7d 8a 9d 00 03 ca  .... -..........
@dots{}
4040: db 9f 8e 00 de ea 4c e2 9f 8e 00 de ea 4c e9 9f  ......L......L..
4050: 8d 00 de ea 4c 43 fe 8d 00 de ea 4c e2 fc 2d 2a  ....LC.....L..-*
@end example

    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 16KiB or 32KiB sizes (1 or 2 banks of 16KiB each)
@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 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  32KiB).  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 8KiB to 72KiB sizes (1 to 9 banks of 8KiB each,
                              or 1 bank of 8KiB and 1 or 2 banks
                              of 32KiB each)
@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 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 (8KiB) which  holds  the  base
    eprom with the base menu, and 2 27256 eproms of  which  8KiB  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 8KiB to 64KiB sizes (1 to 8 banks of 8KiB each)
@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 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 8KiB 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 8KiB to 262KiB sizes (1 to 33 banks of 8KiB each)
@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 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 8KiB  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 8KiB to 262KiB sizes (1 bank of 8KiB and 1 to 8 banks of either
                               8KiB, 16KiB or 32KiB)
@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 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  8KiB  eprom,  the
    other eprom sockets can handle 8KiB, 16KiB or 32KiB eproms, of  which  8KiB
    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
    8KiB piece of the eprom.

    The possible values for bits 5 and 4 for the (extra) eprom banks are:

@example
     8KiB        : 3, 2, 1, 0

    16KiB bank 0 : 2, 0
    16KiB bank 1 : 3, 1

    32KiB bank 0 : 0
    32KiB bank 1 : 1
    32KiB bank 2 : 2
    32KiB 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 8KiB (1 bank of 8KiB)
@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 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 32KiB (1 bank of 32KiB)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@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 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 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 32KiB of ROM, bank 0 is in the cart image but is  unused.
    The first 8KiB of the cart image is unused, the second 8KiB of the  cart
    image is mapped to $E000-$FFFF, the third 8KiB of  the  cart  image  is
    mapped to $8000-$9FFF and the fourth 8KiB 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 32KiB (4 banks of 8KiB)
@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  .xH.......H.....
@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 16KiB (2 banks of 8KiB)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@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 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 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 16KiB of ROM, of which the first  8KiB  is  mapped  in  at
    $8000-$9FFF and the second 8KiB 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 1024KiB (64 banks of 2 * 8KiB)
@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 01 00 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 02 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 MiB 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 controls which bank  is  mapped  into  ROMH  and
    ROML.

    The register at $DE02 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

@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 8KiB (1 bank of 8KiB)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab inactive (hi) (1)
@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 00 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 8KiB of ROM which is mapped to  $E000,  and  8KiB  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 16KiB (2 banks of 8KiB)
@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 16KiB of ROM of which 8KiB 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 32KiB, 64KiB or 128KiB (4, 8 or 16 banks of 8KiB)
@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 24 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 02 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

    Note: When the Cartridge Hardware Subtype/Revision (Offset 0x1A in the
    CRT Header) is 1, then the image utilizes features only present in the
    "Nordic Replay" (see description of Nordic/Atomic Power)

    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 8KiB 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 8KiB-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 8KiB (1 bank of 8KiB)
@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 02 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 64KiB or 512KiB (8 or 64 banks of 8KiB)
@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 02 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 64KiB 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 16KiB 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  32KiB  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    16KiB rom mapping
    6    1 = enable  RR  register.  Disabling  RR  register  disables  ALL
         ROM/RAM banking too.
    7    ALWAYS 0
@end example

    NOTE THAT THE MMC REPLAY EMULATION IS CURRENTLY INCOMPLETE AND CONSIDERED
    BROKEN.

@c @node FIXME
@subsubsection 39 - IDE64

@multitable @columnfractions .3 .7
@item Size
@tab 64KiB or 128KiB (4 or 8 banks of 16KiB)
@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 32KiB (2 banks of 16KiB)
@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 28 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 40 10 00 00 00 00 80 00 40 00  CHIP.. ....... .
0050: 80 AD B5 80 C3 C2 CD 38 30 08 48 A9 06 8D 00 DF  .......80.H.....
@dots{}
2050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00  CHIP.. ....... .
2060: 13 80 BC FE C3 C2 CD 38 30 08 48 A9 02 8D 00 DF  .......80.H.....
@end example


    This cart has 32KiB of ROM and 8KiB 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 16KiB mapping
    is enabled, or if bit 0 is 1, then 8KiB 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 8KiB or
    16KiB mapping)

    $DF02-$DFFF holds the last page of the first 8KiB of the current bank.

@c @node FIXME
@subsubsection 41 - IEEE-488

@multitable @columnfractions .3 .7
@item Size
@tab 4KiB (1 bank of 4KiB)
@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 8KiB (1 bank of 8KiB)
@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 2A 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: 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 256KiB (32 banks of 8KiB)
@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 8KiB (1 bank of 8KiB)
@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 8KiB 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 8KiB (1 bank of 8KiB)
@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 16KiB or 32KiB (1 or 2 banks of 16KiB)
@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 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 40 10 00 00 00 00 80 00 40 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 40 10 00 00 00 01 80 00 40 00  CHIP.. ....... .
2060: 3A 83 60 80 C3 C2 CD 38 30 20 00 00 40 00 00 00  :.`....80 ..@@...
@end example


Warning, the following information is based on guess-work and might be
incorrect, any further information and/or corrections are appreciated.

When the cart starts, the first half of the active ROM is banked to ROML ($8000-$9fff).
When reading from  the  I/O-1  range  the second half of the active ROM  bank
is enabled in RMH ($A000-$BFFF). When  reading from the I/O-2 range the cart is
disabled. 

The 32k variant swaps the 16k bank with a second one when a  reset  happens.

When a freeze happens the first half of the ROM is mapped to ROML ($8000-$9FFF) and
the second half to ROMH ($E000-$FFFF).


@c @node FIXME
@subsubsection 47 - Snapshot 64

@multitable @columnfractions .3 .7
@item Size
@tab 4KiB (1 bank of 4KiB)
@item EXROM
@tab inactive (hi) (1)
@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 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 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 16KiB (2 banks of 8KiB)
@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 16KiB of ROM which are used as two banks of 8KiB, 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 16KiB
@item EXROM
@tab inactive (hi) (1)
@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 31 01 00 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 40 10 00 00 00 00 A0 00 40 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 16KiB 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  (8KiB),  copies  $E000-$FFFF  from  EPROM  to   RAM   at
      $E000-$FFFF (8KiB), 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 16KiB (2 banks of 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB 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 4KiB or 8KiB (1 bank of 4KiB or 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB Game
@item Load address
@tab $8000-$8FFF (4KiB),
                   $8000-$9FFF (8KiB)
@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 8KiB 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 8KiB (1 bank of 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB 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 8KiB 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 64KiB (4 banks of 16KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Startup mode
@tab 16KiB 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 00 00 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 64KiB ROM (2 32KiB Eproms, mapped to $8000  and  $A000  in
    16KiB Game Mode), and 32KiB RAM (mapped to $8000 and $A000 in  16KiB  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

@multitable @columnfractions .3 .7
@item Size
@tab 24KiB (3 banks of 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Startup mode
@tab 16KiB 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 36 00 00 00 00 00 00 00 00  ...@@...6........
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 A2 89 C3 C2 CD 38 30 20 D3 83 78 8D 00 DE  .......80 ..x...
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP.. ....... .
2060: 72 A2 05 A5 45 10 01 CA A5 46 10 02 CA CA 86 28  r...E....F.....(
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP.. ....... .
4070: 78 A2 FF 9A D8 A9 08 8D 16 D0 A0 00 98 99 02 00  x...............
@end example

    This cart has 24KiB ROM (3 8KiB Eproms)

@example
    reading io1:
    - switches to 16KiB game mode
    - first eprom mapped to 8000 (ROML)
    - second eprom mapped to A000 (ROMH)

    writing io1:
    - switches to ultimax mode _only_:
      - if 0xc000 > address >= 0x8000
      - if address >= 0xe000
      (meaning 0x0000-0x7fff and 0xc000-0xdfff gives normal c64 ram/io)
    - first eprom mapped to 8000 (ROML)
    - third eprom mapped to e000 (ROMH)
@end example

@c @node FIXME
@subsubsection 55 - Silverrock 128

@multitable @columnfractions .3 .7
@item Size
@tab 128KiB (16 banks of 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB 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
       -----------------------------------------------  ----------------
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 37 00 01 00 00 00 00 00 00  ...@@...7........
00020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE CART.......
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: 09 80 09 80 C3 C2 CD 38 30 78 A2 FF 9A D8 A9 00  .......80x......
@dots{}
02050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP.. ....... .
02060: 00 21 1D A9 90 1B 67 70 FD B0 04 C3 19 B9 11 2D  .!....gp.......-
@dots{}
04060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP.. ....... .
04070: 00 41 62 92 AD 71 32 87 08 20 BE 90 4C 36 8F 20  .Ab..q2.. ..L6. 
@dots{}
06070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP.. ....... .
06080: 00 61 00 02 02 03 0D 40 82 15 D0 A1 08 40 84 00  .a.....@@.....@@..
@dots{}
08080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00  CHIP.. ....... .
08090: 00 81 8A 85 0D F0 8A 28 83 F8 8A 00 8B 58 83 60  .......(.....X.`
@dots{}
0A090: 43 48 49 50 00 00 20 10 00 00 00 05 80 00 20 00  CHIP.. ....... .
0A0A0: 00 A1 C2 E3 C4 86 32 14 00 C5 40 EA 13 CA CB CC  ......2...@@.....
@dots{}
0C0A0: 43 48 49 50 00 00 20 10 00 00 00 06 80 00 20 00  CHIP.. ....... .
0C0B0: 00 C1 81 59 60 00 81 5D D9 58 5E EE 58 6E 3C 28  ...Y`..].X^.Xn<(
@dots{}
0E0B0: 43 48 49 50 00 00 20 10 00 00 00 07 80 00 20 00  CHIP.. ....... .
0E0C0: 00 E1 0F BF 3D 56 00 7E 52 FD 50 03 AA 00 0D 40  ....=V.~R.P....@@
@dots{}
100C0: 43 48 49 50 00 00 20 10 00 00 00 08 80 00 20 00  CHIP.. ....... .
100D0: 01 01 B9 D1 0D 15 89 55 65 45 41 C5 01 45 45 A8  .......UeEA..EE.
@dots{}
120D0: 43 48 49 50 00 00 20 10 00 00 00 09 80 00 20 00  CHIP.. ....... .
120E0: 01 21 0C C7 29 54 41 29 4D C5 06 24 C7 24 8F 81  .!..)TA)M..$.$..
@dots{}
140E0: 43 48 49 50 00 00 20 10 00 00 00 0A 80 00 20 00  CHIP.. ....... .
140F0: 01 41 EA 87 7A AF 95 67 BD F7 00 7D 6E C4 5D A6  .A..z..g...@}n.].
@dots{}
160F0: 43 48 49 50 00 00 20 10 00 00 00 0B 80 00 20 00  CHIP.. ....... .
16100: 01 61 6A 92 6B 93 6B 94 6C 95 6D 96 6E 97 6E 98  .aj.k.k.l.m.n.n.
@dots{}
18100: 43 48 49 50 00 00 20 10 00 00 00 0C 80 00 20 00  CHIP.. ....... .
18110: 01 81 0E 83 0D 0B 0F 81 FF 28 28 1E E3 0A 14 62  .........((....b
@dots{}
1A110: 43 48 49 50 00 00 20 10 00 00 00 0D 80 00 20 00  CHIP.. ....... .
1A120: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@dots{}
1C120: 43 48 49 50 00 00 20 10 00 00 00 0E 80 00 20 00  CHIP.. ....... .
1C130: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@dots{}
1E130: 43 48 49 50 00 00 20 10 00 00 00 0F 80 00 20 00  CHIP.. ....... .
1E140: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@end example

Cartridge hardware is designed around a 128KiB ROM (PROM or Mask ROM) which is
divided into 16 banks each of 8KiB. When adressing the onboard bank-switching logic
the requested ROM bank is mapped at address range $8000-$9fff (8KiB)

The cartridge PCB layout was cost-optimized for mass-production purposes.

The address-/data-lines and bank-switching logic uses the closest address-/data-lines
with shortest and most direct path/distance in order to avoid too much PCB re-routing
and keep production costs as low as possible.

This means that the respective address-/data-lines from the cartridge port
may not necessarily connect with the corresponding address-/data-line of
the ROM according to the official specs of the ROM.

This has over the years given some headaches and invalid dumps when cartridge
dumpers that wanted to dump the cartridge contents by de-soldering the ROM and
dumping it using an EPROM programmer/reader.

The image extracted from such an operation would need transformation according
to the actual cartridge PCB re-routing of address-/data-lines. Alternatively
one can make an adapter that implements this applied re-routing of the
address-/data-lines.

This mass-production cost optimization also results in an obscured bank-switching
address pattern/values more info on that later.

[HWrev1]: The original "Hugo" PCB [HWrev1] is labeled "HUGO Copyright 1990"
on both sides of the PCB.
PCB production date is stamped on the back og PCB in the format: "YYMM"
1Mib 27C010 EPROM or PROM (typical Atmel)
"Hugo" PCB [HWrev1] contains the following discrete logic IC components:
74LS00N (DIP) and 74LS237N (DIP)
DIP pitch (pin spacing) 2.54mm (0.1 inch)
Assembly/production facilities: Philips, Strandlodsvej (Amager), Copenhagen, Denmark

[HWrev1] Bank-switching pattern:
In order for the rom contents to appear as a continuous memory layout the following
ROM bank-switching pattern must be applied by writing to adress 0xDE00:
Cartridge bank-switching values: 00 80 10 90 20 a0 30 b0 40 c0 50 d0 60 e0 70 f0
Writing the bank-switch value to any address in address-range 0xDE00-0xDEFF
will work.

[HWrev2]: Revised PCB [HWrev2] for SMD mount is labeled "SO-A4-1"
on both sides of PCB.
1Mib Mask ROM (SOIC-32)
PCB contains the following discrete logic SMD IC components:
74HCT02T (SOIC-14) and 74HCT174T (SOIC-16)
SOIC (pitch) pin spacing 1.27mm (SMD mounted)
Assembly/production facilities: Sono Press, Germany.

[HWrev2] Uses alternative bank-switching pattern:
Writing *ANY* value to address 0xDE0y (offset y) will select ROM bank y
Cartridge still has 16 banks and the lower four bits in the address selects
the right bank. Hence the valid address range is 0xDE00-0xDE0F

@c @node FIXME
@subsubsection 56 - Formel 64

@multitable @columnfractions .3 .7
@item Size
@tab 32KiB (4 banks of 8KiB)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Startup mode
@tab Ultimax
@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 38 00 00 00 00 00 00 00 00  ...@@...8........
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: 48 A9 FC 0C A9 FE 8D C2 DF 68 48 C9 8C F0 1C C9  H........hH.....
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 E0 00 20 00  CHIP.. ....... .
2060: EA EA 58 48 A9 FC 8D C2 DF 4C 6E E2 EA EA A9 FA  ..XH.....Ln.....
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 E0 00 20 00  CHIP.. ....... .
4070: 4C 86 E4 A9 FE 78 8D C2 DF 60 78 8C C3 DF A9 FA  L....x...`x.....
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 E0 00 20 00  CHIP.. ....... .
6080: EA EA 48 58 A9 FC 8D C2 DF 68 48 C9 46 D0 7E 68  ..HX.....hH.F.~h
@end example

the following is a quick overview of how the cartridge works, as its a bit
unusual and different from most other cartridges:

@example
- 27256 EPROM (32KiB)
- 7430 TTL
- MC6821
- 1 button (reset)

rom bank 0x00 - 0x03 (0x04) 8192* 4 32KiB mapped to e000
MC6821 registers mapped to io2 at dfc0..dfc4

- press reset and hold delete to get the main menu
- press reset and hold control to skip cbm80 check 
  (dont start additional cartridge)

- press RESTORE, then...
  - left arrow, return  show disk directory
  - delete, 1           load"*" from disk, run
  - f1/f2               ? (disk stuff?)
  - f3/f4               ? (disk stuff?)
  - f5/f6, q            enter monitor
  - f7/f8, 2            show drive error channel
  - control, cursor     back to basic

  - type "help" in basic to get a list of available commands

*** MC6821 Port usage

Port A (parallel cable to floppy drive):
dfc0 port a ddr
dfc1 port a (in/out)

Port B (controls banking)
dfc2 port b ddr ($7f)
dfc3 port b (out)

bit3    1 = rom at $e000 enabled, 0 = cartridge disabled
bit1-2  rom bank number
bit0    ?
@end example

@c @node FIXME
@subsubsection 57 - RGCD

@multitable @columnfractions .3 .7
@item Size
@tab 64KiB (8 banks of 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB 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 39 00 01 00 00 00 00 00 00  ...@@...9........
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: 0C 80 0C 80 C3 C2 CD 38 30 31 30 34 8E 16 D0 20  .......80104... 
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP.. ....... .
2060: B9 0A 72 AB 0B F0 08 C9 2F 0C 10 27 E8 EF 5A C5  ..r...../..'..Z.
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP.. ....... .
4070: C0 B4 6C A6 6A 0A 14 5E 65 AD 94 02 86 C8 30 1F  ..l.j..^e.....0.
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP.. ....... .
6080: A4 89 C6 3A C4 60 F0 10 4D F5 89 F0 13 6C E0 78  ...:.`..M....l.x
@dots{}
8080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00  CHIP.. ....... .
8090: 00 0B 08 14 00 9E 32 30 36 31 00 00 00 A0 35 BA  ......2061....5.
@dots{}
A090: 43 48 49 50 00 00 20 10 00 00 00 05 80 00 20 00  CHIP.. ....... .
A0A0: 1B 4A 00 53 90 77 8E 1A 1D 94 00 A6 E2 50 29 11  .J.S.w.......P).
@dots{}
C0A0: 43 48 49 50 00 00 20 10 00 00 00 06 80 00 20 00  CHIP.. ....... .
C0B0: 14 F7 2E 1A 34 B4 60 53 07 88 C4 F0 21 F6 88 20  ....4.`S....!.. 
@dots{}
E0B0: 43 48 49 50 00 00 20 10 00 00 00 07 80 00 20 00  CHIP.. ....... .
E0C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@end example

    This cartridge type is very similar to the Magic Desk cart type: ROM  memory
    is  organized  in  8KiB  ($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 latch (1 = cart disabled until reset or powercycle)
@end example

    If the Cartridge Hardware Subtype/Revision (Offset 0x1A in the CRT Header)
    is 1, then the banks are addressed in reverse order and the emulated
    cartridge works like the eprom cartridge by "Hucky". This cartridge can
    also be equipped with 8Kib, 16Kib, 32Kib EPROMs.


@c @node FIXME
@subsubsection 58 - RR-Net MK3

@multitable @columnfractions .3 .7
@item Size
@tab 8KiB
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB 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 3A 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 02 00 00 80 00 20 00  CHIP.. ....... .
0050: 09 80 09 80 C3 C2 CD 38 30 78 A2 FF 9A D8 8E 16  .......80x......
@end example

    This cartridge has a CS8900a based RR-Net compatible network interface, and
    on  8KiB  ($2000)  bank ROM  located  at  $8000-$9FFF.  The ROM can be switched
    on/off by writing to the IO1 space:

@example
    a write to $de80 enables the ROM
    a write to $de88 disables the ROM
@end example

@c @node FIXME
@subsubsection 59 - EasyCalc

@multitable @columnfractions .3 .7
@item Size
@tab 24KiB (3 banks of 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab active (lo) (0)
@item Startup mode
@tab 16KiB Game
@item Load address
@tab $8000-$9FFF (bank 1),
                   $A000-$BFFF (banks 2/3)
@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 3B 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: 59 89 BC FE C3 C2 CD 38 30 0B 80 B1 84 48 E6 84  Y......80....H..
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP.. ....... .
2060: 04 0B 20 52 45 50 4C 49 43 41 54 45 20 FB 89 0F  .. REPLICATE ...
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00  CHIP.. ....... .
4070: 02 10 B5 00 C9 E3 D0 01 C8 C9 E2 D0 01 C8 C9 E0  ................
@end example

This cart uses 8KiB mapped in at $8000-$9FFF and 2 banks of 8KiB mapped in at $A000-$BFFF.

The bank at $A000-$BFFF is selected by bit 0 of the address of a write access to I/O-1.

@example
    A0 | bank
    ---------
     0 |  0
     1 |  1
@end example

@c @node FIXME
@subsubsection 60 - GMod2

@multitable @columnfractions .3 .7
@item Size
@tab 512KiB (64 banks of 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB 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
       -----------------------------------------------  ----------------
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 3C 00 01 00 00 00 00 00 00  ...@@...<........
00020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE CART.......
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 02 00 00 80 00 20 00  CHIP.. ....... .
00050: 09 80 09 80 C3 C2 CD 38 30 78 8E 16 D0 20 A3 FD  .......80x... ..
@dots{}
02050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP.. ....... .
02060: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@dots{}
7E430: 43 48 49 50 00 00 20 10 00 00 00 3F 80 00 20 00  CHIP.. ....?.. .
7E440: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@end example

GMod2 (Individual Computers)

This cart uses 512KiB Flash ROM (29F040) in 64 banks, mapped in at $8000-$9fff
and has a 2KiB serial EEPROM (m93C86).

@example
    io1
        - register at de00

        bit7   (rw)  write enable (write 1), EEPROM data output (read)
        bit6   (ro)  EXROM (0=active) and EEPROM chip select (1=selected)
        bit5-0 (ro)  rom bank  bit5 EEPROM clock bit4 EEPROM data input

    see http://wiki.icomp.de/wiki/GMod2
@end example

@c @node FIXME
@subsubsection 61 - MAX Basic

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB (ULTIMAX mode)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-$9FFF (bank 1),
     $E000-$FFFF (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 3D 01 00 00 00 00 00 00 00  ...@@...=........
0020: 4D 41 58 20 42 41 53 49 43 00 00 00 00 00 00 00  MAX 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: 94 E3 7B E3 43 42 4D 42 41 53 49 43 30 88 41 87  ....CBMBASIC0.A.
@end example

This cartridge uses two 8KiB ROMs that contain BASIC and KERNAL for the MAX Machine.
It also provides additional 2KiB RAM which will be mapped to $0800.

@c @node FIXME
@subsubsection 62 - GMod3

@multitable @columnfractions .3 .7
@item Size
@tab 2MiB/4MiB/8MiB/16MiB (256/512/1024/2048 banks of 8KiB)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB 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
       -----------------------------------------------  ----------------
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 3E 00 01 00 00 00 00 00 00  ...@@...<........
00020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE CART.......
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 02 00 00 80 00 20 00  CHIP.. ....... .
00050: 09 80 09 80 C3 C2 CD 38 30 78 8E 16 D0 20 A3 FD  .......80x... ..
@dots{}
02050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP.. ....... .
02060: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@dots{}
001FF030: 43 48 49 50 00 00 20 10 00 00 00 FF 80 00 20 00 CHIP.. ....?.. .
001FF040: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................

@end example

GMod3 (Individual Computers)

This cart uses 2MiB/4MiB/8MiB/16MiB Flash ROM (EN25QH128A(2T)) in 256/512/1024/2048 banks, 
mapped in at $8000-$9fff.

@example
    io1
        - register at de00-de07 (write)
        
        To select the ROM bank, write to de00-7. The lower 3 bits of the address
        are the upper three bits of the bank, as in:
        
        ldx #bankhi  ; upper 3 bits of the bank number
        lda #banklo  ; lower 8 bits of the bank number
        sta $de00,x

        - register at de00/de08 (read)
        
        The current ROM bank can be read from de00/de08, as in:
        
        ldx $de08    ; upper 3 bits of the bank number
        lda $de00    ; lower 8 bits of the bank number
        
        - register at de08 (write)

        bit7   (w)  bitbang mode enabled
        bit6   (w)  EXROM (0=active)
        bit5   (w)  enable cartridge irq vectors

        - register at de00 (bitbang mode)
        
        bit7   (r)  EEPROM data output
        bit6   (w)  EEPROM chip select (0=selected)
        bit5   (w)  EEPROM clock 
        bit4   (w)  EEPROM data input

    see http://wiki.icomp.de/wiki/GMod3
@end example

@c @node FIXME
@subsubsection 63 - ZIPP-CODE 48 

@multitable @columnfractions .3 .7
@item Size
@tab 8KiB
@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 3f 00 01 00 00 00 00 00 00  ...@@...?........
0020: 5a 49 50 50 2d 43 4f 44 45 20 34 38 00 00 00 00  ZIPP-CODE 48....
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: 11 de 7b e3 c3 c2 cd 38 30 41 80 00 00 03 81 31  ..?....80A.....1

@end example

@example
    reading IO1 enables the cartridge ROM
    reading IO2 disables the cartridge ROM
    the second last page of the ROM is mirrored in IO1    
@end example

@subsubsection 64 - Blackbox V8

@multitable @columnfractions .3 .7
@item Size
@tab 32KiB or 64KiB
@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 40 00 00 00 00 00 00 00 00  ...@@...@@........
0020: 42 4c 41 43 4b 42 4f 58 20 56 38 00 00 00 00 00  BLACKBOX V8.....
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 22 80 c3 c2 cd 38 30 8e 16 d0 20 a3 fd 20  ..?....80... .. 

@end example

@example
    writing to IO2 sets the cartridge config:
    A0 - EXROM
    A1 - GAME
    A2 - bank lsb
    A3 - bank msb
@end example

@subsubsection 65 - Blackbox V3

@multitable @columnfractions .3 .7
@item Size
@tab 8KiB
@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 41 00 01 00 00 00 00 00 00  ...@@...A........
0020: 42 4c 41 43 4b 42 4f 58 20 56 33 00 00 00 00 00  BLACKBOX V3.....
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: a7 85 2b 80 c3 c2 cd 38 30 8e 16 d0 20 a3 fd 20  ..+....80... .. 

@end example

@example
    writing IO1 disables the cartridge ROM
    writing IO2 enables the cartridge ROM
@end example

@subsubsection 66 - Blackbox V4

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB
@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 42 00 00 00 00 00 00 00 00  ...@@...B........
0020: 42 4c 41 43 4b 42 4f 58 20 56 34 00 00 00 00 00  BLACKBOX V4.....
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: a7 85 2b 80 c3 c2 cd 38 30 8e 16 d0 20 a3 fd 20  ..+....80... .. 

@end example

@example
    reading IO1 enables the cartridge ROM
    reading IO2 disables the cartridge ROM
@end example

@subsubsection 67 - REX RAM-Floppy

@multitable @columnfractions .3 .7
@item Size
@tab 8KiB
@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 43 00 01 00 00 00 00 00 00  ...@@...C........
0020: 52 45 58 20 52 41 4d 2d 46 4c 4f 50 50 59 00 00  REX RAM-FLOPPY..
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 fe c3 c2 cd 38 30 20 a3 fd 20 50 fd 20  .......80 .. P. 

@end example

This cartridge contains an 8KiB ROM which contains the software, plus up to 256KiB
RAM which can then be used to store up to 100 programs. The RAM is battery
buffered, and the cartridge can be disabled with a switch on the board.

@example
    dfa0    (write) selects RAM bank
    df50    (read) toggles RAM writeable
    dfc0    (read) toggles cartridge enable
    dfe0    (read) toggles RAM enable
@end example
    
@subsubsection 68 - BIS-Plus Cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 2, 4 or 8KiB
@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 44 00 01 00 00 00 00 00 00  ...@@...D........
0020: 42 49 53 2d 50 4c 55 53 00 00 00 00 00 00 00 00  BIS-PLUS........
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 8e 16 d0 20 a3 fd a0  ..^....80... ...

@end example

This cartridge contains a 2, 4 or 8KiB ROM. The software is copied to RAM and then
the cartridge disables itself by writing to IO1 (de00).
    
@subsubsection 69 - SD-BOX

@multitable @columnfractions .3 .7
@item Size
@tab 128KiB
@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 45 00 00 00 00 00 00 00 00  ...@@...E........
0020: 53 44 2d 42 4f 58 00 00 00 00 00 00 00 00 00 00  SD-BOX..........
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 81 ea c3 c2 cd 38 30 a9 00 8d 00 de a9 40  .......80......@@

@end example

This cartridge contains a 128KiB banked ROM with a filebrowser and some extra
software on it. It also contains a sd2iec clone, which seems to be seperate
and runs the original sd2iec firmware.

@example
    there is one register at de00:
    
    bit 0-3     ROM bank
    bit 4       reset SD
    bit 5       CE ROM
    bit 6       EXROM
    bit 7       register enable
    
    additionally there are 3 "ram cells" at de01-de03
@end example    

@c @node FIXME
@subsubsection 70 - MultiMAX

@multitable @columnfractions .3 .7
@item Size
@tab 1MiB, 64*16KiB (ULTIMAX mode)
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-$9FFF (odd banks),
     $E000-$FFFF (even banks)
@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 46 01 00 00 00 00 00 00 00  ...@@...F........
0020: 4d 55 4c 54 49 4d 41 58 00 00 00 00 00 00 00 00  MULTIMAX........
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: 48 80 48 83 48 83 48 83 64 85 64 85 f5 87 aa 88  H.H.H.H.d.d.....
@end example

This cartridge contains 1MiB ROM organised in 64 16KiB banks. It operates in 
ultimax mode and contains all known ultimax releases.
It also provides additional 2KiB RAM for MAX-Basic, which will be mapped to $0800.

@example
    there is one register mirrored in the entire IO1 space:
    
    bit 7       when set, the register is disabled and can only be reenabled by reset
    bit 0-5     select ROM bank 0-63    
@end example

@c @node FIXME
@subsubsection 71 - Blackbox V9

@multitable @columnfractions .3 .7
@item Size
@tab 32KiB, 2*16KiB
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-$9FFF
     $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 47 01 00 00 00 00 00 00 00  ...@@...G........
0020: 42 4c 41 43 4b 42 4f 58 20 56 39 00 00 00 00 00  BLACKBOX V9.....
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: 00 9a b6 fe c3 c2 cd 38 30 c3 ff 00 ff 00 ff 00  .......80.......
@end example

The cartridge starts in ultimax mode in the last bank. The IO1 area also contains
a mirror of the second last ROM page.
    
@example
    a register is mapped to IO1, which is changed by accessing an address in
    the IO space, the address bits are mapped like this:
    
    bit 7   -   bank    (inverted on write)
    bit 6   -   exrom
    bit 0   -   game
@end example

@c @node FIXME
@subsubsection 72 - Lt. Kernal Host Adaptor

@multitable @columnfractions .3 .7
@item Size
@tab 8KiB ROM, 16KiB RAM
@item EXROM
@tab active (lo) (0) Initially
@item GAME
@tab inactive (hi) (1) Initially
@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 48 00 01 00 00 00 00 00 00  ...@@...H........
0020: 4c 54 2e 20 4b 45 52 4e 41 4c 20 48 4f 53 54 20  LT. KERNAL HOST 
0030: 41 44 41 50 54 4f 52 20 36 2e 32 20 52 4f 4d 00  ADAPTOR 6.2 ROM.
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP............
0050: 14 80 14 80 c3 c2 cd 38 30 00 38 37 30 30 30 30  .......80.......

@end example

The Lt. Kernal Host Adaptor (SCSI ID 7) boot rom looks on sector 0 of drive 0
(ID 0) to find the partition (LU or logical unit) information and DOS. If the
drive is not found, it will start up in stock mode.  See
src/c64/cart/ltkernal.c for more details.

The Lt. Kernal Host Adaptor uses the following registers:

@example
    $DF00    = MC6821 Port A: Data and DDR
    $DF01    = MC6821 Port A: Control
    $DF02    = MC6821 Port B: Data and DDR
    $DF03    = MC6821 Port B: Control
    $DF04..7 = LTK Port and Freeze state
@end example

MC6821 Port A connects to the SCSI data bus (inverted). Data is saved to hard 
disk inverted to save data processing time.

@example
 signal  meaning
 ------  -------
 PA 7-0  /Data bus on SCSI (input/output)
 CA2     Pulses SCSI ACK (low to high)
@end example

MC6821 Port B connects to mostly the SCSI control bus. PB2.6 controls write 
access to 16KiB SRAM. When low (0), no writes are permitted, when high (1) 
writes are permitted to $8000-$9FFF AND $E000-$FFFF. Initially, this signal is 
low, which keeps the boot ROM mapped to $8000-$9FFF (lower 4KiB for the C64, 
upper 4KiB for the C128). Once a high (1) is written, the boot ROM is mapped 
out permanently until a reset. CB2 controls which KERNAL is in place. A high 
(1) uses the stock KERNAL while a low (0) maps in one of the 8K RAMs as the 
KERNAL. The other RAM at $8000-$9FFF memory is ONLY mapped in when PB2.6 is 
high (1). The HIRAM line from the PLA goes to the adaptor so it can determine 
the proper write action to the main RAM or adaptor RAM. Writing a high (1) to 
CB2 while PB2.6 is low (0) causes a system reset. The stock KERNAL is copied and 
then patched by the LTK DOS on startup.

@example
 signal  meaning
 ------  -------
 PB 7    /REQ on SCSI (input)
 PB 6    SRAM control
 PB 5    RST on SCSI (output)
 PB 4    SEL on SCSI (output)
 PB 3    /BUSY on SCSI (input)
 PB 2    /CD on SCSI (input)
 PB 1    /MSG on SCSI (input)
 PB 0    /IO on SCSI (input)
 CB2     KERNAL control
@end example

$DF04 - $DF07:

The LTK Port can be between 0 and 15. Only adaptors set to port 0 are allowed 
to change the host configuration. Any writes to this register while PB2.6 and 
CA2 are high (1), will result in the Lt. Kernal Host Adaptor being removed from 
the bus until a reset, essentially reconfiguring to a stock system.

@example
    bit  meaning
    ---  -------
    3-0  LTK port number (input)
    4    Freeze state (0: active, 1: inactive)
@end example

@c @node FIXME
@subsubsection 73 - RAMLink

@multitable @columnfractions .3 .7
@item Size
@tab 64KiB ROM, 8KiB RAM
@item EXROM
@tab inactive (hi) (1) Initially
@item GAME
@tab active (lo) (0) Initially
@item Load address
@tab $8000-$BFFF and $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 49 01 00 00 00 00 00 00 00  ................
0020: 43 4d 44 20 52 41 4d 4c 49 4e 4b 20 32 2e 30 31  CMD RAMLink 2.01
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 20 00  CHIP............
0050: 00 00 00 00 00 00 00 00 ee 42 df 20 1c b9 ee 42  ................
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP............
2060: 03 4c 75 9c 88 f0 01 88 8c 80 de a9 8d 20 38 8f  ................
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP............
4070: 0a 17 d8 8d 64 8c be 00 ce 42 df 20 48 88 ce 42  ................
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP............
6080: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@dots{}
8080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00  CHIP............
8090: 40 48 20 c9 ff aa 68 90 01 8a 60 20 bd ff 20 64  ................
@dots{}
a090: 43 48 49 50 00 00 20 10 00 00 00 05 80 00 20 00  CHIP............
a0a0: 85 56 20 0f bc a5 61 c9 88 90 03 20 d4 ba 20 cc  ................
@dots{}
c0a0: 43 48 49 50 00 00 20 10 00 00 00 06 80 00 20 00  CHIP............
c0b0: 80 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@dots{}
e0b0: 43 48 49 50 00 00 20 10 00 00 00 07 80 00 20 00  CHIP............
e0c0: a2 ff 78 9a d8 a9 00 8d 00 ff a2 0a bd 4b e0 9d  ................

or

      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 49 00 01 00 00 00 00 00 00  ................
0020: 43 4d 44 20 52 41 4d 4c 49 4e 4b 20 31 2e 34 30  CMD RAMLink 1.40
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 20 00  CHIP............
0050: 52 41 4d 4c 49 4e 4b 20 44 4f 53 20 28 43 29 31  ................
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP............
2060: 4e 54 41 58 20 45 52 52 4f 52 00 57 52 49 54 45  ................
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP............
4070: aa 09 f9 10 ec b9 9e 1b ec ce 3f 70 8d 84 df a9  ................
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP............
6080: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@dots{}
8080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00  CHIP............
8090: 40 48 20 c9 ff aa 68 90 01 8a 60 20 bd ff 20 64  ................
@dots{}
a090: 43 48 49 50 00 00 20 10 00 00 00 05 80 00 20 00  CHIP............
a0a0: 85 56 20 0f bc a5 61 c9 88 90 03 20 d4 ba 20 cc  ................
@dots{}
c0a0: 43 48 49 50 00 00 20 10 00 00 00 06 80 00 20 00  CHIP............
c0b0: 80 8d 3f de a9 1b 8d 32 de 8d 34 de a9 ee 8d 33  ................
@dots{}
e0b0: 43 48 49 50 00 00 20 10 00 00 00 07 80 00 20 00  CHIP............
e0c0: a2 ff 78 9a d8 a9 00 8d 00 ff a2 0a bd 4b e0 9d  ................
@end example

The RAMLink CRT file is 64 KiB and consists of eight 8 KiB banks. The first
two are for the RAMLink DOS which is banked in from $8000-$BFFF (16 KiB).
The third and forth are the configuration portion of the DOS which also banks
in at $8000-$BFFF, however only the first 8 KiB is officially used.
The banks are the 64 shadow kernal, 64 trap kernal, 128 shadow kernal, and
128 trap kernal respectively.
The first bytes of the configuration DOS bank contain 16-bit checksums of
various parts of the ROM. The precise mapping is specific to the particular
version of the ROM as the code resides there.
The ROMs verify these checksums on boot up.
Should this fail, the firmware turns on the error LED and goes into an
infinite loop.
Since vice doesn't provide an error or activity LED for RAMLink, the system
would just appear to hang.

The actual RAMLink appears to have the ability to upgrade to a 128 KiB ROM,
but no firmware which utilizes it is known to exist.

The RAMLink uses many locations in IO2 primarily so that it can co-exist with
other cartridges. Most of these registers are write only, that is to say, all
that is required to activate them is a write; the contents of the write are
not important. This technique minimizes the coding required to interact with
the device.
Although RAMLink has 2 pass-thru ports, they are not complete shorts to
the cartridge bus, some of the control lines are altered based on the state
of the device.
Initially, RAMLink is disabled, the trap kernal is active and only one of its
registers is visible:

@example
    $DF7E    = Enable RAMLink registers and switch to shadow kernal
@end example

Once a write is done to $DF7E, all the other registers become active. The
shadow kernal also switches in. This happens regardless of the state of the
microprocessor IO port ($1). Even if the kernal ROM is mapped out, the shadow
kernal will appear.

@example
    $DF20     = NMI Trap Enable? (not certain as to its function)
    $DF21     = Mirror to $DF01 (for REU) when NMI trap is on
    $DF22     = NMI Trap Disable? (not certain as to its function)
    $DF40     = I8255A Port A (Main board and parallel interface)
    $DF41     = I8255A Port B
    $DF42     = I8255A Port C
    $DF43     = I8255A Control
    $DF60     = Enable DOS mapping (maps in $8000-$BFFF)
    $DF70     = Disable DOS mapping
    $DF7F     = Disable RAMLink registers and switch to trap kernal
                (also disables DOS mapping)
    $DF80..9F = Switch SRAM page ($DF80 selects page 0,
                $DF81 selects page 1, $DF82 selects page 2, etc.)
    $DFA0     = I8255A Port A (RAMCard 1; RAMCard 2 uses custom circuit
                but same interface)
    $DFA1     = I8255A Port B
    $DFA2     = I8255A Port C
    $DFA3     = I8255A Control
    $DFB0..BF = 72421 RTC interface (RAMCard 2 only)
    $DFC0     = Maps in SRAM to $DE00-$DEFF
    $DFC1     = Maps in RAMCard to $DE00-$DEFF
    $DFC2     = Maps in RAM Port $DE00-$DEFF (GEORAM, RAMDrive)
    $DFC3     = Maps in Pass-Thru to $DE00-$DEFF
@end example

Note that only address $DF40..42, $DFB0..BF present valid information when
read. Addresses $DFA0..$DFA3 also require valid data when being written to.
See src/c64/cart/ramlink.c for more details.

When kernal swiching, the ROMs change inbetween instructions. This is possible
as the CPU does not cache any incoming instructions. The following is
an example of a JSR to the trap kernal at $E000:

@example
PC     TRAP        SHADOW      DETAILS
          KERNAL      KERNAL
-----  ---------   ---------   ------------------------------------------
$C000  JSR $E000   JSR $E000   Same code
$E000  STA $DF7E   STA $DF7F   In trap kernel, next instruction in shadow
$E003  INC $D021   INC $D020   Increment $D020
$E006  STA $DF7E   STA $DF7F   Switch back to trap on next instruction
$E009  RTS         NOP         Return to $C003
@end example

If the shadow kernal was active, a JSR to $E000 would result in $D021 being
incremented and continuing on back to the NOP in the shadow kernal.
The use of write only registers allows the RAMLink Kernal and DOS to perform
ROM switching with minimal instructions and time.

The RAMLink includes two switches: "Enable/Disable" and "Normal/Direct".
"Enable/Disable" controls whether or not RAMLink is active. In the "Disabled"
state, control will be given back to the stock ROMs.
"Normal/Direct" controls how the IO cartidge lines to the RAM Port (REU,
GEORAM, RAMDrive) are passed. In "Normal" mode, these lines are connected
only when the RAMLink registers are active. This prevents any unauthorized
access to these devices while RAMLink code isn't running. "Direct" connects
the IO lines all the time.

@c @node FIXME
@subsubsection 74 - Drean

@multitable @columnfractions .3 .7
@item Size
@tab 32KiB (4 banks of 8KiB each)
@item EXROM
@tab active (lo) (0)
@item GAME
@tab inactive (hi) (1)
@item Startup mode
@tab 8KiB 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 4a 00 01 00 00 00 00 00 00  ...@...J........
0020: 44 52 45 41 4e 20 48 45 52 4f 00 00 00 00 00 00  DREAN HERO......
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: 0b 80 bc fe c3 c2 cd 38 30 03 49 8e 16 d0 bd 00  .......80.I.....
..
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP.. ....... .
2060: 32 aa 5a aa 00 00 ff 00 90 d9 68 d9 00 00 90 05  2.Z.......h.....
..
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP.. ....... .
4070: ff 7f 7f ff ff 3f 00 00 00 00 00 c0 00 c0 ff 3f  .....?.........?
..
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP.. ....... .
6080: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@end example

    This cartridge type was found in an argentinian H.E.R.O. clone cartridge,
    ROM  memory is  organized in 8KiB ($2000) banks located at $8000-$9FFF. 
    There appears to be one register mirrored over IO2 (the software uses $DFFF).
    Banks are selected by writing to the lower 2 bits of the register, bit 5
    disables the cartridge.

@c @node FIXME
@subsubsection 75 - IEEE Flash! 64

@multitable @columnfractions .3 .7
@item Size
@tab 8KiB (1 bank of 8KiB)
@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 2D 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 8KiB 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 76 - Turtle Graphics II

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB (2 banks of 8KiB each)
@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 4c 00 01 00 00 00 00 00 00  ...@...L........
0020: 48 45 53 20 54 75 72 74 6c 65 20 47 72 61 70 68  HES Turtle Graph
0030: 69 63 73 20 49 49 00 00 00 00 00 00 00 00 00 00  ics II..........
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP.. ....... .
0050: 09 80 bc fe c3 c2 cd 38 30 78 a9 80 85 11 a9 30  .......80x.....0
0060: 85 10 a9 0e 85 13 a9 00 85 12 aa a8 b1 10 91 12  ................
0070: c8 d0 f9 e6 11 e6 13 e8 e0 09 d0 f0 4c 90 15 ea  ............L...
0080: 01 c0 00 01 a0 00 01 90 00 03 88 00 03 84 00 05  ................
0090: 82 00 05 81 00 09 80 80 09 80 40 11 80 20 11 80  ............. ..
@dots{}
4040: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
4050: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@end example

    Any read/write access to IO1 area will  switch  to  bank  1.  Reset will
    switch to bank 0.

@c @node FIXME
@subsubsection 77 - Freeze Frame MK2

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB
@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 CART RIDGE   
0010: 00 00 00 40 01 00 00 4d 00 01 00 00 00 00 00 00  ...@...M ........
0020: 46 72 65 65 7a 65 20 46 72 61 6d 65 20 4d 4b 32  Freeze F rame MK2
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: 10 80 0c 80 c3 c2 cd 38 30 20 00 00 40 00 00 00  .......8 0 ..@...
@dots{}
4030: 02 b0 02 c6 03 60 00 00 a9 ff 85 00 a4 01 68 aa  .....`.. ......h.
4040: 68 98 09 20 48 8a 48 4c 1b ff e0 fe 10 80 10 80  h.. H.HL ........
@end example

Warning, the following information is based on guess-work and might be
incorrect, any further information and/or corrections are appreciated.

When the cart starts, the first half of the active ROM is banked to ROML ($8000-$9fff).
When reading from  the  I/O-2  range  the second half of the active ROM  bank
is enabled in RMH ($A000-$BFFF). When  reading from the I/O-1 range the cart is
disabled. 

When a freeze happens the first half of the ROM is mapped to ROML ($8000-$9FFF) and
the second half to ROMH ($E000-$FFFF).

@c @node FIXME
@subsubsection 78 - Partner 64

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB
@item EXROM
@tab inactive (hi) (1)
@item GAME
@tab active (lo) (0)
@item Load address
@tab $8000-$9FFF (ROML), $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 4e 01 00 00 00 00 00 00 00  ...@...N........
0020: 50 61 72 74 6e 65 72 20 36 34 00 00 00 00 00 00  Partner 64......
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: 78 48 a5 00 48 a5 01 48 a9 2f 85 00 a9 37 85 01  xH..H..H./...7..
@dots{}
4040: 00 00 00 00 00 00 00 00 00 00 01 00 eb 06 c7 06  ................
4050: ff ff ff ff ff ff ff 4c 5d ea 00 80 12 84 e0 84  .......L].......

@end example

Warning, the following information is based on guess-work and might be
incorrect, any further information and/or corrections are appreciated.

This cartridge has 16KiB of ROM and 8KiB of RAM. It starts in ultimax mode with
ROML at $8000, ROMH at $e000 and the extra RAM at $a000.

@c @node FIXME
@subsection C128 Cartridge Specifics

Note: Cartridges that work on both C64 and C128 get "C64 Cartridge" type and get a
CRT-ID in the C64 list! @b{ONLY} Cartridges that exclusively work in C128 mode get
a CRT-ID in the C128 list and "C128 Cartridge" header type.

@multitable @columnfractions .1 .9
@item @b{CRT ID}
@tab @b{Cartridge Type}
@item 0
@tab generic cartridge
@item 1
@tab Warpspeed128
@item 2
@tab Partner 128
@item 3
@tab Comal 80
@item 4
@tab Magic Desk 128
@item 5
@tab Gmod2-C128
@end multitable

@c @node FIXME
@subsubsection 0 - generic (external Function ROM)

Generic cartridges for the C128 can use two 16KiB ROM blocks named ROML and ROMH,
which are mapped to $8000-$BFFF and $C000-$FFFF respectively.

Commonly such cartridges contain one or two 8KiB or 16KiB CHIP packets, one for ROML
and one for ROMH. When a block uses a ROM smaller than the block (like 8KiB ROM), then
mirrors should be created within that ROM block.

Typical cartridges are 32KiB (ROML+ROMH) or 16KiB (ROML only), although smaller
cartridges exist.

@b{8KiB lo function ROM}

@multitable @columnfractions .3 .7
@item Size
@tab 8KiB
@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 31 32 38 20 43 41 52 54 52 49 44 47 45 20 20  C128 CARTRIDGE  
0010:  00 00 00 40 02 00 00 00 00 00 00 00 00 00 00 00  ...@............
0020:  47 65 6e 65 72 69 63 20 43 31 32 38 20 43 61 72  Generic C128 Car
0030:  74 72 69 64 67 65 00 00 00 00 00 00 00 00 00 00  tridge..........
0040:  43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP.. ....... .
0050:  4c 0a 80 4c 0a 80 02 43 42 4d 78 a2 ff 9a d8 a9  L..L...CBMx.....
@dots{}
2030:  aa aa aa aa aa aa aa aa aa aa aa aa aa aa aa aa  ................
2040:  aa aa aa aa aa aa aa aa aa aa aa aa aa aa aa aa  ................
@end example

@b{16KiB lo function ROM}

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB
@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 31 32 38 20 43 41 52 54 52 49 44 47 45 20 20  C128 CARTRIDGE  
0010:  00 00 00 40 02 00 00 00 00 00 00 00 00 00 00 00  ...@............
0020:  47 65 6e 65 72 69 63 20 43 31 32 38 20 43 61 72  Generic C128 Car
0030:  74 72 69 64 67 65 00 00 00 00 00 00 00 00 00 00  tridge..........
0040:  43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP..@.......@.
0050:  4c 0a 80 60 ea ea ff 43 42 4d a5 d4 c9 48 d0 01  L..`...CBM...H..
@dots{}
4030:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
4040:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@end example

@b{32KiB lo+hi function ROM}

@multitable @columnfractions .3 .7
@item Size
@tab 32KiB
@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 31 32 38 20 43 41 52 54 52 49 44 47 45 20 20  C128 CARTRIDGE  
0010:  00 00 00 40 02 00 00 00 00 00 00 00 00 00 00 00  ...@............
0020:  47 65 6e 65 72 69 63 20 43 31 32 38 20 43 61 72  Generic C128 Car
0030:  74 72 69 64 67 65 00 00 00 00 00 00 00 00 00 00  tridge..........
0040:  43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP..@.......@.
0050:  4c 0a 80 d2 d7 d7 30 43 42 4d ad 00 ff 85 fe ad  L.....0CBM......
@dots{}
8040:  32 39 3a 89 31 00 ee 26 50 00 d6 31 32 00 00 00  29:.1..&P..12...
8050:  a9 01 a0 00 91 2d 20 4f 4f 4c 82 4f 00 00 00 00  .....- OOL.O....
@end example

@c @node FIXME
@subsubsection 1 - Warpspeed128

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB
@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 31 32 38 20 43 41 52 54 52 49 44 47 45 20 20  C128 CARTRIDGE  
0010:  00 00 00 40 02 00 00 01 00 00 00 00 00 00 00 00  ...@............
0020:  57 61 72 70 20 53 70 65 65 64 20 31 32 38 00 00  Warp Speed 128..
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. ..
@dots{}
4030:  19 ad 00 1c 29 fd 05 19 8d 00 1c a2 02 bd 03 01  ....)...........
4040:  95 15 95 11 ca d0 f6 8e 00 07 60 41 54 21 21 21  ..........`AT!!!
@end example

This is a 16KiB ROM starting at $8000. The part at $9e00-$9fff is mirrored
to $de00-$dfff in I/O space.

@c @node FIXME
@subsubsection 2 - Partner 128

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB ROM, 8KiB RAM
@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 31 32 38 20 43 41 52 54 52 49 44 47 45 20 20  C128 CARTRIDGE  
0010: 00 00 00 40 02 00 00 02 00 00 00 00 00 00 00 00  ...@............
0020: 50 61 72 74 6e 65 72 20 31 32 38 00 00 00 00 00  Partner 128.....
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 5a 87 4c 5a 87 02 43 42 4d 85 1a 84 1b a0 00  LZ.LZ..CBM......
@dots{}
4030: 22 20 4b f2 8a 0a 0a 0a 0a 0a 85 c2 ad 00 1c 29  " K............)
4040: 9f 05 c2 8d 00 1c 60 8d 03 ff 91 ae 8d 04 ff 60  ......`........`
@end example

$8000-$9fff contains the ROM
$de00-$de7f contains 128 bytes ram
$de80-$deff contains a mirror of $9e80-$9eff
Writing to $de80 selects which one of 64 blocks of 128 byte ram is visible in $de00-$de7f.

@c @node FIXME
@subsubsection 3 - Comal 80

@multitable @columnfractions .3 .7
@item Size
@tab 96KiB (6 banks of 16KiB)
@item Load address
@tab $C000-$FFFF
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
000000: 43 31 32 38 20 43 41 52 54 52 49 44 47 45 20 20  C128 CARTRIDGE  
000010: 00 00 00 40 02 00 00 03 00 00 00 00 00 00 00 00  ...@............
000020: 43 6f 6d 61 6c 20 38 30 20 28 43 31 32 38 29 00  Comal 80 (C128).
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000040: 43 48 49 50 00 00 40 10 00 00 00 00 c0 00 40 00  CHIP..@.......@.
000050: 4c 8c c9 4c 85 1f 01 43 42 4d 4c 5d d2 4c b9 cd  L..L...CBML].L..
@dots{}
018080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
018090: 20 20 20 20 20 20 20 20 20 20 05 ff 3d ff 17 ff            ..=...
@end example

This cartridge contains 3 32KiB ROMs, each containing two 16KiB banks, which are
mapped to $C000 (ROMH). Bankswitching is done via one register at $DE00.

@c @node FIXME
@subsubsection 4 - Magic Desk 128

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB ROM, up to 64 banks (=1MiB)
@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
        -----------------------------------------------  ----------------
000000: 43 31 32 38 20 43 41 52 54 52 49 44 47 45 20 20  C128 CARTRIDGE  
000010: 00 00 00 40 02 00 00 04 00 00 00 00 00 00 00 00  ...@............
000020: 4d 61 67 69 63 20 44 65 73 6b 20 31 32 38 00 00  Magic Desk 128..
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP..@.......@.
000050: 4c 0a 80 4c 12 81 01 43 42 4d d8 a9 3a 8d 00 ff  L..L...CBM..:...
@dots{}
040120: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
040130: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@end example

This cartridge contains two ROM sockets with 19 address lines (A0..A18) each.
A19 selects which of the two ROM sockets is selected.

D0..D5 of the register at $de00 go to A14..A19.
D6/D7 of the register are not used

That means:
D0..D4 select the ROM bank
D5     selects the ROM socket

The common use-case would be to fill the first ROM first (with 512KiB), and only
then add a second ROM. This way you can use linear values in the register to
select the respective banks.

@c @node FIXME
@subsubsection 5 - Gmod2-C128

@multitable @columnfractions .3 .7
@item Size
@tab 16KiB ROM, up to 32 banks (=512KiB)
@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
        -----------------------------------------------  ----------------
000000: 43 31 32 38 20 43 41 52 54 52 49 44 47 45 20 20  C128 CARTRIDGE  
000010: 00 00 00 40 02 00 00 05 00 00 00 00 00 00 00 00  ...@............
000020: 47 6d 6f 64 32 2d 43 31 32 38 00 00 00 00 00 00  Gmod2-C128......
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP..@.......@.
000050: 4c 0a 80 4c 0a 80 02 43 42 4d 78 a9 0a 8d 00 ff  L..L...CBMx.....
@dots{}
080220: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
080230: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@end example

This is similar to the C64 Gmod2 Cartridge. The differences are:
- Banks are 16KiB instead of 8. Because of that one bit less in the register
is used for banking
- The ROM is always mapped to ROML area

@c @node FIXME
@subsection VIC20 Cartridge Specifics

@multitable @columnfractions .1 .9
@item @b{CRT ID}
@tab @b{Cartridge Type}
@item 0
@tab generic cartridge
@item 1
@tab Mega-Cart
@item 2
@tab Behr Bonz
@item 3
@tab Vic Flash Plugin
@item 4
@tab UltiMem
@item 5
@tab Final Expansion
@end multitable

@c @node FIXME
@subsubsection 0 - generic cartridge

Generic VIC20 cartridges are a bit more complex than the ones from the other
machines. Since the VIC20 has so little internal memory, most of it is available
to be used for ROM and/or RAM at the expansion port:

@multitable @columnfractions .1 .4 .4 .1
@item @b{Block}
@tab @b{Start}
@tab @b{End}
@tab @b{Size}
@item 0
@tab $0400
@tab $0FFF
@tab 3k
@item 1
@tab $2000
@tab $3FFF
@tab 8k
@item 2
@tab $4000
@tab $5FFF
@tab 8k
@item 3
@tab $6000
@tab $7FFF
@tab 8k
@item 5
@tab $A000
@tab $BFFF
@tab 8k
@end multitable

Common start addresses for cartridge ROMs are $2000, $4000, $6000, $7000, $A000, $B000.
Also common, for 16KiB cartridges, is a combination of block 1 or 3 with block 5.

Generic VIC20 .crt files may contain one or more CHIP packets fitting into the
above blocks. If only the beginning of a block is used for ROM, then the reminder
should be filled with mirrors (as it would happen on the real hardware when using
a smaller rom and not decoding the unused lines).

@c @node FIXME
@subsubsection 1 - Mega-Cart

@multitable @columnfractions .3 .7
@item Size
@tab 2MiB
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
  0000: 56 49 43 32 30 20 43 41 52 54 52 49 44 47 45 20  VIC20 CARTRIDGE 
  0010: 00 00 00 40 02 00 00 01 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 a0 00 20 00  CHIP.. ....... .
  0050: fd be 0e bf 41 30 c3 c2 cd 81 00 81 55 c1 5a 81  ....A0......U.Z.
@dots{}
201020: a7 ac b0 b5 b9 bd c1 c4 c7 ca cd d0 d3 d5 d8 da  ................
201030: dc de e0 e2 e3 e5 fe 24 17 00 00 00 00 00 00 00  .......$........
@end example

@c FIXME: cartridge details

@c @node FIXME
@subsubsection 2 - Behr Bonz

@multitable @columnfractions .3 .7
@item Size
@tab 2MiB (128 banks)
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
  0000: 56 49 43 32 30 20 43 41 52 54 52 49 44 47 45 20  VIC20 CARTRIDGE 
  0010: 00 00 00 40 02 00 00 02 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 a0 00 20 00  CHIP.. ....... .
  0050: 10 b0 10 b0 41 30 c3 c2 cd ff ff ff ff ff ff ff  ....A0..........
@dots{}
201020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
201030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
@end example

This cartridge has one bank register, mirrored over the whole IO3 ($9c00-$9fff)

@c FIXME: cartridge details


@c @node FIXME
@subsubsection 3 - Vic Flash Plugin

@multitable @columnfractions .3 .7
@item Size
@tab 4MiB
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
  0000: 56 49 43 32 30 20 43 41 52 54 52 49 44 47 45 20  VIC20 CARTRIDGE 
  0010: 00 00 00 40 02 00 00 03 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 a0 00 20 00  CHIP.. ....... .
  0050: 66 a1 31 a1 41 30 c3 c2 cd 00 00 01 03 00 01 8d  f.1.A0..........
@dots{}
402020: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
402030: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@end example

This cartridge has two registers, which are mirrored over the whole IO2 ($9800-$9bff)
area:

@example
$9800   current bank (A20..A13)
$9801   configuration register
 b7     1: I/O2 disabled until RESET
 b6     1: ROM write protect (set by default)
 b5     1: RAM at BLK5 (instead of ROM)
 b4     0: 3k (RAM123), 1: 8k+ (BLK1)
 b3     1: BLK1/RAM123 enable
 b2     unused (always 0)
 b1     unused (always 0)
 b0     A21
@end example

@c FIXME: cartridge details


@c @node FIXME
@subsubsection 4 - UltiMem

@multitable @columnfractions .3 .7
@item Size
@tab 8MiB or 16MiB
@end multitable

@example
         00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
         -----------------------------------------------  ----------------
   0000: 56 49 43 32 30 20 43 41 52 54 52 49 44 47 45 20  VIC20 CARTRIDGE 
   0010: 00 00 00 40 02 00 00 04 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 a0 00 20 00  CHIP.. ....... .
   0050: 09 a0 09 a0 41 30 c3 c2 cd 78 a2 ff 9a d8 a9 7f  ....A0...x......
@dots{}
1008020: a7 00 a2 07 a3 74 a3 57 a1 55 a1 be a9 ea a0 da  .....t.W.U......
1008030: ff ea a0 d0 ff b6 a3 aa aa aa aa aa aa aa aa aa  ................
@end example

This cartridge has 512KiB or 1MiB of RAM and 8MiB or 16MiB of flash rom.

@c FIXME: cartridge details


@c @node FIXME
@subsubsection 5 - Final Expansion

@multitable @columnfractions .3 .7
@item Size
@tab 512KiB (ROM) and 512KiB (RAM)
@end multitable

@example
       00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
       -----------------------------------------------  ----------------
 0000: 56 49 43 32 30 20 43 41 52 54 52 49 44 47 45 20  VIC20 CARTRIDGE 
 0010: 00 00 00 40 02 00 00 05 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 a0 00 20 00  CHIP.. ....... .
 0050: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@dots{}
80420: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
80430: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@end example

This cartridge has 512KiB Flash ROM and 512KiB RAM.

It has two registers mirrored every 4 Bytes in the while IO3 ($9c00-$9fff) range.

@example
$9c02
    bit 7..5    mode
                000: Start Mode
                001: Flash-Write-Mode
                010: Super ROM Mode
                011: RAM/ROM Mode
                100: RAM 1 Mode
                101: Super RAM Mode
                110: RAM 2 Mode
    bit 4       block5 select
    bit 3       block3 select
    bit 2       block2 select
    bit 1       block1 select
    bit 0       block0 select

$9c03
    bit 7  1: register off
    bit 6  1: invert A14
    bit 5  1: invert A13
    bit 4  1: block5 off
    bit 3  1: block3 off
    bit 2  1: block2 off
    bit 1  1: block1 off
    bit 0  1: block0 off
@end example

@c FIXME: cartridge details


@c @node FIXME
@subsection PLUS4 Cartridge Specifics

@multitable @columnfractions .1 .9
@item @b{CRT ID}
@tab @b{Cartridge Type}
@item 0
@tab generic cartridge
@item 1
@tab c264 magic cart
@item 2
@tab Plus4 multi cart
@item 3
@tab 1MB Cartridge
@end multitable

For all Plus4 binary formats (non .crt) the convention is to store all banks of
c1lo first, then all banks of c1hi, c2lo, c2hi.

@c @node FIXME
@subsubsection 0 - generic cartridge

generic cartridges can use 4 different ROM spaces, which are c1lo, c1hi, c2lo,
c2hi. most cartridges will use c1lo only, c2 is really uncommon. to indicate
which chip chunk goes where, the bank number is used - bank 1 means c2.

@b{32KiB C1 cartridge}

@multitable @columnfractions .3 .7
@item Size
@tab 32KiB
@item Load address
@tab $8000-$FFFF (C1)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 50 4c 55 53 34 20 43 41 52 54 52 49 44 47 45 20  PLUS4 CARTRIDGE 
0010: 00 00 00 40 02 00 00 00 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 40 10 00 00 00 00 80 00 40 00  CHIP..@.......@.
0050: 4c 47 80 4c f4 80 06 43 42 4d 53 59 53 31 35 32  LG.L...CBMSYS152
@dots{}
8040: ff 20 40 ff 20 40 ff 20 40 ff 20 40 ff 20 40 ff  . @. @. @. @. @.
8050: 20 40 ff 20 40 ff 8d 3e ff 4c a4 f2 f6 ff b3 fc   @. @..>.L......
@end example

@c @node FIXME
@subsubsection 1 - c264 magic cart

@multitable @columnfractions .3 .7
@item Size
@tab 128KiB/256KiB/512KiB/1MiB/2MiB (32/64/128 banks of 16KiB)
@item Load address
@tab $8000-$BFFF (C1LO)
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
  0000: 50 4c 55 53 34 20 43 41 52 54 52 49 44 47 45 20  PLUS4 CARTRIDGE 
  0010: 00 00 00 40 02 00 00 01 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 40 10 00 00 00 00 80 00 40 00  CHIP..@.......@.
  0050: 4c 13 80 4c 13 80 01 43 42 4d 38 42 49 54 43 48  L..L...CBM8BITCH
@dots{}
200820: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
200830: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@end example

This cartridge has one banking register at $fdfe.

@c @node FIXME
@subsubsection 2 - Plus4 multi cart

@multitable @columnfractions .3 .7
@item Size
@tab 2MiB/4MiB (64/128 banks of 32KiB)
@item Load address
@tab $8000-$FFFF (C1)
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
  0000: 50 4c 55 53 34 20 43 41 52 54 52 49 44 47 45 20  PLUS4 CARTRIDGE 
  0010: 00 00 00 40 02 00 00 02 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 40 10 00 00 00 00 80 00 40 00  CHIP..@.......@.
  0050: 4c 6b 80 4c 6b 80 01 43 42 4d 0a 0a ee f1 00 20  Lk.Lk..CBM..... 
@dots{}
401020: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
401030: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff  ................
@end example

This cartridge has one banking register at $fda0.

@c @node FIXME
@subsubsection 3 - 1MB Cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 1MiB (64 banks of 16KiB)
@item Load address
@tab $8000-$BFFF (C1LO)
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
  0000: 50 4c 55 53 34 20 43 41 52 54 52 49 44 47 45 20  PLUS4 CARTRIDGE 
  0010: 00 00 00 40 02 00 00 03 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 40 10 00 00 00 00 80 00 40 00  CHIP..@.......@.
  0050: 4c 4f 80 00 00 00 0c 43 42 4d 53 59 53 31 35 32  LO.....CBMSYS152
@dots{}
100420: 2f ef ee da db 20 20 20 20 20 20 da db 2f d8 2f  /...........././
100430: 2f ef 2f da db 20 20 20 20 20 20 da db 2f 2f 2f  /./..........///
@end example

This cartridge has one banking register at $fe00.

@c @node FIXME
@subsection CBM2 Cartridge Specifics

@b{TODO}

@c @node FIXME
@subsubsection 0 - generic cartridge

@b{TODO}


@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/v4, RSID v3/v4) and LaLa (assembled most of the following text)
and last not least tweaked a bit by Groepaz to fit into the VICE documentation.

The original documentation maintained by the HVSC team can be found here:
 @uref{http://www.hvsc.de/download/C64Music/DOCUMENTS/SID_file_format.txt}

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/v4 and RSID v3/v4 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, 3 and 4 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.

See section "The SID file environment" below for the default C64 power-on
environment for each SID file format.

@example
+04    WORD version
@end example

Available version number can be 0001, 0002, 0003 or 0004. Headers of version 2, 3 and 4
provide additional fields. RSID and PSID v2NG files must have 0002, 0003 or 0004 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, 3 and 4.

@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, 3 and 4 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, 3 and 4 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, v3 and v4

Version 2, 3 and 4 of the header incorporates the v1 header fields and provides
additional fields. Some of these are actually v2NG, v3 or v4 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, v4)
  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

If bits 6-7 are set to Unknown then the second SID will be set to the same SID
model as the first SID.

This is a v3 specific field.

@itemize
@item Bits 8-9 specify the SID version (sidModel) of the third SID:
  00 = Unknown,
  01 = MOS6581,
  10 = MOS8580,
  11 = MOS6581 and MOS8580.
@end itemize

If bits 8-9 are set to Unknown then the third SID will be set to the same SID
model as the first SID.

This is a v4 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-9 in 'flags' are used as stated above.

@itemize
@item Bits 10-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 thirdSIDAddress
@end example

This is a v4 specific field. For v2NG and v3, it should be set to 0.

This is an 8 bit number indicating the address of the third 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 third SID
is used, like $00.
The address of the third SID cannot be the same as the second SID.

@example
+7C    <data>
@end example

Version 2, 3 and 4 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 @node FIXME
@subsection The SID file environment

Before the data of a SID file is loaded in memory of a C64, certain addresses
and chips must be initialized in order to play the SID tune correctly.

For RSID and PSID files the following address must be set:

@multitable @columnfractions .3 .7
@item $02A6
@tab depending on the PAL/NTSC flag in the SID file header, it is set to
0x01 for PAL and set to 0x00 for NTSC.
@end multitable

The default C64 environment for PSID files is as follows:

@multitable @columnfractions .3 .7
@item VIC
@tab IRQ set to any raster value less than 0x100. Enabled when speed
 flag is 0, otherwise disabled.
@item CIA 1 timer A
@tab set to 60Hz (0x4025 for PAL and 0x4295 for NTSC) with the
counter running. IRQs active when speed flag is 1, otherwise
IRQs are disabled.
@item Other timers
@tab disabled and loaded with 0xFFFF.
@end multitable

When the init and play addresses are called the bank register value must be
written for every call and the value is calculated as follows:

@example
if   address < $A000  -> 0x37 // I/O, Kernal-ROM, Basic-ROM
else address < $D000  -> 0x36 // I/O, Kernal-ROM
else address >= $E000 -> 0x35 // I/O only
else                  -> 0x34 // RAM only
@end example

The default C64 environment for RSID files is as follows:

@multitable @columnfractions .3 .7
@item VIC
@tab IRQ set to raster 0x137, but not enabled.
@item CIA 1 timer A
@tab set to 60Hz (0x4025 for PAL and 0x4295 for NTSC) with the
counter running and IRQs active.
@item Other timers
@tab disabled and loaded with 0xFFFF.
@item Bank register
@tab 0x37
@end multitable

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

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

@item If the C64 BASIC flag is set, the value at $030C must be set with the song
number to be played (0x00 for song 1).
@end itemize

@c @node FIXME
@section The Swaplist (.vfl, .lst) file format

"Swaplist" or "Fliplist" files contain filenames of (mostly) disk images that
belong to a program (game/demo) so the can be easily swapped/changed by a button
press. They were first introduced by VICE, and have since then been adopted and
expanded by other devices. This is an attempt to unify the efforts and create a
standard for a format that will work with all OSs and across all devices that
can use these files, so eg a SD-Card containing a software collection will work
with all of them.

@c @node FIXME
@subsection general

The format itself is pretty straightforward and almost trivial: it is simply a
text file containing one filename per line.

@itemize
@item Each line contains a filename. Depending on the device or emulator, this does
  not necessarily have to be a disk image (see below). Filenames can contain a
  full (absolute) or relative (to the swaplist file) path, or no path at all.

  Note that path notation is device- and/or OS specific and not portable - for
  that reason it is probably a good idea to not put pathes into these files
  unless absolutely necessary.

  What happens when a (non comment) line contains an invalid/non existing file
  name is undefined and implementation specific (see below)

@item Blank lines are ignored, and parsing is tolerant of varying line?endings (any
  occurrences and/or combination of 0x0a and/or 0x0d constitutes a line-ending)

@item Any line starting with a semicolon (;) is a comment and will be skipped. Any
  device specific extensions should be implemented in comment lines, so other
  devices will always skip them.
@end itemize

@c @node FIXME
@subsection extensions

Some devices introduced custom extensions on the format, which are considered
completely optional. Most notable is the #PETSCII tag introduced by sd2iec,
which parsers that don't support it should simply ignore.

Details on the various devices/emulators that support swaplists follow:

@c @node FIXME
@subsubsection VICE

@itemize
@item Until 3.5, VICE used to write "# Vice fliplist file" to the first line of the
  file. To make the created files more universal, this was changed to use the
  new comment line delimiter in 3.5 r40450, ie "; Vice fliplist file"

@item A line containing ";UNIT X" indicates that the following files belong to the
  drive X (This used to be "UNIT X" before 3.5 r40481). When the swaplist
  contains only files for one drive, this marker will not be created.

@item File names that are not readable (or do not exist) will be ignored/skipped

@item the sd2iec #PETSCII marker is recognized since VICE 3.5 r40450
@end itemize

After 3.5 r40450 VICE will still accept (read) files in the old format, but
only create files in the new, more compatible format.

@c @node FIXME
@subsubsection sd2iec

@itemize
@item The file names are parsed in the same way as the CD command, so you can
  include a path to the image if desired. Due to the way this feature is
  implemented you are not limited to a swap list containing just D64 images,
  M2I and even FAT directories will work too.

@item a file name including path can be max. 255 characters long

@item there can be max. 255 files in a swaplist

@item By default sd2iec assumes the swap file is encoded in ASCII. If the the first
  line of the file matches "#PETSCII" (in hex: $23 $50 $45 $54 $53 $43 $49 $49),
  filenames are assumed to be encoded in PETSCII instead.

@item When sd2iec finds an invalid/non existing file name, it will stop and indicate
  an error by blinking the LED
@end itemize

The comment delimiter (;) is recognized in firmware since April 22nd, 2021

@c @node FIXME
@subsubsection Chameleon

@itemize
@item as of now, filenames must _not_ contain a path component

@item a file name can be max. 255 characters long

@item since the files in the list are not "swapped" but immediately mounted, there
  can be max. 4 files in the list

@item d64 and g64 files are recognized, files with other extensions are skipped

@item the sd2iec #PETSCII marker is recognized
@end itemize

@c @node FIXME
@subsubsection pi1541

(some of the following needs more explanation and/or will perhaps change in the
future):

@itemize
@item Path can be relative or not and is in the format; [drive#:][/]directory/file

@item Comments are in the C programming style of // and /* */

@item All files will be ignored if they don't have an extension of the currently
  supported disk image (d64, g64, nib, nbz or t64). If the disk image fails to
  load then it will be ignored.

@item When a file is found where the file name does not end with a supported disk
  extension the file name will be compared to the list of ROM file names that
  have been specified inside of the Pi1541's options.txt file and if a match is
  found then that ROM will be used for that LST selection. If more than one has
  been specified inside the LST file then the last one encountered will be used.
@end itemize

@c @node FIXME
@subsection Examples

example: barebones minimal swaplist
@example
FOO.D64
BAR.D64
BAZ.D64
@end example

example: simple VICE fliplist
@example
; Vice fliplist file
FOO.D64
BAR.D64
BAZ.D64
@end example

example: VICE fliplist for multiple drives + comments
@example
; Vice fliplist file
;UNIT 8
FOO.D64
BAR.D64
BAZ.D64
;UNIT 9
FUU.D64
BOR.D64
BOZ.D64
; don't forget this one
;UNIT 10
BUZ.D64
@end example

example: sd2iec style pathes + comment
@example
//NEATGAME/:DISK1A.D64
//NEATGAME/:DISK1B.D64
//NEATGAME/:DISK2A.D64
//NEATGAME/:DISK2B.D64
; save disk in separate directory for easier backup
//SAVEDISKS/:NEATGAME.D64
@end example

@c section used in file generation, keep to the format used.
@node Acknowledgments
@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{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. Added multi-
threaded GUI display for *nix. 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 SID cartridge
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. Added the
65816 emulation. Added native screenshot (koala/doodle)
support. Added 6502/6510/8500/8502 cpu port unused bit fading.
Added vice.chm (windows), vice.guide (amiga), vice.hlp
(windows), vice.inf (os/2), vice.pdf (generic) and vice.txt
documentation generation. Added Android port based on
'AnVICE 1.0.5'. Improved/fixed the 'in-source' FFMPEG support
and fixed it for msvc7.0 and up. Generalized the 'RS232 net'
support to be able to be used on any network supporting arch.
Started the SDL2 port. Added generic sampler input support.
Added new joyport system and converted the joystick, mouse and
lightpen code to use the new system. Added joyport attached
rtc (bbrtc). Added joyport attached cardkey keypad. Added
joyport attached coplin keypad. Added joyport attached atari
cx21 keypad. Added joyport attached atari cx85 keypad. Added
joyport attached paperclip 64 dongle. Added joyport attached
rushware keypad. Added joyport attached 2/4 bit samplers. Added
vic20 I/O-2 and I/O-3 RAM support. Added the c64 cp/m (z80)
cartridge. Added IDE64 digimax short bus device emulation.
Added tapeport system and the tapelog, cp-clockf83, tape-sense
dongle, and (not yet working) dtl basic dongle devices. Added
easy calc result cartridge emulation. Added hardware SID I/O
access system which allows CW3, HardSID, ParSID and SSI2001 to
work on AmigaOS, BeOS, DOS, SDL, *nix and windows with and
without device drivers. Added clockport system for mmc64,
mmcreplay, retroreplay and ide64. Added rrnet clockport device.
Added mp3@@64 clockport device. Added userport snes pad (petscii)
support. Extended the joyport system to be able to handle all snes
pad buttons. Extended the joyport system to be able to handle
8-player joystick adapters. Added spaceballs joystick adapter
support. Added trapthem joyport snes pad adapter support. Added
superpad64 support. Added multijoy joystick adapter support.
Added inception joystick adapter support. Added protopad support.
Added autofire support. Added plus4 Synergy 3-port joystick
adapter support. Added userport I/O simulation device. Added
Microflyte analog joystick support. Added Stupid Pet Tricks
joystick adapter support. 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. Made some monitor fixes. Fixed some
tape code issues.

@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.
Improved the GTK3 GUI. Added x64(sc), x128, x64dtv, xplus4, xvic model
selection system. Added KoalaPad emulation. Added keyrah keymaps.
Added joystick keys mapping to the keymap system. CIA emulation
improvements. Added basic support for compute gazette sidplayer
files (mus/str) to vsid. Added new palette files. Added
'available features' code. Fixed/added some items in the OSX GUI.
Added random tape wobble emulation. Added 64KiB RGCD cartridge
emulation. Added psid v4 3sid support to vsid. Added single frame
advance. Added drive RPM and wobble support. Added rrnet mk3
emulation. Added GMod2 and GMod3 cartridge emulation. Added xvic BehrBonz
cartridge emulation. Added VICII VSP-bug emulation. Wrote alot of
test programs. Updated this document after a long period of
outdated mess. And various fixes and improvements.

@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.
Added PET HRE (High Res Emulator) board emulation. Added the
2-chip colour board for the Universal PET mainboard. Added
support for 'printer/plotter' Commodore 1520.

@item
@b{Marcus Sutton}
Made some console, dialog and joystick fixes for the BeOS port.
Maintains the BeOS port. Added some GTK2 fixes. Fixed some PET model
selection issues. Revived the Windows NT Unicode 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. Added DAC high pass filtering. Added the xscpu64
emulator. Added scroll wheel support for the Micromys mouse emulation.
Added Swiss ROM support to x128. Added IDE64 USB server emulation. Added
1540 drive emulation. Improved monitor support. Improved vdrive
compatibility. Added godot screenshot support. And fixed various issues.

@item
@b{AreaScout}
Fixed the SDL2 port. Revived the Android port. Maintains the SDL1,
SDL2 and Android ports.

@item
@b{Bas Wassink}
Fixed some gtk2/3 issues. Fixed t64 file handling. Fixed memory
leaks. Added more doxygen documentation. Fixed c1541 issues.
Updated the Linux-Native-Howto.txt file. Added autoconf, automake and
yasm version checking. Fixed runtime linker path issues with *BSD. Fixed
out-of-tree building. One of the driving forces behind the GTK3 port.

@item
@b{Michael C. Martin}
One of the driving forces behind the GTK3 port.

@item
@b{June Tate-Gans}
Made the dual window feature for the SDL2 UI.

@item
@b{Pablo Roldan}
Contributed improvements and fixes to the RS-232 emulation. Contributed
initial patch for VIC-II PAL-N model selection.

@end itemize

Former/inactive team members:

@itemize @bullet

@item
@b{BSzili}
Provided many amigaos4 fixes. Maintained the amigaos based and derived
ports.

@item
@b{Errol Smith}
Improved VDC emulation. Improved MPS803 printer emulation.

@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{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.
Improved the FFMPEG support and started the 'in-source'
FFMPEG support/merge. Wrote test programs. Various
bug(fixe)s. ;-)

@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, fixed some GTK2
issues, 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. Added RSID BASIC tunes support to vsid. Several ReSID
fixes and improvements.

@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-2017
Provided the Danish user interface translations and fixed a few monitor bugs.

@b{Martin Pottendorfer}
Copyright @copyright{} 2000-2017
Provided the German user interface translations.

@b{Manuel Antonio Rodriguez Bas}
Copyright @copyright{} 2011-2017
Provided the Spanish user interface translations.

@b{Paul Dubé}
Copyright @copyright{} 2004-2017
Provided the French user interface translations.

@b{Czirkos Zoltan}
Copyright @copyright{} 2006-2017
Provided the Hungarian user interface translations.

@b{Karai Csaba}
Copyright @copyright{} 2006-2017
Provided the Hungarian user interface translations.

@b{Andrea Musuruane}
Copyright @copyright{} 2001-2017
Provided the Italian user interface translations.

@b{Jesse Lee}
Copyright @copyright{} 2011-2016
Provided the Korean user interface translations.

@b{Marco van den Heuvel}
Copyright @copyright{} 2005-2017
Provided the Dutch user interface translations.

@b{Jarek Sobolewski}
Copyright @copyright{} 2011-2017
Provided the Polish user interface translations.

@b{Michael Litvinov}
Copyright @copyright{} 2010-2017
Provided the Russian user interface translations.

@b{Peter Krefting}
Copyright @copyright{} 2000-2017
Provided the Swedish user interface translations.

@b{Emir Akaydin}
Copyright @copyright{} 2008-2017
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{Alexis Ballier}
Provided some ffmpeg fixes.

@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{Anthony J. Bentley}
Provided some man page fixes.

@item
@b{Eliseo Bianchi}
Provided the italian Amiga translations.

@item
@b{Enrico Bruttomesso}
Improved some italian translations.

@item
@b{Frank Buss}
Provide some midi fixes.

@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{Hans Deragon}
Added support for dead keys in X11.

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

@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. Some drive sound
fixes. Fixed some windows drag'n'drop issues. Fixed some
monitor code issues.

@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. Fixed some network code
issues. Fixed some monitor issues. Provided some SDL
port fixes.

@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. Added Inkwell
Systems lightpen support. Fixed some monitor code
issues. Provided some windows port fixes. Provided some
SDL port fixes.

@item
@b{Michael Klein}
Fixed some MacOSX code issues. 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. Provided some windows
fixes. Provided some gtk port fixes. Provided some SDL port
fixes.

@item
@b{Lioncash}
Provided some c1541 fixes. Fixed some 'geninfocontrib' helper tool
issues. Fixed some 'embedded' build issues. Fixed some memory leaks.

@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{lvd}
Provided some monitor fixes.

@item
@b{Marko Mäkelä}
Wrote lots of CPU documentation. Wrote the VIC Flash Plugin
cartridge emulation in xvic. Wrote the Ultimem cartridge
emulation in xvic.

@item
@b{mar77i}
Fixed some resource handling issues.

@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{Robert W. McMullen}
Provided parts of the widget set for implementing the Xaw GUI.

@item
@b{Jennifer Medkief}
Was 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{mjhn}
Provided some *nix 'readme' fixes.

@item
@b{Moiree}
Provided some command line fixes. Improved the build system. Fixed
some vsid bugs. Fixed some SDL GUI issues. Fixed some documentation
items.

@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 in vdrive. Added Lt. Kernal Host Adaptor,
CMD HD, CMD RAMLINK, and CBM D9090/60 emulation. Added D90 support to vdrive.

@item
@b{Leandro Nini}
Improved ReSID emulation. And fixed some c64dtv cpu opcode issues.

@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{Stein Pedersen}
Fixed windows midi driver for 64bit windows.

@item
@b{Helfried Peyrl}
Supplied a patch that fixes REL file records larger 256 bytes
when using vdrive.

@b{Christopher Phillips}
Fixed and improved some Mac OS X gui items.

@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{Peter Rittwage}
Made 1541 GCR hardware tests.

@item
@b{David Roden}
Fixed various issues related to ffmpeg settings.

@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{Michael Steil}
Provided some c1541 fixes.

@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{TMLPiper}
Provided fixes for the osx port.

@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{vonred}
Added multiple monitor support to the windows port.

@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{David Wood}
Provided some monitor fixes.

@item
@b{Count Zero}
Fixed some monitor issues.

@item
@b{Bjoern Odendahl}
Created the new VICE logo and volunteered to create new icons.

@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, David Horrocks, Benjamin Rosseaux and William McCabe
for writing cool emulators to compete with.  @t{:-)}

@c end of file generation section.
@node Copyright
@chapter Copyright

@itemize @bullet
@item
Copyright @copyright{} 1999-__VICE_CURRENT_YEAR__ Martin Pottendorfer
@item
Copyright @copyright{} 2005-__VICE_CURRENT_YEAR__ Marco van den Heuvel
@item
Copyright @copyright{} 2007-__VICE_CURRENT_YEAR__ Fabrizio Gennari
@item
Copyright @copyright{} 2009-__VICE_CURRENT_YEAR__ Groepaz
@item
Copyright @copyright{} 2009-__VICE_CURRENT_YEAR__ Errol Smith
@item
Copyright @copyright{} 2009-__VICE_CURRENT_YEAR__ Ingo Korb
@item
Copyright @copyright{} 2010-__VICE_CURRENT_YEAR__ Olaf Seibert
@item
Copyright @copyright{} 2011-__VICE_CURRENT_YEAR__ Marcus Sutton
@item
Copyright @copyright{} 2011-__VICE_CURRENT_YEAR__ Kajtar Zsolt
@item
Copyright @copyright{} 2016-__VICE_CURRENT_YEAR__ AreaScout
@item
Copyright @copyright{} 2016-__VICE_CURRENT_YEAR__ Bas Wassink
@item
Copyright @copyright{} 2017-__VICE_CURRENT_YEAR__ Michael C. Martin
@item
Copyright @copyright{} 2018-__VICE_CURRENT_YEAR__ Christopher Phillips
@item
Copyright @copyright{} 2019-__VICE_CURRENT_YEAR__ David Hogan
@item
Copyright @copyright{} 2020-__VICE_CURRENT_YEAR__ Empathic Qubit
@item
Copyright @copyright{} 2020-__VICE_CURRENT_YEAR__ Roberto Muscedere
@item
Copyright @copyright{} 2021-__VICE_CURRENT_YEAR__ June Tate-Gans
@item
Copyright @copyright{} 2021-__VICE_CURRENT_YEAR__ Pablo Roldan

@item
Copyright @copyright{} 2011-2016 Stefan Haubenthal
@item
Copyright @copyright{} 2015-2016 BSzili
@item
Copyright @copyright{} 1999-2016 Andreas Matthies
@item
Copyright @copyright{} 2007-2015 Daniel Kahlin
@item
Copyright @copyright{} 2012-2014 Benjamin 'BeRo' Rosseaux
@item
Copyright @copyright{} 2011-2014 Ulrich Schulz
@item
Copyright @copyright{} 2011-2014 Thomas Giesel
@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
@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.
@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{https://sourceforge.net/p/vice-emu/bugs/}.
@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 libera.chat.

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!). Be patient when your
mail does not show up on the mailing list - it is moderated manually. Once your
mail shows up you should be approved and be able to send mail without further
delay.

@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});
@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. It should be very easy to find them using your favourite search
engine.

@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, , 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. Get it with the command:
@example
@samp{svn checkout svn://svn.code.sf.net/p/vice-emu/code/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;
@end itemize

Preferably post your patch on the tracker:
@uref{https://sourceforge.net/p/vice-emu/patches/}.

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 Concept Index
@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
