This is vice.info, produced by makeinfo version 6.6 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: CRTC Settings,  Next: PET I/O extensions,  Prev: PET model,  Up: PET-specific

7.7.2 CRTC Settings
-------------------

7.7.2.1 CRTC resources
......................

'Crtc'
     Boolean specifying whether to enable/disable CRTC 6545 emulation
     (all models from 40xx and above).

'CrtcVideoCache'
     Boolean specifying whether the video cache is turned on.

'CrtcDoubleSize'
     Boolean specifying whether double-size mode is turned on.

'CrtcDoubleScan'
     Boolean specifying whether double-scan mode is turned on.

'CrtcStretchVertical'
     Boolean specifying whether vertical stretching is turned on.

'CrtcPaletteFile'
     String specifying the name of the palette file being used.  The
     '.vpl' extension is optional.

'CrtcExternalPalette'
     Boolean specifying whether to use external palette file or not.

'CrtcColorSaturation'
     Integer specifying saturation of internal calculated palette.
     (0..2000)

'CrtcColorContrast'
     Integer specifying contrast of internal calculated palette.
     (0..2000)

'CrtcColorBrightness'
     Integer specifying brightness of internal calculated palette.
     (0..2000)

'CrtcColorGamma'
     Integer specifying gamma of internal calculated palette.  (0..4000)

'CrtcColorTint'
     Integer specifying tint of internal calculated palette.  (0..2000)

'CrtcPALScanLineShade'
     Integer specifying amount of scan line shading for the CRT
     emulation.  (0..1000)

'CrtcPALBlur'
     Integer specifying amount of horizontal blur for the CRT emulation.
     (0..1000)

'CrtcPALOddLinePhase'
     Integer specifying phase for color carrier in odd lines.  (0..2000)

'CrtcPALOddLineOffset'
     Integer specifying phase offset for color carrier in odd lines.
     (0..2000)

'CrtcAudioLeak'
     Boolean specifying whether to enable/disable video to audio leak
     emulation.

'CrtcFilter'
     Integer specifying rendering filter.  (0: None, 1: CRT emulation,
     2: Scale2x)

7.7.2.2 CRTC command-line options
.................................

'-crtc'
'+crtc'
     Enable/disable the 6545 CRTC emulation ('Crtc=1', 'Crtc=0').

'-Crtcvcache'
'+Crtcvcache'
     Enable/disable the video cache ('CrtcVideoCache=1',
     'CrtcVideoCache=0').

'-Crtcdsize'
'+Crtcdsize'
     Enable/disable double size ('CrtcDoubleSize=1',
     'CrtcDoubleSize=0').

'-CRTCstretchvertical'
'+CRTCstretchvertical'
     Enable/disable vertical stretching ('CrtcStretchVertical=1',
     'CrtcStretchVertical=0').

'-Crtcdscan'
'+Crtcdscan'
     Enable/disable double scan ('CrtcDoubleScan=1',
     'CrtcDoubleScan=0').

'-Crtcfilter <Mode>'
     Select rendering filter ('CrtcFilter').  (0: None, 2: CRT
     emulation, 3: Scale2x)

'-Crtcintpal'
     Use an internal calculated palette ('CrtcExternalPalette=0').

'-Crtcextpal'
     Use an external palette (file) ('CrtcExternalPalette=1').

'-Crtcpalette <name>'
     Specify the name of the palette file ('CrtcPaletteFile').

'-Crtcsaturation <0-2000>'
     Set saturation of internal calculated palette
     ('CrtcColorSaturation').

'-Crtccontrast <0-2000>'
     Set contrast of internal calculated palette ('CrtcColorContrast').

'-Crtcbrightness <0-2000>'
     Set brightness of internal calculated palette
     ('CrtcColorBrightness').

'-Crtcgamma <0-4000>'
     Set gamma of internal calculated palette ('CrtcColorGamma').

'-Crtctint <0-2000>'
     Set tint of internal calculated palette ('CrtcColorTint').

'-Crtcoddlinesphase <0-2000>'
     Set phase for color carrier in odd lines ('CrtcPALOddLinePhase').

'-Crtcoddlinesoffset <0-2000>'
     Set phase offset for color carrier in odd lines
     ('CrtcPALOddLineOffset').

'-Crtccrtblur <0-1000>'
     Amount of horizontal blur for the CRT emulation ('CrtcPALBlur').

'-Crtccrtscanlineshade <0-1000>'
     Amount of scan line shading for the CRT emulation
     ('CrtcPALScanLineShade').

'-Crtcaudioleak'
'+Crtcaudioleak'
     Enable/disable video to audio leak emulation ('CrtcAudioLeak=1',
     'CrtcAudioLeak=0').


File: vice.info,  Node: PET I/O extensions,  Next: PET system ROM,  Prev: CRTC Settings,  Up: PET-specific

7.7.3 PET I/O extension settings
--------------------------------

7.7.3.1 PET I/O extension resources
...................................

'PETREU'
     Boolean specifying whether PET REU emulation is enabled or not.

'PETREUfilename'
     String specifying the filename of the PET REU image.

'PETREUsize'
     Integer specifying the size of the emulated PET REU in KB. (128,
     512, 1024, 2048)

'PETDWW'
     Boolean specifying whether DWW emulation is enabled or not.

'PETDWWfilename'
     String specifying the filename of the DWW image RAM image.

'PETHRE'
     Boolean specifying whether HRE emulation is enabled or not.

'PETColour'
     Integer selecting the colour extension.  (0: off, 1: RGBI, 2:
     Analog)

'PETColourBG'
     Iteger specifying the analog colour background on PET 4032.
     (0..255)

'UserportDAC'
     Boolean specifying whether userport DAC emulation is enabled.

'SidCart'
     Boolean specifying whether SID Cart emulation is enabled or not.

'SidAddress'
     Integer that specifies the base address of the emulated SID chip.
     (0x8F00, 0xE900)

'SidClock'
     Integer specifying the clock rate used for the emulated SID chip.
     (0: C64, 1: PET)

7.7.3.2 PET I/O extension command-line options
..............................................

'-petreu'
'+petreu'
     Enable/disable the PET Memory Expansion Unit ('PETREU=1',
     'PETREU=0').

'-petreuimage <name>'
     Specify name of PET Ram and Expansion Unit image
     ('PETREUfilename').

'-petreuramsize <size in KB>'
     Size of the PET Ram and Expansion Unit ('PETREUsize').  (128, 512,
     1024, 2048)

'-userportdac'
'+userportdac'
     Enable/disable the userport DAC ('UserportDAC=1', 'UserportDAC=0').

'-petdww'
'+petdww'
     Enable/disable the PET DWW hi-res board (30xx models only)
     ('PETDWW=1', 'PETDWW=0').

'-petdwwimage <name>'
     Specify name of PET DWW RAM image ('PETDWWfilename').

'-pethre'
'+pethre'
     Enable/disable the PET HRE extension (model 8296 only) ('PETHRE=1',
     'PETHRE=0').

'-colour-rgbi'
     Enable the RGBI colour extension to PET 4032 ('PETColour=1').

'-colour-analog'
     Enable the analog colour extension to PET 4032 ('PETColour=2').

'-colour-analog-bg <Colour 0-255>'
     Select the analog colour background on PET 4032 ('PETColourBG').

'-sidcart'
'+sidcart'
     Enable/disable the SID Cartridge ('SidCart=1', 'SidCart=0').

'-sidcartaddress <address>'
     Specify address of the SID Cartridge ('SidAddress').  (0x8F00,
     0xE900)

'-sidcartclock <clock>'
     Specify clock of the SID Cartridge ('SidClock').  (0: C64, 1: PET)


File: vice.info,  Node: PET system ROM,  Next: PET diagnostic pin,  Prev: PET I/O extensions,  Up: PET-specific

7.7.4 PET system ROM settings
-----------------------------

7.7.4.1 PET system ROM resources
................................

'H6809RomAName'
'H6809RomBName'
'H6809RomCName'
'H6809RomDName'
'H6809RomEName'
'H6809RomFName'
     Strings specifying the filenames of the respective H6809 ROM
     images, relevant for the SuperPET.

7.7.4.2 PET system ROM command-line options
...........................................

'-kernal <name>'
     Specify filename of the Kernal ROM file ('KernalName').

'-basic <name>'
     Specify filename of the BASIC ROM file ('BasicName').

'-editor NAME'
     Specify the filename for the editor ROM file ('EditorName').

'-chargen <name>'
     Specify filename of the character generator ROM file
     ('ChargenName').

'-rom9 <name>'
     Specify the filename for the ROM image file for the $9*** cartridge
     area ('RomModule9Name').

'-romA <name>'
     Specify the filename for the ROM image file for the $A*** cartridge
     area ('RomModuleAName').

'-romB <name>'
     Specify the filename for the ROM image file for the $B*** cartridge
     area ('RomModuleBName').

'-6809romA <Name>'
     Specify 4K to 24K ROM file name at $A000 for 6809
     ('H6809RomAName').

'-6809romB <Name>'
     Specify 4K to 20K ROM file name at $B000 for 6809
     ('H6809RomBName').

'-6809romC <Name>'
     Specify 4K to 16K ROM file name at $C000 for 6809
     ('H6809RomCName').

'-6809romD <Name>'
     Specify 4K to 12K ROM file name at $D000 for 6809
     ('H6809RomDName').

'-6809romE <Name>'
     Specify 2K or 8K ROM file name at $E000 for 6809 ('H6809RomEName').

'-6809romF <Name>'
     Specify 4K ROM file name at $F000 for 6809 ('H6809RomFName').


File: vice.info,  Node: PET diagnostic pin,  Next: PET settings,  Prev: PET system ROM,  Up: PET-specific

7.7.5 The PET diagnostic pin
----------------------------

It is possible to enable or disable emulation of the PET diagnostic pin
via the '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.


File: vice.info,  Node: PET settings,  Next: Colour PET,  Prev: PET diagnostic pin,  Up: PET-specific

7.7.6 PET settings
------------------

7.7.6.1 PET resources
.....................

'MachineVideoStandard'
     Integer that specifies the video standard of the emulated machine
     (1: PAL, 2: NTSC).

'CPUswitch'
     Integer specifying the status of the SuperPET CPU switch (0: 6502,
     1: 6809, 2: Prog.)

7.7.6.2 PET command line options
................................

These are the commandline options specific for the PET models.

'-pal'
     Use PAL sync factor ('MachineVideoStandard=1').

'-ntsc'
     Use NTSC sync factor ('MachineVideoStandard=2').

'-model <model>'
     Specify the PET model you want to emulate ('Basic1', 'Basic1Chars',
     'ChargenName', 'KernalName', 'BasicName', 'EditorName',
     'RomModule9Name', 'RomModuleAName', 'RomModuleBName',
     'H6809RomAName', 'H6809RomBName', 'H6809RomCName', 'H6809RomDName',
     'H6809RomEName', 'H6809RomFName').  (2001, 3008, 3016, 3032, 3032B,
     4016, 4032, 4032B, 8032, 8096, 8296, SuperPET)

'-iosize <size>'
     Specify size of I/O in Bytes ('IOSize').  (256, 2048)

'-ramsize <size>'
     Specify size of RAM in KB ('RamSize').  (8, 16, 32, 96, 128)

'-videosize <size>'
     Specify video size ('VideoSize').  (0: Automatic from ROM, 40: 40
     columns, 80: 80 columns)

'-petram9'
'+petram9'
     Switch on/off RAM mapping at address $9000-$9FFF ('Ram9=1',
     'Ram9=0').

'-petramA'
'+petramA'
     Switch on/off RAM mapping at address $A000-$AFFF ('RamA=1',
     'RamA=0').

'-superpet'
'+superpet'
     Enable/disable SuperPET I/O and CPU emulation ('SuperPET').

'-cpu6502'
     Set SuperPET CPU switch to '6502' ('CPUswitch=0').

'-cpu6809'
     Set SuperPET CPU switch to '6809' ('CPUswitch=1').

'-cpuprog'
     Set SuperPET CPU switch to 'Prog' ('CPUswitch=2').

'-basic1'
'+basic1'
     Enable/disable patching the IEEE488 section of the PET2001 ROM when
     detected ('Basic1=1', 'Basic1=0').

'-basic1char'
'+basic1char'
     Enable/disable PET 2001 character generator ('Basic1Chars=1',
     'Basic1Chars=0').

'-eoiblank'
'+eoiblank'
     Enable/disable EOI blanking the screen ('EoiBlank=1',
     'EoiBlank=0').

'-diagpin'
'+diagpin'
     Enable/disable the diagnostic pin at the PET userport ('DiagPin=1',
     'DiagPin=0').


File: vice.info,  Node: Colour PET,  Next: PET colors,  Prev: PET settings,  Up: PET-specific

7.7.7 Colour PET
----------------

The Colour PET is a simple extension by Steve Gray
<http://www.6502.org/users/sjgray/projects/colourpet/>.  It exploits the
similarities and differences between the 4032 and 8032 models, to use
memory at $8800 as colour RAM.

There are two versions of the extension:

with digital colour (RGBI), which can select 16 foreground and 16
background colours for each character cell.  The 8 colour bits are used
as RGBI RGBI, with the most significant bits for the background, and the
least significant bits for the foreground.

With analog colour, which can use 256 foreground colours for each
character cell, the 8 colour bits are used as RRR GGG BB.


File: vice.info,  Node: PET colors,  Next: PET DWW high resolution graphics,  Prev: Colour PET,  Up: PET-specific

7.7.8 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 (*note Palette
files::) in the 'PaletteName' resource.  The menu provides the following
values:

   * 'green.vpl' (default, "green)"), the good old green-on-black
     feeling;
   * 'amber.vpl' ("amber"), an amber phosphor lookalike;
   * 'white.vpl' ("white"), simple white-on-black palette.


File: vice.info,  Node: PET DWW high resolution graphics,  Next: PET HRE (HiRes Emulator) high resolution graphics,  Prev: PET colors,  Up: PET-specific

7.7.9 DWW high resolution graphics
----------------------------------

The DWW, or Double-W (1), board is a high resolution graphics board for
PET models 30xx.  It attaches to the internal expansion connector.  It
would not physically fit in 20xx, 40xx or 80xx models because their
connectors are physically and logically different.  Apart from this, it
requires address space at $EC00-$EFFF, which makes it unfit to work in
40xx and 80xx models, which have only 256 bytes of I/O space at $E800.

The DWW board consists of 8 KB of RAM and a PIA to control various
options.  The RAM can be mapped either linearly at $9000-$AFFF, or
bank-switched in 8 banks of 8 KB each at $EC00-$EFFF.

It seems that in the demo programs, the BASIC versions like to POKE in
60200, where the machine language programs use $EB00.
60200 Port A or DDR A           $EB28
$EBx0 1  0 \
      2  1 - RAM block at $EC00 (0-7)
      4  2 /
      8  3 charrom         0 = off 1 = on
      16 4 hires           0 = on  1 = off
      32 5 extra charrom   0 = on  1 = off

60201 Control Register A: bit #3 (worth 4) controls if 60200
$EBx1 accesses the Data Direction Register A (0) or Port A (1).

60202 Port B or DDR B
$EBx2 0 = RAM is visible from $9000 - $AFFF
      1 = RAM is bank-switched in blocks of 1 K in $EC00 - $EFFF

      [Control Register B is never mentioned, so putting 1 in this
       address would access the DDR, creating an output line, which
       after RESET is default 0...]

Typical initialisation sequence:
    poke 60201,0        poke 60200,255          (all outputs)
    poke 60201,4        poke 60200,24 or 25 (16 + 8 + 1)

Demo programs on disk PBE-110A, 110B, 111A, and 111B. (PBE = PET Benelux
Exchange, the Dutch PET user group)

The memory mapping is a bit strange.  It seems each 1 K block contains
the pixeldata for 1 bit-line of each text line.  This is probably so
that the addressing of the RAM can borrow part of the addressing
logic/signals of the text screen.  (The screen addressing cycles through
0-39, then increases the line (= byte offset) which is fetched from the
character ROM; for the graphics, the screen position selects the byte in
a KB and the char ROM offset selects which KB of graphics RAM).

My notes say: to set a pixel:
RE = INT(Y/8): LY = Y - 8*RE    (or Y AND 7)
BY = INT(X/8): BI = X - 8*BY    (or X AND 7)

when memory mapped to $9000:
    L = 36864 + 1024 * LY + 40 * RE + BY
    POKE L, PEEK(L) OR 2^BI

when memory mapped to $EC00:
    POKE 60200,LY + 40 (or 8?)
    L = 60416 + RE * 40 + BY
    POKE L, PEEK(L) OR 2^BI

Unfortunately there is no logical means of expanding the memory to 16 K,
so even in an 80 columns PET the resolution will be the same.

   ---------- Footnotes ----------

   (1) Dubbel-W bord, designed by Ben de Winter and Pieter Wolvekamp


File: vice.info,  Node: PET HRE (HiRes Emulator) high resolution graphics,  Prev: PET DWW high resolution graphics,  Up: PET-specific

7.7.10 HRE high resolution graphics
-----------------------------------

This information comes from Michal Pleban <kontakt@michau.name>,
<http://www.cbm-ii.com>.

This is a short information about the HRE (HiRes Emulator) graphics
board for PET 8296.  This is a small board that is installed on the
mainboard into sockets for the CRTC and character ROM. It adds the
ability to display 512x256 graphics on the built-in monitor.

The board is accompanied with two extension ROMs:

   * 324992-02 HiRes Emulator (at $9000)
   * 324993-02 HiRes BASIC (at $A000)

The ROMs are initialized by the command 'SYS 36864'.

