This is vice.info, produced by makeinfo version 4.5 from vice.texi.

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

   VICE Manual

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

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


File: vice.info,  Node: CBM-II memory module,  Next: C500 data module,  Prev: PET memory module,  Up: Module formats

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

   The CBM2MEM module

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

   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.

   The CBM2ROM module

Type    Name                          Description
UBYTE   CONFIG                        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.
ARRAY   KERNAL                        8 KERNAL ROM image ($e000-$efff)
ARRAY   BASIC                         BASIC ROM image ($8000-$bfff)
ARRAY   CHARGEN                       4k CHARGEN ROM image
ARRAY   ROM1                          4k cartridge ROM image for $1***
                                      (if CONFIG & 2)
ARRAY   ROM2                          8k cartridge ROM image for
                                      $2000-$3fff (if CONFIG & 4)
ARRAY   ROM4                          8k cartridge ROM image for
                                      $4000-$5fff (if CONFIG & 8)
ARRAY   ROM6                          8k cartridge ROM image for
                                      $6000-$7fff (if CONFIG & 16)


File: vice.info,  Node: C500 data module,  Prev: CBM-II memory module,  Up: Module formats

C500 data module
................

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

   Version numbers: Major 0, Minor 0

   The C500DATA module

Type    Name                          Description
DWORD   IRQCLK                        CPU clock ticks till next 50Hz IRQ


File: vice.info,  Node: Monitor,  Next: c1541,  Prev: Snapshots,  Up: Top

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
`rxvt' or `xterm') in order to use the monitor.

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


File: vice.info,  Node: Terminology,  Next: Machine state commands,  Prev: Monitor,  Up: Monitor

Terminology
===========

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

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

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

`address'
     A specific memory location in the range $0000 to $FFFF.

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

`address_opt_range'
     An address or an address range.

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

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

`breakpoint'
     A breakpoint is triggered based on the program counter.  When it is
     triggered, the monitor is entered.

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

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

`<...>'
     A data type.

`*'
     Zero or more occurrences.

`[...]'
     An optional argument.



File: vice.info,  Node: Machine state commands,  Next: Memory commands,  Prev: Terminology,  Up: Monitor

Machine state commands
======================

`goto <address>'
     Change the PC to address and continue execution.

`io'
     Nothing yet.  Will display VIC/VIA/CIA/SID registers.

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

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

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

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



File: vice.info,  Node: Memory commands,  Next: Assembly commands,  Prev: Machine state commands,  Up: Monitor

Memory commands
===============

`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 `ram' bank is used where the bank has holes.  The
     `cpu' bank uses the bank currently used by the CPU.

`compare <address_range> <address>'
     Compare memory from the source specified by the address range to
     the destination specified by the address.  The regions may
     overlap.  Any values that miscompare are displayed using the
     default displaytype.

`device [c:|8:|9:]'
     Set the default address space to either the computer `c:' or the
     specified drive `8:' or `9:'

`fill <address_range> <data_list>'
     Fill memory in the specified address range with the data in
     <data_list>.  If the size of the address range is greater than the
     size of the data_list, the data_list is repeated.

`hunt <address_range> <data_list>'
     Hunt memory in the specified address range for the data in
     <data_list>.  If the data is found, the starting address of the
     match is displayed.  The entire range is searched for all possible
     matches.

`i <address_opt_range>'
     Display memory contents as PETSCII text.

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

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

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

`move <address_range> <address>'
     Move memory from the source specified by the address range to the
     destination specified by the address.  The regions may overlap.

`sidefx [on|off|toggle]'
     Control how monitor generated reads affect memory locations that
     have read side-effects, like CIA interrupt registers for example.
     If the argument is 'on' then reads may cause side-effects.  If the
     argument is 'off' then reads don't cause side-effects.  If the
     argument is 'toggle' then the current mode is switched.  No
     argument displays the current state.

`> [<address>] <data_list>'
     Write the specified data at `address'.



File: vice.info,  Node: Assembly commands,  Next: Checkpoint commands,  Prev: Memory commands,  Up: Monitor

Assembly commands
=================

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

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



File: vice.info,  Node: Checkpoint commands,  Next: General commands,  Prev: Assembly commands,  Up: Monitor

Checkpoint commands
===================

`break [<address> [if <cond_expr>] ]'
     This command allows setting a breakpoint or listing the current
     breakpoints.  If no address is given, the currently valid
     checkpoints are printed.  If an address is given, a breakpoint is
     set for that address and the breakpoint number is printed.  A
     conditional expression can also be specified for the breakpoint.
     For more information on conditions, see the CONDITION command.

