RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

Writing a FileCore module


Under RISC OS 3.6 FileCore has been extended to support larger discs than the versions previously supplied with RISC OS. This has been done by using sector addresses in the interface to FileCore modules, rather than the byte addresses previously used.

Obviously you cannot use these larger discs without both the new version of FileCore, and a new-style FileCore module that supports sector addressing. We therefore recommend that you write all new-style FileCore modules to use sector addressing internally. Existing old-style FileCore modules must be rewritten to use sector addressing before you can use them with large discs.

Declaring your module

The process for registering a FileCore module has been extended so that each of FileCore and the registering FileCore module can determine whether the other supports sector addressing. You must use this process whenever you register a new-style FileCore module, including on module reinitialisation.

Descriptor block

The first stage in registering a new-style FileCore module is the same as before; your module must call FileCore_Create. Two new flag bits have been defined in the descriptor block it passes:

Bit Meaning when set
8 FileCore module supports MiscOp 7
9 FileCore module uses sector offsets (ie uses the new FileCore format)

All versions of FileCore that do not support MiscOp 7 or sector addressing simply ignore these flag bits.

Ensuring the new FileCore is present

Immediately you have a registered a new-style FileCore module using FileCore_Create, you must then check it is running under the new FileCore. To do so, you should call FileCore_MiscOp 6 using the module's newly issued private word.

If no error is returned, you may then assume you are running under a FileCore that understands sector addressing, and can take full advantage of the new larger disc sizes available. See Running new-style FileCore modules under the new FileCore.

If an error is returned, the FileCore module is running under an old version of FileCore. You must then either:

Running new-style FileCore modules under the new FileCore

DiscOp entry

All disc addresses FileCore passes to the DiscOp entry point are sector addresses, rather than the byte addresses used by older versions of FileCore. Since your new-style module should be using sector addresses internally, you shouldn't need to translate these.

MiscOp entry

The only MiscOp entry point which takes a disc address is MiscOp 0 (Mount). FileCore can't know the sector size until after it has mounted the disc, so it can't pass a sector address to MiscOp 0. Thus the parameters passed to your module's MiscOp entry point are unchanged from earlier versions of RISC OS. The disc address of the boot block (&C00) is still passed as a byte address, and it is your module's responsibility to deal with this.

Returning errors

The meaning of R0 when returning an error has been extended so that sector addresses can be returned. From RISC OS 3.6 onwards, if bits 30 and 31 of R0 are set, then bits 0 - 29 point to a two-word block:

Offset Meaning
0 bits 0 - 7 are error number, bits 8 - 29 are clear
4 bits 0 - 28 are the sector number of the disc address, bits 29 - 31 are the drive number

Calling FileCore DiscOp SWIs

Your module is responsible for ensuring that any calls it makes to FileCore's DiscOp SWIs use the correct form of addressing:

  • FileCore_SectorOp uses sector addressing; your module doesn't need to translate its own internal sector addresses.
  • FileCore_DiscOp continues to use byte addressing; your module must translate between its own internal sector addresses and FileCore_DiscOp's byte addresses, both on entry and on exit.

    Since FileCore has to do a similar translation back to sector addresses before calling your module's low-level entry points, calling FileCore_DiscOp is inefficient, and your module should always use FileCore_SectorOp in preference.

Providing a SWI handler

Your module should provide a full SWI interface, including equivalents to all relevant FileCore SWI calls - both new and old. Any calls others make to your module's SWI handler will already use the correct form of addressing for the SWI being called, so typically your handler just needs to set R8 to point to your module's FileCore instance private word, and then call the equivalent FileCore SWI. It does not need to perform any address translation.

Running new-style FileCore modules under an old FileCore

Low-level entry points

If you are running your new-style FileCore module under a version of FileCore that does not understand sector addressing, FileCore will call your low-level entry points using the only form of addressing it knows about: byte addressing. See Module interfaces.

Calling FileCore SWIs

Your module must ensure that it only uses calls available under the old FileCore it is using. In particular this means that you must not call FileCore_SectorOp, but must instead use FileCore_DiscOp, translating between your module's own internal sector addresses and FileCore_DiscOp's byte addresses, both on entry and on exit.

Providing a SWI handler

Your module should still provide a full SWI interface, including equivalents to all relevant FileCore SWI calls - both new and old. Your SWI handler should downgrade any call to an unavailable 64 bit / sector-addressing SWI to instead call the corresponding 32 bit / byte-addressing FileCore SWI, and then fake the return values for the original 64 bit / sector-addressing call. Thus:

Your module's handler must not attempt to validate reason codes passed to its own DiscOp and MiscOp SWIs; you must - as usual - just set R8 to point to your module's FileCore instance private word, and then call the equivalent FileCore SWI. FileCore is responsible for faulting any unavailable reason codes, such as an attempt to call FileCore_MiscOp 6.

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015