After that, the computer recognizes additional BASIC commands like
DISPLAY, PLOT and so on; these commands are identical to those of the
HiRes Graphics boards based on Thomson chips.  All BASIC programs
written for the HRG boards should also work on the HRE (albeit much
slower).

Upon initialization, the ROM code writes some routines into expansion
RAM as $8800 - they are used to manipulate the bitmap data.  The actual
bitmap is located in expansion RAM at addresses $A000-$DFFF, and is
organized linearly (first 64 bytes form the first display line, then
comes the next line and so on).

The RAM is accessed for reading by writing the value #$83 into $E888.
This is a register in the CRTC memory space that is intercepted by the
board and serves as a latch to drive jumpers on the 8296D mainboard.
Because the ROMs are banked out this way, all video memory manipulation
must happen with interrupts disabled.  Normal ROM operation is restored
by writing #$0F into $E888.

As usual with the 8296, the RAM can also be written even when the ROMs
are mapped normally.

The board is initialized into graphics mode by modifying the following
values in CRTC registers (it is done by the routine located at $8C1A):

   * Register $01 (horizontal displayed) = #$20
   * Register $02 (horizontal sync position) = original + #$02
   * Register $06 (vertical displayed) = #$20
   * Register $07 (vertical sync position) = original + #$04
   * Register $0C (RAM address high) = #$02

The last value causes the board to switch into graphics mode; former
values set up propoer screen dimensions for 512x256 display.


File: vice.info,  Node: CBM-II-specific,  Next: VSID-specific,  Prev: PET-specific,  Up: Machine-specific features

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


File: vice.info,  Node: CBM-II model,  Next: CBM-II commandline options,  Prev: CBM-II-specific,  Up: CBM-II-specific

7.8.1 Changing CBM-II model
---------------------------

With 'xcbm2' and '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):

'RamSize'
     Size of memory in kByte.  xcbm2: (128, 256, 512, 1024) xcbm5x0:
     (64, 128, 256, 512, 1024)

'Ram08'
     Boolean specifying whether the RAM should be mapped to the
     expansion ROM area at $0800-$0FFF or not.

'Ram1'
     Boolean specifying whether the RAM should be mapped to the
     expansion ROM area at $1000-$1FFF or not.

'Ram2'
     Boolean specifying whether the RAM should be mapped to the
     expansion ROM area at $2000-$3FFF or not.

'Ram4'
     Boolean specifying whether the RAM should be mapped to the
     expansion ROM area at $4000-$5FFF or not.

'Ram6'
     Boolean specifying whether the RAM should be mapped to the
     expansion ROM area at $6000-$7FFF or not.

'RamC'
     Boolean specifying whether the RAM should be mapped to the
     expansion ROM area at $C000-$CFFF or not.

'CartridgeReset'
     Boolean specifying whether the machine should be reset when a
     cartridge is changed.

'Cart1Name'
     String specifying the filename for the $1000-$1FFF expansion ROM
     file.  This file contains a 4k ROM dump.

'Cart2Name'
     String specifying the filename for the $2000-$3FFF expansion ROM
     file.  This file contains an 8k ROM dump.

'Cart4Name'
     String specifying the filename for the $4000-$5FFF expansion ROM
     file.  This file contains an 8k ROM dump.

'Cart6Name'
     String specifying the filename for the $6000-$7FFF expansion ROM
     file.  This file contains an 8k ROM dump.

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

'ChargenName'
     String specifying the name of the character generator ROM (default
     for xcbm2: 'chargen.600', default for xcbm5x0: 'chargen.500').

'KernalName'
     String specifying the name of the Kernal ROM (default for xcbm2:
     'kernal', default for xcbm5x0: 'kernal.500').

'BasicName'
     String specifying the name of the Basic ROM (default for xcbm2:
     'basic.128', default for xcbm5x0: 'basic.500').

'MachineVideoStandard'
     Integer that specifies the video standard of the emulated machine
     (1: PAL, 2: NTSC).

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:

   * C510 PAL or NTSC (128k RAM)
   * C610 PAL or NTSC (128k RAM)
   * C620 (256k RAM)
   * C620+ (1024k RAM, expanded) PAL or NTSC
   * C710 (128k RAM) NTSC
   * C720 (256k RAM) NTSC
   * C720+ (1024k RAM, expanded) NTSC

Notice that this will *reset the emulated machine*.

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
'-model' command-line option: for example, 'xcbm2 -model 610' will
emulate a CBM 610 while 'xcbm2 -model 620' will emulate a CBM 620.

7.8.2 CBM-II system ROM settings
--------------------------------

7.8.2.1 CBM-II system ROM resources
...................................

7.8.2.2 CBM-II system ROM command line options
..............................................

'-kernal <name>'
     Specify the name of the Kernal ROM file ('KernalName').

'-basic <name>'
     Specify the name of the Basic ROM file ('BasicName').

'-chargen <name>'
     Specify the filename for the character generator ROM file
     ('ChargenName').

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

'-cartreset'
'+cartreset'
     Reset/do not reset machine if a cartridge is attached or detached
     ('CartridgeReset=1', 'CartridgeReset=0').

'-cart1 <name>'
     Specify the filename for the ROM image file for the cartridge area
     $1000-$1FFF ('Cart1Name').

'-cart2 <name>'
     Specify the filename for the ROM image file for the cartridge area
     $2000-$2FFF ('Cart2Name').

'-cart4 <name>'
     Specify the filename for the ROM image file for the cartridge area
     $4000-$5FFF ('Cart4Name').

'-cart6 <name>'
     Specify the filename for the ROM image file for the cartridge area
     $6000-$7FFF ('Cart6Name').


File: vice.info,  Node: CBM-II commandline options,  Next: CBM-II colors,  Prev: CBM-II model,  Up: CBM-II-specific

7.8.3 CBM-II command line options
---------------------------------

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

'-pal'
     Use PAL sync factor ('MachineVideoStandard=1').

'-ntsc'
     Use NTSC sync factor ('MachineVideoStandard=2').

'-ramsize <ramsize>'
     Specify size of RAM ('RamSize').  xcbm2: (128, 256, 512, 1024)
     xcbm5x0: (64, 128, 256, 512, 1024)

'-ram08'
'+ram08'
     Enable/disable RAM mapping in bank 15 at address $0800-$0FFF
     ('Ram08=1', 'Ram08=0').

'-ram1'
'+ram1'
     Enable/disable RAM mapping in bank 15 at address $1000-$1FFF
     ('Ram1=1', 'Ram1=0').

'-ram2'
'+ram2'
     Enable/disable RAM mapping in bank 15 at address $2000-$3FFF
     ('Ram2=1', 'Ram2=0').

'-ram4'
'+ram4'
     Enable/disable RAM mapping in bank 15 at address $4000-$5FFF
     ('Ram4=1', 'Ram4=0').

'-ram6'
'+ram6'
     Enable/disable RAM mapping in bank 15 at address $6000-$7FFF
     ('Ram6=1', 'Ram6=0').

'-ramC'
'+ramC'
     Enable/disable RAM mapping in bank 15 at address $C000-$CFFF
     ('RamC=1', 'RamC=0').

'-model <modelnumber>'
     Specify CBM-II model to emulate ('ModelLine',
     'MachineVideoStandard', 'RamSize', 'KernalName', 'BasicName',
     'ChargenName').  xcbm2: (610, 620, 620+, 710, 720, 720+) xcbm5x0:
     (510)


File: vice.info,  Node: CBM-II colors,  Prev: CBM-II commandline options,  Up: CBM-II-specific

7.8.4 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 (*note Palette
files::) in the 'PaletteName' resource.  The menu provides the following
values:

   * 'green.vpl' (default, "green"), the good old green-on-black
     feeling;
   * 'amber.vpl' ("amber"), an amber phosphor lookalike;
   * 'white.vpl' ("white"), simple white-on-black palette.


File: vice.info,  Node: VSID-specific,  Prev: CBM-II-specific,  Up: Machine-specific features

7.9 VSID-specific commands and settings
=======================================

7.9.1 VSID settings
-------------------

7.9.1.1 VSID resources
......................

'PSIDKeepEnv'
     Boolean that specifies whether to override PSID settings for Video
     standard and SID model.

'PSIDTune'
     Integer that specifies the currently played sub tune.

'HVSCRoot'
     String specifying the location of the HVSC "C64Music" directory.

'ChargenName'
     String specifying the name of the character generator ROM (default
     'chargen').

'KernalName'
     String specifying the name of the Kernal ROM (default 'kernal').

'BasicName'
     String specifying the name of the Basic ROM (default 'basic').

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

     '0'
          Kernal revision 0;
     '3'
          Kernal revision 3;
     'sx'
     '67'
          Commodore SX-64 ROM;
     '100'
     '4064'
          Commodore 4064 (also known as "PET64" or "Educator 64") ROM.

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

7.9.1.2 VSID command-line options
.................................

'-keepenv'
     Override PSID settings for Video standard and SID model
     ('PSIDKeepEnv=1').

'-tune <number>'
     Specify PSID tune <number> ('PSIDTune').

'-hvsc-root <path>'
     Specify the location of the HVSC "C64Music" directory.
     ('HVSCRoot').

'-chargen <name>'
     Specify name of character generator ROM image ('ChargenName').

'-kernal <name>'
     Specify name of the Kernal ROM image ('KernalName').

'-basic <name>'
     Specify name of the Basic ROM image ('BasicName').

'-pal'
     Use PAL sync factor ('MachineVideoStandard=1').

'-ntsc'
     Use NTSC sync factor ('MachineVideoStandard=2').

'-ntscold'
     Use old NTSC sync factor ('MachineVideoStandard=3').

'-paln'
     Use PAL-N sync factor ('MachineVideoStandard=4').


File: vice.info,  Node: Platform-specific features,  Next: Snapshots,  Prev: Machine-specific features,  Up: Top

8 Platform-specific features
****************************

This section lists the settings and commands that are platform specific.

* Menu:

* SDL-specific features::
* GTK3 specific features::


File: vice.info,  Node: SDL-specific features,  Next: GTK3 specific features,  Up: Platform-specific features

8.1 SDL-specific features
=========================

This section lists the settings and commands that are common and
specific to SDL, and are thus not present in other platforms.

8.1.1 SDL specific resources
----------------------------

'HotkeyFile'
     String specifying the name of the hotkey file (all emulators except
     vsid).

'MenuKey'
     Integer specifying the keycode for activating the SDL menu.

'MenuKeyUp'
     Integer specifying the keycode for 'up' in the SDL menu.

'MenuKeyDown'
     Integer specifying the keycode for 'down' in the SDL menu.

'MenuKeyLeft'
     Integer specifying the keycode for 'left' in the SDL menu.

'MenuKeyRight'
     Integer specifying the keycode for 'right' in the SDL menu.

'MenuKeyPageUp'
     Integer specifying the keycode for 'page up' in the SDL menu.

'MenuKeyPageDown'
     Integer specifying the keycode for 'page down' in the SDL menu.

'MenuKeyHome'
     Integer specifying the keycode for 'home' in the SDL menu.

'MenuKeyEnd'
     Integer specifying the keycode for 'end' in the SDL menu.

'MenuKeySelect'
     Integer specifying the keycode for 'select' in the SDL menu.

'MenuKeyCancel'
     Integer specifying the keycode for 'cancel' in the SDL menu.

'MenuKeyExit'
     Integer specifying the keycode for 'exit' in the SDL menu.

'MenuKeyMap'
     Integer specifying the keycode for 'map' in the SDL menu.

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

'ConfirmOnExit'
     Boolean specifying whether to show a confirmation dialog on exit.

'SDLStatusbar'
     Boolean to enable/disable the statusbar (all emulators except
     vsid).

'SDLBitdepth'
     Integer specifying the bitdepth used.  (0: current, 8, 15, 16, 24,
     32)

'SDLLimitMode'
     Integer specifying the resolution limit mode.  (0: off, 1: max, 2:
     fixed)

'SDLCustomWidth'
     Integer specifying the custom resolution width.

'SDLCustomHeight'
     Integer specifying the custom resolution height.

'KbdStatusbar'
     Boolean specifying whether the keyboard-status bar is enabled.

'SDL2Renderer'
     String specifying the preferred SDL2 renderer.

'SDLWindowWidth'
     Integer specifying the SDL window width.

'SDLWindowHeight'
     Integer specifying the SDL window height.

'SDLGLFilter'
     Integer specifying the OpenGL filtering mode.

'JoyDevice1'
     Integer specifying which joystick device the emulator should use
     for the emulation of joystick 1 (all emulators except xcbm2, xpet
     and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4:
     Joystick (only if joystick support was present in the compile time
     SDL library))

'JoyDevice2'
     Integer specifying which joystick device the emulator should use
     for the emulation of joystick 2 (all emulators except xcbm2, xpet,
     xvic and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4:
     Joystick (only if joystick support was present in the compile time
     SDL library))

'JoyDevice3'
     Integer specifying which joystick device the emulator should use
     for the emulation of extra joystick 1 (all emulators except xcbm5x0
     and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4:
     Joystick (only if joystick support was present in the compile time
     SDL library))

'JoyDevice4'
     Integer specifying which joystick device the emulator should use
     for the emulation of extra joystick 2 (all emulators except
     xcbm5x0, xplus4 and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3:
     Keyset 2, 4: Joystick (only if joystick support was present in the
     compile time SDL library))

'CrtcSDLFullscreenMode'
     Integer specifying the fullscreen mode (xcbm2 and xpet only).

'CrtcHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (xcbm2 and xpet only).

'CrtcFullscreenDevice'
     String specifying the fullscreen device (xcbm2 and xpet only).

'CrtcFullscreen'
     Boolean specifying whether to use fullscreen mode or not (xcbm2 and
     xpet only).

'CrtcFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (xcbm2 and xpet only).

'TEDSDLFullscreenMode'
     Integer specifying the fullscreen mode (xplus4 only).

'TEDHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (xplus4 only).

'TEDFullscreenDevice'
     String specifying the fullscreen device (xplus4 only).

'TEDFullscreen'
     Boolean specifying whether to use fullscreen mode or not (xplus4
     only).

'TEDFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (xplus4 only).

'VDCSDLFullscreenMode'
     Integer specifying the fullscreen mode (x128 only).

'VDCHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (x128 only).

'VDCFullscreenDevice'
     String specifying the fullscreen device (x128 only).

'VDCFullscreen'
     Boolean specifying whether to use fullscreen mode or not (x128
     only).

'VDCFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (x128 only).

'VICSDLFullscreenMode'
     Integer specifying the fullscreen mode (xvic only).

'VICHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (xvic only).

'VICFullscreenDevice'
     String specifying the fullscreen device (xvic only).

'VICFullscreen'
     Boolean specifying whether to use fullscreen mode or not (xvic
     only).

'VICFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (xvic only).

'VICIISDLFullscreenMode'
     Integer specifying the fullscreen mode (all emulators except xcbm2,
     xpet, xplus4, xvic and vsid).

'VICIIHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (all emulators except xcbm2, xpet, xplus4, xvic and vsid).

'VICIIFullscreenDevice'
     String specifying the fullscreen device (all emulators except
     xcbm2, xpet, xplus4, xvic and vsid).

'VICIIFullscreen'
     Boolean specifying whether to use fullscreen mode or not (all
     emulators except xcbm2, xpet, xplus4, xvic and vsid).

'VICIIFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (all emulators except xcbm2, xpet, xplus4, xvic and
     vsid).

The following resources are only present if the OpenGL library is
present and used at compile time.

'AspectRatio'
     String/float specifying the aspect ratio.  (0.5-2.0)

'SDLGLAspectMode'
     Integer specifying the OpenGL aspect mode.  (0: off, 1: custom, 2:
     true)

'SDLGLFlipX'
     Boolean to enable/disable OpenGL horizontal screen flip.

'SDLGLFlipY'
     Boolean to enable/disable OpenGL vertical screen flip.

The following resources are only present if the SDL library has joystick
support at compile time and applies to all emulators except vsid.

'JoyMapFile'
     String specifying the name of the joystick map file.

'JoyThreshold'
     Integer specifying the joystick threshold.  (0..32767)

'JoyFuzz'
     Integer specifying the joystick fuzz.  (0..32767)

8.1.2 SDL specific command-line options
---------------------------------------

'-hotkeyfile <name>'
     Set the hotkey file name ('HotkeyFile') (all emulators except
     vsid).

'-menukey <key>'
     Set the keycode of the SDL menu activation key ('MenuKey').

'-menukeyup <key>'
     Set the keycode of the 'up' key in the SDL menu ('MenuKeyUp').

'-menukeydown <key>'
     Set the keycode of the 'down' key in the SDL menu ('MenuKeyDown').

'-menukeyleft <key>'
     Set the keycode of the 'left' key in the SDL menu ('MenuKeyLeft').

'-menukeyright <key>'
     Set the keycode of the 'right' key in the SDL menu
     ('MenuKeyRight').

'-menukeypageup <key>'
     Set the keycode of the 'page up' key in the SDL menu
     ('MenuKeyPageUp').

'-menukeypagedown <key>'
     Set the keycode of the 'page down' key in the SDL menu
     ('MenuKeyPageDown').

'-menukeyhome <key>'
     Set the keycode of the 'home' key in the SDL menu ('MenuKeyHome').

'-menukeyend <key>'
     Set the keycode of the 'end' key in the SDL menu ('MenuKeyEnd').

'-menukeyselect <key>'
     Set the keycode of the 'select' key in the SDL menu
     ('MenuKeySelect').

'-menukeycancel <key>'
     Set the keycode of the 'cancel' key in the SDL menu
     ('MenuKeyCancel').

