
*** Introduction to the various Emulator Formats

 Compiled by:    Peter Schepers
     Started:   August 24, 1996
Last updated:     June 26, 2000


---------------------------------------------------------------------------


  There are always questions asked regarding the various formats which  are
commonly used on either the emulators or  the  real  C64.  Most  often  the
question involves conversion... "What do I do with LNX files?" or "How do I
make these files work on the C64s emulator?". This document is  an  attempt
to explain their internal structure, what to do  with  them,  and  some  of
their respective strengths and weaknesses.

  Some of what is contained in this document has been compiled from various
sources, and I have given the appropriate attributions in the  CONCLUDE.TXT
file. Some of the information may not be accurate as it may have been taken
from other documents, and I have no first-hand experience with it.  I  will
try to make it as thorough as possible, but if there  is  something  wrong,
please alert me so I can make the appropriate changes for future releases.


  So far, this document covers the following emulator types:

  * D64 (1541 disk representation, with a description  of  RELATIVE  files,
         and some D64 variants)
  * X64 (for the X64/Vice emulator)
  * T64 (Tape images for the C64s emulator)
  * T64 .FRZ (FRoZen Files, saved emulator sessions)
  * PC64 (P/S/U/Rxx)
  * PC64 .C64 (saved emulator sessions)
  * D71 (1571 disk representation)
  * D81 (1581 disk representation)
  * G64 (GCR image of a 1541 disk)
  * F64 (not an image file, but a companion file to D64's)
  * N64 (64NET's custom files)
  * L64 (64LAN's custom files)
  * C64 (PCLINK's custom files)
  * CRT (CCS64 ROM cartridge files)
  * 64x (PC64 ROM files)
  * TAP (CCS64 TAPe files)

  ...as well as the following native C64 types,  some  of  which  are  also
  supported on the various emulators:

  * Disk file layout (how files are stored on 1541, 1571 & 1581 disks)
  * 4-file diskpacked ZipCode (or .Z64, 4 or 5 files, #!xxxxx)
  * 6-file SixPack ZipCode (or .Z64, #!!xxxx)
  * Filepacked ZipCode (or .Z64, x files, x!xxxxx)
  * LNX (LyNX)
  * ARK & SRK (ARKive & compressed ARKive)
  * LHA & LZH (header description only)
  * SFX (SelF-eXtracting LHA/LZH)
  * SDA (Self-Dissolving Archive)
  * ARC (ARChive)
  * ZIP (PKZIP)
  * CKIT (Compression KIT)
  * CPK
  * WRA & WR3 (Wraptor, version 1 to 3)
  * LBR (LiBRary, C64 only, not the C128 CP/M .LBR files)
  * GEOS VLIR (Variable Length Index Record)
  * CVT (GEOS ConVerT files)
  * SPY (SPYne)
  * Binary
  
  Also included is a very basic look at some C64 graphic bitmap formats (in
BITMAP.TXT), and the  saved  session  layout  of  the  Macintosh-based  C64
emulator "Power64" (in POWER64.TXT). Thanks to Peter Weighill for the above
info.

  Joe Forster/STA also wrote up a description of how the various  Commodore
drives (1541/1571/1581) allocate sectors and directory entries when  saving
files (under normal mode and under GEOS). It is included as DISK.TXT

  At  the  end  of  the  CONCLUDE.TXT  document  is  a   BINARY/HEX/Decimal
conversion chart, useful when you don't know  how  to  convert  the  number
bases around. It might come in handy when working  with  and  understanding
the GCR conversion that the SixPack ZipCode format uses.

  Right now there are several good utilities available to work with most of
the mentioned formats. The first is 64COPY, my own conversion program.  The
second is Star Commander, by Joe Forster/STA. Included with his program are
many smaller utilities such as Star ARK, Star LHA and Star ZIP, which  will
convert specific formats to D64 images.

                                                 Peter Schepers,
                                                 University of Waterloo.

                                          Email: schepers@ist.uwaterloo.ca


---------------------------------------------------------------------------


Most recent changes:

Aug 30/99 - Renamed cartridge document CCS_CART.TXT to CRT.TXT.
          - Added new cartridge definitions (#4-8)
          - Added PCVIC (PCV) VIC-20 emulator snapshot format
          - Added Phau Zeh (S20) VIC-20 emulator snapshot format

Mar 10/00 - Updated the CRT definitions

 Apr 7/00 - Updated the WRA (Wraptor) topic. Renamed topic  to  WRA-WR3  to
            reflect the changes that Wraptor has undergone.

Jun 19/00 - Added in DISK.TXT, a  description  of  how  the  1541/1571/1581
            drives save files to disk (written by Joe Forster/STA)

Jun 23/00 - Corrections to the D71  document  (removed  references  to  the
            SUPER SIDE SECTOR as the D71 doesn't use it)

Jun 30/00 - Additions to the CRT doc.


---------------------------------------------------------------------------


*** Terms and acronyms

  Many strange terms have come along with computers in general, and I  will
not attempt to explain them all, but some of the ones in this document  may
not be entirely clear. I will attempt to make things  a  little  easier  by
explaining some of the more common ones.


  <CR> - Short form for a Carriage Return ($0D) symbol.

  <LF> - Short form for a Line Feed ($0A) symbol.

  ASCII - This is an acronym for "American Standard  Code  for  Information
          Interchange". The standard  is  a  7-bit  code  covering  control
          codes, punctuation, alphanumeric (A to Z, 0 to 9) as well as math
          and a few other symbols. Since it is a 7-bit code, it ranges from
          $00 to $7F (0-127). This leaves the top 128-255 definable by  the
          vendor. The PC world has corrupted this standard making it 8-bit.

  BAM - An acronym for "Block Availability Map". Here  is  where  the  disk
        operating system keeps track of  what  sectors  are  allocated  (or
        available) for each track.

  BLOCK - This refers to sectors which  on  a  logical  level  are  grouped
          together. On a 1541 disk, it could be a series of sectors  linked
          together in a file, or a partition on a  1581  disk.  In  the  PC
          world it represents a "cluster"  of  sectors.  Generally  if  I'm
          referring to a grouping of sectors thats *not* 256  bytes  large,
          then I talk in blocks.

  BYTE - A group of 8 bits, the contents of 1 memory location.

  CHAIN - A series of sectors linked  together.  One  sector  will  have  a
          pointer to another, and that sector will point to another,  until
          the chain has no more forward pointers. A file stored on  a  1541
          disk would be considered a chain of sectors, but it  also  has  a
          directory entry explaining what the chain is for.

  FILETYPE - In the Commodore world, this would be the kind of file, be  it
             SEQ, REL, PRG, USR, GEOS etc. In the  DOS  world,  this  would
             possibly be the file extension, be it EXE, TXT, DOC. It  tells
             the user what file it is, making usage easier.

  GCR - An acronym for "Group Code Recording". This is the encoding  method
        Commodore uses to physically store the  information  on  the  disks
        (i.e. 1541). It encodes an 8 bit sequence into a 10 bit sequence so
        that long repeated sequences of 1's or 0's are avoided. These  must
        be avoided so that the timing of reading/writing to the disk  won't
        become "out of sync". As a user, you would not normally see the GCR
        information since the drive does all the conversion to  normal  HEX
        data before it gives it to you.

  HIGH/LOW - The bytes here are stored backwards compared to  the  LOW/HIGH
             method. See LOW/HIGH for more information.

  LINK - This is the track/sector values, stored in the first two bytes  of
         a sector, which point to (or "link" to) the t/s  location  of  the
         next sector. A  series  of  these  links  comprise  a  "chain"  of
         sectors.

  LOW/HIGH - This is how values are stored when they  exceed  one  byte.  A
             good example of this is the sector count of  a  D64  file.  To
             calculate the actual value, take the second value, multiply it
             by 256 and add the low  value.  You  will  now  get  the  real
             decimal value. i.e. (HIGH*256)+LOW=result.

             If you look at is as a HEX value, swap the  bytes  around  and
             put them together for the 16-bit HEX value. i.e. $FE $03 would
             be $03FE as a 16-bit HEX value.

  LSB/MSB - See LOW/HIGH.

  LSU - This is my own acronym meaning "last  sector  useage".  It  is  the
        value stored in byte position $01 (the "sector" value  of  the  t/s
        link) of the last sector of a file. This value is the offset  into
        the sector where the last byte is stored. It  also  represents  the
        byte count + 1, since a value of 255 would actually mean  only  254
        bytes of file data exists (full sector less the  2  bytes  for  t/s
        chain). Without reasonable knowledge of the disk layout, this  byte
        can be confusing, and hard to explain.

  NYBBLE - A grouping of 4 bits (half a byte), either the first or  last  4
           bits of an 8-bit binary number,  or  one  half  of  a  two-digit
           hexadecimal number.

           Typically, a byte will be broken down into two parts, the top  4
           bits and the bottom 4 bits. These are referred to as  the  upper
           and lower  nybble  respectively,  and  are  represented  by  two
           hexadecimal digits in base 16.

  PETASCII - (or PETSCII) This is Commodore's version  of  ASCII  (the  PET
             part of the name comes from the  first  computer  to  use  the
             code, the PET or Personal Electronic Transactor).

             Most of the codes from 0-127 are the same as ASCII, but  there
             are differences, especially  noticible  when  converting  text
             from a C64  to  a  DOS  machine.  Where  ASCII  has  uppercase
             characters, PETASCII has lower  case  ones,  and  vice  versa.
             Also, the top 128 characters (128 to 255) are quite  different
             from the PC "standard".

  RLE - An acronym for "Run Length Encoding". This is a simple  compression
        method, employed by most compression programs,  and  also  used  by
        some archive formats  (ZipCode,  CPK).  It  encodes  sequences  (or
        "runs", hence the name "RUN length...") of the same byte  (i.e.  00
        00 00 00 00  00)  into  a  smaller  string  using  a  shorter  code
        sequence, making the resultant file smaller than the original. This
        is the simplest form of file compression.

  SECTOR - It is best described as the method that the drive uses to  store
           the smallest group of bytes physically on the disk. On the  1541
           this refers to a group of 256 bytes stored together in a  single
           sector. On a PC disk, this is typically 512 bytes.

  SIGNATURE - A group of bytes, usually near or at the front of  the  file,
              which are used to identify the type of file. i.e. a PC64 file
              will always have the signature string "C64file" contained  at
              the beginning of the file.

  TAR - An acronym for "Tape ARchiver", a UNIX application, and  method  of
        backing up information.

