CBM ROM Loader
--------------

Informations provided by Luigi Di Fraia (armaeth@libero.it) as a guide to the
use of the Exam20 tool, by the same author, with TAP files using CBM ROM Loader.
These informations were previously available as part of the TZX project and
SubChrist's FinalTap documentation, but they were adapted to describe Exam20's
internal scanner. Therefore, they should be taken as a guideline to how Exam20
works, and not as the original standard specifications.


Pulse types
-----------

3 different pulse types were defined by CBM as standard for ROM Loader:

  (S)hort  : $2B (2840 Hz)
  (M)edium : $3F (1953 Hz)
  (L)ong   : $53 (1488 Hz)

anyway, the following values are more likely to be seen on C64 tapes and few
VIC20 ones:

  (S)hort  : $30
  (M)edium : $42
  (L)ong   : $56

Pulses are always interpreted as a pair:

  (S,M) = 0 bit
  (M,S) = 1 bit
  (L,M) = new-data marker
  (L,S) = end-of-data marker


Framing
-------

Each data byte is organized as follows:

  (?,?) (?,?) (?,?) (?,?) (?,?) (?,?) (?,?) (?,?) (?,?) (?,?)
    |     |     |     |     |     |     |     |     |     |
   bit0  bit1  bit2  bit3  bit4  bit5  bit6  bit7   |     |
                                                    |     |
                                               checkbit   |
                                                       data marker

So that, each byte is encoded as a sequence of 20 pulses (10 pairs):

  - 8 bits of information in LSbF format.

  - 1 checkbit which is computed as:

      1 XOR bit0 XOR bit1 XOR bit2 XOR bit3 XOR bit4 XOR bit5 XOR bit6 XOR bit7.

  - 1 data marker:

      the data is finished when you read an "end-of-data marker" (L,S) instead of (L,M).


Structure
---------

When a VIC20 or a C64 save a "BASIC program" or a "PRG file" to tape with the
following:

  SAVE "MY PROGRAM", 1    (BASIC program)
  SAVE "MY PROGRAM", 1, 1 (PRG file)

they create 4 files:

  HEADER
  HEADER REPEATED

  silence (roughly 0.4 seconds)

  DATA
  DATA REPEATED

When a SEQuential file is saved to tape with:

  OPEN N, 1, 1, "MY SEQ DATA" (no "End-of-tape marker" is saved)
  OPEN N, 1, 2, "MY SEQ DATA" ("End-of-tape marker" is saved after all files)

  PRINT# N, "DATA STARTS HERE..."
  ...  PRINT# N, "... DATA..."
  ...  PRINT# N, "STOP"

  CLOSE N

it's segmented, if required, and encapsulated into HEADER files. A padding is
automatically done, if required, since HEADER payload has a standard length (191
bytes). An empty HEADER (all "File name" and "body" bytes are $20) comes before
data:

  HEADER - SEQ file header
  HEADER - SEQ file header, REPEATED

One or more of these follow, depending on the SEQ data size:

  silence (duration is variable)

  HEADER - Data block for SEQ file
  HEADER - Data block for SEQ file, REPEATED

If an "End-of-tape marker" is requested, the OS saves an additional empty HEADER
just after the last "Data block for SEQ file":

  silence (roughly 0.34 seconds)

  HEADER - End-of-tape marker
  HEADER - End-of-tape marker, REPEATED


Pilot
-----

Pilot: various amounts of 'S' pulses.

The amount of pulses is:

  - $6A00 for HEADER
  - $1A00 for DATA, and HEADER when it contains "Data block for SEQ file"
  - $4F   for HEADER REPEATED and DATA REPEATED


Sync
----

Sync: a new-data marker, followed by a sync train (9 bytes):

  Both HEADER and DATA blocks have the following sequence:

    $89 $88 $87 $86 $85 $84 $83 $82 $81

  Both HEADER REPEATED and DATA REPEATED blocks have the same sequence
  with bit 7 clear:

    $09 $08 $07 $06 $05 $04 $03 $02 $01


HEADER
------

For any HEADER the following information is sent after the sync sequence:

  1 Byte   : File type.

    $01= BASIC program
    $02= Data block for SEQ file
    $03= PRG file
    $04= SEQ file header
    $05= End-of-tape marker

  Here starts what I refer to as HEADER "payload".
  In case File type is not $02, the following informations are sent too:

    2 Bytes  : Start Address (LSBF).
    2 Bytes  : End Address+1 (LSBF).
    16 Bytes : File Name.

  When File type is $02, SEQ file data starts immediately after File Type thus
  allowing the use of those 20 bytes to store additional data.

  After the File Name there is HEADER "body", 171 bytes, often used by commercial
  loaders to store executable loader code or pretty much any additional data or
  code the loader or program may require.
  It encapsulates Data for segmented SEQ files too, as discussed before.

  Last Byte: Data checkbyte (its data marker is "end-of-data marker"), computed as:

    0 XOR all other HEADER bytes, from "File type" to end of "body".


DATA
----

For any DATA the following information is sent after the sync sequence:

  DATA body

  Last Byte: Data checkbyte (its data marker is "end-of-data marker"), computed as:

    0 XOR all DATA "body" bytes.


Trailer
-------

  Some trailing tones ('S' pulses) follow both HEADER REPEATED and DATA REPEATED.
  The standard amount is $4E pulses.


C64 Notes
---------

HEADER blocks always load into the Tape Buffer at $033C.

If the File Type is 'BASIC Program' the start address for loading will be $0801
regardless of what may be written in the 'Start Address' field.