LocalFile Implementor's Guide
Filed as [eris]<lispcore>internal>doc>localFileImpl.tedit
Written by Tayloe Stansbury 18-Feb-85

The Dandelion/Dove local file system has two layers: the Pilot layer and the Lisp streams layer.  The Pilot layer emulates a subset of the Pilot file system, as described in the Pilot Programmer's Manual.  The Lisp streams layer implements the Lisp streams specification laid out in [eris]<lispcore>internal>doc>streams.tedit.  

The Pilot layer is implemented by four files:

1.  DiskDlion, which talks to the disk microcode to transfer pages and labels to and from the disk.

2.  LFAllocationMap, which keeps track of which pages have been allocated and which are free.  LFAllocationMap provides the functionality of [idun]<apilot>11.0>pilot>private>volallocmapimpl.mesa, though its implementation is only very loosely based on that file.

3.  LFFileMap, which keeps track of the mapping between file ID numbers and runs of disk pages.  This mapping is stored in a specialized B-tree.  LFFileMap provides the functionality of [idun]<apilot>11.0>pilot>private>volfilemapimpl.mesa, though its implementation was based more on [idun]<apilot100>pilot>private>volfilemapimpl.mesa, and later updated to be compatible with the Mesa 11.0 release of Pilot.

4.  LFPilotFile, which has a primitive notion of file, as embodied in its datatype FileDescriptor.  LFPilotFile handles things like creating, extending, shrinking, and deleting files; reading and writing file pages; labels; and volume root directories (which map file types onto higher level directories -- e.g. Lisp file type -> Lisp directory ID, Mesa file type -> MFile directory ID, etc.).  LFPilotFile does not emulate any particular Mesa file, but rather grew up as the gray area between the two layers became more well-defined during the evolution of the Lisp local file system.

The Lisp stream layer is defined by two files:

1.  LFDirectory, which implements the Lisp directory.  The Lisp directory maps symbolic Lisp file names onto Pilot file ID numbers, and handles directory search and directory enumeration.

2.  LocalFile, which implements all other operations of the local disk file device.  LocalFile uses Pilot files as backing files for Lisp streams: page 0 of the Pilot file becomes the stream's leader page (containing stuff GETFILEINFO and the scavenger will be interested in), page 1 of the Pilot file becomes page 0 of the stream, etc.  Pilot backing files may be longer than the Lisp stream they hold.

In addition, there are two associated Library files (which at some point should probably be merged in with the rest of the file system):

1.  DskDisplay, which provides a window which displays file system status.  This file is part of the Pilot layer.

2.  ScavengeDskDirectory, which provides a scavenger for the Lisp directory.  (Failures at the Pilot layer can be scavenged by the Othello scavenger.)  ScavengeDskDirectory has one function that belongs in LFFileMap, and the rest are part of the Lisp stream layer.

At the time of this writing, the file system is stable, scavengeable, Pilot-compatible, and fixes all the file system AR's I know about.  However, the file system is a sink-hole for development work, and I can think of several other projects that might improve it (mostly in the area of speed):

1.  Get it to work on a Trident disk.  This may require fixing some minor bugs in the Trident half of DiskDlion.

2.  Modify DiskDlion to allow it to read or write multiple disk pages in a single operation.  This is possible (Pilot does it) and would speed up disk IO significantly.

3.  Modify LFAllocationMap to check and write labels on groups of disk pages in a single operation (to take advantage of #2).

4.  Modify LocalFile to read or write multiple stream pages in a single operation.

Should you have any questions, do not hesitate to contact me.  My mail address is Stansbury.pa, and my extension is 4330.  Good luck!