SpecServer/SerialServ file mapping
                     ==================================

Native
------
BBC load and execution addresses hold Spectrum load and execution addresses,
and the Spectrum filetype:

  BBC                   Spectrum
  Load Addr b0-b15  <-> Start Addr (autorun line, array name, load address)
  Exec Addr b0-b15  <-> Parameter Addr (VARS-PROG, execution address)
  Length            <-> Length
  Load/Exec b16-b17 <-> File type

On loading, the Spectrum filetype is formed by reading b16-17 from the BBC
load address and adding 4 times the difference between b16-17 of the BBC
load address and b16-b17 of the execution address.

On saving, b0-1 of the Spectrum filetype is stored in b16-17 of the BBC load
address and the filetype divided by 4 is subtracted from b0-b1 and stored in
b16-17 of the BBC execution address.

This results in the usual Spectrum filetypes 0, 1, 2 and 3 being reflected
in the load and execution address high bytes being the same, as here:

   LoadAddr  ExecAddr
  &0000xxxx &0000xxxx -> Type 0 (BASIC)
  &0001xxxx &0001xxxx -> Type 1 (NumArray)
  &0002xxxx &0002xxxx -> Type 2 (CharArray)
  &0003xxxx &0003xxxx -> Type 3 (Code)

Any more Spectrum filetypes would be encoded as follows:

  &0000xxxx &0001xxxx -> Type 4
  &0001xxxx &0002xxxx -> Type 5
  &0002xxxx &0003xxxx -> Type 6
  &0003xxxx &0000xxxx -> Type 7

  &0000xxxx &0002xxxx -> Type 8
  &0001xxxx &0003xxxx -> Type 9
  &0002xxxx &0000xxxx -> Type 10
  &0003xxxx &0001xxxx -> Type 11

  &0000xxxx &0003xxxx -> Type 12
  &0001xxxx &0000xxxx -> Type 13
  &0002xxxx &0001xxxx -> Type 14
  &0003xxxx &0002xxxx -> Type 15

DFS uses 18-bit addresses, so &0003xxxx appears as &FFFFxxxx.

Tapefile
--------
A Tapefile is filetyped to "TAPE" (DOS ".TAP"), type &11D (BBC load address
is &FFF11Dxx) or to Speculator "SpecTape" (DOS ".SPT"), type &701 (BBC load
address &FFF701xx). The file contains the file information header prefixing
the file data, as follows for a TAPE file:

  Byte  Content
   0-1: &0013 - Length of header, ignored on loading
     2:  &00  - Header type, ignored on loading
     3: File type: &00=Basic, &01=NumArray, &02=CharArray, &03=Code, etc.
  4-13: Filename, duplicate of leafname on saving, ignored on loading
 14-15: Length of data, lo-hi - ignored on loading
 16-17: Start address, lo-hi (load address)
 18-19: Extra address, lo-hi (exec address)
    20: Header checksum, ignored on loading
 21-22: &nnnn - Length of data portion, ignored on loading
    23:  &FF  - Data type, ignored on loading
 24...: Actual data
25+len: Data checksum, ignored on loading

A Speculator SpecTape file is the same, but the length fields are two less
(ie, bytes 0-1 contain &0011) and the checksum bytes are omitted, so the
data starts at byte 23.

The embedded header and data length, type and checksum, as well as the
embedded filename and file length are written correctly when saving, but are
ignored when loading. The checksums are generated by XORing all the bytes
from after the length (byte 2 or byte 23) to before the checksum (byte 19 or
byte 24+len). The server program only fetches the first entry in a tapefile.


Load Address
------------
This is the "parameter 1" or "start" field in the Spectrum file header.  For
a Basic program it is the autorun line if <&8000. For a Code file, it is the
address to load to if none is specified. For an array the high byte is the
array name.

 
Execution Address
-----------------
This is the "parameter 2" or "extra" field in the Spectrum file header. For
a Basic program it is VARS-PROG, the length of the Basic program excluding
the variables. For a Code file it is the start address the code is executed
from if RUN as machine code.


Running Machine Code
--------------------
When a piece of machine code is loaded and run it is entered with the
registers in the following state:

  BC= entry address
  DE=>command tail
  HL= undefined
  Cy=1
  A,Z=undefined

If a file's load address is &0000 it is loaded to a temporarily allocated
piece of memory. It's execution address is taken as the offset from the
start of the code at which to enter.

This is useful for small transient utilities. If it is small enough,
transient code is run on the stack. Where the transient memory is, and what
the system thinks is "small enough" are system-specific and may change from
time to time, including within a running system.


File Headers
------------
The load and execution addresses are stored in the order they occur in the
tape header. Interface 1 headers hold the information in a slightly
different order. These diagrams show where the addresses are expected.
(LOAD) means that on reading this field is filled with the load address; but
this field is ignored when writing.

              Tape Header                     Interface 1 Header
              -----------                     ------------------
Type 00 - BASIC
   00 01 -  - 0A 0B 0C 0D  0E 0F  10      00 01 02 03  04 05  06 07  08
  +--+--- -- ---+--+--+---+--+---+--+    +--+--+--+---+--+---+--+---+--+
  |00| Filename | LEN | LOAD | EXEC |    |00| LEN |(LOAD)| EXEC | LOAD |
  +--+--- -- ---+--+--+---+--+---+--+    +--+--+--+---+--+---+--+---+--+ 
          Length --+      |      |    Length --+             |      |
      Autostart line -----+      |            VARS-PROG -----+      |
               VARS-PROG --------+            Autostart line -------+

Type 01 - Number Array
   00 01 -  - 0A 0B 0C 0D  0E 0F  10      00 01 02 03  04 05  06 07  08
  +--+--- -- ---+--+--+---+--+---+--+    +--+--+--+---+--+---+--+---+--+
  |01| Filename | LEN | LOAD | EXEC |    |01| LEN | EXEC | LOAD |(LOAD)|
  +--+--- -- ---+--+--+---+--+---+--+    +--+--+--+---+--+---+--+---+--+ 
          Length --+       |          Length --+           |
           Array name -----+               Array name -----+

Type 02 - Character Array
   00 01 -  - 0A 0B 0C 0D  0E 0F  10      00 01 02 03  04 05  06 07  08
  +--+--- -- ---+--+--+---+--+---+--+    +--+--+--+---+--+---+--+---+--+
  |02| Filename | LEN | LOAD | EXEC |    |02| LEN | EXEC | LOAD |(LOAD)|
  +--+--- -- ---+--+--+---+--+---+--+    +--+--+--+---+--+---+--+---+--+ 
          Length --+       |          Length --+           |
           Array name -----+               Array name -----+

Type 03 - CODE
   00 01 -  - 0A 0B 0C 0D  0E 0F  10      00 01 02 03  04 05  06 07  08
  +--+--- -- ---+--+--+---+--+---+--+    +--+--+--+---+--+---+--+---+--+
  |03| Filename | LEN | LOAD | EXEC |    |03| LEN | LOAD | EXEC |(LOAD)|
  +--+--- -- ---+--+--+---+--+---+--+    +--+--+--+---+--+---+--+---+--+ 
          Length --+      |      |    Length --+      |      |
       Start address -----+      |    Start address --+      |
       Execution address --------+    Execution address -----+


History
-------
1.00 12-Apr-1988 Initial version.
1.10 15-Mar-1992 Added support for TAPE files.