FileCore 32-bit/64-bit APIs
---------------------------

A number of changes are needed in FileCore to support both bigger discs (larger
than 256GB) and full 32-bit addressing.

  1) Alternative disc record pointers passed in to various SWIs currently only
     have a 26-bit range.
  2) FileCore_SectorDiscOp limits discs to 2^29 sectors, ie 256GB for drives
     with 512 byte sectors.
  3) Error code responses from filecore modules use the top bits of R0 to
     distinguish between error pointers and error codes.
  4) Block pointers in background transfers' "process status" word are 30-bit.

Items 1 and 2 are dealt with simultaneously by adding a new "DiscOp64" SWI.
This SWI also adds the headroom for larger discs, even if support is not added
immediately.

This new call uses larger disc addresses, which are passed by reference
rather than by value. Their structure is as follows:

   Word 0   bits 0-7: drive number
            bits 8-31: reserved, must be zero
   Word 1   byte address (low word)
   Word 2   byte address (high word)

In the future, this will allow for up to 16 exbibytes (over 16 billion GiB)
per disc, and many more discs per filing system. 


FileCore_DiscOp64 (SWI &4054C)
-----------------
In: R1   bits 0-3 = reason code
         bits 4-7 = option bits
         bits 8-31 reserved
    R2 -> disc address
    R3 = pointer to buffer (or scatter list)
    R4 = length in bytes
    R5 = pointer to alternative disc record, or zero
    R6 = cache handle
    R8 = pointer to FileCore instance private word
Out: R1 preserved
     R2 preserved; disc address pointed to is updated to point
        to the next byte to be transferred
     R3 = pointer to next buffer location to be transferred
     R4 = number of bytes not transferred


FileCore_Features (SWI &4054D)
-----------------
In: -
Out: R0   bit 0: FileCore supports new error scheme
          bits 1-31: reserved, equal to zero

Error responses
---------------
The current scheme for error returns from FileCore modules is as follows:

R0 bits 30-31 clear:      bits 8-29 clear
                          bits 0-7 error number
R0 bit 31 set, 30 clear:  bits 24-29 disc error number
                          bits 21-23 drive number
                          bits 0-20 disc byte address / 256
R0 bit 31 clear, 30 set:  R0 is an error pointer, once bit 30 is cleared.
R0 bits 30-31 set:        bits 0-29 point to a two-word block:
                             offset 0: bits 0-7 disc error number
                                       bits 8-31 clear
                             offset 4: bits 0-28 disc sector number
                                       bits 29-31 drive number

This whole scheme is predicated on addresses having their top bits clear.

For the new scheme, this is changed to use the least significant bits to
distinguish the types:

R0 < 256:              R0 = error number

Else:

R0 bits 0 & 1 clear:   R0 is an error pointer

R0 bit 0 set, 1 clear: R0 (once bit 0 cleared) points to a three-word block:
                           offset 0: bits 0-7   drive number
                                     bits 8-15  disc error number
                                     bits 16-31 clear
                           offset 4: 64-bit disc byte address
R0 bit 1 set:  reserved for future use

Clearly, this scheme is not compatible with the existing one, but the two forms
can easily be mechanically converted between.

To use this error scheme, a FileCore module must set the following flag bit
in the descriptor block passed to FileCore_Create:

      Bit        meaning when set
      10         FileCore module returns new-style errors

However, if you wish your module to work with older versions of FileCore, you
must return old-style errors when running with such a version. These versions
can be distinguished by calling FileCore_Features after registering. If no
error is returned, and bit 0 of R0 is on exit, you are running on a new
FileCore, and should return the new error codes. Otherwise, you should return
the old error codes - this can be easily be dealt with by using new-style
errors throughout the core of your module, and putting a small conversion
veneer on the error exit cases from your entry points.

Note that the same error codes are used in the process error word of
background transfer scatter lists; these should also use either the old or new
scheme appropriately.

If you are returning new-style errors, you must also store the most
significant 30 bits of the block pointer in the background transfer process
status word (ie bits 29-0 of process status correspond to bits 31-2 of the
address of the scatter list entry corresponding to an error).