'-menukeyexit <key>'
     Set the keycode of the 'exit' key in the SDL menu ('MenuKeyExit').

'-menukeymap <key>'
     Set the keycode of the 'map' key in the SDL menu ('MenuKeyMap').

'-saveres'
'+saveres'
     Enable/disable automatic saving of settings on exit
     ('SaveResourcesOnExit=1', 'SaveResourcesOnExit=0').

'-confirmonexit'
     Confirm quitting VICE ('ConfirmOnExit=1').
'+confirmonexit'
     Never confirm quitting VICE ('ConfirmOnExit=0').

'-statusbar'
'+statusbar'
     Enable/disable the statusbar ('SDLStatusbar=1', 'SDLStatusbar=0')
     (all emulators except vsid).

'-sdlbitdepth <bpp>'
     Set the display bitdepth ('SDLBitdepth').  (0: current, 8, 15, 16,
     24, 32)

'-sdllimitmode <mode>'
     Set the resolution limit mode ('SDLLimitMode').  (0: off, 1: max,
     2: fixed)

'-sdlcustomw <width>'
     Set the custom resolution width ('SDLCustomWidth').

'-sdlcustomh <height>'
     Set the custom resolution height ('SDLCustomHeight').

'-sdlinitialw <width>'
     Set initial window width.

'-sdlinitialh <height>'
     Set initial window height.

'-kbdstatusbar'
'+kbdstatusbar'
     Enable/Disable keyboard-status bar (when status bar is enabled)
     ('KbdStatusbar=1', 'KbdStatusbar=0').

'-sdlglfilter <mode>'
     Set OpenGL filtering mode (0 = nearest, 1 = linear)
     ('SDLGLFilter').

'-sdl2renderer <renderer name>'
     Set the preferred SDL2 renderer ('SDL2Renderer').

'-joydev1 <0-3> / <0-4>'
     Set the device for joystick emulation of port 1 ('JoyDevice1') (all
     emulators except xcbm2, xpet and vsid).  (0: None, 1: Numpad, 2:
     Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was
     present in the compile time SDL library))

'-joydev2 <0-3> / <0-4>'
     Set the device for joystick emulation of port 2 ('JoyDevice2') (all
     emulators except xcbm2, xpet, xvic and vsid).  (0: None, 1: Numpad,
     2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was
     present in the compile time SDL library))

'-extrajoydev1 <0-3> / <0-4>'
     Set device for extra joystick port 1 ('JoyDevice3') (all emulators
     except xcbm5x0 and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3:
     Keyset 2, 4: Joystick (only if joystick support was present in the
     compile time SDL library))

'-extrajoydev2 <0-3> / <0-4>'
     Set device for extra joystick port 2 ('JoyDevice4') (all emulators
     except xcbm5x0, xplus4 and vsid).  (0: None, 1: Numpad, 2: Keyset
     1, 3: Keyset 2, 4: Joystick (only if joystick support was present
     in the compile time SDL library))

'-CRTCSDLfullmode <Mode>'
     Set the fullscreen mode ('CrtcSDLFullscreenMode') (xcbm2 and xpet
     only).

'-CRTChwscale'
'+CRTChwscale'
     Enable/Disable hardware scaling ('CrtcHwScale=1', 'CrtcHwScale=0')
     (xcbm2 and xpet only).

'-CRTCfulldevice <device>'
     Select fullscreen device ('CrtcFullscreenDevice') (xcbm2 and xpet
     only).

'-CRTCfull'
'+CRTCfull'
     Enable/Disable fullscreen ('CrtcFullscreen=1', 'CrtcFullscreen=0')
     (xcbm2 and xpet only).

'-TEDSDLfullmode <Mode>'
     Set the fullscreen mode ('TEDSDLFullscreenMode') (xplus4 only).

'-TEDhwscale'
'+TEDhwscale'
     Enable/Disable hardware scaling ('TEDHwScale=1', 'TEDHwScale=0')
     (xplus4 only).

'-TEDfulldevice <device>'
     Select fullscreen device ('TEDFullscreenDevice') (xplus4 only).

'-TEDfull'
'+TEDfull'
     Enable/Disable fullscreen ('TEDFullscreen=1', 'TEDFullscreen=0')
     (xplus4 only).

'-VDCSDLfullmode <Mode>'
     Set the fullscreen mode ('VDCSDLFullscreenMode') (x128 only).

'-VDChwscale'
'+VDChwscale'
     Enable/Disable hardware scaling ('VDCHwScale=1', 'VDCHwScale=1')
     (x128 only).

'-VDCfulldevice <device>'
     Select fullscreen device ('VDCFullscreenDevice') (x128 only).

'-VDCfull'
'+VDCfull'
     Enable/Disable fullscreen ('VDCFullscreen=1', 'VDCFullscreen=0')
     (x128 only).

'-VICSDLfullmode <Mode>'
     Set the fullscreen mode ('VICSDLFullscreenMode') (xvic only).

'-VIChwscale'
'+VIChwscale'
     Enable/Disable hardware scaling ('VICHwScale=1', 'VICHwScale=0')
     (xvic only).

'-VICfulldevice <device>'
     Select fullscreen device ('VICFullscreenDevice') (xvic only).

'-VICfull'
'+VICfull'
     Enable/Disable fullscreen ('VICFullscreen=1', 'VICFullscreen=0')
     (xvic only).

'-VICIISDLfullmode <Mode>'
     Set the fullscreen mode ('VICIISDLFullscreenMode') (all emulators
     except xcbm2, xpet, xplus4, xvic and vsid).

'-VICIIhwscale'
'+VICIIhwscale'
     Enable/Disable hardware scaling ('VICIIHwScale=1',
     'VICIIHwScale=0') (all emulators except xcbm2, xpet, xplus4, xvic
     and vsid).

'-VICIIfulldevice <device>'
     Select fullscreen device ('VICIIFullscreenDevice') (all emulators
     except xcbm2, xpet, xplus4, xvic and vsid).

'-VICIIfull'
'+VICIIfull'
     Enable/Disable fullscreen ('VICIIFullscreen=1',
     'VICIIFullscreen=0') (all emulators except xcbm2, xpet, xplus4,
     xvic and vsid).

The following command-line options are only present if the OpenGL
library is present and used at compile time.

'-aspect <aspect ratio>'
     Set the aspect ratio ('AspectRatio').  (0.5-2.0)

'-sdlaspectmode <mode>'
     Set the aspect mode ('SDLGLAspectMode').  (0: off, 1: custom, 2:
     true)

'-sdlflipx'
'+sdlflipx'
     Enable/disable OpenGL horizontal screen flip ('SDLGLFlipX=1',
     'SDLGLFlipX=0').

'-sdlflipy'
'+sdlflipy'
     Enable/disable OpenGL vertical screen flip ('SDLGLFlipY=1',
     'SDLGLFlipY=0').

The following command-line options are only present if the SDL library
has joystick support at compile time and applies to all emulators except
vsid.

'-joymap <name>'
     Set the joystick map file name ('JoyMapFile').

'-joythreshold <0-32767>'
     Set the joystick threshold ('JoyThreshold').

'-joyfuzz <0-32767>'
     Set the joystick fuzz ('JoyFuzz').


File: vice.info,  Node: GTK3 specific features,  Next: SDL-specific features,  Prev: Platform-specific features

8.2 GTK3 specific features
==========================

This section lists the settings and commands that are common and
specific to Unix, and are thus not present in other platforms.

8.2.1 GTK3 specific resources
-----------------------------

'GTKBackend'
     Rendering backend to use for the Gtk3 UI (0: Cairo, 1: OpenGL).

'GTKFilter'
     Rendering filter to use for the Gtk3 UI (0: Nearest neighbor, 1:
     Bilinear interpolation).

'AspectRatio'
     String/float specifying the aspect ratio (0.5-2.0).

'KeepAspectRatio'
     Boolean specifying whether the aspect ratio of the output window
     should be preserved.  (0: free scaling, 1: scale with fixed aspect
     ratio)

'TrueAspectRatio'
     Boolean specifying whether to use the true (non square pixels)
     aspect ratio.

'StartMinimized'
     Boolean specifying whether the emulator should start minimized

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

'ConfirmOnExit'
     Boolean specifying whether to show a confirmation dialog on exit.

'DisplayDepth'
     Integer specifying the depth of the host display.  The value '0'
     (the default) causes the emulator to autodetect it (all emulators
     except vsid).  (0..32)

'Window0Width'
'Window0Height'
'Window0Xpos'
'Window0Ypos'
     Integers specifying the position and size of the (first) emulator
     window (all emulators except vsid).

'Window1Width'
'Window1Height'
'Window1Xpos'
'Window1Ypos'
     Integers specifying the position and size of the (second) emulator
     window (x128 only).

'CrtcHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (xcbm2 and xpet only).

'CrtcFullscreenDevice'
     String specifying the fullscreen device (xcbm2 and xpet only).

'CrtcFullscreen'
     Boolean specifying whether to use fullscreen mode or not (xcbm2 and
     xpet only).

'CrtcFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (xcbm2 and xpet only).

'TEDHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (xplus4 only).

'TEDFullscreenDevice'
     String specifying the fullscreen device (xplus4 only).

'TEDFullscreen'
     Boolean specifying whether to use fullscreen mode or not (xplus4
     only).

'TEDFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (xplus4 only).

'VDCHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (x128 only).

'VDCFullscreenDevice'
     String specifying the fullscreen device (x128 only).

'VDCFullscreen'
     Boolean specifying whether to use fullscreen mode or not (x128
     only).

'VDCFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (x128 only).

'VICHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (xvic only).

'VICFullscreenDevice'
     String specifying the fullscreen device (xvic only).

'VICFullscreen'
     Boolean specifying whether to use fullscreen mode or not (xvic
     only).

'VICFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (xvic only).

'VICIIHwScale'
     Boolean specifying whether to enable or disable hardware scaling
     (all emulators except xcbm2, xpet, xplus4, xvic and vsid).

'VICIIFullscreenDevice'
     String specifying the fullscreen device (all emulators except
     xcbm2, xpet, xplus4, xvic and vsid).

'VICIIFullscreen'
     Boolean specifying whether to use fullscreen mode or not (all
     emulators except xcbm2, xpet, xplus4, xvic and vsid).

'VICIIFullscreenStatusbar'
     Boolean specifying whether to show the status bar in fullscreen
     mode or not (all emulators except xcbm2, xpet, xplus4, xvic and
     vsid).

'JoyDevice1'
     Integer specifying which joystick device the emulator should use
     for the emulation of joystick 1 (all emulators except xcbm2, xpet
     and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4:
     Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7:
     Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10:
     Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13:
     USB joystick 2)

'JoyDevice2'
     Integer specifying which joystick device the emulator should use
     for the emulation of joystick 2 (all emulators except xcbm2, xpet,
     xvic and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4:
     Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7:
     Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10:
     Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13:
     USB joystick 2)

'JoyDevice3'
     Integer specifying which joystick device the emulator should use
     for the emulation of extra joystick 1 (all emulators except xcbm5x0
     and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4:
     Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7:
     Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10:
     Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13:
     USB joystick 2)

'JoyDevice4'
     Integer specifying which joystick device the emulator should use
     for the emulation of extra joystick 2 (all emulators except
     xcbm5x0, xplus4 and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3:
     Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog
     joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog
     joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB
     joystick 1, 13: USB joystick 2)

The available joysticks might differ depending on operating system and
joystick support in the OS.

'Devices 4..9'
     Only available if joystick support is available at compile time.

'Devices 10 and 11'
     Only available if digital joystick support is available at compile
     time.

'Devices 12 and 13'
     Only available if USB joystick support is available at compile
     time.

The following resources are only available if MIDI support is available
at compile time.

'MIDIInDev'
     String specifying the MIDI input device (x64, x64sc, xscpu64, x128
     and xvic only).

'MIDIOutDev'
     String specifying the MIDI output device (x64, x64sc, xscpu64, x128
     and xvic only).

The following resource is only available if MIDI support and ALSA
support is available at compile time.

'MIDIDriver'
     Enum specifying the MIDI driver (x64, x64sc, xscpu64, x128 and xvic
     only).  (0: OSS, 1: ALSA)

8.2.2 GTK3 specific command-line options
----------------------------------------

'-saveres'
'+saveres'
     Enable/disable automatic saving of settings on exit
     ('SaveResourcesOnExit=1', 'SaveResourcesOnExit=0').

'-minimized'
'+minimized'
     Start/Do not start with minimized window ('StartMinimized=1',
     'StartMinimized=0').

'-aspect <aspect ratio>'
     Set the aspect ratio ('AspectRatio').  (0.5-2.0)

'-gtkbackend <backend>'
     Set the Gtk3 rendering backend ('GTKBackend') (0: Cairo, 1: OpenGL)

'-gtkfilter <filter>'
     ('GTKFilter') (0: Nearest neighbor, 1: Bilinear interpolation)

'-keepaspect'
     Enable keeping of the aspect ratio when scaling
     ('KeepAspectRatio=1').
'+keepaspect'
     Disable keeping of the aspect ratio when scaling (freescaling)
     ('KeepAspectRatio=0').

