SALV - Salvager for the SITS file system.

doc/rjl/salvd.3

@@ -0,0 +1,128 @@
+SALV, the SITS/LOGO File System Checker
+
+Introduction
+
+	The program called SALV is a utility program for the maintence of
+disks for the SITS/LOGO systems. Its main function is to provide a consitency
+check of the directory structure on the disks, but it also includes functions
+for initializing format and file structure, and copying disks in various ways.
+The purpose of this document is to aquaint the reader with both the theory
+and the operation of SALV, and in particular give him enough information
+to enable him to deal with both day-to-day file system maintence and the
+many special problems that can arise.
+
+The SITS File System
+
+	The SITS file system provides users of the SITS system with very flexible
+ways of maintaining disk files. It makes no attempt to impose any restrictions
+on the type and format of the data stored in the files, provided that that data
+can be represented as an ordered vector of 16 bit words. It does, however,
+impose a structure of 1directories0 in which files may be kept. That structure
+is a strictly inverted tree, that is, pointers from directories must always
+point downward in the structure. Also, no directory may be pointed at by
+more or less than one other directory, except in the special case of the
+1root0 directory, which no other directory points to. Now, we shall try to
+clarify this.
+
+The Notion of Directory
+
+	In the SITS file system, a directory is a vector of files and 
+inferior directories. The inferior directories may in turn contain
+directories. Each entry in the vector has a name and a type and possibly
+a version number. The entries are kept in alphabetical order by name, and
+when names are the same, in numerical order by version number. Each entry
+also contains a block descriptor which provides the disk addresses of zero
+or more blocks that are associated with the file or directory described
+by the entry. There are also two special entries at the beggining of each
+directory which we will discuss later.
+	At the very top of the directory structure of each disk is the special
+directory called the root. The main thing that is special about
+the root directory is that its disk address is predefined.
+The first block of the root directory of each logical disk resides on block 46 of that
+disk. All other information about what is where on any given disk
+can and must be determined by reading the root directory and
+following the tree structure downwards to the file or directory of
+interest.
+
+Files
+
+	A file is a vector of 8 bit bytes stored in blocks of 1024 bytes
+on the disk. Each byte has a number assigned to it called its 1address in the
+file0. Thus, the first byte of a file is byte 0, the last byte in the
+first block of a file is byte 1023, etc. A file has a length, which is the
+byte address of the last byte of the file; this length is not restricted
+to be a multiple of 1024, nor of 2.
+Files may in theory be up to
+2**25 (about 33.5 million) bytes long, but other restrictions reduce this.
+It is possible for there to be 1holes0 in the file
+these holes must start and end on file address which are a multiple of 1024,
+that is, on block boundaries. These holes are not particularly useful
+and we will attempt to avoid any futher discussion of them.
+	The directory entry for a file contains two pieces of information
+that describe the file: the file address of the first byte which is
+1not0 in the file, and an encoded list of the disk block addresses
+where the bytes of the file reside.
+	In addition to the name and version number the file entry also
+contains the date and time that the file was created. The file
+entry also potentially contains an 1access list0 which would
+restrict access to files to specified users, but neither LOGO nor
+SITS support this feature.
+
+Operation of the SALV Program
+
+	Now that the reader (hopefully) has a general idea of what the
+file system looks like, we will switch topics drascially and discuss
+the operation of the SALV program, particularlly it's user interaction.
+	The SALV program currently can only be run standalone, that is,
+it cannot be run under the SITS timesharing system since it does
+direct hardware disk operations, and also because the operation of
+SITS could cause the file structure to become inconsistent.
+SALV can either be loaded with RUG or directly from paper tape.
+Its starting address is 1000, and it can be safely restarted at
+(almost) any time. Restarting SALV is a perfectly valid way to
+abort an operation. Generally, SALV is either waiting for command
+input from the teletype or running performing some function
+commanded from the teletype. It ignores typing while it is
+performing a function. All functions are initated with one character
+commands. Most functions also accept preceeding arguments or
+require inputs. Some of the more drastic functions require
+confirmation after they have described themselves. At
+any time SALV is waiting for an input character the character
+<control>Z may be typed which will cause SALV to execute
+a BPT instruction which should in turn cause RUG to be called,
+if SALV was loaded by RUG. If SALV is then proceeded (type <esc>P
+to RUG) you will reenter the typein wait you just left.
+SALV can also be restarted (type <esc>G to RUG) to go
+back to the beginning. The following commands take a 1 digit
+number preceeding the command as input. The number specifies
+which disk the command is to effect:
+
+	C	Check a disk. The main function of SALV.
+
+	I	Initialize a disk.
+
+	<control>F	Format a disk.
+
+The following commands take no preceeding input:
+
+	<control>U	Copy logigical disks 0 and 1 to logical disks
+			2 and 3, i.e. copy the fixed platter up to the
+			removable platter on double density drives.
+
+	<control>D	As <control>U, but copy 2 and 3 to 0 and 1, i.e.
+			copy removable down to fixed.
+
+	<control>C	Asks for two disk numbers and copies one logical
+			disk to another logical disk.
+
+(A note about the meaning of "logical disk": currently the only type
+of disk supported by LOGO/SITS/SALV/RUG is the RK11 compatible units
+made by DEC and others. The disk DEC makes has one disk per drive,
+and each disk has 203. tracks; this corresponds to the standard
+"logical disk". The drives made by Caleus and Wangco and supported by
+IMS disk controllers have 2 disks in each drive, one fixed and one
+removeable. Most of these have 203. tracks on each pyhsical disk
+and thus coorespond to 2 logical disks, but there are drives that
+have 406. tracks on each disk, and in this case, currently, each
+pyhsical disk cooresponds to 2 logical disks, and therefore there
+are 4 logical disks per drive. Clear?)