This is a documentation of the changes to the SWI interface to FileCore made
between version 2.04 and 2.05.

Changes to old SWIs.
--------------------

FileCore_DiscOp

Extended reason code, Write Track (4)

On entry
  R1 = &000000o4
  R2 = Disc address of start of track
  R3 = 0 (this distinguishes it from a normal Write track)
  R4 = Pointer to disc format structure
On exit
  All regs preserved, except in an error.

The disc format structure is as follows:
Offset  Length  Meaning
0       4       Sector size (bytes)
4       4       Gap1 side 0
8       4       Gap1 side 1
12      4       Gap3
16      1       Sectors per track
17      1       Density:
                1 - single (125Kbps FM)
                2 - double (250Kbps MFM)
                3 - Double+ (300Kbps MFM)
                4 - quad (500Kbps MFM)
                8 - octal (1000Mbps MFM)
18      1       Options:
                Bit 0   1 - index mark required
                Bit 1   1 - double step
                Bit 2-3 0 - alternate sides
                        1 - Format side 1 only
                        2 - format side 2 only
                        3 - Sequence sides
                Bit 4-7 reserved, should be 0
19      1       Sector fill value
20      4       cylinders per drive
24      12      Reserved, should be 0
36      ?       Sector ID buffer, 1 word per sector:
                bits    use
                0-7     Cylinder number mod 256
                8-15    Head (0 for side 1, 1 for side 2)
                16-23   Sector number
                24-31   Log2 sector size - 7, eg 1 for 256 byte sector

The o nibble in R1 is the flags nibble as normal. The SWI will format a
track of the specified disc. An error will occur if the specified format is
not possible to generate, or if the track requested is outside the valid
range. The tracks are numbered from 0, so the valid track numbers are 0 to
number of track minus one. The mapping of the address is controlled by the
disc structure record.

New reason code, CachedReadSectors (9)

In
  R1 = 9 (CachedReadSectors) 
  R2 = disc address
  R3 = pointer to buffer
  R4 = length in bytes
  R6 = Cache handle
  R8 = Pointer to FileCore instance private word

Out
  R1 preserved
  R2 = disc address of next byte to be transfered
  R3 = pointer to next buffer location to be transfered
  R4 = number of bytes not transfered
  R6 = New cache handle

This DiscOp reason code will read sectors via a cache held in the RMA. To
start a sequence of these operations call this with R6=0. The following
options apply when this reason is used:

An alternate defect list cannot be specified
A scatter list can not be specified
Escape can not be ignored
A 1 second timeout on floppy discs applies

Setting these options bits will have no effect. Multiple calls to this may
update R6, the cache handle. The new value of R6 must be used in subsequent
calls of CachedReadSectors. To discard the cache once finished call
FileCore_DiscardReadSectorsCache.

FileCore_Create

Notes on the PRM:
In the desciptor block the flag bits have the following meanings:
Bit     Meaning when set
0       Winnie needs FIQ
1       Floppy needs FIQ
2       Unused (The PRM incorrectly described this bit)
3       Use scratch space only when a temporary buffer is needed
        (The PRM did not describe this bit). Other areas
        which are sometimes used are:
                Spare screen memory
                Wimp free pool
                RMA heap
                System heap
                Application area
                Dir cache
        Here is a table of usage:

                Area:   SS      VDU     WF      RH      SH      AA      DC
        Usage:
        Rename          *       *       *       *       *
        Close           *       *       *       *       *
        EnsureSize      *       *       *       *       *
        AllocCompact    *       *       *       *       *
        Compact         *       *       *       *       *
        *Backup X X                     *       *       *               *
        *backup X Y     *       *       *       *       *
        *backup X X q                   *       *       *       *       *
        *backup X Y q   *       *       *       *       *       *
        *compact        *       *       *       *       *

        Key:
        SS      Scratch space
        VDU     Spare screen area
        WF      Wimp free pool
        RH      RMA heap
        SH      System heap
        AA      Application area
        DC      Directory cache
        Rename  fsfunc_Rename
        Close   fsentry_Close
        EnsureSize fsargs_EnsureSize
        AllocCompact Auto-compact triggered when allocating space for a file
        Compact Auto-compact
        *backup The *Backup command
        *Compact The *Compact command

4       Winnies support mount like floppies do, ie they fill in sector size,
        heads, sectors per track and density.
5       Winnies support poll change. This means the poll change call on a
        winnie will work and return a sensible value. This also means that
        locking winnies will have a sensible result.

New SWIs.
---------

FileCore_DiscardReadSectorsCache (&40546)

In
  R6 = Cache handle
Out
  Cache discarded


FileCore_DiscFormat (&40547)

In
  R0 = pointer to the disc format structure to be filled in (64 bytes)
  R1 = number of SWI to vet the format
  R2 = parameter to pass to the vetting SWI
  R3 = format specifier
Out
  regs preserved

This SWI fills in the format structure with the parameters for the specified
format. Once filled in the format structure will be vetted by the given SWI
before this SWI returns. The following format specifiers are defined:
        &80     L format floppy
        &81     D format floppy
        &82     E format floppy
        &83     F format floppy

FileCore_LayoutStructure (&40548)

In
  R0 = identifier of particular format to lay out
  R1 = pointer to bad block list
  R2 = pointer to nul-terminated disc name
  R3 = file handle
Out
  Regs preserved

This SWI will lay out into the specified file a set of structures
corresponding to the identified format. The format identifier is a pointer
to a disc record. An error will be returned if the specified format can not
map out defects and there were defects in the defect list.


FileCore_MiscOp

In
  R0 = reason
  R1 = drive
  R2..R5 depend on reason
  R8 = pointer to FileCore instance private word

Out
  R0..R6 depend on reason

This SWI provides various miscellaneous functions for accessing drives:

Misc_Mount
In
  R0 = 0
  R1 = drive
  R2 = disc address to read from
  R3 = pointer to buffer
  R4 = length to read into buffer
  R5 = pointer to disc record to fill in

Out
  R0..R5 preserved

This will mount the disc in the specified drive and fill in, where possible,
the physical details of the disc in the supplied disc record. The disc
record need only be 32 bytes long.

Misc_PollChanged
In
  R0 = 1
  R1 = drive
  R2 = sequence number
Out
  R2 = new sequence number
  R3 = result flags

This will sence the status of the drive. The sequence number is used to
prevent a user of Misc_PollChanged missing a change of disc in the drive.
The bits in the resul flags have the following meanings:
Bit     Meaning when set
0       Disc hasn't changed since last poll
1       Disc may have changed since last poll
2       Disc changed since last poll
3       Drive is empty
4       Drive is ready
5       Drive is 40-track
6       Drive has empty detection
7       Drive has disc changed detection
8       Disc in drive is high density
9       Disc density detection works
10      Drive ready works
11-31   Reserved for future use - will be 0.
Only one of bits 0-3 will be set at any time. To use this quote a sequence
number of 0 first time round and quote back the returned sequence number
from the last poll in each further poll.

Misc_LockDrive
In
  R0 = 2
  R1 = drive
Out
  -

This locks the disc in the drive. For floppy discs this causes the drive
light to remain illuminated until the drive is unlocked. Note that locks are
counted so that each LockDrive must be matched by an UnlockDrive.

Misc_UnlockDrive
In
  R0 = 3
  R1 = drive
Out
  -

This reverses the LockDrive miscellaneous operation.

Misc_PollPeriod
In
  R0 = 4
  R1 = drive
Out
  R5 = minimum polling period (in centi-seconds), or -1 if disc changed
        doesn't work.
  R6 = pointer to media type string eg 'disc' for ADFS.