'-trueaspect'
'+trueaspect'
     Enable/disable whether to use the true (non square pixels) aspect
     ratio ('TrueAspectRatio=1', ('TrueAspectRatio=0').

'-confirmonexit'
     Confirm quitting VICE ('ConfirmOnExit=1').
'+confirmonexit'
     Never confirm quitting VICE ('ConfirmOnExit=0').

'-fullscreen'
'+fullscreen'
     Enable/disable fullscreen mode ('UseFullscreen=1',
     ('UseFullscreen=0') (all emulators except vsid).

'-CRTChwscale'
'+CRTChwscale'
     Enable/Disable hardware scaling ('CrtcHwScale=1', 'CrtcHwScale=0')
     (xcbm2 and xpet only).

'-CRTCfulldevice <device>'
     Select fullscreen device ('CrtcFullscreenDevice') (xcbm2 and xpet
     only).

'-TEDhwscale'
'+TEDhwscale'
     Enable/Disable hardware scaling ('TEDHwScale=1', 'TEDHwScale=0')
     (xplus4 only).

'-TEDfulldevice <device>'
     Select fullscreen device ('TEDFullscreenDevice') (xplus4 only).

'-VDChwscale'
'+VDChwscale'
     Enable/Disable hardware scaling ('VDCHwScale=1', 'VDCHwScale=1')
     (x128 only).

'-VIChwscale'
'+VIChwscale'
     Enable/Disable hardware scaling ('VICHwScale=1', 'VICHwScale=0')
     (xvic only).

'-VICfulldevice <device>'
     Select fullscreen device ('VICFullscreenDevice') (xvic only).

'-VICIIhwscale'
'+VICIIhwscale'
     Enable/Disable hardware scaling ('VICIIHwScale=1',
     'VICIIHwScale=0') (all emulators except xcbm2, xpet, xplus4, xvic
     and vsid).

'-VICIIfulldevice <device>'
     Select fullscreen device ('VICIIFullscreenDevice') (all emulators
     except xcbm2, xpet, xplus4, xvic and vsid).

'-joydev1 <0-3> / <0-9> / <0-11> / <0-13>'
     Set the device for joystick emulation of port 1 ('JoyDevice1') (all
     emulators except xcbm2, xpet and vsid).  (0: None, 1: Numpad, 2:
     Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2,
     6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5,
     9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick
     2, 12: USB joystick 1, 13: USB joystick 2)

'-joydev2 <0-3> / <0-9> / <0-11> / <0-13>'
     Set the device for joystick emulation of port 2 ('JoyDevice2') (all
     emulators except xcbm2, xpet, xvic and vsid).  (0: None, 1: Numpad,
     2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick
     2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick
     5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital
     joystick 2, 12: USB joystick 1, 13: USB joystick 2)

'-extrajoydev1 <0-3> / <0-9> / <0-11> / <0-13>'
     Set device for extra joystick port 1 ('JoyDevice3') (all emulators
     except xcbm5x0 and vsid).  (0: None, 1: Numpad, 2: Keyset 1, 3:
     Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog
     joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog
     joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB
     joystick 1, 13: USB joystick 2)

'-extrajoydev2 <0-3> / <0-9> / <0-11> / <0-13>'
     Set device for extra joystick port 2 ('JoyDevice4') (all emulators
     except xcbm5x0, xplus4 and vsid).  (0: None, 1: Numpad, 2: Keyset
     1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6:
     Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9:
     Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2,
     12: USB joystick 1, 13: USB joystick 2)

The available joysticks might differ depending on operating system and
joystick support in the OS.

'Devices 4..9'
     Only available if joystick support is available at compile time.

'Devices 10 and 11'
     Only available if digital joystick support is available at compile
     time.

'Devices 12 and 13'
     Only available if USB joystick support is available at compile
     time.

The following command-line options are only available if MIDI support is
available at compile time.

'-midiin <name>'
     Specify MIDI-In device ('MIDIInDev') (x64, x64sc, xscpu64, x128 and
     xvic only).

'-midiout <name>'
     Specify MIDI-Out device ('MIDIOutDev') (x64, x64sc, xscpu64, x128
     and xvic only).

The following command-line option is only available if MIDI support and
ALSA support is available at compile time.

'-mididrv <driver>'
     Specify MIDI driver ('MIDIDriver') (x64, x64sc, xscpu64, x128 and
     xvic only).  (0: OSS, 1: ALSA)


File: vice.info,  Node: Snapshots,  Next: Monitor,  Prev: Platform-specific features,  Up: Top

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


File: vice.info,  Node: Snapshot usage,  Next: Snapshot format,  Prev: Snapshots,  Up: Snapshots

9.1 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 '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 'M-F11' key and
reloaded by pressing the 'M-F10' key.


File: vice.info,  Node: Snapshot format,  Prev: Snapshot usage,  Up: Snapshots

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


File: vice.info,  Node: Emulator modules,  Next: Module formats,  Prev: Snapshot format,  Up: Snapshot format

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


File: vice.info,  Node: x64 modules,  Next: x128 modules,  Prev: Emulator modules,  Up: Emulator modules

9.2.1.1 x64 modules
...................

The modules in the x64 emulator are:

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

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.


File: vice.info,  Node: x128 modules,  Next: xvic modules,  Prev: x64 modules,  Up: Emulator modules

9.2.1.2 x128 modules
....................

The modules in the x128 emulator are:

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

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.


File: vice.info,  Node: xvic modules,  Next: xpet modules,  Prev: x128 modules,  Up: Emulator modules

9.2.1.3 xvic modules
....................

The modules in the xvic emulator are:

Name    Type                          Description
MAINCPU 6502                          The Main CPU
VIC20MEMMemory                        Holds the RAM contents of the
                                      VIC20.
VIC20ROMROM images                    Holds the ROM images of the VIC20,
                                      including possibly attached
                                      cartridges
VIC-I   656*                          The VIC-I of the VIC20
VIA1    6522                          The VIA for the interrupts and the
                                      keyboard
VIA2    6522                          The VIA for the userport, IEC-bus
                                      and RS232.
*       Drive modules                 The emulated drive(s) have their
                                      own modules *note Drive modules::


File: vice.info,  Node: xpet modules,  Next: xcbm2 and xcbm5x0 modules,  Prev: xvic modules,  Up: Emulator modules

9.2.1.4 xpet modules
....................

The modules in the xpet emulator are:

Name    Type                          Description
MAINCPU 6502                          The Main CPU
PETMEM  Memory                        Holds the RAM contents of the PET.
PETROM  ROM images                    Holds the ROM images of the PET,
                                      including possibly attached
                                      cartridges
CRTC    6545                          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.
PIA1    6520                          The PIA for the interrupts, tape
                                      and the keyboard
PIA2    6520                          The PIA for the IEEE488-bus
VIA     6522                          The VIA for IEEE488, userport,
                                      sound
ACIA1   6551                          The ACIA for the SuperPET. This
                                      module is optional.
DWWPIA  6520                          The PIA for the DWW hires board.
CPU6809 6809                          The extra CPU in the SuperPET.
                                      This module is optional.
*       Drive modules                 The emulated drive(s) have their
                                      own modules *note Drive modules::


File: vice.info,  Node: xcbm2 and xcbm5x0 modules,  Next: Drive modules,  Prev: xpet modules,  Up: Emulator modules

9.2.1.5 xcbm2 and xcbm5x0 modules
.................................

The modules in the xcbm2 and xcbm5x0 emulators are:

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


File: vice.info,  Node: Drive modules,  Prev: xcbm2 and xcbm5x0 modules,  Up: Emulator modules

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

Name    Type                          Description
*CPU    6502                          The Drive 0 CPU
*       *                             *


File: vice.info,  Node: Module formats,  Prev: Emulator modules,  Up: Snapshot format

9.2.2 Module formats
--------------------

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

The single chip modules contain the chip state, and sometimes additional
state of the emulator.  In the past we tried to make the format as
implementation-independent as possible, to allow reuse of snapshots in
later versions of the emulator, that however proved to be very
impractical and insanely hard to maintain.

* Menu:

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


File: vice.info,  Node: Module Terminology,  Next: Module framework,  Prev: Module formats,  Up: Module formats

9.2.2.1 Terminology
...................

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

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

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.


File: vice.info,  Node: Module framework,  Next: CPU 6502 module,  Prev: Module Terminology,  Up: Module formats

9.2.2.2 Module framework
........................

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

Type           Name                   Description
19 BYTE        MAGIC                  "VICE Snapshot File\032", padded
                                      with 0
BYTE           VMAJOR                 fileformat major version number
BYTE           VMINOR                 fileformat minor version number
16 BYTE        MACHINENAME            Name of emulated machine, like
                                      "PET", "CBM-II", "VIC20", "C64" or
                                      "C128".  zerobyte-padded.
13 BYTE        VERSION MAGIC          "VICE Version\032", padded with 0
4 BYTE         VERSION                Release version
2 BYTE         SVNVERSION             SVN revision (or 0 if not
                                      available)

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

Each module has a header with the information given in the table below.
The header includes two version numbers, VMAJOR and VMINOR. In the past
the idea was that modules with the same VMAJOR should be able to be
exchanged.  This however proved to be too difficult to maintain, and
insanely hard to test for correctness, which is why now the emulator
will reject the snapshot when it finds a module that is too old.
Because of this you should not use snapshots for permanent/long term
storage.

Type    Name                          Description
16      MODULENAME                    The name of the module in ASCII,
BYTE                                  padded with 0 to 16 byte.
BYTE    VMAJOR                        major version number
BYTE    VMINOR                        minor version number
DWORD   SIZE                          size of the module, including this
                                      header


File: vice.info,  Node: CPU 6502 module,  Next: CPU 6809 module,  Prev: Module framework,  Up: Module formats

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

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


File: vice.info,  Node: CPU 6809 module,  Next: CIA 6526 module,  Prev: CPU 6502 module,  Up: Module formats

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

Type    Name                          Description
DWORD   CLK                           the current CPU clock value.  All
                                      other clock values are relative to
                                      this.
WORD    X                             The X register
WORD    Y                             The Y register
WORD    U                             The U register
WORD    PC                            The Program Counter register
BYTE    DP                            The Direct Page register
BYTE    CC                            The Condition Code register
BYTE    A                             The A register
BYTE    B                             The B register
                                      The following are for 6309
                                      compatibility:
WORD    V                             The V register
BYTE    E                             The E register
BYTE    F                             The F register


File: vice.info,  Node: CIA 6526 module,  Next: VIA 6522 module,  Prev: CPU 6809 module,  Up: Module formats

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

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

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 'ciatimer.h'.


File: vice.info,  Node: VIA 6522 module,  Next: PIA 6520 module,  Prev: CIA 6526 module,  Up: Module formats

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

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


File: vice.info,  Node: PIA 6520 module,  Next: TPI 6525 module,  Prev: VIA 6522 module,  Up: Module formats

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

Type    Name                          Description
UBYTE   ORA                           Output register A
UBYTE   DDRA                          Data Direction Register A
UBYTE   CTRLA                         Control Register A
UBYTE   ORB                           Output register B
UBYTE   DDRB                          Data Direction Register B
UBYTE   CTRLB                         Control Register B
UBYTE   CABSTATE                      Bit 7 = state of CA2, Bit 6 =
                                      state of CB2


File: vice.info,  Node: TPI 6525 module,  Next: RIOT 6532 module,  Prev: PIA 6520 module,  Up: Module formats

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

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


File: vice.info,  Node: RIOT 6532 module,  Next: SID 6581 module,  Prev: TPI 6525 module,  Up: Module formats

9.2.2.9 RIOT module
...................

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

Version numbers: Major 0, Minor 0.

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


File: vice.info,  Node: SID 6581 module,  Next: ACIA 6551 module,  Prev: RIOT 6532 module,  Up: Module formats

9.2.2.10 SID module
...................


File: vice.info,  Node: ACIA 6551 module,  Next: VIC-I module,  Prev: SID 6581 module,  Up: Module formats

9.2.2.11 ACIA module
....................

The ACIA 6551 is an RS232 interface chip.  VICE emulates RS232
connections via '/dev/ttyS*' (Unix) or '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.

Type    Name                          Description
BYTE    TDR                           Transmit Data Register
BYTE    RDR                           Receiver Data Register
BYTE    SR                            Status Register
BYTE    CMD                           Command Register
BYTE    CTRL                          Ctrl Register
BYTE    INTX                          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
DWORD   TICKS                         Clock ticks till the next TDR
                                      empty interrupt


File: vice.info,  Node: VIC-I module,  Next: VIC-II module,  Prev: ACIA 6551 module,  Up: Module formats

9.2.2.12 VIC-I module
.....................


File: vice.info,  Node: VIC-II module,  Next: CRTC module,  Prev: VIC-I module,  Up: Module formats

9.2.2.13 VIC-II module
......................


File: vice.info,  Node: CRTC module,  Next: C64 memory module,  Prev: VIC-II module,  Up: Module formats

9.2.2.14 CRTC module
....................

Version numbers: Major 1, Minor 1.

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

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.

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


File: vice.info,  Node: C64 memory module,  Next: C128 memory module,  Prev: CRTC module,  Up: Module formats

9.2.2.15 C64 memory module
..........................

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

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

Version numbers: Major 0, Minor 0

The C64MEM module

Type    Name                          Description
BYTE    CPUDATA                       CPU port data byte
BYTE    CPUDIR                        CPU port direction byte
BYTE    EXROM                         state of the EXROM line (?)
BYTE    GAME                          state of the GAME line (?)
ARRAY   RAM                           64k RAM dump

The C64ROM module

Type    Name                          Description
ARRAY   KERNAL                        8k dump of the kernal ROM
ARRAY   BASIC                         8k dump of the basic ROM
ARRAY   CHARGEN                       4k dump of the chargen ROM


File: vice.info,  Node: C128 memory module,  Next: VIC20 memory module,  Prev: C64 memory module,  Up: Module formats

9.2.2.16 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

The C128MEM module

Type    Name                          Description
12      MMU                           dump of the 12 MMU registers
BYTE
ARRAY   RAM                           128k RAM dump banks 0 and 1

The C128ROM module

Type    Name                          Description
ARRAY   KERNAL                        8k dump of the kernal ROM
ARRAY   BASIC                         32k dump of the basic ROM
ARRAY   EDITOR                        4k dump of the editor ROM
ARRAY   4k CHARGEN                    dump of the chargen ROM


File: vice.info,  Node: VIC20 memory module,  Next: PET memory module,  Prev: C128 memory module,  Up: Module formats

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

The VIC20MEM module

Version numbers: Major 1, Minor 0

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

The VIC20ROM module

Version numbers: Major 1, Minor 1

Type    Name                          Description
BYTE    CONFIG                        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.
ARRAY   KERNAL                        8k KERNAL ROM image $e000-$ffff
ARRAY   BASIC                         16k BASIC ROM image $c000-$dfff
ARRAY   CHARGEN                       4k CHARGEN ROM image
ARRAY   BLK1A                         4k ROM image $2*** (if CONFIG & 1)
ARRAY   BLK1B                         4k ROM image $3*** (if CONFIG & 2)
ARRAY   BLK3A                         4k ROM image $6*** (if CONFIG &
                                      16)
ARRAY   BLK3B                         4k ROM image $7*** (if CONFIG &
                                      32)
ARRAY   BLK5A                         4k ROM image $A*** (if CONFIG &
                                      64)
ARRAY   BLK5B                         4k ROM image $B*** (if CONFIG &
                                      128)
ARRAY   BLK2A                         4k ROM image $4*** (if CONFIG & 4;
                                      added in V1.1)
ARRAY   BLK2B                         4k ROM image $5*** (if CONFIG & 8;
                                      added in V1.1)


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

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

The PETMEM module

Version numbers: Major 1, Minor 3

Type    Name                          Description
BYTE    CONFIG                        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***.
BYTE    KEYBOARD                      Keyboard type.  0= UK business; 1=
                                      Graphics; 2= German business
BYTE    MEMSIZE                       memory size of low 32k in k
                                      (possible values 4, 8, 16, 32)
BYTE    CONF8X96                      Value of the 8x96 configuration
                                      register
BYTE    SUPERPET                      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.
ARRAY   RAM                           4-32k RAM (not 8296, size depends
                                      on MEMSIZE)
ARRAY   VRAM                          2/4k RAM (not 8296, size depends
                                      on CONFIG)
ARRAY   EXTRAM                        64k expansion RAM (SuperPET and
                                      8096 only)
ARRAY   RAM                           128k RAM (8296 only)
-       -                             The following item has been added
                                      in V1.1
BYTE    POSITIONAL                    bit 0=0 = symbolic keyboard
                                      mapping, bit 0=1 = positional
                                      mapping.
-       -                             The following item has been added
                                      in V1.2
BYTE    EOIBLANK                      bit 0=0 = EOI does not blank
                                      screen, bit 0=1 = EOI blanks
                                      screen.
-       -                             The following items have been
                                      added in V1.3
WORD    CPU_SWITCH                    6502 / 6809 / PROG
BYTE    VAL, PREVODD, WANTODD         6702 dongle state information
WORD[8] SHIFT
BYTE    SuperPET config 2             Extra bits due to the Super-OS-9
                                      MMU. Bit 5: FIRQ disabled.  Bit 6:
                                      expansion memory in OS-9 flat
                                      mode.
                                      

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.

The PETROM module

Version numbers: Major 1, Minor 1

Type    Name                          Description
BYTE    CONFIG                        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.
ARRAY   KERNAL                        4k KERNAL ROM image $f000-$ffff
ARRAY   EDITOR                        2k EDITOR ROM image $e000-$e7ff
ARRAY   CHARGEN                       2k CHARGEN ROM image
ARRAY   ROM9                          4k $9*** ROM image (if CONFIG & 1)
ARRAY   ROMA                          4k $A*** ROM image (if CONFIG & 2)
ARRAY   ROMB                          4k $B*** ROM image (if CONFIG & 4)
ARRAY   ROMC                          4k $C*** ROM image
ARRAY   ROMD                          4k $D*** ROM image
ARRAY   ROME9                         7 blocks $e900-$efff ROM image (if
                                      CONFIG & 8)
-       -                             The following items have been
                                      added in V1.1
ROM6809 ROM6809                       24k $A000-$FFFF ROM (if CONFIG &
                                      16)
ARRAY   CHARGEN(2)                    upper half of CHARGEN (if CONFIG &
                                      16)

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.

Type    Name                          Description
WORD    SIZE                          The size of the memory dump that
                                      follows, or 0 if DWW disabled.
ARRAY   MEM                           The memory in the DWW card, SIZE
                                      bytes.


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

9.2.2.19 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

9.2.2.20 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

10 Media images
***************

10.1 Media images resources
===========================

'DoodleOversizeHandling'
     Integer specifying the way the oversized input should be handled
     (all emulators except vsid).  (0: scale down, 1: crop left top, 2:
     crop center top, 3: crop right top, 4: crop left center, 5: crop
     center, 6: crop right center, 7: crop left bottom, 8: crop center
     bottom, 9: crop right bottom)

'DoodleUndersizeHandling'
     Integer specifying the way the undersized input should be handled
     (all emulators except vsid).  (0: scale, 1: borderize)

'DoodleMultiColorHandling'
     Integer specifying the way the multicolor to hires should be
     handled (all emulators except vsid).  (0: b&w, 1: 2 colors, 2: 4
     colors, 3: gray scale, 4: best cell colors)

'DoodleTEDLumHandling'
     Integer specifying the way the TED luminosity should be handled
     (all emulators except vsid).  (0: ignore, 1: dither)

'DoodleCRTCTextColor'
     Integer specifying the text color used when making screenshots from
     a CRTC window in doodle format (all emulators except vsid).  (0:
     white, 1: amber, 2: green)

'KoalaOversizeHandling'
     Integer specifying the way the oversized input should be handled
     (all emulators except vsid).  (0: scale down, 1: crop left top, 2:
     crop center top, 3: crop right top, 4: crop left center, 5: crop
     center, 6: crop right center, 7: crop left bottom, 8: crop center
     bottom, 9: crop right bottom)

'KoalaUndersizeHandling'
     Integer specifying the way the undersized input should be handled
     (all emulators except vsid).  (0: scale, 1: borderize)

'KoalaTEDLumHandling'
     Integer specifying the way the TED luminosity should be handled
     (all emulators except vsid).  (0: ignore, 1: dither)

'KoalaCRTCTextColor'
     Integer specifying the text color used when making screenshots from
     a CRTC window in doodle format (all emulators except vsid).  (0:
     white, 1: amber, 2: green)

'FFMPEGFormat'
     String specifying the current FFMPEG output driver.
'FFMPEGAudioBitrate'
     Integer specifying the current FFMPEG audio bitrate.
'FFMPEGVideoBitrate'
     Integer specifying the current FFMPEG video bitrate.
'FFMPEGAudioCodec'
     Integer specifying the current FFMPEG audio codec.
'FFMPEGVideoCodec'
     Integer specifying the current FFMPEG video codec.
'FFMPEGVideoHalveFramerate'
     Boolean, if true record only every other frame.

10.2 Media images command-line options
======================================

'-doodleoversize <method>'
     Select the way the oversized input should be handled
     ('DoodleOversizeHandling') (all emulators except vsid).  (0: scale
     down, 1: crop left top, 2: crop center top, 3: crop right top, 4:
     crop left center, 5: crop center, 6: crop right center, 7: crop
     left bottom, 8: crop center bottom, 9: crop right bottom)

'-doodleundersize <method>'
     Select the way the undersized input should be handled
     ('DoodleUndersizeHandling') (all emulators except vsid).  (0:
     scale, 1: borderize)

'-doodlemc <method>'
     Select the way the multicolor to hires should be handled
     ('DoodleMultiColorHandling') (all emulators except vsid).  (0: b&w,
     1: 2 colors, 2: 4 colors, 3: gray scale, 4: best cell colors)

'-doodletedlum <method>'
     Select the way the TED luminosity should be handled
     ('DoodleTEDLumHandling') (all emulators except vsid).  (0: ignore,
     1: dither)

'-doodlecrtctextcolor <color>'
     Select the CRTC text color ('DoodleCRTCTextColor') (all emulators
     except vsid).  (0: white, 1: amber, 2: green)

'-koalaoversize <method>'
     Select the way the oversized input should be handled
     ('KoalaOversizeHandling') (all emulators except vsid).  (0: scale
     down, 1: crop left top, 2: crop center top, 3: crop right top, 4:
     crop left center, 5: crop center, 6: crop right center, 7: crop
     left bottom, 8: crop center bottom, 9: crop right bottom)

'-koalaundersize <method>'
     Select the way the undersized input should be handled
     ('KoalaUndersizeHandling') (all emulators except vsid).  (0: scale,
     1: borderize)

'-koalatedlum <method>'
     Select the way the TED luminosity should be handled
     ('KoalaTEDLumHandling') (all emulators except vsid).  (0: ignore,
     1: dither)

'-koalacrtctextcolor <color>'
     Select the CRTC text color ('KoalaCRTCTextColor') (all emulators
     except vsid).  (0: white, 1: amber, 2: green)

'-ffmpegaudiobitrate <value>'
     Set bitrate for audio stream in media file
'-ffmpegvideobitrate <value>'
     Set bitrate for video stream in media file

11 Event history
****************

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.

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

11.2 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

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

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

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

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

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

11.8 Event history resources
============================

'EventSnapshotDir'
     String specifying the directory used for loading and saving
     snapshots (all emulators except vsid).

'EventStartSnapshot'
     String specifying the filename for the start snapshot (all
     emulators except vsid).

'EventEndSnapshot'
     String specifying the filename for the end snapshot (all emulators
     except vsid).

'EventStartMode'
     Integer specifying how to start event recording (all emulators
     except vsid).  (0: save new snapshot, 1: load existing snapshot, 2:
     reset, 3: playback)

'EventImageInclude'
     Boolean specifying whether to include ROM and Disk images in the
     snapshots (all emulators except vsid).

11.9 Event history command-line options
=======================================

'-playback'
     Playback recorded events (all emulators except vsid).

'-eventsnapshotdir <Name>'
     Set event snapshot directory ('EventSnapshotDir') (all emulators
     except vsid).

'-eventstartsnapshot <Name>'
     Set event start snapshot filename ('EventStartSnapshot') (all
     emulators except vsid).

'-eventendsnapshot <Name>'
     Set event end snapshot filename ('EventEndSnapshot') (all emulators
     except vsid).

'-eventstartmode <Mode>'
     Set event start mode ('EventStartMode') (all emulators except
     vsid).  (0: save new snapshot, 1: load existing snapshot, 2: reset,
     3: playback)

'-eventimageinc'
'+eventimageinc'
     Enable/disable the inclusion of disk images in the event
     ('EventImageInclude=1', 'EventImageInclude=0') (all emulators
     except vsid).


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

12 Monitor
**********

The VICE emulator has a complete built-in monitor, which can be used to
examine, disassemble and assemble machine language programs, as well as
debug them through breakpoints.  It can be activated by using "Activate
monitor" from the menu.  The monitor will either run in a seperate
window, or in a terminal emulation program (such as 'rxvt' or 'xterm')
when "native monitor" has been enabled in the settings.

* Menu:

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


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

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

'label'
     'label' is the name of a label.  It must start with a dot (".")  in
     order for the monitor to recognize it as a label.  Register names
     preceeded by a dot (for example '.PC') are special labels that
     evaluate to value of the respective register at the time it is
     used, and thus can not be used as a regular label.

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

'memmap'
     The memmap keeps track of RAM/ROM/IO read/write/execute accesses.
     The feature must be enabled with "-enable-cpuhistory" configure
     option, as it might decrease performance notably on slower
     hardware.  The option also enables CPU history.

'<...>'
     A data type.

'*'
     Zero or more occurrences.

'[...]'
     An optional argument.


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

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

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

'cpuhistory [<count>]'
'chis [<count>]'
     Show <count> last executed commands.  (disabled by default;
     configure with -enable-cpuhistory to enable)

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

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

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

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

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

'reset [<type>]'
     Reset the machine or drive.  'type': 0 = soft, 1 = hard, 8-11 =
     drive.

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

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

'stopwatch [reset]'
     Print the CPU cycle counter of the current device.  'reset' sets
     the counter to 0.

'undump "<filename>"'
     Read a snapshot of the machine from the file specified.


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

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

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

'hunt <address_range> <data_list>'
'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.

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

'ii <address_opt_range>'
     Display memory contents as screen code text

'mem [<data_type>] [<address_opt_range>]'
'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.

'memmapshow [<mask>] [<address_opt_range>]'
'mmsh [<mask>] [<address_opt_range>]'
     Show the memmap.  The mask can be specified to show only those
     locations with accesses of certain type(s).  The mask is a number
     with the bits "ioRWXrwx", where RWX are for ROM and rwx for RAM.
     Optionally, an address range can be specified.  (disabled by
     default; configure with -enable-cpuhistory to enable)

'memmapzap'
'mmzap'
     Clear the memmap.  (disabled by default; configure with
     -enable-cpuhistory to enable)

'memmapsave "<filename>" <format>'
'mmsave "<filename>" <format>'
     Save the memmap as a picture.  'format': 0 = BMP, 1 = PCX, 2 = PNG,
     3 = GIF, 4 = IFF. (disabled by default; configure with
     -enable-cpuhistory to enable)

'memchar [<data_type>] [<address_opt_range>]'
'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.

'memsprite [<data_type>] [<address_opt_range>]'
'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>'
'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.

'screen'
'sc'
     Displays the contents of the screen.

'sidefx [on|off|toggle]'
'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.

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


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

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

'disass [<address> [<address>]]'
'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

12.5 Checkpoint commands
========================

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

'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>'
'cond <checknum> if <cond_expr>'
     Each time the specified checkpoint is examined, the condition is
     evaluated.  If it evalutes to true, the checkpoint is activated.
     Otherwise, it is ignored.  If registers are specified in the
     expression, the values used are those at the time the checkpoint is
     examined, not when the condition is set.

     The condition can use registers (A, X, Y, PC, SP, FL and other cpu
     specific registers (see manual)) and compare them (==, !=, <, >,
     <=, >=) against other registers or constants.  RL can be used to
     refer to the current rasterline, and CY refers to the current cycle
     in the line.

     Full expressions are also supported (+, -, *, /, &&, ||).  This
     let's you f.e.  to check specific bits in the FL register using the
     bitwise boolean operators.  Paranthises are also supported in the
     expression.  Registers can be the registers of other devices; this
     is denoted by a memspace prefix (i.e., c:, 8:, 9:, 10:, 11:
     Examples: A == $0, X == Y, 8:X == X) You can also compare against
     the value of a memory location in a specific bank, i.e you can
     break only if the vic register $d020 is $f0.  use the form
     @[bankname]:[$<address>] | [.label].  Note this is for the C :
     memspace only.  Examples : if @io:$d020 == $f0, if @io:.vicBorder
     == $f0

'delete <checknum>'
'del <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 [load|store|exec] [address [address] [if <cond_expr>]]'
'tr [load|store|exec] [address [address] [if <cond_expr>]]'
     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.  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.

'until [<address>]'
'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.

'watch [load|store|exec] [address [address] [if <cond_expr>]]'
'w [load|store|exec] [address [address] [if <cond_expr>]]'
     This command is similar to the '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.


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

12.6 General commands
=====================

'cd <directory>'
     Change the working directory.

'device [c:|8:|9:]'
'dev [c:|8:|9:]'
     Set the default address space to either the computer ('c:') or the
     disk ('8:|9:').

'dir [<directory>]'
'ls [<directory>]'
     Display the directory contents.

'pwd'
     Show current working directory.

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

'log [on|off|toggle]'
     Control whether the monitor output is logged into a logfile.  If
     the argument is 'on' then all output will be written into the
     logfile.  If the argument is 'off' then no log is produced.  If the
     argument is 'toggle' then the current mode is switched.  No
     argument displays the current state.

'logname "<filename>"'
     Sets the filename of the logfile.


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

12.7 Disk commands
==================

'attach <filename> <device>'
     Attach file to device.  (device 32 = cart)

'block_read <track> <sector> [<address>]'
'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.

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

'detach <device>'
     Detach file from device.  (device 32 = cart)

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

'list [<directory>]'
     List disk contents.

'bload "<filename>" <device> <address>'
'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.

'save "<filename>" <device> <address1> <address2>'
'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.

'bsave "<filename>" <device> <address1> <address2>'
'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.


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

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

'playback "<filename>"'
'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.

'record "<filename>"'
'rec "<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

12.9 Label commands
===================

'add_label <address> <label>'
'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.

'delete_label [<address_space>] <label>'
'dl [<address_space>] <label>'
     Remove the specified label from the label tables.  If no address
     space is checked, all tables are checked.

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

     The file must contain commands the monitor understands, e.g.
     add_label.  The compiler cc65 can create such label files.

     Vice can also load label files created by the Acme assembler.
     Their syntax is e.g.  "labelname = $1234 ; Maybe a comment".  A dot
     will be added automatically to label names assigned in this way to
     fit to the Vice label syntax.  Normally the semicolon seperates
     commands but after an assignment of this kind it may be used to
     start a comment to end of line, so unchanged Acme label files can
     be fed into Vice.

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

'show_labels [<address_space>]'
'shl [<address_space>]'
     Display current label mappings.  If no address space is specified,
     show all labels from default address space.

'clear_labels [<address_space>]'
'cl [<address_space>]'
     Clear current label mappings.  If no address space is specified,
     clear all labels from default address space.


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

12.10 Miscellaneous commands
============================

'cartfreeze'
     Use cartridge freeze.

'cpu <type>'
     Specify the type of CPU currently used (6502/z80).

'exit'
'x'
     Leave the monitor and return to execution.

'export'
'exp'
     Print out list of attached expansion port devices.

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

'keybuf "<string>"'
     Put the specified string into the keyboard buffer.  Note that you
     can specify specific keycodes by using C-style escaped hexcodes
     ("\x0a").

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

'resourceget "<resource>"'
'resget "<resource>"'
     Displays the value of the 'resource'.

'resourceset "<resource>" "<value>"'
'resset "<resource>" "<value>"'
     Sets the value of the 'resource'.

'load_resources "<file>"'
'resload "<file>"'
     Load resources from 'file'.

'save_resources "<file>"'
'ressave "<file>"'
     Save resources to 'file'.

'screenshot "<filename>" [<format>]'
'scrsh "<filename>" [<format>]'
     Take a screenshot.  'format': default = BMP, 1 = PCX, 2 = PNG, 3 =
     GIF, 4 = IFF.

'tapectrl <command>'
     Control the datasette.  'command': 0 = stop, 1 = start, 2 =
     forward, 3 = rewind, 4 = record, 5 = reset, 6 = reset counter.

'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

13 c1541
********

VICE is provided with a complete stand-alone disk image maintenance
utility, called 'c1541'.

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

13.1 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

13.2 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

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

'bam [<unit>] | <track-min> <track-max> [<unit>]'
     Show the BAM of 'unit', optionally displaying only the entries for
     'track-min' to 'track-max'

'bcopy <src-trk> <src-sec> <dst-trk> <dst-sec> [<src-unit> [<dst-unit>]]'
     Copy a block to another block, optionally specifying different
     source and destination units.  The block is copied using all 256
     bytes.

'bfill <track> <sector> <value> [<unit>]'
     Fill a block with a single value.

'block <track> <sector> [<offset> [<unit>]]'
     Show specified disk block in hex form.

'bpoke [@unit:<unit>] <track> <sector> <offset> <data ...>'
     Store one or more bytes of 'data' into a block.  The 'data' can be
     specified using prefixes:
     '0b or %'
          binary value ('%11111111')
     '&'
          octal value ('&377')
     '0x or $'
          hexadecimal value ('$ff')
     The <unit> is optional, and when used must use the CBM DOS notation
     for the unit number, for example '@9:'.

'bread <filename> <track> <sector> [<unit>]'
     Read a block from a disk image and write it to the host filesystem
     as 'filename'.

'bwrite <filename> <track> <sector> [<unit>]'
     Write data from the host filesystem using 'filename' as input.  At
     most 256 bytes are written to the disk image.

'chain <track> <sector> [<unit>]'
     Show block chain starting at ('track', 'sector').  The last number
     shown is the number of bytes used in the final block.

'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), 'g71'
     (VC1571 but in GCR coding), 'd81' (VC1581), 'd80' (CBM8050) or
     'd82' (CBM8250/1001).  Otherwise, format the disk in the current
     unit, if any.

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

'geoswrite <source>'
     Write GOES Convert file <source> from the file system on a disk
     image.

'geosextract <source>'
     Extract all the files to the file system and GEOS Convert them.

'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>]'
'dir [<pattern>]'
     List files matching 'pattern' (default is all files).

'name <diskname>[,<id>] <unit>'
     Change image name.

'p00save <enable> [<unit>]'
     Save P00 files to the file system.

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

'show [copying | warranty]'
     Show conditions for redistributing copies of C1541 ('copying') or
     the various kinds of warranty you do not have with C1541
     ('warranty').

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

'verbose ["off"]'
     Enable or disable verbose output.

'version'
     Show C1541 version string

'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

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

If you want to execute a shell command from within '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.

13.5 c1541 examples
===================

'c1541 -attach test.d64 -list'
     Attach 'test.d64' and show directory.

'c1541 -attach test.d64 -write test.prg testfile'
     Write 'test.prg' to 'test.d64' as 'testfile'.

'c1541 -format "name,id" d64 disk.d64'
     Create a disk image in 'd64' format, format it with the 'name' and
     'id' and save it to 'disk.d64'.

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

14.1 cartconv command line options
==================================

The cartconv program has the following parameters:

'-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.
'-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.
'-t carttype'
     This parameter is optional.  It is only needed when converting to a
     .crt file.  See below for the supported cartridge types.
'-s revision'
     This parameter is optional.  It is only needed when converting to a
     .crt file.  See the detailed description of the .crt format for
     which types support subtypes/revisions.
'-n "cart name"'
     This parameter is optional and is used as the cartridge name when
     creating a .crt file.
'-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.
'-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.
'-r'
     This parameter is optional, it enables repair mode (accept broken
     input files)
'-p'
     This parameter is optional, when it is given cartconv will accept
     input files that do not match the cartridge sizes (useful for
     development).
'-b'
     This parameter is optional, when it is given cartconv will not omit
     banks that are empty (filled with $ff).
'-q'
     This parameter is optional, it disables all non-error messages
'--types'
     This parameter is optional.  It shows all supported cartridge types
     (see below).
'--version'
     Show cartconv version string and exit

The following cartridge types are supported:

'bin'
     Binary .bin file (Default crt->bin)
'normal'
     Generic 8kB/12kB/16kB .crt file (Default bin->crt)
'prg'
     Binary C64 .prg file with load-address
'ulti'
     Ultimax mode 4kB/8kB/16kB .crt file
'ap'
     Atomic Power .crt file
'ar2'
     Action Replay MK2 .crt file
'ar3'
     Action Replay MK3 .crt file
'ar4'
     Action Replay MK4 .crt file
'ar5'
     Action Replay V5 .crt file
'cap'
     Capture .crt file
'comal'
     Comal 80 .crt file
'dep256'
     Dela EP256 .crt file, extra files can be inserted (1)(2)
'dep64'
     Dela EP64 .crt file, extra files can be inserted (1)
'dep7x8'
     Dela EP7x8 .crt file, extra files can be inserted (1)(2)(3)
'din'
     Dinamic .crt file
'dsm'
     Diashow-Maker .crt file
'easy'
     EasyFlash .crt file
'ecr'
     Easy Calc Result .crt file
'epyx'
     Epyx FastLoad .crt file
'exos'
     EXOS .crt file
'expert'
     Expert Cartridge .crt file
'f64'
     Formel 64 .crt file
'fc1'
     The Final Cartridge .crt file
'fc3'
     The Final Cartridge III .crt file
'fcp'
     Final Cartridge Plus .crt file
'ff'
     Freeze Frame .crt file
'fm'
     Freeze Machine .crt file
'fp'
     Fun Play .crt file
'gk'
     Game Killer .crt file
'gmod2'
     GMod2 .crt file
'gs'
     C64 Games System .crt file
'ide64'
     IDE64 .crt file
'ieee'
     IEEE-488 Interface .crt file
'kcs'
     KCS Power Cartridge .crt file
'ks'
     Kingsoft .crt file
'mach5'
     MACH 5 .crt file
'md'
     Magic Desk .crt file
'mf'
     Magic Formel .crt file
'max'
     MAX Basic .crt file
'mikro'
     Mikro Assembler .crt file
'mmc64'
     MMC64 .crt file
'mmcr'
     MMC Replay .crt file
'mv'
     Magic Voice .crt file
'ocean'
     Ocean .crt file
'p64'
     Prophet64 .crt file
'pf'
     Pagefox .crt file
'rep256'
     REX 256k EPROM Cart .crt file, extra files can be inserted
     (1)(2)(3)
'rgcd'
     RGCD .crt file
'ross'
     ROSS .crt file
'rr'
     Retro Replay .crt file
'rrnet'
     RR-Net MK3 .crt file
'ru'
     REX Utility .crt file
's64'
     Snapshot 64 .crt file
'sb'
     Structured BASIC .crt file
'se5'
     Super Explode V5.0 .crt file
'sg'
     Super Games .crt file
'silver'
     Silverrock 128K Cartridge .crt file
'simon'
     Simons' BASIC .crt file
'ss4'
     Super Snapshot V4 .crt file
'ss5'
     Super Snapshot V5 .crt file
'star'
     Stardos .crt file
'wl'
     Westermann Learning .crt file
'ws'
     Warp Speed .crt file
'zaxxon'
     Zaxxon .crt file

   * (1) insertion of 32kB EPROM files supported.
   * (2) insertion of 8kB .crt/binary files supported.
   * (3) insertion of 16kB .crt/binary files supported.

14.2 cartconv examples
======================

'cartconv -i foo.crt -o foo.bin'
     Convert a .crt file to a binary file with no load-address.
'cartconv -t prg -i foo.crt -o foo.prg'
     Convert a .crt file to a .prg file with default load-address.
'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.
'cartconv -t ocean -i foo.bin -o foo.crt'
     Convert a binary file to an ocean type cartridge.
'cartconv -t dep64 -i dep64.bin -i eprom.prg -o foo.crt'
     Inserting a 32kB EPROM file into an dep64 type cartridge.
        * step 1 : use the dep64 binary file in VICE as a generic 8kB
          cartridge.
        * step 2 : generate an EPROM file.
        * step 3 : get the EPROM file to the host computer.
        * step 4 : insert the EPROM file into the final dep64 .crt file:
'cartconv -t dep256 -i dep256.bin -i somegame.crt -o foo.crt'
     Insert an 8kB .crt file into a dep256 type cartridge.
'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.
'cartconv -f foo.crt'
     Get information about a .crt file.

15 petcat
*********

The petcat program is a text conversion utility, it can convert between
ASCII, PETSCII and tokenized BASIC.

15.1 petcat command line options
================================

'-help'
     Output help text
'-?'
     Same as above
'-version'
     show petcat version string and exit
'-v'
     verbose output
'-c'
     controls (interpret also control codes) (default if textmode)
'-nc'
     no controls (suppress control codes in printout) (default if
     non-textmode)
'-qc'
     convert all non alphanumeric characters inside quotes into
     controlcodes
'-ic'
     interpret control codes case-insensitive
'-d'
     output raw codes in decimal
'-h'
     write header (default if output is stdout)
'-nh'
     no header (default if output is a file)
'-skip <n>'
     Skip <n> bytes in the beginning of input file.  Ignored on P00.
'-text'
     Force text mode
'-<version>'
     use keywords for <version> instead of the v7.0 ones
'-w<version>'
     tokenize using keywords on specified Basic version.
'-k<version>'
     list all keywords for the specified Basic version
'-k'
     list all Basic versions available.
'-l'
     Specify load address for program (in hex, no loading chars!).
'-o <name>'
     Specify the output file name
'-f'
     Force overwritten the output file.  The default depends on the
     BASIC version.

BASIC Versions:
'10'
     Basic v10.0 (C65/C64DX)
'1p'
     Basic v1.0 (PET)
'2'
     Basic v2.0 (C64/VIC20/PET)
'3'
     Basic v3.5 (C16)
'40'
     Basic v4.0 (PET/CBM2)
'4e'
     Basic v2.0 with Basic v4.0 extension (C64)
'4v'
     Basic v2.0 with Basic v4.0 extension (VIC20)
'5'
     Basic v2.0 with Basic v5.0 extension (VIC20)
'70'
     Basic v7.0 (C128)
'71'
     Basic v7.0 with Basic v7.1 extension (C128)
'a'
     Basic v2.0 with AtBasic (C64)
'bk'
     Basic v2.0 with Kipper Basic (C64)
'blarg'
     Basic v2.0 with Blarg (C64)
'bob'
     Basic v2.0 with Basic on Bails (C64)
'bsx'
     Basic v2.0 with Basex (C64)
'bwarsaw'
     Basic v2.0 with Warsaw Basic (C64)
'bws'
     Basic v2.0 with WS Basic (C64)
'bwsf'
     Basic v2.0 with WS Basic final (C64)
'drago'
     Basic v2.0 with Drago basic v2.2 (C64)
'easy'
     Basic v2.0 with Easy Basic (VIC20)
'eve'
     Basic v2.0 with Eve Basic (C64)
'exp20'
     Basic v2.0 with Expanded Basic (VIC20)
'exp64'
     Basic v2.0 with Expanded Basic (C64)
'f'
     Basic v2.0 with Final Cartridge III (C64)
'game'
     Basic v2.0 with Game Basic (C64)
'graph'
     Basic v2.0 with Graphics basic (C64)
'lightning'
     Basic v2.0 with Basic Lightning (C64)
'magic'
     Basic v2.0 with Magic Basic (C64)
'mighty'
     Basic v2.0 with Mighty Basic by Craig Bruce (VIC20)
'pegasus'
     Basic v2.0 with Pegasus Basic v4.0 (C64)
'reu'
     Basic v2.0 with REU-Basic (C64)
'simon'
     Basic v2.0 with Simons' Basic extension (C64)
'speech'
     Basic v2.0 with Speech Basic v2.7 (C64)
'superbas'
     Basic v2.0 with Super Basic (C64)
'superexp'
     Basic v2.0 with Super Expander (VIC20)
'supergra'
     Basic v2.0 with Supergrafik 64 (C64)
'sxc'
     Basic v2.0 with Super Expander Chip (C64)
'tt64'
     Basic v2.0 with The Tool 64 (C64)
'turtle'
     Basic v2.0 with Turtle Basic by Craig Bruce (VIC20)
'ultra'
     Basic v2.0 with Ultrabasic-64 (C64)
'xbasic'
     Basic v2.0 with Xbasic (C64)

15.2 petcat examples
====================

'petcat -2 -o outputfile.txt -- inputfile.prg'
     De-tokenize, Convert inputfile.prg to a text file in
     outputfile.txt, using BASIC V2 only
'petcat -wsimon -o outputfile.prg -- inputfile.txt'
     Tokenize, Convert inputfile.txt to a PRG file in outputfile.prg,
     using Simons' BASIC
'petcat -text -o outputfile.txt -- inputfile.seq'
     Convert inputfile.seq to a Ascii text file in outputfile.txt.
'petcat -text -w2 -o outputfile.seq -- inputfile.txt'
     Convert inputfile.txt to a Petscii text SEQ file in outputfile.seq.


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

16 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


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

16.1 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

16.1.1 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

16.1.2 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

16.1.3 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,  Next: D64,  Prev: T64,  Up: File formats

16.2 The G64 GCR-encoded disk image format
==========================================

16.2.1 The original format
--------------------------

(This section was contributed by Peter Schepers and slightly edited by
Ettore Perazzoli.)

This format was defined in 1998 as a cooperative effort between several
emulator people, mainly Per Håkan Sundell, author of the CCS64 C64
emulator, Andreas Boose of the VICE CBM emulator team and Joe
Forster/STA, the author of Star Commander.  It was the first real public
attempt to create a format for the emulator community which removed
almost all of the drawbacks of the other existing image formats, namely
'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.

16.2.2 An extension for double sided disks (Commodore VIC 1571)
---------------------------------------------------------------

Given that a Commodore VIC 1541/1570/1571 can read/write at most 42
tracks per side, it is quite natural to use the half-tracks from 1 to 84
for the first side and the following 84 half-tracks (i.  e.  halg.track
85 to 168) for the second size.

In order for this to work, byte 9 of the image (i.  e.  the maximum
number of tracks) usually contains 168 for double sided disks.

To make identifying such images easy, the fiel signature in the first 8
bytes of such files will be 'GCR-1571').

16.3 The P64 NRZI flux pulse disk image format
==============================================

This section is taken from "P64 file format specification" by Benjamin
'BeRo' Rosseaux.

All values are in little endian order !

16.3.1 P64 Header Layout
------------------------

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

Version: File format version, current is 0x00000000

Size Size of the following whole chunk content stream

Flags: Bit 0 = Write protect Bit 1 = Number of sides (0 for single
sided, 1 for double sided) Bit 2-31 = Reserved, all set to 0 when
creating a file, preserve existing value when updating

CRC32CheckSum: CRC32 checksum of the following whole chunk content
stream

16.3.2 P64 Chunk Header Layout
------------------------------

             0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
           +-----------------------------------------------+
     0000: |Chunk Signature|      Size     | CRC32Checksum |
           +-----------------------------------------------+

Chunk signature: Signature of chunk

Size: Size of the chunk data

CRC32CheckSum: CRC32 checksum of the chunk data

16.3.3 P64 Chunk 'HTPx' Layout
------------------------------

| x = half track index byte | +------------------+ Bit 7 of the half
track index byte contains the side.

Track 18 = Half track 36 = Half track index byte decimal value 36

Half track NRZI transition flux pulse data chunk block

             0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
           +---------------------------------------------------------------+
     0000: |  Count pulses |     Size      | ..... Range-encoded data .... |
           +---------------------------------------------------------------+

Count pulses: Count of the NRZI transition flux pulses in half track

Size: Size of the range-encoded data

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

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

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

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:
     procedure WriteBit(Model, Value : longword);
     begin
        RangeCoderProbabilityStates[Model] :=
          RangeCoderEncodeBit(RangeCoderProbabilities[
            RangeCoderProbabilityOffsets[Model] +
              RangeCoderProbabilityStates[Model]], 4, Value and 1);
     end;

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

The decoding is simply just in the another direction way.

Pseudo code for a FPAQ0-style carryless range coder:

Pascal-Style pseudo code:
     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;

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.

16.3.5 P64 Chunk 'DONE' Layout
------------------------------

This is the last empty chunk for to signalize that the correct file end
is reached.


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

16.4 The D64 disk image format
==============================

(This section was contributed by Peter Schepers and slightly edited by
Marco van den Heuvel.  Added 42 track info by groepaz)

First and foremost we have D64, which is basically a sector-for-sector
copy of a 1540/1541 disk.  There are several versions of these which I
will cover shortly.  The standard D64 is a 174848 byte file comprised of
256 byte sectors arranged in 35 tracks with a varying number of sectors
per track for a total of 683 sectors.  Track counting starts at 1, not
0, and goes up to 35.  Sector counting starts at 0, not 1, for the first
sector, therefore a track with 21 sectors will go from 0 to 20.

The original media (a 5.25" disk) has the tracks laid out in circles,
with track 1 on the very outside of the disk (closest to the sides) to
track 35 being on the inside of the disk (closest to the inner hub
ring).  Commodore, in their infinite wisdom, varied the number of
sectors per track and data densities across the disk to optimize
available storage, resulting in the chart below.  It shows the
sectors/track for a standard D64.  Since the outside diameter of a
circle is the largest (versus closer to the center), the outside tracks
have the largest amount of storage.

Track                    Sectors/track            # Sectors
1-17                     21                       357
18-24                    19                       133
25-30                    18                       108
31-35                    17                       85
36-40(*)                 17                       85
41-42(*)                 17                       34

Track              #Sect              #SectorsIn         D64 Offset
1                  21                 0                  $00000
2                  21                 21                 $01500
3                  21                 42                 $02A00
4                  21                 63                 $03F00
5                  21                 84                 $05400
6                  21                 105                $06900
7                  21                 126                $07E00
8                  21                 147                $09300
9                  21                 168                $0A800
10                 21                 189                $0BD00
11                 21                 210                $0D200
12                 21                 231                $0E700
13                 21                 252                $0FC00
14                 21                 273                $11100
15                 21                 294                $12600
16                 21                 315                $13B00
17                 21                 336                $15000
18                 19                 357                $16500
19                 19                 376                $17800
20                 19                 395                $18B00
21                 19                 414                $19E00
22                 19                 433                $1B100
23                 19                 452                $1C400
24                 19                 471                $1D700
25                 18                 490                $1EA00
26                 18                 508                $1FC00
27                 18                 526                $20E00
28                 18                 544                $22000
29                 18                 562                $23200
30                 18                 580                $24400
31                 17                 598                $25600
32                 17                 615                $26700
33                 17                 632                $27800
34                 17                 649                $28900
35                 17                 666                $29A00
36(*)              17                 683                $2AB00
37(*)              17                 700                $2BC00
38(*)              17                 717                $2CD00
39(*)              17                 734                $2DE00
40(*)              17                 751                $2EF00
41(*)              17                 768                $30000
42(*)              17                 785                $31100

(*) Tracks 36-40 apply to 40- and 42-track images only.  (*) Tracks
41-42 apply to 42-track images only.

The directory track should be contained totally on track 18.  Sectors
1-18 contain the entries and sector 0 contains the BAM (Block
Availability Map) and disk name/ID. Since the directory is only 18
sectors large (19 less one for the BAM), and each sector can contain
only 8 entries (32 bytes per entry), the maximum number of directory
entries is 18 * 8 = 144.  The first directory sector is always 18/1,
even though the t/s pointer at 18/0 (first two bytes) might point
somewhere else.  It then follows the same chain structure as a normal
file, using a sector interleave of 3.  This makes the chain links go
18/1, 18/4, 18/7 etc.

Note that you can extend the directory off of track 18, but only when
reading the disk or image.  Attempting to write to a directory sector
not on track 18 will cause directory corruption.  Each directory sector
has the following layout (18/1 partial dump):

      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)

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:

Bytes          Description
$00-$1F        First directory entry
$20-$3F        Second dir entry
$40-$5F        Third dir entry
$60-$7F        Fourth dir entry
$80-$9F        Fifth dir entry
$A0-$BF        Sixth dir entry
$C0-$DF        Seventh dir entry
$E0-$FF        Eighth dir entry

This is a breakdown of a standard directory entry:

Bytes          Description
$00-$01        Track/Sector location of next directory sector ($00 $00
               if not the first entry in the sector)
$02            File type
$03-$04        Track/sector location of first sector of file
$05-$14        16 character filename (in PETASCII, padded with $A0)
$15-$16        Track/Sector location of first side-sector block (REL
               file only)
$17            REL file record length (REL file only, max.  value 254)
$18-$1D        Unused (except with GEOS disks)
$1E-$1F        File size in sectors, low/high byte order ($1E+$1F*256).
               The approx.  filesize in bytes is <= #sectors * 254

The file type field is used as follows:

Bits           Description
0-3            The actual file type
4              Unused
5              Used only during SAVE-@ replacement
6              Locked flag (Set produces ">" locked files)
7              Closed flag (Not set produces "*", or "splat" files)

The actual file type can be one of the following:

Binary         Decimal        File type
0000           0              DEL
0001           1              SEQ
0010           2              PRG
0011           3              USR
0100           4              REL

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.

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

16.4.2 BAM layout
-----------------

The layout of the BAM area (sector 18/0) is a bit more complicated...

          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

Bytes          Description
$00-$01        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)
$02            Disk DOS version type (see note below) $41 ("A")
$03            Unused
$04-$8F        BAM entries for each track, in groups of four bytes per
               track, starting on track 1 (see below for more details)
