vice.texi

\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename vice.info
@settitle VICE Manual
@c %**end of header

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

@c global options
@setchapternewpage on
@firstparagraphindent none
@paragraphindent 0
@exampleindent 0

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

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

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

@ifinfo
VICE Manual

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

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

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

@end ifinfo

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

@titlepage

@title VICE, the Versatile Commodore Emulator

@c page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2014 Dag Lem
Copyright @copyright{} 1999-2014 Andreas Matthies
Copyright @copyright{} 1999-2014 Martin Pottendorfer
Copyright @copyright{} 2005-2014 Marco van den Heuvel
Copyright @copyright{} 2006-2014 Christian Vogelgsang
Copyright @copyright{} 2007-2014 Fabrizio Gennari
Copyright @copyright{} 2007-2014 Daniel Kahlin
Copyright @copyright{} 2008-2014 Antti S. Lankila
Copyright @copyright{} 2009-2014 Groepaz
Copyright @copyright{} 2009-2014 Ingo Korb
Copyright @copyright{} 2009-2014 Errol Smith
Copyright @copyright{} 2010-2014 Olaf Seibert
Copyright @copyright{} 2011-2014 Marcus Sutton
Copyright @copyright{} 2011-2014 Ulrich Schulz
Copyright @copyright{} 2011-2014 Stefan Haubenthal
Copyright @copyright{} 2011-2014 Thomas Giesel
Copyright @copyright{} 2011-2014 Kajtar Zsolt
Copyright @copyright{} 2012-2014 Benjamin 'BeRo' Rosseaux

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

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

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

@end titlepage

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

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

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

@ifinfo

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

@end ifinfo

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

* Preface::                     Fundamental concepts.

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

* Basics::                      Simple things you can do.

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

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

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

* File formats::                Technical description of file formats.

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

* Concept Index::
* Resource Index::
@end menu

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

@center Version 2, June 1991

@display
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.  675
Mass Ave, Boston, MA 02111-1307, USA

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

@unnumberedsec Preamble

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@page
@unnumberedsec How to Apply These Terms to Your New Programs

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

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

@smallexample
@var{one line to give the program's name and an idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

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

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

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

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

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

@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
@end smallexample

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

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

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

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

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

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

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

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

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

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

@emph{Notice:} This documentation is written for the Unix release of VICE.

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


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

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

The fast C64 emulator, called @samp{x64}, features a fairly complete
emulation of the VIC-II video chip: sprites, all registers and all video
modes are fully emulated.  The emulation has been fully cycle-accurate
since version 0.13.0.

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

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

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


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

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

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


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

The C128 emulator, called @samp{x128}, features a complete emulation of
the internal MMU (@dfn{Memory Management Unit}), 80 column VDC screen, fast
IEC bus emulation, 2 MHz mode, Z80 emulation plus all the features of the
C64 emulation.


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

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

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

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


@node PET emulator features, CBM-II emulator features, VIC20 emulator features, Preface
@section PET emulator features

The PET emulator emulates the 2001, 3032, 4032, 8032, 8096, 8296 and
SuperPET (MicroMainFrame 9000) models, covering practically the whole series.
The hardware is pretty much the same in each and that is why one single
program is enough to emulate all of them.  For more detailed information
about PET hardware please refer to the @file{PETdoc} file.
@c FIXME: add link to doc/html/plain/PETdoc.txt

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

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

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

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

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

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

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

Moreover, the secondary addresses used are now @code{0} and @code{1} for
load and save, respectively, and not arbitrary unused secondary
addresses.

To select which model to run, specify it on the
command line with the @code{-model MODEL} option, where
@code{MODEL} can be one of a list of PET model numbers, all
described in @pxref{PET model}
@c FIXME: add link to section


@node CBM-II emulator features, SCPU64 emulator features, PET emulator features, Preface
@section CBM-II emulator features

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

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

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

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

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

The different settings are described in @pxref{CBM-II model}.

@node SCPU64 emulator features, Keyboard emulation, CBM-II emulator features, Preface
@section SCPU64 emulator features

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

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

Still to do:

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

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

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

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

@node Keyboard emulation, Joystick emulation, SCPU64 emulator features, Preface
@section The keyboard emulation

There are two ways of emulating the keyboard in VICE.

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

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

@c FIXME: add a detailed list of all keys

The second way (@dfn{positional mapping}) is to map every key on the
``real'' keyboard to the key which has the same position on the keyboard
of the emulated machine.  This way, no @key{Shift} key is forced by the
program (with the exception of the function keys @key{F2}, @key{F4},
@key{F6} and @key{F8}, which require @key{Shift} on the Commodore
keyboards), and the keyboard is more comfortable to use in those
programs (such as some games) that require the keys to be in the correct
positions.

@strong{Warning:} unlike the real C64, VICE ``presses'' the @key{Shift}
key @emph{together} with the key to shift when the @key{Shift} must be
forced.  In most cases this should work fine, but some keyboard routines
are quite picky and tend not to recognize the shift key because of this.
For instance, @kbd{F6} (which on the real C64 is obtained with
@kbd{Shift + F5}) could be recognized as @kbd{F5}.  In that case, use
the shift key manually (i.e., type @kbd{Shift + F5} in the example).
Yes, we know this is a bug.

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


@node Joystick emulation, Disk drive emulation, Keyboard emulation, Preface
@section The joystick emulation

Joysticks can be emulated both via the keyboard and via a real joystick
connected to the host machine (the latter only works on GNU/Linux
systems).

There are two keyboard layouts for joystick use, known as @dfn{numpad}
and @dfn{custom}.

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

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


@node Disk drive emulation, Supported file formats, Joystick emulation, Preface
@section The disk drive emulation

All the emulators support up to 4 external disk drives as
devices 8, 9, 10 and 11.  Each of these devices can emulate virtual
Commodore 1541, 1541-II, 1571, 1581, 2031, 2040, 3040, 4040, 1001, 8050 and
8250 drives in one of four ways:

@itemize @bullet
@item
using disk images, i.e., files that contain a dump of all the blocks
contained in a real floppy disk (if you want more information about
what a disk image is, consult the
@code{comp.emulators.cbm} FAQ);
@item
accessing file system directories, thus giving you the use of files
without having to copy them to disk images; this also allows you to
read and write files in the @code{P00} format (again, consult the
@code{comp.emulators.cbm} FAQ for more info).
@item
accessing a real device connected to the host machine. As of VICE 1.11
it is possible to connect real drives like Commodore 1541 to the
printer port of the host using the XA1541 or XM1541 cable. Currently
this only works on Linux or Windows using the OpenCBM library. You can
get it from @uref{http://www.lb.shuttle.de/puffin/cbm4linux} (cbm4linux,
Linux version) or from @uref{http://cbm4win.sf.net/} (cbm4win, Windows
version).

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

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

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

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

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

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

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

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

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

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

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

VICE supports the most popular Commodore file formats:

@itemize @bullet

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

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

@item
@code{P64} NRZI flux pulse disk image files

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

@item
@code{D71} VC1571 disk image format

@item
@code{D81} VC1581 disk image format

@item
@code{D80} CBM8050 disk image format

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

@item
@code{D1M} FD2000/FD4000 DD disk image format

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

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

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

@item
@code{P00} program files

@item
@code{CRT} C64 cartridge image files

@end itemize

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

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

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

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

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

@node Common problems,  , Supported file formats, Preface
@section Common problems

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

@menu
* Sound problems::
* Shared memory problems::
* Printer problems::
* PET keyboard problems::
@end menu

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

VICE should compile and run without major problems on many UNIX systems,
but there are some known issues related to the sound driver.  In fact,
the sound code is the least portable part of the emulator and has not
yet been thoroughly tested on all the supported platforms.

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

@cindex HP-UX and Solaris audio problems
On the other hand, HP-UX and Solaris machines are known to cause
troubles.  If you think you can help debugging the code for these
systems, your help would be really appreciated.  We are having troubles
finding HP-UX and SUN consoles to work at@dots{}

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


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

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

Reasons for this failure could be:

@itemize @bullet
@item
IPC support has been disabled at the system level; some system
administrators disable this for security reasons.  If @emph{you} are the
system administrator, use a kernel that has IPC support compiled in and
enabled.
@item
You are attempting to run the emulator across the network (i.e., the
emulator runs on one machine, and the output is displayed on another
machine that works as an X terminal) and for some reason VICE does not
recognize this fact.  In this case, you have found a bug, so please report it
to us.
@end itemize

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

@node Printer problems, PET keyboard problems ,Shared memory problems, Common problems
@subsection Printer problems

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

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

@node PET keyboard problems, ,Printer problems, Common problems
@subsection PET keyboard problems

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

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

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

The names of the available emulators are:

@itemize @bullet

@item
@code{vsid}, the SID player

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

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

@item
@code{x64dtv}, the C64DTV emulator

@item
@code{x128}, the C128 emulator

@item
@code{xvic}, the VIC20 emulator

@item
@code{xpet}, the PET emulator

@item
@code{xplus4}, the PLUS4 emulator

@item
@code{xcbm2}, the CBM-II emulator (CRTC models)

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

@item
@code{xscpu64}, the SCPU64 emulator

@end itemize

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

If you want to look at the log output, or use the monitor in a port which does
not have a dedicated monitor UI yet (such as the XAW port), you should always 
run them from a terminal window such as @code{xterm} or @code{rxvt}.  For example, 
you could do

@example
xterm -e x64
@end example


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

@node Command-line initialization, Command-line autostart, Usage, Usage
@section Command-line options used during initialization

There are several options you can specify on the command line.  Some of
them are used to specify emulation settings and will be described in
detail later (@pxref{Settings and resources} for a complete list).  The
remaining options are used only to give usage information or to
initialize the emulator in some way:

@table @code
@cindex -help
@item -help
@cindex -?
@itemx -?
List all the available command-line options and their meaning.
@cindex -default
@item -default
Set default resources (@pxref{Settings and resources}).  This will
override all the settings specified before, but not the settings
specified afterwards on the command line.
@cindex -config
@item -config <filename>
Specify config file
@cindex -logfile
@item -logfile <name>
Specify log file name
@cindex -verbose
@item -verbose
Enable verbose log output.
@cindex -keybuf
@item -keybuf <string>
Put the specified string into the keyboard buffer.
@cindex -console
@item -console
Console mode (for music playback)
@cindex -chdir
@item -chdir <directory>
Change the working directory.
@cindex -autostart
@item -autostart IMAGE
Autostart @file{IMAGE} (@pxref{Command-line autostart}).
@cindex -autoload
@item -autoload <name>
Attach and autoload tape/disk image <name>
@cindex -basicload, +basicload
@item -basicload
On autostart, load to BASIC start (without ',1')
@item +basicload
On autostart, load with ',1'
@cindex -autostartwithcolon, +autostartwithcolon
@item -autostartwithcolon
On autostart, use the 'RUN' command with a colon, i.e., 'RUN:'
@item +autostartwithcolon
On autostart, do not use the 'RUN' command with a colon; i.e., 'RUN'
@cindex -autostart-handle-tde, +autostart-handle-tde
@item -autostart-handle-tde
@itemx +autostart-handle-tde
Handle/Do not handle True Drive Emulation on autostart
@cindex -autostart-warp, +autostart-warp
@item +autostart-warp
Enable/Disable warp mode during autostart
@cindex -autostartprgmode
@item -autostartprgmode
Set autostart mode for PRG files
@cindex -autostartprgdiskimage
@item -autostartprgdiskimage
Set disk image for autostart of PRG files

@cindex -autostart-delay-random, +autostart-delay-random
@item -autostart-delay-random
@itemx +autostart-delay-random
Enable/Disable random delay on autostart
@cindex -autostart-delay
@item -autostart-delay <value>
Set initial autostart delay (0: use default)

@cindex -1
@item -1 NAME
Attach @file{NAME} as a tape image file.
@cindex -8
@item -8 NAME
@cindex -9
@itemx -9 NAME
@cindex -10
@itemx -10 NAME
@cindex -11
@itemx -11 NAME
Attach @file{NAME} as a disk image to device 8, 9, 10 or 11.

@cindex -attach8ro
@cindex -attach9ro
@cindex -attach10ro
@cindex -attach11ro
@item -attach8ro
@itemx -attach9ro
@itemx -attach10ro
@itemx -attach11ro
Attach disk image for drive #8-11 read only
@cindex -attach8rw
@cindex -attach9rw
@cindex -attach10rw
@cindex -attach11rw
@item -attach8rw
@itemx -attach9rw
@itemx -attach10rw
@itemx -attach11rw
Attach disk image for drive #8-11 read write (if possible)

@end table


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

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

@example
x64 lovelygame.x64.gz
@end example

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

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

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

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

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

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

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


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

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

@itemize @bullet

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

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

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

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

@end itemize

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

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

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

For example, if you have the C64 emulator installed in

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

then the value will be

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

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

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

System files can still be installed in a different directory if you
specify a complete path instead of just a file name.  For example, if
you specify @file{./kernal} as the kernal image name, the kernal image
will be loaded from the current directory.  This can be done by using
command-line options or by modifying resource values (@pxref{Resource
files}).

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

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

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

@itemize @bullet

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

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

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

@end itemize

The C128 needs the following files:

@itemize @bullet

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

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

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

@end itemize

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

@itemize @bullet

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

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

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

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

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

@item
@file{dos4000}, the 4000 drive ROM (32 Kbytes)

@end itemize

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

@itemize @bullet

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

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

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

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

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

@end itemize

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

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

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

@itemize @bullet

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

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

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

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

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

The PETs also have sockets for extension ROMs for the addresses
$9000-$9FFF, $A000-$AFFF and $B000-$BFFF (the last one for PET2001 and
PET3032 only).  You can specify ROM image files for those extensions
command line options @code{-petrom9}, @code{-petromA} and
@code{-petromB} resp.

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

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

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

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

@itemize @bullet

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

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

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

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

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

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

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

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

@end itemize

The SCPU64 needs the following files:

@itemize @bullet

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

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

@end itemize

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

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

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

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

@example
KEYSYM ROW COLUMN SHIFTFLAG
@end example

Where:

@itemize @bullet

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

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

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

@itemize @bullet

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

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

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

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

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

@end itemize

@end itemize

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

@example
F2 0 4 1
@end example

where @code{0} and @code{4} identify the key (row 0, column 4 on the
keyboard matrix), and @code{1} specifies that every time the user presses
@key{F2} the shift key on the C64 keyboard must be pressed.

There are also some special commands you can put into the keyboard file;
they are recognized because they start with an exclamation mark:

@itemize @bullet

@item
@code{!CLEAR} clears the currently loaded keyboard map; it is
necessary to put this at the beginning of the file if you want the
keymap file to override all of the current internal settings;

@item
@code{!LSHIFT}, @code{!RSHIFT}, followed by a row and a column
value, specify where the left and right shift keys are located on the
emulated keyboard; for example, C64 default keymaps will specify

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

@end itemize

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

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


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

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

@example
RED GREEN BLUE DITHER
@end example

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

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

Lines starting with the @code{#} sign are completely ignored.  This is
useful for adding comments (such as color names) within the palette
file.

For example, the default PET palette file (which has only two colors, 0 for
background and 1 for foreground), looks like the following:

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

# Background
00 00 00 0

# Foreground
00 FF 00 F
@end example

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

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

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

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

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

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

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

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


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

@node Emulation window, Menus, Basics, Basics
@section The emulation window

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

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

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

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

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

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

Sometimes commands can be reached via @dfn{shortcuts} or @dfn{hotkeys},
i.e., it is possible to execute them by pressing a sequence of keys
instead of going through the menu with the mouse.  Where shortcuts
exist, they are displayed in parentheses at the right edge of the menu
item.  In VICE, all shortcuts must begin with the @key{Meta} or
@key{Alt} key.  So, for example, to attach a disk image to drive #8 (the
corresponding menu item displays ``M-8''), you have to press the
@key{Meta} (or @key{Alt}) and then @key{8}.

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


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

At any time, if you get stuck or do not remember how to perform a
certain action, you can use the ``Browse manuals'' command (left button
menu).  This will popup a browser and open the HTML version of this
documentation.  Notice that this requires VICE to be properly (and
fully) installed with a @samp{make install}.

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


@node File Selector, Disk and tape images, Help, Basics
@section Using the file selector

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

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

At the top, there is a @dfn{directory box}, with the complete path of
the current directory, and a @dfn{file name box}, with the name of the
currently selected file.  At the bottom there are two buttons: ``OK''
confirms the selected file and ``Cancel'' abandons the file selector
without cancelling the operation.

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


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

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

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

@itemize @bullet

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

@end itemize

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

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

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

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

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

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

It is possible to examine the directory of a disk or tape image before
attaching it.  Just press the ``Contents'' button in the file selector
window and a new window will pop up with the contents of the selected
image.

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


@node Autostart, Compressed files, Previewing contents, Disk and tape images
@subsection ``Autostarting'' an image

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

Notice that, if true drive emulation is turned on, it will be turned off
before running the program and then turned on again after it has been
loaded.  This way, you get the maximum possible speed while loading the
file, but you do not lose compatibility once the program itself is
running.

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


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

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

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

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

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

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

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

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

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

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

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


@node Reset,  , Disk and tape images, Basics
@section Resetting the machine

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

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

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

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

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

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

In the VICE emulators, all the settings are stored in entities known as
called @dfn{resources}.  Each resource has a name and a value which may
be either an integer or a string.  Integer values are often used as
boolean values with the usual convention of using zero for ``false''
and any other value for ``true''.

Resource values can be changed via the right-button menu (the
@dfn{settings} menu), via command-line options or via the @dfn{resource
file}.

The @dfn{resource file} is a human-readable file containing resource
values: it is called @file{vicerc} and is stored in the directory
@file{.vice/} in the user's home
directory.  It is possible to dump the current values of the resources
into that file or load the values stored into that file as the current
values, at any time.  This is achieved with the ``Save settings'' and
``Load settings'' right menu items.  A third menu item, ``Restore
Default Settings'', can be used to reset all the values to the factory
defaults.

A special resource, @code{SaveResourcesOnExit}, if set to a non zero
value, causes the emulator to ask you if you want to save the current
(changed) settings before exiting, and can be toggled with the ``Save
settings on exit'' command from the right-button menu.

Notice that not all the resources can be changed from the menus; some of
them can only be changed by manually modifying the resource file or by
using command-line options.

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

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

@node Resource files, Resources and command-line, Settings and resources, Settings and resources
@section Format of resource files

A resource file is made up of several sections; sections have the
purpose of separating the resources of a certain emulator from the ones
of the other emulators.  A section starts with the name of an
emulator in brackets (e.g., @samp{[C64]}) and ends when another section
starts or when the file ends.

Every line in a section has the following format:

@example
RESOURCE=VALUE
@end example

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

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

@example
[VIC20]
HTMLBrowserCommand="netscape %s"
SaveResourcesOnExit=0
FileSystemDevice8=1
FSDevice8ConvertP00=1
FSDevice8Dir="/home/ettore/cbm/stuff/vic20p00"
FSDevice8SaveP00=1
FSDevice8HideCBMFiles=1
[C64]
HTMLBrowserCommand="netscape %s"
SaveResourcesOnExit=1
FileSystemDevice8=1
FSDevice8ConvertP00=1
FSDevice8Dir="/home/ettore/cbm/stuff/c64p00"
FSDevice8SaveP00=1
FSDevice8HideCBMFiles=1
@end example

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

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

Resources can also be changed via command-line options.

Command-line options always override the defaults from @code{.vice/vicerc},
and their assignments last for the whole session.  So, if you specify a
certain command-line option that changes a certain resource from its
default value and then use ``Save Settings'', the value specified with
the command-line option will be saved back to the resource file.

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

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

@c @node FIXME
@section Autostart settings

@c @node FIXME
@subsection Autostart resources

@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.
@vindex AutostartBasicLoad
@item AutostartBasicLoad
Boolean, if true load to basic start using ,8 when autostarting.
@vindex AutostartRunWithColon
@item AutostartRunWithColon
Boolean, if true put a colon after the load command when autostarting.
@vindex AutostartHandleTrueDriveEmulation
@item AutostartHandleTrueDriveEmulation
Boolean, if true handle (enable/disable) True Drive Emulation on autostart.
@vindex AutostartWarp
@item AutostartWarp
Boolean, if true temporarily enable warp mode when autostarting
@vindex AutostartPrgMode
@item AutostartPrgMode
Integer specifying the autostart mode for prg files. (0: virtual filesystem,
1: inject to RAM, 2: copy to D64)
@vindex AutostartDelayRandom
@item AutostartDelayRandom
Boolean, enables a short random delay on autostart.
@vindex AutostartDelay
@item AutostartDelay
Integer specifying the maximum delay in frames.

@end table

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

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

@cindex Refresh rate
It is also possible to control the emulator's rate of frame update using
the ``Refresh rate'' setting; the value ranges from ``1/1'' (update 1/1
of the frames of the real machine, that is 50 frames per second) to
``1/10'' (update 1 every 10 frames) and can be changed via the ``Refresh
Rate'' submenu.  The ``Auto'' setting means to dynamically adapt the
refresh rate to the current speed of the host machine, making sure the
maximum speed specified by the via ``Maxium speed'' is always reached if
possible.  In any case, the refresh rate will never be worse than 1/10
if this option is specified.

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

@cindex Warp speed mode
Moreover, a special @dfn{warp speed} mode is provided and can be toggled
with the ``Enable Warp Mode'' menu item.  If this mode is enabled, it
will cause the emulator to disable any speed limit, turn sound emulation
off and use a 1/10 refresh rate, so that it will run at the maximum
possible speed.

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

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

@table @code

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

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

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

@end table


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

@table @code

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

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

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

@end table


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

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

@itemize @bullet

@cindex Video cache
@item
``Video Cache'' enables a video cache that can speed up the emulation
when little graphics activity is going on; it is especially useful when
you run the emulator on a networked X terminal as it can reduce the
network bandwidth required.  However, this setting can actually make the
emulator slower when there is little graphics activity and the amount of
work needed to maintain the cache is greater than the amount of work that
would be wasted by not using it (if any).

@cindex Double-size mode
@item
``Double Size'' toggles @dfn{double-size mode}, which makes the
emulation window twice as big.  When emulating a 80-column PET, only the
height is doubled, so that the aspect ratio is closer to that of the
real thing.

@cindex Double-scan mode.
@item
``Double Scan'' toggles @dfn{double-scan mode}, which causes the
emulator to draw only odd lines when running in double-size mode (this
saves some CPU time and also makes the emulation window look more like
an old monitor).

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

@end itemize


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

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

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

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

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

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

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

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

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

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

@code{Option         "DynamicTwinView" "False"}

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

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

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

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

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

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

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

The following resources affect the screen emulation.

@table @code

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

@vindex MITSHM
@item MITSHM
Integer specifying whether VICE should try to use the shared memory
extensions (MITSHM) when starting up.  The shared memory extensions make
things a lot faster but might not be available on your system.  You will
not be able to use these extensions if you are sitting at an X terminal
while running the emulator on a remote machine across a network.  Valid
values are: 0 = do not use MITSHM, 1 = do use MITSHM, -1 = try to
autodetect availability on startup (default).  The last is a simple test
if the emulator runs across a network and if so disables MITSHM (If you
have problems with this test please report it).

@vindex PrivateColormap
@item PrivateColormap
Boolean specifying whether VICE should install a private colormap at
startup.  This makes sense for 8-bit displays that could run out of
colors if other color-hungry applications are running at the same time.

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

@vindex UseFullscreen
@item UseFullscreen
Boolean specifying whether fullscreen mode is currently in use.
@vindex HwScalePossible
@item HwScalePossible
Boolean that indicates whether hardware scaling is possible or not.
@vindex openGL_sync
@item openGL_sync
Boolean, if true enable Open-GL frame sync.
@vindex openGL_no_sync
@item openGL_no_sync
Boolean, if true Open-GL sync is not available.
@vindex 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 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.
@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.

@end table


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

@table @code

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

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

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

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

@cindex -fullscreen, +fullscreen
@item -fullscreen
@itemx +fullscreen
Enable/disable fullscreen mode

@end table

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

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

The keyboard settings submenu also allows you to:

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


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

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

@table @code

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

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

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

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

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

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

@end table


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

@table @code

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

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

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

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

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

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

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

@end table

@c @node FIXME
@section Joystick settings

@c @node FIXME
@subsection Joystick resources

@table @code

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

@vindex JoyOpposite
@item JoyOpposite
Boolean, if true allow (usually impossible) bitcombinations for opposite directions.
@vindex ExtraJoy
@item ExtraJoy
Boolean, enables extra joysticks if true.
@vindex ExtraJoyType
@item ExtraJoyType
Integer specifying the type of adapter used for the extra joysticks. (0=Classical Games/
Protovision, 1=PET, 2=Hummer, 3=OEM, 4=Digital Excess/Hitmen, 5=Kingsoft, 6=Starbyte)

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

@vindex Lightpen
@item Lightpen
Boolean, enables lightpen emulation
@vindex LightpenType
@item LightpenType
Integer specifying the type of lightpen. (0=Pen with button Up, 1=Pen with button Left,
 2=Datel Pen, 3=Magnum Light Phaser, 4=Stack Light Rifle)

@vindex KeySet1NorthWest
@vindex KeySet1North
@vindex KeySet1NorthEast
@vindex KeySet1East
@vindex KeySet1SouthEast
@vindex KeySet1South
@vindex KeySet1SouthWest
@vindex KeySet1West
@vindex KeySet1Fire
@item KeySet1NorthWest
@itemx KeySet1North
@itemx KeySet1NorthEast
@itemx KeySet1East
@itemx KeySet1SouthEast
@itemx KeySet1South
@itemx KeySet1SouthWest
@itemx KeySet1West
@itemx KeySet1Fire
Integers specifying the keycodes for keyset 1.

@vindex KeySet2NorthWest
@vindex KeySet2North
@vindex KeySet2NorthEast
@vindex KeySet2East
@vindex KeySet2SouthEast
@vindex KeySet2South
@vindex KeySet2SouthWest
@vindex KeySet2West
@vindex KeySet2Fire
@item KeySet2NorthWest
@itemx KeySet2North
@itemx KeySet2NorthEast
@itemx KeySet2East
@itemx KeySet2SouthEast
@itemx KeySet2South
@itemx KeySet2SouthWest
@itemx KeySet2West
@itemx KeySet2Fire
Integers specifying the keycodes for keyset 2.

@vindex KeySetEnable
@item KeySetEnable
Boolean that specifies whether user defined keysets are enabled.

@end table

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

@table @code

@cindex -joydev1
@cindex -joydev2
@item -joydev1 <0-8>
@itemx -joydev2 <0-8>
Set the device for joystick emulation of port 1 and 2, respectively
(@code{JoyDevice1}, @code{JoyDevice2}).
@cindex -extrajoydev1
@cindex -extrajoydev2
@item -extrajoydev1 <0-8>
@itemx -extrajoydev2 <0-8>
Set device for extra joystick port 1 and 2.

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

@cindex -lightpen, +lightpen
@item -lightpen
@itemx +lightpen
Enable/Disable lightpen emulation
@cindex -lightpentype
@item -lightpentype <type>
Set lightpen type

@end table

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

The following menu items control sound output:

@itemize @bullet

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

@cindex Sound syncronization
@cindex Sound speed adjustment
@item
``Sound synchronization'' specifies the method for syncronizing the
sound playback.  Possible settings are:
@itemize @bullet
@item
``Flexible'', i.e., the audio renderer flexibly adds/removes samples to
the output to smoothly adapt the playback to slight changes in the speed
of the emulator.
@item
``Adjusting'' works like ``flexible'', but supports bigger differences
in speed.  For example, if the emulation speed drops down from from 100%
to 50%, audio slows down by the same amount too.
@item
``Exact'', instead, makes the audio renderer output always the same
sounds you would hear from the real thing, without trying to adapt the
ratio; to compensate the tolerances in speed, some extra frames will be
skipped or added.
@end itemize

@cindex Sample rate
@item
``Sample rate'' specifies the sampling frequency, ranging from 8000 to
48000 Hz (not all the sound cards and/or sound drivers can support all
the frequencies, so actually the nearest candidate will be chosen).

@cindex Audio buffer size
@cindex Sound buffer size
@item
``Buffer size'' specifies the size of the audio buffer; the bigger the
buffer, the longer the delay with which sounds are played.  You should
pick the smallest value your machine can handle without problems.

@cindex Sound suspend time
@item
``Sound suspend time'', will cause the audio playback to pause for the
specified number of seconds whenever some clicking happens.  If ``Keep
going'' is selected, no pausing is done.

@end itemize

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

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

@table @code

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

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

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

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

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

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

Implemented drivers are:

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

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

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

@vindex SoundRecordDeviceName
@item SoundRecordDeviceName
String specifying the filename used for sound recording.
@vindex SoundRecordDeviceArg
@item SoundRecordDeviceArg
String specifying additional arguments for sound recording.
@vindex SoundFragmentSize
@item SoundFragmentSize
Enum specifying the fragment size (0: small, 1: medium, 2: large)
@vindex SoundVolume
@item SoundVolume
Integer specifying the master volume in percent. [100] (0..100)s
@vindex SoundOutput
@item SoundOutput
Enum specifying how the type of sound output. Output is selectable between 'system' 
(system decides to use mono or stereo output based on the presence of a stereo sid), 
'always mono' (output is always mono, stereo streams are mixed into a mono stream) 
or 'always stereo' (output is always stereo, mono streams are multiplexed to a stereo 
stream). (0=system, 1=mono, 2=stereo)

@end table

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

@table @code

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

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

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

@cindex -soundoutput 
@item -soundoutput <output mode>
Sound output mode: (0: system decides mono/stereo, 1: always mono, 2: always stereo)

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

@cindex -soundfragsize
@item -soundfragsize <value>
Set sound fragment size (0 = small, 1 = medium, 2 = large)

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

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

@cindex -soundrecdev
@item -soundrecdev <name>
Specify recording sound driver
@cindex -soundrecarg
@item -soundrecarg <args>
Specify initialization parameters for recording sound driver

@end table

@c @node FIXME
@section Tape settings

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

@c @node FIXME
@subsection Tape resources

@table @code

@vindex DatasetteResetWithCPU
@item DatasetteResetWithCPU
Boolean specifying whether to reset (rewind) the tape when resetting the CPU.
@vindex DatasetteZeroGapDelay
@item DatasetteZeroGapDelay
Integer specifying the delay in cycles for a zero in the tap.
@vindex DatasetteSpeedTuning
@item DatasetteSpeedTuning
Integer specifying the number of cycles added to each gap in the tap.

@end table

@subsection Tape command-line options

@table @code

@cindex -dsresetwithcpu, +dsresetwithcpu
@item -dsresetwithcpu
@itemx +dsresetwithcpu
Enable/Disable automatic Datasette-Reset

@cindex -dszerogapdelay
@item -dszerogapdelay <value>
Set delay in cycles for a zero in the tap

@cindex -dsspeedtuning
@item -dsspeedtuning <value>
Set number of cycles added to each gap in the tap

@end table

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

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

The following settings affect both drives:

@itemize @bullet

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

@item
``Drive sync factor'' specifies the speed of the drive's CPU.  This can
be used to help loading certain programs that have trouble with the
default PAL setting (for example, programs designed for NTSC machines).
The ratio is calculated as follows:

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

where @code{clk_drive} and @code{clk_machine} are clock speeds in MHz.
The menu lets you choose between the PAL and NTSC values, and also lets
you specify whatever value you want.  Be careful when changing it,
though, because a wrong value can break things and even corrupt disk
images.

@end itemize

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

@itemize @bullet

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

@item
``Enable parallel cable'' enables emulation of a SpeedDOS parallel
cable; if you switch this option on and replace the original Commodore
ROMs with SpeedDOS-compatible ones, you can speed up loading/saving times.

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

@itemize @bullet
@item
@dfn{Skip cycles}: Each time the serial line is accessed by the C64, the
drive executes all the cycles since the last time it ran.  If
the number of elapsed cycles is larger than a certain value, the drive
discards part of them.
@item
@dfn{Trap idle}: The disk drive is still emulated upon serial line
accesses as with the previous option, but it is also always emulated at
the end of each screen frame.  If the drive gets into the DOS idle loop,
only pending interrupts are emulated to save time.
@item
@dfn{No traps}: Like ``Trap idle'', but without any traps at all.  So
basically the drive works exactly as with the real thing, and nothing is
done to reduce the power needs of the drive emulation.
@end itemize

The first option (``Skip cycles'') is usually best for performance, as
the drive is emulated as little as possible; on the other hand, you may
notice sudden slowdowns (when the drive executes several cycles at once)
and the LED status is never updated (because it would not be possible to
do correctly so).  Moreover, if the drive tries to get in sync with the
computer in some weird way and the computer does not access the serial
line for a long time, it is possible that some cycles are discarded and
the sync is lost.  Notice that this hack will have no effect on
performance if a program continuously reads from the IEC port, as the
drive will have to be fully emulated in any case (some stupid programs
do this, even when they don't actually need to use the drive).

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

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

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

@itemize @bullet
@item
``Never extend'' never extends disk images at all (so if a program tries
to write tracks beyond the 35th, it is not allowed to do so);
@item
``Ask on extend'' prompts the user as soon as a program tries to write
tracks beyond the 35th, and the user can then choose whether he wants
the disk image to be extended or not;
@item
``Extend on access'' simply extends the disk image as soon the program
needs it, without prompting the user.
@end itemize

@end itemize


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

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

@table @code

@vindex RawDriveDriver
@item RawDriveDriver
String specifying the name of the device to be used for raw block access.

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

@vindex DriveSoundEmulation
@item DriveSoundEmulation
Boolean controlling whether the drive noise emulation is turned on.

@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}, @code{1542} (1541-II), @code{1570}, @code{1571}, 
@code{1573} (1571CR), @code{1551}, @code{1581}, @code{1001}, @code{2000}, 
@code{2031}, @code{2040}, @code{3040}, @code{4000}, @code{4040}, @code{8050}, @code{8250}.

@vindex Drive8ParallelCable
@vindex Drive9ParallelCable
@vindex Drive10ParallelCable
@vindex Drive11ParallelCable
@item Drive8ParallelCable
@itemx Drive9ParallelCable
@itemx Drive10ParallelCable
@itemx Drive11ParallelCable
integer controlling what type of parallel cable is emulated for drives 8 to 11.
(0: none, 1: speed-DOS, 2: Professional DOS, 3: Formel64)

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

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

@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.
Possible values are @code{0} (never extend), @code{1} (ask on extend),
@code{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.  Possible values
are @code{0} (none), @code{1} (skip cycles), @code{2} (trap idle).
@xref{Drive settings}.

@vindex DosName1541
@vindex DosName1541ii
@vindex DosName1570
@vindex DosName1571
@vindex DosName1571cr
@vindex DosName1581
@vindex DosName2000
@vindex DosName4000
@vindex DosName2031
@vindex DosName2040
@vindex DosName3040
@vindex DosName4040
@vindex DosName1001
@vindex DosName1551
@item DosName1541
@itemx DosName1541ii
@itemx DosName1570
@itemx DosName1571
@itemx DosName1571cr
@itemx DosName1581
@itemx DosName2000
@itemx DosName4000
@itemx DosName2031
@itemx DosName2040
@itemx DosName3040
@itemx DosName4040
@itemx DosName1001
@itemx DosName1551
Strings specifying the names of the ROM images for the drive emulation.

@vindex DriveProfDOS1571Name
@item DriveProfDOS1571Name
String specifying the filename of the 1571 professional DOS ROM image.

@end table

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

@table @code

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

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

@cindex -drive8type
@cindex -drive9type
@cindex -drive10type
@cindex -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}, @code{1542} (meaning 1541-II),
@code{1551}, @code{1570}, @code{1571}, @code{1573} (meaning 1571cr),
@code{1581}, @code{2000}, @code{4000}, @code{2031}, @code{2040},
@code{3040}, @code{4040}, @code{1001}, @code{8050} and @code{8250}.

@cindex -parallel8
@cindex -parallel9
@cindex -parallel10
@cindex -parallel11
@item -parallel8 <type>
@itemx -parallel9 <type>
@itemx -parallel10 <type>
@itemx -parallel11 <type>
Set parallel cable type (0: none, 1: standard, 2: Dolphin DOS)

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

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

@cindex -dos1541
@cindex -dos1541II
@cindex -dos1551
@cindex -dos1570
@cindex -dos1571
@cindex -dos1571cr
@cindex -dos1581
@cindex -dos2000
@cindex -dos4000
@cindex -dos2031
@cindex -dos2040
@cindex -dos3040
@cindex -dos4040
@cindex -dos1001
@item -dos1541 <name>
@itemx -dos1541II <name>
@item -dos1551 <name>
@itemx -dos1570 <name>
@itemx -dos1571 <name>
@itemx -dos1571cr <name>
@itemx -dos1581 <name>
@itemx -dos2000 <name>
@itemx -dos4000 <name>
@itemx -dos2031 <name>
@itemx -dos2040 <name>
@itemx -dos3040 <name>
@itemx -dos4040 <name>
@itemx -dos1001 <name>
Specify the ROM names for the 1541, 1541II, 1551, 1570, 1571, 1571cr, 1581,
2000, 4000, 2031, 2040, 3040, 4040 and 1001 emulation respectively.

@cindex -drive8ram2000, +drive8ram2000
@cindex -drive9ram2000, +drive9ram2000
@cindex -drive10ram2000, +drive10ram2000
@cindex -drive11ram2000, +drive11ram2000
@item -drive8ram2000, +drive8ram2000
@itemx -drive9ram2000, +drive9ram2000
@itemx -drive10ram2000, +drive10ram2000
@itemx -drive11ram2000, +drive11ram2000
Enable/Disable 8KB RAM expansion at $2000-$3FFF
@cindex -drive8ram4000, +drive8ram4000
@cindex -drive9ram4000, +drive9ram4000
@cindex -drive10ram4000, +drive10ram4000
@cindex -drive11ram4000, +drive11ram4000
@item -drive8ram4000, +drive8ram4000
@itemx -drive9ram4000, +drive9ram4000
@itemx -drive10ram4000, +drive10ram4000
@itemx -drive11ram4000, +drive11ram4000
Enable/Disable 8KB RAM expansion at $4000-$5FFF
@cindex -drive8ram6000, +drive8ram6000
@cindex -drive9ram6000, +drive9ram6000
@cindex -drive10ram6000, +drive10ram6000
@cindex -drive11ram6000, +drive11ram6000
@item -drive8ram6000, +drive8ram6000
@itemx -drive9ram6000, +drive9ram6000
@itemx -drive10ram6000, +drive10ram6000
@itemx -drive11ram6000, +drive11ram6000
Enable/Disable 8KB RAM expansion at $6000-$7FFF
@cindex -drive8ram8000, +drive8ram8000
@cindex -drive9ram8000, +drive9ram8000
@cindex -drive10ram8000, +drive10ram8000
@cindex -drive11ram8000, +drive11ram8000
@item -drive8ram8000, +drive8ram8000
@itemx -drive9ram8000, +drive9ram8000
@itemx -drive10ram8000, +drive10ram8000
@itemx -drive11ram8000, +drive11ram8000
Enable/Disable 8KB RAM expansion at $8000-$9FFF
@cindex -drive8rama000, +drive8rama000
@cindex -drive9rama000, +drive9rama000
@cindex -drive10rama000, +drive10rama000
@cindex -drive11rama000, +drive11rama000
@item -drive8rama000, +drive8rama000
@itemx -drive9rama000, +drive9rama000
@itemx -drive10rama000, +drive10rama000
@itemx -drive11rama000, +drive11rama000
Enable/Disable 8KB RAM expansion at $A000-$BFFF

@cindex -drive8profdos, +drive8profdos
@cindex -drive9profdos, +drive9profdos
@cindex -drive10profdos, +drive10profdos
@cindex -drive11profdos, +drive11profdos
@item -drive8profdos, +drive8profdos
@itemx -drive9profdos, +drive9profdos
@itemx -drive10profdos, +drive10profdos
@itemx -drive11profdos, +drive11profdos
Enable/Disable Professional DOS

@cindex -profdos1571
@item -profdos1571 <name>
Specify name of Professional DOS 1571 ROM image

@end table


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

VICE is able to support some special peripherals:

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

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

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

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

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

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

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

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

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

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


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


@table @code

@vindex 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
Enum specifying the device type for device 8-11 (0: NONE, 1: FILESYSTEM, 2: OPENCBM (Real), 3: BLOCK DEVICE (Raw))

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

@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 (on by default for drives 8-10, off for 11).

@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 to
programs running in the emulator (do not hide by default).

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

@end table


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

@table @code

@cindex -iecdevice8, +iecdevice8
@item -iecdevice8
@itemx +iecdevice8
Enable/Disable IEC device emulation for device #8
@cindex -iecdevice9, +iecdevice9
@item -iecdevice9
@itemx +iecdevice9
Enable/Disable IEC device emulation for device #9
@cindex -iecdevice10, +iecdevice10
@item -iecdevice10
@itemx +iecdevice10
Enable/Disable IEC device emulation for device #10
@cindex -iecdevice11, +iecdevice11
@item -iecdevice11
@itemx +iecdevice11
Enable/Disable IEC device emulation for device #11

@cindex -device8
@cindex -device9
@cindex -device10
@cindex -device11
@item -device8 <type>
@itemx -device9 <type>
@itemx -device10 <type>
@itemx -device11 <type>
Set device type for device 8-11 (0: NONE, 1: FILESYSTEM, 2: OPENCBM (Real), 3: BLOCK DEVICE (Raw))

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

@cindex -flipname
@item -flipname <name>
Specify name of the flip list file image

@end table


@node Printer settings, No kernal traps, File system device settings, Peripheral settings
@subsection Printer settings

The VICE emulators can emulate printers connected to either the IEC
buffer or the user port.  Emulation can be achieved by redirecting the
printer output to a file or by piping it through an external process.
This is defined by so-called @dfn{printer device file names}; a printer
device file name can be either a simple path, or a command name
preceeded by a pipe symbol @samp{|}.

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

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

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

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


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

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

@table @code

@vindex IECDevice4
@vindex IECDevice5
@item IECDevice4
@itemx IECDevice5
Booleans that specify whether IEC device emulation for device #4 and #5 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
@item Printer4TextDevice
@itemx Printer5TextDevice
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
@item Printer4
@itemx Printer5
Integer specifying how the IEC printer (device 4-5) is being emulated.
(0: NONE, 1: FS, 2: REAL)

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

@vindex Printer4Output
@vindex Printer5Output
@item Printer4Output
@itemx Printer5Output
String specifying the IEC printer output device.


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

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

@vindex PrinterUserportDriver
@item PrinterUserportDriver
String specifying the user-port printer output driver.

@vindex PrinterUserportOutput
@item PrinterUserportOutput
String specifying the user-port printer output device.

@end table

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

@table @code

@cindex -iecdevice4, +iecdevice4
@item -iecdevice4
@itemx +iecdevice4
Enable/Disable IEC device emulation for device #4
@cindex -iecdevice5, +iecdevice5
@item -iecdevice5
@itemx +iecdevice5
Enable/Disable IEC device emulation for device #5

@cindex -device4
@cindex -device5
@item -device4 <type>
@itemx -device5 <type>
Set device type for device 4-5 (0: NONE, 1: FS, 2: REAL)

@cindex -prtxtdev1
@cindex -prtxtdev2
@cindex -prtxtdev3
@item -prtxtdev1 <name>
@itemx -prtxtdev2 <name>
@itemx -prtxtdev3 <name>
Specify name of printer text device or dump file
@cindex -pr4txtdev
@cindex -pr5txtdev
@item -pr4txtdev <0-2>
@itemx -pr5txtdev <0-2>
Specify printer text output device for IEC printer #4-5

@cindex -pr4output
@cindex -pr5output
@item -pr4output <name>
@itemx -pr5output <name>
Specify name of output device for device #4-5
Specify name of output device for device #5-5
@cindex -pr4drv
@cindex -pr5drv
@item -pr4drv <name>
@itemx -pr5drv <name>
Specify name of printer driver for device #4-5
Specify name of printer driver for device #5-5

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

@cindex -prusertxtdev
@item -prusertxtdev <0-2>
Specify printer text output device for userport printer
@cindex -pruseroutput
@item -pruseroutput <name>
Specify name of output device for the userport printer
@cindex -pruserdrv
@item -pruserdrv <name>
Specify name of printer driver for the userport printer

@end table


@node No kernal traps,  , Printer settings, Peripheral settings
@subsection Disabling kernal traps

If you have compatibility problems, you can completely disable Kernal
traps with the ``Disable kernal traps'' option.  This will of course
disable all the features that depend on it, such as the fast 1541
emulation (so you will have to turn true 1541 emulation on if you want
to be able to read or write disk images) and tape support.

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

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

@table @code

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

@end table


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

@table @code

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

@end table

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

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

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

Emulation can be achieved by either:

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

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

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

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

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

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

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

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

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

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

@table @code

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

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

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

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

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

@vindex RsUserBaud
@item RsUserBaud
Integer specifying the baudrate of the user-port RS232 interface
(C64, C128 and VIC20).

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

@end table

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

@table @code

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

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

@cindex -myaciadev
@item -myaciadev <0-3>
Specify RS232 device the ACIA should work on

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

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

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

@end table

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

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

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

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

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

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

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

@end table

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

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

@menu
* Monitor options::
@end menu

@node Monitor options,  ,  , Monitor settings

@c @node FIXME
@subsection Monitor resources

@table @code

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

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

@end table

@subsection Monitor command-line options

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

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

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

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

@end table

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

@c @node FIXME
@section Machine settings

@c @node FIXME
@subsection Machine resources

@table @code

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

@end table

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

@table @code

@cindex -pal
@item -pal
Use PAL sync factor
@cindex -ntsc
@item -ntsc
Use NTSC sync factor
@cindex -ntscold
@item -ntscold
Use old NTSC sync factor
@cindex -paln
@item -paln
Use PAL-N sync factor

@end table

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

@c @node FIXME
@section Memory settings

@c @node FIXME
@subsection Memory resources

@table @code

@vindex RAMInitStartValue
@item RAMInitStartValue
Integer specifying the value for the very first RAM address after powerup
@vindex RAMInitValueInvert
@item RAMInitValueInvert
Integer specifying the length of the memory block initialized with the same value
@vindex RAMInitPatternInvert
@item RAMInitPatternInvert
Integer specifying the length of the memory block initialized with the same pattern

@end table

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

@table @code

@cindex -raminitstartvalue
@item -raminitstartvalue <value>
Set the value for the very first RAM address after powerup
@cindex -raminitvalueinvert
@item -raminitvalueinvert <num of bytes>
Length of memory block initialized with the same value
@cindex -raminitpatterninvert
@item -raminitpatterninvert <num of bytes>
Length of memory block initialized with the same pattern

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

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

where:

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

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

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

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

@vindex SaveResourcesOnExit
@item SaveResourcesOnExit
Boolean specifying whether the emulator should save changed settings
before exiting.  If this is enabled, the user will be always prompted
first, in case the settings have changed.

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

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

@vindex LogFileName
@item LogFileName
String specifying the filename of the current log file.
@vindex FliplistName
@item FliplistName
String specifying the filename of the current flip list. (Drive 8 only)

@vindex ConfirmOnExit
@item ConfirmOnExit
Boolean specifying whether to show a confirmation dialog on exit.

@vindex AttachDevice8Readonly
@vindex AttachDevice9Readonly
@vindex AttachDevice10Readonly
@vindex AttachDevice11Readonly
@item AttachDevice8Readonly
@itemx AttachDevice9Readonly
@itemx AttachDevice10Readonly
@itemx AttachDevice11Readonly
Booleans that specify whether to attach images on drives 8 to 11 read-only.

@vindex RomsetArchiveName
@item RomsetArchiveName
String specifying the filename of the ROM set archive (.vra) file ["default"]
@vindex RomsetArchiveActive
@item RomsetArchiveActive
String specifying the active configuration of the current ROM set archive [""]
@vindex RomsetFileName
@item RomsetFileName
String specifying the filename of the ROM set resource file ["default"]
@vindex RomsetSourceFile
@item RomsetSourceFile
Boolean specifying the type of currently used ROM set (0: .vra Archive, 1: resource file) [1]

@end table

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

@table @code
@cindex -directory
@item -directory SEARCHPATH
Specify the system file search path (@code{Directory}).
@cindex -htmlbrowser
@item -htmlbrowser COMMAND
Specify the command to run the HTML browser for the on-line help
(@code{HTMLBrowserCommand}).

@cindex -saveres, +saveres
@item -saveres
@itemx +saveres
Enable/disable automatic saving of settings on exit
(@code{SaveResourcesOnExit=1}, @code{SaveResourcesOnExit=0}).

@cindex -confirmexit, +confirmexit
@item -confirmexit
Confirm quiting VICE
@item +confirmexit
Never confirm quiting VICE

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

@end table


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

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

@node C64/128-specific, C64DTV-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/128 system ROM settings::  Settings to control the system ROMs.
@end menu

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

@subsection Using cartridges

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

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

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

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

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

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

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

Of course, it is also possible to detach a currently attached
cartridge image (``Detach cartridge image'').

If you are using a freezer cart like an Action Replay cartridge, you can
emulate the cartridge's freeze button with the ``Cartridge freeze''
command.

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

@c @node FIXME
@subsubsection Slot 0

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

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

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

The following cartridges are emulated in this slot:

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

@c @node FIXME
@subsubsection Slot 1

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

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

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

The following cartridges are emulated in this slot:

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

@c @node FIXME
@subsubsection Main Slot

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

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

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

The following cartridges are emulated in this slot:

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

@c @node FIXME
@subsubsection I/O Slot

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

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

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

The following cartridges are emulated in this slot:

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

@c @node FIXME
@subsubsection Expected behaviour

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

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

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

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

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

@c @node FIXME
@subsubsection Common problems

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

@itemize @bullet

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

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

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

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

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

@end itemize

@c @node FIXME
@subsubsection IEEE-488 interface

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

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

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

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

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

@c @node FIXME
@subsection C64 cartridge settings

@c @node FIXME
@subsubsection C64 cartridge resources

@table @code

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

@vindex CartridgeReset
@item CartridgeReset
Boolean specifying whether the machine should be resetted when a cartridge is
changed.
@vindex CartridgeType
@item CartridgeType
Integer specifying the type of cartridge emulated in the "main" slot
@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 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
Enum specifying the state of the expert cartridge switch (0=off 1=prg 2=on)
@vindex IDE64Config
@item IDE64Config
String encoded content of IDE64 DS1302 RAM, used to store IDEDOS setup parameters. Not meant to
be directly manipulated as content depends on the version of IDEDOS used.
@vindex IDE64version4
@item IDE64version4
Boolean specifying whether the emulated card version is V4.1 or V3.4. This is automatically
detected most of the time for .crt cartridge images.
@vindex IDE64RTCOffset
@item IDE64RTCOffset
Integer in seconds which gives the difference between the local time and the time of the emulated DS1302 RTC.
@vindex IDE64Image1
@vindex IDE64Image2
@vindex IDE64Image3
@vindex IDE64Image4
@item IDE64Image1
@itemx IDE64Image2
@itemx IDE64Image3
@itemx IDE64Image4
String 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
Number of cylinders for the four harddisk images. Valid range is 1--65535.
@vindex IDE64Heads1
@vindex IDE64Heads2
@vindex IDE64Heads3
@vindex IDE64Heads4
@item IDE64Heads1
@itemx IDE64Heads2
@itemx IDE64Heads3
@itemx IDE64Heads4
Number of heads for the four harddisk images. Valid range is 1--16.
@vindex IDE64Sectors1
@vindex IDE64Sectors2
@vindex IDE64Sectors3
@vindex IDE64Sectors4
@item IDE64Sectors1
@itemx IDE64Sectors2
@itemx IDE64Sectors3
@itemx IDE64Sectors4
Number of sectors for the four harddisk images. Valid range is 1--63.
@vindex IDE64AutodetectSize1
@vindex IDE64AutodetectSize2
@vindex IDE64AutodetectSize3
@vindex IDE64AutodetectSize4
@item IDE64AutodetectSize1
@itemx IDE64AutodetectSize2
@itemx IDE64AutodetectSize3
@itemx IDE64AutodetectSize4
Boolean 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 IEEE488
@item IEEE488
Boolean specifying whether the IEEE488 interface should be emulated or not.
@vindex IEEE488Image
@item IEEE488Image
String specifying the filename of the IEEE488 ROM image
@vindex IsepicCartridgeEnabled
@item IsepicCartridgeEnabled
Boolean specifying whether ISEPIC should be emulated or not.
@vindex Isepicfilename
@item Isepicfilename
String specifying the filename of the ISEPIC RAM image.
@vindex IsepicSwitch
@item IsepicSwitch
Boolean specifying the status of the ISEPIC switch (0: off, 1: on)
@vindex IsepicImageWrite
@item IsepicImageWrite
Boolean, if true write back the ISEPIC image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.
@vindex MagicVoiceCartridgeEnabled
@item MagicVoiceCartridgeEnabled
Boolean specifying whether the Magic Voice should be emulated or not.
@vindex MagicVoiceImage
@item MagicVoiceImage
String specifying the filename of the Magic Voice ROM image

@vindex MMC64
@item MMC64
Boolean specifying whether the MMC64 should be emulated or not.
@vindex MMC64BIOSfilename
@item MMC64BIOSfilename
String specifying the filename of the MMC64 Flash ROM image.
@vindex MMC64_bios_write
@item MMC64_bios_write
Boolean, if true write back the MMC64 Flash ROM image file automatically, incase the
contents changed, when detaching or quitting the emulator.
@vindex MMC64_flashjumper
@item MMC64_flashjumper
Boolean that specifies whether the MMC64 flash jumper is set.
@vindex MMC64_revision
@item MMC64_revision
Integer that specifies the MMC64 hardware revision (0=Rev. A, 1=Rev. B)
@vindex MMC64imagefilename
@item MMC64imagefilename
String specifying the filename of the SD-Card image used by the MMC64 emulation.
@vindex MMC64_RO
@item MMC64_RO
Boolean, if true the SD-Card image is mounted read-only.
@vindex MMC64_sd_type
@item MMC64_sd_type
Integer that specifies the reported type for the emulated SD-Card. (0=Auto, 1=MMC,
2=SD, 3=SDHC)

@vindex MMCRCardImage
@item MMCRCardImage
String that specifies the filename of the SD-Card image used by the MMCR emulation.
@vindex MMCREEPROMImage
@item MMCREEPROMImage
String that specifies the filename of the MMCR EEPROM image.
@vindex MMCRRescueMode
@item MMCRRescueMode
Boolean that specifies 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 that specifies 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 that specifies if the MMCR EEPROM image is writeable.

@vindex RAMCART
@item RAMCART
Boolean specifying whether the RAMCart should be emulated or not.
@vindex RAMCARTfilename
@item RAMCARTfilename
String specifying the filename of the RAMCart RAM image.
@vindex RAMCARTImageWrite
@item RAMCARTImageWrite
Boolean, if true write back the RAMCart image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.
@vindex RAMCART_RO
@item RAMCART_RO
Boolean, if true the RAMCart contents are read only
@vindex RAMCARTsize
@item RAMCARTsize
Integer specifying the size of the RAMCart in KB (64, 128)

@vindex RRrevision
@item RRrevision
Integer specifying the RR hardware revision (0=retro replay, 1=nordic replay)
@vindex RRFlashJumper
@item RRFlashJumper
Boolean specifying whether the RR flash jumper is set or not.
@vindex RRBankJumper
@item RRBankJumper
Boolean specifying whether the RR bank jumper is set or not.
@vindex RRBiosWrite
@item RRBiosWrite
Boolean, if true write back the RR Flash ROM image file automatically, incase the
contents changed, when detaching or quitting the emulator.
@end table

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

@table @code

@cindex -iocollision
@item -iocollision <method>
Select 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

@cindex +cart
@item +cart
Disable all cartridges (which would eventually be enabled in the config file).
@cindex -cartreset, +cartreset
@item -cartreset
@itemx +cartreset
Reset/Do not reset machine if a cartridge is attached or detached
@cindex -cart8
@item -cart8 <name>
Attach generic 8KB cartridge image
@cindex -cart16
@item -cart16 <name>
Attach generic 16KB cartridge image
@cindex -cartultimax
@item -cartultimax <name>
Attach generic 16kB Ultimax cartridge image
@cindex -cartcrt
@item -cartcrt <name>
Attach CRT cartridge image
@cindex -cartap
@item -cartap <name>
Attach raw 32KB Atomic Power cartridge image
@cindex -cartar2
@item -cartar2 <name>
Attach raw 16kB Action Replay MK2 cartridge image
@cindex -cartar3
@item -cartar3 <name>
Attach raw 16KB Action Replay MK3 cartridge image
@cindex -cartar4
@item -cartar4 <name>
Attach raw 32KB Action Replay MK4 cartridge image
@cindex -cartar5
@item -cartar5 <name>
Attach raw 32KB Action Replay cartridge image
@cindex -cartcap
@item -cartcap <name>
Attach raw 8kB Capture cartridge image
@cindex -cartcomal
@item -cartcomal <name>
Attach raw 64kB Comal 80 cartridge image
@cindex -cartdep256
@item -cartdep256 <name>
Attach raw Dela EP256 cartridge image
@cindex -cartdep64
@item -cartdep64 <name>
Attach raw Dela EP64 cartridge image
@cindex -cartdep7x8
@item -cartdep7x8 <name>
Attach raw Dela EP7x8 cartridge image
@cindex -cartdin
@item -cartdin <name>
Attach raw 128kB Dinamic cartridge image
@cindex -cartdsm
@item -cartdsm <name>
Attach raw 8kB Diashow-Maker cartridge image
@cindex -cartdqbb
@item -cartdqbb <name>
Attach raw 16kB Double Quick Brown Box cartridge image
@cindex -dqbb, +dqbb
@item -dqbb
@itemx +dqbb
Enable/Disable Double Quick Brown Box
@cindex -dqbbimage
@item -dqbbimage <name>
Specify Double Quick Brown Box filename
@cindex -dqbbimagerw, +dqbbimagerw
@item -dqbbimagerw
@itemx +dqbbimagerw
Allow/Disallow writing to DQBB image
@cindex -carteasy
@item -carteasy <name>
Attach raw EasyFlash cartridge image
@cindex -easyflashjumper, +easyflashjumper
@item -easyflashjumper
@itemx +easyflashjumper
Enable/Disable EasyFlash jumper
@cindex -easyflashcrtwrite, +easyflashcrtwrite
@item -easyflashcrtwrite
@itemx +easyflashcrtwrite
Allow/Disallow writing to EasyFlash .crt image
@cindex -cartepyx
@item -cartepyx <name>
Attach raw 8KB Epyx FastLoad cartridge image
@cindex -cartexos
@item -cartexos <name>
Attach raw 8kB EXOS cartridge image
@cindex -cartexpert
@item -cartexpert <name>
Attach raw 8kB Expert Cartridge image
@cindex -expert, +expert
@item -expert
@itemx +expert
Enable/Disable the Expert Cartridge
@cindex -expertimagename
@item -expertimagename <name>
Set Expert Cartridge image name
@cindex -expertimagerw, +expertimagerw
@item -expertimagerw
@itemx +expertimagerw
Allow/Disallow writing to Expert Cartridge image
@cindex -cartf64
@item -cartf64 <Name>
Attach raw 32kB Formel 64 image
@cindex -cartfc1
@item -cartfc1 <name>
Attach raw 16kB Final Cartridge image
@cindex -cartfc3
@item -cartfc3 <name>
Attach raw 64kB Final Cartridge III image
@cindex -cartfcplus
@item -cartfcplus <name>
Attach raw 32kB Final Cartridge Plus image
@cindex -cartff
@item -cartff <name>
Attach raw 8kB Freeze Frame image
@cindex -cartfm
@item -cartfm <name>
Attach raw 32kB Freeze Machine image
@cindex -cartfp
@item -cartfp <name>
Attach raw 128kB Fun Play/Power Play cartridge image
@cindex -cartgk
@item -cartgk <name>
Attach raw 8KB Game Killer cartridge image
@cindex -cartgs
@item -cartgs <name>
Attach raw 512kB Game System cartridge image
@cindex -cartide64
@item -cartide64 <name>
Attach raw 64KB or 128KB IDE64 cartridge image
@cindex -IDE64image1
@item -IDE64image1 <name>
@cindex -IDE64image2
@item -IDE64image2 <name>
@cindex -IDE64image3
@item -IDE64image3 <name>
@cindex -IDE64image4
@item -IDE64image4 <name>
Specify path to the image files for IDE64 harddisks
@cindex -IDE64cyl1
@item -IDE64cyl1 <value>
@cindex -IDE64cyl2
@item -IDE64cyl2 <value>
@cindex -IDE64cyl3
@item -IDE64cyl3 <value>
@cindex -IDE64cyl4
@item -IDE64cyl4 <value>
Set number of cylinders for the IDE64 harddisk emulation (1-65535)
@cindex -IDE64hds1
@item -IDE64hds1 <value>
@cindex -IDE64hds2
@item -IDE64hds2 <value>
@cindex -IDE64hds3
@item -IDE64hds3 <value>
@cindex -IDE64hds4
@item -IDE64hds4 <value>
Set number of heads for the IDE64 harddisk emulation (1-16)
@cindex -IDE64sec1
@item -IDE64sec1 <value>
@cindex -IDE64sec2
@item -IDE64sec2 <value>
@cindex -IDE64sec3
@item -IDE64sec3 <value>
@cindex -IDE64sec4
@item -IDE64sec4 <value>
Set number of sectors for the IDE64 harddisk emulation (1-63)
@cindex -IDE64autosize1, +IDE64autosize1
@cindex -IDE64autosize2, +IDE64autosize2
@cindex -IDE64autosize3, +IDE64autosize3
@cindex -IDE64autosize4, +IDE64autosize4
@item -IDE64autosize1
@itemx +IDE64autosize1
@item -IDE64autosize2
@itemx +IDE64autosize2
@item -IDE64autosize3
@itemx +IDE64autosize3
@item -IDE64autosize4
@itemx +IDE64autosize4
Autodetect geometry of formatted images or do not autodetect and use specified geometry
@cindex -IDE64version4, +IDE64version4
@item -IDE64version4
@itemx +IDE64version4
Emulate version 4 hardware/Emulate pre version 4 hardware
@cindex -cartieee
@item -cartieee <name>
Attach CBM IEEE-488 cartridge image
@cindex -ieee488, +ieee488
@item -ieee488
@itemx +ieee488
Enable (@code{IEEE488=1}) or disable (@code{IEEE488=0}) emulation of the
IEEE488 interface.
@cindex -ieee488image
@item -ieee488image <name>
Set IEEE488 interface image name
@cindex -isepic, +isepic
@item -isepic
@itemx +isepic
Enable/Disable the ISEPIC cart
@cindex -cartisepic
@item -cartisepic <name>
Attach raw 2kB ISEPIC cartridge image
@cindex -isepicimagename
@item -isepicimagename <name>
Set ISEPIC image name
@cindex -isepicimagerw, +isepicimagerw
@item -isepicimagerw
@itemx +isepicimagerw
Allow/Disallow writing to ISEPIC image
@cindex -cartkcs
@item -cartkcs <name>
Attach raw 16kB KCS Power cartridge image
@cindex -cartks
@item -cartks <name>
Attach raw 24kB Kingsoft cartridge image
@cindex -cartmach5
@item -cartmach5 <name>
Attach raw 8kB MACH 5 cartridge image
@cindex -cartmd
@item -cartmd <name>
Attach raw 32/64/128kB Magic Desk cartridge image
@cindex -cartmf
@item -cartmf <name>
Attach raw Magic Formel cartridge image
@cindex -cartmikro
@item -cartmikro <name>
Attach raw 8kB Mikro Assembler cartridge image
@cindex -mmc64, +mmc64
@item -mmc64
@itemx +mmc64
Enable/Disable the MMC64 expansion
@cindex -cartmmc64
@item -cartmmc64 <name>
Attach raw 8kB MMC64 cartridge image
@cindex -mmc64bios
@item -mmc64bios <name>
Specify name of MMC64 BIOS image
@cindex -mmc64image
@item -mmc64image <name>
Specify name of MMC64 image
@cindex -mmc64readonly
@item -mmc64readonly
Set the MMC64 card to read-only
@cindex -mmc64readwrite
@item -mmc64readwrite
Set the MMC64 card to read/write
@cindex -mmc64bioswrite
@item -mmc64bioswrite
Save the MMC64 bios when changed
@cindex -cartmmcr
@item -cartmmcr <name>
Attach raw 512kB MMC Replay cartridge image
@cindex -mmcrrescue, +mmcrrescue
@item -mmcrrescue
@itemx +mmcrrescue
Enable/Disable MMC Replay rescue mode
@cindex -mmcrimagerw, +mmcrimagerw
@item -mmcrimagerw
@itemx +mmcrimagerw
Allow/Disallow writing to MMC Replay image
@cindex -mmcrcardimage
@item -mmcrcardimage <filename>
Specify MMC Replay card image filename
@cindex -mmcrcardrw, +mmcrcardrw
@item -mmcrcardrw
@itemx +mmcrcardrw
Allow/Disallow writes to MMC Replay card image
@cindex -mmcreepromimage
@item -mmcreepromimage
Specify MMC Replay EEPROM image filename
@cindex -mmcreepromrw, +mmcreepromrw
@item -mmcreepromrw
@itemx +mmcreepromrw
Allow/Disallow writes to MMC Replay EEPROM image
@cindex -cartmv
@item -cartmv <name>
Attach raw 16kB Magic Voice cartridge image
@cindex -cartocean
@item -cartocean <name>
Attach raw Ocean cartridge image
@cindex -cartp64
@item -cartp64 <name>
Attach raw 256KB Prophet 64 cartridge image
@cindex -cartpf
@item -cartpf <name>
Attach raw 64kb Pagefox cartridge image
@cindex -cartramcart
@item -cartramcart <name>
Attach raw RamCart cartridge image
@cindex -ramcart, +ramcart
@item -ramcart
@itemx +ramcart
Enable/Disable the RAMCART expansion
@cindex -ramcartsize
@item -ramcartsize <size in KB>
Size of the RAMCART expansion
@cindex -ramcartimage
@item -ramcartimage <name>
Specify name of RAMCART image
@cindex -ramcartimagerw, +ramcartimagerw
@item -ramcartimagerw
@itemx +ramcartimagerw
Allow/Disallow writing to RAMCart image
@cindex -cartrep256
@item -cartrep256 <name>
Attach raw REX EP256 cartridge image
@cindex -cartross
@item -cartross <name>
Attach raw 16/32kB ROSS cartridge image
@cindex -cartrr
@item -cartrr <name>
Attach raw 64KB Retro Replay cartridge image
@cindex -rrbioswrite, +rrbioswrite
@item -rrbioswrite
@itemx +rrbioswrite
Enable/Disable saving of the RR ROM at exit
@cindex -rrbankjumper, +rrbankjumper
@item -rrbankjumper
@itemx +rrbankjumper
Set/Unset RR Bank Jumper
@cindex -rrflashjumper, +rrflashjumper
@item -rrflashjumper
@itemx +rrflashjumper
Set/Unset RR Flash Jumper
@cindex -cartru
@item -cartru <name>
Attach raw 8kB REX Utility cartridge image
@cindex -carts64
@item -carts64 <name>
Attach raw 4kB Snapshot 64 cartridge image
@cindex -cartsb
@item -cartsb <name>
Attach raw Structured Basic cartridge image
@cindex -cartse5
@item -cartse5 <name>
Attach raw 16kB Super Explode V5 cartridge image
@cindex -cartsg
@item -cartsg <name>
Attach raw 64kB Super Games cartridge image
@cindex -cartsilver
@item -cartsilver <Name>
Attach raw Silverrock 128 cartridge image
@cindex -cartsimon
@item -cartsimon <name>
Attach raw 16kB Simons Basic cartridge image
@cindex -cartss4
@item -cartss4 <name>
Attach raw 32KB Super Snapshot V4 cartridge image
@cindex -cartss5
@item -cartss5 <name>
Attach raw 64KB Super Snapshot V5 cartridge image
@cindex -cartstar
@item -cartstar <name>
Attach raw 16KB Stardos cartridge image
@cindex -cartwl
@item -cartwl <name>
Attach raw 16KB Westermann Learning cartridge image
@cindex -cartws
@item -cartws <name>
Attach raw 8kB Warp Speed cartridge image
@cindex -cartzaxxon
@item -cartzaxxon <name>
Attach raw 16kB Zaxxon cartridge image
@end table

@c @node FIXME
@subsection CIA settings

@c @node FIXME
@subsubsection CIA resources

@table @code

@vindex CIA1Model
@vindex CIA2Model
@item CIA1Model
@itemx CIA2Model
Enum specifying CIA model (0 = old 6526, 1 = new 6526A)

@end table

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

@table @code

@cindex -ciamodel
@item -ciamodel <model>
Set both CIA models (0 = old 6526, 1 = new 6526A)
@cindex -cia1model
@item -cia1model <model>
Set CIA 1 model (0 = old 6526, 1 = new 6526A)
@cindex -cia2model
@item -cia2model <model>
Set CIA 2 model (0 = old 6526, 1 = new 6526A)

@end table

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

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

@itemize @bullet

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

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

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

@end itemize

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

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

@table @code

@vindex VICIIModel
@item VICIIModel
Integer that specifies VIC-II model (6569/6569r1/8565/6567/8562/6567r56a).
only available in @code{x64sc}.

@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 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 VICIIHwScale
@item VICIIHwScale
Boolean specifying whether to enable or disable hardware scaling

@vindex VICIIFullscreenDevice
@item VICIIFullscreenDevice
fullscreen device

@vindex VICIIFullscreen
@item VICIIFullscreen
Boolean specifying whether to use fullscreen mode or not.

@vindex VICIIFullscreenStatusbar
@item VICIIFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not.

@vindex VICIIXRANDRFullscreenMode
@item VICIIXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode

@vindex VICIIVidmodeFullscreenMode
@item VICIIVidmodeFullscreenMode
integer specifying Vidmode fullscreen mode

@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 [1000] <0-2000>

@vindex VICIIColorContrast
@item VICIIColorContrast
integer specifying contrast of internal calculated palette [1000] <0-2000>

@vindex VICIIColorBrightness
@item VICIIColorBrightness
integer specifying brightness of internal calculated palette [1000] <0-2000>

@vindex VICIIColorGamma
@item VICIIColorGamma
integer specifying gamma of internal calculated palette [2200] <0-4000>

@vindex VICIIColorTint
@item VICIIColorTint
integer specifying tint of internal calculated palette [1000] <0-2000>

@vindex VICIIPALScanLineShade
@item VICIIPALScanLineShade
integer specifying amount of scan line shading for the CRT emulation [667] <0-1000>

@vindex VICIIPALBlur
@item VICIIPALBlur
integer specifying amount of horizontal blur for the CRT emulation. [500] <0-1000>

@vindex VICIIPALOddLinePhase
@item VICIIPALOddLinePhase
integer specifying phase offset for color carrier in odd lines [750] <0-2000>

@vindex VICIIPALOddLineOffset
@item VICIIPALOddLineOffset
integer specifying phase for color carrier in odd lines [1250] <0-2000>

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

@vindex VICIIFilter
@item VICIIFilter
integer specifying rendering filter, 0:none, 1:CRT emulation, 2: scale2x

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

@end table


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

@table @code

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

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

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

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

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

@cindex -VICIIhwscale, +VICIIhwscale
@item -VICIIhwscale
@itemx +VICIIhwscale
Enable/Disable hardware scaling
@cindex -VICIIfilter
@item -VICIIfilter <Mode>
Select rendering filter, 0:none, 1:CRT emulation, 2: scale2x
@cindex -VICIIintpal
@item -VICIIintpal
Use an internal calculated palette
@cindex -VICIIextpal
@item -VICIIextpal
Use an external palette (file)

@cindex -VICIIpalette
@item -VICIIpalette NAME
Specify @code{NAME} as the palette file (@code{VICIIPaletteFile}).

@cindex -VICIIfulldevice
@item -VICIIfulldevice <device>
Select fullscreen device
@cindex -VICIIXRANDRfullmode
@item -VICIIXRANDRfullmode <mode>
Select fullscreen mode
@cindex -VICIIVidmodefullmode
@item -VICIIVidmodefullmode <mode>
Select fullscreen mode
@cindex -VICIIborders
@item -VICIIborders <mode>
Set VIC-II border display mode (0: normal, 1: full, 2: debug, 3:none)
@cindex -VICIImodel
@item -VICIImodel <model>
Set VIC-II model (6569/6569r1/8565/6567/8562/6567r56a). This setting is
only available in @code{x64sc}.

@cindex -VICIInewluminance, +VICIInewluminance
@item -VICIInewluminance
@item +VICIInewluminance
Enable/Disable new luminances.

@cindex -VICIIsaturation
@item -VICIIsaturation <0-2000>
Set saturation of internal calculated palette [1000]
@cindex -VICIIcontrast
@item -VICIIcontrast <0-2000>
Set contrast of internal calculated palette [1000]
@cindex -VICIIbrightness
@item -VICIIbrightness <0-2000>
Set brightness of internal calculated palette [1000]
@cindex -VICIIgamma
@item -VICIIgamma <0-4000>
Set gamma of internal calculated palette [2200]
@cindex -VICIItint
@item -VICIItint <0-2000>
Set tint of internal calculated palette [1000]
@cindex -VICIIoddlinesphase
@item -VICIIoddlinesphase <0-2000>
Set phase for color carrier in odd lines [1250]
@cindex -VICIIoddlinesoffset
@item -VICIIoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines [750]
@cindex -VICIIcrtblur
@item -VICIIcrtblur <0-1000>
Amount of horizontal blur for the CRT emulation. [500]
@cindex -VICIIcrtscanlineshade
@item -VICIIcrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation [667]

@cindex -VICIIaudioleak, +VICIIaudioleak
@item -VICIIaudioleak
@item +VICIIaudioleak
Enable/Disable video to audio leak emulation.

@end table


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

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

@itemize @bullet

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

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

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

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

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

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

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

@end itemize

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

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

@table @code

@vindex SidStereo
@item SidStereo
Integer specifying the amount of emulated extra SIDs. (0=off, 1=1 extra sid, 
2=2 extra sids.

@vindex SidStereoAddressStart
@item SidStereoAddressStart
Integer specifying the base address of the second SID.

@vindex SidTripleAddressStart
@item SidTripleAddressStart
Integer specifying the base address of the third SID.

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

@vindex SidModel
@item SidModel
Integer specifying what model of the SID must be emulated (@code{0}: 6581
, @code{1}: 8580, @code{2}: 8580D, @code{3}: 6581R4, @code{4}: DTVSID, @code{8}: 6581R3_4885   
, @code{9}: 6581R3_0486S, @code{10}: 6581R3_3984, @code{11}: 6581R4AR_3789, @code{12}: 6581R3_4485   
, @code{13}: 6581R4_1986S, @code{16}: 8580R5_3691, @code{17}: 8580R5_3691D, @code{18}: 8580R5_1489   
, @code{19}: 8580R5_1489D).

@vindex SidEngine
@item SidEngine
Integer specifying what SID engine will be used (@code{0}: FASTSID, @code{1}: RESID
, @code{2}: CATWEASELMKIII, @code{3}: HARDSID, @code{4}: PARSID_PORT1, @code{5}: PARSID_PORT2
, @code{6}: PARSID_PORT3).

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

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

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

@end table


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

@table @code

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

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

@cindex -sidtripleaddress
@item -sidtripleaddress @code{ADDRESS}
Specifies the start address for the third SID chip
(@code{SidTripleAddressStart}).

@cindex -sidenginemodel
@item -sidenginemodel <engine and model>
Specify @code{SID engine} and @code{MODEL} for the emulated SID chip (
0: FastSID 6581,
1: FastSID 8580,
256: ReSID 6581,
257: ReSID 8580,
258: ReSID 8580 + digiboost,
1024: ParSID in par port 1,
1280: ParSID in par port 2,
1536: ParSID in par port 3).

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

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

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

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

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

@end table


@node C64 I/O extension settings, C64/128 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 Ethernet (The Final Ethernet, RR-Net)
@item Ethernet (The Final Ethernet, RR-Net)

@cindex GEO-RAM
@item GEO-RAM

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

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

@cindex SFX Sound Expander
@item SFX Sound Expander

@cindex SFX Sound Sampler
@item SFX Sound Sampler

@end itemize

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

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

@table @code

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

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

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

@vindex GEORAM
@item GEORAM
Boolean specifying whether the GEO-RAM cartridge should be emulated or not.
@vindex GEORAMfilename
@item GEORAMfilename
String specifying the filename of the GEORAM image.
@vindex GEORAMImageWrite
@item GEORAMImageWrite
Boolean, if true write back the GEO-RAM image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.
@vindex GEORAMsize
@item GEORAMsize
Integer specifying the size of the emulated GEO-RAM in KB (64, 128, 256, 512, 1024, 
2048, 4096)

@vindex MIDIEnable
@item MIDIEnable
Boolean specifying whether the MIDI cartridge should be emulated or not.
@vindex MIDIMode
@item MIDIMode
Enum specifying the type of emulated MIDI interface (0: Sequential, 1: Passport/Syntech,
2: DATEL/Siel/JMS, 3: Namesoft, 4: Maplin)
@vindex MIDIDriver
@item MIDIDriver
Enum specifying the MIDI driver (0: OSS; 1:ALSA)
@vindex MIDIInDev
@item MIDIInDev
String specifying the MIDI input device.
@vindex MIDIOutDev
@item MIDIOutDev
String specifying the MIDI output device.

@vindex REU
@item REU
Boolean specifying whether the RAM Expansion Module should be emulated or not.
@vindex REUfilename
@item REUfilename
String specifying the filename of the REU image.
@vindex REUImageWrite
@item REUImageWrite
Boolean, if true write back the REU image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.
@vindex REUsize
@item REUsize
Integer specifying the size of the emulated REU in KB (128, 256, 512, 1024, 2048,
4096, 8192, 16384)

@vindex SFXSoundExpander
@item SFXSoundExpander
Boolean specifying whether the SFX Sound Expander should be emulated or not.
@vindex SFXSoundExpanderChip
@item SFXSoundExpanderChip
Enum specifying which YM chip is emulated (0: 3526, 1: 3812)

@vindex SFXSoundSampler
@item SFXSoundSampler
Boolean specifying whether the SFX Sound Sampler should be emulated or not.

@end table


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

@table @code

@cindex -acia1, +acia1
@item -acia1
@itemx +acia1
Enable/Disable the $DE** ACIA RS232 interface emulation
@cindex -digimax, +digimax
@item -digimax
@itemx +digimax
Enable/Disable the DigiMAX cartridge
@cindex -digimaxbase
@item -digimaxbase <base address>
Base address of the DigiMAX cartridge
@cindex -miditype
@item -miditype <0-4>
MIDI interface type (0: Sequential, 1: Passport, 2: DATEL, 3: Namesoft, 4: Maplin)
@cindex -midi, +midi
@item -midi
@itemx +midi
Enable/Disable MIDI emulation
@cindex -midiin
@item -midiin <name>
Specify MIDI-In device
@cindex -midiout
@item -midiout <name>
Specify MIDI-Out device
@cindex -mididrv
@item -mididrv <driver>
Specify MIDI driver (0 = OSS, 1 = ALSA)
@cindex -georam, +georam
@item -georam
@itemx +georam
Enable/Disable the GEORAM expansion unit
@cindex -cartgeoram
@item -cartgeoram <name>
Attach raw GEO-RAM cartridge image
@cindex -georamimage
@item -georamimage <name>
Specify name of GEORAM image
@cindex -georamimagerw, +georamimagerw
@item -georamimagerw
@itemx +georamimagerw
Allow/Disallow writing to GEORAM image
@cindex -georamsize
@item -georamsize <size in KB>
Size of the GEORAM expansion unit
@cindex -reu, +reu
@item -reu
@itemx +reu
Enable (@code{REU=1}) or disable (@code{REU=0}) emulation of the
RAM Expansion Module.
@cindex -cartreu
@item -cartreu <name>
Attach raw REU cartridge image
@cindex -reuimage
@item -reuimage <name>
Specify name of REU image
@cindex -reuimagerw, +reuimagerw
@item -reuimagerw
@itemx +reuimagerw
Allow/Disallow writing to REU image
@cindex -reusize
@item -reusize <size in KB>
Size of the RAM expansion unit
@cindex -sfxse, +sfxse
@item -sfxse
@itemx +sfxse
Enable/Disable the SFX soundexpander cartridge
@cindex -sfxsetype
@item -sfxsetype <type>
Set YM chip type (3526 / 3812)
@cindex -sfxss, +sfxss
@item -sfxss
@itemx +sfxss
Enable/Disable the SFX Sound Sampler cartridge
@cindex -tfe, +tfe
@item -tfe
@itemx +tfe
Enable/Disable the TFE ("The Final Ethernet") unit
@cindex -tfeif
@item -tfeif <name>
Set the system ethernet interface for TFE emulation
@cindex -tferrnet, +tferrnet
@item -tferrnet
@itemx +tferrnet
Enable/Disable RRNet mode of TFE emulation
@cindex -burstmod
@item -burstmod <value>
Enable/Disable burst modification. If it's 1 the cable is connected to CIA1, if 2
then to CIA2 and 0 disables it. This is emulates the fast serial bus connection
as described at @uref{http://www.cs.tut.fi/~albert/Dev/burst/}, with the wire to
the tape port cut.
@end table

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

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

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

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

@table @code

@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}).  In
the C128 emulator, the ROM image must actually include the editor ROM too.

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

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

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

@end table

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

@table @code

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

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

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

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

@end table

@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-log. (0: discrete, 1: custom IC)

@vindex BurstMod
@item BurstMod
Boolean, enable/disable the Burst-Mode modification.

@vindex PLUS60K
@item PLUS60K
Boolean, enable/disable the PLUS60K RAM expansion
@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.

@vindex PLUS256K
@item PLUS256K
Boolean, enable/disable the PLUS256K RAM expansion
@vindex PLUS256Kfilename
@item PLUS256Kfilename
String specifying the filename of the PLUS256K RAM image.

@vindex C64_256K
@item C64_256K
Boolean, enable/disable the 256K RAM expansion
@vindex C64_256Kfilename
@item C64_256Kfilename
String specifying the filename of the 256K RAM image.
@vindex C64_256Kbase
@item C64_256Kbase
Integer that specifies the base address of the 256K RAM expansion.

@end table

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

@table @code

@cindex -gluelogictype
@item -gluelogictype <type>
Set glue logic type (0 = discrete, 1 = 252535-01)

@cindex -plus60k, +plus60k
@item -plus60k
@itemx +plus60k
Enable/Disable the PLUS60K RAM expansion
@cindex -plus60kimage
@item -plus60kimage <name>
Specify name of PLUS60K image
@cindex -plus60kbase
@item -plus60kbase <base address>
Base address of the PLUS60K expansion

@cindex -plus256k, +plus256k
@item -plus256k
@itemx +plus256k
Enable/Disable the PLUS256K RAM expansion
@cindex -plus256kimage
@item -plus256kimage <name>
Specify name of PLUS256K image

@cindex -256k, +256k
@item -256k
@itemx +256k
Enable/Disable the 256K RAM expansion
@cindex -256kimage
@item -256kimage <name>
Specify name of 256K image
@cindex -256kbase
@item -256kbase <base address>
Base address of the 256K expansion

@end table

@c @node FIXME
@section C128-specific commands and settings

@c @node FIXME
@subsection VDC settings

@c @node FIXME
@subsubsection VDC resources

@table @code

@vindex VDC64KB
@item VDC64KB
Boolean, enabled full 64k video ram.
@vindex VDCRevision
@item VDCRevision
Integer specifying the VDC hardware revision. (0: Rev 0, 1: Rev 1, 2: Rev 2)

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

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

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

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

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

@vindex VDCHwScale
@item VDCHwScale
Boolean specifying whether to enable or disable hardware scaling

@vindex VDCFullscreenDevice
@item VDCFullscreenDevice
fullscreen device

@vindex VDCFullscreen
@item VDCFullscreen
Boolean specifying whether to use fullscreen mode or not.

@vindex VDCFullscreenStatusbar
@item VDCFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not.

@vindex VDCXRANDRFullscreenMode
@item VDCXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode

@vindex VDCVidmodeFullscreenMode
@item VDCVidmodeFullscreenMode
integer specifying Vidmode fullscreen mode

@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 [1000] <0-2000>

@vindex VDCColorContrast
@item VDCColorContrast
integer specifying contrast of internal calculated palette [1000] <0-2000>

@vindex VDCColorBrightness
@item VDCColorBrightness
integer specifying brightness of internal calculated palette [1000] <0-2000>

@vindex VDCColorGamma
@item VDCColorGamma
integer specifying gamma of internal calculated palette [2200] <0-4000>

@vindex VDCColorTint
@item VDCColorTint
integer specifying tint of internal calculated palette [1000] <0-2000>

@vindex VDCPALScanLineShade
@item VDCPALScanLineShade
integer specifying amount of scan line shading for the CRT emulation [667] <0-1000>

@vindex VDCPALBlur
@item VDCPALBlur
integer specifying amount of horizontal blur for the CRT emulation. [500] <0-1000>

@vindex VDCPALOddLinePhase
@item VDCPALOddLinePhase
integer specifying phase offset for color carrier in odd lines [750] <0-2000>

@vindex VDCPALOddLineOffset
@item VDCPALOddLineOffset
integer specifying phase for color carrier in odd lines [1250] <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
@cindex -VDCvcache, +VDCvcache
@item -VDCvcache
@itemx +VDCvcache
Enable/Disable the video cache
@cindex -VDCdsize, +VDCdsize
@item -VDCdsize
@itemx +VDCdsize
Enable/Disable double size
@cindex -VDCstretchvertical, +VDCstretchvertical
@item -VDCstretchvertical
@itemx +VDCstretchvertical
Enable/Disable vertical stretching
@cindex -VDCdscan, +VDCdscan
@item -VDCdscan
@itemx +VDCdscan
Enable/Disable double scan
@cindex -VDChwscale, +VDChwscale
@item -VDChwscale
@itemx +VDChwscale
Enable/Disable hardware scaling
@cindex -VDCintpal
@item -VDCintpal
Use an internal calculated palette
@cindex -VDCextpal
@item -VDCextpal
Use an external palette (file)
@cindex -VDCpalette
@item -VDCpalette <name>
Specify name of file of external palette
@cindex -VDCfulldevice
@item -VDCfulldevice <device>
Select fullscreen device
@cindex -VDCXRANDRfullmode
@item -VDCXRANDRfullmode <mode>
Select fullscreen mode
@cindex -VDCVidmodefullmode
@item -VDCVidmodefullmode <mode>
Select fullscreen mode
@cindex -VDC16KB
@item -VDC16KB
Set the VDC memory size to 16KB
@cindex -VDC64KB
@item -VDC64KB
Set the VDC memory size to 64KB
@cindex -VDCRevision
@item -VDCRevision <number>
Set VDC revision (0..2)

@cindex -VDCsaturation
@item -VDCsaturation <0-2000>
Set saturation of internal calculated palette [1000]
@cindex -VDCcontrast
@item -VDCcontrast <0-2000>
Set contrast of internal calculated palette [1000]
@cindex -VDCbrightness
@item -VDCbrightness <0-2000>
Set brightness of internal calculated palette [1000]
@cindex -VDCgamma
@item -VDCgamma <0-4000>
Set gamma of internal calculated palette [2200]
@cindex -VDCtint
@item -VDCtint <0-2000>
Set tint of internal calculated palette [1000]
@cindex -VDCoddlinesphase
@item -VDCoddlinesphase <0-2000>
Set phase for color carrier in odd lines [1250]
@cindex -VDCoddlinesoffset
@item -VDCoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines [750]
@cindex -VDCcrtblur
@item -VDCcrtblur <0-1000>
Amount of horizontal blur for the CRT emulation. [500]
@cindex -VDCcrtscanlineshade
@item -VDCcrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation [667]

@cindex -VDCaudioleak, +VDCaudioleak
@item -VDCaudioleak
@item +VDCaudioleak
Enable/Disable video to audio leak emulation.

@end table

@c @node FIXME
@subsection C128 system ROM settings

@c @node FIXME
@subsubsection C128 system ROM resources

@table @code

@vindex ChargenIntName
@vindex ChargenDEName
@vindex ChargenFRName
@vindex ChargenSEName
@item ChargenIntName
@itemx ChargenDEName
@itemx ChargenFRName
@itemx ChargenSEName
Strings specifying the filename of the Chargen ROM images.

@vindex KernalIntName
@vindex KernalDEName
@vindex KernalFIName
@vindex KernalFRName
@vindex KernalITName
@vindex KernalNOName
@vindex KernalSEName
@item KernalIntName
@itemx KernalDEName
@itemx KernalFIName
@itemx KernalFRName
@itemx KernalITName
@itemx KernalNOName
@itemx KernalSEName
Strings specifying the filename of the Kernal ROM images.

@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
Boolean, enables the internal function ROM.
@vindex InternalFunctionName
@item InternalFunctionName
Strings specifying the filename of the ROM image for the internal function ROM.

@vindex ExternalFunctionROM
@item ExternalFunctionROM
Boolean, enables the external function ROM.
@vindex ExternalFunctionName
@item ExternalFunctionName
Strings specifying the filename of the ROM image for the external function ROM.

@end table

@c @node FIXME
@subsubsection C128 system ROM command-line options

@table @code

@cindex -basic64
@item -basic64 <name>
Specify name of C64 mode BASIC ROM image
@cindex -kernal64
@item -kernal64 <name>
Specify name of C64 mode Kernal ROM image

@cindex -basiclo
@item -basiclo <name>
Specify name of BASIC ROM image (lower part)
@cindex -basichi
@item -basichi <name>
Specify name of BASIC ROM image (higher part)

@cindex -kernal
@item -kernal <name>
Specify name of international Kernal ROM image
@cindex -kernalde
@item -kernalde <name>
Specify name of German Kernal ROM image
@cindex -kernalfi
@item -kernalfi <name>
Specify name of Finnish Kernal ROM image
@cindex -kernalfr
@item -kernalfr <name>
Specify name of French Kernal ROM image
@cindex -kernalit
@item -kernalit <name>
Specify name of Italian Kernal ROM image
@cindex -kernalno
@item -kernalno <name>
Specify name of Norwegian Kernal ROM image
@cindex -kernalse
@item -kernalse <name>
Specify name of Swedish Kernal ROM image

@cindex -chargen
@item -chargen <name>
Specify name of international character generator ROM image
@cindex -chargde
@item -chargde <name>
Specify name of German character generator ROM image
@cindex -chargfr
@item -chargfr <name>
Specify name of French character generator ROM image
@cindex -chargse
@item -chargse <name>
Specify name of Swedish character generator ROM image

@cindex -intfunc
@item -intfunc
@itemx +intfunc
Enable/Disable the internal Function ROM (0: None, 1: ROM, 2: RAM, 3: RTC)
@cindex -intfrom
@item -intfrom <name>
Specify name of internal Function ROM image

@cindex -extfunc
@item -extfunc
@itemx +extfunc
Enable/Disable the external Function ROM (0: None, 1: ROM, 2: RAM, 3: RTC)
@cindex -extfrom
@item -extfrom <name>
Specify name of external Function ROM image

@end table

@c @node FIXME
@subsection C128 settings

@c @node FIXME
@subsubsection C128 resources

@table @code

@vindex 40/80ColumnKey
@item 40/80ColumnKey
Boolean, status of the 40/80 columns key
@vindex Go64Mode
@item Go64Mode
Boolean, if true enter C64 mode on reset
@vindex C128FullBanks
@item C128FullBanks
Boolean, enables Banks 2 and 3.
@vindex MachineType
@item MachineType
Integer specifying the C128 machine type. (0: Internatinal, 1: Finnish, 2: French,
3: German, 4: Italian, 5: Norwegian, 6: Swedish)
@end table

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

@table @code

@cindex -40col
@item -40col
Activate 40 column mode
@cindex -80col
@item -80col
Activate 80 column mode

@cindex -go64, +go64
@item -go64
Always switch to C64 mode on reset
@item +go64
Always switch to C128 mode on reset

@end table

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

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

@menu
* C64DTV ROM image::
* DTV revision::
* LumaFix::
* Userport::
* Debug::
* Monitor DTV features::
@end menu


@node C64DTV ROM image, DTV revision, C64DTV-specific, C64DTV-specific
@subsection C64DTV ROM image

The DTV has a 2MB Flash chip which contains the kernal, basic and
character set ROMs along with other data, such as games in the case of
the original C64DTV ROM.

The image file is a dump of the flash chip. It is exactly 2MB (2097152 bytes).

If you do not have a suitable image file, an image using the C64 kernal,
basic and charset is automatically created.

If writing to the C64DTV ROM is enabled, the image file is rewritten with
the current data when exiting x64dtv.

Note that x64dtv tries to load the image file from the C64DTV
directory first, and if it isn't found there, x64dtv tries to
load it from the current directory. If you do not have @file{dtvrom.bin}
in your C64DTV directory and writing to DTV ROM is enabled,
the @file{dtvrom.bin} file is created to the current directory.

NOTE: The original C64DTV ROM has somewhat distorted colors,
normally you should use a patched rom.

@table @code

@cindex -c64dtvromimage
@item -c64dtvromimage NAME
Specify @file{NAME} as the C64DTV ROM image

@cindex -c64dtvromrw, +c64dtvromrw
@item -c64dtvromrw
@itemx +c64dtvromrw
Enable or disable writing to C64DTV ROM image

@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

@cindex -trueflashfs, +trueflashfs
@item -trueflashfs
@itemx +trueflashfs
Enable or disable true hardware flash file system

@cindex -fsflash
@item -fsflash NAME
Specify @file{NAME} as directory for flash file system device

@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

@cindex -dtvrev
@item -dtvrev REVISION
Specify DTV @file{REVISION} (2 or 3)

@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

@cindex -hummeradc, +hummeradc
@item -hummeradc
@itemx +hummeradc
Enable/Disable Hummer ADC

@cindex -ps2mouse, +ps2mouse
@item -ps2mouse
@itemx +ps2mouse
Enable or disable PS/2 mouse on userport

@end table


@node Debug, Monitor DTV features, Userport, C64DTV-specific
@subsection Debug

Debugging information on Blitter, DMA and Flash can be enabled with command
line parameters. This can be useful for DTV software development.

@table @code

@cindex -dtvblitterlog, +dtvblitterlog
@item -dtvblitterlog
@itemx +dtvblitterlog
Enable or disable DTV Blitter log

@cindex -dtvdmalog, +dtvdmalog
@item -dtvdmalog
@itemx +dtvdmalog
Enable or disable DTV DMA log

@cindex -dtvflashlog, +dtvflashlog
@item -dtvflashlog
@itemx +dtvflashlog
Enable or disable DTV Flash log

@end table


@node Monitor DTV features, , Debug, C64DTV-specific
@subsection Monitor DTV features

Currently the registers A, Y and X are registers R0, R1 and R2 regardless of
the mapping, which can be seen and modified via the registers ACM and XYM.

The monitor can access all 2MB of RAM and 2MB of Flash, but only 64 kB at a time.
The 64kB bank can be selected with "bank ram00".."ram1f" for RAM and
"bank rom00".."rom1f" for Flash.

The "load" command can load large files (>64kB) correctly if the bank is set
to "ramXX", where XX is the starting bank (usually "bank00").

@c @node FIXME
@subsection DTV resources

@table @code

@vindex DtvRevision
@item DtvRevision
Integer specifying the emulated DTV revision (2: DTV2, 3: DTV3)

@vindex 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, enables Hummer ADC emulation.

@vindex ps2mouse
@item ps2mouse
Boolean, enables 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.

@end table

@node VIC20-specific, PET-specific, C64DTV-specific, Machine-specific features
@section VIC20-specific commands and settings

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

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


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

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

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

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

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

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

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

@c @node FIXME
@subsection VIC20 cartridge settings

@c @node FIXME
@subsubsection VIC20 cartridge resources

@table @code

@vindex CartridgeReset
@item CartridgeReset
Boolean specifying whether the machine should be resetted when a cartridge is
changed.
@vindex CartridgeType
@item CartridgeType
Integer specifying the type of cartridge emulated.
@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
String specifying the name of the respective cartridge ROM images.

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

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

@vindex MegaCartNvRAMfilename
@item MegaCartNvRAMfilename
String specifying the filename of the MegaCart NvRAM image.
@vindex MegaCartNvRAMWriteBack
@item MegaCartNvRAMWriteBack
Boolean, if true write back the NvRAM image file automatically, incase the RAM
contents changed, when detaching or quitting the emulator.

@vindex TFEIOSwap
@item TFEIOSwap
Boolean, swap/don't swap io mapping (map cart I/O to VIC20 I/O-2)
@vindex SFXSoundExpanderIOSwap
@item SFXSoundExpanderIOSwap
Boolean, swap/don't swap io mapping (map cart I/O to VIC20 I/O-2)
@vindex SFXSoundSamplerIOSwap
@item SFXSoundSamplerIOSwap
Boolean, swap/don't swap io mapping (map cart I/O to VIC20 I/O-2)
@vindex GEORAMIOSwap
@item GEORAMIOSwap
Boolean, swap/don't swap  io mapping (map cart I/O-1 to VIC20 I/O-3 and cart I/O-2 to VIC20 I/O-2)

@vindex SidCart
@item SidCart
Boolean, enables SID cart emulation.
@vindex SidAddress
@item SidAddress
Integer that specifies the base address of the emulated SID chip.
@vindex SidClock
@item SidClock
Integer specifying the clock rate used for the emulated SID chip (0: C64, 1: VIC-20)

@end table

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

@table @code

@cindex -iocollision
@item -iocollision <method>
Select 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

@cindex -cart2
@item -cart2 <name>
Specify 4/8/16K extension ROM name at $2000
@cindex -cart4
@item -cart4 <name>
Specify 4/8/16K extension ROM name at $4000
@cindex -cart6
@item -cart6 <name>
Specify 4/8/16K extension ROM name at $6000
@cindex -cartA
@item -cartA <name>
Specify 4/8K extension ROM name at $A000
@cindex -cartB
@item -cartB <name>
Specify 4K extension ROM name at $B000
@cindex -cartgeneric
@item -cartgeneric <name>
Specify generic extension ROM name

@cindex -cartmega
@item -cartmega <name>
Specify Mega-Cart extension ROM name
@cindex -mcnvramfile
@item -mcnvramfile <name>
Set Mega-Cart NvRAM filename
@cindex -mcnvramwriteback, +mcnvramwriteback
@item -mcnvramwriteback
@itemx +mcnvramwriteback
Enable/Disable Mega-Cart NvRAM writeback

@cindex -cartfe
@item -cartfe <name>
Specify Final Expansion extension ROM name
@cindex -fewriteback, +fewriteback
@item -fewriteback
@itemx +fewriteback
Enable/Disable Final Expansion write back to ROM file

@cindex -cartfp
@item -cartfp <name>
Specify Vic Flash Plugin extension ROM name
@cindex -fpwriteback, +fpwriteback
@item -fpwriteback
@itemx +fpwriteback
Enable/Disable Vic Flash Plugin write back to ROM file

@cindex -ieee488, +ieee488
@item -ieee488
@itemx +ieee488
Enable/Disable VIC-1112 IEEE488 interface

@cindex -sidcart, +sidcart
@item -sidcart
@item +sidcart
Enable/Disable SID Cartridge

@cindex -tfeioswap, +tfeioswap
@item -tfeioswap
@itemx +tfeioswap
Swap/don't swap io mapping (map cart I/O to VIC20 I/O-2)
@cindex -tfe, +tfe
@item -tfe
@itemx +tfe
Enable/Disable the TFE ("The Final Ethernet") unit
@cindex -tfeif
@item -tfeif <name>
Set the system ethernet interface for TFE emulation
@cindex -tferrnet, +tferrnet
@item -tferrnet
@itemx +tferrnet
Enable/Disable RRNet mode of TFE emulation

@cindex -digimax, +digimax
@item -digimax
@itemx +digimax
Enable/Disable the DigiMAX cartridge
@cindex -digimaxbase
@item -digimaxbase <base address>
Base address of the DigiMAX cartridge

@cindex -sfxseioswap, +sfxseioswap
@item -sfxseioswap
@itemx +sfxseioswap
Swap/don't swap io mapping (map cart I/O to VIC20 I/O-2)
@cindex -sfxse, +sfxse
@item -sfxse
@itemx +sfxse
Enable/Disable the SFX soundexpander cartridge
@cindex -sfxsetype
@item -sfxsetype <type>
Set YM chip type (3526 / 3812)

@cindex -sfxssioswap, +sfxssioswap
@item -sfxssioswap
@itemx +sfxssioswap
Swap/don't swap io mapping (map cart I/O to VIC20 I/O-2)
@cindex -sfxss, +sfxss
@item -sfxss
@itemx +sfxss
Enable/Disable the SFX Sound Sampler cartridge

@cindex -georamioswap, +georamioswap
@item -georamioswap
@itemx +georamioswap
Swap/don't swap  io mapping (map cart I/O-1 to VIC20 I/O-3 and cart I/O-2 to VIC20 I/O-2)
@cindex -georam, +georam
@item -georam
@itemx +georam
Enable/Disable the GEORAM expansion unit
@cindex -georamimage
@item -georamimage <name>
Specify name of GEORAM image
@cindex -georamimagerw, +georamimagerw
@item -georamimagerw
@itemx +georamimagerw
Allow/Disallow writing to GEORAM image
@cindex -georamsize
@item -georamsize <size in KB>
Size of the GEORAM expansion unit

@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 VICHwScale
@item VICHwScale
Boolean specifying whether to enable or disable hardware scaling

@vindex VICFullscreenDevice
@item VICFullscreenDevice
fullscreen device

@vindex VICFullscreen
@item VICFullscreen
Boolean specifying whether to use fullscreen mode or not.

@vindex VICFullscreenStatusbar
@item VICFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not.

@vindex VICXRANDRFullscreenMode
@item VICXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode

@vindex VICVidmodeFullscreenMode
@item VICVidmodeFullscreenMode
integer specifying Vidmode fullscreen mode

@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 [1000] <0-2000>

@vindex VICColorContrast
@item VICColorContrast
integer specifying contrast of internal calculated palette [1000] <0-2000>

@vindex VICColorBrightness
@item VICColorBrightness
integer specifying brightness of internal calculated palette [1000] <0-2000>

@vindex VICColorGamma
@item VICColorGamma
integer specifying gamma of internal calculated palette [2200] <0-4000>

@vindex VICColorTint
@item VICColorTint
integer specifying tint of internal calculated palette [1000] <0-2000>

@vindex VICPALScanLineShade
@item VICPALScanLineShade
integer specifying amount of scan line shading for the CRT emulation [667] <0-1000>

@vindex VICPALBlur
@item VICPALBlur
integer specifying amount of horizontal blur for the CRT emulation. [500] <0-1000>

@vindex VICPALOddLinePhase
@item VICPALOddLinePhase
integer specifying phase offset for color carrier in odd lines [750] <0-2000>

@vindex VICPALOddLineOffset
@item VICPALOddLineOffset
integer specifying phase for color carrier in odd lines [1250] <0-2000>

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

@vindex VICFilter
@item VICFilter
integer specifying 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

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

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

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

@cindex -VIChwscale, +VIChwscale
@item -VIChwscale
@item +VIChwscale
Enable/Disable hardware scaling

@cindex -VICfilter
@item -VICfilter <Mode>
Select rendering filter, 0:none, 1:CRT emulation, 2: scale2x

@cindex -VICpalette
@item -VICpalette NAME
Specify @code{NAME} as the palette file (@code{VICPaletteFile}).

@cindex -VICintpal
@item -VICintpal
Use an internal calculated palette
@cindex -VICextpal
@item -VICextpal
Use an external palette (file)
@cindex -VICfulldevice
@item -VICfulldevice <device>
Select fullscreen device
@cindex -VICXRANDRfullmode
@item -VICXRANDRfullmode <mode>
Select fullscreen mode
@cindex -VICVidmodefullmode
@item -VICVidmodefullmode <mode>
Select fullscreen mode
@cindex -VICborders
@item -VICborders <mode>
Set VIC border display mode (0: normal, 1: full, 2: debug, 3:none)

@cindex -VICsaturation
@item -VICsaturation <0-2000>
Set saturation of internal calculated palette [1000]
@cindex -VICcontrast
@item -VICcontrast <0-2000>
Set contrast of internal calculated palette [1000]
@cindex -VICbrightness
@item -VICbrightness <0-2000>
Set brightness of internal calculated palette [1000]
@cindex -VICgamma
@item -VICgamma <0-4000>
Set gamma of internal calculated palette [2200]
@cindex -VICtint
@item -VICtint <0-2000>
Set tint of internal calculated palette [1000]
@cindex -VICoddlinesphase
@item -VICoddlinesphase <0-2000>
Set phase for color carrier in odd lines [1250]
@cindex -VICoddlinesoffset
@item -VICoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines [750]
@cindex -VICcrtblur
@item -VICcrtblur <0-1000>
Amount of horizontal blur for the CRT emulation. [500]
@cindex -VICcrtscanlineshade
@item -VICcrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation [667]

@cindex -VICaudioleak, +VICaudioleak
@item -VICaudioleak
@item +VICaudioleak
Enable/Disable video to audio leak emulation.

@end table


@node VIC20 memory expansions, VIC20 system ROM settings, VIC20 cartridges, VIC20-specific
@subsection Changing memory configuration

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

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

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

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

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

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

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

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

@table @code

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

@end table

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

@table @code

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

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

For example,

@example
xvic -memory none
@end example

gives an unexpanded VIC20.  While

@example
xvic -memory 60,a0
@end example

or

@example
xvic -memory 3,5
@end example

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

@end table


@node VIC20 system ROM settings,  , VIC20 memory expansions, VIC20-specific
@subsection VIC20 system ROM settings

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

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

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

@table @code

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

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

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

@end table

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

@table @code

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

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

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

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

@end table

@c @node FIXME
@subsection VIC20 settings

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

@table @code

@cindex -OEMjoy, +OEMjoy
@item -OEMjoy
@item +OEMjoy
Enable/Disable the OEM userport joystick adapter

@end table

@c @node FIXME
@section PLUS4-specific commands and settings

@c @node FIXME
@subsection TED settings

@c @node FIXME
@subsubsection TED resources

@table @code
@vindex TEDVideoCache
@item TEDVideoCache
Boolean specifying whether the video cache is turned on.

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

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

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

@vindex TEDHwScale
@item TEDHwScale
Boolean specifying whether to enable or disable hardware scaling

@vindex TEDFullscreenDevice
@item TEDFullscreenDevice
fullscreen device

@vindex TEDFullscreen
@item TEDFullscreen
Boolean specifying whether to use fullscreen mode or not.

@vindex TEDFullscreenStatusbar
@item TEDFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not.

@vindex TEDXRANDRFullscreenMode
@item TEDXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode

@vindex TEDVidmodeFullscreenMode
@item TEDVidmodeFullscreenMode
integer specifying Vidmode fullscreen mode

@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 [1000] <0-2000>

@vindex TEDColorContrast
@item TEDColorContrast
integer specifying contrast of internal calculated palette [1000] <0-2000>

@vindex TEDColorBrightness
@item TEDColorBrightness
integer specifying brightness of internal calculated palette [1000] <0-2000>

@vindex TEDColorGamma
@item TEDColorGamma
integer specifying gamma of internal calculated palette [2200] <0-4000>

@vindex TEDColorTint
@item TEDColorTint
integer specifying tint of internal calculated palette [1000] <0-2000>

@vindex TEDPALScanLineShade
@item TEDPALScanLineShade
integer specifying amount of scan line shading for the CRT emulation [667] <0-1000>

@vindex TEDPALBlur
@item TEDPALBlur
integer specifying amount of horizontal blur for the CRT emulation. [500] <0-1000>

@vindex TEDPALOddLinePhase
@item TEDPALOddLinePhase
integer specifying phase offset for color carrier in odd lines [750] <0-2000>

@vindex TEDPALOddLineOffset
@item TEDPALOddLineOffset
integer specifying phase for color carrier in odd lines [1250] <0-2000>

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

@vindex TEDFilter
@item TEDFilter
integer specifying rendering filter, 0:none, 1:CRT emulation, 2: scale2x

@vindex TEDBorderMode
@item TEDBorderMode
integer specifying border display mode (0: normal, 1: full, 2: debug, 3:none)

@end table

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

@table @code
@cindex -TEDvcache, +TEDvcache
@item -TEDvcache
@itemx +TEDvcache
Enable/Disable the video cache
@cindex -TEDdsize, +TEDdsize
@item -TEDdsize
@itemx +TEDdsize
Enable/Disable double size
@cindex -TEDdscan, +TEDdscan
@item -TEDdscan
@itemx +TEDdscan
Enable/Disable double scan
@cindex -TEDfilter
@item -TEDfilter <Mode>
Select rendering filter, 0:none, 1:CRT emulation, 2: scale2x
@cindex -TEDhwscale, +TEDhwscale
@item -TEDhwscale
@itemx +TEDhwscale
Enable/Disable hardware scaling
@cindex -TEDintpal
@item -TEDintpal
Use an internal calculated palette
@cindex -TEDextpal
@item -TEDextpal
Use an external palette (file)
@cindex -TEDpalette
@item -TEDpalette <name>
Specify name of file of external palette
@cindex -TEDfulldevice
@item -TEDfulldevice <device>
Select fullscreen device
@cindex -TEDXRANDRfullmode
@item -TEDXRANDRfullmode <mode>
Select fullscreen mode
@cindex -TEDVidmodefullmode
@item -TEDVidmodefullmode <mode>
Select fullscreen mode
@cindex -TEDborders
@item -TEDborders <mode>
Set TED border display mode (0: normal, 1: full, 2: debug, 3:none)

@cindex -TEDsaturation
@item -TEDsaturation <0-2000>
Set saturation of internal calculated palette [1000]
@cindex -TEDcontrast
@item -TEDcontrast <0-2000>
Set contrast of internal calculated palette [1000]
@cindex -TEDbrightness
@item -TEDbrightness <0-2000>
Set brightness of internal calculated palette [1000]
@cindex -TEDgamma
@item -TEDgamma <0-4000>
Set gamma of internal calculated palette [2200]
@cindex -TEDtint
@item -TEDtint <0-2000>
Set tint of internal calculated palette [1000]
@cindex -TEDoddlinesphase
@item -TEDoddlinesphase <0-2000>
Set phase for color carrier in odd lines [1250]
@cindex -TEDoddlinesoffset
@item -TEDoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines [750]
@cindex -TEDcrtblur
@item -TEDcrtblur <0-1000>
Amount of horizontal blur for the CRT emulation. [500]
@cindex -TEDcrtscanlineshade
@item -TEDcrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation [667]

@cindex -TEDaudioleak, +TEDaudioleak
@item -TEDaudioleak
@item +TEDaudioleak
Enable/Disable video to audio leak emulation.

@end table

@c @node FIXME
@subsection PLUS4 I/O extension settings

@c @node FIXME
@subsubsection PLUS4 I/O extension resources

@table @code

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

@vindex DIGIBLASTER
@item DIGIBLASTER
Boolean, enables Digiblaster emulation.

@vindex SpeechEnabled
@item SpeechEnabled
Boolean, enables emulation of the V364 speech chip.
@vindex SpeechImage
@item SpeechImage
String specifying the filename of the speech ROM image.

@vindex SidCart
@item SidCart
Boolean, enables emulation of the SID-Cart
@vindex SidAddress
@item SidAddress
Integer that specifies the base address of the emulated SID chip.
@vindex SidClock
@item SidClock
Integer specifying the clock rate used for the emulated SID chip (0: C64, 1: Plus4)
@vindex SIDCartJoy
@item SIDCartJoy
Boolean, enables emulation of the SID-Cart joystick

@end table

@c @node FIXME
@subsubsection PLUS4 I/O extension command-line options

@table @code

@cindex -cartreset, +cartreset
@item -cartreset
@itemx +cartreset
Do/don't reset machine if a cartridge is attached or detached
@cindex -cart
@item -cart <Name>
Smart-attach cartridge image
@cindex +cart
@item +cart
Disable default cartridge

@cindex -digiblaster, +digiblaster
@item -digiblaster
@itemx +digiblaster
Enable/Disable the digiblaster add-on

@cindex -sidcart, +sidcart
@item -sidcart
@item +sidcart
Enable/Disable SID Cartridge

@cindex -sidcartjoy, +sidcartjoy
@item -sidcartjoy
@item +sidcartjoy
Enable/Disable SID cartridge joystick

@cindex -speech, +speech
@item -speech
@itemx +speech
Enable/Disable the v364 speech add-on

@cindex -speechrom
@item -speechrom <name>
Attach Speech ROM image

@end table

@c @node FIXME
@subsection PLUS4 system ROM settings

@c @node FIXME
@subsubsection PLUS4 system ROM resources

@table @code

@vindex FunctionLowName
@item FunctionLowName
String specifying the filenames of the Lo Function ROM.
@vindex FunctionHighName
@item FunctionHighName
String specifying the filenames of the High Function ROM.

@vindex c1loName
@item c1loName
String specifying the filenames of cartridge 1 Lo ROM.
@vindex c1hiName
@item c1hiName
String specifying the filenames of cartridge 1 High ROM.
@vindex c2loName
@item c2loName
String specifying the filenames of cartridge 2 Lo ROM.
@vindex c2hiName
@item c2hiName
String specifying the filenames of cartridge 2 High ROM.

@end table

@c @node FIXME
@subsubsection PLUS4 system ROM command-line options

@table @code

@cindex -functionlo
@item -functionlo <name>
Specify name of Function low ROM image
@cindex -functionhi
@item -functionhi <name>
Specify name of Function high ROM image

@cindex -c1lo
@item -c1lo <name>
Specify name of Cartridge 1 low ROM image
@cindex -c1hi
@item -c1hi <name>
Specify name of Cartridge 1 high ROM image
@cindex -c2lo
@item -c2lo <name>
Specify name of Cartridge 2 low ROM image
@cindex -c2hi
@item -c2hi <name>
Specify name of Cartridge 2 high ROM image

@end table

@c @node FIXME
@subsection PLUS4 settings

@c @node FIXME
@subsubsection PLUS4 resources

@table @code

@vindex H256K
@item H256K
Integer, enables the HANNES 256K RAM expansion (0: disabled, 1: 256kB, 2: 1024kB,
3: 4096kB)

@vindex CS256K
@item CS256K
Boolean, enables the CSORY 256K RAM expansion

@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

@cindex -ramsize
@item -ramsize <ramsize>
Specify size of RAM installed in kb (16/32/64)

@cindex -h256k
@item -h256k
Enable the HANNES 256K RAM expansion
@cindex -h1024k
@item -h1024k
Enable the HANNES 1024K RAM expansion
@cindex -h4096k
@item -h4096k
Enable the HANNES 4096K RAM expansion
@cindex -cs256k
@item -cs256k
Enable the CSORY 256K RAM expansion

@cindex -acia, +acia
@item -acia
@itemx +acia
Enable/Disable the ACIA emulation

@end table

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

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

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

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

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

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

@table @code

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@end table

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

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

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

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

@c @node FIXME
@subsection CRTC Settings

@c @node FIXME
@subsubsection CRTC resources

@table @code

@vindex Crtc
@item Crtc
Enables 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 CrtcHwScale
@item CrtcHwScale
Boolean specifying whether to enable or disable hardware scaling

@vindex CrtcFullscreenDevice
@item CrtcFullscreenDevice
fullscreen device

@vindex CrtcFullscreen
@item CrtcFullscreen
Boolean specifying whether to use fullscreen mode or not.

@vindex CrtcFullscreenStatusbar
@item CrtcFullscreenStatusbar
Boolean specifying whether to show the status bar in fullscreen mode or not.

@vindex CrtcXRANDRFullscreenMode
@item CrtcXRANDRFullscreenMode
integer specifying XRANDR fullscreen mode

@vindex CrtcVidmodeFullscreenMode
@item CrtcVidmodeFullscreenMode
integer specifying Vidmode fullscreen mode

@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 [1000] <0-2000>

@vindex CrtcColorContrast
@item CrtcColorContrast
integer specifying contrast of internal calculated palette [1000] <0-2000>

@vindex CrtcColorBrightness
@item CrtcColorBrightness
integer specifying brightness of internal calculated palette [1000] <0-2000>

@vindex CrtcColorGamma
@item CrtcColorGamma
integer specifying gamma of internal calculated palette [2200] <0-4000>

@vindex CrtcColorTint
@item CrtcColorTint
integer specifying tint of internal calculated palette [1000] <0-2000>

@vindex CrtcPALScanLineShade
@item CrtcPALScanLineShade
integer specifying amount of scan line shading for the CRT emulation [667] <0-1000>

@vindex CrtcPALBlur
@item CrtcPALBlur
integer specifying amount of horizontal blur for the CRT emulation. [500] <0-1000>

@vindex CrtcPALOddLinePhase
@item CrtcPALOddLinePhase
integer specifying phase offset for color carrier in odd lines [750] <0-2000>

@vindex CrtcPALOddLineOffset
@item CrtcPALOddLineOffset
integer specifying phase for color carrier in odd lines [1250] <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
@cindex -Crtcvcache, +Crtcvcache
@item -Crtcvcache
@itemx +Crtcvcache
Enable/Disable the video cache
@cindex -Crtcdsize, +Crtcdsize
@item -Crtcdsize
@itemx +Crtcdsize
Enable/Disable double size
@cindex -CRTCstretchvertical, +CRTCstretchvertical
@item -CRTCstretchvertical
@itemx +CRTCstretchvertical
Enable/Disable vertical stretching
@cindex -Crtcdscan, +Crtcdscan
@item -Crtcdscan
@itemx +Crtcdscan
Enable/Disable double scan
@cindex -Crtcfilter
@item -Crtcfilter <Mode>
Select rendering filter, 0:none, 1:CRT emulation, 2: scale2x
@cindex -Crtchwscale, +Crtchwscale
@item -Crtchwscale
@itemx +Crtchwscale
Enable/Disable hardware scaling
@cindex -Crtcintpal
@item -Crtcintpal
Use an internal calculated palette
@cindex -Crtcextpal
@item -Crtcextpal
Use an external palette (file)
@cindex -Crtcpalette
@item -Crtcpalette NAME
Specify @code{NAME} as the palette file (@code{CrtcPaletteFile}).
@cindex -Crtcfulldevice
@item -Crtcfulldevice <device>
Select fullscreen device
@cindex -CrtcXRANDRfullmode
@item -CrtcXRANDRfullmode <mode>
Select fullscreen mode
@cindex -CrtcVidmodefullmode
@item -CrtcVidmodefullmode <mode>
Select fullscreen mode

@cindex -Crtcsaturation
@item -Crtcsaturation <0-2000>
Set saturation of internal calculated palette [1000]
@cindex -Crtccontrast
@item -Crtccontrast <0-2000>
Set contrast of internal calculated palette [1000]
@cindex -Crtcbrightness
@item -Crtcbrightness <0-2000>
Set brightness of internal calculated palette [1000]
@cindex -Crtcgamma
@item -Crtcgamma <0-4000>
Set gamma of internal calculated palette [2200]
@cindex -Crtctint
@item -Crtctint <0-2000>
Set tint of internal calculated palette [1000]
@cindex -Crtcoddlinesphase
@item -Crtcoddlinesphase <0-2000>
Set phase for color carrier in odd lines [1250]
@cindex -Crtcoddlinesoffset
@item -Crtcoddlinesoffset <0-2000>
Set phase offset for color carrier in odd lines [750]
@cindex -Crtccrtblur
@item -Crtccrtblur <0-1000>
Amount of horizontal blur for the CRT emulation. [500]
@cindex -Crtccrtscanlineshade
@item -Crtccrtscanlineshade <0-1000>
Amount of scan line shading for the CRT emulation [667]

@cindex -Crtcaudioleak, +Crtcaudioleak
@item -Crtcaudioleak
@item +Crtcaudioleak
Enable/Disable video to audio leak emulation.

@end table

@c @node FIXME
@subsection PET I/O extension settings

@c @node FIXME
@subsubsection PET I/O extension resources

@table @code

@vindex PETREU
@item PETREU
Boolean specifying whether PET REU emulation is enabled.
@vindex PETREUfilename
@item PETREUfilename
String specifying the filename of the PET REU image.
@vindex PETREUsize
@item PETREUsize
Integer specifying the size of the emulated PET REU in KB (128, 512, 1024, 2048)

@vindex PETDWW
@item PETDWW
Boolean specifying whether DWW emulation is enabled.
@vindex PETDWWfilename
@item PETDWWfilename
String specifying the filename of the DWW image RAM image.

@vindex UserportDAC
@item UserportDAC
Boolean specifying whether userport DAC emulation is enabled.

@vindex SidCart
@item SidCart
Boolean specifying whether SID Cart emulation is enabled.
@vindex SidAddress
@item SidAddress
Integer that specifies the base address of the emulated SID chip.
@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

@cindex -petreu, +petreu
@item -petreu
@itemx +petreu
Enable or disable the PET Memory Expansion Unit.

@cindex -petreuimage
@item -petreuimage <name>
Specify name of PET Ram and Expansion Unit image
@cindex -petreuramsize
@item -petreuramsize <size in KB>
Size of the PET Ram and Expansion Unit

@cindex -userportdac, +userportdac
@item -userportdac, +userportdac
Enable or disable the userport DAC.

@cindex -petdww, +petdww
@item -petdww
@itemx +petdww
Enable/Disable the PET DWW hi-res board
@cindex -petdwwimage
@item -petdwwimage <name>
Specify name of PET DWW image

@cindex -sidcart, +sidcart
@item -sidcart
@item +sidcart
Enable/Disable SID Cartridge

@end table

@c @node FIXME
@subsection PET system ROM settings

@c @node FIXME
@subsubsection PET system ROM resources

@table @code

@vindex H6809RomAName
@vindex H6809RomBName
@vindex H6809RomCName
@vindex H6809RomDName
@vindex H6809RomEName
@vindex H6809RomFName
@item H6809RomAName
@itemx H6809RomBName
@itemx H6809RomCName
@itemx H6809RomDName
@itemx H6809RomEName
@itemx H6809RomFName
Strings specifying the filenames of the respective H6809 ROM images,
relevant for the SuperPET.

@end table

@c @node FIXME
@subsubsection PET system ROM command-line options

@table @code

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

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

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

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

@cindex -6809romA
@item -6809romA <Name>
Specify 4K to 24K ROM file name at $A000 for 6809
@cindex -6809romB
@item -6809romB <Name>
Specify 4K to 20K ROM file name at $B000 for 6809
@cindex -6809romC
@item -6809romC <Name>
Specify 4K to 16K ROM file name at $C000 for 6809
@cindex -6809romD
@item -6809romD <Name>
Specify 4K to 12K ROM file name at $D000 for 6809
@cindex -6809romE
@item -6809romE <Name>
Specify 2K or 8K ROM file name at $E000 for 6809
@cindex -6809romF
@item -6809romF <Name>
Specify 4K ROM file name at $F000 for 6809

@end table

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

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

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

@c @node FIXME
@subsection PET settings

@c @node FIXME
@subsubsection PET resources

@table @code

@vindex CPUswitch
@item CPUswitch
Integer specifying the status of the SuperPET CPU switch (0: 6502, 1: 6809, 2: PROG)

@end table

@c FIXME: relink this node
@node PET commandline options, PET colors, PET diagnostic pin, PET-specific
@subsubsection PET command line options

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

@table @code

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

@cindex -petram9, +petram9
@item -petram9, +petram9
Switch on RAM mapping on addresses
$9000-$9fff (@code{Ram9}).

@cindex -petramA, +petramA
@item -petramA, +petramA
Switch on RAM mapping on addresses
$a000-$afff (@code{RamA}).

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

@cindex -cpu6502
@item -cpu6502
Set SuperPET CPU switch to '6502'
@cindex -cpu6809
@item -cpu6809
Set SuperPET CPU switch to '6809'
@cindex -cpuprog
@item -cpuprog
Set SuperPET CPU switch to 'Prog'

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

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

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

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

@end table

@node PET colors,  , PET commandline options, PET-specific
@subsection Changing screen colors

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

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

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

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

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

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

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

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

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

@table @code

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

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

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

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

@end table

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

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

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

@b{Warning:} At this time the 5x0 and other machines are implemented
in different executables, so switching between those models is not possible.

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

@c @node FIXME
@subsection CBM-II system ROM settings

@c @node FIXME
@subsubsection CBM-II system ROM resources

@c @node FIXME
@subsubsection CBM-II system ROM command line options

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

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

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

@cindex -cart1
@item -cart1 <name>
Specify @file{NAME} as the ROM image file for the
cartridge area $1000-$1FFF (@code{Cart1Name}).
@cindex -cart2
@item -cart2 <name>
Specify @file{NAME} as the ROM image file for the
cartridge area $2000-$3fff (@code{Cart2Name}).
@cindex -cart4
@item -cart4 <name>
Specify @file{NAME} as the ROM image file for the
cartridge area $4000-$5fff (@code{Cart4Name}).
@cindex -cart6
@item -cart6 <name>
Specify @file{NAME} as 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

@cindex -ramsize
@item -ramsize <ramsize>
Specify size of RAM (64/128/256/512/1024 kByte)

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

@cindex -model
@item -model <modelnumber>
Specify CBM-II model to emulate

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

@c @node FIXME
@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.

@end table

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

@table @code

@cindex -keepenv
@item -keepenv
Override PSID settings for Video standard and SID model
@cindex -tune <number>
@item -tune <number>
Specify PSID tune <number>

@end table

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The modules in the x64 emulator are:

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

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

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

The modules in the x128 emulator are:

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

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

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

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

The modules in the xvic emulator are:

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

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

The modules in the xpet emulator are:

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

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

The modules in the xcbm2 and xcbm5x0 emulators are:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item DWORD
@tab CLK
@tab the current CPU clock value.  All other clock values are relative to this.
@item WORD
@tab X
@tab The X register
@item WORD
@tab Y
@tab The Y register
@item WORD
@tab U
@tab The U register
@item WORD
@tab PC
@tab The Program Counter register
@item BYTE
@tab DP
@tab The Direct Page register
@item BYTE
@tab CC
@tab The Condition Code register
@item BYTE
@tab A
@tab The A register
@item BYTE
@tab B
@tab The B register
@item 
@tab 
@tab The following are for 6309 compatibility:
@item WORD
@tab V
@tab The V register
@item BYTE
@tab E
@tab The E register
@item BYTE
@tab F
@tab The F register
@end multitable

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

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

Version numbers: Major 1, Minor 1.

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

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

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

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

Version numbers: Major 1, Minor 0.

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

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

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

Version numbers: Major 1, Minor 0.

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

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

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

Version numbers: Major 1, Minor 0.

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

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

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

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

Version numbers: Major 0, Minor 0.

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

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

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

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

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

Version numbers: Major 1, Minor 0.

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

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

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

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

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

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

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

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

Version numbers: Major 1, Minor 1.

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

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

Version numbers: Major 0, Minor 0.

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

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

The C64 memory module actually consists of two modules.  The "C64MEM" module
is mandatory and contains the RAM dump.  The "C64ROM" module is optional
and contains a dump of the ROM images.

The size of the C64 memory modules differs with each different memory
configuration. The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded. The attached cartridges are
@b{not yet(!)} saved and not yet restored upon load.

Version numbers: Major 0, Minor 0

@b{The C64MEM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CPUDATA
@tab CPU port data byte
@item BYTE
@tab CPUDIR
@tab CPU port direction byte
@item BYTE
@tab EXROM
@tab state of the EXROM line (?)
@item BYTE
@tab GAME
@tab state of the GAME line (?)
@item ARRAY
@tab RAM
@tab 64k RAM dump
@end multitable

@b{The C64ROM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item ARRAY
@tab KERNAL
@tab 8k dump of the kernal ROM
@item ARRAY
@tab BASIC
@tab 8k dump of the basic ROM
@item ARRAY
@tab CHARGEN
@tab 4k dump of the chargen ROM
@end multitable

@node C128 memory module, VIC20 memory module, C64 memory module, Module formats
@subsubsection C128 memory module

The C128 memory module actually consists of two modules.  The "C128MEM" module
is mandatory and contains the RAM dump.  The "C128ROM" module is optional
and contains a dump of the ROM images.

The size of the C128 memory modules differs with each different memory
configuration. The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded. The attached cartridges are
also restored upon load if they have been saved in the snapshot.

Version numbers: Major 0, Minor 0

@b{The C128MEM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item 12 BYTE
@tab MMU
@tab dump of the 12 MMU registers
@item ARRAY
@tab RAM
@tab 128k RAM dump banks 0 and 1
@end multitable

@b{The C128ROM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item ARRAY
@tab KERNAL
@tab 8k dump of the kernal ROM
@item ARRAY
@tab BASIC
@tab 32k dump of the basic ROM
@item ARRAY
@tab EDITOR
@tab 4k dump of the editor ROM
@item ARRAY
@tab 4k CHARGEN
@tab dump of the chargen ROM
@end multitable

@node VIC20 memory module, PET memory module, C128 memory module, Module formats
@subsubsection VIC20 memory module

The VIC20 memory module actually consists of two modules.  The "VIC20MEM" module
is mandatory and contains the RAM dump.  The "VIC20ROM" module is optional
and contains a dump of the ROM images.

The size of the VIC20 memory modules differs with each different memory
configuration. The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded. The attached cartridges are
also restored upon load if they have been saved in the snapshot.

@b{The VIC20MEM module}

Version numbers: Major 1, Minor 0

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CONFIG
@tab Configuration register.  Bits 0,1,2,3,5 reflect if the corresponding memory block is RAM (bit=1) or not (bit=0).
@item ARRAY
@tab RAM0
@tab 1k RAM dump $0000-$03ff
@item ARRAY
@tab RAM1
@tab 4k RAM dump $1000-$1fff
@item ARRAY
@tab COLORRAM
@tab 2k Color RAM, $9400-$9bff
@item ARRAY
@tab BLK0
@tab if CONFIG & 1 then: 3k RAM dump $0400-$0fff
@item ARRAY
@tab BLK1
@tab if CONFIG & 2 then: 8k RAM dump $2000-$3fff
@item ARRAY
@tab BLK2
@tab if CONFIG & 4 then: 8k RAM dump $4000-$5fff
@item ARRAY
@tab BLK3
@tab if CONFIG & 8 then: 8k RAM dump $6000-$7fff
@item ARRAY
@tab BLK5
@tab if CONFIG & 32 then: 8k RAM dump $a000-$bfff
@end multitable

@b{The VIC20ROM module}

Version numbers: Major 1, Minor 1

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CONFIG
@tab Bit 0: 1= ROM block $2*** enabled.  Bit 1: 1= ROM block $3*** enabled. Bit 2: 1= ROM block $4*** enabled.  Bit 3: 1= ROM block $5*** enabled. Bit 4: 1= ROM block $6*** enabled. Bit 5: 1= ROM block $7*** enabled. Bit 6: 1= ROM block $A*** enabled. Bit 7: 1= ROM block $B*** enabled.
@item ARRAY
@tab KERNAL
@tab 8k KERNAL ROM image $e000-$ffff
@item ARRAY
@tab BASIC
@tab 16k BASIC ROM image $c000-$dfff
@item ARRAY
@tab CHARGEN
@tab 4k CHARGEN ROM image
@item ARRAY
@tab BLK1A
@tab 4k ROM image $2*** (if CONFIG & 1)
@item ARRAY
@tab BLK1B
@tab 4k ROM image $3*** (if CONFIG & 2)
@item ARRAY
@tab BLK3A
@tab 4k ROM image $6*** (if CONFIG & 16)
@item ARRAY
@tab BLK3B
@tab 4k ROM image $7*** (if CONFIG & 32)
@item ARRAY
@tab BLK5A
@tab 4k ROM image $A*** (if CONFIG & 64)
@item ARRAY
@tab BLK5B
@tab 4k ROM image $B*** (if CONFIG & 128)
@item ARRAY
@tab BLK2A
@tab 4k ROM image $4*** (if CONFIG & 4; added in V1.1)
@item ARRAY
@tab BLK2B
@tab 4k ROM image $5*** (if CONFIG & 8; added in V1.1)
@end multitable

@node PET memory module, CBM-II memory module, VIC20 memory module, Module formats
@subsubsection PET memory module

The PET memory module actually consists of three modules.  The "PETMEM" module
is mandatory and contains the RAM dump.  The "PETROM" module is optional
and contains a dump of the ROM images. The "PETDWW" module is also
optional and contains the image of the hires expansion board (if
enabled).

The size of the PET memory modules differs with each different memory
configuration.  The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded.

@b{The PETMEM module}

Version numbers: Major 1, Minor 3

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CONFIG
@tab Configuration value. Bits 0-3: 0= 40 col PET without CRTC; 1= 40 col PET with CRTC; 2 = 80 col PET (with CRTC); 3= SuperPET; 4= 8096; 5= 8296. Bit 6: 1= RAM at $9***. Bit 7: 1= RAM at $A***.
@item BYTE
@tab KEYBOARD
@tab Keyboard type. 0= UK business; 1= Graphics; 2= German business
@item BYTE
@tab MEMSIZE
@tab memory size of low 32k in k (possible values 4, 8, 16, 32)
@item BYTE
@tab CONF8X96
@tab Value of the 8x96 configuration register
@item BYTE
@tab SUPERPET
@tab SuperPET config. Bit 0: 1= $9*** RAM enabled. Bit 1: 1= RAM write protected. Bit 2: 1= CTRL register write protected. Bit 3: 0= DIAG pin active. Bits 4-7: RAM block in use.
@item ARRAY
@tab RAM
@tab 4-32k RAM (not 8296, size depends on MEMSIZE)
@item ARRAY
@tab VRAM
@tab 2/4k RAM (not 8296, size depends on CONFIG)
@item ARRAY
@tab EXTRAM
@tab 64k expansion RAM (SuperPET and 8096 only)
@item ARRAY
@tab RAM
@tab 128k RAM (8296 only)
@item --
@tab --
@tab The following item has been added in V1.1
@item BYTE
@tab POSITIONAL
@tab bit 0=0 = symbolic keyboard mapping, bit 0=1 = positional mapping.
@item --
@tab --
@tab The following item has been added in V1.2
@item BYTE
@tab EOIBLANK
@tab bit 0=0 = EOI does not blank screen, bit 0=1 = EOI blanks screen.
@item --
@tab --
@tab The following items have been added in V1.3
@item WORD
@tab CPU_SWITCH
@tab 6502 / 6809 / PROG
@item BYTE
@tab VAL, PREVODD, WANTODD
@tab 6702 dongle state information
@item WORD[8]
@tab SHIFT
@item BYTE
@tab SuperPET config 2
@tab Extra bits due to the Super-OS/9 MMU. Bit 5: FIRQ disabled. Bit 6:
expansion memory in OS/9 flat mode.

@end multitable

The POSITIONAL item has been added in PETMEM snapshot version 1.1. It is
ignored by earlier restore routines (V1.0) and the V1.1 restore routines
do not change the current setting when reading a V1.0 snapshot.

In V1.2 the new EOIBLANK variable has been added. This implements
the "blank screen on EOI" feature that was previously linked to a wrong
resource.

In V1.3 the state for SuperPET has been added.

@b{The PETROM module}

Version numbers: Major 1, Minor 1

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item BYTE
@tab CONFIG
@tab Bit 0: 1= $9*** ROM included. Bit 1: 1= $A*** ROM included. Bit 2: 1= $B*** ROM included. Bit 3: 1= $e900-$efff ROM included. Bit 4: 1= SuperPET ROMs included.
@item ARRAY
@tab KERNAL
@tab 4k KERNAL ROM image $f000-$ffff
@item ARRAY
@tab EDITOR
@tab 2k EDITOR ROM image $e000-$e7ff
@item ARRAY
@tab CHARGEN
@tab 2k CHARGEN ROM image
@item ARRAY
@tab ROM9
@tab 4k $9*** ROM image (if CONFIG & 1)
@item ARRAY
@tab ROMA
@tab 4k $A*** ROM image (if CONFIG & 2)
@item ARRAY
@tab ROMB
@tab 4k $B*** ROM image (if CONFIG & 4)
@item ARRAY
@tab ROMC
@tab 4k $C*** ROM image
@item ARRAY
@tab ROMD
@tab 4k $D*** ROM image
@item ARRAY
@tab ROME9
@tab 7 blocks $e900-$efff ROM image (if CONFIG & 8)
@item --
@tab --
@tab The following items have been added in V1.1
@item ROM6809
@tab ROM6809
@tab 24k $A000-$FFFF ROM   (if CONFIG & 16)
@item ARRAY
@tab CHARGEN(2)
@tab upper half of CHARGEN (if CONFIG & 16)
@end multitable

@b{The PETDWW module}

For storing the state of the DWW hires expansion board, there is a
PETDWWPIA module, and a DWWMEM module.

The former has the same format as the PIA1.

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item WORD
@tab SIZE
@tab The size of the memory dump that follows, or 0 if DWW disabled.
@item ARRAY
@tab MEM
@tab The memory in the DWW card, SIZE bytes.
@end multitable

@node CBM-II memory module, C500 data module, PET memory module, Module formats
@subsubsection CBM-II memory module

The CBM-II memory module actually consists of two modules.  The
"CBM2MEM" module is mandatory and contains the RAM dump.  The "CBM2ROM"
module is optional and contains a dump of the ROM images.

The size of the CBM-II memory modules differs with each different memory
configuration.  The RAM configuration is saved in the snapshot, and
restored when the snapshot is loaded.

Version numbers: Major 1, Minor 0

@b{The CBM2MEM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item UBYTE
@tab MEMSIZE
@tab Memory size in 128k blocks (1=128k, 2=256k, 4=512k, 8=1024k)
@item UBYTE
@tab CONFIG
@tab Bit 0 = $f0800-$f0fff RAM, Bit 1 = $f1000-$f1fff RAM, Bit 2 = $f2000-$f3fff RAM, Bit 3 = $f4000-$f5fff RAM, Bit 4 = $f6000-$f7fff RAM, Bit 5 = $fc000-$fcfff RAM, Bit 6 = is a C500
@item UBYTE
@tab HWCONFIG
@tab Bit 0/1: model line configuration
@item UBYTE
@tab EXECBANK
@tab CPUs execution bank register
@item UBYTE
@tab INDBANK
@tab CPUs indirection bank register
@item ARRAY
@tab SYSRAM
@tab 2k system RAM $f0000-$f07ff
@item ARRAY
@tab VIDEO
@tab 2k video RAM $fd000-$fd7ff
@item ARRAY
@tab RAM
@tab RAM dump, size according to MEMSIZE
@item ARRAY
@tab RAM08
@tab if memsize < 1M and CONFIG & 1 : 2k RAM $f0800-$f0fff
@item ARRAY
@tab RAM1
@tab if memsize < 1M and CONFIG & 2 : 4k RAM $f1000-$f1fff
@item ARRAY
@tab RAM2
@tab if memsize < 1M and CONFIG & 4 : 8k RAM $f2000-$f3fff
@item ARRAY
@tab RAM4
@tab if memsize < 1M and CONFIG & 8 : 8k RAM $f4000-$f5fff
@item ARRAY
@tab RAM6
@tab if memsize < 1M and CONFIG & 16 : 8k RAM $f6000-$f7fff
@item ARRAY
@tab RAMC
@tab if memsize < 1M and CONFIG & 32 : 4k RAM $fc000-$fcfff
@end multitable

The RAM* arrays are only saved if the RAM itself is less than 1M.
If the memory size is 1M then those areas are taken from the
bank 15 area of the normal RAM.

The memory array starts at $10000 if the memory size is less than 512k,
or at $00000 if 512k or more. In case of a C510, then the memory array
also always starts at $00000.

@b{The CBM2ROM module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item UBYTE
@tab CONFIG
@tab Bit 1: 1= $1*** ROM image included. Bit 2: 1= $2000-$3fff ROM image included. Bit 3: 1= $4000-$5fff ROM image included. Bit 4: 1= $6000-$7fff ROM image included. Bit 5: 1= chargen ROM is VIC-II chargen, 0= CRTC chargen.
@item ARRAY
@tab KERNAL
@tab 8 KERNAL ROM image ($e000-$efff)
@item ARRAY
@tab BASIC
@tab BASIC ROM image ($8000-$bfff)
@item ARRAY
@tab CHARGEN
@tab 4k CHARGEN ROM image
@item ARRAY
@tab ROM1
@tab 4k cartridge ROM image for $1*** (if CONFIG & 2)
@item ARRAY
@tab ROM2
@tab 8k cartridge ROM image for $2000-$3fff (if CONFIG & 4)
@item ARRAY
@tab ROM4
@tab 8k cartridge ROM image for $4000-$5fff (if CONFIG & 8)
@item ARRAY
@tab ROM6
@tab 8k cartridge ROM image for $6000-$7fff (if CONFIG & 16)
@end multitable

@node C500 data module,  ,CBM-II memory module, Module formats
@subsubsection C500 data module

The C500 data module contains simple state information not already saved
in the other modules.

Version numbers: Major 0, Minor 0

@b{The C500DATA module}

@multitable @columnfractions .1 .4 .5
@item Type
@tab Name
@tab Description
@item DWORD
@tab IRQCLK
@tab CPU clock ticks till next 50Hz IRQ
@end multitable

@c -----------------------------------------------------------------
@c @node FIXME
@chapter Media images

@c FIXME: add some info on making screenshots, wav- and avi recordings

@c @node FIXME
@section Media images resources

@table @code

@vindex DoodleOversizeHandling
@item DoodleOversizeHandling
Integer specifying  the way the oversized input should be handled, (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 DoodleMultiColorHandling
@item DoodleMultiColorHandling
Integer specifying  the way the multicolor to hires should be handled, (0: b&w, 
1: 2 colors, 2: 4 colors, 3: gray scale,  4: best cell colors)
@vindex DoodleTEDLumHandling
@item DoodleTEDLumHandling
Integer specifying the way the TED luminosity should be handled, (0: ignore, 1: dither)
@vindex DoodleCRTCTextColor
@item DoodleCRTCTextColor
Integer specifying the text color used when making screenshots from a CRTC window
in doodle format. (0: white, 1: amber, 2: green)

@vindex FFMPEGFormat
@item FFMPEGFormat
String specifying the current FFMPEG output driver.
@vindex FFMPEGAudioBitrate
@item FFMPEGAudioBitrate
Integer specifying the current FFMPEG audio bitrate.
@vindex FFMPEGVideoBitrate
@item FFMPEGVideoBitrate
Integer specifying the current FFMPEG video bitrate.
@vindex FFMPEGAudioCodec
@item FFMPEGAudioCodec
Integer specifying the current FFMPEG audio codec.
@vindex FFMPEGVideoCodec
@item FFMPEGVideoCodec
Integer specifying the current FFMPEG video codec.
@vindex FFMPEGVideoHalveFramerate
@item FFMPEGVideoHalveFramerate
Boolean, if true record only every other frame.

@end table

@c @node FIXME
@section Media images command-line options

@table @code

@cindex -doodleoversize
@item -doodleoversize <method>
Select the way the oversized input should be handled, (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)
@cindex -doodlemc
@item -doodlemc <method>
Select the way the multicolor to hires should be handled, (0: b&w, 1: 2 colors, 2: 4 colors, 3: gray scale,  4: best cell colors)
@cindex -doodletedlum
@item -doodletedlum <method>
Select the way the TED luminosity should be handled, (0: ignore, 1: dither)
@cindex -doodlecrtctextcolor
@item -doodlecrtctextcolor <color>
Select the CRTC text color (0: white, 1: amber, 2: green)

@cindex -ffmpegaudiobitrate
@item -ffmpegaudiobitrate <value>
Set bitrate for audio stream in media file
@cindex -ffmpegvideobitrate
@item -ffmpegvideobitrate <value>
Set bitrate for video stream in media file

@end table

@c -----------------------------------------------------------------
@c @node FIXME
@chapter Event history

@c FIXME: the "Event history" section needs to be style-checked.

VICE supports recording an arbitrary session on the emulated machine and
playing back this session later. This is done by saving a snapshot at the beginning
of the recording session and then remembering all the user interaction such as
keyboard and joystick input. We call this an 'event history'.
The main purpose for having an event history is to create game sessions, e.g. recording 
how to solve a game. An example walkthrough for the well known game "Fort Apocalypse" is
available.

This brief chapter will advise you how to record and playback such a session.
Although it is based on the WinVICE x64 release and its user interface, histories may be
transferred to other machines and other ports that support event history, e.g. the
Unix port.

@c @node FIXME
@section Recommended Settings

When using the event history feature it is possible that the playback session
differs from what was done at recording time. This might arise due to a problem 
in the initial snapshot or settings.
Here are some suggestions to minimize the chance of failures in the session:
a. Reset to default settings.
b. Choose refresh rate 1/1.
c. Choose joystick and Video/Doublesize settings as desired or needed.
d. SID engine must be reSID (which is the default).
e. Choose Drive settings/Idle method: None
Do not change any settings during recording or playback!

@c @node FIXME
@section Recorded Events

The following is a list of the user interaction that will be recorded:
- Joystick movement and button
- Keyboard
- Resetting the machine (hard and soft)
- Attaching or detaching disk/tape images (see 8. Limitations)
- Datasette controls

@c @node FIXME
@section Recording an Event History

Recording an event history will create one or two files for a snapshot and
the list of the user events. First, create an empty directory in which these
files are to be saved and then select this directory and the name of the 
snapshot files via 'Snapshot//Select History files/directory'. 
Next, attach the disk or tape image with the game you want to record and load and
run the game.

Start recording via 'Snapshot//Start/Stop Recording History'.
Play the game. All actions will be recorded.
After the game is finished, stop recording via 'Snapshot//Start/Stop
Recording History'. The selected directory should now contain the two
snapshot files (default ist start.vsf and end.vsf). 

@c @node FIXME
@section Setting and Returning to Milestones

It is difficult to finish a game in one sitting and noone wants to
record all their mistakes and lost lives. Use the milestone feature in a
recording session in the following way:

Set a milestone when you have finished a level or completed a task
('Snapshot//Set recording milestone' or ALT-E). This will save the event
history and a snapshot of the machine to the file end.vsf but recording will
continue.

Return to the last milestone when you have made a mistake or lost a life
('Snapshot//Return to milestone' or ALT-U). This will reset the game and the
event history to the last milestone snapshot so that you can try again.

@c @node FIXME
@section Continuing an Event History

If you have stopped a recording session and want to continue it later, you
should create a backup of your start.vsf and end.vsf files first to avoid
overwriting them by accident.

Then change the event history start mode: 'Snapshot//Recording start mode//Load
existing snapshot'. When you start recording now, you will continue where the
session was stopped last time.

Another way of continuing an existing history is to start somewhere inside the
history (e.g. you have recorded 10 minutes of a game and later recognize that you
made a mistake after 6 minutes that makes it impossible to finish the game).
For this you have to select the start mode 'Overwrite playback'. Now you can
start the playback with 'Snapshot//Start/Stop Playback History' and when you
reach the point where you want to change the history you can directly switch to
recording via 'Snapshot//Start/Stop Recording History'.

@c @node FIXME
@section Playing Back an Event History

To play back an event history, select the directory with the history files
start.vsf and end.vsf via 'Snapshot//Select History directory' and start the
playback with 'Snapshot//Start/Stop Playback History'. Enjoy!
During playback any user interaction is disabled.
The playback stops when the end of the session is reached or if 
'Snapshot//Select History directory' is selected again.

@c @node FIXME
@section Limitations and Suggestions

a. Snapshot files will be quite big (>1MB) if a disk image has been attached. 
If possible, use PRG or T64 images to reduce the size of snapshot files.
b. Snapshots may not be 100% accurate even with all the recommended settings.


@c @node FIXME
@section Event history resources

@table @code

@vindex EventSnapshotDir
@item EventSnapshotDir
String specifying the directory used for loading and saving snapshots.
@vindex EventStartSnapshot
@item EventStartSnapshot
String specifying the filename for the start snapshot. ["start.vsf"]
@vindex EventEndSnapshot
@item EventEndSnapshot
String specifying the filename for the end snapshot. ["end.vsf"]
@vindex EventStartMode
@item EventStartMode
Integer specifying how to start event recording. (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. [1]

@end table

@c @node FIXME
@section Event history command-line options

@table @code
@cindex -playback
@item -playback
Playback recorded events
@end table

@c -----------------------------------------------------------------

@node Monitor, c1541, Snapshots, Top
@chapter Monitor

Every VICE emulator has a complete built-in monitor, which can be used
to examine, disassemble and assemble machine language programs, as
well as debug them through breakpoints.  It can be activated by using
the ``Activate monitor'' command (left button menu).  Notice that you
have to run the emulator from a terminal emulation program (such as
@code{rxvt} or @code{xterm}) in order to use the monitor.

@b{Warning}: this version of the monitor is still under construction,
and some of the features are not fully working yet.

@menu
* Terminology::
* Machine state commands::
* Memory commands::
* Assembly commands::
* Checkpoint commands::
* General commands::
* Disk commands::
* Command file commands::
* Label commands::
* Miscellaneous commands::
@end menu

@node Terminology, Machine state commands, Monitor, Monitor
@section Terminology

@table @samp

@item address_space
This refers to the range of memory locations and a set of registers.
This can be the addresses available to the computer's processor, the
disk drive's processor or a specific memory configuration of one of
the mentioned processors.

@item bankname
The CPU can only see 64k of memory at any one time, due to its 16 bit
address bus. The C64 and other computers have more than this amount,
and this is handled by banking: a memory address can have different
contents, depending on the active memory bank.
A bankname names a specific bank in the current address_space.

@item register
One of the following: program counter (PC), stack pointer (SP),
accumulator (A), X register (X), or Y register (Y).

@item address
A specific memory location in the range $0000 to $FFFF.

@item address_range
Two addresses.  If the second address is less than the first, the
range is assumed to wraparound from $FFFF to $0000.  Both addresses
must be in the same address space.

@item address_opt_range
An address or an address range.

@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.

@item prompt
The prompt has the format [x:y].  If x is -, memory reads from the
monitor do not have side effects.  Otherwise, x is S.  The second part
of the prompt, y, shows the default address space.

@item checkpoint
The monitor has the ability to setup triggers that perform an action
when a specified situation occurs.  There are three types of
checkpoints; breakpoints, tracepoints and watchpoints.

@item breakpoint
A breakpoint is triggered based on the program counter.  When it is
triggered, the monitor is entered.

@item tracepoint
Like breakpoints, a tracepoint is triggered based on the program
counter.  Instead of entering the monitor, the program counter is
printed and execution continues.

@item watchpoint
Watchpoints are triggered by a read and/or write to an address.  When
a watchpoint is triggered, the monitor is entered.

@item memmap
The memmap keeps track of RAM/ROM/IO read/write/execute
accesses. The feature must be enabled with "--enable-memmap"
configure option, as it might decrease performance notably on
slower hardware. The option also enables CPU history.

@item <@dots{}>
A data type.

@item *
Zero or more occurrences.

@item [@dots{}]
An optional argument.

@end table

@node Machine state commands, Memory commands, Terminology, Monitor
@section Machine state commands

@table @code

@item backtrace
@itemx bt
Print JSR call chain (most recent call first). Stack offset
relative to SP+1 is printed in parentheses. This is a best guess
only.

@item cpuhistory [<count>]
@itemx chis [<count>]
Show <count> last executed commands.
(disabled by default; configure with --enable-memmap to enable)

@item dump "<filename>"
Write a snapshot of the machine into the file specified.
This snapshot is compatible with a snapshot written out by the UI.
Note: No ROM images are included into the dump.

@item goto <address>
@itemx g <address>
Change the PC to address and continue execution.

@item io [<address>]
Display i/o registers. Invoking without an address shows a dump of
the entire io range, if an address is given then details for the
chip at the respective (base-)address are displayed (if available).

@item next [<count>]
@itemx n [<count>]
Advance to the next instruction.  Subroutines are treated as a single
instruction.

@item registers [<reg_name> = <number> [, <reg_name> = <number>]*]
@itemx r [<reg_name> = <number> [, <reg_name> = <number>]*]
Assign respective registers.  With no parameters, display register
values.

@item reset [<type>]
Reset the machine or drive.
@code{type}: 0 = soft, 1 = hard, 8-11 = drive.

@item return
@itemx ret
Continues execution  and returns to the monitor just
after the next RTS or RTI is executed.

@item step [<count>]
@itemx z [<count>]
Single step through instructions.  An optional count allows stepping
more than a single instruction at a time.

@item stopwatch [reset]
Print the CPU cycle counter of the current device. 'reset' sets the counter to 0.

@item undump "<filename>"
Read a snapshot of the machine from the file specified.

@end table


@node Memory commands, Assembly commands, Machine state commands, Monitor
@section Memory commands


@table @code

@item bank [<bankname>]
Without a bankname, display all available banks for the current
address_space. With a bankname given, switch to the specified
bank. If a bank is not completely filled (ROM banks for example)
normally the @code{ram} bank is used where the bank has holes.
The @code{cpu} bank uses the bank currently used by the CPU.

@item compare <address_range> <address>
@itemx c <address_range> <address>
Compare memory from the source specified by the address range to the
destination specified by the address.  The regions may overlap.  Any
values that miscompare are displayed using the default displaytype.

@item device [c:|8:|9:]
Set the default address space to either the computer `c:' or the
specified drive `8:' or `9:'

@item fill <address_range> <data_list>
@itemx f <address_range> <data_list>
Fill memory in the specified address range with the data in
<data_list>.  If the size of the address range is greater than the
size of the data_list, the data_list is repeated.

@item hunt <address_range> <data_list>
@itemx h <address_range> <data_list>
Hunt memory in the specified address range for the data in
<data_list>.  If the data is found, the starting address of the match
is displayed.  The entire range is searched for all possible matches.
The data list may have `xx' as a wildcard.

@item i <address_opt_range>
Display memory contents as PETSCII text.

@item ii <address_opt_range>
Display memory contents as screen code text

@item mem [<data_type>] [<address_opt_range>]
@itemx m [<data_type>] [<address_opt_range>]
Display the contents of memory.  If no datatype is given, the default
is used.  If only one address is specified, the length of data
displayed is based on the datatype.  If no addresses are given, the
'dot' address is used.

@item memmapshow [<mask>] [<address_opt_range>]
@itemx mmsh [<mask>] [<address_opt_range>]
Show the memmap. The mask can be specified to show only those
locations with accesses of certain type(s). The mask is a number
with the bits "ioRWXrwx", where RWX are for ROM and rwx for RAM.
Optionally, an address range can be specified.
(disabled by default; configure with --enable-memmap to enable)

@item memmapzap
@itemx mmzap
Clear the memmap.
(disabled by default; configure with --enable-memmap to enable)

@item memmapsave "<filename>" <format>
@itemx mmsave "<filename>" <format>
Save the memmap as a picture. @code{format}:
0 = BMP, 1 = PCX, 2 = PNG, 3 = GIF, 4 = IFF.
(disabled by default; configure with --enable-memmap to enable)

@item memchar [<data_type>] [<address_opt_range>]
@itemx mc [<data_type>] [<address_opt_range>]
Display the contents of memory as character data.  If only one address
is specified, only one character is displayed.  If no addresses are
given, the ``dot'' address is used.

@item memsprite [<data_type>] [<address_opt_range>]
@itemx ms [<data_type>] [<address_opt_range>]
Display the contents of memory as sprite data.  If only one address is
specified, only one sprite is displayed.  If no addresses are given,
the ``dot'' address is used.

@item move <address_range> <address>
@itemx t <address_range> <address>
Move memory from the source specified by the address range to the
destination specified by the address.  The regions may overlap.

@item screen
@itemx sc
Displays the contents of the screen.

@item sidefx [on|off|toggle]
@itemx sfx [on|off|toggle]
Control how monitor generated reads affect memory locations that have
read side-effects, like CIA interrupt registers for example.
If the argument is 'on' then reads may cause side-effects.  If the
argument is 'off' then reads don't cause side-effects.  If the
argument is 'toggle' then the current mode is switched.  No argument
displays the current state.

@item > [<address>] <data_list>
Write the specified data at @code{address}.

@end table

@node Assembly commands, Checkpoint commands, Memory commands, Monitor
@section Assembly commands

@table @code

@item a <address> [ <instruction> [: <instruction>]* ]
Assemble instructions to the specified address.  If only one
instruction is specified, enter assembly mode (enter an empty line to
exit assembly mode).

@item disass [<address> [<address>]]
@itemx d [<address> [<address>]]
Disassemble instructions.  If two addresses are specified, they are
used as a start and end address.  If only one is specified, it is
treated as the start address and a default number of instructions are
disassembled.  If no addresses are specified, a default number of
instructions are disassembled from the dot address.

@end table

@node Checkpoint commands, General commands, Assembly commands, Monitor
@section Checkpoint commands


@table @code

@item break [load|store|exec] [address [address] [if <cond_expr>]]
This command allows setting a breakpoint or listing the current
breakpoints.  If no address is given, the currently valid checkpoints
are printed.  If an address is given, a breakpoint is set for that
address and the breakpoint number is printed.
The "load|store|exec" parameter can be either "load", "store" or "exec"
(or any combination of these) to determine on which operation the
monitor breaks. If not specified, the monitor breaks on "exec".
A conditional expression can also be specified for the breakpoint.
For more information on conditions, see the CONDITION command.

@item enable <checknum>
@item disable <checknum>
Each checkpoint can be enabled or disabled.  This command allows
changing between these states.

@item command <checknum> "<command>"
When checkpoint @code{checknum} is hit, the specified command is
executed by the monitor.  Note that the @code{x} command is not yet
supported as a command argument.

@item condition <checknum> if <cond_expr>
@itemx cond <checknum> if <cond_expr>
Each time the specified checkpoint is examined, the condition is
evaluated.  If it evalutes to true, the checkpoint is activated.
Otherwise, it is ignores.  If registers are specified in the
expression, the values used are those at the time the checkpoint is
examined, not when the condition is set.

Currently, the cond_expr is very limited. You can use registers (.A, .X,
.Y, .PC, and .SP) and compare against other registers or absolute
values. For example, the following are all valid conditions:
.A == 0, .X == .Y, 8:.X == .X, .A != 5, .A < .X.

However, you cannot specify memory contents and compare that.


@item delete <checknum>
@itemx del <checknum>
Delete the specified checkpoint.

@item ignore <checknum> [<count>]
Ignore a checkpoint after a given number of crossings.  If no count is
given, the default value is 1.

@item trace [load|store|exec] [address [address] [if <cond_expr>]]
@itemx tr [load|store|exec] [address [address] [if <cond_expr>]]
This command is similar to the @code{break} command except that it
operates on tracepoints.  A tracepoint differs from a breakpoint by
not stopping execution but simply printing the PC, giving the user an
execution trace.  The second optional address can be used to specify
the end of an range of addresses to be traced.
If no addresses are given, a list of all the checkpoints is printed.
The "load|store|exec" parameter can be either "load", "store" or "exec"
(or any combination of these) to determine which operation the
monitor traces. If not specified, the monitor traces all operations.
A conditional expression can also be specified for the tracepoint.
For more information on conditions, see the CONDITION command.

@item until [<address>]
@itemx un [<address>]
If no address is given, the currently valid breakpoints are printed.
If an address is given, a temporary breakpoint is set for that address
and the breakpoint number is printed.  Control is returned to the
emulator by this command.  The breakpoint is deleted once it is hit.

@item watch [load|store|exec] [address [address] [if <cond_expr>]]
@itemx w [load|store|exec] [address [address] [if <cond_expr>]]
This command is similar to the @code{break} command except that it
operates on watchpoints.  A watchpoint differs from a breakpoint by
stopping on a read and/or write to an address or range of addresses.
If no addresses are given, a list of all the checkpoints is printed.
The "load|store|exec" parameter can be either "load", "store" or "exec"
(or any combination of these) to determine on which operation the
monitor breaks. If not specified, the monitor breaks on "load" and
"store" operations.
A conditional expression can also be specified for the watchpoint.
For more information on conditions, see the CONDITION command.

@end table


@node General commands, Disk commands, Checkpoint commands, Monitor
@section General commands


@table @code

@item cd <directory>
Change the working directory.

@item device [c:|d:]
@itemx dev [c:|d:]
Set the default memory device to either the computer (@code{c:}) or
the disk (@code{d:}).

@item dir [<directory>]
@itemx ls [<directory>]
Display the directory contents.

@item pwd
Show current working directory.

@item radix [H|D|O|B]
@itemx rad [H|D|O|B]
Set the default radix to hex, decimal, octal, or binary.  With no
argument, the current radix is printed.

@end table


@node Disk commands, Command file commands, General commands, Monitor
@section Disk commands

@table @code

@item attach <filename> <device>
Attach file to device. (device 32 = cart)

@item block_read <track> <sector> [<address>]
@itemx br <track> <sector> [<address>]
Read the block at the specified track and sector.  If an address is
specified, the data is loaded into memory.  If no address is given,
the data is displayed using the default datatype.

@item block_write <track> <sector> <address>
@itemx bw <track> <sector> <address>
Write a block of data at @code{address} to the specified track and
sector of disk in drive 8.

@item detach <device>
Detach file from device. (device 32 = cart)

@item @@<disk command>
Perform a disk command on the currently attached disk image on drive
8.  The specified disk command is sent to the drive's channel #15.

@item load "<filename>" <device> [<address>]
@itemx l "<filename>" <device> [<address>]
Load the specified file into memory.  If no address is given, the file
is loaded to the address specified by the first two bytes read from
the file.  If address is given, the file is loaded to the specified
address and the first two bytes read from the file are skipped.  If
device is 0, the file is read from the file system.

@item list [<directory>]
List disk contents.

@item bload "<filename>" <device> <address>
@itemx bl "<filename>" <device> <address>
Load the specified file into memory at the specified address.
If device is 0, the file is read from the file system.

@item save "<filename>" <device> <address1> <address2>
@itemx s "<filename>" <device> <address1> <address2>
Save the memory from address1 to address2 to the specified file.
Write two-byte load address.
If device is 0, the file is written to the file system.

@item bsave "<filename>" <device> <address1> <address2>
@itemx bs "<filename>" <device> <address1> <address2>
Save the memory from address1 to address2 to the specified file.
If device is 0, the file is written to the file system.

@end table


@node Command file commands, Label commands, Disk commands, Monitor
@section Command file commands


@table @code

@item playback "<filename>"
@itemx pb "<filename>"
Monitor commands from the specified file are read and executed.  This
command stops at the end of file or when a STOP command is read.

@item record "<filename>"
@itemx rec "<filename>"
After this command, all commands entered are written to the specified
file until the STOP command is entered.

@item stop
Stop recording commands.  See @code{record}.

@end table

@node Label commands, Miscellaneous commands, Command file commands, Monitor
@section Label commands


@table @code

@item add_label <address> <label>
@itemx al <address> <label>
Map a given address to a label.  This label can be used when entering
assembly code and is shown during disassembly.  Additionally, it can
be used whenever an address must be specified.

<label> is the name of the label; it must start with a dot (".") in
order for the monitor to recognize it as a label.

@item delete_label [<memspace>] <label>
@itemx dl [<memspace>] <label>
Remove the specified label from the label tables.  If no memory space is
checked, all tables are checked.

@item load_labels [<memspace>] "<filename>"
@itemx ll [<memspace>] "<filename>"
Load a file containing a mapping of labels to addresses.  If no memory
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 [<memspace>] "<filename>"
@itemx sl [<memspace>] "<filename>"
Save labels to a file.  If no memory space is specified, all of the
labels are saved.

@item show_labels [<memspace>]
@itemx shl [<memspace>]
Display current label mappings.  If no memory space is specified, show
all labels.

@end table


@node Miscellaneous commands,  , Label commands, Monitor
@section Miscellaneous commands


@table @code

@item cartfreeze
Use cartridge freeze.

@item cpu <type>
Specify the type of CPU currently used (6502/z80).

@item exit
@itemx x
Leave the monitor and return to execution.

@item export
@itemx exp
Print out list of attached expansion port devices.

@item help [<command>]
If no argument is given, prints out a list of all available commands.
If an argument is given, prints out specific help for that command.

@item keybuf "<string>"
Put the specified string into the keyboard buffer. Note that you can specify
specific keycodes by using C-style escaped hexcodes ("\x0a").

@item print <expression>
@itemx p <expression>
Evaluate the specified expression and output the result.

@item resourceget "<resource>"
@itemx resget "<resource>"
Displays the value of the @code{resource}.

@item resourceset "<resource>" "<value>"
@itemx resset "<resource>" "<value>"
Sets the value of the @code{resource}.

@item load_resources "<file>"
@itemx resload "<file>"
Load resources from @code{file}.

@item save_resources "<file>"
@itemx ressave "<file>"
Save resources to @code{file}.

@item screenshot "<filename>" [<format>]
@itemx scrsh "<filename>" [<format>]
Take a screenshot. @code{format}:
default = BMP, 1 = PCX, 2 = PNG, 3 = GIF, 4 = IFF.

@item tapectrl <command>
Control the datasette. @code{command}:
0 = stop, 1 = start, 2 = forward, 3 = rewind, 4 = record,
5 = reset, 6 = reset counter.

@item quit
Exit the emulator immediately.

@item ~ <number>
Display the specified number in decimal, hex, octal and binary.

@end table


@node c1541, File formats, Monitor, Top
@chapter c1541

VICE is provided with a complete stand-alone disk image maintenance
utility, called @code{c1541}.

You can either invoke it from the command
line or from within one of the VICE emulators, using the ``Run c1541''
command which will open a new @code{xterm} window with a running
@code{c1541} in it.

The syntax is:

@example
c1541 [IMAGE1 [IMAGE2]] [COMMAND1 COMMAND2 @dots{} COMMANDN]
@end example

@code{IMAGE1} and @code{IMAGE2} are disk image names that can be
attached before @code{c1541} starts.  @code{c1541} can handle up to
two disk images at the same time by using two virtual built-in drives,
numbered @code{8} and @code{9}; @code{IMAGE1} (if present) is always
attached to drive @code{8}, while @code{IMAGE2} is attached to drive
@code{9}.

@code{COMMAND}s specified on the command-line all begin with the minus
sign (@code{-}); if present, @code{c1541} executes them in the same
order as they are on the command line and returns a zero error code if
they were successful.  If any of the @code{COMMAND}s fails, @code{c1541}
stops and returns a nonzero error code.

If no @code{COMMAND}s are specified at all, @code{c1541} enters
interactive mode, where you can type commands manually.  Commands in
interactive mode are the same as commands in batch mode, but do not
require a leading @code{-}.  As with the monitor, file name completion
and command line editing with history are provided via GNU
@code{readline}.  Use the command @samp{quit} or press @kbd{C-d} to
exit.

@menu
* c1541 file specification::
* c1541 quoting::
* c1541 commands and options::
* c1541 executing shell commands::
@end menu

@node c1541 file specification, c1541 quoting, c1541, c1541
@section Specifying files in c1541

When accessing CBM DOS files (i.e. files that reside on disk images),
c1541 uses a special syntax that lets you access files on both drive 8
and 9.  If you prepend the file name with @code{@@8:} or @code{@@9:}, you
will specified that file is to be found or created on drive 8 and 9,
respectively.

For instance,

@example
@@8:somefile
@end example

will name file named @code{somefile} on unit 8, while

@example
@@9:somefile
@end example

will name file named @code{somefile} on unit 9.

@node c1541 quoting, c1541 commands and options, c1541 file specification, c1541
@section Using quotes and backslashes

You can use quotes (@code{"}) in a command to embed spaces into file
names.  For instance,

@example
read some file
@end example

will read file @code{some} from the disk image and write it into the
file system as @code{file}, while

@example
read "some file"
@end example

will copy @code{some file} into the file system, with the name
@code{some file}.

The backslash character (@code{\}) has a special meaning too: it lets
you literally insert the following character no matter what it is.  For
example,

@example
read some\ file
@end example

will copy file @code{some file} into the file system, while

@example
read some\ file this\"file
@end example

will copy @code{some file} into the file system with name
@code{this"file} (with an embedded quote).


@node c1541 commands and options, c1541 executing shell commands, c1541 quoting, c1541
@section c1541 commands and options

This is a list of the @code{c1541} commands.  They are shown in their
interactive form, without the leading @code{-}.
Square brackets [] indicate an optional part, and "<COMMAND>" translates
to a disk command according to CBM DOS, like "i0" for example.

@table @code

@item @@ [<command>]
Execute specified CBM DOS command and print the current status of the
drive.  If no @code{command} is specified, just print the status.

@item ? [<command>]
Explain specified command.  If no command is specified, list available
ones.

@item attach <diskimage> [<unit>]
Attach @code{diskimage} to @code{unit} (default unit is 8).

@item block <track> <sector> <disp> [<drive>]
Show specified disk block in hex form.

@item copy <source1> [<source2> @dots{} <sourceN>] <destination>
Copy @code{source1} @dots{} @code{sourceN} into destination.  If N > 1,
@code{destination} must be a simple drive specifier (@code{@@n:}).

@item delete <file1> [<file2> @dots{} <fileN>]
Delete the specified files.

@item exit
Exit (same as @code{quit}).

@item extract
Extract all the files to the file system.

@item format <diskname,id> [<type> <imagename>] [<unit>]
If @code{unit} is specified, format the disk in unit @code{unit}.  If
@code{type} and @code{imagename} are specified, create a new image named
@code{imagename}, attach it to unit 8 and format it.  @code{type} is a
disk image type, and must be either @code{x64}, @code{d64} (both VC1541/2031),
@code{g64} (VC1541/2031 but in GCR coding), @code{d71} (VC1571), @code{d81}
(VC1581), @code{d80} (CBM8050) or @code{d82} (CBM8250/1001).
Otherwise, format the disk in the current unit, if any.

@item gcrformat <diskname,id> <imagename>
Create and format a G64 disk image named @code{imagename}.

@item help [<command>]
Explain specified command.  If no command is specified, list available
ones.

@item info [<unit>]
Display information about unit @code{unit} (if unspecified, use the current
one).

@item list [<pattern>]
List files matching @code{pattern} (default is all files).

@item quit
Exit (same as @code{exit}).

@item read <source> [<destination>]
Read @code{source} from the disk image and copy it into @code{destination} in
the file system.  If @code{destination} is not specified, copy it into a
file with the same name as @code{source}.",

@item rename <oldname> <newname>
Rename @code{oldname} into @code{newname}.  The files must be on the
same drive.

@item tape <t64name> [<file1> @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 write <source> [<destination>]
Write @code{source} from the file system into @code{destination} on a
disk image.

@item zcreate <x64name> <zipname> [<label,id>]
Create an X64 disk image out of a set of four Zipcoded files named
@code{1!zipname}, @code{2!zipname}, @code{3!zipname} and
@code{4!zipname}.

@end table

@node c1541 executing shell commands,  , c1541 commands and options, c1541
@section Executing shell commands

If you want to execute a shell command from withing @code{c1541}, just
prepend it with an exclamation mark (@code{!}).  For example,

@example
!ls -la
@end example

will execute the command @code{ls -la}, which will show you all the
files in the current directory.

@c @node FIXME
@section c1541 examples

@c FIXME: add more c1541 examples

@table @code
@item c1541 -attach test.d64 -write test.prg testfile
Write @code{test.prg} to @code{test.d64} as @code{testfile}.
@end table

@c @node FIXME
@chapter cartconv

The cartconv program is a cartridge conversion utility, it can convert
between binary and .crt images and it can 'insert' binary and/or
.crt images into the EPROM type of cartridges.

@section cartconv command line options

The cartconv program has the following parameters:

@table @code
@cindex -i
@item -i "input name"
This parameter is mandatory, it should contain the name of the binary/.crt
file you want to convert. For the EPROM type of cartridges this parameter
can be used multiple times to insert images into the resulting file.
@cindex -o
@item -o "output name"
This parameter is mandatory, it should contain the name of the binary/.crt
file you want to convert the input file to.
@cindex -t
@item -t carttype
This parameter is optional. It is only needed when converting to a .crt
file. See below for the supported cartridge types.
@cindex -n
@item -n "cart name"
This parameter is optional and is used as the cartridge name when creating
a .crt file.
@cindex -l
@item -l loadaddress
This parameter is optional and is used as the load-address when converting
a .crt file to a .prg file, or when converting to a generic type .crt
file.
@cindex -f
@item -f "input name"
This parameter is optional, and is meant to output information about the
named file. It can't be used in conjuction with any of the other parameters.
@cindex -r
@item -r
This parameter is optional, it enables repair mode (accept broken input files)
@end table

The following cartridge types are supported:

@table @code
@item bin
Binary .bin file (Default crt->bin)
@item normal
Generic 8kB/12kB/16kB .crt file (Default bin->crt)
@item prg
Binary C64 .prg file with load-address
@item ulti
Ultimax mode 4kB/8kB/16kB .crt file
@item ap
Atomic Power .crt file
@item ar2
Action Replay MK2 .crt file
@item ar3
Action Replay MK3 .crt file
@item ar4
Action Replay MK4 .crt file
@item ar5
Action Replay V5 .crt file
@item cap
Capture .crt file
@item comal
Comal 80 .crt file
@item dep256
Dela EP256 .crt file, extra files can be inserted (1)(2)
@item dep64
Dela EP64 .crt file, extra files can be inserted (1)
@item dep7x8
Dela EP7x8 .crt file, extra files can be inserted (1)(2)(3)
@item din
Dinamic .crt file
@item dsm
Diashow-Maker .crt file
@item easy
EasyFlash .crt file
@item epyx
Epyx FastLoad .crt file
@item exos
EXOS .crt file
@item expert
Expert Cartridge .crt file
@item fc1
The Final Cartridge .crt file
@item fc3
The Final Cartridge III .crt file
@item fcp
Final Cartridge Plus .crt file
@item ff
Freeze Frame .crt file
@item fm
Freeze Machine .crt file
@item fp
Fun Play .crt file
@item gk
Game Killer .crt file
@item gs
C64 Games System .crt file
@item ide64
IDE64 .crt file
@item ieee
IEEE-488 Interface .crt file
@item kcs
KCS Power Cartridge .crt file
@item mach5
MACH 5 .crt file
@item md
Magic Desk .crt file
@item mf
Magic Formel .crt file
@item mikro
Mikro Assembler .crt file
@item mmc64
MMC64 .crt file
@item mmcr
MMC Replay .crt file
@item mv
Magic Voice .crt file
@item ocean
Ocean .crt file
@item p64
Prophet64 .crt file
@item rep256
REX 256k EPROM Cart .crt file, extra files can be inserted (1)(2)(3)
@item ross
ROSS .crt file
@item rr
Retro Replay .crt file
@item ru
REX Utility .crt file
@item s64
Snapshot 64 .crt file
@item sb
Structured BASIC .crt file
@item se5
Super Explode V5.0 .crt file
@item sg
Super Games .crt file
@item simon
Simons' BASIC .crt file
@item ss4
Super Snapshot V4 .crt file
@item ss5
Super Snapshot V5 .crt file
@item star
Stardos .crt file
@item wl
Westermann Learning .crt file
@item ws
Warp Speed .crt file
@item zaxxon
Zaxxon .crt file
@end table

@itemize @bullet
@item (1) insertion of 32kB EPROM files supported.
@item (2) insertion of 8kB .crt/binary files supported.
@item (3) insertion of 16kB .crt/binary files supported.
@end itemize

@c @node FIXME
@section cartconv examples

@table @code
@item cartconv -i foo.crt -o foo.bin
Convert a .crt file to a binary file with no load-address.
@item cartconv -t prg -i foo.crt -o foo.prg
Convert a .crt file to a .prg file with default load-address.
@item cartconv -t prg -l 49152 -i foo.crt -o foo.prg
Convert a .crt file to a .prg file with 49152 as the load-address.
@item cartconv -t ocean -i foo.bin -o foo.crt
Convert a binary file to an ocean type cartridge.
@item cartconv -t dep64 -i dep64.bin -i eprom.prg -o foo.crt
Inserting a 32kB EPROM file into an dep64 type cartridge.
@itemize @bullet
@item step 1 : use the dep64 binary file in VICE as a generic 8kB cartridge.
@item step 2 : generate an EPROM file.
@item step 3 : get the EPROM file to the host computer.
@item step 4 : insert the EPROM file into the final dep64 .crt file:
@end itemize
@item cartconv -t dep256 -i dep256.bin -i somegame.crt -o foo.crt
Insert an 8kB .crt file into a dep256 type cartridge.
@item cartconv -t rep256 -i rep256.bin -i foo1.crt -i foo2.crt -i foo3.crt -o foo.crt
Insert multiple 8kB .crt files into a rep256 type cartridge.
@item cartconv -f foo.crt
Get information about a .crt file.
@end table

@c @node FIXME
@chapter petcat

The petcat program is a text conversion utility, it can convert
between ASCII, PETSCII and tokenized BASIC.

@section petcat command line options

@table @code
@cindex -help
@item -help
Output help text
@cindex -v
@item -v
Same as above
@cindex -c
@item -c
controls (interpret also control codes) (default if textmode)
@cindex -nc
@item -nc
no controls (suppress control codes in printout) (default if non-textmode)
@cindex -ic
@item -ic
interpret control codes case-insensitive
@cindex -h
@item -h
write header (default if output is stdout)
@cindex -nh
@item -nh
no header (default if output is a file)
@cindex -skip <n>
@item -skip <n>
Skip <n> bytes in the beginning of input file. Ignored on P00.
@cindex -text
@item -text
Force text mode
@c @cindex -<version> - this one breaks the index (?!)
@item -<version>
use keywords for <version> instead of the v7.0 ones
@cindex -w<version>
@item -w<version>
tokenize using keywords on specified Basic version.
@cindex -k<version>
@item -k<version>
list all keywords for the specified Basic version
@cindex -k
@item -k
list all Basic versions available.
@cindex -l
@item -l
Specify load address for program (in hex, no loading chars!).
@cindex -o <name>
@item -o <name>
Specify the output file name
@cindex -f
@item -f
Force overwritten the output file. The default depends on the BASIC version.
@end table

BASIC Versions:
@table @code
@item 1
PET Basic V1.0
@item 2
Basic v2.0
@item superexp
Basic v2.0 with Super Expander (VIC20)
@item turtle
Basic v2.0 with Turtle Basic by Craig Bruce (VIC20)
@item mighty
Basic v2.0 with Mighty Basic by Craig Bruce (VIC20)
@item a
Basic v2.0 with AtBasic (C64)
@item simon
Basic v2.0 with Simon's Basic extension (C64)
@item speech
Basic v2.0 with Speech Basic v2.7 (C64)
@item F
Basic v2.0 with Final Cartridge III (C64)
@item ultra
Basic v2.0 with Ultrabasic-64 (C64)
@item graph
Basic v2.0 with Graphics basic (C64)
@item WSB
Basic v2.0 with WS basic (C64)
@item WSBF
Basic v2.0 with WS basic final (C64)
@item Pegasus
Basic v2.0 with Pegasus basic 4.0 (C64)
@item Xbasic
Basic v2.0 with Xbasic (C64)
@item Drago
Basic v2.0 with Drago basic 2.2 (C64)
@item REU
Basic v2.0 with REU-basic (C64)
@item Lightning
Basic v2.0 with Basic Lightning (C64)
@item magic
Basic v2.0 with Magic Basic (C64)
@item easy
Basic v2.0 with Easy Basic (VIC20)
@item blarg
Basic v2.0 with Blarg (C64)
@item Game
Basic v2.0 with Game Basic (C64)
@item BSX
Basic v2.0 with Basex (C64)
@item superbas
Basic v2.0 with Super Basic (C64)
@item exp20
Basic 2.0 with Expanded Basic (VIC20)
@item exp64
Basic 2.0 with Expanded Basic (C64)
@item sxc
Basic 2.0 with Super Expander Chip (C64)
@item warsaw
Basic 2.0 with Warsaw Basic (C64)
@item 4v
Basic 2.0 with Basic 4.0 extensions (VIC20)
@item 4 -w4e
PET Basic v4.0 program (PET/C64)
@item 5
Basic 2.0 with Basic 5.0 extensions (VIC20)
@item 3
Basic v3.5 program (C16)
@item 70
Basic v7.0 program (C128)
@item 71
Basic v7.1 program (C128)
@item 10
Basic v10.0 program (C64DX)
@end table

@c @node FIXME
@section petcat examples

@table @code
@item petcat -2 -o outputfile.txt -- inputfile.prg
Convert inputfile.prg to a text file in outputfile.txt, using BASIC V2 only
@item petcat -wsimon -o outputfile.prg -- inputfile.txt
Convert inputfile.txt to a PRG file in outputfile.prg, using Simon's BASIC
@end table


@node File formats, Acknowledgments, c1541, Top
@chapter The emulator file formats

This chapter gives a technical description of the various files
supported by the emulators.

@menu
* T64::                         The tape image format
* G64::                         The GCR-encoded disk image format
* D64::                         The D64 disk image format
* D71::                         The D71 disk image format
* D80::                         The D80 disk image format
* D81::                         The D81 disk image format
* D82::                         The D82 disk image format
* X64::                         The X64 disk image format
* P00::                         The P00 image format
@end menu

@node T64, G64, File formats, File formats
@section The T64 tape image format

(This section was taken from the C64S distribution.)

The @code{T64} File Structure was developed by Miha Peternel for use in
the C64S emulator.  It is easy to use and allows future extensions.

@menu
* T64 file structure::
* T64 tape record::
* T64 file record::
@end menu

@c FIXME: add D67 CBM2040 (DOS1) disk image file structure
@c FIXME: add D1M FD2000/FD4000 DD disk image file structure
@c FIXME: add D2M FD2000/FD4000 HD disk image file structure
@c FIXME: add D4M FD4000 ED disk image file structure

@node T64 file structure, T64 tape record, T64, T64
@subsection T64 File structure

@multitable @columnfractions .3 .3 .4
@item @b{Offset}
@tab @b{Size}
@tab @b{Description}
@item 0
@tab 64
@tab tape record
@item 64
@tab 32*n
@tab file records for n directory entries
@item 64+32*n
@tab varies
@tab binary contents of the files
@end multitable

@node T64 tape record, T64 file record, T64 file structure, T64
@subsection Tape Record

@multitable @columnfractions .3 .3 .4
@item @b{Offset}
@tab @b{Size}
@tab @b{Description}
@item 0
@tab 32
@tab DOS tape description + EOF (for type)
@item 32
@tab 2
@tab tape version ($0200)
@item 34
@tab 2
@tab number of directory entries
@item 36
@tab 2
@tab number of used entries (can be 0 in my loader)
@item 38
@tab 2
@tab free
@item 40
@tab 24
@tab user description as displayed in tape menu
@end multitable

@node T64 file record,  , T64 tape record, T64
@subsection  File record

@multitable @columnfractions .3 .3 .4
@item @b{Offset}
@tab @b{Size}
@tab @b{Description}
@item 0
@tab 1
@tab entry type (see below)
@item 1
@tab 1
@tab C64 file type
@item 2
@tab 2
@tab start address
@item 4
@tab 2
@tab end address
@item 6
@tab 2
@tab free
@item 8
@tab 4
@tab offset of file contents start within T64 file
@item 12
@tab 4
@tab free
@item 16
@tab 16
@tab C64 file name
@end multitable

Valid entry types are:

@multitable @columnfractions .3 .7
@item @b{Code}
@tab @b{Explanation}
@item @code{0}
@tab free entry
@item @code{1}
@tab normal tape file
@item @code{2}
@tab tape file with header: header is saved just before file data
@item @code{3}
@tab memory snapshot v0.9, uncompressed
@item @code{4}
@tab tape block
@item @code{5}
@tab digitized stream
@item @code{6} @dots{} @code{255}
@tab reserved
@end multitable

Notes:

@itemize @bullet
@item VICE only supports file type @code{1}.
@item Types @code{3}, @code{4} and @code{5} are subject to change (and
are rarely  used).
@end itemize

@node G64, D64 , T64, File formats
@section The G64 GCR-encoded disk image format

(This section was contributed by Peter Schepers and slightly edited by
Ettore Perazzoli.)

This format was defined in 1998 as a cooperative effort between several
emulator people, mainly Per Håkan Sundell, author of the CCS64 C64
emulator, Andreas Boose of the VICE CBM emulator team and Joe
Forster/STA, the author of Star Commander.  It was the first real public
attempt to create a format for the emulator community which removed
almost all of the drawbacks of the other existing image formats, namely
@code{D64}.

The intention behind @code{G64} is not to replace the widely used
@code{D64} format, as @code{D64} works fine with the vast majority of
disks in existence.  It is intended for those small percentage of
programs which demand to work with the 1541 drive in a non-standard way,
such as reading or writing data in a custom format.  The best example is
with speeder software such as Action Cartridge in Warp Save mode or
Vorpal which write track/sector data in another format other than
standard GCR.  The other obvious example is copy-protected software
which looks for some specific data on a track, like the disk ID, which
is not stored in a standard @code{D64} image.

@code{G64} has a deceptively simply layout for what it is capable of
doing.  We have a signature, version byte, some predefined size values,
and a series of offsets to the track data and speed zones.  It is what's
contained in the track data areas and speed zones which is really at the
heart of this format.

Each track entry in simply the raw stream of GCR data, just what a read
head would see when a diskette is rotating past it.  How the data gets
interpreted is up to the program trying to access the disk.  Because the
data is stored in such a low-level manner, just about anything can be
done.  Most of the time I would suspect the data in the track would be
standard sectors, with SYNC, GAP, header, data and checksums.  The
arrangement of the data when it is in a standard GCR sector layout is
beyond the scope of this document.

Since it is a flexible format in both track count and track byte size,
there is no ``standard'' file size.  However, given a few constants like
42 tracks and halftracks, a track size of 7928 bytes and no speed offset
entries, the typical file size will a minimum of 333744 bytes.

Below is a dump of the header, broken down into its various parts.
After that will be an explanation of the track offset and speed zone
offset areas, as they demand much more explanation.

@example
Addr  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
----  -----------------------------------------------
0000: 47 43 52 2D 31 35 34 31 00 54 F8 1E .. .. .. ..
@end example

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $0000-0007
@tab File signature (@code{GCR-1541})
@item $0008
@tab @code{G64} version (presently only $00 defined)
@item $0009
@tab Number of tracks in image (usually $54, decimal 84)
@item $000A-000B
@tab Size of each stored track in bytes (usually 7928, or $1EF8) in LO/HI format.
@end multitable

An obvious question here is ``why are there 84 tracks defined when a
normal @code{D64} disk only has 35 tracks?''  Well, by definition, this
image includes all half-tracks, so there are actually 42 tracks and 42
half tracks.  The 1541 stepper motor can access up to 42 tracks and the
in-between half-tracks.  Even though using more than 35 tracks is not
typical, it was important to define this format from the start with what
the 1541 is capable of doing, and not just what it typically does.

At first, the defined track size value of 7928 bytes may seem to be
arbitrary, but it is not.  It is determined by the fastest write speed
possible (speed zone 0), coupled with the average rotation speed of the
disk (300 rpm).  After some math, the answer that actually comes up is
7692 bytes.  Why the discrepency between the actual size of 7692 and the
defined size of 7928? Simply put, not all drives rotate at 300 rpm.
Some can be faster or slower, so a upper safety margin of +3% was built
added, in case some disks rotate slower and can write more data.  After
applying this safety factor, and some rounding-up, 7928 bytes per track
was arrived at.

Also note that this upper limit of 7928 bytes per track really only
applies to 1541 and compatible disks.  If this format were applied to
another disk type like the SFD1001, this value would be higher.

Below is a dump of the first section of a @code{G64} file, showing the offsets
to the data portion for each track and half-track entry. Following that
is a dump of the speed zone offsets.

@example
Addr  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
----  -----------------------------------------------
0000: .. .. .. .. .. .. .. .. .. .. .. .. AC 02 00 00
0010: 00 00 00 00 A6 21 00 00 00 00 00 00 A0 40 00 00
0020: 00 00 00 00 9A 5F 00 00 00 00 00 00 94 7E 00 00
0030: 00 00 00 00 8E 9D 00 00 00 00 00 00 88 BC 00 00
0040: 00 00 00 00 82 DB 00 00 00 00 00 00 7C FA 00 00
0050: 00 00 00 00 76 19 01 00 00 00 00 00 70 38 01 00
0060: 00 00 00 00 6A 57 01 00 00 00 00 00 64 76 01 00
0070: 00 00 00 00 5E 95 01 00 00 00 00 00 58 B4 01 00
0080: 00 00 00 00 52 D3 01 00 00 00 00 00 4C F2 01 00
0090: 00 00 00 00 46 11 02 00 00 00 00 00 40 30 02 00
00A0: 00 00 00 00 3A 4F 02 00 00 00 00 00 34 6E 02 00
00B0: 00 00 00 00 2E 8D 02 00 00 00 00 00 28 AC 02 00
00C0: 00 00 00 00 22 CB 02 00 00 00 00 00 1C EA 02 00
00D0: 00 00 00 00 16 09 03 00 00 00 00 00 10 28 03 00
00E0: 00 00 00 00 0A 47 03 00 00 00 00 00 04 66 03 00
00F0: 00 00 00 00 FE 84 03 00 00 00 00 00 F8 A3 03 00
0100: 00 00 00 00 F2 C2 03 00 00 00 00 00 EC E1 03 00
0110: 00 00 00 00 E6 00 04 00 00 00 00 00 E0 1F 04 00
0120: 00 00 00 00 DA 3E 04 00 00 00 00 00 D4 5D 04 00
0130: 00 00 00 00 CE 7C 04 00 00 00 00 00 C8 9B 04 00
0140: 00 00 00 00 C2 BA 04 00 00 00 00 00 BC D9 04 00
0150: 00 00 00 00 B6 F8 04 00 00 00 00 00 .. .. .. ..
@end example

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $000C-000F
@tab Offset to stored track 1.0 ($000002AC, in LO/HI format, see below for more)
@item $0010-0013
@tab Offset to stored track 1.5 ($00000000)
@item $0014-0017
@tab Offset to stored track 2.0 ($000021A6)
@item @dots{}
@item $0154-0157
@tab Offset to stored track 42.0 ($0004F8B6)
@item $0158-015B
@tab Offset to stored track 42.5 ($00000000)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
0150: .. .. .. .. .. .. .. .. .. .. .. .. 03 00 00 00
0160: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
0170: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
0180: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
0190: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01A0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01B0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01C0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01D0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00
01E0: 00 00 00 00 02 00 00 00 00 00 00 00 02 00 00 00
01F0: 00 00 00 00 02 00 00 00 00 00 00 00 02 00 00 00
0200: 00 00 00 00 02 00 00 00 00 00 00 00 02 00 00 00
0210: 00 00 00 00 02 00 00 00 00 00 00 00 01 00 00 00
0220: 00 00 00 00 01 00 00 00 00 00 00 00 01 00 00 00
0230: 00 00 00 00 01 00 00 00 00 00 00 00 01 00 00 00
0240: 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00
0250: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0260: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0270: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0280: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0290: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
02A0: 00 00 00 00 00 00 00 00 00 00 00 00 .. .. .. ..
@end example

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $015C-015F
@tab Speed zone entry for track 1 ($03, in LO/HI  format, see below for more)
@item $0160-0163
@tab Speed zone entry for track 1.5 ($03)
@item @dots{}
@item $02A4-02A7
@tab Speed zone entry for track 42 ($00)
@item $02A8-02AB
@tab Speed zone entry for track 42.5 ($00)
@end multitable

Starting here at $02AC is the first track entry (from above, it is the
first entry for track 1.0)

The track offsets (from above) require some explanation.  When one is
set to all 0's, no track data exists for this entry.  If there is a
value, it is an absolute reference into the file (starting from the
beginning of the file).  From the track 1.0 entry we see it is set for
$000002AC.  Going to that file offset, here is what we see@dots{}

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
02A0: .. .. .. .. .. .. .. .. .. .. .. .. 0C 1E FF FF
02B0: FF FF FF 52 54 B5 29 4B 7A 5E 95 55 55 55 55 55
02C0: 55 55 55 55 55 55 FF FF FF FF FF 55 D4 A5 29 4A
02D0: 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52
@end example

@multitable @columnfractions .2 .8
@item @b{Offset}
@tab @b{Description}
@item $02AC-02AD
@tab Actual size of stored track (7692 or $1E0C, in LO/HI format)
@item $02AE-02AE+$1E0C
@tab Track data
@end multitable

Following the track data is filler bytes.  In this case, there are 368
bytes of unused space.  This space can contain anything, but for the
sake of those wishing to compress these images for storage, they should
all be set to the same value.  In the sample I used, these are all set
to $FF.

Below is a dump of the end of the track 1.0 data area.  Note the actual
track data ends at address $20B9, with the rest of the block being
unused, and set to $FF.

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
1FE0: 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52
1FF0: 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94
2000: A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5
2010: 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29
2020: 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A
2030: 55 55 55 55 55 55 FF FF FF FF FF FF FF FF FF FF
2040: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2050: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2060: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2070: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2080: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2090: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20A0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20B0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20C0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20D0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20E0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20F0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2100: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2110: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2120: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2130: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2140: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2150: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2160: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2170: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2180: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
2190: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
21A0: FF FF FF FF FF FF .. .. .. .. .. .. .. .. .. ..
@end example

The speed offset entries can be a little more complex. The 1541 has four
speed zones defined, which means the drive can write data at four
distinct speeds.  On a normal 1541 disk, these zones are as follows:

@multitable @columnfractions .5 .5
@item @b{Track Range}
@tab @b{Speed Zone}
@item 1-17
@tab 3  (highest writing speed)
@item 18-24
@tab 2
@item 25-30
@tab 1
@item 31 and up
@tab 0 (lowest writing speed)
@end multitable

Note that you can, through custom programming of the 1541, change the
speed zone of any track to something different (change the 3 to a 0) and
write data differently.  From the dump of the speed offset entries
above, we see that all the entries are in the range of 0-3. If any entry
is less than 4, this is not considered a speed offset but defines the
whole track to be recorded at that one speed.

In the example I had, there were no offsets defined, so no speed zone
dump can be shown.  However, I can define what should be there.  You
will have a block of data, 1982 bytes long.  Each byte is encoded to
represent the speed of 4 bytes in the track offset area, and is broken
down as follows:

@example
Speed entry $FF:  in binary %11111111
                             |'|'|'|'
                             | | | |
                             | | | +- 4'th byte speed (binary 11, 3 dec)
                             | | +--- 3'rd byte speed (binary 11, 3 dec)
                             | +----- 2'nd byte speed (binary 11, 3 dec)
                             +------- 1'st byte speed (binary 11, 3 dec)
@end example

It was very smart thinking to allow for two speed zone settings, one in
the offset block and another defining the speed on a per-byte basis.  If
you are working with a normal disk, where each track is one constant
speed, then you don't need the extra blocks of information hanging
around the image, wasting space.

What may not be obvious is the flexibility of this format to add tracks
and speed offset zones at will.  If a program decides to write a track
out with varying speeds, and no speed offset exist, a new block will be
created by appending it to the end of the image, and the offset pointer
for that track set to point to the new block.  If a track has no offset
yet, meaning it doesn't exist (like a half-track), and one needs to be
added, the same procedure applies.  The location of the actual track or
speed zone data is not important, meaning they do not have to be in any
particular order since they are all referenced by the offsets at the
beginning of the image.

@c @node FIXME
@section The P64 NRZI flux pulse disk image format

@c FIXME: the P64 section needs to be style-checked.

This section is taken from "P64 file format specification" by Benjamin 'BeRo' 
Rosseaux.

All values are in little endian order ! 

@c @node FIXME
@subsection P64 Header Layout

@example
        0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
      +---------------------------------------------------------------+
0000: |'P'|'6'|'4'|'-'|'1'|'5'|'4'|'1'|    Version    |     Flags     |   
      +---------------+---------------+-------------------------------+
0010: |     Size      | CRC32Checksum |
      +-------------------------------+
@end example

         Version:  File format version, current is 0x00000000
      
            Size   Size of the following whole chunk content stream
      
           Flags:  Bit    0 = Write protect
                   Bit 1-31 = Reserved, all set to 0 when creating a file, 
                              preserve existing value when updating
       
   CRC32CheckSum:  CRC32 checksum of the following whole chunk content stream                

@c @node FIXME
@subsection P64 Chunk Header Layout

@example
        0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
      +-----------------------------------------------+
0000: |Chunk Signature|      Size     | CRC32Checksum |   
      +-----------------------------------------------+
@end example

 Chunk signature:  Signature of chunk
      
            Size:  Size of the chunk data
      
   CRC32CheckSum:  CRC32 checksum of the chunk data                

@c @node FIXME
@subsection P64 Chunk 'HTPx' Layout

                          | x = half track index byte |
                          +---------------------------+
                          
       Track 18 = Half track 36 = Half track index byte decimal value 36
                          
              Half track NRZI transition flux pulse data chunk block                          
                                                                                         
@example
        0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
      +---------------------------------------------------------------+
0000: |  Count pulses |     Size      | ..... Range-encoded data .... |    
      +---------------------------------------------------------------+
@end example

    Count pulses:  Count of the NRZI transition flux pulses in half track 
      
            Size:  Size of the range-encoded data
            
@c @node FIXME
@subsection 'HTPx' Range encoded data format

             Hint: For a working C implememtation see p64.c and p64.h

The range coder is a FPAQ0-style range coder combined with 12-bit 0-order 
models, one model per byte with one bit per byte processing.

@example
 +--------------------------------------------------------------------------+
 |   Sub stream     | Count of models |  Size per model  | Total value bits |
 +------------------+-----------------+------------------+------------------+
 |     Position     |        4        |      65536       |        32        |
 +------------------+-----------------+------------------+------------------+
 |     Strength     |        4        |      65536       |        32        | 
 +------------------+-----------------+------------------+------------------+
 |   Position flag  |        1        |        2         |        1         |
 +------------------+-----------------+------------------+------------------+
 |   Strenth flag   |        1        |        2         |        1         | 
 +------------------+-----------------+------------------+------------------+
 +===Total models===|        10       |==================|==================|
 +--------------------------------------------------------------------------+
@end example

All initial model state values are initialized with zero.
 
All initial model probability values are initialized with 2048. 

These model probability values will be updating in a adaptive way on the
fly and not precalculated before the encoding and even not loaded before 
the decoding, see pseudo code below.

16000000 Hz / 5 rotations per second at 300 RPM = maximal 3200000 flux pulses 
        
So NRZI transition flux pulse positions are in the 0 .. 3199999 value range, 
which is also a exact single rotation, where each time unit is a cycle at 
16 MHz with 300 RPM as a mapping for the ideal case.    
  
The NRZI transition flux pulse stength are in the 0x00000000 .. 0xffffffff
value range, where 0xffffffff indices a strong flux pulse, that always 
triggers, and 0x00000001 indices a weak flux pulse, that almost never 
triggers, and 0x00000000 indices a flux pulse, that absolutly never 
triggers.            
        
For 32-bit values, the model sub streams are subdivided byte wide in a 
little-endian manner, and each byte is processed bitwise with model 
probability shifting of 4 bits, just as:

Pascal-Style pseudo code:
@example
procedure WriteDWord(Model, Value : longword);                             
var ByteValue, ByteIndex, Context, Bit : longword;                         
begin                                                                      
  for ByteIndex := 0 to 3 do begin                                         
    ByteValue := (Value shr (ByteIndex shl 3)) and $ff;                    
    Context := 1;                                                          
    for Bit := 7 downto 0 do begin                                         
      Context := (Context shl 1) or RangeCoderEncodeBit(                   
                    RangeCoderProbabilities[                               
                     RangeCoderProbabilityOffsets[Model + ByteIndex] +     
                     (((RangeCoderProbabilityStates[Model + ByteIndex]      
                     shl 8) or Context) and $ffff)], 4, (ByteValue shr     
                     Bit) and 1);                                          
    end;                                                                   
    RangeCoderProbabilityStates[Model+ByteIndex] := ByteValue;             
  end;                                                                     
end;                                                                       
@end example

And for 1-bit flag values it is much simpler, but also with model probability 
shifting of 4 bits, just as:

Pascal-Style pseudo code:
@example
procedure WriteBit(Model, Value : longword);                               
begin                                                                      
   RangeCoderProbabilityStates[Model] :=                                   
     RangeCoderEncodeBit(RangeCoderProbabilities[                          
       RangeCoderProbabilityOffsets[Model] +                               
         RangeCoderProbabilityStates[Model]], 4, Value and 1);             
end;                                                                       
@end example

The position and strength values are delta-encoded. If a value is equal to 
the last previous value, then the value will not encoded, instead, a flag for
this will encoded. First the position value will encoded, then the stength 
value. If the last position delta is 0, then it is a track stream end marker.

Pascal-Style pseudo code:
@example
LastPosition := 0;                                                         
PreviousDeltaPosition := 0                                                 
                                                                           
LastStrength := 0;                                                         
                                                                           
for PulseIndex := 0 to PulseCount - 1 do begin                             
                                                                           
  DeltaPosition := Pulses[PulseIndex].Position - LastPosition;             
  if PreviousDeltaPosition <> DeltaPosition then begin                     
    PreviousDeltaPosition := DeltaPosition;                                
    WriteBit(ModelPositionFlag, 1)                                         
    WriteDWord(ModelPosition, DeltaPosition);                              
  end else begin                                                           
    WriteBit(ModelPositionFlag, 0);                                        
  end;                                                                     
  LastPosition := Pulses[PulseIndex].Position;                              
                                                                           
  if LastStrength <> Pulses[PulseIndex].Strength then begin                
    WriteBit(ModelStrengthFlag, 1)                                         
    WriteDWord(ModelStrength, Pulses[PulseIndex].Strength - LastStrength);   
  end else begin                                                           
    WriteBit(ModelStrengthFlag, 0);                                         
  end;                                                                       
  LastStrength := Pulses^[PulseIndex].Strength;                            
                                                                           
end;                                                                       
                                                                           
// End code                                                                
WriteBit(ModelPositionFlag, 1);                                            
WriteDWord(ModelPosition, 0);                                              
@end example
 
The decoding is simply just in the another direction way.
  
Pseudo code for a FPAQ0-style carryless range coder:

Pascal-Style pseudo code:
@example
procedure RangeCoderInit; // At encoding and decoding start                
begin                                                                      
  RangeCode := 0;                                                          
  RangeLow := 0;                                                           
  RangeHigh := $ffffffff;                                                  
end;                                                                       
                                                                           
procedure RangeCoderStart; // At decoding start                            
var Counter : longword;                                                       
begin                                                                      
  for Counter := 1 to 4 do begin                                           
   RangeCode := (RangeCode shl 8) or ReadByteFromInput;                    
  end;                                                                     
end;                                                                       
                                                                           
procedure RangeCoderFlush; // At encoding end                              
var Counter : longword;                                                      
begin                                                                      
  for Counter := 1 to 4 do begin                                           
    WriteByteToOutput(RangeHigh shr 24);                                   
    RangeHigh := RangeHigh shl 8;                                          
  end;                                                                     
end;                                                                        
                                                                           
procedure RangeCoderEncodeNormalize;                                          
begin                                                                      
  while ((RangeLow xor RangeHigh) and $ff000000) = 0 do begin              
   WriteByteToOutput(RangeHigh shr 24);                                    
   RangeLow := RangeLow shl 8;                                             
   RangeHigh := (RangeHigh shl 8) or $ff;                                    
  end;                                                                      
end;                                                                        
                                                                           
function RangeCoderEncodeBit(var Probability : longword; Shift,            
                             BitValue : longword) : longword;               
begin                                                                      
  RangeMiddle := RangeLow + (((RangeHigh - RangeLow) shr 12) *             
                              Probability);                                  
  if BitValue <> 0 then begin                                               
    inc(Probability, ($fff - Probability) shr Shift);                      
    RangeHigh := RangeMiddle;                                                
  end else begin                                                           
    dec(Probability, Probability shr Shift);                               
    RangeLow := RangeMiddle + 1;                                           
  end;                                                                     
  RangeCoderEncodeNormalize;                                               
  result := BitValue;                                                      
end;                                                                       
                                                                            
procedure RangeCoderDecodeNormalize;                                        
begin                                                                      
  while ((RangeLow xor RangeHigh) and $ff000000) = 0 do begin              
    RangeLow := RangeLow shl 8;                                            
    RangeHigh := (RangeHigh shl 8) or $ff;                                 
    RangeCode := (RangeCode shl 8) or ReadByteFromInput;                   
  end;                                                                     
end;                                                                       
                                                                            
function RangeCoderDecodeBit(var Probability : longword;                   
                             Shift : longword) : longword;                 
begin                                                                      
  RangeMiddle := RangeLow + (((RangeHigh - RangeLow) shr 12) *             
                             Probability);                                 
  if RangeCode <= RangeMiddle then begin                                   
    inc(Probability, ($fff - Probability) shr Shift);                      
    RangeHigh := RangeMiddle;                                              
    result := 1;                                                           
  end else begin                                                           
    dec(Probability, Probability shr Shift);                               
    RangeLow := RangeMiddle + 1;                                           
    result := 0;                                                           
  end;                                                                     
  RangeCoderDecodeNormalize;                                               
end;                                                                       
@end example

The probability may be never zero! But that can't happen here with this 
adaptive model in this P64 file format, since the adaptive model uses a
shift factor of 4 bits and initial probabilities value of 2048, so the 
probability has a value range from 15 up to 4080 here. If you do want to use 
the above range coder routines for other stuff with other probability models, 
then you must to ensure that the probability output value is never zero, for 
example with  "probability |= (probability < 1); " in C.     
  
@c @node FIXME
@subsection P64 Chunk 'DONE' Layout

This is the last empty chunk for to signalize that the correct file end is
reached.


@node D64, X64 , G64, File formats
@section The D64 disk image format

@c FIXME: the D64 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

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
@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
@end multitable

(*) Tracks 36-40 apply to 40-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. 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 or 40 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
@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.

These first errors are "seek" errors, where the disk
controller is simply reading headers and looking at
descriptor bytes, checksums, format ID's and reporting what
errors it sees. These errors do *not* necessarily apply to
the exact sector being looked for. This fact makes
duplication of these errors very unreliable.

Code    : $03
Error   : 21
Type    : Seek
Message : No SYNC sequence found.

Each sector data block and header block are preceeded by
SYNC marks. If *no* sync sequence is found within 20
milliseconds (only ~1/10 of a disk rotation!) then this
error is generated. This error used to mean the entire
track is bad, but it does not have to be the case. Only
a small area of the track needs to be without a SYNC
mark and this error will be generated.

Converting this error to a D64 is very problematic
because it depends on where the physical head is on the
disk when a read attempt is made. If it is on valid
header/sectors then it won't occur. If it happens over
an area without SYNC marks, it will happen.

Code    : $02
Error   : 20
Type    : Seek
Message : Header descriptor byte not found (HEX $08, GCR $52)

Each sector is preceeded by an 8-byte GCR header block, which
starts with the value $52 (GCR). If this value is not found
after 90 attempts, this error is generated.

Basically, what a track has is SYNC marks, and possibly valid
data blocks, but no valid header descriptors.

Code    : $09
Error   : 27
Type    : Seek
Message : Checksum error in header block

The header block contains a checksum value, calculated by
XOR'ing the TRACK, SECTOR, ID1 and ID2 values. If this
checksum is wrong, this error is generated.

Code    : $0B
Error   : 29
Type    : Seek
Message : Disk sector ID mismatch

The ID's from the header block of the currently read sector are
compared against the ones from the low-level header of 18/0. If
there is a mismatch, this error is generated.

Code    : $02
Error   : 20
Type    : Seek
Message : Header block not found

This error can be reported again when searching for the correct
header block. An image of the header is built and searched for,
but not found after 90 read attempts. Note the difference from
the first occurance. The first one only searches for a valid
ID, not the whole header.

Note that error 20 occurs twice during this phase. The first
time is when a header ID is being searched for, the second is
when the proper header pattern for the sector being searched
for is not found.

From this point on, all the errors apply to the specific
sector you are looking for. If a read passed all the previous
checks, then we are at the sector being searched for.

Note that the entire sector is read before these errors are
detected. Therefore the data, checksum and off bytes are
available.

Code    : $04
Error   : 22
Type    : Read
Message : Data descriptor byte not found (HEX $07, GCR $55)

Each sector data block is preceeded by the value $07, the
"data block" descriptor. If this value is not there, this
error is generated. Each encoded sector has actually 260
bytes. First is the descriptor byte, then follows the
256 bytes of data, a checksum, and two "off" bytes.

Code    : $05
Error   : 23
Type    : Read
Message : Checksum error in data block

The checksum of the data read of the disk is calculated, and
compared against the one stored at the end of the sector. If
there's a discrepancy, this error is generated.

Code    : $0F
Error   : 74
Type    : Read
Message : Drive Not Ready (no disk in drive or no device 1)

These errors only apply when writing to a disk. I don't see the
usefulness of having these as they cannot be present when only
*reading* a disk.

Code    : $06
Error   : 24
Type    : Write
Message : Write verify (on format)

Code    : $07
Error   : 25
Type    : Write
Message : Write verify error

Once the GCR-encoded sector is written out, the drive waits for
the sector to come around again and verifies the whole 325-byte
GCR block. Any errors encountered will generate this error.

Code    : $08
Error   : 26
Type    : Write
Message : Write protect on

Self explanatory. Remove the write-protect tab, and try again.

Code    : $0A
Error   : 28
Type    : Write
Message : Write error

In actual fact, this error never occurs, but it is included
for completeness.

This is not an error at all, but it gets reported when the
read of a sector is ok.

Code    : $01
Error   : 00
Type    : N/A
Message : No error.

Self explanatory. No errors were detected in the reading
and decoding of the sector.

The advantage with using the 35 track D64 format, regardless of
error bytes, is that it can be converted directly back to a 1541
disk by either using the proper cable and software on the PC, or
send it down to the C64 and writing it back to a 1541. It is the
best documented format since it is also native to the C64, with
many books explaining the disk layout and the internals of the
1541.

@node X64, D71, D64, File formats
@section The X64 disk image format

@c FIXME: the X64 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

This file type, created by Teemu Rantanen, is used on the X64
emulator (a UNIX-based emulator) which has been superceeded by
VICE. Both VICE and X64 support the X64 file standard, with
VICE also supporting the regular D64 and T64 files.

X64 is not a specific type of file, but rather encompasses
*all* known C64 disk types (hard disk, floppies, etc). An X64
is created by prepending a 64-byte header to an existing image
(1541, 1571, etc) and setting specific bytes which describe
what type of image follows. This header has undergone some
revision, and this description is based on the 1.02 version,
which was the last known at the time of writing.

The most common X64 file you will see is the D64 variety,
typically 174912 bytes long (174848 for the D64 and 64 bytes
for the header, assuming no error bytes are appended). The
header layout (as used in 64COPY) is as follows:

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
0000: 43 15 41 64 01 02 01 23 00 00 00 00 00 00 00 00
0010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0040: XX XX XX <- standard C64 image starts here@dots{}.
@end example

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$03
@tab This is the "Magic header" ($43 $15 $41 $64)
@item $04
@tab Header version major ($01)
@item $05
@tab Header version minor ($01, now its up to $02)
@item $06
@tab Device type represented
@item $07
@tab Maximum tracks in image (only in version 1.02 or greater) 1540/41/70: 35 1571: 35 1581: 80 (Logical single-sided disk)
@item $08
@tab Number of disk sides in image. This value must be $00 for all 1541 and 1581 formats. $00=No second side $01=Second side
@item $09
@tab Error data flag.
@item $0A-$1F
@tab Unused, set to $00
@item $20-$3E
@tab Disk image description (in ASCII or ISO Latin/1)
@item $3F
@tab Always set to $00
@item $40-
@tab Standard C64 file begins here.
@end multitable

The device types are:

@multitable @columnfractions .2 .8
@item @b{Value}
@tab @b{Drive type}
@item $00
@tab 1540 See note below@dots{}
@item $01
@tab 1541 (Default)
@item $02
@tab 1542
@item $03
@tab 1551
@item $04
@tab 1570
@item $05
@tab 1571
@item $06
@tab 1572
@item $08
@tab 1581
@item $10
@tab 2031 or 4031
@item $11
@tab 2040 or 3040
@item $12
@tab 2041
@item $18
@tab 4040
@item $20
@tab 8050
@item $21
@tab 8060
@item $22
@tab 8061
@item $30
@tab SFD-1001
@item $31
@tab 8250
@item $32
@tab 8280
@end multitable

The first four bytes used for the device type at position $06
($00 to $03) are functionally the same, and are compatible with
older version of X64 files. Some old X64 files might have $00
for the device type (instead of $01), but it makes no real
difference.

As most instances of X64 files will be strictly 1541 images,
bytes $08-$3F are set to zero, and some versions of the X64
emulator don't use bytes $08-$3F.

@node D71, D81, X64, File formats
@section The D71 disk image format

@c FIXME: the D71 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

Similar to the D64 (1541), the 1571 drive can operate in either
single-sided (1541 compatible) mode or double-sided (1571) mode. In
this section I will be dealing with the double-sided mode only. For
the breakdown of the single-sided mode, see the D64 section.

The D71 has 70 tracks, double that of the 1541, with a DOS file
size of 349696 bytes. If the error byte block (1366 bytes) is
attached, this makes the file size 351062 bytes. The track range
and offsets into the D71 files are as follows:

@multitable @columnfractions .5 .25 .25
@item @b{Track}
@tab @b{Sec/trk}
@tab @b{# Sectors}
@item 1-17 (side 0)
@tab 21
@tab 357
@item 18-24 (side 0)
@tab 19
@tab 133
@item 25-30 (side 0)
@tab 18
@tab 108
@item 31-35 (side 0)
@tab 17
@tab 85
@item 36-52 (side 1)
@tab 21
@tab 357
@item 53-59 (side 1)
@tab 19
@tab 133
@item 60-65 (side 1)
@tab 18
@tab 108
@item 66-70 (side 1)
@tab 17
@tab 85
@end multitable

@multitable @columnfractions .25 .25 .25 .25
@item @b{Track}
@tab @b{#Sect}
@tab @b{#SectorsIn}
@tab @b{D71 Offset}
@item 1
@tab 21
@tab 0
@tab $00000
@item 2
@tab 21
@tab 21
@tab $01500
@item 3
@tab 21
@tab 42
@tab $02A00
@item 4
@tab 21
@tab 63
@tab $03F00
@item 5
@tab 21
@tab 84
@tab $05400
@item 6
@tab 21
@tab 105
@tab $06900
@item 7
@tab 21
@tab 126
@tab $07E00
@item 8
@tab 21
@tab 147
@tab $09300
@item 9
@tab 21
@tab 168
@tab $0A800
@item 10
@tab 21
@tab 189
@tab $0BD00
@item 11
@tab 21
@tab 210
@tab $0D200
@item 12
@tab 21
@tab 231
@tab $0E700
@item 13
@tab 21
@tab 252
@tab $0FC00
@item 14
@tab 21
@tab 273
@tab $11100
@item 15
@tab 21
@tab 294
@tab $12600
@item 16
@tab 21
@tab 315
@tab $13B00
@item 17
@tab 21
@tab 336
@tab $15000
@item 18
@tab 19
@tab 357
@tab $16500
@item 19
@tab 19
@tab 376
@tab $17800
@item 20
@tab 19
@tab 395
@tab $18B00
@item 21
@tab 19
@tab 414
@tab $19E00
@item 22
@tab 19
@tab 433
@tab $1B100
@item 23
@tab 19
@tab 452
@tab $1C400
@item 24
@tab 19
@tab 471
@tab $1D700
@item 25
@tab 18
@tab 490
@tab $1EA00
@item 26
@tab 18
@tab 508
@tab $1FC00
@item 27
@tab 18
@tab 526
@tab $20E00
@item 28
@tab 18
@tab 544
@tab $22000
@item 29
@tab 18
@tab 562
@tab $23200
@item 30
@tab 18
@tab 580
@tab $24400
@item 31
@tab 17
@tab 598
@tab $25600
@item 32
@tab 17
@tab 615
@tab $26700
@item 33
@tab 17
@tab 632
@tab $27800
@item 34
@tab 17
@tab 649
@tab $28900
@item 35
@tab 17
@tab 666
@tab $29A00
@item 36
@tab 21
@tab 683
@tab $2AB00
@item 37
@tab 21
@tab 704
@tab $2C000
@item 38
@tab 21
@tab 725
@tab $2D500
@item 39
@tab 21
@tab 746
@tab $2EA00
@item 40
@tab 21
@tab 767
@tab $2FF00
@item 41
@tab 21
@tab 788
@tab $31400
@item 42
@tab 21
@tab 809
@tab $32900
@item 43
@tab 21
@tab 830
@tab $33E00
@item 44
@tab 21
@tab 851
@tab $35300
@item 45
@tab 21
@tab 872
@tab $36800
@item 46
@tab 21
@tab 893
@tab $37D00
@item 47
@tab 21
@tab 914
@tab $39200
@item 48
@tab 21
@tab 935
@tab $3A700
@item 49
@tab 21
@tab 956
@tab $3BC00
@item 50
@tab 21
@tab 977
@tab $3D100
@item 51
@tab 21
@tab 998
@tab $3E600
@item 52
@tab 21
@tab 1019
@tab $3FB00
@item 53
@tab 19
@tab 1040
@tab $41000
@item 54
@tab 19
@tab 1059
@tab $42300
@item 55
@tab 19
@tab 1078
@tab $43600
@item 56
@tab 19
@tab 1097
@tab $44900
@item 57
@tab 19
@tab 1116
@tab $45C00
@item 58
@tab 19
@tab 1135
@tab $46F00
@item 59
@tab 19
@tab 1154
@tab $48200
@item 60
@tab 18
@tab 1173
@tab $49500
@item 61
@tab 18
@tab 1191
@tab $4A700
@item 62
@tab 18
@tab 1209
@tab $4B900
@item 63
@tab 18
@tab 1227
@tab $4CB00
@item 64
@tab 18
@tab 1245
@tab $4DD00
@item 65
@tab 18
@tab 1263
@tab $4EF00
@item 66
@tab 17
@tab 1281
@tab $50100
@item 67
@tab 17
@tab 1298
@tab $51200
@item 68
@tab 17
@tab 1315
@tab $52300
@item 69
@tab 17
@tab 1332
@tab $53400
@item 70
@tab 17
@tab 1349
@tab $54500
@end multitable

The directory structure is the same as a D64/1541. All the same
filetypes apply, the directory still only holds 144 files per
disk and should only exist on track 18.

The first two bytes of the sector ($12/$04 or 18/4) indicate
the location of the next track/sector of the directory. If the
track value is set to $00, then it is the last sector of the
directory. It is possible, however unlikely, that the directory
may *not* be competely on track 18 (some disks do exist like
this). Just follow the chain anyhow.

When the directory is done, the track value will be $00. The
sector link should contain a value of $FF, meaning the whole
sector is allocated, but the actual value doesn't matter. The
drive will return all the available entries anyways. This is a
breakdown of a standard directory sector and entry:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 12 04 82 11 00 4A 45 54 20 53 45 54 20 57 49 4C
10: 4C 59 A0 A0 A0 00 00 00 00 00 00 00 00 00 2B 00
20: 00 00 82 0F 01 4A 53 57 20 31 A0 A0 A0 A0 A0 A0
30: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 BF 00
40: 00 00 82 06 03 53 4F 4E 20 4F 46 20 42 4C 41 47
50: 47 45 52 A0 A0 00 00 00 00 00 00 00 00 00 AE 00
60: 00 00 82 15 0D 50 4F 54 54 59 20 50 49 47 45 4F
70: 4E A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 A2 00
80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First directory entry
@item $20-$3F
@tab Second dir entry
@item $40-$5F
@tab Third dir entry
@item $60-$7F
@tab Fourth dir entry
@item $80-$9F
@tab Fifth dir entry
@item $A0-$BF
@tab Sixth dir entry
@item $C0-$DF
@tab Seventh dir entry
@item $E0-$FF
@tab Eighth dir entry
@end multitable

This is a breakdown of a standard directory entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next directory sector ($00/$FF if its the last sector)
@item $02
@tab File type
@item $03-$04
@tab Track/sector location of first sector of file
@item $05-$14
@tab 16 character filename (in PETASCII, padded with $A0)
@item $15-$16
@tab Track/Sector location of first side-sector block (REL file only)
@item $17
@tab REL file record length (REL file only, max. value 254)
@item $18-$1D
@tab Unused (except with GEOS disks)
@item $1E-$1F
@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254
@end multitable

The file type field is used as follows:

@multitable @columnfractions .2 .8
@item @b{Bits}
@tab @b{Description}
@item 0-3
@tab The actual file type
@item 4
@tab Unused
@item 5
@tab Used only during SAVE-@@ replacement
@item 6
@tab Locked flag (Set produces ">" locked files)
@item 7
@tab Closed flag (Not set produces "*", or "splat" files)
@end multitable

The actual file type can be one of the following:

@multitable @columnfractions .2 .2 .6
@item @b{Binary}
@tab @b{Decimal}
@tab @b{File type}
@item 0000
@tab 0
@tab DEL
@item 0001
@tab 1
@tab SEQ
@item 0010
@tab 2
@tab PRG
@item 0011
@tab 3
@tab USR
@item 0100
@tab 4
@tab REL
@end multitable

Values 5-15 are illegal, but if used will produce very strange
results. The 1571 is inconsistent in how it treats these bits.
Some routines use all 4 bits, others ignore bit 3, resulting in
values from 0-7.

When the 1571 is in is native ("1571") mode, files are stored
with a sector interleave of 6, rather than 10 which the 1541
(and the 1571 in "1541" mode) uses. The directory still uses an
interleave of 3.

@c @node FIXME
@subsection Non-Standard & Long Directories

Most Commodore floppy disk drives use a single dedicated
directory track where all filenames are stored. This limits the
number of files stored on a disk based on the number of sectors
on the directory track. There are some disk images that contain
more files than would normally be allowed. This requires
extending the directory off the default directory track by
changing the last directory sector pointer to a new track,
allocating the new sectors in the BAM, and manually placing (or
moving existing) file entries there. The directory of an
extended disk can be read and the files that reside there can be
loaded without problems on a real drive. However, this is still
a very dangerous practice as writing to the extended portion of
the directory will cause directory corruption in the non-
extended part. Many of the floppy drives core ROM routines
ignore the track value that the directory is on and assume the
default directory track for operations.

To explain: assume that the directory has been extended from
track 18 to track 19/6 and that the directory is full except
for a few slots on 19/6. When saving a new file, the drive DOS
will find an empty file slot at 19/6 offset $40 and correctly
write the filename and a few other things into this slot. When
the file is done being saved the final file information will
be written to 18/6 offset $40 instead of 19/6 causing some
directory corruption to the entry at 18/6. Also, the BAM
entries for the sectors occupied by the new file will not be
saved and the new file will be left as a SPLAT (*) file.

Attempts to validate the disk will result in those files
residing off the directory track to not be allocated in the
BAM, and could also send the drive into an endless loop. The
default directory track is assumed for all sector reads when
validating so if the directory goes to 19/6, then the validate
code will read 18/6 instead. If 18/6 is part of the normal
directory chain then the validate routine will loop endlessly.

@c @node FIXME
@subsection Bam layout The BAM is somewhat different as it now has to
take 35 new tracks into account. In order to do this, most of
the extra BAM information is stored on track 53/0, and the
remaining sectors on track 53 are marked in the BAM as
allocated. This does mean that except for one allocated
sector on track 53, the rest of the track is unused and
wasted. (Track 53 is the equivalent to track 18, but on the
flip side of the disk). Here is a dump of the first BAM
sector@dots{}

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 12 01 41 80 12 FF F9 17 15 FF FF 1F 15 FF FF 1F
10: 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F
20: 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F
30: 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F
40: 15 FF FF 1F 15 FF FF 1F 11 FC FF 07 13 FF FF 07
50: 13 FF FF 07 13 FF FF 07 13 FF FF 07 13 FF FF 07
60: 13 FF FF 07 12 FF FF 03 12 FF FF 03 12 FF FF 03
70: 12 FF FF 03 12 FF FF 03 12 FF FF 03 11 FF FF 01
80: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01
90: A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0
A0: A0 A0 30 30 A0 32 41 A0 A0 A0 A0 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 15 15 15
E0: 15 15 15 15 15 15 15 15 15 15 15 15 15 15 00 13
F0: 13 13 13 13 13 12 12 12 12 12 12 11 11 11 11 11
@end example

@multitable @columnfractions .5 .5
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of the first directory sector (should be set to 18/1 but it doesn't matter, and don't trust what is there, always go to 18/1 for first directory entry)
@item $02
@tab Disk DOS version type (see note below) $41 ('A') = 1541
@item $03
@tab Double-sided flag $00 - Single sided disk $80 - Double sided disk
@item $04-8F
@tab BAM entries for each track, in groups of four bytes per track, starting on track 1.
@item $90-$9F
@tab Disk Name (padded with $A0)
@item $A0-$A1
@tab Filled with $A0
@item $A2-$A3
@tab Disk ID
@item $A4
@tab Usually $A0
@item $A5-$A6
@tab DOS type, usually "2A"
@item $A7-$AA
@tab Filled with $A0
@item $AB-$DC
@tab Not used ($00's)
@item $DD-$FF
@tab Free sector count for tracks 36-70 (1 byte/track).
@end multitable

The "free sector" entries for tracks 36-70 are likely included
here in the first BAM sector due to some memory restrictions in
the 1571 drive. There is only enough memory available for one
BAM sector, but in order to generate the "blocks free" value at
the end of a directory listing, the drive needs to know the
extra track "free sector" values. It does make working with the
BAM a little more difficult, though.

These are the values that would normally be with the 4-byte BAM
entry, but the rest of the entry is contained on 53/0.

Note: If the DOS version byte is set to anything other than $41
or $00, then we have what is called "soft write protection". Any
attempt to write to the disk will return the "DOS Version" error
code 73. The 1571 is simply telling you that it thinks the disk
format version is incorrect.

The BAM entries require some explanation. Take the first entry
at bytes $04-$07 ($12 $FF $F9 $17). The first byte ($12) is the
number of free sectors on that track. Since we are looking at the
track 1 entry, this means it has 18 (decimal) free sectors.

The next three bytes represent the bitmap of which sectors are
used/free. Since it is 3 bytes (8 bits/byte) we have 24 bits of
storage. Remember that at most, each track only has 21 sectors,
so there are a few unused bits. These entries must be viewed in
binary to make any sense. We will use the first entry (track 1)
at bytes 04-07:

@example
 FF=11111111, F9=11111001, 17=00010111
@end example

In order to make any sense from the binary notation, flip the
bits around.

@example
            111111 11112222
 01234567 89012345 67890123
 --------------------------
 11111111 10011111 11101000
 ^                     ^
 sector 0           sector 20
@end example

Since we are on the first track, we have 21 sectors, and only
use up to the bit 20 position. If a bit is on (1), the sector
is free. Therefore, track 1 has sectors 9,10 and 19 used, all
the rest are free.

In order to complete the BAM, we must check 53/0.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF
10: FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF
20: 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F
30: FF FF 1F 00 00 00 FF FF 07 FF FF 07 FF FF 07 FF
40: FF 07 FF FF 07 FF FF 07 FF FF 03 FF FF 03 FF FF
50: 03 FF FF 03 FF FF 03 FF FF 03 FF FF 01 FF FF 01
60: FF FF 01 FF FF 01 FF FF 01 00 00 00 00 00 00 00
70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

Each track from 36-70 has 3 byte entries, starting at
address $00.

@example
Byte: $00-$02: $FF $FF $1F - BAM map for track 36
      $03-$05: $FF $FF $1F - BAM map for track 37
      @dots{}
      $33-$35: $00 $00 $00 - BAM map for track 53
      @dots{}
      $66-$68: $FF $FF $01 - BAM map for track 70
      $69-$FF:             - Not used
@end example

You can break down the entries for tracks 36-70 the same way as
track 1, just combine the free sector bytes from 18/0 and the BAM
usage from 53 to get the full 4-byte entry.

Just like a D64, you can attach error bytes to the file, for
sector error information. This block is 1366 bytes long, 1 byte
for each of the 1366 sectors in the image. With the error bytes,
the file size is 351062 bytes.

@node D81, D80, D71, File formats
@section The D81 disk image format

@c FIXME: the D81 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

Like D64 and D71, this is a byte for byte copy of a physical 1581
disk. It consists of 80 tracks, 40 sectors each (0 to 39) for a
size of 819200 bytes, or 3200 sectors. If the error byte block is
attached, this makes the file size 822400 bytes.

There are three sectors on the directory track used for disk
internals (header and BAM), leaving 37 sectors for filename
entries, thus allowing for 296 files (37 * 8) to be stored at the
root level of the disk.

The actual physical layout on the disk is quite different from what
the user sees, but this is unimportant to the scope of this section.
One important difference from the D64 and D71 is all the sector
interleaves are now 1 for both files and directory storage (rather
than 3 for directory and 10 for file on a D64/D71). This is due to
the built-in buffering in the 1581. When reading a sector, the
whole track will be buffered in memory, and any sectors being
modified will be done in memory. Once it has to be written, the
whole track will be written out in one step.

The track range and offsets into the D81 files are as follows:

@multitable @columnfractions .25 .25 .25 .25
@item @b{Track}
@tab @b{#Sect}
@tab @b{#SectorsIn}
@tab @b{D81 Offset}
@item 1
@tab 40
@tab 0
@tab $00000
@item 2
@tab 40
@tab 40
@tab $02800
@item 3
@tab 40
@tab 80
@tab $05000
@item 4
@tab 40
@tab 120
@tab $07800
@item 5
@tab 40
@tab 160
@tab $0A000
@item 6
@tab 40
@tab 200
@tab $0C800
@item 7
@tab 40
@tab 240
@tab $0F000
@item 8
@tab 40
@tab 280
@tab $11800
@item 9
@tab 40
@tab 320
@tab $14000
@item 10
@tab 40
@tab 360
@tab $16800
@item 11
@tab 40
@tab 400
@tab $19000
@item 12
@tab 40
@tab 440
@tab $1B800
@item 13
@tab 40
@tab 480
@tab $1E000
@item 14
@tab 40
@tab 520
@tab $20800
@item 15
@tab 40
@tab 560
@tab $23000
@item 16
@tab 40
@tab 600
@tab $25800
@item 17
@tab 40
@tab 640
@tab $28000
@item 18
@tab 40
@tab 680
@tab $2A800
@item 19
@tab 40
@tab 720
@tab $2D000
@item 20
@tab 40
@tab 760
@tab $2F800
@item 21
@tab 40
@tab 800
@tab $32000
@item 22
@tab 40
@tab 840
@tab $34800
@item 23
@tab 40
@tab 880
@tab $37000
@item 24
@tab 40
@tab 920
@tab $39800
@item 25
@tab 40
@tab 960
@tab $3C000
@item 26
@tab 40
@tab 1000
@tab $3E800
@item 27
@tab 40
@tab 1040
@tab $41000
@item 28
@tab 40
@tab 1080
@tab $43800
@item 29
@tab 40
@tab 1120
@tab $46000
@item 30
@tab 40
@tab 1160
@tab $48800
@item 31
@tab 40
@tab 1200
@tab $4B000
@item 32
@tab 40
@tab 1240
@tab $4D800
@item 33
@tab 40
@tab 1280
@tab $50000
@item 34
@tab 40
@tab 1320
@tab $52800
@item 35
@tab 40
@tab 1360
@tab $55000
@item 36
@tab 40
@tab 1400
@tab $57800
@item 37
@tab 40
@tab 1440
@tab $5A000
@item 38
@tab 40
@tab 1480
@tab $5C800
@item 39
@tab 40
@tab 1520
@tab $5F000
@item 40
@tab 40
@tab 1560
@tab $61800
@item 41
@tab 40
@tab 1600
@tab $64000
@item 42
@tab 40
@tab 1640
@tab $66800
@item 43
@tab 40
@tab 1680
@tab $69000
@item 44
@tab 40
@tab 1720
@tab $6B800
@item 45
@tab 40
@tab 1760
@tab $6E000
@item 46
@tab 40
@tab 1800
@tab $70800
@item 47
@tab 40
@tab 1840
@tab $73000
@item 48
@tab 40
@tab 1880
@tab $75800
@item 49
@tab 40
@tab 1920
@tab $78000
@item 50
@tab 40
@tab 1960
@tab $7A800
@item 51
@tab 40
@tab 2000
@tab $7D000
@item 52
@tab 40
@tab 2040
@tab $7F800
@item 53
@tab 40
@tab 2080
@tab $82000
@item 54
@tab 40
@tab 2120
@tab $84800
@item 55
@tab 40
@tab 2160
@tab $87000
@item 56
@tab 40
@tab 2200
@tab $89800
@item 57
@tab 40
@tab 2240
@tab $8C000
@item 58
@tab 40
@tab 2280
@tab $8E800
@item 59
@tab 40
@tab 2320
@tab $91000
@item 60
@tab 40
@tab 2360
@tab $93800
@item 61
@tab 40
@tab 2400
@tab $96000
@item 62
@tab 40
@tab 2440
@tab $98800
@item 63
@tab 40
@tab 2480
@tab $9B000
@item 64
@tab 40
@tab 2520
@tab $9D800
@item 65
@tab 40
@tab 2560
@tab $A0000
@item 66
@tab 40
@tab 2600
@tab $A2800
@item 67
@tab 40
@tab 2640
@tab $A5000
@item 68
@tab 40
@tab 2680
@tab $A7800
@item 69
@tab 40
@tab 2720
@tab $AA000
@item 70
@tab 40
@tab 2760
@tab $AC800
@item 71
@tab 40
@tab 2800
@tab $AF000
@item 72
@tab 40
@tab 2840
@tab $B1800
@item 73
@tab 40
@tab 2880
@tab $B4000
@item 74
@tab 40
@tab 2920
@tab $B6800
@item 75
@tab 40
@tab 2960
@tab $B9000
@item 76
@tab 40
@tab 3000
@tab $BB800
@item 77
@tab 40
@tab 3040
@tab $BE000
@item 78
@tab 40
@tab 3080
@tab $C0800
@item 79
@tab 40
@tab 3120
@tab $C3000
@item 80
@tab 40
@tab 3160
@tab $C5800
@end multitable

The header sector is stored at 40/0, and contains the disk name,
ID and DOS version bytes, but the BAM is no longer contained here
(like the D64).

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 28 03 44 00 31 35 38 31 20 55 54 49 4C 49 54 59
10: 20 56 30 31 A0 A0 47 42 A0 33 44 A0 A0 00 00 00
20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of the first directory sector (should be set to 40/3 but it doesn't matter, and don't trust what is there, always go to 40/3 for first directory entry)
@item $02
@tab Disk DOS version type (see note below) $44 ('D')=1581
@item $03
@tab $00
@item $04-$13
@tab 16 character Disk Name (padded with $A0)
@item $14-$15
@tab $A0
@item $16-$17
@tab Disk ID
@item $18
@tab $A0
@item $19
@tab DOS Version ("3")
@item $1A
@tab Disk version ("D")
@item $1B-$1C
@tab $A0
@item $1D-$FF
@tab Unused (usually $00)
@end multitable

The following might be set if the disk is a GEOS format (this
info is based on the D64 layout, and might not prove to be true)

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $AB-$AC
@tab Border sector (GEOS only, else set to $00)
@item $AD-$BC
@tab GEOS ID string ("geos FORMAT V1.x" GEOS only, else $00)
@item $BD-$FF
@tab Unused (usually $00)
@end multitable

Note: If the DOS version byte is changed to anything other than
a $44 (or $00), then we have what is called "soft write
protection". Any attempt to write to the disk will return the
"DOS Version" error code 73. The drive is simply telling you
that it thinks the disk format version is incompatible.

The directory track should be contained totally on track 40.
Sectors 3-39 contain the entries and sector 1 and 2 contain the
BAM (Block Availability Map). Sector 0 holds the disk name and
ID. The first directory sector is always 40/3, even though the
t/s pointer at 40/0 (first two bytes) might point somewhere
else. It goes linearly up the sector count, 3-4-5-6-etc. Each
sector holds up to eight entries.

The first two bytes of the sector ($28/$04) indicate the location
of the next track/sector of the directory (40/4). If the track is
set to $00, then it is the last sector of the directory. It is
possible, however unlikely, that the directory may *not* be
competely on track 40. Just follow the chain anyhow.

When the directory is done (track=$00), the sector should contain
an $FF, meaning the whole sector is allocated. Theactual value
doesn't matter as all the entries will be returned anyways. Each
directory sector has the following layout:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 28 04 81 2B 00 53 43 52 45 45 4E 20 20 33 A0 A0
10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 02 00
20: 00 00 81 2B 01 53 43 52 45 45 4E 20 20 34 A0 A0
30: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 03 00
40: 00 00 81 2B 02 53 43 52 45 45 4E 20 20 35 A0 A0
50: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 07 00
60: 00 00 81 2B 08 53 43 52 45 45 4E 20 20 36 A0 A0
70: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 08 00
80: 00 00 81 2B 14 53 43 52 45 45 4E 20 20 37 A0 A0
90: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 07 00
A0: 00 00 81 24 00 53 43 52 45 45 4E 20 20 38 A0 A0
B0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0B 00
C0: 00 00 82 24 04 46 49 4C 45 34 32 39 33 36 39 30
D0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 07 00
E0: 00 00 82 24 06 46 49 4C 45 32 35 37 38 38 31 35
F0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 05 00
@end example


@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First directory entry
@item $20-$3F
@tab Second dir entry
@item $40-$5F
@tab Third dir entry
@item $60-$7F
@tab Fourth dir entry
@item $80-$9F
@tab Fifth dir entry
@item $A0-$BF
@tab Sixth dir entry
@item $C0-$DF
@tab Seventh dir entry
@item $E0-$FF
@tab Eighth dir entry
@end multitable

This is a breakdown of a standard directory entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next directory sector
@item $02
@tab File type
@item $03-$04
@tab Track/sector location of first sector of file or partition
@item $05-$14
@tab 16 character filename (in PETASCII, padded with $A0)
@item $15-$16
@tab Track/Sector location of first SUPER SIDE SECTOR block (REL file only)
@item $17
@tab REL file record length (REL file only)
@item $18-$1B
@tab Unused (except with GEOS disks)
@item $1C-$1D
@tab (Used during an SAVE or OPEN, holds the new t/s link)
@item $1E-$1F
@tab File or partition size in sectors, low/high byte order ($1E+$1F*256). The approx. file size in bytes is <= #sectors * 254
@end multitable

The file type field is used as follows:

@multitable @columnfractions .2 .8
@item @b{Bits}
@tab @b{Description}
@item 0-3
@tab The actual file type
@item 4
@tab Unused
@item 5
@tab Used only during SAVE-@@ replacement
@item 6
@tab Locked flag (Set produces ">" locked files)
@item 7
@tab Closed flag (Not set produces "*", or "splat" files)
@end multitable

The actual file type can be one of the following:

@multitable @columnfractions .2 .2 .6
@item @b{Binary}
@tab @b{Decimal}
@tab @b{File type}
@item 0000
@tab 0
@tab DEL
@item 0001
@tab 1
@tab SEQ
@item 0010
@tab 2
@tab PRG
@item 0011
@tab 3
@tab USR
@item 0100
@tab 4
@tab REL
@item 0101
@tab 5
@tab CBM (partition or sub-directory)
@end multitable

Values 6-15 are illegal, but if used will produce very strange results.

@c @node FIXME
@subsection Non-Standard & Long Directories

Most Commdore floppy disk drives use a single dedicated directory
track where all filenames are stored. This limits the number of
files stored on a disk based on the number of sectors on the
directory track. There are some disk images that contain more
files than would normally be allowed. This requires extending the
directory off the default directory track by changing the last
directory sector pointer to a new track, allocating the new
sectors in the BAM, and manually placing (or moving existing)
file entries there. The directory of an extended disk can be read
and the files that reside there can be loaded without problems on
a real drive. However, this is still a very dangerous practice as
writing to the extended portion of the directory will cause
directory corruption in the non-extended part. Many of the floppy
drives core ROM routines ignore the track value that the
directory is on and assume the default directory track for
operations.

@c @node FIXME
@subsection BAM layout

The BAM is located on 40/1 (for side 0, tracks 1-40) and 40/2
(for side 1, tracks 41-80). Each entry takes up six bytes, one
for the "free sector" count and five for the allocation bitmap.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 28 02 44 BB 47 42 C0 00 00 00 00 00 00 00 00 00
10: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
20: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
30: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
40: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
50: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
60: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
70: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
80: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
90: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
A0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
B0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
C0: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
D0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
E0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
F0: FF FF FF FF 28 FF FF FF FF FF 24 F0 FF 2D FF FE
@end example

@example
Bytes:
$00-$01: Track/sector of next bam sector (40/2)
    $02: Version # ('D')
    $03: One's complement of version# ($BB)
$04-$05: Disk ID bytes (same as 40/0 Disk ID)
    $06: I/O byte
         bit 7 set - Verify on
         bit 7 clear - Verify off
         bit 6 set - Check header CRC
         bit 6 clear - Don't check header CRC
    $07: Auto-boot-loader flag
$08-$0F: Reserved for future (set to $00)
$10-$15: BAM entry for track 1 (track 41, side 1)
$16-$1B: BAM entry for track 2 (track 42, side 1)
         @dots{}
$46-$4B: BAM entry for track 10 (track 50, side 1)
         @dots{}
$82-$87: BAM entry for track 20 (track 60, side 1)
         @dots{}
$BE-$C3: BAM entry for track 30 (track 70, side 1)
         @dots{}
$FA-$FF: BAM entry for track 40 (track 80, side 1)
@end example

The BAM entries require some explanation, so lets look at the
track 40 entry at bytes $FA-FF ($24 $F0 $FF $2D $FF $FE). The
first byte ($24, or 36 decimal) is the number of free sectors
on that track. The next five bytes represent the bitmap of
which sectors are used/free. Since it is five bytes
(8 bits/byte) we have 40 bits of storage. Since this format
has 40 sectors/track, the whole five bytes are used.

@example
 F0: .. .. .. .. .. .. .. .. .. .. 24 F0 FF 2D FF FE
@end example

The last five bytes of any BAM entry must be viewed in binary
to make any sense. We will once again use track 40 as our
reference:

@example
 F0=11110000, FF=11111111, 2D=00101101, FF=11111111, FE=11111110
@end example

In order to make any sense from the binary notation, flip the
bits around.

@example
                   111111 11112222 22222233 33333333
 Sector 01234567 89012345 67890123 45678901 23456789
        -------------------------- -------- --------
        00001111 11111111 10110100 11111111 01111111
@end example

Note that if a bit is on (1), the sector is free. Therefore,
track 40 has sectors 0-3, 17, 20, 22, 23 and 32 used, all the
rest are free.

The second BAM (for side 1) contains the entries for tracks
41-80.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 00 FF 44 BB 47 42 C0 00 00 00 00 00 00 00 00 00
10: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
20: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
30: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
40: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
50: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
60: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
70: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
80: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
90: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
A0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
B0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
C0: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
D0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
E0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF
F0: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF
@end example

It is laid out exactly as the side 0 BAM except for one
difference. The track/sector reference for the next sector
should be set to $00/$FF, indicating there is no next sector.

@c @node FIXME
@subsection REL files The REL filetype requires some extra explaining.
It was designed to make access to data *anywhere* on the disk
very fast. Take a look at this directory entry@dots{}

@example
 00: 00 FF 84 27 00 41 44 44 49 54 49 4F 4E 41 4C 20
 10: 49 4E 46 4F A0 27 02 FE 00 00 00 00 00 00 D2 0B
@end example

The third byte ($84) indicates this entry is a REL file and
that the three normally empty entries at offset $15, $16 and
$17 are now used as they are explained above. It's the
track/sector chain that this entry points to, called the SUPER
SIDE SECTOR, which is of interest here (in this case, 39/2).
The SUPER SIDE SECTOR is very different from the D64 format. If
you check the D64 entry for a REL file and do the calculations,
you will find that the maximum file size of the REL file is 720
data sectors. With the new SUPER SIDE SECTOR, you can now have
126 groups of these SIDE SECTORS chains, allowing for file
sizes up to (theoretically) 90720 sectors, or about 22.15
Megabytes.

Here is a dump of the beginning of the SUPER SIDE SECTOR@dots{}

@example
 00: 27 01 FE 27 01 15 09 03 0F 38 16 4A 1C 00 00 00
 10: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@example
Bytes:
$00-$01: Track/sector of first side sector in group 0
    $02: Always $FE
$03-$04: Track/sector of first side sector in group 0 (again)
         @dots{}
$FD-$FE: Track/sector of first side sector in group 125
    $FF: Unused (likely $00)
@end example

The side sector layout is the same as the D64/1571.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 12 0A 00 FE 15 09 12 0A 0F 0B 0C 0C 09 0D 06 0E
10: 15 07 15 08 15 0A 15 0B 15 0C 15 0D 15 0E 15 0F
20: 15 10 15 11 15 12 15 13 15 14 15 15 15 16 15 17
30: 15 18 15 19 15 1A 15 1B 15 1C 15 1D 15 1E 15 1F
40: 15 20 15 21 15 22 15 23 15 24 15 25 15 26 15 27
50: 14 00 14 01 14 02 14 03 14 04 14 05 14 06 14 07
60: 14 08 14 09 14 0A 14 0B 14 0C 14 0D 14 0E 14 0F
70: 14 10 14 11 14 12 14 13 14 14 14 15 14 16 14 17
80: 14 18 14 19 14 1A 14 1B 14 1C 14 1D 14 1E 14 1F
90: 14 20 14 21 14 22 14 23 14 24 14 25 14 26 14 27
A0: 13 00 13 01 13 02 13 03 13 04 13 05 13 06 13 07
B0: 13 08 13 09 13 0A 13 0B 13 0C 13 0D 13 0E 13 0F
C0: 13 10 13 11 13 12 13 13 13 14 13 15 13 16 13 17
D0: 13 18 13 19 13 1A 13 1B 13 1C 13 1D 13 1E 13 1F
E0: 13 20 13 21 13 22 13 23 13 24 13 25 13 26 13 27
F0: 12 00 12 01 12 02 12 03 12 04 12 05 12 06 12 07
@end example

@example
Bytes:
    $00: Track location of next side-sector ($00 if last sector)
    $01: Sector location of next side-sector
    $02: Side-sector block number (first sector is $00, the next is
         $01, then $02, etc)
    $03: REL file RECORD size (from directory entry)
$04-$0F: Track/sector locations of the six other side-sectors. Note
         the first entry is this very sector we have listed here.
         The next is the next t/s listed at the beginning of the
         sector. All of this information must be correct. If one of
         these chains is $00/$00, then we have no more side sectors.
         Also, all of these (up to six) side sectors must have the
         same values in this range.
$10-$FF: T/S chains of *each* sector of the data portion. When we
         get a $00/$00, we are at the end of the file.
@end example

@c @node FIXME
@subsection 1581 Partitions and Sub-directories

At the beginning of this section it was stated that the 1581 can
hold 296 entries "at the root level". The 1581 also has the
ability to partition areas of the disk. Under the right
conditions these can become sub-directories, acting as a small
diskette, complete with its own directory and BAM. When you are
inside of a sub-directory, no other files except those in that
directory are visible, or can be affected.

To the 1581, this file will show up as a "CBM" filetype in a
directory. All this does is tell the disk that a file, starting
at X/Y track/sector and Z sectors large exists. Doing a validate
will not harm these files as they have a directory entry, and
are fully allocated in the BAM.

There are two main uses for partitions. One is to simply
allocate a section of the disk to be used for direct-access
reads/writes, and lock it away from being overwritten after a
VALIDATE. The second is as a sub-directory, basically a small
"disk within a disk".

In order to use a partition as a sub-directory, it must adhere
to the following four rules:

@example
 1. If must start on sector 0
 2. It's size must be in multiples of 40 sectors
 3. It must be a minimum of 120 sectors long (3 tracks)
 4. If must not start on or cross track 40, which limits the
    biggest directory to 1600 sectors (tracks 1-39).
@end example

This is a dump of a sub-directory entry:

@example
 00: 00 FF 85 29 00 50 41 52 54 49 54 49 4F 4E 20 31
 10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 40 06
@end example

It is a partition starting on track 41/0, extends for 1600
sectors, and has been formatted as a sub-directory. Note that
when a partition is created, the area being allocated is not
touched in any way. If you want it set up as a sub-directory,
you must issue the FORMAT command to the 1581 to create the
central directory and BAM. Also note that from the directory
entry you can't tell whether it is a sub-directory or not, just
that it fits the sub-directory parameters.

The BAM track for the sub-directory exists on the first track of
the partition, and has the same layout as the disk BAM on track
40. The biggest difference is the "disk name" is what what given
when the partition was formatted rather than what the actual
disk name is. Also, except for the free sectors in the partition
area, all other sectors in the BAM will be allocated.

If the partition size doesn't match the above rules for a
sub-directory, it will simply exist as a "protected" area of the
disk, and can't be used as a sub-directory. Either way, it still
shows up as a "CBM" type in a directory listing. Below is a dump
of a 10-sector partition starting on track 5/1, which does not
qualify as a sub-directory@dots{}

@example
 00: 00 00 85 05 01 53 4D 41 4C 4C 50 41 52 54 20 32
 10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0A 00
@end example

The master BAM shows the entry for this partition on track 5@dots{}

@example
 00: 28 02 44 BB 43 44 C0 00 00 00 00 00 00 00 00 00
 10: 23 C1 FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF
 20: FF FF 28 FF FF FF FF FF 1E 01 F8 FF FF FF 28 FF
                             ^^^^^^^^^^^^^^^^^
@end example

The breakdown of the BAM shows the allocation for this track,
with sectors 1-10 allocated, as it should be.

@example
 10000000 00011111 11111111 11111111 11111111
 ^          ^          ^         ^          ^
 0          10         20        30         39
@end example

Partitions and sub-directories share one very important trait.
When created, the sub-directory entry simply has the starting
track/sector and the size of the partition in sectors.
Partitions are created linearly, meaning if one starts on 30/1
and is of size 15 sectors, then the sector range from 1 through
15 on track 30 will be allocated. If a partition size crosses
a track boundary, the allocation will continue on the next
track starting on sector 0, and going up.

The section allocated will *not* have a track/sector chain like
a file would, but rather is dependant on the directory entry to
keep it from being overwritten. You can store whatever you want
to in the allocated area.

@c @node FIXME
@subsection AUTO-BOOT LOADER

If byte $07 in the BAM is set, then when the drive is reset
(and other circumstances) it will look for a USR file called
"COPYRIGHT CBM 86". This file will then be loaded into the
drive RAM and executed.

The format for this auto-loader file is fairly basic. It
starts with a two-byte load address, a size byte, program data,
and a checksum at the end.

@example
Bytes:
       $00-$01: Load address, low/high format
           $02: Size of program (SZ) (smaller than 256 bytes)
$03-($03+SZ-1): Program data
        $03+SZ: Checksum byte
@end example

@node D80, D82, D81, File formats
@section The D80 disk image format

@c FIXME: the D80 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

This is a sector-for-sector copy of an 8050 floppy disk. The
file size for an 8050 image is 533248 bytes. It is comprised
of 256-byte sectors arranged across 77 tracks, with a
varying number of sectors per track for a total of 2083
sectors. Track counting starts at 1 (not 0) and sector
counting starts at 0 (not 1), therefore a track with 29
sectors will go from 0 to 28.

The original media (a 5.25" disk) has the tracks laid out in
circles, with track 1 on the very outside of the disk
(closest to the sides) to track 77 being on the inside of
the disk (closest to the inner hub ring). Commodore, in
their infinite wisdom, varied the number of sectors per
track and data densities across the disk to optimize
available storage, resulting in the chart below. It shows
the sectors/track for a D80. Since the outside diameter of a
circle is the largest (versus closer to the center), the
outside tracks have the largest amount of storage.

@multitable @columnfractions .33 .33 .33
@item @b{Track Range}
@tab @b{Sectors/track}
@tab @b{# Sectors}
@item 1-39
@tab 29
@tab 1131
@item 40-53
@tab 27
@tab 378
@item 54-64
@tab 25
@tab 275
@item 65-77
@tab 23
@tab 299
@end multitable

@multitable @columnfractions .25 .25 .25 .25
@item @b{Track}
@tab @b{#Sect}
@tab @b{#SectorsIn}
@tab @b{D8x Offset}
@item 1
@tab 29
@tab 0
@tab $00000
@item 2
@tab 29
@tab 29
@tab $01D00
@item 3
@tab 29
@tab 58
@tab $03A00
@item 4
@tab 29
@tab 87
@tab $05700
@item 5
@tab 29
@tab 116
@tab $07400
@item 6
@tab 29
@tab 145
@tab $09100
@item 7
@tab 29
@tab 174
@tab $0AE00
@item 8
@tab 29
@tab 203
@tab $0CB00
@item 9
@tab 29
@tab 232
@tab $0E800
@item 10
@tab 29
@tab 261
@tab $10500
@item 11
@tab 29
@tab 290
@tab $12200
@item 12
@tab 29
@tab 319
@tab $13F00
@item 13
@tab 29
@tab 348
@tab $15C00
@item 14
@tab 29
@tab 377
@tab $17900
@item 15
@tab 29
@tab 406
@tab $19600
@item 16
@tab 29
@tab 435
@tab $1B300
@item 17
@tab 29
@tab 464
@tab $1D000
@item 18
@tab 29
@tab 493
@tab $1ED00
@item 19
@tab 29
@tab 522
@tab $20A00
@item 20
@tab 29
@tab 551
@tab $22700
@item 21
@tab 29
@tab 580
@tab $24400
@item 22
@tab 29
@tab 609
@tab $26100
@item 23
@tab 29
@tab 638
@tab $27E00
@item 24
@tab 29
@tab 667
@tab $29B00
@item 25
@tab 29
@tab 696
@tab $2B800
@item 26
@tab 29
@tab 725
@tab $2D500
@item 27
@tab 29
@tab 754
@tab $2F200
@item 28
@tab 29
@tab 783
@tab $30F00
@item 29
@tab 29
@tab 812
@tab $32C00
@item 30
@tab 29
@tab 841
@tab $34900
@item 31
@tab 29
@tab 870
@tab $36600
@item 32
@tab 29
@tab 899
@tab $38300
@item 33
@tab 29
@tab 928
@tab $3A000
@item 34
@tab 29
@tab 957
@tab $3BD00
@item 35
@tab 29
@tab 986
@tab $3DA00
@item 36
@tab 29
@tab 1015
@tab $3F700
@item 37
@tab 29
@tab 1044
@tab $41400
@item 38
@tab 29
@tab 1073
@tab $43100
@item 39
@tab 29
@tab 1102
@tab $44E00
@item 40
@tab 27
@tab 1131
@tab $46B00
@item 41
@tab 27
@tab 1158
@tab $48600
@item 42
@tab 27
@tab 1185
@tab $4A100
@item 43
@tab 27
@tab 1212
@tab $4BC00
@item 44
@tab 27
@tab 1239
@tab $4D700
@item 45
@tab 27
@tab 1266
@tab $4F200
@item 46
@tab 27
@tab 1293
@tab $50D00
@item 47
@tab 27
@tab 1320
@tab $52800
@item 48
@tab 27
@tab 1347
@tab $54300
@item 49
@tab 27
@tab 1374
@tab $55E00
@item 50
@tab 27
@tab 1401
@tab $57900
@item 51
@tab 27
@tab 1428
@tab $59400
@item 52
@tab 27
@tab 1455
@tab $5AF00
@item 53
@tab 27
@tab 1482
@tab $5CA00
@item 54
@tab 25
@tab 1509
@tab $5E500
@item 55
@tab 25
@tab 1534
@tab $5FE00
@item 56
@tab 25
@tab 1559
@tab $61700
@item 57
@tab 25
@tab 1584
@tab $63000
@item 58
@tab 25
@tab 1609
@tab $64900
@item 59
@tab 25
@tab 1634
@tab $66200
@item 60
@tab 25
@tab 1659
@tab $67B00
@item 61
@tab 25
@tab 1684
@tab $69400
@item 62
@tab 25
@tab 1709
@tab $6AD00
@item 63
@tab 25
@tab 1734
@tab $6C600
@item 64
@tab 25
@tab 1759
@tab $6DF00
@item 65
@tab 23
@tab 1784
@tab $6F800
@item 66
@tab 23
@tab 1807
@tab $70F00
@item 67
@tab 23
@tab 1830
@tab $72600
@item 68
@tab 23
@tab 1853
@tab $73D00
@item 69
@tab 23
@tab 1876
@tab $75400
@item 70
@tab 23
@tab 1899
@tab $76B00
@item 71
@tab 23
@tab 1922
@tab $78200
@item 72
@tab 23
@tab 1945
@tab $79900
@item 73
@tab 23
@tab 1968
@tab $7B000
@item 74
@tab 23
@tab 1991
@tab $7C700
@item 75
@tab 23
@tab 2014
@tab $7DE00
@item 76
@tab 23
@tab 2037
@tab $7F500
@item 77
@tab 23
@tab 2060
@tab $80C00
@end multitable

The BAM (Block Availability Map) is on track 38. The D80 is only
77 tracks and so the BAM is contained on 38/0 and 38/3. The BAM
interleave is 3.

The directory is on track 39, with 39/0 contains the header
(DOS type, disk name, disk ID's) and sectors 1-28 contain the
directory entries. Both files and the directory use an
interleave of 1. Since the directory is only 28 sectors large
(29 less one for the header), and each sector can contain only
8 entries (32 bytes per entry), the maximum number of directory
entries is 28 * 8 = 224. The first directory sector is always
39/1. It then follows a chain structure using a sector
interleave of 1 making the links go 39/1, 39/2, 39/3 etc.

When reading a disk, you start with 39/0 (disk label/ID) which
points to 38/0 (BAM0), 38/3 (BAM1), and finally to 39/1 (first
dir entry sector). When writing a file to a blank disk, it will
start at 38/1 because 38/0 is already allocated.

Below is a dump of the header sector 39/0:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 00 43 00 00 00 73 61 6D 70 6C 65 20 64 38 30
10: A0 A0 A0 A0 A0 A0 A0 A0 65 72 A0 32 43 A0 A0 A0
20: A0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@dots{}
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to first BAM sector (38/0)
@item $02
@tab $43 'C' is for DOS format version
@item $03
@tab Reserved
@item $04-$05
@tab Unused
@item $06-$16
@tab Disk name, padded with 0xA0 ("sample d80")
@item $17
@tab 0xA0
@item $18-$19
@tab Disk ID bytes "er"
@item $1A
@tab 0xA0
@item $1B-$1C
@tab DOS version bytes "2C"
@item $1D-$20
@tab 0xA0
@item $21-$FF
@tab Unused
@end multitable

Below is a dump of the first directory sector, 39/1

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 27 02 82 26 01 54 45 53 54 A0 A0 A0 A0 A0 A0 A0
10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
20: 00 00 82 26 02 54 45 53 54 32 A0 A0 A0 A0 A0 A0
30: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
40: 00 00 82 26 04 54 45 53 54 33 A0 A0 A0 A0 A0 A0
50: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 05 00
60: 00 00 82 26 0B 54 45 53 54 34 A0 A0 A0 A0 A0 A0
70: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 09 00
80: 00 00 82 26 14 54 45 53 54 35 A0 A0 A0 A0 A0 A0
90: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0C 00
A0: 00 00 82 28 00 54 45 53 54 36 A0 A0 A0 A0 A0 A0
B0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
C0: 00 00 82 28 01 54 45 53 54 37 A0 A0 A0 A0 A0 A0
D0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
E0: 00 00 82 28 02 54 45 53 54 38 A0 A0 A0 A0 A0 A0
F0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
@end example

The first two bytes of the directory sector ($27/$02) indicate
the location of the next track/sector of the directory (39/2).
If the track is set to $00, then it is the last sector of the
directory.

When the directory is done, the track value will be $00. The sector
link should contain a value of $FF, meaning the whole sector is
allocated, but the actual value doesn't matter. The drive will
return all the available entries anyways. This is a breakdown of a
standard directory sector:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First directory entry
@item $20-$3F
@tab Second dir entry
@item $40-$5F
@tab Third dir entry
@item $60-$7F
@tab Fourth dir entry
@item $80-$9F
@tab Fifth dir entry
@item $A0-$BF
@tab Sixth dir entry
@item $C0-$DF
@tab Seventh dir entry
@item $E0-$FF
@tab Eighth dir entry
@end multitable

This is a breakdown of a standard directory entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next directory sector ($00 $00 if not the first entry in the sector)
@item $02
@tab File type
@item $03-$04
@tab Track/sector location of first sector of file
@item $05-$14
@tab 16 character filename (in PETASCII, padded with $A0)
@item $15-$16
@tab Track/Sector location of first side-sector block (REL file only)
@item $17
@tab REL file record length (REL file only, max. value 254)
@item $18-$1D
@tab Unused
@item $1E-$1F
@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254
@end multitable

The file type field is used as follows:

@multitable @columnfractions .2 .8
@item @b{Bits}
@tab @b{Description}
@item 0-3
@tab The actual file type
@item 4
@tab Unused
@item 5
@tab Used only during SAVE-@@ replacement
@item 6
@tab Locked flag (Set produces ">" locked files)
@item 7
@tab Closed flag (Not set produces "*", or "splat" files)
@end multitable

The actual file type can be one of the following:

@multitable @columnfractions .2 .2 .6
@item @b{Binary}
@tab @b{Decimal}
@tab @b{File type}
@item 0000
@tab 0
@tab DEL
@item 0001
@tab 1
@tab SEQ
@item 0010
@tab 2
@tab PRG
@item 0011
@tab 3
@tab USR
@item 0100
@tab 4
@tab REL
@end multitable

Values 5-15 are illegal, but if used will produce very strange results.

@c @node FIXME
@subsection Non-Standard & Long Directories

Most Commdore floppy disk drives use a single dedicated
directory track where all filenames are stored. This limits the
number of files stored on a disk based on the number of sectors
on the directory track. There are some disk images that contain
more files than would normally be allowed. This requires
extending the directory off the default directory track by
changing the last directory sector pointer to a new track,
allocating the new sectors in the BAM, and manually placing (or
moving existing) file entries there. The directory of an
extended disk can be read and the files that reside there can
be loaded without problems on a real drive. However, this is
still a very dangerous practice as writing to the extended
portion of the directory will cause directory corruption in the
non-extended part. Many of the floppy drives core ROM routines
ignore the track value that the directory is on and assume the
default directory track for operations.

@c @node FIXME
@subsection BAM layout

The BAM only occupies up to four sectors on track 38, so the
rest of the track is empty and is available for file storage.
Below is a dump of the first BAM block, 38/0. A D80 will only
contain two BAM sectors, 38/0 and 38/3. Each entry takes 5
bytes, 1 for the free count on that track, and 4 for the BAM
bits.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 03 43 00 01 33 1D FF FF FF 1F 1D FF FF FF 1F
10: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
20: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
30: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
40: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
50: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
60: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
70: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
80: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
90: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
A0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
B0: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1B
C0: F6 FF FF 1F 1B FC FF FF 1F 1B FF FF FF 07 1B FF
D0: FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF
E0: FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF
F0: 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to second BAM sector (38/3)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x01=1)
@item $05
@tab Highest+1 track covered by this BAM (0x33=51)
@item $06-$0A
@tab BAM for track 1. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 2
@item @dots{}
@tab @dots{}
@item $FB-$FF
@tab BAM for track 50
@end multitable

Being bit-based, the BAM entries need some explanation. The
first track entry in the above BAM sector is at offset 06,
"1D FF FF FF 1F". The first number is how many blocks are
free on this track ($1D=29) and the remainder is the bit
representation of the usage map for the track. These
entries must be viewed in binary to make any sense. First
convert the values to binary:

@example
 FF=11111111, FF=11111111, FF=11111111, 1F=00011111
@end example

In order to make any sense from the binary notation, flip the
bits around.

@example
            111111 11112222 222222
 01234567 89012345 67890123 456789@dots{}
 -------------------------- ---------
 11111111 11111111 11111111 11111000
 ^                              ^
 sector 0                   sector 28
@end example

Since we are on the first track, we have 29 sectors, and only
use up to the bit 28 position. If a bit is on (1), the sector
is free. Therefore, track 1 is clean, all sectors are free.
Any leftover bits that refer to sectors that don't exist,
like bits 29-31 in the above example, are set to allocated.

Second BAM block 38/3.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 27 01 43 00 33 4E 1B FF FF FF 07 1B FF FF FF 07
10: 1B FF FF FF 07 19 FF FF FF 01 19 FF FF FF 01 19
20: FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF
30: FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF FF
40: FF 01 19 FF FF FF 01 19 FF FF FF 01 17 FF FF 7F
50: 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00
60: 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17
70: FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF
80: FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 00 00 00
90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to second BAM sector (39/1)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x33=51)
@item $05
@tab Highest+1 track covered by this BAM (0x43=78)
@item $06-$0A
@tab BAM for track 51. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 52
@item @dots{}
@tab @dots{}
@item $88-$8C
@tab BAM for track 77
@item $8D-$FF
@tab Not used
@end multitable

@node D82, P00, D80, File formats
@section The D82 disk image format

@c FIXME: the D82 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

This is a sector-for-sector copy of an 8250 floppy disk. The file
size for an 8250 image is 1066496 bytes. It is comprised of
256-byte sectors arranged across 154 tracks, with a varying
number of sectors per track for a total of 4166 sectors. Track
counting starts at 1 (not 0) and sector counting starts at 0
(not 1), therefore a track with 29 sectors will go from 0 to 28.

The original media (a 5.25" disk) has the tracks laid out in
circles, with track 1 on the very outside of the disk (closest
to the sides) to track 77 being on the inside of the disk
(closest to the inner hub ring). Commodore, in their infinite
wisdom, varied the number of sectors per track and data
densities across the disk to optimize available storage,
resulting in the chart below. It shows the sectors/track for a
D82. Since the outside diameter of a circle is the largest
(versus closer to the center), the outside tracks have the
largest amount of storage.


@multitable @columnfractions .33 .33 .33
@item @b{Track Range}
@tab @b{Sectors/track}
@tab @b{# Sectors}
@item 1-39
@tab 29
@tab 1131
@item 40-53
@tab 27
@tab 378
@item 55-64
@tab 25
@tab 275
@item 65-77
@tab 23
@tab 299
@item 78-116
@tab 29
@tab 1131
@item 117-130
@tab 27
@tab 378
@item 131-141
@tab 25
@tab 275
@item 142-154
@tab 23
@tab 299
@end multitable

@multitable @columnfractions .25 .25 .25 .25
@item @b{Track}
@tab @b{#Sect}
@tab @b{#SectorsIn}
@tab @b{D82 Offset}
@item 1
@tab 29
@tab 0
@tab $000000
@item 2
@tab 29
@tab 29
@tab $001D00
@item 3
@tab 29
@tab 58
@tab $003A00
@item 4
@tab 29
@tab 87
@tab $005700
@item 5
@tab 29
@tab 116
@tab $007400
@item 6
@tab 29
@tab 145
@tab $009100
@item 7
@tab 29
@tab 174
@tab $00AE00
@item 8
@tab 29
@tab 203
@tab $00CB00
@item 9
@tab 29
@tab 232
@tab $00E800
@item 10
@tab 29
@tab 261
@tab $010500
@item 11
@tab 29
@tab 290
@tab $012200
@item 12
@tab 29
@tab 319
@tab $013F00
@item 13
@tab 29
@tab 348
@tab $015C00
@item 14
@tab 29
@tab 377
@tab $017900
@item 15
@tab 29
@tab 406
@tab $019600
@item 16
@tab 29
@tab 435
@tab $01B300
@item 17
@tab 29
@tab 464
@tab $01D000
@item 18
@tab 29
@tab 493
@tab $01ED00
@item 19
@tab 29
@tab 522
@tab $020A00
@item 20
@tab 29
@tab 551
@tab $022700
@item 21
@tab 29
@tab 580
@tab $024400
@item 22
@tab 29
@tab 609
@tab $026100
@item 23
@tab 29
@tab 638
@tab $027E00
@item 24
@tab 29
@tab 667
@tab $029B00
@item 25
@tab 29
@tab 696
@tab $02B800
@item 26
@tab 29
@tab 725
@tab $02D500
@item 27
@tab 29
@tab 754
@tab $02F200
@item 28
@tab 29
@tab 783
@tab $030F00
@item 29
@tab 29
@tab 812
@tab $032C00
@item 30
@tab 29
@tab 841
@tab $034900
@item 31
@tab 29
@tab 870
@tab $036600
@item 32
@tab 29
@tab 899
@tab $038300
@item 33
@tab 29
@tab 928
@tab $03A000
@item 34
@tab 29
@tab 957
@tab $03BD00
@item 35
@tab 29
@tab 986
@tab $03DA00
@item 36
@tab 29
@tab 1015
@tab $03F700
@item 37
@tab 29
@tab 1044
@tab $041400
@item 38
@tab 29
@tab 1073
@tab $043100
@item 39
@tab 29
@tab 1102
@tab $044E00
@item 40
@tab 27
@tab 1131
@tab $046B00
@item 41
@tab 27
@tab 1158
@tab $048600
@item 42
@tab 27
@tab 1185
@tab $04A100
@item 43
@tab 27
@tab 1212
@tab $04BC00
@item 44
@tab 27
@tab 1239
@tab $04D700
@item 45
@tab 27
@tab 1266
@tab $04F200
@item 46
@tab 27
@tab 1293
@tab $050D00
@item 47
@tab 27
@tab 1320
@tab $052800
@item 48
@tab 27
@tab 1347
@tab $054300
@item 49
@tab 27
@tab 1374
@tab $055E00
@item 50
@tab 27
@tab 1401
@tab $057900
@item 51
@tab 27
@tab 1428
@tab $059400
@item 52
@tab 27
@tab 1455
@tab $05AF00
@item 53
@tab 27
@tab 1482
@tab $05CA00
@item 54
@tab 25
@tab 1509
@tab $05E500
@item 55
@tab 25
@tab 1534
@tab $05FE00
@item 56
@tab 25
@tab 1559
@tab $061700
@item 57
@tab 25
@tab 1584
@tab $063000
@item 58
@tab 25
@tab 1609
@tab $064900
@item 59
@tab 25
@tab 1634
@tab $066200
@item 60
@tab 25
@tab 1659
@tab $067B00
@item 61
@tab 25
@tab 1684
@tab $069400
@item 62
@tab 25
@tab 1709
@tab $06AD00
@item 63
@tab 25
@tab 1734
@tab $06C600
@item 64
@tab 25
@tab 1759
@tab $06DF00
@item 65
@tab 23
@tab 1784
@tab $06F800
@item 66
@tab 23
@tab 1807
@tab $070F00
@item 67
@tab 23
@tab 1830
@tab $072600
@item 68
@tab 23
@tab 1853
@tab $073D00
@item 69
@tab 23
@tab 1876
@tab $075400
@item 70
@tab 23
@tab 1899
@tab $076B00
@item 71
@tab 23
@tab 1922
@tab $078200
@item 72
@tab 23
@tab 1945
@tab $079900
@item 73
@tab 23
@tab 1968
@tab $07B000
@item 74
@tab 23
@tab 1991
@tab $07C700
@item 75
@tab 23
@tab 2014
@tab $07DE00
@item 76
@tab 23
@tab 2037
@tab $07F500
@item 77
@tab 23
@tab 2060
@tab $080C00
@item 78
@tab 29
@tab 2083
@tab $082300
@item 79
@tab 29
@tab 2112
@tab $084000
@item 80
@tab 29
@tab 2141
@tab $085D00
@item 81
@tab 29
@tab 2170
@tab $087A00
@item 82
@tab 29
@tab 2199
@tab $089700
@item 83
@tab 29
@tab 2228
@tab $08B400
@item 84
@tab 29
@tab 2257
@tab $08D100
@item 85
@tab 29
@tab 2286
@tab $08EE00
@item 86
@tab 29
@tab 2315
@tab $090600
@item 87
@tab 29
@tab 2344
@tab $092800
@item 88
@tab 29
@tab 2373
@tab $094500
@item 89
@tab 29
@tab 2402
@tab $096200
@item 90
@tab 29
@tab 2431
@tab $097F00
@item 91
@tab 29
@tab 2460
@tab $099C00
@item 92
@tab 29
@tab 2489
@tab $09B900
@item 93
@tab 29
@tab 2518
@tab $09D600
@item 94
@tab 29
@tab 2547
@tab $09F300
@item 95
@tab 29
@tab 2576
@tab $0A1000
@item 96
@tab 29
@tab 2605
@tab $0A2D00
@item 97
@tab 29
@tab 2634
@tab $0A4A00
@item 98
@tab 29
@tab 2663
@tab $0A6700
@item 99
@tab 29
@tab 2692
@tab $0A8400
@item 100
@tab 29
@tab 2721
@tab $0AA100
@item 101
@tab 29
@tab 2750
@tab $0ABE00
@item 102
@tab 29
@tab 2779
@tab $0ADB00
@item 103
@tab 29
@tab 2808
@tab $0AF800
@item 104
@tab 29
@tab 2837
@tab $0B1500
@item 105
@tab 29
@tab 2866
@tab $0B3200
@item 106
@tab 29
@tab 2895
@tab $0B4F00
@item 107
@tab 29
@tab 2924
@tab $0B6C00
@item 108
@tab 29
@tab 2953
@tab $0B8900
@item 109
@tab 29
@tab 2982
@tab $0BA600
@item 110
@tab 29
@tab 3011
@tab $0BC300
@item 111
@tab 29
@tab 3040
@tab $0BE000
@item 112
@tab 29
@tab 3069
@tab $0BFD00
@item 113
@tab 29
@tab 3098
@tab $0C1A00
@item 114
@tab 29
@tab 3137
@tab $0C3700
@item 115
@tab 29
@tab 3156
@tab $0C5400
@item 116
@tab 29
@tab 3185
@tab $0C7100
@item 117
@tab 27
@tab 3214
@tab $0C8E00
@item 118
@tab 27
@tab 3241
@tab $0CA900
@item 119
@tab 27
@tab 3268
@tab $0CC400
@item 120
@tab 27
@tab 3295
@tab $0CDF00
@item 121
@tab 27
@tab 3322
@tab $0CFA00
@item 122
@tab 27
@tab 3349
@tab $0D1500
@item 123
@tab 27
@tab 3376
@tab $0D3000
@item 124
@tab 27
@tab 3403
@tab $0D4B00
@item 125
@tab 27
@tab 3430
@tab $0D6600
@item 126
@tab 27
@tab 3457
@tab $0D8100
@item 127
@tab 27
@tab 3484
@tab $0D9C00
@item 128
@tab 27
@tab 3511
@tab $0DB700
@item 129
@tab 27
@tab 3538
@tab $0DD200
@item 130
@tab 27
@tab 3565
@tab $0DED00
@item 131
@tab 25
@tab 3592
@tab $0E0800
@item 132
@tab 25
@tab 3617
@tab $0E2100
@item 133
@tab 25
@tab 3642
@tab $0E3A00
@item 134
@tab 25
@tab 3667
@tab $0E5300
@item 135
@tab 25
@tab 3692
@tab $0E6C00
@item 136
@tab 25
@tab 3717
@tab $0E8500
@item 137
@tab 25
@tab 3742
@tab $0E9E00
@item 138
@tab 25
@tab 3767
@tab $0EB700
@item 139
@tab 25
@tab 3792
@tab $0ED000
@item 140
@tab 25
@tab 3817
@tab $0EE900
@item 141
@tab 25
@tab 3842
@tab $0F0200
@item 142
@tab 23
@tab 3867
@tab $0F1B00
@item 143
@tab 23
@tab 3890
@tab $0F3200
@item 144
@tab 23
@tab 3913
@tab $0F4900
@item 145
@tab 23
@tab 3936
@tab $0F6000
@item 146
@tab 23
@tab 3959
@tab $0F7700
@item 147
@tab 23
@tab 3982
@tab $0F8E00
@item 148
@tab 23
@tab 4005
@tab $0FA500
@item 149
@tab 23
@tab 4028
@tab $0FBC00
@item 150
@tab 23
@tab 4051
@tab $0FD300
@item 151
@tab 23
@tab 4074
@tab $0FEA00
@item 152
@tab 23
@tab 4097
@tab $100100
@item 153
@tab 23
@tab 4120
@tab $101800
@item 154
@tab 23
@tab 4143
@tab $102F00
@end multitable

The BAM (Block Availability Map) is on track 38. The D82 is 154
tracks and so the BAM is contained on 38/0, 38/3, 38/6 and 38/9.
The BAM interleave is 3.

The directory is on track 39, with 39/0 contains the header (DOS
type, disk name, disk ID's) and sectors 1-28 contain the
directory entries. Both files and the directory use an
interleave of 1. Since the directory is only 28 sectors large
(29 less one for the header), and each sector can contain only 8
entries (32 bytes per entry), the maximum number of directory
entries is 28 * 8 = 224. The first directory sector is always
39/1. It then follows a chain structure using a sector
interleave of 1 making the links go 39/1, 39/2, 39/3 etc.

When reading a disk, you start with 39/0 (disk label/ID) which
points to 38/0 (BAM0), 38/3 (BAM1), 38/6 (BAM2), 38/9 (BAM3, and
finally to 39/1 (first dir entry sector). When writing a file to
a blank disk, it will start at 38/1 because 38/0 is already
allocated.

Below is a dump of the header sector 39/0:

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 00 43 00 00 00 73 61 6D 70 6C 65 20 64 38 30
10: A0 A0 A0 A0 A0 A0 A0 A0 65 72 A0 32 43 A0 A0 A0
20: A0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@dots{}
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to first BAM sector (38/0)
@item $02
@tab $43 'C' is for DOS format version
@item $03
@tab Reserved
@item $04-$05
@tab Unused
@item $06-$16
@tab Disk name, padded with 0xA0 ("sample d82")
@item $17
@tab 0xA0
@item $18-$19
@tab Disk ID bytes "er"
@item $1A
@tab 0xA0
@item $1B-$1C
@tab DOS version bytes "2C"
@item $1D-$20
@tab 0xA0
@item $21-$FF
@tab Unused
@end multitable

Below is a dump of the first directory sector, 39/1

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 27 02 82 26 01 54 45 53 54 A0 A0 A0 A0 A0 A0 A0
10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
20: 00 00 82 26 02 54 45 53 54 32 A0 A0 A0 A0 A0 A0
30: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
40: 00 00 82 26 04 54 45 53 54 33 A0 A0 A0 A0 A0 A0
50: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 05 00
60: 00 00 82 26 0B 54 45 53 54 34 A0 A0 A0 A0 A0 A0
70: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 09 00
80: 00 00 82 26 14 54 45 53 54 35 A0 A0 A0 A0 A0 A0
90: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0C 00
A0: 00 00 82 28 00 54 45 53 54 36 A0 A0 A0 A0 A0 A0
B0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
C0: 00 00 82 28 01 54 45 53 54 37 A0 A0 A0 A0 A0 A0
D0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
E0: 00 00 82 28 02 54 45 53 54 38 A0 A0 A0 A0 A0 A0
F0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00
@end example

The first two bytes of the directory sector ($27/$02) indicate
the location of the next track/sector of the directory (39/2).
If the track is set to $00, then it is the last sector of the
directory.

When the directory is done, the track value will be $00. The
sector link should contain a value of $FF, meaning the whole
sector is allocated, but the actual value doesn't matter. The
drive will return all the available entries anyways. This is a
breakdown of a standard directory sector:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$1F
@tab First directory entry
@item $20-$3F
@tab Second dir entry
@item $40-$5F
@tab Third dir entry
@item $60-$7F
@tab Fourth dir entry
@item $80-$9F
@tab Fifth dir entry
@item $A0-$BF
@tab Sixth dir entry
@item $C0-$DF
@tab Seventh dir entry
@item $E0-$FF
@tab Eighth dir entry
@end multitable

This is a breakdown of a standard directory entry:

@multitable @columnfractions .2 .8
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab Track/Sector location of next directory sector ($00 $00 if not the first entry in the sector)
@item $02
@tab File type
@item $03-$04
@tab Track/sector location of first sector of file
@item $05-$14
@tab 16 character filename (in PETASCII, padded with $A0)
@item $15-$16
@tab Track/Sector location of first side-sector block (REL file only)
@item $17
@tab REL file record length (REL file only, max. value 254)
@item $18-$1D
@tab Unused
@item $1E-$1F
@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254
@end multitable

The file type field is used as follows:

@multitable @columnfractions .2 .8
@item @b{Bits}
@tab @b{Description}
@item 0-3
@tab The actual file type
@item 4
@tab Unused
@item 5
@tab Used only during SAVE-@@ replacement
@item 6
@tab Locked flag (Set produces ">" locked files)
@item 7
@tab Closed flag (Not set produces "*", or "splat" files)
@end multitable

The actual file type can be one of the following:

@multitable @columnfractions .2 .2 .6
@item @b{Binary}
@tab @b{Decimal}
@tab @b{File type}
@item 0000
@tab 0
@tab DEL
@item 0001
@tab 1
@tab SEQ
@item 0010
@tab 2
@tab PRG
@item 0011
@tab 3
@tab USR
@item 0100
@tab 4
@tab REL
@end multitable

Values 5-15 are illegal, but if used will produce very strange results.

@c @node FIXME
@subsection Non-Standard & Long Directories

Most Commdore floppy disk drives use a single dedicated
directory track where all filenames are stored. This limits the
number of files stored on a disk based on the number of sectors
on the directory track. There are some disk images that contain
more files than would normally be allowed. This requires
extending the directory off the default directory track by
changing the last directory sector pointer to a new track,
allocating the new sectors in the BAM, and manually placing (or
moving existing) file entries there. The directory of an
extended disk can be read and the files that reside there can
be loaded without problems on a real drive. However, this is
still a very dangerous practice as writing to the extended
portion of the directory will cause directory corruption in the
non-extended part. Many of the floppy drives core ROM routines
ignore the track value that the directory is on and assume the
default directory track for operations.

@c @node FIXME
@subsection BAM layout

The BAM only occupies up to four sectors on track 38, so the
rest of the track is empty and is available for file storage.
Below is a dump of the first BAM block, 38/0. A D82 will
contain four BAM sectors, 38/0, 38/3, 38/6 and 38/9. Each
entry takes 5 bytes, 1 for the free count on that track, and
4 for the BAM bits.

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 03 43 00 01 33 1D FF FF FF 1F 1D FF FF FF 1F
10: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
20: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
30: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
40: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
50: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
60: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
70: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
80: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
90: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
A0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
B0: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1B
C0: F6 FF FF 1F 1B FC FF FF 1F 1B FF FF FF 07 1B FF
D0: FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF
E0: FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF
F0: 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to second BAM sector (38/3)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x01=1)
@item $05
@tab Highest+1 track covered by this BAM (0x33=51)
@item $06-$0A
@tab BAM for track 1. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 2
@item @dots{}
@tab @dots{}
@item $FB-$FF
@tab BAM for track 50
@end multitable

Being bit-based, the BAM entries need some explanation. The
first track entry in the above BAM sector is at offset 06,
"1D FF FF FF 1F". The first number is how many blocks are free
on this track ($1D=29) and the remainder is the bit
representation of the usage map for the track. These entries
must be viewed in binary to make any sense. First convert the
values to binary:

@example
 FF=11111111, FF=11111111, FF=11111111, 1F=00011111
@end example

In order to make any sense from the binary notation, flip the
bits around.

@example
            111111 11112222 222222
 01234567 89012345 67890123 456789@dots{}
 -------------------------- ---------
 11111111 11111111 11111111 11111000
 ^                              ^
 sector 0                  sector 28
@end example

Since we are on the first track, we have 29 sectors, and only
use up to the bit 28 position. If a bit is on (1), the sector is
free. Therefore, track 1 is clean, all sectors are free. Any
leftover bits that refer to sectors that don't exist, like bits
29-31 in the above example, are set to allocated.

Second BAM block 38/3

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 06 43 00 33 65 1B FF FF FF 07 1B FF FF FF 07
10: 1B FF FF FF 07 19 FF FF FF 01 19 FF FF FF 01 19
20: FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF
30: FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF FF
40: FF 01 19 FF FF FF 01 19 FF FF FF 01 17 FF FF 7F
50: 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00
60: 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17
70: FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF
80: FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 1D FF FF
90: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
A0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
B0: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
C0: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
D0: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
E0: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
F0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to third BAM sector (38/6)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x33=51)
@item $05
@tab Highest+1 track covered by this BAM (0x65=101)
@item $06-$0A
@tab BAM for track 51. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 52
@item @dots{}
@tab @dots{}
@item $FB-$FF
@tab BAM for track 100
@end multitable

Third BAM block 38/6

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 26 09 43 00 65 97 1D FF FF FF 1F 1D FF FF FF 1F
10: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D
20: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF
30: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF
40: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF
50: 1F 1D FF FF FF 1F 1B FF FF FF 07 1B FF FF FF 07
60: 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B
70: FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF
80: FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF
90: FF 07 1B FF FF FF 07 1B FF FF FF 07 19 FF FF FF
A0: 01 19 FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01
B0: 19 FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19
C0: FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF
D0: FF FF 01 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF
E0: 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F
F0: 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to fourth BAM sector (38/9)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x65=101)
@item $05
@tab Highest+1 track covered by this BAM (0x97=151)
@item $06-$0A
@tab BAM for track 101. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 102
@item @dots{}
@tab @dots{}
@item $FB-$FF
@tab BAM for track 150
@end multitable

Fourth BAM block 38/9

@example
    00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
    -----------------------------------------------
00: 27 01 43 00 97 9B 17 FF FF 7F 00 17 FF FF 7F 00
10: 17 FF FF 7F 00 17 FF FF 7F 00 00 00 00 00 00 00
20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$01
@tab T/S pointer to first directory sector (39/1)
@item $02
@tab DOS version byte (0x43='C')
@item $03
@tab Reserved
@item $04
@tab Lowest track covered by this BAM (0x97=151)
@item $05
@tab Highest+1 track covered by this BAM (0x9B=155)
@item $06-$0A
@tab BAM for track 151. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track.
@item $0B-$0F
@tab BAM for track 152
@item @dots{}
@tab @dots{}
@item $15-$19
@tab BAM for track 154
@item $1A-$FF
@tab Not used
@end multitable

@node P00, , D82, File formats
@section The P00 image format

@c FIXME: the P00 section needs to be style-checked.

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.)

These files were created for use in the PC64 emulator, written
by Wolfgang Lorenz. Each one has the same layout with the
filetype being stored in the DOS extension (i.e. Pxx is a PRG,
Sxx is a SEQ, Uxx is a USR and Rxx is a RELative file), and the
header is only 26 bytes long.

This is a dump of a Pxx file (PRG)@dots{}

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
      -----------------------------------------------
0000: 43 36 34 46 69 6C 65 00 43 52 49 53 49 53 20 4D
0010: 4F 55 4E 54 41 49 4E 00 00 00
@end example

@multitable @columnfractions .3 .7
@item @b{Bytes}
@tab @b{Description}
@item $00-$06
@tab ASCII string "C64File"
@item $07
@tab Always $00
@item $08-$17
@tab Filename in PETASCII, padded with $00 (not $A0, like a D64)
@item $18
@tab Always $00
@item $19
@tab REL file record size ($00 if not a REL file)
@item $1A-??
@tab Program data
@end multitable

The 'xx' in the extension of the file is usually 00, except when
we have two DOS filenames which would be the same, but the C64
filenames are different! If we have two C64 filenames which are
the same, they *cannot* co-exist in the same directory. If we
have two files which do convert down to be the same DOS
filename, the extension is incremented until an unused one is
found (x01, x02, x03, up to x99). We can have up to 99 different
C64 files with the same corresponding DOS names as that's all
the extension will hold (from P00 to P99).

Each PC64 file only has one entry, there are no multi-file
containers allowed. This could result in a large number of
these files in a directory, even for only a few programs, as
each C64 file will result in a PC64 file entry. The best use
for a PC64 file is a single-file program, one which does not
load anything else.

@c FIXME: the CRT section needs to be style-checked.

@c @node FIXME
@section The CRT cartridge image format

This chapter is based on CRT.txt (rev1.14) compiled by Peter Schepers, with
additional contributions from Per Hakan Sundell, Markus Brenner,
Marco Van Den Heuvel, Groepaz.

  Cartridge files were introduced in the CCS64  emulator,  written  by  Per
Hakan Sundell, and use the ".CRT" file extension. This format  was  created
to handle the various ROM cartridges that exist, such as Action Replay, the
Power cartridge, and the Final Cartridge.

  Normal game cartridges can load  into  several  different  memory  ranges
($8000-9FFF,  $A000-BFFF  or  $E000-FFFF).  Newer   utility   and   freezer
cartridges were less intrusive, hiding themselves until  called  upon,  and
still others used bank-switching techniques to allow much larger ROM's than
normal. Because of these "stealthing" and bank-switching methods, a special
cartridge format  was  necessary,  to  let  the  emulator  know  where  the
cartridge should reside, the control line  states  to  enable  it  and  any
special hardware features it uses.

@subsection Header contents

  Here is a dump of a sample 8K normal cartridge,  "Attack  Of  The  Mutant
Camels"@dots{}

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 00 00 01 00 00 00 00 00 00   ???@@????????????
0020: 41 54 54 41 43 4B 20 4F 46 20 54 48 45 20 4D 55   ATTACK?OF?THE?MU
0030: 54 41 4E 54 20 43 41 4D 45 4C 53 00 00 00 00 00   TANT?CAMELS?????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: D3 9B BC FE C3 C2 CD 38 30 EA EA EA A9 01 85 13   .›?....80....?…?
0060: 4C B3 9B A9 08 85 5A 88 D0 FD C6 5A D0 F9 60 D0   L³›.?…Zˆ...Z.?`.
@end example

@example
  Bytes:$0000-000F - 16-byte cartridge signature  "C64  CARTRIDGE"  (padded
                     with space characters)
         0010-0013 - File header length  ($00000040,  in  high/low  format,
                     calculated from offset $0000). The default  (also  the
                     minimum) value is $40.  Some  cartridges  exist  which
                     show a value of $00000020 which is wrong.
         0014-0015 - Cartridge version (high/low, presently 01.00)
         0016-0017 - Cartridge hardware type ($0000, high/low)
                       0 - Normal cartridge
                       1 - Action Replay
                       2 - KCS Power Cartridge
                       3 - Final Cartridge III
                       4 - Simons' BASIC
                       5 - Ocean type 1*
                       6 - Expert Cartridge
                       7 - Fun Play, Power Play
                       8 - Super Games
                       9 - Atomic Power
                      10 - Epyx Fastload
                      11 - Westermann Learning
                      12 - Rex Utility
                      13 - Final Cartridge I
                      14 - Magic Formel
                      15 - C64 Game System, System 3
                      16 - Warp Speed
                      17 - Dinamic**
                      18 - Zaxxon, Super Zaxxon (SEGA)
                      19 - Magic Desk, Domark, HES Australia
                      20 - Super Snapshot V5
                      21 - Comal-80
                      22 - Structured BASIC
                      23 - Ross
                      24 - Dela EP64
                      25 - Dela EP7x8
                      26 - Dela EP256
                      27 - Rex EP256
                      28 - Mikro Assembler
                      29 - Final Cartridge Plus
                      30 - Action Replay 4
                      31 - Stardos
                      32 - EasyFlash
                      33 - EasyFlash Xbank
                      34 - Capture
                      35 - Action Replay 3
                      36 - Retro Replay
                      37 - MMC64
                      38 - MMC Replay
                      39 - IDE64
                      40 - Super Snapshot V4
                      41 - IEEE-488
                      42 - Game Killer
                      43 - Prophet64
                      44 - EXOS
                      45 - Freeze Frame
                      46 - Freeze Machine
                      47 - Snapshot64
                      48 - Super Explode V5.0
                      49 - Magic Voice
                      50 - Action Replay 2
                      51 - MACH 5
                      52 - Diashow-Maker
                      53 - Pagefox
              0018 - Cartridge port EXROM line status
                      0 - inactive
                      1 - active
              0019 - Cartridge port GAME line status
                      0 - inactive
                      1 - active
         001A-001F - Reserved for future use
         0020-003F - 32-byte cartridge  name  "CCSMON"  (uppercase,  padded
                     with null characters)
         0040-xxxx - Cartridge contents (called CHIP PACKETS, as there  can
                     be more than one  per  CRT  file).  See  below  for  a
                     breakdown of the CHIP format.
@end example

  (*Note: Ocean type 1 includes Navy Seals, Robocop 2 & 3,  Shadow  of  the
    Beast, Toki, Terminator 2 and more)

  (**Note: Dinamic includes Narco Police and more)

@c @node FIXME
@subsection CHIP Contents


  The following is the contents of the CHIP packet, from position $0040  on
in the CRT file. Note I have re-adjusted the starting address to be  $0000,
since we are now looking at a file contained in the .CRT file, and all size
references are from where it starts.

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0010: D3 9B BC FE C3 C2 CD 38 30 EA EA EA A9 01 85 13   .›?....80....?…?
0020: 4C B3 9B A9 08 85 5A 88 D0 FD C6 5A D0 F9 60 D0   L³›.?…Zˆ...Z.?`.
0030: F2 60 A9 04 85 49 A9 00 85 48 A2 00 A5 48 9D 40   ?`.?…I.?…H.?¥H@@
0040: 03 A5 49 9D 60 03 A5 48 18 69 28 85 48 A5 49 69   ?¥I`?¥H?i(…H¥Ii
0050: 00 85 49 E8 E0 18 D0 E4 60 A6 03 A4 02 BD 40 03   ?…I???.?`?????@@?
@end example

@example
  Bytes:$0000-0003 - Contained ROM signature "CHIP" (note there can be more
                     than one image in a .CRT file)
         0004-0007 - Total packet length ($00002010,  ROM  image  size  and
                     header combined) (high/low format)
         0008-0009 - Chip type
                      0 - ROM
                      1 - RAM, no ROM data
                      2 - Flash ROM
         000A-000B - Bank number ($0000 - normal cartridge)
         000C-000D - Starting load address (high/low format)
         000E-000F - ROM image size in bytes  (high/low  format,  typically
                     $2000 or $4000)
         0010-xxxx - ROM data
@end example

  The following is a chart taken from the "Commodore Programmers  Reference
Guide". It details the state of various areas of memory  depending  on  the
state of the control lines.


Legend:
L - ROML (low)
H - ROMH (high)
G - GAME
E - EXROM

@example
Addr       LHGE   LHGE   LHGE   LHGE   LHGE   LHGE   LHGE   LHGE   LHGE
Range
           1111   101X   1000   011X   001X   1110   0100   1100   XX01
         default                00X0                             Ultimax
-------------------------------------------------------------------------
E000-FFFF Kernal  RAM    RAM   Kernal  RAM   Kernal Kernal Kernal ROMH(*)
D000-DFFF IO/CHR IO/CHR IO/RAM IO/CHR  RAM   IO/CHR IO/CHR IO/CHR   I/O
C000-CFFF  RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM     -
A000-BFFF BASIC   RAM    RAM    RAM    RAM   BASIC   ROMH   ROMH    -
8000-9FFF  RAM    RAM    RAM    RAM    RAM    ROML   RAM    ROML  ROML(*)
4000-7FFF  RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM     -
1000-3FFF  RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM     -
0000-0FFF  RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM    RAM
@end example

(*) Internal memory does not respond to write accesses in these areas


  From the above chart, the following table can be built. It shows standard
cartridges, either 8K or 16K in size, and the memory ranges they load into.

@example
Type     Size   Game   EXRom  Low Bank  High Bank
         in K   Line   Line    (ROML)    (ROMH)
-------------------------------------------------
Normal    8k     hi     lo     $8000      ----
Normal    16k    lo     lo     $8000     $A000
Ultimax   8k     lo     hi     $E000      ----
@end example

  The ROMH and ROML lines are CPU-controlled status  lines,  used  to  bank
in/out RAM, ROM or I/O, depending on what is needed at the time.

  Ultimax cartridges typically are situated  in  the  $E000-FFFF  (8K)  ROM
address range. There are some cartridges  which  only  use  4K  of  the  8K
allocation. If the cartridge is 16K in size, then it will  reside  in  both
$8000-9FFF and $E000-FFFF.

@c @node FIXME
@subsection Cartridge Specifics

@c @node FIXME
@subsubsection 0 - Normal cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 00 00 01 00 00 00 00 00 00   ???@@????????????
0020: 41 54 54 41 43 4B 20 4F 46 20 54 48 45 20 4D 55   ATTACK?OF?THE?MU
0030: 54 41 4E 54 20 43 41 4D 45 4C 53 00 00 00 00 00   TANT?CAMELS?????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: D3 9B BC FE C3 C2 CD 38 30 EA EA EA A9 01 85 13   .›?....80....?…?
@end example

      The second sample below is a dump of "Music Machine", a  4Kb  ULTIMAX
    mode cartridge. It  is  still  identified  as  a  "standard  cartridge"
    according to the ID.

    Normal cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 4Kb (ULTIMAX mode)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (1)
@item Load address
@tab $F000-F7FF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 00 01 00 00 00 00 00 00 00   ???@@????????????
0020: 4D 55 53 49 43 20 4D 41 43 48 49 4E 45 00 00 00   MUSIC?MACHINE???
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 10 10 00 00 00 00 F0 00 10 00   CHIP????????????
0050: 3C 66 C3 C3 66 3C FF FF 18 3C 66 7E 66 66 66 00   <f..f<???<f~fff?
@end example


      The third sample is a dump of "Adventure Creator",  a  16Kb  standard
    cartridge.

    Normal cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 00 00 00 00 00 00 00 00 00   ???@@????????????
0020: 41 64 76 65 6E 74 75 72 65 20 43 72 65 61 74 6F   Adventure?Creato
0030: 72 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   r???????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00   CHIP??@?????.?@@?
0050: 09 80 81 EA C3 C2 CD 38 30 A2 00 78 D8 8E 11 D0   ?.....80.?x.Ž?.
@end example


@c @node FIXME
@subsubsection 1 - Action Replay

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb (4 banks of 8Kb each)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-9FFF (all modules)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 01 00 00 00 00 00 00 00 00   ???@@????????????
0020: 41 63 74 69 6F 6E 20 52 65 70 6C 61 79 20 56 00   Action?Replay?V?
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 09 80 0C 80 C3 C2 CD 38 30 4C 60 80 4C 63 80 4C   ?.?....80L`.Lc.L
@end example

    This cart has 32Kb of ROM, and 8Kb of RAM. The bank switching  is  done
    by writing to the I/O-1 range as follows:

@example
    bit  meaning
    ---  -------
    7    extra ROM bank selector (A15) (unused)
    6    1 = resets FREEZE-mode (turns back to normal mode)
    5    1 = enable RAM at ROML ($8000-$9FFF) &
             I/O-2 ($DF00-$DFFF = $9F00-$9FFF)
    4    ROM bank selector high (A14)
    3    ROM bank selector low  (A13)
    2    1 = disable cartridge (turn off $DE00)
    1    1 = /EXROM high
    0    1 = /GAME low
@end example

    Additionally the RAM or ROM can be available through a  window  in  the
    I/O-2 range.


@c @node FIXME
@subsubsection 2 - KCS Power Cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8K each)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab module #1 - $8000-9FFF
                   module #2 - $A000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 20 01 00 00 02 00 00 00 00 00 00 00 00   ????????????????
0020: 4B 43 53 20 50 6F 77 65 72 20 43 61 72 74 72 69   KCS?Power?Cartri
0030: 64 67 65 00 00 00 00 00 00 00 00 00 00 00 00 00   dge?????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 09 80 5E FE C3 C2 CD 38 30 78 D8 A2 FF 9A A9 27   ?.^....80x..?..'
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00   CHIP???????? ???
2060: 97 E3 16 A1 FF FF FF 20 13 A0 A5 01 09 01 85 01   —.?.????? ¥???…?
@end example


@c @node FIXME
@subsubsection 3 - Final Cartridge III

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb each)
@item GAME
@tab active (1)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-BFFF (all modules)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 03 01 01 00 00 00 00 00 00   ???@@????????????
0020: 46 69 6E 61 6C 20 43 61 72 74 72 69 64 67 65 20   Final?Cartridge?
0030: 49 49 49 20 31 39 38 37 00 00 00 00 00 00 00 00   III?1987????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00   CHIP??@@?????.?@@?
0050: 09 80 5E FE C3 C2 CD 38 30 4C 4C 80 4C 55 95 4C   ?.^....80LL.LU•L
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00   CHIP??@@?????.?@@?
4060: 01 02 00 81 5D 81 61 81 99 81 D8 81 0B 82 33 82   ???]a™.?‚3‚
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00   CHIP??@@?????.?@@?
8070: 20 43 80 20 52 80 A9 4E 20 05 DE 20 FD BF AD 39   ?C.?R..N??.?..­9
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00   CHIP??@@?????.?@@?
C080: A2 06 BD DD 85 95 05 CA 10 F8 AE A0 02 E8 EC A2   .??.…•?.??® ???.
@end example

    A total of 64 kB of ROM memory  is  organized  into  four  $4000  banks
    located at $8000-$BFFF.

    The banks are arranged in the following way:

@example
    Bank 0:  BASIC, Monitor, Disk-Turbo
    Bank 1:  Notepad, BASIC (Menu Bar)
    Bank 2:  Desktop, Freezer/Print
    Bank 3:  Freezer, Compression
@end example

    The cartridges uses the entire I/O-1 and I/O-2 range. Bank switching is
    done by writing the bank number plus $40 into  memory  location  $DFFF.
    For instance, to select bank 2, $DFFF is set to $42.

    The CRT file contains four CHIP blocks, each block with a start address
    of $8000, length $4000 and the bank number in the bank  field.  In  the
    cartridge header, both EXROM ($18) and GAME  ($19)  are  set  to  1  to
    enable the 16 kB ROM configuration.

    The registers are arranged in the following way:

    One register at $DFFF:

@example
    bit  meaning
    ---  -------
    7      Hide this register (1 = hidden)
    6      NMI line  (0 = low = active) *1)
    5      GAME line  (0 = low = active) *2)
    4      EXROM line (0 = low = active)
    2-3    unassigned (usually set to 0)
    0-1    number of bank to show at $8000
@end example

    1) if either the freezer button is pressed, or bit 6 is 0, then an  NMI
       is generated

    2) if the freezer button is pressed, GAME is also forced low

    The rest of I/O-1/I/O-2 contain a mirror of the last  2  pages  of  the
    currently selected ROM bank (also at $dfff, contrary to what some other
    documents say)


@c @node FIXME
@subsubsection 4 - Simons' Basic

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8kb each)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 40 01 00 00 04 00 01 00 00 00 00 00 00   ???@@????????????
0020: 53 69 6D 6F 6E 27 73 20 42 61 73 69 63 00 00 00   Simon's?Basic???
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 52 81 52 81 C3 C2 CD 38 30 41 4C 52 81 20 2C 81   RR...80ALR?,
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00   CHIP???????? ???
2060: 20 A4 A6 99 9E CB A0 05 A5 A8 91 20 A4 A6 99 A2   ???™ž. ?¥?.???™.
@end example

    Simons' BASIC permanently uses 16 kB ($4000) bytes of cartridge  memory
    from $8000-$BFFF. However, through some custom bank-switching logic the
    upper area ($A000-$BFFF) may be disabled so Simons' BASIC may use it as
    additional RAM. Writing a value of $01 to address location $DE00  banks
    in ROM, $00 disables ROM and enables RAM.

    The CRT file contains two CHIP blocks of length $2000 each,  the  first
    block having a start address of $8000, the second block $A000.  In  the
    cartridge header, EXROM ($18) is set to 0, GAME ($19) is set  to  1  to
    indicate the RESET/power-up configuration of 8 kB ROM.


@c @node FIXME
@subsubsection 5 - Ocean type 1

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb, 128Kb, 256Kb or 512Kb sizes (4, 16, 32 or 64 banks of 8Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab Banks 00-15 - $8000-9FFF
                   Banks 16-31 - $A000-BFFF  (except Terminator 2)
@end multitable

@example
       00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
       -----------------------------------------------   ----------------
00000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
00010: 00 00 00 40 01 00 00 05 00 00 00 00 00 00 00 00   ???@@????????????
00020: 53 48 41 44 4F 57 20 4F 46 20 54 48 45 20 42 45   SHADOW?OF?THE?BE
00030: 41 53 54 00 00 00 00 00 00 00 00 00 00 00 00 00   AST?????????????
00040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
00050: 09 80 83 81 C3 C2 CD 38 30 4C 83 81 4C 76 82 80   ?.ƒ...80LƒLv‚.
 @dots{}
02050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00   CHIP????????.???
02060: 59 6D 00 56 AD 00 55 AE F0 00 01 A0 FE 00 01 F8   Ym?V­?U®??? .???
 @dots{}
20140: 43 48 49 50 00 00 20 10 00 00 00 10 A0 00 20 00   CHIP???????? ???
20150: 0A 9A 55 FF 9B 69 57 FE AA 65 96 FE 65 0F D6 D9   ?.U?›iW.×e–.e?..
@end example

    Here is a list of the known OCEAN cartridges:

@example
    Batman The Movie    (128 kB)
    Battle Command      (128 kB)
    Double Dragon       (128 kB)
    Navy Seals          (128 kB)
    Pang                (128 kB)
    Robocop 3           (128 kB)
    Space Gun           (128 kB)
    Toki                (128 kB)
    Chase H.Q. II       (256 kB)
    Robocop 2           (256 kB)
    Shadow of the Beast (256 kB)
    Terminator 2        (512 kB)
@end example

    The 32Kb type of cart  has  4  banks  of  8Kb  ($2000),  banked  in  at
    $8000-$9FFF.

    The 128Kb type of cart has  16  banks of  8Kb  ($2000),  banked  in  at
    $8000-$9FFF.

    The 256Kb type of cart has 32 banks of 8Kb ($2000),  16  banked  in  at
    $8000-$9FFF, and 16 banked in at $A000-$BFFF.

    The 512Kb type of cart has 64  banks  of  8Kb  ($2000),  banked  in  at
    $8000-$9FFF.

    Bank switching is done by writing to $DE00. The lower six bits give the
    bank number (ranging from 0-63). Bit 8 in this selection word is always
    set.


@c @node FIXME
@subsubsection 6 - Expert Cartridge

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb
@item GAME
@tab active (1)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 06 01 01 00 00 00 00 00 00   ???@@????????????
0020: 45 78 70 65 72 74 20 43 61 72 74 72 69 64 67 65   Expert?Cartridge
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 40 10 00 02 00 00 80 00 20 00   CHIP??@@?????.???
0050: 00 00 00 0A F3 00 00 00 00 00 00 00 00 00 00 00   ????????????????
@end example


@c @node FIXME
@subsubsection 7 - Fun Play, Power Play

@multitable @columnfractions .3 .7
@item Size
@tab 128Kb (16 banks of 8Kb modules)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-9FFF (all modules)
@end multitable

@example
       00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
       -----------------------------------------------   ----------------
00000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
00010: 00 00 00 40 01 00 00 07 00 00 00 00 00 00 00 00   ???@@????????????
00020: 46 55 4E 20 50 4C 41 59 00 00 00 00 00 00 00 00   FUN?PLAY????????
00030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
00040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
00050: 1E 80 86 EA C3 C2 CD 38 30 1B 00 81 0D 08 80 00   ?.†....80????.?
 @dots{}
02050: 43 48 49 50 00 00 20 10 00 00 00 08 80 00 20 00   CHIP????????.???
02060: 78 A2 F0 86 01 BD 1D 08 9D F8 00 CA D0 F7 4C 00   x.?†??????..?L?
 @dots{}
04060: 43 48 49 50 00 00 20 10 00 00 00 10 80 00 20 00   CHIP????????.???
04070: 38 E5 68 85 03 B0 11 27 03 12 C0 18 69 27 42 90   8?h…?°?'??.?i'B
 @dots{}
06070: 43 48 49 50 00 00 20 10 00 00 00 18 80 00 20 00   CHIP????????.???
06080: 44 D0 5E 06 02 C0 44 11 40 04 11 44 01 5F 1C 73   D.^??.D?@@??D?_?s
 @dots{}
1E130: 43 48 49 50 00 00 20 10 00 00 00 39 80 00 20 00   CHIP???????9.???
1E140: 85 EB 41 EA 9E 08 03 00 C0 06 18 01 00 C0 08 03   …?A.ž???.????.??
@end example

    The FUN PLAY Cartridge uses $DE00 for  bank  selection,  and  uses  8Kb
    banks ($2000) at $8000-$9FFF. There are 16 banks of ROM memory and  are
    referenced by the following values:

@example
    $00 -> Bank 0
    $08 -> Bank 1
    $10 -> Bank 2
    $18 -> Bank 3
    $20 -> Bank 4
    $28 -> Bank 5
    $30 -> Bank 6
    $38 -> Bank 7
    $01 -> Bank 8
    $09 -> Bank 9
    $11 -> Bank 10
    $19 -> Bank 11
    $21 -> Bank 12
    $29 -> Bank 13
    $31 -> Bank 14
    $39 -> Bank 15
@end example

    The bank field in the chip  headers  is  set  according  to  the  value
    written to $DE00. The following bits are  used  for  bank  decoding  in
    $DE00 (0 being the LSB, 3 being the MSB).

@example
        Bit# 76543210
             xx210xx3
@end example

    After copying memory from the ROM banks, the selection  program  writes
    a value of $86 to $DE00. This seems either  to  reset  or  disable  the
    cartridge ROM.


@c @node FIXME
@subsubsection 8 - Super Games

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb each)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-BFFF (all modules)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 08 00 00 00 00 00 00 00 00   ???@@????????????
0020: 53 55 50 45 52 20 47 41 4D 45 53 00 00 00 00 00   SUPER?GAMES?????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00   CHIP??@@?????.?@@?
0050: 0A 80 0A 80 C3 C2 CD 38 30 00 A9 80 A0 00 85 FB   ?.?....80?.. ?….
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00   CHIP??@@?????.?@@?
4060: 27 80 A8 80 C3 C2 CD 38 30 00 40 C0 40 C0 40 C0   '.?....80?@@.@@.@@.
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00   CHIP??@@?????.?@@?
8070: 00 00 00 49 4D C7 64 47 46 45 F3 48 DC 08 7E 0B   ???IM.dGFE?H.?~?
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00   CHIP??@@?????.?@@?
C080: D5 F9 F0 C1 D5 F7 F0 BD E8 B5 02 F0 FB C9 05 30   .??..????µ??..?0
@end example

    The Super Games cartridge  uses  4  16Kb  banks  ($8000-$BFFF)  of  ROM
    memory. Bank selecting is done by writing to $DF00.

    $DF00 register is as follows:

@example
    bit  meaning
    ---  -------
    0    bank bit 0
    1    bank bit 1
    2    inverted GAME line
    3    inverted EXROM line
    4-7  unused
@end example

@c @node FIXME
@subsubsection 9 - Atomic Power

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb (4 banks of 8Kb modules)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-9FFF (all modules)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 09 00 00 00 00 00 00 00 00   ???@@????????????
0020: 41 74 6F 6D 69 63 20 50 6F 77 65 72 00 00 00 00   Atomic?Power????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 09 80 0C 80 C3 C2 CD 38 30 4C 41 80 4C 1E 80 4C   ?.?....80LA.L?.L
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00   CHIP????????.???
2060: 09 80 0C 80 C3 C2 CD 38 30 4C 3F 80 4C 91 80 4C   ?.?....80L?.L..L
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00   CHIP????????.???
4070: EF FC 09 80 C3 C2 CD 38 30 4C 27 80 4C DB 81 4C   ?.?....80L'.L.L
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00   CHIP????????.???
6080: 09 80 0C 80 C3 C2 CD 38 30 4C 73 86 4C 30 80 4C   ?.?....80Ls†L0.L
@end example

    This cart has 32Kb of ROM and 8Kb of RAM

    Writing to I/O-1 will do the following:

@example
    bit  meaning
    ---  -------
    7    extra ROM bank selector (A15) (unused)
    6    1 = resets FREEZE-mode (turns back to normal mode)
    5    1 = enable RAM at ROML ($8000-$9FFF) &
             I/O-2 ($DF00-$DFFF = $9F00-$9FFF)
    4    ROM bank selector high (A14)
    3    ROM bank selector low  (A13)
    2    1 = disable cartridge (turn off $DE00)
    1    1 = /EXROM high
    0    1 = /GAME low
@end example

    If bit 5 (RAM enable) is 1, bit 0,1 (exrom/game) is ==  2  (cart  off),
    bit 2,6,7 (cart disable, freeze clear) are 0, then cart ROM (Bank 0..3)
    is mapped at 8000-9FFF, and cart RAM (Bank 0) is  mapped  at  A000-BFFF
    and cart RAM (Bank 0) is is enabled in the I/O-2 area using  16Kb  game
    config.

    The cart RAM or ROM is available through a window in the I/O-2 range.


@c @node FIXME
@subsubsection 10 - Epyx Fastload

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb
@item GAME
@tab active (1)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 0A 01 01 00 00 00 00 00 00   ???@@????????????
0020: 45 50 59 58 20 46 41 53 54 4C 4F 41 44 00 00 00   EPYX?FASTLOAD???
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 30 80 5E FE C3 C2 CD 38 30 20 04 90 4C 38 DF AB   0.^....80??L8?«
@end example

    The Epyx FastLoad cart uses a simple capacitor to toggle the ROM on
    and off:

    the capacitor is discharged, and 8k game config enabled, by either
    reading ROML or reading I/O-1. If none of those accesses happen the
    capacitor will charge, and if it is charged (after 512 cycles) then
    the ROM will get disabled.

@c @node FIXME
@subsubsection 11 - Westermann Learning

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 0B 00 00 00 00 00 00 00 00   ???@@????????????
0020: 57 45 53 54 45 52 4D 41 4E 4E 00 00 00 00 00 00   WESTERMANN??????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 40 00   CHIP????????.?@@?
0050: 09 80 9C 80 C3 C2 CD 38 30 A2 00 8E 16 D0 20 84   ?.œ....80.?Ž?.?„
@end example

    Any read from the I/O-2 range will switch the cart off.


@c @node FIXME
@subsubsection 12 - Rex Utility

@multitable @columnfractions .3 .7
@item Size
@tab 8K
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 0C 00 01 00 00 00 00 00 00   ???@@????????????
0020: 52 45 58 00 00 00 00 00 00 00 00 00 00 00 00 00   REX?????????????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00   ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00   CHIP????????.???
0050: 08 80 C1 FE C3 C2 CD 38 30 6C 95 E3 20 A3 FD 20   ?......80l•.?£.?
@end example

    Reading from $DF00-DFBF disables ROM, reading from $DFC0-DFFF enables
    ROM (8k game config).


@c @node FIXME
@subsubsection 13 - Final Cartridge I

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb
@item GAME
@tab active (1)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F        ASCII
      -----------------------------------------------   ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20   C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 0D 01 01 00 00 00 00 00 00   ???@@????????????
0020: 54 68 65 20 46 69 6E 61 6C 20 43 61 72 74 72 69   The?Final?Cartri
0030: 64 67 65 20 49 00 00 00 00 00 00 00 00 00 00 00   dge?I???????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00   CHIP??@@?????.?@@?
0050: 80 BA 5E FE C3 C2 CD 38 30 00 A0 A0 20 2D FE 58   .÷^....80?  ?-.X
@end example

    Any access to I/O-1 turns cartridge ROM off. Any access to I/O-2  turns
    cartridge ROM on.

    The cart ROM is visible in I/O-1 and I/O-2.

@c @node FIXME
@subsubsection 14 - Magic Formel

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (8 banks of 8Kb)
@item GAME
@tab Inactive (0)
@item EXROM
@tab Inactive (0)
@item Load Address
@tab $E000-FFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 0E 01 01 00 00 00 00 00 00  ???@@????????????
0020: 4D 61 67 69 63 20 46 6F 72 6D 65 6C 00 00 00 00  Magic?Formel????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00  CHIP????????????
0050: 4D 46 30 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF0??`??`??`
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 E0 00 20 00  CHIP????????????
2060: 4C 5F E4 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  L_???`??`??`
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 E0 00 20 00  CHIP????????????
4070: 4D 46 32 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF2??`??`??`
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 E0 00 20 00  CHIP????????????
6080: 4D 46 33 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF3??`??`??`
@dots{}
8080: 43 48 49 50 00 00 20 10 00 00 00 04 E0 00 20 00  CHIP????????????
8090: 4D 46 34 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF4??`??`??`
@dots{}
A090: 43 48 49 50 00 00 20 10 00 00 00 05 E0 00 20 00  CHIP????????????
A0A0: 4D 46 35 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF5??`??`??`
@dots{}
C0A0: 43 48 49 50 00 00 20 10 00 00 00 06 E0 00 20 00  CHIP????????????
C0B0: 4D 46 36 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF6??`??`??`
..
E0B0: 43 48 49 50 00 00 20 10 00 00 00 07 E0 00 20 00  CHIP????????????
E0C0: 4D 46 37 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D  MF7??`??`??`
@end example


@c @node FIXME
@subsubsection 15 - C64 Game System, System 3

@multitable @columnfractions .3 .7
@item Size
@tab 512Kb (64 banks of 8Kb each)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (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
        -----------------------------------------------  ----------------
000000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
000010: 00 00 00 40 01 00 00 0F 00 01 00 00 00 00 00 00  ???@@????????????
000020: 43 36 34 47 53 20 43 61 72 74 72 69 64 67 65 00  C64GS?Cartridge?
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
000040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
000050: 6D 80 C5 80 C3 C2 CD 38 30 4C CB 80 4C 36 84 4C  m......80L..L6„L
@dots{}
002050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
002060: 18 D0 A9 FF 8D 15 D0 8D 1D D0 8D 17 D0 A2 07 A9  ?..??.?.?..?.
@dots{}
004060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP????????.???
004070: E0 08 19 21 77 84 52 98 9F 80 A5 21 31 01 31 89  ???!w„R˜Ÿ.¥!1?1‰
@dots{}
006070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP????????.???
006080: C0 08 1C 1D A0 92 03 03 D8 AA 04 C0 B8 01 40 EA  .??? .??.×?.??@@.
@dots{}
07E430: 43 48 49 50 00 00 20 10 00 00 00 3F 80 00 20 00  CHIP????????.???
07E440: 45 20 41 20 42 49 47 20 58 FE 4F 4E 20 54 48 49  E?A?BIG?X.ON?THI
@end example

    Here is a list of the known cartridges:

@example
    C64GS 4-in-1      (Commodore)  (512 kB)
    Last Ninja Remix  (System 3)   (512 kB)
    Myth              (System 3)   (512 kB)
@end example

    ROM memory is organized in 8Kb ($2000) banks  located  at  $8000-$9FFF.
    Bank switching is done by writing to address $DE00+X, where  X  is  the
    bank number (STA $DE00,X). For instance, to read from bank  3,  address
    $DE03 is written to. Reading from anywhere  in  the  I/O-1  range  will
    disable the cart.

    The CRT file contains a string of CHIP blocks, each block with a  start
    address of $8000, length $2000 and the bank number in the  bank  field.
    In the cartridge header, EXROM ($18) is set to 0, GAME ($19) is set  to
    1 to enable the 8 kB ROM configuration.


@c @node FIXME
@subsubsection 16 - Warp Speed

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 10 01 01 00 00 00 00 00 00  ???@@????????????
0020: 57 61 72 70 73 70 65 65 64 00 00 00 00 00 00 00  Warpspeed???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 4C 22 80 4C 22 80 FF 43 42 4D 20 53 E4 20 18 E5  L".L".?CBM?S????
@end example

    After  RESET  or  POWER  ON,  16kB  of  cartridge  ROM  is  visible  at
    $8000-$BFFF. Additionally,  ROM  normally  located  at  $9E00-$9FFF  is
    mirrored into I/O-1 and I/O-2 at $DE00-$DFFF.  ROM  at  $8000-$BFFF  is
    disabled by writing into the I/O-2 area (typically $DF00)  and  may  be
    re-enabled by writing into  I/O-1  ($DE00).  However,  the  $DE00-$DFFF
    (I/O-1/I/O-2) area itself always remains mapped to cartridge ROM.


@c @node FIXME
@subsubsection 17 - Dinamic

@multitable @columnfractions .3 .7
@item Size
@tab 128Kb (16 banks of 8Kb each)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (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
        -----------------------------------------------  ----------------
000000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
000010: 00 00 00 40 01 00 00 11 00 01 00 00 00 00 00 00  ???@@????????????
000020: 4E 61 72 63 6F 20 50 6F 6C 69 63 65 00 00 00 00  Narco?Police????
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
000040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
000050: 0B 80 0B 80 C3 C2 CD 38 30 00 00 78 A2 FF 9A D8  ?.?....80??x.?..
..
002050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
002060: 1C 8C 1B 8C 16 16 8F 16 16 88 1C 1C 86 1C 1C 89  ?Œ?Œ????ˆ??†??‰
..
004060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP????????.???
004070: B6 02 07 08 07 07 00 0A 0A B6 00 05 0A 00 07 07  ¶????????¶??????
..
01E130: 43 48 49 50 00 00 20 10 00 00 00 0F 80 00 20 00  CHIP????????.???
01E140: 00 D5 70 03 F5 70 0F 5F 70 0F F7 70 35 FD F0 37  ?.p??p?_p??p5.?7
@end example

    Here is a list of the known DINAMIC cartridges:

@example
    Narco Police  (128 kB)
    Satan         (128 kB)
@end example

    ROM memory is organized in 8Kb ($2000) banks  located  at  $8000-$9FFF.
    Bank switching is done by reading from address $DE00+X, where X is  the
    bank number (LDA $DE00,X). For instance, to read from bank  3,  address
    $DE03 is accessed.

    The CRT file contains a string of CHIP blocks, each block with a  start
    address of $8000, length $2000 and the bank number in the  bank  field.
    In the cartridge header, EXROM ($18) is set to 0, GAME ($19) is set  to
    1 to enable the 8 kB ROM configuration.


@c @node FIXME
@subsubsection 18 - Zaxxon, Super Zaxxon (SEGA)

@multitable @columnfractions .3 .7
@item Size
@tab 20Kb (3 banks of different sizes)
@item GAME
@tab active (1)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-8FFF (mirrored in $9000-9FFF, module 0, chip U1)
                    $A000-BFFF (banked modules 1 and 2, chip U2)
@end multitable

@example
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
        -----------------------------------------------  ----------------
000000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
000010: 00 00 00 40 01 00 00 12 00 00 00 00 00 00 00 00  ???@@????????????
000020: 5A 61 78 78 6F 6E 00 00 00 00 00 00 00 00 00 00  Zaxxon??????????
000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
000040: 43 48 49 50 00 00 10 10 00 00 00 00 80 00 10 00  CHIP????????.???
000050: 0D 80 29 80 C3 C2 CD 38 30 78 4C 09 80 78 A9 00  ?.)....80xL?.x.?
..
001050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP???????? ???
001060: A2 0F BD 00 20 D0 04 CA 10 F8 60 BD 70 20 F0 0D  .????.?.??`?p???
..
003060: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00  CHIP???????? ???
003070: 65 A2 36 A3 E7 A3 CB A4 94 A5 86 A6 5E A7 35 A8  e.6£?£.?”¥†?^§5?
@end example

    The (Super) Zaxxon carts use a 4Kb ($1000) ROM at $8000-$8FFF (mirrored
    in $9000-$9FFF) along with two 8Kb ($2000) cartridge banks  located  at
    $A000-$BFFF. One of the two banks is selected by doing a read access to
    either the $8000-$8FFF area (bank 0 is selected) or to $9000-$9FFF area
    (bank 1 is selected). EXROM ($18 = $00) and GAME ($19 = $00) lines  are
    always pulled to GND to select the 16 kB ROM configuration.

    The CRT file includes three CHIP blocks:
@example
    a) bank = 0, load address = $8000, size = $1000
    b) bank = 0, load address = $A000, size = $2000
    c) bank = 1, load address = $A000, size = $2000
@end example

@c @node FIXME
@subsubsection 19 - Magic Desk, Domark, HES Australia

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb, 64Kb or 128Kb sizes (4 to 16 banks of 8Kb each)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (1)
@item Load address 
@tab (banks 00-15) - $8000-9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 13 00 01 00 00 00 00 00 00  ???@@????????????
0020: 4D 61 67 69 63 20 44 65 73 6B 00 00 00 00 00 00  Magic?Desk??????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 C6 CA C3 C2 CD 38 30 8E 16 D0 20 A3 FD 20  ?......80Ž?.?£.?
..
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 00 3F 0A 01 00 86 4E 24 28 31 30 29 3A 4A 4F 59  ?????†N$(10):JOY
..
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP????????.???
4070: 00 8B C9 28 4E 24 2C 31 29 B3 B1 22 FF 22 A7 32  ?‹.(N$,1)³±"?"§2
..
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP????????.???
6080: AE 01 83 33 2C 37 2C 22 32 29 20 44 45 4C 20 4B  ®?ƒ3,7,"2)?DEL?K
@end example

    This cartridge type is very similar to the OCEAN cart type: ROM  memory
    is  organized  in  8Kb  ($2000)  banks  located  at  $8000-$9FFF.  Bank
    switching is done by writing the bank number to $DE00. Deviant from the
    Ocean type, bit 8 is cleared for selecting one of the ROM banks. If bit
    8 is set ($DE00 = $80), the GAME/EXROM lines are disabled,  turning  on
    RAM at $8000-$9FFF instead of ROM.

    In the cartridge header, EXROM ($18) is set to 0, GAME ($19) is set  to
    1 to indicate the RESET/power-up configuration of 8 kB ROM.

    Here is a list of the known cartridges:

@example
    Ghosbusters        (HES Australia)   (32 kB)
    Magic Desk         (Commodore)       (32 kB)
    Badlands           (Domark)          (64 kB)
    Vindicators        (Domark)          (64 kB)
    Wonderboy          (HES Australia)   (64 kB)
    Cyberball          (Domark)         (128 kB)
@end example


@c @node FIXME
@subsubsection 20 - Super Snapshot V5

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb each)
@item GAME
@tab active (1)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 14 01 01 00 00 00 00 00 00  ???@@????????????
0020: 53 75 70 65 72 20 53 6E 61 70 73 68 6F 74 20 35  Super?Snapshot?5
0030: 20 4E 54 53 43 00 00 00 00 00 00 00 00 00 00 00  ?NTSC???????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 09 80 59 80 C3 C2 CD 38 30 20 03 9F 00 FA F4 20  ?.Y....80??Ÿ????
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00  CHIP??@@?????.?@@?
4060: 79 DE BC FE C3 C2 CD 38 30 A9 05 8D 20 D0 8D 21  y.?....80.??.!
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00  CHIP??@@?????.?@@?
8070: 50 DE BC FE C3 C2 CD 38 30 A9 0A 85 6A A9 0D 85  P.?....80.?…j.?…
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00  CHIP??@@?????.?@@?
C080: 50 DE BC FE C3 C2 CD 38 30 85 07 20 1A AD A5 76  P.?....80…???­¥v
@end example

    The first page of the currently selected ROM bank is  mirrored  in  the
    I/O-1 range when reading.

    The control Register is the I/O-1 range when writing:

@example
    bit  meaning
    ---  -------
    7-5  unused
    4    ROM/RAM bank bit 1
    3    ROM enable
    2    ROM/RAM bank bit 0
    1    RAM enable, EXROM
    0    release freeze, !GAME
@end example


@c @node FIXME
@subsubsection 21 - Comal-80

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb each)
@item GAME
@tab active (1)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 15 01 01 00 00 00 00 00 00  ???@@????????????
0020: 43 6F 6D 61 6C 20 38 30 00 00 00 00 00 00 00 00  Comal?80????????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 87 87 70 CF C3 C2 CD 38 30 4C AA CF 4C 70 CF 4C  ..p....80L×.Lp.L
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00  CHIP??@@?????.?@@?
4060: AA CF 70 CF C3 C2 CD 38 30 01 29 01 28 01 2C 04  ×.p....80?)?(?,?
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00  CHIP??@@?????.?@@?
8070: AA CF 70 CF C3 C2 CD 38 30 91 92 92 92 92 92 92  ×.p....80.......
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00  CHIP??@@?????.?@@?
C080: 7B C8 7E C8 C3 C2 CD 38 30 43 4F 4D 41 4C 80 93  ..~....80COMAL..
@end example


    The Comal-80 Cartridge uses $DE00 for bank  selection,  and  uses  16Kb
    banks ($4000) at $8000-$BFFF. There are 4 banks of ROM memory  and  are
    referenced by the following values:

@example
       $80 -> Bank 0
       $81 -> Bank 1
       $82 -> Bank 2
       $83 -> Bank 3
@end example


@c @node FIXME
@subsubsection 22 - Structured Basic

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb each)
@item GAME
@tab active (0)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-9FFF
@end multitable

    No sample data/file available.

    Any read/write access to $DE00 or $DE01 will  switch  in  bank  0.  Any
    read/write access to $DE02 will switch in bank 1. Any read/write access
    to $DE03 will switch off EXROM.


@c @node FIXME
@subsubsection 23 - Ross

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb or 32Kb sizes (1 or 2 banks of 16Kb each)
@item GAME
@tab active (1)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-BFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 17 00 00 00 00 00 00 00 00  ???@@????????????
0020: 52 6F 73 73 20 31 34 00 00 00 00 00 00 00 00 00  Ross?14?????????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 09 80 09 80 C3 C2 CD 38 30 A2 00 BD 20 80 4D 0E  ?.?....80.???.M?
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00  CHIP??@@?????.?@@?
4060: 3F 5A 4D 4D 50 4D 8D 25 3F 1A 1F 77 3F CD E0 3F  ?ZMMPM%???w?.??
@end example

    Any read access to $DE00 will switch in bank 1 (if cart is  32Kb).  Any
    read access to $DF00 will switch off EXROM and GAME.


@c @node FIXME
@subsubsection 24 - Dela EP64

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb to 72kb sizes (1 to 9 banks of 8Kb each,
                              or 1 bank of 8Kb and 1 or 2 banks
                              of 32Kb each)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (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 (8Kb) which  holds  the  base
    eprom with the base menu, and 2 27256 eproms of  which  8Kb  parts  are
    banked into the $8000-9FFF area.

    The bank selecting is done by writing to $DE00. The following bits  are
    used for bank decoding in $DE00 (0 being the LSB, 3 being the MSB).

@example
         Bit# 76543210
              xx10xx32
@end example

    Any bank value below 4 or above 11 switches in the base bank (bank 0).

    The bit values for each eprom bank are :

@example
    eprom bank 1 : xx00xx01
    eprom bank 2 : xx01xx01
    eprom bank 3 : xx10xx01
    eprom bank 4 : xx11xx01
    eprom bank 5 : xx00xx10
    eprom bank 6 : xx01xx10
    eprom bank 7 : xx10xx10
    eprom bank 8 : xx11xx10
@end example

    Setting bit 7 high will switch off EXROM.


@c @node FIXME
@subsubsection 25 - Dela EP7x8

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb to 64kb sizes (1 to 8 banks of 8Kb each)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (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 8Kb banks of which the first holds
    the base menu, the other eproms can be banked into the $8000-9FFF area.

    The bank selecting is done by writing to $DE00. Each low bit is used to
    bank in the respective eprom. If all bits are high then  the  EXROM  is
    switched off.

    The bit values for each eprom bank is:

@example
    eprom bank 1 : 11111110 ($FE) (base eprom)
    eprom bank 2 : 11111101 ($FD)
    eprom bank 3 : 11111011 ($FB)
    eprom bank 4 : 11110111 ($F7)
    eprom bank 5 : 11101111 ($EF)
    eprom bank 6 : 11011111 ($DF)
    eprom bank 7 : 10111111 ($BF)
    eprom bank 8 : 01111111 ($7F)

    EXROM off    : 11111111 ($FF)
@end example

@c @node FIXME
@subsubsection 26 - Dela EP256

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb to 262kb sizes (1 to 33 banks of 8Kb each)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (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 8Kb  banks  of  which  the  first
    holds the base menu, the other eproms can be banked into the $8000-9FFF
    area.

    The bank selecting is done by writing to $DE00.

    The values for the (extra) eprom banks are:

@example
    eprom banks  1- 8 : $38-3F
    eprom banks  9-16 : $28-2F
    eprom banks 17-24 : $18-1F
    eprom banks 25-32 : $08-0F
@end example

    Setting bit 7 high will switch off EXROM.


@c @node FIXME
@subsubsection 27 - Rex EP256

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb to 262kb sizes (1 bank of 8Kb and 1 to 8 banks of either
                               8Kb, 16Kb or 32Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (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  8Kb  eprom,  the
    other eprom sockets can handle 8Kb, 16Kb or 32Kb eproms, of  which  8kb
    can be banked into the $8000-9FFF area.

    The bank selecting is done by  writing  to  $DFA0.  Bits  2,  1  and  0
    determine which socket is used and bits 5 and 4 are used to  select  an
    8Kb piece of the eprom.

    The possible values for bits 5 and 4 for the (extra) eprom banks are:

@example
     8Kb        : 3, 2, 1, 0

    16Kb bank 0 : 2, 0
    16Kb bank 1 : 3, 1

    32Kb bank 0 : 0
    32Kb bank 1 : 1
    32Kb bank 2 : 2
    32Kb bank 3 : 3
@end example

    Reading from $DFC0 switches off the EXROM.
    Reading from $DFE0 switches on the EXROM.

@c @node FIXME
@subsubsection 28 - Mikro Assembler

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (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 32Kb (1 bank of 32Kb)
@item GAME
@tab active (1)
@item EXROM
@tab active (1)
@item Load address
@tab $0000-$7FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 1D 00 01 00 00 00 00 00 00  ???@@????????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 80 10 00 00 00 00 00 00 80 00  CHIP??.???????.?
0050: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF  ????????????????
@end example


    This cart has 32Kb of ROM, bank 0 is in the cart image but is  unused.
    The first 8Kb of the cart image is unused, the second 8Kb of the  cart
    image is mapped to $E000-$FFFF, the third 8Kb of  the  cart  image  is
    mapped to $8000-$9FFF and the fourth 8Kb of the cart image  is  mapped
    to $A000-$BFFF. An NMI can be triggered by the cart, if address  $0001
    is written to and the cartridge is enabled. The cart can  be  disabled
    by software, by clearing bit 4 when writing to $DF00-$DFFF.  Cart  ROM
    at $E000-$FFFF can be disabled by setting bit 5 to 0 when  writing  to
    $DF00-$DFFF. Cart ROM at $8000-$BFFF can be disabled by setting bit  6
    to 1 when  writing  to  $DF00-$DFFF.  Bit  7  of  a  byte  written  to
    $DF00-$DFFF can be read back from the cartridge  if  enabled  (like  a
    memory cell).

@c @node FIXME
@subsubsection 30 - Action Replay 4

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb (4 banks of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 1E 00 01 00 00 00 00 00 00  ???@@????????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: EA 78 48 A9 7F 8D 0D DD D0 0E 48 AD 0D DD 10 04  .xP.??..?P?.??
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 09 80 0C 80 C3 C2 CD 38 30 4C E9 80 4C 81 81 4C  ?.?....80L?.LL
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00  CHIP????????.???
4070: 09 80 0E 80 C3 C2 CD 38 30 A2 00 4C EF FC 20 BC  ?.?....80.?L?.??
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00  CHIP????????.???
6080: 09 80 0C 80 C3 C2 CD 38 30 4C 70 88 4C 3F 80 4C  ?.?....80LpˆL?.L
@end example

    The control register is the I/O-1 range:

@example
    bit  meaning
    ---  -------
    0    Eprom banking bit 0 (bank address 13)
    1    Controls the GAME line (0 sets GAME low, 1 sets GAME high)
    2    Freeze-end bit (disables the register and hides any rom bank)
    3    Controls the Exrom line (1 sets EXROM low, 0 sets EXROM high)
    4    Eprom banking bit 1 (bank address 14)
    5-7  Unused
@end example

    The first page of the currently banked ROM block can be  read  in  the
    I/O-2 range.

@c @node FIXME
@subsubsection 31 - Stardos

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 00 01 00 00 00 00 00 00  ???@@????????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: F9 80 B6 80 C3 C2 CD 38 30 FD 80 89 80 4C 0C 88  ?.¶....80..‰.L?ˆ
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00  CHIP????????????
2060: 85 56 20 0F BC A5 61 C9 88 90 03 20 D4 BA 20 CC  …V???¥a.ˆ??.÷?.
@end example

    This cart has 16Kb of ROM, of which the first  8Kb  is  mapped  in  at
    $8000-$9FFF and the second 8Kb is used as a  kernel  replacement.  The
    kernel replacement is achieved by a clip that needs  to  be  installed
    inside the C64.

    Reading from I/O-1 causes a capacitor to get charged with every  read,
    once the capacitor is charged enough it switches the cart on.

    Reading from I/O-2 causes a different capacitor to  get  charged  with
    every read, once the capacitor is charged enough it switched the  cart
    off.

@c @node FIXME
@subsubsection 32 - EasyFlash

@multitable @columnfractions .3 .7
@item Size
@tab 1024Kb (64 banks of 2 * 8Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (1)
@item Load address
@tab $8000-$9FFF (ROML), $A000-$BFFF or $E000-$FFFF (ROMH)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 20 00 01 00 00 00 00 00 00  ???@@????????????
0020: 45 61 73 79 46 6C 61 73 68 20 43 61 72 74 72 69  EasyFlash?Cartri
0030: 64 67 65 00 00 00 00 00 00 00 00 00 00 00 00 00  dge?????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
0050: 00 85 5E FE C3 C2 CD 38 30 93 0D 2B 2B 2B 20 45  ?…^....80.?+++?E
@end example


    EasyFlash is a 1 MByte Flash EPROM card with  multiple  configurations
    and banks possible, it also has 256 bytes of RAM which is mapped  into
    the I/O-2 range.

    There are two control registers, one at $DE00 and one at $DE02.

    The register at $DE00 does the following:

@example
    bit  meaning
    ---  -------
    7    LED control
    6-3  Unused
    2    Mode (0/1)
    1    Exrom line control
    0    Game line control
@end example

    The register at $DE02 controls which bank  is  mapped  into  ROMH  and
    ROML.

@c @node FIXME
@subsubsection 33 - EasyFlash Xbank

@multitable @columnfractions .3 .7
@item Size
@tab -
@item GAME
@tab -
@item EXROM
@tab -
@item Load address
@tab -
@end multitable

This CRT type is not actually related to a seperate hardware, it is used by some
EasyFlash related tools as a container format. Consequently VICE does (can) not
load files of this type.

@c @node FIXME
@subsubsection 34 - Capture

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $E000-$FFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 22 00 01 00 00 00 00 00 00  ???@@???"????????
0020: 4D 61 67 69 63 20 46 6F 72 6D 65 6C 00 00 00 00  Magic?Formel????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 01 E0 00 20 00  CHIP????????????
0050: 00 0A 0D 8A B4 A1 20 80 00 0A 82 8A 8D 20 9E 20  ???Š?.?.??‚Š?ž?
@end example


    This cart has 8Kb of ROM which is mapped to  $E000,  and  8Kb  of  RAM
    which is mapped to $6000. The cartridge is disabled after a reset.

    When the freeze button is pressed the following happens:

@itemize @bullet
@item an NMI is generated
@item as soon as the current adress is in bank 0xfe the cart  switches  to
      ultimax  mode.  The  cart  ROM  then  contains  one  page  full   of
      "jmp $eaea", which ultimately calls the freezer code.
@item the $FFF7/$FFF8 "register" logic is enabled and any access (read  or
      write) to $FFF7 will turn the cart_enabled off (leave ultimax mode),
      and an access to $FFF8 will turn the cart  back  on  (enter  ultimax
      mode). the "register logic" that causes this can  only  be  disabled
      again by a hardware reset.
@end itemize

@c @node FIXME
@subsubsection 35 - Action Replay 3

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 23 00 01 00 00 00 00 00 00  ???@@???#????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: EA A9 E3 48 A9 7B 48 08 4C 1A 80 EA EA EA 48 AD  ...H..H?L?....H
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 09 80 5E FE C3 C2 CD 38 30 78 A2 FB D8 9A A9 27  ?.^....80x.....'
@end example


    This cart has 16Kb of ROM of which 8Kb is mapped in at both  ROML  and
    ROMH. Bank switching and control register is done  through  the  I/O-1
    range:

@example
    bit  meaning
    ---  -------
    7-4  unused
    3    Exrom line control
    2    Disable cart
    1    Unused
    0    Bank
@end example

@c @node FIXME
@subsubsection 36 - Retro Replay

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb, 64Kb or 128Kb (4, 8 or 16 banks of 8Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 24 00 00 00 00 00 00 00 00  ???@@???$????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 0C 80 C3 C2 CD 38 30 4C 7F 81 4C 87 81 4C  ?.?....80L?L.L
@end example


    The Retro Replay has three registers: Two write-only ($DE00  &  $DE01)
    and one read-only register ($DE00 & $DE01 giving the same results).

    The register at $DE00 is reset to $00 on a hard reset if not in  flash
    mode. If in flash mode, it is set to  $02  in  order  to  prevent  the
    computer from starting the normal cartridge. Flash  mode  is  selected
    with a jumper.

    Register at $DE00:

@example
    bit  meaning
    ---  -------
    0    Controls the GAME line: A 1 asserts the line, a 0  will  deassert
         it.
    1    Controls the EXROM line: A 0 will assert it, a  1  will  deassert
         it.
    2    Writing a 1 will disable further write accesses to all  registers
         of the Retro Replay, and  set  the  memory  map  of  the  C64  to
         standard, as if there is no cartridge installed at all.
    3    Controls bank-address 13 for ROM and RAM banking.
    4    Controls bank-address 14 for ROM and RAM banking.
    5    Switches between ROM and RAM: 0=ROM, 1=RAM
    6    Must be written once to "1" after a successful freeze in order to
         set the correct memory map and  enable  bits  0  and  1  of  this
         register. Otherwise no effect.
    7    Controls bank-address 15 for ROM banking.
@end example

    The register at $DE01 is the extended  control  register.  If  not  in
    Flash mode, bits 1, 2 and 6 can only be  written  once.  If  in  Flash
    mode, the REUcomp bit cannot be set, but  the  register  will  not  be
    disabled by the first write. Bit 5 is always set to 0 if not in  Flash
    mode.

    Register at $DE01:

@example
    bit  meaning
    ---  -------
    0    Enable clockport connector.
    1    AllowBank (1 allows banking of RAM in $DF00/$DE02 area)
    2    NoFreeze (1 disables Freeze function)
    3    Bank-address 13 for RAM and ROM (mirror of $DE00)
    4    Bank-address 14 for RAM and ROM (mirror of $DE00)
    5    Bank-address 16 for ROM (only in flash mode)
    6    REU compatibility bit. 0=standard memory map, 1 = REU  compatible
         memory map
    7    Bank-address 15 for ROM (mirror of $DE00)
@end example

    Reading from the registers at either $DE00 or $DE01  will  return  the
    content of the status register.

    Status register:

@example
    bit  meaning
    ---  -------
    0    1=Flashmode active (jumper set)
    1    feedback of AllowBank bit
    2    1=Freeze button pressed
    3    feedback of banking bit 13
    4    feedback of banking bit 14
    5    feedback of banking bit 16
    6    1=REU compatible memory map active
    7    feedback of banking bit 15
@end example

    The following memory maps are available:

@itemize @bullet
@item standard - 
    $DE00 and $DE01 registers are active,  $DF00-$DFFF  contain  the  last
    page of the selected 8Kb bank  of  either  ROM  or  RAM,  whatever  is
    selected. RAM can only be accessed in $8000-$9FFF. ROM can  be  mapped
    to $8000, $A000 or $E000 with the corresponding  status  on  GAME  and
    EXROM.

    Note: If the AllowBank bit is  not  set,  the  $DF00-$DFFF  area  will
    always access bank 0 of the RAM, so the older  cartridge  images  will
    work. The AllowBank bit does not have any effect on the ROM mirror  in
    that area.

@item Freeze -
    ROM is mapped to $E000-$FFFF, bank 0 is active directly after  Freeze.
    Writing to bits 0 and 1 of the $DE00 register will have no  effect  on
    GAME and EXROM. RAM can be  selected  and  used  in  $DF00  or  $DE02,
    respectively, but not in $8000. Banking bits work, so  you  have  full
    read access to the ROM, and access to up to four RAM  pages  with  the
    AllowBank bit set (minus 2 bytes if REU compatible bit  is  set).  You
    should leave this memory map ASAP by setting bit 6 of  $DE00,  because
    C64 RAM in the $E000 area is not available, and you don't have control
    of the GAME and EXROM lines.

@item REU compatible -
    $DE00 and $DE01 registers are active, $DE02-$DEFF contain a mirror  of
    $9E02-$9EFF of the selected 8K-bank of either ROM or RAM, whatever  is
    selected. RAM can only be accessed in $8000-$9FFF. ROM can  be  mapped
    to $8000, $A000 or $E000 with the corresponding  status  on  GAME  and
    EXROM. The $DF00 stays free for use with the 1764 Ram  Expansion  Unit
    (REU).

    Note: If the AllowBank bit is  not  set,  the  $DE02-$DEFF  area  will
    always access bank 0 of the RAM, so the older  cartridge  images  will
    work. The AllowBank bit does not have any effect on the ROM mirror  in
    that area.
@end itemize

@c @node FIXME
@subsubsection 37 - MMC64

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 25 00 01 00 00 00 00 00 00  ???@@???%????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 64 97 C3 C2 CD 38 30 78 D8 A2 FF 9A 20 D4  ?.d—...80x..?.?.
@end example


    The clockport registers  of  this  cart  can  be  switched  to  either
    $DE01-$DE0F or $DF21-$DF2F. The control  registers  are  available  at
    $DF10-$DF13.

    The register at $DE01 / $DF21 is write only:

@example
    bit  meaning
    ---  -------
    7-1  Unused
    0    0 = disable clock port, 1 = enable clockport
@end example

    The registers at $DE02-$DE0F / $DF22-$DF2F are for the clock port  and
    are read/write.

    The register at $DF10 is the  MMC64  SPI  transfer  register,  a  byte
    written to this registers is sent to the card & response from the card
    is read here.

    The register at $DF11 is the MMC64 control register:

@example
    bit  meaning
    ---  -------
    0    0 = MMC64 BIOS active, 1 = external ROM active
    1    0 = card selected, 1 = card not selected
    2    0 = 250khz transfer, 1 = 8mhz transfer
    3    0 = clock port @@ $DE00, 1 = clock port @@ $DF20
    4    0 = normal Operation, 1 = flash mode (*)
    5    0 = allow external rom when BIOS is disabled,
         1 = disable external ROM
    6    0 = SPI write trigger mode, 1 = SPI read trigger mode
    7    0 = MMC64 is active, 1 = MMC64 is completely disabled (**)
@end example

    (*) bit can only be programmed when flash jumper is set
    (**) bit can only be modified after unlocking

    The  register  at  $DF12  is  the  MMC64  status  register,  which  is
    read-only:

@example
    bit  meaning
    ---  -------
    0    0 = SPI ready, 1 = SPI busy
    1    external GAME line
    2    external EXROM line
    3    0 = card inserted, 1 = no card inserted
    4    0 = card write enabled, 1 = card write disabled
    5    0 = flash jumper not set, 1 = flash jumper set
    6-7  unused
@end example

    The register at $DF13 is the MMC64 identification register, which when
    reading from it can have the following values:

    $64 when bit 1 of $DF11 is 0.
    $01 when bit 1 of $DF11 is 1 and REV A hardware is used.
    $02 when bit 1 of $DF11 is 1 and REV B hardware is used.

    when writing to it it can be used to unlock  bit  7  of  $DF11  or  to
    re-enable the cart:

    Write $55 & $AA into this register to unlock bit 7 of $DF11.
    Write $0A & $1C into this register to re-enable MMC64 hardware.

@c @node FIXME
@subsubsection 38 - MMC Replay

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb or 512Kb (8 or 64 banks of 8Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 26 00 00 00 00 00 00 00 00  ???@@???&????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 1A 80 6E 9E C3 C2 CD 38 30 4D 4D 43 52 45 50 4C  ?.nž...80MMCREPL
@end example


    The cart uses the following registers:

    $DE00 - RR control register write

@example
    bit  meaning
    ---  -------
    0    GAME line
    1    EXROM line
    2    1 = disable RR, bit can be reset by setting bit 6 of $DF12
    3    bank address 13
    4    bank address 14
    5    0 = rom enable, 1 = ram enable
    6    1 = exit freeze mode
    7    bank address 15
@end example

    $DE01 - extended RR control register write

@example
    bit  meaning
    ---  -------
    0    0 = disable clockport, 1 = enable clockport
    1    0 = disable I/O RAM banking, 1 = enable I/O RAM banking
    2    0 = enable freeze, 1 = disable freeze
    3    bank address 13 (mirror of $DE00)
    4    bank address 14 (mirror of $DE00)
    5    0 = enable MMC registers, 1 = disable MMC registers. Can only  be
         written when bit 6 of $DF12 is 1. Register becomes effective when
         bit 0 of $DF11 is 1.
    6    0 = RAM/ROM at $DFxx, 1 = RAM/ROM at $DExx
    7    bank address 15 (mirror of $DE00)
@end example

    $DE02-$DE0F - Clockport memory area (when enabled)

    $DF10 - MMC SPI transfer register, a byte written is sent to the  card
            & response from the card is read here.

    $DF11 - MMC control register

@example
    bit  meaning
    ---  -------
    0    0 = MMC BIOS enabled, 1 = MMC BIOS disabled.  Enabling  MMC  BIOS
         sets ROM banking to the last 64Kb bank.
    1    0 = card selected, 1 = card not selected. This bit also  controls
         the green activity LED.
    2    0 = 250khz transfer, 1 = 8mhz transfer
    3    ALWAYS 0
    4    ALWAYS 0
    5    (in RR-Mode:)
          0 = allow RR rom when MMC BIOS disabled , 1 = disable RR ROM
          (in mmcreplay bios mode:)
          RAM banking (0 = $E000 - $FFFF, 1 = $8000 - $9FFF)
          (in 16K mode:)
          enable RAM at $A000 - $BFFF
    6    0 = SPI write trigger mode, 1 = SPI read trigger mode
    7    ALWAYS 0
@end example

    $DF12 - MMC status register

@example
    bit  meaning
    ---  -------
    0    0 = SPI ready, 1 = SPI busy (read)
                        1 = forbid ROM  write  accesses  (write).  Setting
                        this bit will disable writes  to  ROM  until  next
                        reset
    1  feedback of $DE00 bit 0 (GAME)
    2  feedback of $DE00 bit 1 (EXROM)
    3  0 = card inserted, 1 = no card inserted
    4  0 = card write enabled, 1 = card write disabled
    5  EEPROM DATA line /  DDR  register.  Setting  DATA  to  "1"  enables
       reading data bit from EEPROM at this position.
    6  0 = RR compatibility mode, 1 = Extended mode
       Selecting RR compatibility mode limits RAM  to  32Kb  and  disables
       writes  to  extended  banking  register.  Selecting  Extended  mode
       enables full RAM banking and enables Nordic Power mode in RR mode.
    7  EEPROM CLK line
@end example


    $DF13 - Extended banking register
            Can only be read/written to when bit 6 of $DF12 is 1

@example
    bit  meaning
    ---  -------
    0    bank address 16
    1    bank address 17
    2    bank address 18
    3    ALWAYS 0
    4    ALWAYS 0
    5    16K rom mapping
    6    1 = enable  RR  register.  Disabling  RR  register  disables  ALL
         ROM/RAM banking too.
    7    ALWAYS 0
@end example

@c @node FIXME
@subsubsection 39 - IDE64

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb or 128Kb (8 or 16 banks of 8Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-$9FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 26 00 00 00 00 00 00 00 00  ???@@???'????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 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 - $DE27  Primary HDD Registers
    $DE28 - $DE2F  Secondary HDD 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
    $DE33 - $DE35 = IDE64 ROM bank select registers
    $DE5F         = RTC access (bit 0 only to serial accessed RTC)
    $DE60 - $DEFA = RAM used by software
    $DEFB         = IDE64 clock reset, kill the cartridge
    $DEFC - $DEFF = IDE64 ROM configuration registers
@end example

@c @node FIXME
@subsubsection 40 - Super Snapshot V4

@multitable @columnfractions .3 .7
@item Size
@tab 32Kb (4 banks of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 28 00 01 00 00 00 00 00 00  ???@@???(????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 80 AD B5 80 C3 C2 CD 38 30 08 48 A9 06 8D 00 DF  .µ....80?P.???
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP???????? ???
2060: 4C FA A0 A9 07 8D 00 DD 2C 00 DD 50 FB 2C 00 DD  L? .??.,?.P.,?.
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
4070: 13 80 BC FE C3 C2 CD 38 30 08 48 A9 02 8D 00 DF  ?.?....80?H.???
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00  CHIP???????? ???
6080: F0 8A 48 A9 00 85 22 85 23 8D 53 0F 20 0C A1 B0  ?ŠH.?…"…#S???.°
@end example


    This cart has 32Kb of ROM and 8Kb of RAM, it uses I/O-1 as a mirror of
    the last page of cart RAM. It has the following registers in the I/O-2
    range:

    ROM config register at $DF00 (can only be written to):

@example
    bit  meaning
    ---  -------
    0    ?
    1    ? (write 1 to release freeze mode)
    2    ROM bank select
    3    write 1 to disable cartridge
    4-6  unused
    7    ?
@end example

    Note: if bit0, bit1, bit7 are all 0, then ultimax mapping is  selected
    and RAM is enabled at ROML, otherwise if bit 0 is 0, then 16Kb mapping
    is enabled, or if bit 0 is 1, then 8Kb mapping is enabled.

    RAM config register at $DF01 (read/write):

    If written value == last value - 1, then ultimax mapping  is  selected
    and RAM is enabled at ROML, if written value == last value +  1,  then
    ROM is enabled at ROML and exrom is deasserted (switch to either 8k or
    16k mapping)

    $DF02-$DFFF holds the last page of the first 8kb of the current bank.

@c @node FIXME
@subsubsection 41 - IEEE-488

@multitable @columnfractions .3 .7
@item Size
@tab 4Kb (1 bank of 4Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-$8FFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 29 00 01 00 00 00 00 00 00  ???@@???)????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 10 10 00 00 00 00 80 00 10 00  CHIP????????.???
0050: 09 80 7A 80 C3 C2 CD 38 30 8E 16 D0 20 84 FF 20  ?.z....80Ž?.?„??
@end example


    The cart uses a TPI for the  IEEE488  interface/communication  in  the
    I/O-2 range:

@example
    $DF00 - Port A Data
    $DF01 - Port B Data
    $DF02 - Port C Data
    $DF03 - Port A Direction
    $DF04 - Port B Direction
    $DF05 - Port C Direction
    $DF06 - Control register
    $DF07 - Active Interrupt register
@end example

@c @node FIXME
@subsubsection 42 - Game Killer

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $E000-$FFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 2A 00 00 00 00 00 00 00 00  ???@@???*????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00  CHIP????????????
0050: 00 25 08 CF 07 9E 32 30 38 38 20 4D 43 2E 43 52  ?%?.?ž2088?MC.CR
@end example


    When the cartridge is active, ultimax  is  enabled  when  the  address
    being accessed is is the $E000-$FFFF range, so the ROM is  visible  at
    $E000, below is normal C64 RAM. The cart can be disabled by writing to
    either I/O-1 or I/O-2 range. When the freezer button is  pressed,  the
    cartridge will be enabled and an NMI will be triggered.

@c @node FIXME
@subsubsection 43 - Prophet64

@multitable @columnfractions .3 .7
@item Size
@tab 256Kb (32 banks of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 2B 00 01 00 00 00 00 00 00  ???@@???+????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 09 80 C3 C2 CD 38 30 78 A0 00 84 F8 84 FA  ?.?....80x ?„?„?
@end example


    The control register is the I/O-2 range:

@example
    bit  meaning
    ---  -------
    7-6  unused
    5    disable cart
    4-0  bank select
@end example

@c @node FIXME
@subsubsection 44 - EXOS

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab active (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 2C 01 00 00 00 00 00 00 00  ???@@???,????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00  CHIP????????????
0050: 85 56 20 0F BC A5 61 C9 88 90 03 20 D4 BA 20 CC  …V???¥a.ˆ??.÷?.
@end example


    This cart has 8Kb of ROM, mapped in at $E000-$FFFF only when hirom  is
    selected. The cart uses a clip that needs to be installed  inside  the
    C64.

@c @node FIXME
@subsubsection 45 - Freeze Frame

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 2D 00 01 00 00 00 00 00 00  ???@@???-????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 10 80 10 80 C3 C2 CD 38 30 20 00 00 00 00 00 00  ?.?....80???????
@end example


    When reading from the I/O-1 range the cart is  enabled,  when  reading
    from the I/O-2 range the cart is disabled. When the freeze  button  is
    pressed the ROM is mapped to both $8000-$9FFF and $E000-$FFFF.

@c @node FIXME
@subsubsection 46 - Freeze Machine

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb or 32Kb (2 or 4 banks of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 2E 00 01 00 00 00 00 00 00  ???@@???.????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 3A 83 60 80 C3 C2 CD 38 30 20 00 00 40 00 00 00  :ƒ`....80???@@???
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP???????? ???
2060: 78 A9 34 85 01 A0 00 B1 F8 91 F6 E6 F8 D0 02 E6  x.4…? ?±?.?µ?.?µ
@dots{}
4060: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
4070: 3A 83 60 80 C3 C2 CD 38 30 20 00 00 40 00 00 00  :ƒ`....80???@@???
@dots{}
6070: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00  CHIP???????? ???
6080: 78 A9 34 85 01 A0 00 B1 F8 91 F6 E6 F8 D0 02 E6  x.4…? ?±?.?µ?.?µ
@end example


    Warning, the following information is based on guess-work and might be
    incorrect, any further information and/or corrections are appreciated.

    When reading from  the  I/O-1  range  ROM  bank  0(/2)  is  mapped  to
    $8000-$9FFF and ROM bank 1(/3) is mapped to $A000-$BFFF. When  reading
    from the I/O-2 range the cart is disabled. When a  reset  happens  the
    ROM banks get switched and ROM bank 0(/2) is  mapped  to  $8000-$9FFF.
    When a freeze happens ROM bank 0(/2) is mapped to both $8000-$9FFF and
    $E000-$FFFF.


@c @node FIXME
@subsubsection 47 - Snapshot 64

@multitable @columnfractions .3 .7
@item Size
@tab 4Kb (1 bank of 4Kb)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $E000-$EFFF
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 2F 00 00 00 00 00 00 00 00  ???@@???/????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 10 10 00 00 00 00 E0 00 10 00  CHIP????????????
0050: 78 D8 48 8A 48 98 48 AC 0D DD 10 03 4C EE F2 AD  x.HŠH˜H??.??L??
@end example


    Warning, the following information is based on guess-work and might be
    incorrect, any further information and/or corrections are appreciated.

    The cart has a control bit (bit 0) in the I/O-2 range which is used to
    disable or enable the cart.


@c @node FIXME
@subsubsection 48 - Super Explode V5.0

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 30 00 01 00 00 00 00 00 00  ???@@???0????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: D7 86 5E FE C3 C2 CD 38 30 A9 00 2C A9 FF 85 FE  .†^....80.?,.?….
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: E8 96 5E FE C3 C2 CD 38 30 20 6C 81 A9 09 8D 99  ?–^....80?l.?™
@end example


    Warning, the following information is based on guess-work and might be
    incorrect, any further information and/or corrections are appreciated.

    The cart has 16Kb of ROM which are used as two banks of 8Kb, they  are
    mapped into $8000-$9FFF and the last page of the current ROM  bank  is
    mirrored in $DF00-$DFFF. The cart has a control bit (bit 7) at  $DF00,
    which is used to select what ROM bank is used.


@c @node FIXME
@subsubsection 49 - Magic Voice

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-$9FFF (bank 1),
                   $A000-$BFFF (bank 2)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 31 00 01 00 00 00 00 00 00  ???@@???1????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: EA 2C 80 DF 50 FB A0 00 8C 80 DF B9 E3 A3 29 0F  .,.?P. ?Œ.?¹.£)?
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00  CHIP???????? ???
2060: 4A EB C0 49 6A EA BB FB 4E CA 43 1E 75 63 15 97  J?.Ij.».N.C?uc?—
@end example


    This cart has 16Kb of ROM, mapped in at reset at $8000-$BFFF. The cart
    is controled through a TPI at $DF80-$DF87:

@example
    $DF80 - Port A Data
    $DF81 - Port B Data
    $DF82 - Port C Data
    $DF83 - Port A Direction
    $DF84 - Port B Direction
    $DF85 - Port C Direction
    $DF86 - Control register
    $DF87 - Active Interrupt register
@end example

    The cart has a pass-through port and does the following at start-up:

@itemize @bullet
@item Program  starts  after  reset  at  $FFD3,  and  copies   code   from
      $FF36-$FFD2 to $0200-$029C (157 bytes)

@item Program continues at $021A, copies $A000-$BFFF from EPROM to RAM  at
      $A000-$BFFF  (8Kb),  copies  $E000-$FFFF  from  EPROM  to   RAM   at
      $E000-$FFFF (8Kb), copies $AE62-$B461 from RAM to RAM at $C000-$C5FF
      (Magic Voice Code)

@item Jump to beginning of Magic Voice code at $C000
@end itemize

@c @node FIXME
@subsubsection 50 - Action Replay 2

@multitable @columnfractions .3 .7
@item Size
@tab 16Kb (2 banks of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 32 00 01 00 00 00 00 00 00  ???@@???2????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: EA EA 68 AA 68 85 94 68 85 95 68 85 96 68 85 97  ..h×h…”h…•h…–h…—
@dots{}
2050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00  CHIP????????.???
2060: 30 80 5E FE C3 C2 CD 38 30 20 04 90 4C 38 DF 1A  0.^....80??L8??
@end example


    Warning, the following information is based on guess-work and might be
    incorrect, any further information and/or corrections are appreciated.

    I/O-1 is somehow used to enable the cart, the exact way in which  this
    is done is unknown. Reading from the I/O-2 range  will  give  you  the
    last page of the current ROM bank, and writing to it will disable  the
    cart.

@c @node FIXME
@subsubsection 51 - MACH 5

@multitable @columnfractions .3 .7
@item Size
@tab 4Kb or 8Kb (1 bank of 4Kb or 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-$8FFF (4Kb),
                   $8000-$9FFF (8Kb)
@end multitable

@example
      00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       ASCII
      -----------------------------------------------  ----------------
0000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20  C64?CARTRIDGE???
0010: 00 00 00 40 01 00 00 33 00 01 00 00 00 00 00 00  ???@@???3????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: AF 83 5E FE C3 C2 CD 38 30 4D 41 43 48 35 A5 93  »ƒ^....80MACH5¥.
@end example


    This cart has 8Kb ROM mapped at $8000-$9FFF, the $9E00-$9EFF range  is
    mirrored at $DE00-$DEFF and  the  $9F00-$9FFF  range  is  mirrored  at
    $DF00-$DFFF.


@c @node FIXME
@subsubsection 52 - Diashow maker

@multitable @columnfractions .3 .7
@item Size
@tab 8Kb (1 bank of 8Kb)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (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 34 00 01 00 00 00 00 00 00  ???@@???4????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00  CHIP????????.???
0050: 09 80 09 80 C3 C2 CD 38 30 AD 11 D0 29 10 D0 62  ?.?....80?.)?.b
@end example


    Accessing I/O-1 (the software  uses  $DE00  only  it  seems)  disables
    cartridge ROM. A reset enables 8K game mode and the ROM bank is mapped
    to $8000. A freeze causes ROM to be mapped to $8000.


@c @node FIXME
@subsubsection 53 - Pagefox

@multitable @columnfractions .3 .7
@item Size
@tab 64Kb (4 banks of 16Kb)
@item GAME
@tab active (1)
@item EXROM
@tab active (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 35 01 01 00 00 00 00 00 00  ???@@???5????????
0020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00  VICE?CART???????
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ????????????????
0040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00  CHIP??@@?????.?@@?
0050: 31 80 BB 0E C3 C2 CD 38 30 50 46 20 56 31 2E 30  1.»?...80PF?V1.0
@dots{}
4050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00  CHIP??@@?????.?@@?
4060: A2 FE 9A 20 EC AE 20 82 80 20 74 86 20 A5 8B 4C  ...??®?‚.?t†?¥‹L
@dots{}
8060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00  CHIP??@@?????.?@@?
8070: 5A 01 02 03 04 06 0A 0B 10 14 1E 28 3C 00 00 00  Z??????????(<???
@dots{}
C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00  CHIP??@@?????.?@@?
C080: 1E 03 14 82 09 05 09 0F 0C 0D 0F 05 09 09 0B 0A  ???‚????????????
@end example


    This cart has 64Kb ROM (2 32Kb Eproms, mapped to $8000  and  $A000  in
    16Kb Game Mode), and 32Kb RAM (mapped to $8000 and $A000 in  16K  Game
    Mode). The cart has 1 (write-only)  bank  control  register  which  is
    located at $DE80 and mirrored throughout the $DE80-$DEFF range:

@example
    Bit 0: unused/don't care
    Bit 1: Bank select: 0=upper, 1=lower (not correct ?!)
    Bit 2: chip select 0
    Bit 3: chip select 1
    Bit 4: cartridge enable/disable: 0=enable, 1=disable
    Bits 5-7: unused/don't care
@end example

    Chip select combinations of 0/1 are:
@example
    00: Eprom "79"
    01: Eprom "ZS3"
    10: Ram
    11: empty space (reading returns VIC-II data)
@end example

    note: on the original hardware "disabling" the  cartridge  by  setting
          bit 4 of the control register does NOT prevent write accesses to
          the cartridge RAM!. So  to  actually  disable  the  RAM,  it  is
          suggested to write $FF to the register.

@c @node FIXME
@subsubsection 54 - Kingsoft

@c FIXME: todo

@multitable @columnfractions .3 .7
@item Size
@tab -
@item GAME
@tab -
@item EXROM
@tab -
@item Load address
@tab -
@end multitable

@c @node FIXME
@subsubsection 55 - Silverrock 128

@c FIXME: todo

@multitable @columnfractions .3 .7
@item Size
@tab 128k (16 banks of 8k)
@item GAME
@tab active (1)
@item EXROM
@tab inactive (0)
@item Load address
@tab $8000-$9FFF
@end multitable

@c @node FIXME
@subsubsection 56 - Formel 64

@c FIXME: todo

@multitable @columnfractions .3 .7
@item Size
@tab 32kb (4 banks of 8k)
@item GAME
@tab inactive (0)
@item EXROM
@tab inactive (0)
@item Load address
@tab $E000-$FFFF
@end multitable

@node Acknowledgments, Copyright, File formats, Top
@chapter Acknowledgments

VICE derives from X64, the first Commodore 64 emulator for the
X Window System. Here is an informal list of the people who were
mostly involved in the development of X64 and VICE:

The VICE core team:
@itemize @bullet
@c The Texinfo manual says we should not use @b though!

@item
@b{Dag Lem}
Implemented the reSID SID emulation engine and video hardware
scaling.

@item
@b{Andreas Matthies}
Improved the datasette support, the VIC20 video emulation and
some UI stuff in the Win32 and DOS ports. He also wrote the
BeOS port and implemented video/audio capture support. Improved
history recording/playback and implemented support for video
recording and the netlink feature. Made the Win32 user
changable keyboard shortcut system. Improved CIA and VIA
emulation. Worked on x64sc, especially interrupt timing. Wrote
test programs. Various bug(fixe)s. ;-)

@item
@b{Martin Pottendorfer}
Implemented the Gnome Port based on Oliver Schaertels GTK+
port. Added support code for internationalization based on
gettext. Improved the *nix fullscreen support. Translated the
UI to German. Implemented the fliplists + UI (*nix).

@item
@b{Marco van den Heuvel}
Translated the UI to Dutch. Made the internationalization
support for the Win32 and Amiga ports. Wrote the GEO-RAM and
RamCart cartridge code. Wrote the c64 +60K, +256K and 256K
memory expansions code. Wrote the pet REU code. Wrote the plus4
memory expansions code. Made the ethernet support for the DOS
port. Maintains the QNX 4.x, QNX 6.x, Solaris, Openserver,
Unixware, Minix 3.x, Amiga, Syllable and OS/2 binary ports.
Maintains the Win64 and Open Watcom project files. Maintains
the SDL port(s). Added new .crt support. Added new screenshot
formats. Added new sound recording support. Added SIDcart
support for xpet, xplus4 and xvic. Improved the MMC64
emulation. Added 2 MHz mode and banks 2/3 support for x128.
Added the various userport joystick emulations. Added text copy
and paste support to the Amiga and BeOS ports. Added DQBB and
ISEPIC cartridge support. Added SFX Sound Sampler and SFX Sound
Expander support. Added PCI support to the Amiga and DOS ports.
Rewrote the sound system into a modular one, added always mono
and always stereo support for the sound output. Added the RTC
system. Added digiblaster support. Added 3rd SID support. Added
the 6309 CPU emulation. Added the 65(S)C02 emulation. And
lots of other fixes and improvements.

@item
@b{Christian Vogelgsang}
Maintains 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{Fabrizio Gennari}
Added some improvements to the DOS and GTK+ ports. Changed the
Windows video to use GDI as fallback, making it compile without
DX if needed. Fixed the t64 support. Added monitor window support
using VTE to the GTK+ GUI.

@item
@b{Daniel Kahlin}
Worked on DTV VIC emulation, palette, DTV SID support in resid,
better DMA/Blitter support and did lots of refactoring. Added
new monitor commands and features. Improved the VIC emulation
for xvic. Made MIDI driver code for Win32. Rewrote the xvic
cartridge system. Added Mega-Cart and Final Expansion V3.2
support to xvic. Wrote large parts of the new VIC-II emulation
used in x64sc, especially the dot clock domain emulation. Wrote
many test programs for hardware analysis.

@item
@b{Antti S. Lankila}
Made the ReSID-fp engine, rewrote the PAL emulation code and
fixed the sound core for lower latency. Rewrote DTV SID support
(ReSID-dtv). Improved 1541 drive rotation emulation. Worked on
x64sc.

@item
@b{Groepaz}
Added new more precise CRT emulation. Added support for the new
cartridge system and many new cartridges. Fixed up parts of
cartconv, c1541 and petcat. Added video to audio leak sound support.
Implemented many bug fixes. 
Wrote test programs. Updated this document after a long period
of outdated mess.

@item
@b{Ingo Korb}
Corrected block allocation and interleave for c1541/vdrive,
added rudimentary xplus4 tape recording support, corrected a
case of missing Pi symbols in petcat, changed the trap opcode
byte, stopped the high-level serial drive code from responding
to addresses 16-30 and was forced to update this entry himself.

@item
@b{Errol Smith}
Improved VDC emulation.

@item
@b{Olaf Seibert}
Contributed some PET, including PET DWW hires, Xaw, lightpen,
hardware scaling, and disk drive patches. Added proper SuperPET
support, including 6809/6309 CPU emulation. Maintains the Xaw UI.

@item
@b{Stefan Haubenthal}
Added some Amiga fixes.

@item
@b{Thomas Giesel}
Added new monitor commands, features and improvements.

@item
@b{Marcus Sutton}
Made some console, dialog and joystick fixes for the BeOS port.
Maintains the BeOS port.

@item
@b{Ulrich Schulz}
Maintains the Dingoo port(s).

@item
@b{Kajtar Zsolt}
Wrote the IDE64 interface emulation, FD2000/4000 drive emulation, SCPU64
emulation and alot of fixes. Improved the mouse support. Added drive
burst modification support. Added 1541 drive sounds emulation. Improved
c64 cart emulation.

@end itemize

Former/inactive team members:

@itemize @bullet

@item
@b{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
@b{Mikkel Holm Olsen}
Provided the Danish user interface translations and fixed a few
monitor bugs.

@b{Manuel Antonio Rodriguez Bas}
Provided the Spanish user interface translations.

@b{Paul Dubé}
From Rivière-du-Loup, Québec, provided the French user
interface translations.

@b{Czirkos Zoltan} and @b{Karai Csaba}
Provided the Hungarian user interface translations.

@b{Andrea Musuruane}
Provided the Italian user interface translations.

@b{Jesse Lee}
Provided the Korean user interface translations.

@b{Jarek Sobolewski}
Provided the new Polish user interface translations.

@b{Michael Litvinov}
Provided the Russian user interface translations.

@b{Peter Krefting}
Provided the Swedish user interface translations.

@b{Emir Akaydin}
Provided the Turkish user interface translations (in world
record time).

@end itemize

External contributors:

@itemize @bullet

@item
@b{Christian Bauer}
Wrote the very interesting ``VIC article'' from which we got
invaluable information about the VIC-II chip: without this, the
VIC-II implementation would not have been possible.

@item
@b{Eliseo Bianchi}
Provided the italian Amiga translations.

@item
@b{ck!}
Provided a win32 cbm character font.

@item
@b{iAN CooG}
Added win32 vsid GUI and contributed various patches.

@item
@b{Mike Dawson}
Provided the GP2X port.

@item
@b{Paul David Doherty}
Wrote @code{zip2disk}, on which the Zipcode support in @code{c1541} is based.

@item
@b{Sven A. Droll}
Added Supergrafik support to petcat.

@item
@b{Peter Edwards}
Implemented the SDL UI slider control and fixed some
GP2X/Dingoo SDL UI issues.

@item
@b{Daniel Fandrich}
Contributed some disk drive patches.

@item
@b{Dirk Farin}
Rewrote the MITSHM code.

@item
@b{Georg Feil}
Added support for toggling CB2 sound output line in the PET
emulator.

@item
@b{Peter Andrew Felvegi aka Petschy}
Fixed a couple of bugs in the fast serial emulation.

@item
@b{Ricardo Ferreira}
Contributed the @code{unlynx} and @code{system} commands in @code{c1541} and
added aRts sound support.

@item
@b{Flooder}
Provided parts of the Polish user interface translations.

@item
@b{Robert H. Forsman Jr.}
Provided parts of the widget set for implementing the Xaw GUI.

@item
@b{Ian Gledhill}
Added support for the catweasel.device driver.

@item
@b{Peter Gordon}
Provided support for native AmigaOS4 compiling.

@item
@b{Richard Hable}
Contributed the initial version of the REU emulation.

@item
@b{Shawn Hargreaves}
Wrote Allegro, the graphics and audio library used in the DOS
version.

@item
@b{Ville-Matias Heikkila}
Rewrote the vic20 sound code.

@item
@b{David Holz}
Provided a label file which gives the built-in monitor the
labels for the C64.

@item
@b{Nathan Huizinga}
Added support for Expert and Super Snapshot carts.

@item
@b{Derrick Inksley}
Fixed loading of zip files with brackets ([]) in
the filename for the windows port. Added drive selection
functionality to the window sdl port.

@item
@b{Craig Jackson}
Contributed miscellaneous patches in the old X64 times.

@item
@b{Dirk Jagdmann}
Wrote the Catweasel sound driver.

@item
@b{Uffe Jakobsen}
Wrote the Silverrock cartridge emulation and fixed the
ocean cartridge bank wrap.

@item
@b{Lasse Jyrkinen}
Contributed miscellaneous patches in the old X64 times.

@item
@b{Peter Karlsson}
Provided the swedish UI translations in the past.

@item
@b{Greg King}
Added a working RTC to the emulation of the IDE64
cartridge. Provided some vdrive fixes.

@item
@b{Michael Klein}
Contributed the ESD sound driver, basic support for the OPENCBM
library and some other patches.

@item
@b{Frank König}
Contributed the Win32 joystick autofire feature.

@item
@b{Bernd Kortz}
Provided some fixes for ZETA and the ZETA binary package.

@item
@b{Bernhard Kuhn}
Made some joystick improvements for Linux.

@item
@b{Alexander Lehmann}
Added complete support for all the VIC20 memory configurations
for the old VICE 0.12.

@item
@b{Ilkka "itix" Lehtoranta}
Provided the routines for the cybergraphics support for the
Amiga ports.

@item
@b{Magnus Lind}
Atari ST mouse and Atari CX-22 trackball emulation and pixel
aspect fixes. Improved the Amiga mouse emulation. Improved
the vic20 sound output. Added windows POV hat support.
Improved sound fragment size handling.

@item
@b{Locnet}
Made the initial android port of x64.

@item
@b{Wolfgang Lorenz}
Wrote an excellent 6510 test suite that helped us to debug the
CPU emulation.

@item
@b{Marko Mäkelä}
Wrote lots of CPU documentation. Wrote the VIC Flash Plugin
cartridge emulation in xvic.

@item
@b{mar77i}
Fixed some resource handling issues.

@item
@b{Robert W. McMullen}
Provided parts of the widget set for implementing the Xaw GUI.

@item
@b{Jennifer Medkief}
Is in charge of checking up on the GUIs for elements that are
wrong, unaccessable, and missing.

@item
@b{Dan Miner}
Contributed some patches to the fast disk drive emulation.

@item
@b{Luca Montecchiani}
Contributed a new Unix joystick driver.

@item
@b{Wolfgang Moser}
Provided small optimization fixes to the GCR code, provided an
excellent REU test suite and added REU fixes, and is always the
good guy reviewing and commenting changes in the background.

@item
@b{Roberto Muscedere}
Improved support for REL files.

@item
@b{Tomi Ollila}
Donated @code{findpath.c}.

@item
@b{Per Olofsson}
Digitalized the C64 colors used in the (old) default palette.

@item
@b{Lasse Öörni}
Contributed the Windows Multimedia sound driver

@item
@b{Helfried Peyrl}
Supplied a patch that fixes REL file records larger 256 bytes
when using vdrive.

@item
@b{Frank Prindle}
Contributed some patches.

@item
@b{Giuliano Procida}
Used to maintain the VICE @code{deb} package for the Debian
distribution, and also helped proofreading the documentation.

@item
@b{Vesa-Matti Puro}
Wrote the very first 6502 CPU emulator in x64 0.1.0. That was
the beginning of the story@dots{}

@item
@b{Rami Rasanen}
Rewrote the VIC20 sound code.

@item
@b{David Roden}
Fixed various issues related to ffmpeg settings.

@item
@b{Pablo Roldán}
Contributed initial patch for VIC-II PAL-N model selection.

@item
@b{Mathias Roslund}
Provided the AmigaOS4 port.

@item
@b{Gunnar Ruthenberg}
Provided some VIC-II enhancements and improved the Win32 port.

@item
@b{Johan Samuelsson}
Provided the Swedish Amiga translations.

@item
@b{Oliver Schaertel}
Wrote the X11 full screen, parts of custom ROM set support and
1351 mouse emulation for unix.

@item
@b{Peter Schepers}
Contributed a document describing the G64 image format.

@item
@b{Michael Schwendt}
Helped with the SID (audio) chip emulation, bringing important
suggestions and bug reports, as well as the wave tables and
filter emulation from his SIDplay emulator.

@item
@b{Heiko Selber}
Contributed some VIC20 I/O patches.

@item
@b{John Selck}
Improved the video rendering and added the fast PAL emulation.
Implemented new color generation based on P. Timmermanns
knowledge.

@item
@b{Chris Sharp}
Wrote the AIX sound driver.

@item
@b{Andr351 "JoBBo" Siegel}
Provided the native MorphOS icons.

@item
@b{Harry "Piru" Sintonen}
Provided lots of fixes and improvements for the Amiga ports.

@item
@b{Manfred Spraul}
Wrote the Win32 text lister.

@item
@b{Markus Stehr}
Provided the MMC64 emulation.

@item
@b{Dominique Strigl}
Contributed miscellaneous patches in the old X64 times.

@item
@b{Samuli Suominen}
Fixed XShm includes for newer xextproto versions and updated
libpng check for newer versions.

@item
@b{Steven Tieu}
Added initial support for 16/24 bpp X11 displays.

@item
@b{Philip Timmermann}
Did a lot of research about the VIC-II colors.

@item
@b{Brian Totty}
Provided parts of the widget set for implementing the Xaw GUI.

@item
@b{Mustafa "GnoStiC" Tufan}
Made improvements to the GP2x port.

@item
@b{Lionel Ulmer}
Implemented joystick support for Linux and a first try of a SID
emulation for SGI machines.

@item
@b{Krister Walfridsson}
Implemented joystick and sound support for NetBSD.

@item
@b{webulator}
Provided Win32 drag & drop support

@item
@b{Robert Willie}
Added some additional commands to the fsdevice emulation.

@item
@b{Peter Weighill}
Gave many ideas and contributed the ROM patcher.

@item
@b{Gerhard Wesp}
Contributed the @code{extract} command in @code{c1541}.

@item
@b{Maciej Witkowiak}
Did some IDE64 and C1541 fixes.

@item
@b{Peter Rittwage}
Made 1541 GCR hardware tests.

@item
@b{Robert McIntyre}
Bugged people enough to get the improved g64 support rolling, 
updated g64 support to allow variable-length tracks, and 
performed initial development of half-track support.

@item
@b{István Fábián}
Contributed a initial patch with the more correct 1541 bus
timing code and which gave us hints for to improving the 1541
emulation.

@end itemize

(We hope we have not forgotten anybody; if you think we have,
 please tell us.)

The people around the world providing results from running our
test programs on various machines deserve a special mention:

@itemize @bullet

@item
@b{hedning} (Drean C64 PAL-N, various C64 PAL boxes)
@item
@b{Jason Compton} (Various C64 and C128 NTSC boxes)
@item
@b{The Woz} (Drean C64 PAL-N)
@item
@b{Thierry} (Drean C64 PAL-N)
@item
@b{MOS6569} (C64C PAL)
@item
@b{Mike} (VIC-20 PAL)
@item
@b{Wilson} (VIC-20 NTSC)
@item
@b{Vicassembly} (VIC-20 NTSC)
@item
@b{David "jbevren" Wood} (C64 NTSC-OLD)
@end itemize

Thanks also to everyone else for sending suggestions, ideas,
bug reports, questions and requests. In particular, a warm
thanks goes to the following people:

@itemize @bullet
@item
@b{Lutz Sammer}
@item
@b{Ralph Mason}
@item
@b{George Caswell}
@item
@b{Jasper Phillips}
@item
@b{Luca Forcucci}
@item
@b{Asger Alstrup}
@item
@b{Bernhard Schwall}
@item
@b{Salvatore Valente}
@item
@b{Arthur Hagen}
@item
@b{Douglas Carmichael}
@item
@b{Ferenc Veres}
@item
@b{Frank Reichel}
@item
@b{Ullrich von Bassewitz}
@item
@b{Holger Busse}
@item
@b{David "jbevren" Wood}
@item
@b{Gary Glenn}
@end itemize

Last but not least, a very special thank to Andreas Arens, Lutz
Sammer, Edgar Tornig, Christian Bauer, Wolfgang Lorenz, Miha
Peternel, Per Håkan Sundell and David Horrocks for writing
cool emulators to compete with.  @t{:-)}

@node Copyright, Contacts, Acknowledgments, Top
@chapter Copyright

@itemize @bullet
@item
Copyright @copyright{} 1998-2014 Dag Lem
@item
Copyright @copyright{} 1999-2014 Andreas Matthies
@item
Copyright @copyright{} 1999-2014 Martin Pottendorfer
@item
Copyright @copyright{} 2005-2014 Marco van den Heuvel
@item
Copyright @copyright{} 2006-2014 Christian Vogelgsang
@item
Copyright @copyright{} 2007-2014 Fabrizio Gennari
@item
Copyright @copyright{} 2007-2014 Daniel Kahlin
@item
Copyright @copyright{} 2009-2014 Groepaz
@item
Copyright @copyright{} 2009-2014 Ingo Korb
@item
Copyright @copyright{} 2009-2014 Errol Smith
@item
Copyright @copyright{} 2010-2014 Olaf Seibert
@item
Copyright @copyright{} 2011-2014 Marcus Sutton
@item
Copyright @copyright{} 2011-2014 Ulrich Schulz
@item
Copyright @copyright{} 2011-2014 Stefan Haubenthal
@item
Copyright @copyright{} 2011-2014 Thomas Giesel
@item
Copyright @copyright{} 2011-2014 Kajtar Zsolt
@item
Copyright @copyright{} 2012-2014 Benjamin 'BeRo' Rosseaux

@item
Copyright @copyright{} 2000-2011 Spiro Trikaliotis
@item
Copyright @copyright{} 1998-2010 Tibor Biczo
@item
Copyright @copyright{} 1998-2010 Andreas Boose
@item
Copyright @copyright{} 2007-2010 M. Kiesel
@item
Copyright @copyright{} 2007-2011 Hannu Nuotio
@item
Copyright @copyright{} 1999-2007 Andreas Dehmel
@item
Copyright @copyright{} 2003-2005 David Hansel
@item
Copyright @copyright{} 2000-2004 Markus Brenner

@item
Copyright @copyright{} 1999-2004 Thomas Bretz
@item
Copyright @copyright{} 1997-2001 Daniel Sladic
@item
Copyright @copyright{} 1996-1999 Ettore Perazzoli
@item
Copyright @copyright{} 1996-1999 André Fachat
@item
Copyright @copyright{} 1993-1994, 1997-1999 Teemu Rantanen
@item
Copyright @copyright{} 1993-1996 Jouko Valta
@end itemize


This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307  USA


@node Contacts, Concept Index, Copyright, Top
@chapter Contact information

@menu
* Home page::                   The official VICE WWW page.
* Sending feedback::            How to report impressions and
                                bugs to the authors.
* Contributing::                How to help developing VICE.
* Newsgroups::                  VICE-related Usenet groups.
* FAQs you should read::        VICE-related Frequently Asked Questions.
@end menu

@node Home page, Sending feedback, Contacts, Contacts
@section VICE home page

You can find the latest news about VICE at the official VICE
home page:

@example
@uref{http://vice-emu.sourceforge.net/}
@end example

VICE has moved its source repository to public services provided by
SourceForge. You can find it at
@example
@uref{http://sf.net/projects/vice-emu}.
@end example

We would like to thank the SourceForge staff for that help.

If you are going to report a bug, please check those pages @emph{first};
it is possible that the problem you encountered has already been
fixed with a newer version.

Please, also have a look at the VICE knowledge base at

@example
@uref{http://vicekb.trikaliotis.net/}
@end example

@node Sending feedback, Contributing, Home page, Contacts
@section How to send feedback

Before contacting us, have a look at the VICE knowledge base at
@uref{http://vicekb.trikaliotis.net/} if your question is answered
there. Keep in mind that we work on VICE in our spare-time, so the more
time we don't need to answer the same questions over and over again, the
more time we have to improve the emulation itself. On the other hand,
that does not mean that you should not contact us, especially if you
find bugs or have suggestions which might improve the emulation.

Bug reports, suggestions, support requests should be directed to the
SourceForge trackers at

@itemize @bullet

@item
@uref{http://sourceforge.net/tracker/?group_id=223021}.
@end itemize

This way, you, the users, and we, the developers, can track what has
been reported and what has been already fixed. Ideally, also sent the
report to the mailing address of the Vice team at

@itemize @bullet

@item
VICE Mailing List (@email{vice-emu-mail@@lists.sourceforge.net}) for all
general questions, bug reports, suggestions.

@end itemize

You can also contact (some of) us on IRC, at #vice-dev on freenode.

It's always nice to receive feedback and/or bugreports about VICE, but
please read these few notes before sending mail to anybody in the
team.

@itemize @bullet

@item
Please put the word @samp{VICE} @emph{in all capitals} in your subject
line (e.g., @samp{VICE fails to run game XXX}).  This helps mail
splitting and reduces chances that your message is unintentionally
deleted, forgotten or lost.

@item
Please don't send any HTML mail (we really hate that!).  If you use
M$ Outlook or Netscape Communicator, make sure you turn off the
"rich text" (HTML) feature.

@item
Please don't send @emph{any} binaries without asking first.

@item
Please read the following documents carefully before reporting a bug
or a problem you cannot solve:

@itemize @bullet
@item
the VICE documentation (you are reading it!);
@item
the VICE FAQ (it is available on the Internet, and reachable from the
VICE home page:
@uref{http://vice-emu.sourceforge.net/});
@item
The VICE knowledge base (it is available on the Internet at
@uref{http://vicekb.trikaliotis.net/});
@item
the @code{comp.emulators.cbm} and @code{comp.sys.cbm} FAQs (@pxref{FAQs
you should read}).
@end itemize

@item
When you report a bug, please try to be as accurate as possible and
describe how it can be reproduced to the very detail.  You should also
tell us what machine you are running on, what operating system you are
using as well as the version of it.

@item
Please don't ask us how to transfer original C64 disk or tapes to your
PC; this has been asked a gazillion times through email.  To transfer
disks, you can use the Star Commander
(@uref{http://sta.c64.org/sc.html}) on DOS, and OpenCBM
(@uref{http://www.trikaliotis.net/opencbm}) on Windows and Linux.  And
no, you cannot read C64 disks with your old 5"1/4 PC drive.

@item
Please don't ask us where to find games for the emulator on the
Internet.

@item
Please don't ask us when the next version will be out, because we
really don't know.

@item
Please write in English.

@end itemize

In any case, we would be @emph{really} glad to receive your comments
about VICE.  We cannot always answer all the email, but we surely read
all of it.

Thanks!


@node Contributing, Newsgroups, Sending feedback, Contacts
@section How to contribute

If you want to make a major contribution, please @emph{ask} first.  It
has already happened a couple of times that somebody started working at
something that had already been done but not released to the public yet,
and we really do @emph{not} want anybody to waste time.

If you are going to make a patch, please make sure the patch is relative
to the very latest version, and provide us with the following:

@itemize @bullet
@item
Make sure you are giving us a diff against the latest Subversion
trunk version of VICE. For instructions on accessing the Subversion
repository, first read @uref{http://sourceforge.net/svn/?group_id=223021} and
get it with the command:
@example
@samp{svn co https://vice-emu.svn.sourceforge.net/svnroot/vice-emu/trunk vice-src}
@end example
@item
send a unified diff file against the trunk version of VICE (see above
bullet point) by using the command: @samp{svn diff} inside of the
SVN workspace you checked out before.

@item
If you cannot use SVN for one or the other reason, send a unified diff
file containing all the changes you have made @samp{diff -u};
please don't use plain @samp{diff}), as it adds much work for us to get
it working;
@item
GNU-style @file{ChangeLog} entries with a description of the changes you
have made (look at the @file{ChangeLog}s provided with the original VICE
sources for an example).
@end itemize

This is very important, and makes adding patches much smoother and
safer.

People willing to port VICE to other platforms are always welcome.
But notice from experience it will take at least a full year of
continuous work to write a well working and stable port.

@node Newsgroups, FAQs you should read, Contributing, Contacts
@section Interesting newsgroups

There are some Usenet newsgroups you might be interested in:

@itemize @bullet

@item
@code{comp.emulators.cbm}, discussing about emulators of Commodore 8-bit
machines (definitely not Amiga emulators).

@item
@code{comp.sys.cbm}, discussing various topics regarding real Commodore
8-bit machines.  This newsgroup is mainly for people who actually use
original Commodore equipment (so please don't talk about emulation
here).

@item
@code{comp.emulators.misc}, discussing emulators in general.

@end itemize

@node FAQs you should read, , Newsgroups, Contacts
@section FAQs you should read

We recommend reading the @code{comp.emulators.cbm} and
@code{comp.sys.cbm} FAQs, which are posted regularly on the
corresponding newsgroups and are also available via FTP from
@uref{ftp://rtfm.mit.edu}.

@node Concept Index, Resource Index, Contacts, Top
@unnumbered Concept Index

@printindex cp

@node Resource Index,  , Concept Index, Top
@unnumbered Index of Resources

@printindex vr

@contents

@bye