
What GoSDC stores on a flash card
---------------------------------

- Overall layout

There are four basic areas : global header, catalogue, free space, objects.
Suppose the catalogue area ends at card address #xxxxxxxx, the objects area
starts at #yyyyyyyy and the card itself ends at #zzzzzzzz, then the layout of
the areas on the card is as follows :

#00000000 - #00000200  global header
#00000200 - #xxxxxxxx  catalogue
#xxxxxxxx - #yyyyyyyy  free space
#yyyyyyyy - #zzzzzzzz  objects

- The global header

This is a single 512 byte block that is all zeroes except :

at offset #00 : 'GoMMCCat' (8 bytes)
at offset #10 : free space pointer for catalogue 'E' (4 bytes)
at offset #14 : free space pointer for objects 'F' (4 bytes)
at offset #20 : name of area (0-terminated)

'E' starts off as 0, and 'F' starts off as #zzzzzzzz. Whenever an object is
added to the card, 'E' increases by 1, and 'F' decreases by the number of bytes
needed to store the object. If 'F' would go below #xxxxxxxx, the card is 'full'
and the object is not added. This system allows a total number of objects that
is only limited by the card's storage capacity.

- The catalogue

This simply consists of 'E' catalogue entries. Each entry stores information
about a single object. A catalogue entry is a 64 byte block, and is all zeroes
except :

at offset #00 : type (1 byte)
at offset #01 : subtype (1 byte)
at offset #02 : property (1 byte)
at offset #04 : card address (4 bytes)
at offset #08 : size in bytes (4 bytes)
at offset #10 : name (48 bytes)

type is 1,2,3,4,5 for FS (filing system), tool, medium (disc or tape), UE
(utility or extension ROM), file. Currently, GoMMC and GoSDC for BBC/Electron
only use types 1,2,3, GoSDC for Atom only uses types 2,4,5.

subtype for type 1 is the (internal) filing system code (for a list, see Guide,
section 'Supported filing systems').

subtype for type 2 is always 0 (for now).

subtype for type 3 is 1,2,3,4 for 'DFS disc', 'ADFS disc', 'CFS tape' and
'HADFS disc'.

subtype for type 4 is a user-defined code.

subtype for type 5 is always 0 (for now), plus : name shortened to 38 bytes and
always terminated, file's load / exec / size at #36+2 / #39+2 / #3C+3.

property contains flags : bit 0 is set if the object was deleted.

card address is the absolute address of the exact start of the object. But note
that every object is also /preceded/ by an 'object header' (see below) to aid
in possible future 'recovery' operations.

size in bytes is the original object size. The total space occupied by the
object is the value of this field, rounded up to a multiple of 512, plus 512
(the size of the object header).

name is the object name (supplied by the user for object types 2, 3 and 5, or
by the system for object types 1 and 4). Name is 0-terminated, or fills up all
48 bytes.

NOTE !!! The catalogue is ordered (and should remain that way after mutations).
The order is by ascending type code (type 1 before type 2 etc.), then for types
2, 3 and 5 by 'ascending' name (ASCII character codes between 33 and 126
inclusive), and for types 1 and 4 by ascending subtype code. Type 0 entries may
appear anywhere (these are deleted type 1, 2 or 3 entries) but deleting is no
longer done this way (the relevant property flag should be set instead).

- The object header

This is a single 512 byte block that is all zeroes except :

at offset #00 : 'GoMMCEnt' (8 bytes)
at offset #10 : a copy of the object's catalogue entry (64 bytes)

- Object-internal storage

Everything except discs is simply stored 'as is'. Discs are stored in drive
order (for DFS 0,2,1,3 as usual, for ADFS 0,1,4,5), then within a drive simply
in linear order (for DFS this means the entire surface under a 'head', for ADFS
this means <all sectors head 0> <all sectors head 1>), i.e. all discs can be
addressed by <drive> then <head> then <track> then <sector> (regardless of the
filing system type).