$90-$9F        Disk Name (padded with $A0)
$A0-$A1        Filled with $A0
$A2-$A3        Disk ID
$A4            Usually $A0
$A5-$A6        DOS type, usually "2A"
$A7-$AA        Filled with $A0
$AB            Unused ($00)
$AC-$BF        For DOLPHIN DOS track 36-40 BAM entries, otherwise
               unused ($00)
$C0-$D3        For SPEED DOS track 36-40 BAM entries, otherwise unused
               ($00)
$D4-$FF
Unused ($00)

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.

Bytes          Data                          Description
$04-$07        $12 $FF $F9 $17               Track 1 BAM
$08-$0B        $15 $FF $FF $FF               Track 2 BAM
$0C-$0F        $15 $FF $FF $1F               Track 3 BAM
...            ...                           ...
$8C-$8F        $11 $FF $FF $01               Track 35 BAM

These entries must be viewed in binary to make any sense.  We will use
the first entry (track 1) at bytes 04-07:

      FF=11111111, F9=11111001, 17=00010111

In order to make any sense from the binary notation, flip the bits
around.

                 111111 11112222
      01234567 89012345 67890123
      --------------------------
      11111111 10011111 11101000
      ^                     ^
      sector 0           sector 20

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.

1            2            3            4            5            6
---          ---          ---          ---          ---          ---
17/0         17/10        17/20        17/1         17/11        0/52
(11/00)      (11/0A)      (11/14)      (11/01)      (11/0B)      (0/34)

