FileCore 32-bit/64-bit APIs

Document version 0.11, 20 December 2002

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

Alternative disc record pointers passed in to various SWIs currently only have a 26-bit range.
FileCore_SectorDiscOp limits discs to 2^29 sectors, ie 256GB for drives with 512 byte sectors.
Error code responses from filecore modules use the top bits of R0 to distinguish between error pointers and error codes.
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

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

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-29 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 bits 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 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).

FileCore background scatter lists

High (top-bit set) addresses are possible in a scatter list, thus only negative numbers smaller or equal to than -64K (ie >= unsigned &FFFF0000) should be interpreted as the end of list marker. This applies to any FileCore module for RISC OS 3.5 or later.