`enable <checknum>'

`disable <checknum>'
     Each checkpoint can be enabled or disabled.  This command allows
     changing between these states.

`command <checknum> "<command>"'
     When checkpoint `checknum' is hit, the specified command is
     executed by the monitor.  Note that the `x' command is not yet
     supported as a command argument.

`condition <checknum> if <cond_expr>'
     Each time the specified checkpoint is examined, the condition is
     evaluated.  If it evalutes to true, the checkpoint is activated.
     Otherwise, it is ignores.  If registers are specified in the
     expression, the values used are those at the time the checkpoint is
     examined, not when the condition is set.

`delete <checknum>'
     Delete the specified checkpoint.

`ignore <checknum> [<count>]'
     Ignore a checkpoint after a given number of crossings.  If no
     count is given, the default value is 1.

`trace [address [address]]'
     This command is similar to the `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.

`watch [loadstore] [address [address]]'
     This command is similar to the previous two commands except that it
     operates on watchpoints.  A watchpoint differs from the others by
     stopping on a read and/or write to an address or range of
     addresses.  If no addresses are given, a list of all the
     watchpoints is printed.  The loadstore parameter can be either
     "load" or "store" to determine on which operation the monitor
     breaks. If not specified, the monitor breaks on both operations.



File: vice.info,  Node: General commands,  Next: Disk commands,  Prev: Checkpoint commands,  Up: Monitor

General commands
================

`cd <directory>'
     Change the working directory.