16.4.3 Variations on the D64 layout
-----------------------------------

These are some variations of the D64 layout:

1.  Standard 35 track layout but with 683 error bytes added on to the
end of the file.  Each byte of the error info corresponds to a single
sector stored in the D64, indicating if the sector on the original disk
contained an error.  The first byte is for track 1/0, and the last byte
is for track 35/16.

2.  A 40 track layout, following the same layout as a 35 track disk, but
with 5 extra tracks.  These contain 17 sectors each, like tracks 31-35.
Some of the PC utilities do allow you to create and work with these
files.  This can also have error bytes attached like variant #1.

3.  A 42 track layout, with two extra tracks of 17 sectors each.  This
is extremely uncommon, since real drives often have problems with
accessing these tracks, software that uses them is very rare.

4.  The Commodore 128 allowed for "auto-boot" disks.  With this, t/s 1/0
holds a specific byte sequence which the computer recognizes as boot
code.

Below is a small chart detailing the standard file sizes of D64 images,
35, 40 or 42 tracks, with or without error bytes.

Disk type                            Size
35 track, no errors                  174848
35 track, 683 error bytes            175531
40 track, no errors                  196608
40 track, 768 error bytes            197376
42 track, no errors                  205312
42 track, 802 error bytes            206114

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.

Disk format                          tracks  header  Dos     Diskdos vs.
                                             7/8     type    type
Original CBM DOS v2.6                35      $0f     "2A"    $41/'A'
                                             $0f
*SpeedDOS+                           40      $0f     "2A"    $41/'A'
                                             $0f
