>!Implement

NOTES ON THE IMPLEMENTATION OF FILECORE
=======================================

This document has the following sections:

1) contents of source files
2) use of workspace
3) conventions
4) debugging

1) contents of source files
---------------------------

BigDirCode Handling big directories
Commands   Handling *commands
DebugOpts  Declares T and F and sets the debugging options
Defns      Definitions of constants
Errors     declares error numbers and builds error table
FileCore   GETs all the source files
FileCore00 Start of module, allocates workspace, and GETs Errors
FileCore05 useful subroutines
FileCore15 interfaces to low level disc op at various abstraction levels
FileCore20 routines maintaining disc <-> drive mapping
FileCore25 directory caching
FileCore30 more useful subroutines, including interfaces to rest of system
FileCore31 new map allocation
FileCore32 new map zone compaction
FileCore33 new map primitives
FileCore35 old free space map operations
FileCore40 filename and directory operations
FileCore45 OSFILE and map/directory writing to disc
FileCore60 OSFUN
FileCore70 open files
FileCore80 new open file write behind/read ahead/caching
Fixes      documents and sets switches for fixes since image became stable
FormSrvcs  Image filing system services
FormSWIs   Image filing system SWIs
GenSWIs    SWI decod
Identify   Identify
InitDieSvc Module init and finalisation and service calls
MsgsStuff  MessageTrans glue
MyMacros   Macros not in Hdr:Macros
TokHelpSrc Tokenised help generated from HelpText

2) use of workspace
-------------------

main module workspace
----------------------------------------------------------------------------
| misc. | Dir    | Directory cache : open file         | free    | winnie
| work  | Buffer |                 : file buffer cache | space   | defect
| space |        |                 :                   | maps    | lists
----------------------------------------------------------------------------
^0                                 ^ FileBufsStart     ^MapSpace ^DefectSpace

The size of the directory cache, file buffer cache, and hard disc maps are
kept in CMOS RAM. The hard disc maps are claimed in separate blocks from the
RMA so that if the value in CMOS RAM is wrong (due to reformatting or
connecting a different drive) the blocks can be returned and ones of the
correct size claimed. The file buffers are held after the file is closed and
are only thrown away when needed for other files, or when the directory
cache is allowed to temporarily expand into the file buffer cache.

The miscellaneous workspace contains various byte and word variables and
records such as the disc and drive records.

3) conventions
--------------
a) The routines are mostly callee save ie registers not explicitly returning
a result are preserved. Many subroutine calls document the registers
expected for parameters and results eg.

 BL     FullLookUp      ;(R1,R2->R0-R6,C,V)

means that R1 and R2 are parameters and that R0 to R6 are modified by the
call. Flags are listed in the result if they have significant meaning after
the call and it cannot be assumed that other flags are preserved.

b) The variable ReEntrance keeps track of the levels of nesting of calls.
This is used to detect illegal reentrance and must be modified appropriately
by all entry and exit points. Suitable macros and routines are declared in
FileCore30.

c) errors are kept in a different format internally - see Errors

d) disc addresses are kept in three forms for different levels of
abstraction. In each case the top 3 bits indicate the device and the other
29 bits define the position on the device.

external disc address - This is the form used to communicate with the
external device drivers and when calling RetryDriveOp. The top 3 bits is
the drive number and the bottom 29 bits is an offset in bytes from the
beginning of the disc.

disc address - This is the next level up where discs are abstracted from
drives and is used when calling RetryDiscOp. The top 3 bits is the disc
number and the bottom 29 bits is an offset in bytes from the beginning of
the disc.

indirect disc address - This is the top level and is used in new map discs
to abstract the SIN (system internal number) of a file from its allocation
on the disc. On old map discs it is exactly the same as a disc address. On
new map discs the top 3 bits are still the disc number. However bits 8-23 is a file id which can be looked up in the map and bits 0-7 are 0 for a file
which does not share a map chunk or the sector offset + 1 in the map chunk
if it does.

4) Debugging
------------
FileCore00 contains various switches which can be turned on to aid debugging.
Some of the more specialised are:

ExceptionTrap - To ensure the FIRST exception is trapped
VduTrap - To redirect debugging text in a circular fashion into the memory
          reserved for RAMFS. For time critical debugging.
SpoolOff - To turn spooling off for debugging text to prevent illegal reentry
IrqDebug - To disable debugging while IrqSema set to avoid being swamped by
           background scheduling debugging.
DebugSwitch - For all debugging to be conditional on the contents of a
              memory location to allow debugging to be turned on and off
              during a test.