`device [c:|d:]'
     Set the default memory device to either the computer (`c:') or the
     disk (`d:').

`radix [H|D|O|B]'
     Set the default radix to hex, decimal, octal, or binary.  With no
     argument, the current radix is printed.

`sidefx [on|off|toggle]'
     Control how monitor generated reads affect memory locations that
     have read side-effects.  If the argument is 'on' then reads may
     cause side-effects.  If the argument is 'off' then reads don't
     cause side-effects.  If the argument is 'toggle' then the current
     mode is switched.  No argument displays the current state.

`system <system command>'
     Nothing yet.



File: vice.info,  Node: Disk commands,  Next: Command file commands,  Prev: General commands,  Up: Monitor

Disk commands
=============

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

`bw <track> <sector> <address>'
     Write a block of data at `address' to the specified track and
     sector of disk in drive 8.

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

`load "<filename>" <device> [<address>]'
     Load the specified file into memory.  If no address is given, the
     file is loaded to the address specified by the first two bytes
     read from the file.  If address is given, the file is loaded to
     the specified address and the first two bytes read from the file
     are skipped.  If device is 0, the file is read from the file
     system.

`save "<filename>" <device> <address1> <address2>'
     Save the memory from address1 to address2 to the specified file.
     If device is 0, the file is written to the file system.



File: vice.info,  Node: Command file commands,  Next: Label commands,  Prev: Disk commands,  Up: Monitor

Command file commands
=====================

`playback "<filename>"'
     Monitor commands from the specified file are read and executed.
     This command stops at the end of file or when a STOP command is
     read.

`record "<filename>"'
     After this command, all commands entered are written to the
     specified file until the STOP command is entered.

`stop'
     Stop recording commands.  See `record'.



File: vice.info,  Node: Label commands,  Next: Miscellaneous commands,  Prev: Command file commands,  Up: Monitor

Label commands
==============

`add_label <address> <label>'
     Map a given address to a label.  This label can be used when
     entering assembly code and is shown during disassembly.

`delete_label [<memspace>] <label>'
     Remove the specified label from the label tables.  If no memory
     space is checked, all tables are checked.

`load_labels [<memspace>] "<filename>"'
     Load a file containing a mapping of labels to addresses.  If no
     memory space is specified, the default readspace is used.

`save_labels [<memspace>] "<filename>"'
     Save labels to a file.  If no memory space is specified, all of the
     labels are saved.

`show_labels [<memspace>]'
     Display current label mappings.  If no memory space is specified,
     show all labels.



File: vice.info,  Node: Miscellaneous commands,  Prev: Label commands,  Up: Monitor

Miscellaneous commands
======================

`exit'
     Leave the monitor and return to execution.

`print <expression>'
     Evaluate the specified expression and output the result.

`quit'
     Exit the emulator immediately.

`~ <number>'
     Display the specified number in decimal, hex, octal and binary.



File: vice.info,  Node: c1541,  Next: File formats,  Prev: Monitor,  Up: Top

c1541
*****

   VICE is provided with a complete stand-alone disk image maintenance
utility, called `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
`xterm' window with a running `c1541' in it.

   The syntax is:

     c1541 [IMAGE1 [IMAGE2]] [COMMAND1 COMMAND2 ... COMMANDN]

   `IMAGE1' and `IMAGE2' are disk image names that can be attached
before `c1541' starts.  `c1541' can handle up to two disk images at the
same time by using two virtual built-in drives, numbered `8' and `9';
`IMAGE1' (if present) is always attached to drive `8', while `IMAGE2'
is attached to drive `9'.

   `COMMAND's specified on the command-line all begin with the minus
sign (`-'); if present, `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 `COMMAND's fails, `c1541' stops and returns
a nonzero error code.

   If no `COMMAND's are specified at all, `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 `-'.  As with the monitor, file name completion and command
line editing with history are provided via GNU `readline'.  Use the
command `quit' or press `C-d' to exit.

* Menu:

* c1541 file specification::
* c1541 quoting::
* c1541 commands and options::
* c1541 executing shell commands::


File: vice.info,  Node: c1541 file specification,  Next: c1541 quoting,  Prev: c1541,  Up: c1541

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 `@8:' or `@9:', you will
specified that file is to be found or created on drive 8 and 9,
respectively.

   For instance,

     @8:somefile

   will name file named `somefile' on unit 8, while

     @9:somefile

   will name file named `somefile' on unit 9.


File: vice.info,  Node: c1541 quoting,  Next: c1541 commands and options,  Prev: c1541 file specification,  Up: c1541

Using quotes and backslashes
============================

   You can use quotes (`"') in a command to embed spaces into file
names.  For instance,

     read some file

   will read file `some' from the disk image and write it into the file
system as `file', while

     read "some file"

   will copy `some file' into the file system, with the name `some
file'.

   The backslash character (`\') has a special meaning too: it lets you
literally insert the following character no matter what it is.  For
example,

     read some\ file

   will copy file `some file' into the file system, while

     read some\ file this\"file

   will copy `some file' into the file system with name `this"file'
(with an embedded quote).


File: vice.info,  Node: c1541 commands and options,  Next: c1541 executing shell commands,  Prev: c1541 quoting,  Up: c1541

c1541 commands and options
==========================

   This is a list of the `c1541' commands.  They are shown in their
interactive form, without the leading `-'.  Square brackets [] indicate
an optional part, and "<COMMAND>" translates to a disk command
according to CBM DOS, like "i0" for example.

` [<command>]'
     Execute specified CBM DOS command and print the current status of
     the drive.  If no `command' is specified, just print the status.

`? [<command>]'
     Explain specified command.  If no command is specified, list
     available ones.

`attach <diskimage> [<unit>]'
     Attach `diskimage' to `unit' (default unit is 8).

`block <track> <sector> <disp> [<drive>]'
     Show specified disk block in hex form.

`copy <source1> [<source2> ... <sourceN>] <destination>'
     Copy `source1' ... `sourceN' into destination.  If N > 1,
     `destination' must be a simple drive specifier (`@n:').

`delete <file1> [<file2> ... <fileN>]'
     Delete the specified files.

`exit'
     Exit (same as `quit').

`extract'
     Extract all the files to the file system.

`format <diskname,id> [<type> <imagename>] [<unit>]'
     If `unit' is specified, format the disk in unit `unit'.  If `type'
     and `imagename' are specified, create a new image named
     `imagename', attach it to unit 8 and format it.  `type' is a disk
     image type, and must be either `x64', `d64' (both VC1541/2031),
     `g64' (VC1541/2031 but in GCR coding), `d71' (VC1571), `d81'
     (VC1581), `d80' (CBM8050) or `d82' (CBM8250/1001).  Otherwise,
     format the disk in the current unit, if any.

`gcrformat <diskname,id> <imagename>'
     Create and format a G64 disk image named `imagename'.

`help [<command>]'
     Explain specified command.  If no command is specified, list
     available ones.

`info [<unit>]'
     Display information about unit `unit' (if unspecified, use the
     current one).

`list [<pattern>]'
     List files matching `pattern' (default is all files).

`quit'
     Exit (same as `exit').

`read <source> [<destination>]'
     Read `source' from the disk image and copy it into `destination' in
     the file system.  If `destination' is not specified, copy it into a
     file with the same name as `source'.",

`rename <oldname> <newname>'
     Rename `oldname' into `newname'.  The files must be on the same
     drive.

`tape <t64name> [<file1> ... <fileN>]'
     Extract files from a T64 image.

`unit <number>'
     Make unit `number' the current unit.

`unlynx <lynxname> [<unit>]'
     Extract the specified Lynx image file into the specified unit
     (default is the current unit).

`validate [<unit>]'
     Validate the disk in unit `unit'.  If `unit' is not specified,
     validate the disk in the current unit.

`write <source> [<destination>]'
     Write `source' from the file system into `destination' on a disk
     image.

`zcreate <x64name> <zipname> [<label,id>]'
     Create an X64 disk image out of a set of four Zipcoded files named
     `1!zipname', `2!zipname', `3!zipname' and `4!zipname'.



File: vice.info,  Node: c1541 executing shell commands,  Prev: c1541 commands and options,  Up: c1541

Executing shell commands
========================

   If you want to execute a shell command from withing `c1541', just
prepend it with an exclamation mark (`!').  For example,

     !ls -la

   will execute the command `ls -la', which will show you all the files
in the current directory.


File: vice.info,  Node: File formats,  Next: Acknowledgments,  Prev: c1541,  Up: Top

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


File: vice.info,  Node: T64,  Next: G64,  Prev: File formats,  Up: File formats

The T64 tape image format
=========================

   (This section was taken from the C64S distribution.)

   The `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::


File: vice.info,  Node: T64 file structure,  Next: T64 tape record,  Prev: T64,  Up: T64

T64 File structure
------------------

Offset                 Size                   Description
0                      64                     tape record
64                     32*n                   file records for n directory
                                              entries
64+32*n                varies                 binary contents of the files


File: vice.info,  Node: T64 tape record,  Next: T64 file record,  Prev: T64 file structure,  Up: T64

Tape Record
-----------

Offset                 Size                   Description
0                      32                     DOS tape description + EOF
                                              (for type)
32                     2                      tape version ($0200)
34                     2                      number of directory entries
36                     2                      number of used entries (can
                                              be 0 in my loader)
38                     2                      free
40                     24                     user description as
                                              displayed in tape menu


File: vice.info,  Node: T64 file record,  Prev: T64 tape record,  Up: T64

File record
-----------

Offset                 Size                   Description
0                      1                      entry type (see below)
1                      1                      C64 file type
2                      2                      start address
4                      2                      end address
6                      2                      free
8                      4                      offset of file contents
                                              start within T64 file
12                     4                      free
16                     16                     C64 file name

   Valid entry types are:

Code                   Explanation
`0'                    free entry
`1'                    normal tape file
`2'                    tape file with header: header is saved just
                       before file data
`3'                    memory snapshot v0.9, uncompressed
`4'                    tape block
`5'                    digitized stream
`6' ... `255'          reserved

   Notes:

   * VICE only supports file type `1'.

   * Types `3', `4' and `5' are subject to change (and are rarely
     used).


File: vice.info,  Node: G64,  Prev: T64,  Up: File formats

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
`D64'.

   The intention behind `G64' is not to replace the widely used `D64'
format, as `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 `D64' image.

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

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

Offset         Description
$0000-0007     File signature (`GCR-1541')
$0008          `G64' version (presently only $00 defined)
$0009          Number of tracks in image (usually $54, decimal 84)
$000A-000B     Size of each stored track in bytes (usually 7928, or
               $1EF8) in LO/HI format.

   An obvious question here is "why are there 84 tracks defined when a
normal `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 `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.

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

Offset         Description
$000C-000F     Offset to stored track 1.0 ($000002AC, in LO/HI format,
               see below for more)
$0010-0013     Offset to stored track 1.5 ($00000000)
$0014-0017     Offset to stored track 2.0 ($000021A6)
...            
$0154-0157     Offset to stored track 42.0 ($0004F8B6)
$0158-015B     Offset to stored track 42.5 ($00000000)

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

Offset         Description
$015C-015F     Speed zone entry for track 1 ($03, in LO/HI  format, see
               below for more)
$0160-0163     Speed zone entry for track 1.5 ($03)
...            
$02A4-02A7     Speed zone entry for track 42 ($00)
$02A8-02AB     Speed zone entry for track 42.5 ($00)

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

           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

Offset         Description
$02AC-02AD     Actual size of stored track (7692 or $1E0C, in LO/HI
               format)
$02AE-02AE+$1E0CTrack data

   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.

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

   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:

Track Range                          Speed Zone
1-17                                 3  (highest writing speed)
18-24                                2
25-30                                1
31 and up                            0 (lowest writing speed)

   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:

     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)

   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.


File: vice.info,  Node: Acknowledgments,  Next: Copyright,  Prev: File formats,  Up: Top

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:
   * Daniel Sladic started the work on hardware-level 1541 emulation
     and wrote the new monitor introduced with VICE 0.15.

   * Andreas Boose gave lots of information and bug reports about the
     VIC-II, the 6510 and the CIAs; moreover, he wrote several
     test-routines that were used to improve the emulation.  He also
     added cartridge support and has been the main head behind the
     drive and datasette emulation since version 0.15.  Also added
     several UI elements to the MSDOS and MS-Windows ports. He rewrote
     the C128 emulation adding Z80 mode, C64 mode and function ROM
     support.

   * Dag Lem implemented the reSID SID emulation engine.

   * Tibor Biczo improved the MS-Windows port.

   * Andreas Dehmel wrote the Acorn RISC OS port.

   * Thomas Bretz responsible for the OS/2 port.

   * Andreas Matthies improved the datasette support, the VIC20 video
     emulation and some ui stuff in the Win32 and MSDOS port. He also
     wrote the BeOS port.

   * Martin Pottendorfer Implemented Gnome Port based on Oliver
     Schaertels GTK+ port Added support code for internationalization
     based on gettext Translated the Unix Port to German Implemented
     the fliplists + ui (unix).

   * Markus Brenner added VDC emulation to x128 and added support for
     some more cartridges.

   * Spiro Trikaliotis wrote the Win32 console implementation for the
     built-in monitor and provided some further patches.

   * Marco van den Heuvel Translated the UI to Dutch.
     Internationalization support for the Win32 port. Wrote the GEORAM
     and RamCart code. Wrote the c64 +60K and 256K expansions code.
     Made the ethernet support for the Msdos port. Maintains the QNX
     6.x, Solaris and newly resurrected OS/2 binary ports. Added new
     .crt carts support. Added new screenshot formats. And lots of
     other fixes.


   Former team members:

   * Ettore Perazzoli Copyright (C) 1996-1999 Made the 6510, VIC-II,
     VIC-I and CRTC emulations, part of the hardware-level 1541
     emulation, speed optimizations, bug fixes, the event-driven
     cycle-exact engine, the Xt/Xaw/Xfwf-based GUI for X11, a general
     code reorganization, the new resource handling, most of the
     documentation.  He also wrote the MS-DOS port and the initial
     MS-Windows port (well, somebody had to do it).

   * André Fachat Copyright (C) 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.

   * Teemu Rantanen Copyright (C) 1993-1994, 1997-1999 Implemented the
     SID emulation and the trap-based disk drive and serial bus
     implementation; added support for multiple display depths under
     X11.  Also wrote `c1541'

   * Jouko Valta Copyright (C) 1993-1996 Wrote `petcat' and `c1541',
     `T64' handling, user service and maintenance (most of the work in
     x64 0.3.x was made by him); retired from the project in July 96,
     after VICE 0.10.0.

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


   External contributors:

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

   * Christian Bauer wrote the very interesting "VIC article" from
     which we got invaluable information about the VIC-II chip: without
     this, the VIC-II implementation would have not been possible.

   * Wolfgang Lorenz wrote an excellent 6510 test suite that helped us
     to debug the CPU emulation.

   * Giuliano Procida is the maintainer of the VICE `deb' package for
     the Debian distribution, and also helped proofreading the
     documentation.

   * Marko Mäkelä wrote lots of CPU documentation.

   * Chris Sharp wrote the AIX sound driver.

   * Krister Walfridsson implemented joystick and sound support for
     NetBSD.

   * Mattias Engdegård got non-default depths to work.

   * Peter Andrew Felvegi aka Petschy fixed a couple of bugs in the
     fast serial emulation.

   * Olaf Seibert contributed some PET, and disk drive patches.

   * Daniel Fandrich contributed some disk drive patches.

   * Heiko Selber contributed some VIC20 I/O patches.

   * Steven Tieu added initial support for 16/24 bpp X11 displays.

   * Alexander Lehmann added complete support for all the VIC20 memory
     configurations for the old VICE 0.12.

   * Lionel Ulmer implemented joystick support for Linux and a first
     try of a SID emulation for SGI machines.

   * Bernhard Kuhn made some joystick improvements for Linux.

   * Gerhard Wesp contributed the `extract' command in `c1541'.

   * Ricardo Ferreira contributed the `unlynx' and `system' commands in
     `c1541'.

   * Tomi Ollila donated `findpath.c'.

   * Richard Hable contributed the initial version of the REU Emulation.

   * Vesa-Matti Puro wrote the very first 6502 CPU emulator in x64
     0.1.0.  That was the beginning of the story...

   * Dan Miner contributed some patches to the fast disk drive
     emulation.

   * Frank Prindle contributed some patches.

   * Peter Weighill gave many ideas and contributed the ROM patcher.

   * Dominique Strigl, Craig Jackson and Lasse Jyrkinen contributed
     miscellaneous patches in the old X64 times.

   * Per Olofsson digitalized the C64 colors used in the default
     palette.

   * Paul David Doherty wrote `zip2disk', on which the Zipcode support
     in `c1541' is based.

   * Robert H. Forsman Jr., Brian Totty and Robert W. McMullen provided
     the widget set for implementing the `Xaw' GUI.

   * Shawn Hargreaves wrote Allegro, the graphics and audio library
     used in the MS-DOS version.

   * Peter Schepers contributed a document describing the G64 image
     format.

   * Oliver Schaertel wrote the X11 full screen, parts of custom ROM
     set support and 1351 mouse emulation for unix.

   * Luca Montecchiani contributed a new Unix joystick driver.

   * Dirk Farin rewrote the MITSHM code.

   * Manfred Spraul wrote the MS-Windows text lister.

   * Eric provided the french translation for the Unix ports.

   * Andrea Musuruane provided the italian translation for the Unix
     ports

   * Michael Klein contributed the ESD sound driver and some patches.

   * David Holz provided a label file which gives the built-in monitor
     the labels for the C64.

   * Lasse Öörni contributed the Windows Multimedia sound driver

   * Frank König contributed the Win32 joystick autofire feature.

   * John Selck wrote the fast PAL emulation.

   * webulator provided win32 drag & drop support

   * ck! provided a win32 cbm character font.

   * Lutz Sammer

   * Ralph Mason

   * George Caswell

   * Per Olofsson

   * Jasper Phillips

   * Luca Forcucci

   * Asger Alstrup

   * Bernhard Schwall

   * Salvatore Valente

   * Arthur Hagen

   * Douglas Carmichael

   * Ferenc Veres

   * Andrea Musuruane

   * Frank Reichel

   * Ullrich von Bassewitz

   * Holger Busse

   Last but not least, a very special thank to Andreas Arens, Lutz
Sammer, Edgar Tornig, Christian Bauer, Wolfgang Lorenz, Miha Peternel
and Per Håkan Sundell for writing cool emulators to compete with.  :-)