Professional DOS Initial             35      $0f     "2A"    $41/'A'
                                             $0f
Professional DOS Version             40      $0f     "2A"    $41/'A'
1/Prototype                                  $0f
ProfDOS Release                      40      $0f     "4A"    $41/'A'
                                             $0f
Dolphin-DOS 2.0/3.0                  35      $0f     "2A"    $41/'A'
                                             $0f
Dolphin-DOS 2.0/3.0                  40      $0d     "2A"    $41/'A'
                                             $0f
PrologicDOS 1541                     35      $0f     "2A"    $41/'A'
                                             $0f
PrologicDOS 1541                     40      $0f     "2P"    $50/'P'
                                             $0f
ProSpeed 1571 2.0                    35      $0f     "2A"    $41/'A'
                                             $0f
ProSpeed 1571 2.0                    40      $0f     "2P"    $50/'P'
                                             $0f

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

            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

Below is a HEX dump of a Dolphin DOS BAM sector.  Note the location of
the extra BAM info from $AC-BF.

            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

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.

            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

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

Code           Error          Type           D64            Description
$01            00             N/A            *              No error.
$02            20             Seek           *              Header block
                                                            not found /
                                                            Header
                                                            descriptor
                                                            byte not
                                                            found
$03            21             Seek           *              No SYNC
                                                            sequence
                                                            found
$04            22             Read           *              Data
                                                            descriptor
                                                            byte not
                                                            found
$05            23             Read           *              Checksum
                                                            error in
                                                            data block
$06            24             Write                         Write verify
                                                            on format
                                                            (never
                                                            occurs on
                                                            1541)
$07            25             Write                         Write verify
                                                            error
$08            26             Write                         Write
                                                            protect on
$09            27             Seek           *              Checksum
                                                            error in
                                                            header block
$0A            28             Write                         Write error
                                                            (never
                                                            occurs on
                                                            1541)
$0B            29             Seek           *              Disk sector
                                                            ID mismatch
$0F            74             Read                          Drive Not
                                                            Ready (no
                                                            disk in
                                                            drive or no
                                                            device 1)

Codes $0 and $C to $E are unused and never occur.

These first errors are "seek" errors, where the disk controller is
simply reading headers and looking at descriptor bytes, checksums,
format ID's and reporting what errors it sees.  These errors do *not*
necessarily apply to the exact sector being looked for.  This fact makes
duplication of these errors very unreliable.

Code : $03 Error : 21 Type : Seek Message : No SYNC sequence found.

Each sector data block and header block are preceeded by SYNC marks.  If
*no* sync sequence is found within 20 milliseconds (only ~1/10 of a disk
rotation!)  then this error is generated.  This error used to mean the
entire track is bad, but it does not have to be the case.  Only a small
area of the track needs to be without a SYNC mark and this error will be
generated.

Converting this error to a D64 is very problematic because it depends on
where the physical head is on the disk when a read attempt is made.  If
it is on valid header/sectors then it won't occur.  If it happens over
an area without SYNC marks, it will happen.

Code : $02 Error : 20 Type : Seek Message : Header descriptor byte not
found (HEX $08, GCR $52)

Each sector is preceeded by an 8-byte GCR header block, which starts
with the value $52 (GCR). If this value is not found after 90 attempts,
this error is generated.

Basically, what a track has is SYNC marks, and possibly valid data
blocks, but no valid header descriptors.

Code : $09 Error : 27 Type : Seek Message : Checksum error in header
block

The header block contains a checksum value, calculated by XOR'ing the
TRACK, SECTOR, ID1 and ID2 values.  If this checksum is wrong, this
error is generated.

Code : $0B Error : 29 Type : Seek Message : Disk sector ID mismatch

The ID's from the header block of the currently read sector are compared
against the ones from the low-level header of 18/0.  If there is a
mismatch, this error is generated.

Code : $02 Error : 20 Type : Seek Message : Header block not found

This error can be reported again when searching for the correct header
block.  An image of the header is built and searched for, but not found
after 90 read attempts.  Note the difference from the first occurance.
The first one only searches for a valid ID, not the whole header.

Note that error 20 occurs twice during this phase.  The first time is
when a header ID is being searched for, the second is when the proper
header pattern for the sector being searched for is not found.

From this point on, all the errors apply to the specific sector you are
looking for.  If a read passed all the previous checks, then we are at
the sector being searched for.

Note that the entire sector is read before these errors are detected.
Therefore the data, checksum and off bytes are available.

Code : $04 Error : 22 Type : Read Message : Data descriptor byte not
found (HEX $07, GCR $55)

Each sector data block is preceeded by the value $07, the "data block"
descriptor.  If this value is not there, this error is generated.  Each
encoded sector has actually 260 bytes.  First is the descriptor byte,
then follows the 256 bytes of data, a checksum, and two "off" bytes.

Code : $05 Error : 23 Type : Read Message : Checksum error in data block

The checksum of the data read of the disk is calculated, and compared
against the one stored at the end of the sector.  If there's a
discrepancy, this error is generated.

Code : $0F Error : 74 Type : Read Message : Drive Not Ready (no disk in
drive or no device 1)

These errors only apply when writing to a disk.  I don't see the
usefulness of having these as they cannot be present when only *reading*
a disk.

Code : $06 Error : 24 Type : Write Message : Write verify (on format)

Code : $07 Error : 25 Type : Write Message : Write verify error

Once the GCR-encoded sector is written out, the drive waits for the
sector to come around again and verifies the whole 325-byte GCR block.
Any errors encountered will generate this error.

Code : $08 Error : 26 Type : Write Message : Write protect on

Self explanatory.  Remove the write-protect tab, and try again.

Code : $0A Error : 28 Type : Write Message : Write error

In actual fact, this error never occurs, but it is included for
completeness.

This is not an error at all, but it gets reported when the read of a
sector is ok.

Code : $01 Error : 00 Type : N/A Message : No error.

Self explanatory.  No errors were detected in the reading and decoding
of the sector.

The advantage with using the 35 track D64 format, regardless of error
bytes, is that it can be converted directly back to a 1541 disk by
either using the proper cable and software on the PC, or send it down to
the C64 and writing it back to a 1541.  It is the best documented format
since it is also native to the C64, with many books explaining the disk
layout and the internals of the 1541.


File: vice.info,  Node: X64,  Next: D71,  Prev: D64,  Up: File formats

16.5 The X64 disk image format
==============================

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

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

Bytes          Description
$00-$03        This is the "Magic header" ($43 $15 $41 $64)
$04            Header version major ($01)
$05            Header version minor ($01, now its up to $02)
$06            Device type represented
$07            Maximum tracks in image (only in version 1.02 or
               greater) 1540/41/70: 35 1571: 35 1581: 80 (Logical
               single-sided disk)
$08            Number of disk sides in image.  This value must be $00
               for all 1541 and 1581 formats.  $00=No second side
               $01=Second side
$09            Error data flag.
$0A-$1F        Unused, set to $00
$20-$3E        Disk image description (in ASCII or ISO Latin/1)
$3F            Always set to $00
$40-           Standard C64 file begins here.

The device types are:

Value          Drive type
$00            1540 See note below...
$01            1541 (Default)
$02            1542
$03            1551
$04            1570
$05            1571
$06            1572
$08            1581
$10            2031 or 4031
$11            2040 or 3040
$12            2041
$18            4040
$20            8050
$21            8060
$22            8061
$30            SFD-1001
$31            8250
$32            8280

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.


File: vice.info,  Node: D71,  Next: D81,  Prev: X64,  Up: File formats

16.6 The D71 disk image format
==============================

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

Track                                Sec/trk            # Sectors
1-17 (side 0)                        21                 357
18-24 (side 0)                       19                 133
25-30 (side 0)                       18                 108
31-35 (side 0)                       17                 85
36-52 (side 1)                       21                 357
53-59 (side 1)                       19                 133
60-65 (side 1)                       18                 108
66-70 (side 1)                       17                 85

Track              #Sect              #SectorsIn         D71 Offset
1                  21                 0                  $00000
2                  21                 21                 $01500
3                  21                 42                 $02A00
4                  21                 63                 $03F00
5                  21                 84                 $05400
6                  21                 105                $06900
7                  21                 126                $07E00
8                  21                 147                $09300
9                  21                 168                $0A800
10                 21                 189                $0BD00
11                 21                 210                $0D200
12                 21                 231                $0E700
13                 21                 252                $0FC00
14                 21                 273                $11100
15                 21                 294                $12600
16                 21                 315                $13B00
17                 21                 336                $15000
18                 19                 357                $16500
19                 19                 376                $17800
20                 19                 395                $18B00
21                 19                 414                $19E00
22                 19                 433                $1B100
23                 19                 452                $1C400
24                 19                 471                $1D700
25                 18                 490                $1EA00
26                 18                 508                $1FC00
27                 18                 526                $20E00
28                 18                 544                $22000
29                 18                 562                $23200
30                 18                 580                $24400
31                 17                 598                $25600
32                 17                 615                $26700
33                 17                 632                $27800
34                 17                 649                $28900
35                 17                 666                $29A00
36                 21                 683                $2AB00
37                 21                 704                $2C000
38                 21                 725                $2D500
39                 21                 746                $2EA00
40                 21                 767                $2FF00
41                 21                 788                $31400
42                 21                 809                $32900
43                 21                 830                $33E00
44                 21                 851                $35300
45                 21                 872                $36800
46                 21                 893                $37D00
47                 21                 914                $39200
48                 21                 935                $3A700
49                 21                 956                $3BC00
50                 21                 977                $3D100
51                 21                 998                $3E600
52                 21                 1019               $3FB00
53                 19                 1040               $41000
54                 19                 1059               $42300
55                 19                 1078               $43600
56                 19                 1097               $44900
57                 19                 1116               $45C00
58                 19                 1135               $46F00
59                 19                 1154               $48200
60                 18                 1173               $49500
61                 18                 1191               $4A700
62                 18                 1209               $4B900
63                 18                 1227               $4CB00
64                 18                 1245               $4DD00
65                 18                 1263               $4EF00
66                 17                 1281               $50100
67                 17                 1298               $51200
68                 17                 1315               $52300
69                 17                 1332               $53400
70                 17                 1349               $54500

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:

         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

Bytes          Description
$00-$1F        First directory entry
$20-$3F        Second dir entry
$40-$5F        Third dir entry
$60-$7F        Fourth dir entry
$80-$9F        Fifth dir entry
$A0-$BF        Sixth dir entry
$C0-$DF        Seventh dir entry
$E0-$FF        Eighth dir entry

This is a breakdown of a standard directory entry:

Bytes          Description
$00-$01        Track/Sector location of next directory sector ($00/$FF
               if its the last sector)
$02            File type
$03-$04        Track/sector location of first sector of file
$05-$14        16 character filename (in PETASCII, padded with $A0)
$15-$16        Track/Sector location of first side-sector block (REL
               file only)
$17            REL file record length (REL file only, max.  value 254)
$18-$1D        Unused (except with GEOS disks)
$1E-$1F        File size in sectors, low/high byte order ($1E+$1F*256).
               The approx.  filesize in bytes is <= #sectors * 254

The file type field is used as follows:

Bits           Description
0-3            The actual file type
4              Unused
5              Used only during SAVE-@ replacement
6              Locked flag (Set produces ">" locked files)
7              Closed flag (Not set produces "*", or "splat" files)

The actual file type can be one of the following:

Binary         Decimal        File type
0000           0              DEL
0001           1              SEQ
0010           2              PRG
0011           3              USR
0100           4              REL

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.

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

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

         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

Bytes                                Description
$00-$01                              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)
$02                                  Disk DOS version type (see note
                                     below) $41 ('A') = 1541
$03                                  Double-sided flag $00 - Single
                                     sided disk $80 - Double sided disk
$04-8F                               BAM entries for each track, in
                                     groups of four bytes per track,
                                     starting on track 1.
$90-$9F                              Disk Name (padded with $A0)
$A0-$A1                              Filled with $A0
$A2-$A3                              Disk ID
$A4                                  Usually $A0
$A5-$A6                              DOS type, usually "2A"
$A7-$AA                              Filled with $A0
$AB-$DC                              Not used ($00's)
$DD-$FF                              Free sector count for tracks 36-70
                                     (1 byte/track).

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:

      FF=11111111, F9=11111001, 17=00010111

In order to make any sense from the binary notation, flip the bits
around.

                 111111 11112222
      01234567 89012345 67890123
      --------------------------
      11111111 10011111 11101000
      ^                     ^
      sector 0           sector 20

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.

         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

Each track from 36-70 has 3 byte entries, starting at address $00.

     Byte: $00-$02: $FF $FF $1F - BAM map for track 36
           $03-$05: $FF $FF $1F - BAM map for track 37
           ...
           $33-$35: $00 $00 $00 - BAM map for track 53
           ...
           $66-$68: $FF $FF $01 - BAM map for track 70
           $69-$FF:             - Not used

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.


File: vice.info,  Node: D81,  Next: D80,  Prev: D71,  Up: File formats

16.7 The D81 disk image format
==============================

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

Track              #Sect              #SectorsIn         D81 Offset
1                  40                 0                  $00000
2                  40                 40                 $02800
3                  40                 80                 $05000
4                  40                 120                $07800
5                  40                 160                $0A000
6                  40                 200                $0C800
7                  40                 240                $0F000
8                  40                 280                $11800
9                  40                 320                $14000
10                 40                 360                $16800
11                 40                 400                $19000
12                 40                 440                $1B800
13                 40                 480                $1E000
14                 40                 520                $20800
15                 40                 560                $23000
16                 40                 600                $25800
17                 40                 640                $28000
18                 40                 680                $2A800
19                 40                 720                $2D000
20                 40                 760                $2F800
21                 40                 800                $32000
22                 40                 840                $34800
23                 40                 880                $37000
24                 40                 920                $39800
25                 40                 960                $3C000
26                 40                 1000               $3E800
27                 40                 1040               $41000
28                 40                 1080               $43800
29                 40                 1120               $46000
30                 40                 1160               $48800
31                 40                 1200               $4B000
32                 40                 1240               $4D800
33                 40                 1280               $50000
34                 40                 1320               $52800
35                 40                 1360               $55000
36                 40                 1400               $57800
37                 40                 1440               $5A000
38                 40                 1480               $5C800
39                 40                 1520               $5F000
40                 40                 1560               $61800
41                 40                 1600               $64000
42                 40                 1640               $66800
43                 40                 1680               $69000
44                 40                 1720               $6B800
45                 40                 1760               $6E000
46                 40                 1800               $70800
47                 40                 1840               $73000
48                 40                 1880               $75800
49                 40                 1920               $78000
50                 40                 1960               $7A800
51                 40                 2000               $7D000
52                 40                 2040               $7F800
53                 40                 2080               $82000
54                 40                 2120               $84800
55                 40                 2160               $87000
56                 40                 2200               $89800
57                 40                 2240               $8C000
58                 40                 2280               $8E800
59                 40                 2320               $91000
60                 40                 2360               $93800
61                 40                 2400               $96000
62                 40                 2440               $98800
63                 40                 2480               $9B000
64                 40                 2520               $9D800
65                 40                 2560               $A0000
66                 40                 2600               $A2800
67                 40                 2640               $A5000
68                 40                 2680               $A7800
69                 40                 2720               $AA000
70                 40                 2760               $AC800
71                 40                 2800               $AF000
72                 40                 2840               $B1800
73                 40                 2880               $B4000
74                 40                 2920               $B6800
75                 40                 2960               $B9000
76                 40                 3000               $BB800
77                 40                 3040               $BE000
78                 40                 3080               $C0800
79                 40                 3120               $C3000
80                 40                 3160               $C5800

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

         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

Bytes          Description
$00-$01        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)
$02            Disk DOS version type (see note below) $44 ('D')=1581
$03            $00
$04-$13        16 character Disk Name (padded with $A0)
$14-$15        $A0
$16-$17        Disk ID
$18            $A0
$19            DOS Version ("3")
$1A            Disk version ("D")
$1B-$1C        $A0
$1D-$FF        Unused (usually $00)

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)

Bytes          Description
$AB-$AC        Border sector (GEOS only, else set to $00)
$AD-$BC        GEOS ID string ("geos FORMAT V1.x" GEOS only, else $00)
$BD-$FF        Unused (usually $00)

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:

         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

Bytes          Description
$00-$1F        First directory entry
$20-$3F        Second dir entry
$40-$5F        Third dir entry
$60-$7F        Fourth dir entry
$80-$9F        Fifth dir entry
$A0-$BF        Sixth dir entry
$C0-$DF        Seventh dir entry
$E0-$FF        Eighth dir entry

This is a breakdown of a standard directory entry:

Bytes          Description
$00-$01        Track/Sector location of next directory sector
$02            File type
$03-$04        Track/sector location of first sector of file or
               partition
$05-$14        16 character filename (in PETASCII, padded with $A0)
$15-$16        Track/Sector location of first SUPER SIDE SECTOR block
               (REL file only)
$17            REL file record length (REL file only)
$18-$1B        Unused (except with GEOS disks)
$1C-$1D        (Used during an SAVE or OPEN, holds the new t/s link)
$1E-$1F        File or partition size in sectors, low/high byte order
               ($1E+$1F*256).  The approx.  file size in bytes is <=
               #sectors * 254

The file type field is used as follows:

Bits           Description
0-3            The actual file type
4              Unused
5              Used only during SAVE-@ replacement
6              Locked flag (Set produces ">" locked files)
7              Closed flag (Not set produces "*", or "splat" files)

The actual file type can be one of the following:

Binary         Decimal        File type
0000           0              DEL
0001           1              SEQ
0010           2              PRG
0011           3              USR
0100           4              REL
0101           5              CBM (partition or sub-directory)

Values 6-15 are illegal, but if used will produce very strange results.

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

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

         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

     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)
              ...
     $46-$4B: BAM entry for track 10 (track 50, side 1)
              ...
     $82-$87: BAM entry for track 20 (track 60, side 1)
              ...
     $BE-$C3: BAM entry for track 30 (track 70, side 1)
              ...
     $FA-$FF: BAM entry for track 40 (track 80, side 1)

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.

      F0: .. .. .. .. .. .. .. .. .. .. 24 F0 FF 2D FF FE

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:

      F0=11110000, FF=11111111, 2D=00101101, FF=11111111, FE=11111110

In order to make any sense from the binary notation, flip the bits
around.

                        111111 11112222 22222233 33333333
      Sector 01234567 89012345 67890123 45678901 23456789
             -------------------------- -------- --------
             00001111 11111111 10110100 11111111 01111111

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.

         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

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.

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

      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

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

      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

     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)
              ...
     $FD-$FE: Track/sector of first side sector in group 125
         $FF: Unused (likely $00)

The side sector layout is the same as the D64/1571.

         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

     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.

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

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

This is a dump of a sub-directory entry:

      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

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

      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

The master BAM shows the entry for this partition on track 5...

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

The breakdown of the BAM shows the allocation for this track, with
sectors 1-10 allocated, as it should be.

      10000000 00011111 11111111 11111111 11111111
      ^          ^          ^         ^          ^
      0          10         20        30         39

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.

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

     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


File: vice.info,  Node: D80,  Next: D82,  Prev: D81,  Up: File formats

16.8 The D80 disk image format
==============================

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

Track Range              Sectors/track            # Sectors
1-39                     29                       1131
40-53                    27                       378
54-64                    25                       275
65-77                    23                       299

Track              #Sect              #SectorsIn         D8x Offset
1                  29                 0                  $00000
2                  29                 29                 $01D00
3                  29                 58                 $03A00
4                  29                 87                 $05700
5                  29                 116                $07400
6                  29                 145                $09100
7                  29                 174                $0AE00
8                  29                 203                $0CB00
9                  29                 232                $0E800
10                 29                 261                $10500
11                 29                 290                $12200
12                 29                 319                $13F00
13                 29                 348                $15C00
14                 29                 377                $17900
15                 29                 406                $19600
16                 29                 435                $1B300
17                 29                 464                $1D000
18                 29                 493                $1ED00
19                 29                 522                $20A00
20                 29                 551                $22700
21                 29                 580                $24400
22                 29                 609                $26100
23                 29                 638                $27E00
24                 29                 667                $29B00
25                 29                 696                $2B800
26                 29                 725                $2D500
27                 29                 754                $2F200
28                 29                 783                $30F00
29                 29                 812                $32C00
30                 29                 841                $34900
31                 29                 870                $36600
32                 29                 899                $38300
33                 29                 928                $3A000
34                 29                 957                $3BD00
35                 29                 986                $3DA00
36                 29                 1015               $3F700
37                 29                 1044               $41400
38                 29                 1073               $43100
39                 29                 1102               $44E00
40                 27                 1131               $46B00
41                 27                 1158               $48600
42                 27                 1185               $4A100
43                 27                 1212               $4BC00
44                 27                 1239               $4D700
45                 27                 1266               $4F200
46                 27                 1293               $50D00
47                 27                 1320               $52800
48                 27                 1347               $54300
49                 27                 1374               $55E00
50                 27                 1401               $57900
51                 27                 1428               $59400
52                 27                 1455               $5AF00
53                 27                 1482               $5CA00
54                 25                 1509               $5E500
55                 25                 1534               $5FE00
56                 25                 1559               $61700
57                 25                 1584               $63000
58                 25                 1609               $64900
59                 25                 1634               $66200
60                 25                 1659               $67B00
61                 25                 1684               $69400
62                 25                 1709               $6AD00
63                 25                 1734               $6C600
64                 25                 1759               $6DF00
65                 23                 1784               $6F800
66                 23                 1807               $70F00
67                 23                 1830               $72600
68                 23                 1853               $73D00
69                 23                 1876               $75400
70                 23                 1899               $76B00
71                 23                 1922               $78200
72                 23                 1945               $79900
73                 23                 1968               $7B000
74                 23                 1991               $7C700
75                 23                 2014               $7DE00
76                 23                 2037               $7F500
77                 23                 2060               $80C00

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:

         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
     ...
     F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

Bytes                  Description
$00-$01                T/S pointer to first BAM sector (38/0)
$02                    $43 'C' is for DOS format version
$03                    Reserved
$04-$05                Unused
$06-$16                Disk name, padded with 0xA0 ("sample d80")
$17                    0xA0
$18-$19                Disk ID bytes "er"
$1A                    0xA0
$1B-$1C                DOS version bytes "2C"
$1D-$20                0xA0
$21-$FF                Unused

Below is a dump of the first directory sector, 39/1

         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

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:

Bytes          Description
$00-$1F        First directory entry
$20-$3F        Second dir entry
$40-$5F        Third dir entry
$60-$7F        Fourth dir entry
$80-$9F        Fifth dir entry
$A0-$BF        Sixth dir entry
$C0-$DF        Seventh dir entry
$E0-$FF        Eighth dir entry

This is a breakdown of a standard directory entry:

Bytes          Description
$00-$01        Track/Sector location of next directory sector ($00 $00
               if not the first entry in the sector)
$02            File type
$03-$04        Track/sector location of first sector of file
$05-$14        16 character filename (in PETASCII, padded with $A0)
$15-$16        Track/Sector location of first side-sector block (REL
               file only)
$17            REL file record length (REL file only, max.  value 254)
$18-$1D        Unused
$1E-$1F        File size in sectors, low/high byte order ($1E+$1F*256).
               The approx.  filesize in bytes is <= #sectors * 254

The file type field is used as follows:

Bits           Description
0-3            The actual file type
4              Unused
5              Used only during SAVE-@ replacement
6              Locked flag (Set produces ">" locked files)
7              Closed flag (Not set produces "*", or "splat" files)

The actual file type can be one of the following:

Binary         Decimal        File type
0000           0              DEL
0001           1              SEQ
0010           2              PRG
0011           3              USR
0100           4              REL

Values 5-15 are illegal, but if used will produce very strange results.

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

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

         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

Bytes                  Description
$00-$01                T/S pointer to second BAM sector (38/3)
$02                    DOS version byte (0x43='C')
$03                    Reserved
$04                    Lowest track covered by this BAM (0x01=1)
$05                    Highest+1 track covered by this BAM (0x33=51)
$06-$0A                BAM for track 1.  The first byte shows the
                       "blocks free" for this track, the remaining 4
                       show the BAM for the track.
$0B-$0F                BAM for track 2
...                    ...
$FB-$FF                BAM for track 50

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:

      FF=11111111, FF=11111111, FF=11111111, 1F=00011111

In order to make any sense from the binary notation, flip the bits
around.

                 111111 11112222 222222
      01234567 89012345 67890123 456789...
      -------------------------- ---------
      11111111 11111111 11111111 11111000
      ^                              ^
      sector 0                   sector 28

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.

         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

Bytes                  Description
$00-$01                T/S pointer to second BAM sector (39/1)
$02                    DOS version byte (0x43='C')
$03                    Reserved
$04                    Lowest track covered by this BAM (0x33=51)
$05                    Highest+1 track covered by this BAM (0x43=78)
$06-$0A                BAM for track 51.  The first byte shows the
                       "blocks free" for this track, the remaining 4
                       show the BAM for the track.
$0B-$0F                BAM for track 52
...                    ...
$88-$8C                BAM for track 77
$8D-$FF                Not used


File: vice.info,  Node: D82,  Next: P00,  Prev: D80,  Up: File formats

16.9 The D82 disk image format
==============================

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

Track Range              Sectors/track            # Sectors
1-39                     29                       1131
40-53                    27                       378
55-64                    25                       275
65-77                    23                       299
78-116                   29                       1131
117-130                  27                       378
131-141                  25                       275
142-154                  23                       299

Track              #Sect              #SectorsIn         D82 Offset
1                  29                 0                  $000000
2                  29                 29                 $001D00
3                  29                 58                 $003A00
4                  29                 87                 $005700
5                  29                 116                $007400
6                  29                 145                $009100
7                  29                 174                $00AE00
8                  29                 203                $00CB00
9                  29                 232                $00E800
10                 29                 261                $010500
11                 29                 290                $012200
12                 29                 319                $013F00
13                 29                 348                $015C00
14                 29                 377                $017900
15                 29                 406                $019600
16                 29                 435                $01B300
17                 29                 464                $01D000
18                 29                 493                $01ED00
19                 29                 522                $020A00
20                 29                 551                $022700
21                 29                 580                $024400
22                 29                 609                $026100
23                 29                 638                $027E00
24                 29                 667                $029B00
25                 29                 696                $02B800
26                 29                 725                $02D500
27                 29                 754                $02F200
28                 29                 783                $030F00
29                 29                 812                $032C00
30                 29                 841                $034900
31                 29                 870                $036600
32                 29                 899                $038300
33                 29                 928                $03A000
34                 29                 957                $03BD00
35                 29                 986                $03DA00
36                 29                 1015               $03F700
37                 29                 1044               $041400
38                 29                 1073               $043100
39                 29                 1102               $044E00
40                 27                 1131               $046B00
41                 27                 1158               $048600
42                 27                 1185               $04A100
43                 27                 1212               $04BC00
44                 27                 1239               $04D700
45                 27                 1266               $04F200
46                 27                 1293               $050D00
47                 27                 1320               $052800
48                 27                 1347               $054300
49                 27                 1374               $055E00
50                 27                 1401               $057900
51                 27                 1428               $059400
52                 27                 1455               $05AF00
53                 27                 1482               $05CA00
54                 25                 1509               $05E500
55                 25                 1534               $05FE00
56                 25                 1559               $061700
57                 25                 1584               $063000
58                 25                 1609               $064900
59                 25                 1634               $066200
60                 25                 1659               $067B00
61                 25                 1684               $069400
62                 25                 1709               $06AD00
63                 25                 1734               $06C600
64                 25                 1759               $06DF00
65                 23                 1784               $06F800
66                 23                 1807               $070F00
67                 23                 1830               $072600
68                 23                 1853               $073D00
69                 23                 1876               $075400
70                 23                 1899               $076B00
71                 23                 1922               $078200
72                 23                 1945               $079900
73                 23                 1968               $07B000
74                 23                 1991               $07C700
75                 23                 2014               $07DE00
76                 23                 2037               $07F500
77                 23                 2060               $080C00
78                 29                 2083               $082300
79                 29                 2112               $084000
80                 29                 2141               $085D00
81                 29                 2170               $087A00
82                 29                 2199               $089700
83                 29                 2228               $08B400
84                 29                 2257               $08D100
85                 29                 2286               $08EE00
86                 29                 2315               $090600
87                 29                 2344               $092800
88                 29                 2373               $094500
89                 29                 2402               $096200
90                 29                 2431               $097F00
91                 29                 2460               $099C00
92                 29                 2489               $09B900
93                 29                 2518               $09D600
94                 29                 2547               $09F300
95                 29                 2576               $0A1000
96                 29                 2605               $0A2D00
97                 29                 2634               $0A4A00
98                 29                 2663               $0A6700
99                 29                 2692               $0A8400
100                29                 2721               $0AA100
101                29                 2750               $0ABE00
102                29                 2779               $0ADB00
103                29                 2808               $0AF800
104                29                 2837               $0B1500
105                29                 2866               $0B3200
106                29                 2895               $0B4F00
107                29                 2924               $0B6C00
108                29                 2953               $0B8900
109                29                 2982               $0BA600
110                29                 3011               $0BC300
111                29                 3040               $0BE000
112                29                 3069               $0BFD00
113                29                 3098               $0C1A00
114                29                 3137               $0C3700
115                29                 3156               $0C5400
116                29                 3185               $0C7100
117                27                 3214               $0C8E00
118                27                 3241               $0CA900
119                27                 3268               $0CC400
120                27                 3295               $0CDF00
121                27                 3322               $0CFA00
122                27                 3349               $0D1500
123                27                 3376               $0D3000
124                27                 3403               $0D4B00
125                27                 3430               $0D6600
126                27                 3457               $0D8100
127                27                 3484               $0D9C00
128                27                 3511               $0DB700
129                27                 3538               $0DD200
130                27                 3565               $0DED00
131                25                 3592               $0E0800
132                25                 3617               $0E2100
133                25                 3642               $0E3A00
134                25                 3667               $0E5300
135                25                 3692               $0E6C00
136                25                 3717               $0E8500
137                25                 3742               $0E9E00
138                25                 3767               $0EB700
139                25                 3792               $0ED000
140                25                 3817               $0EE900
141                25                 3842               $0F0200
142                23                 3867               $0F1B00
143                23                 3890               $0F3200
144                23                 3913               $0F4900
145                23                 3936               $0F6000
146                23                 3959               $0F7700
147                23                 3982               $0F8E00
148                23                 4005               $0FA500
149                23                 4028               $0FBC00
150                23                 4051               $0FD300
151                23                 4074               $0FEA00
152                23                 4097               $100100
153                23                 4120               $101800
154                23                 4143               $102F00

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:

         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
     ...
     F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

Bytes                  Description
$00-$01                T/S pointer to first BAM sector (38/0)
$02                    $43 'C' is for DOS format version
$03                    Reserved
$04-$05                Unused
$06-$16                Disk name, padded with 0xA0 ("sample d82")
$17                    0xA0
$18-$19                Disk ID bytes "er"
$1A                    0xA0
$1B-$1C                DOS version bytes "2C"
$1D-$20                0xA0
$21-$FF                Unused

Below is a dump of the first directory sector, 39/1

         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

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:

Bytes          Description
$00-$1F        First directory entry
$20-$3F        Second dir entry
$40-$5F        Third dir entry
$60-$7F        Fourth dir entry
$80-$9F        Fifth dir entry
$A0-$BF        Sixth dir entry
$C0-$DF        Seventh dir entry
$E0-$FF        Eighth dir entry

This is a breakdown of a standard directory entry:

Bytes          Description
$00-$01        Track/Sector location of next directory sector ($00 $00
               if not the first entry in the sector)
$02            File type
$03-$04        Track/sector location of first sector of file
$05-$14        16 character filename (in PETASCII, padded with $A0)
$15-$16        Track/Sector location of first side-sector block (REL
               file only)
$17            REL file record length (REL file only, max.  value 254)
$18-$1D        Unused
$1E-$1F        File size in sectors, low/high byte order ($1E+$1F*256).
               The approx.  filesize in bytes is <= #sectors * 254

The file type field is used as follows:

Bits           Description
0-3            The actual file type
4              Unused
5              Used only during SAVE-@ replacement
6              Locked flag (Set produces ">" locked files)
7              Closed flag (Not set produces "*", or "splat" files)

The actual file type can be one of the following:

Binary         Decimal        File type
0000           0              DEL
0001           1              SEQ
0010           2              PRG
0011           3              USR
0100           4              REL

Values 5-15 are illegal, but if used will produce very strange results.

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

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

         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

Bytes                  Description
$00-$01                T/S pointer to second BAM sector (38/3)
$02                    DOS version byte (0x43='C')
$03                    Reserved
$04                    Lowest track covered by this BAM (0x01=1)
$05                    Highest+1 track covered by this BAM (0x33=51)
$06-$0A                BAM for track 1.  The first byte shows the
                       "blocks free" for this track, the remaining 4
                       show the BAM for the track.
$0B-$0F                BAM for track 2
...                    ...
$FB-$FF                BAM for track 50

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:

      FF=11111111, FF=11111111, FF=11111111, 1F=00011111

In order to make any sense from the binary notation, flip the bits
around.

                 111111 11112222 222222
      01234567 89012345 67890123 456789...
      -------------------------- ---------
      11111111 11111111 11111111 11111000
      ^                              ^
      sector 0                  sector 28

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

         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

Bytes                  Description
$00-$01                T/S pointer to third BAM sector (38/6)
$02                    DOS version byte (0x43='C')
$03                    Reserved
$04                    Lowest track covered by this BAM (0x33=51)
$05                    Highest+1 track covered by this BAM (0x65=101)
$06-$0A                BAM for track 51.  The first byte shows the
                       "blocks free" for this track, the remaining 4
                       show the BAM for the track.
$0B-$0F                BAM for track 52
...                    ...
$FB-$FF                BAM for track 100

Third BAM block 38/6

         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

Bytes                  Description
$00-$01                T/S pointer to fourth BAM sector (38/9)
$02                    DOS version byte (0x43='C')
$03                    Reserved
$04                    Lowest track covered by this BAM (0x65=101)
$05                    Highest+1 track covered by this BAM (0x97=151)
$06-$0A                BAM for track 101.  The first byte shows the
                       "blocks free" for this track, the remaining 4
                       show the BAM for the track.
$0B-$0F                BAM for track 102
...                    ...
$FB-$FF                BAM for track 150

Fourth BAM block 38/9

         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

Bytes                  Description
$00-$01                T/S pointer to first directory sector (39/1)
$02                    DOS version byte (0x43='C')
$03                    Reserved
$04                    Lowest track covered by this BAM (0x97=151)
$05                    Highest+1 track covered by this BAM (0x9B=155)
$06-$0A                BAM for track 151.  The first byte shows the
                       "blocks free" for this track, the remaining 4
                       show the BAM for the track.
$0B-$0F                BAM for track 152
...                    ...
$15-$19                BAM for track 154
$1A-$FF                Not used

