Add some system documentation.

.CALLS - Symbolic system calls.
UUOS - Old system calls.
BINFMT - Program binary formats.
UFD - Disk format.

doc/sysdoc/binfmt.101

@@ -0,0 +1,272 @@
+BINARY FILE FORMATS
+
+This file documents the formats of absolute binary program
+files on ITS, as understood by the LOAD symbolic system
+call.
+
+There are two different file formats:  "SBLK" files, and
+"PDUMP" files.  Each has its advantages.  An SBLK file is
+easier to write, when that must be done "by hand"; it is
+usually smaller than a PDUMP file containing the same
+information.  On the other hand, a PDUMP file can record
+the accessibility of the pages dumped, including the fact
+that some pages may not exist, and when it is loaded such
+pages will be left nonexistent;  an SBLK file would lose
+that information, and when loaded would fill in all gaps in
+the page map, which may be very slow.  On the third hand, a
+PDUMP file loads a whole page or it loads nothing in the
+page, while an SBLK file may specify contents for some
+words in a page but leave the others unmentioned; thus,
+when a file is to be merge-loaded an SBLK file may be
+advantageous.
+
+
+A.  SBLK FILES
+
+An SBLK file contains one or more blocks, each of which
+specifies the data to be loaded into one or more
+consecutive words of core.
+
+ 1. RIM10 LOADER
+
+The file begins with an essentially arbitrary prologue,
+whose end is marked by a word containing a JRST 1
+instruction.   The intention of the prologue is to contain
+a RIM10-format program which will load the rest of the SBLK
+file, assuming that it has been punched on paper tape and
+read in using KA-10 "read-in" mode (The one normally used
+happens to end with a JRST 1).  However, if that mode of
+operation is not desired, the JRST 1 may be the first word
+of the SBLK file.  In any case, the prologue's first word
+should be nonzero, so that the file will not appear to be a
+PDUMP file.
+
+ 2. SIMPLE BLOCKS
+
+After the JRST 1 come one or more "simple blocks" (whence
+comes "SBLK file").  Each simple block starts with an
+AOBJN-pointer to the range of core to be loaded;
+explicitly, -<number of words>,,<first word's address>.  It
+is inadvisable for any block to load more than 1K, or for a
+block's range to wrap around from -1 to 0.  After the
+range-word come as many words of data as the range-word
+specifies.  The simple block is completed by the checksum
+word, which is computed as follows:
+
+	(DO ((I 0 (1+ I)) (ACCUM 0))
+	    ((> I NUMBER-OF-DATA-WORDS) ACCUM)
+	    (SETQ ACCUM (+ (WORD I) (ROT ACCUM 1))))
+
+where the range-word is treaded as (WORD 0).  All SBLK
+files MUST be written with correct checksums, but it is not
+essential for all readers of SBLK files to check them
+(though it is better to do so).
+
+ 3. START ADDRESS
+
+A simple block always starts with a negative word.  
+A positive word seen when the beginning of another simple
+block was expected, indicates that there are no more simple
+blocks in the file.  The positive word itself is the "start
+instruction" of the file, and should be a jump of some sort.
+0 indicates that there is no starting address.
+
+                 Other Information Blocks
+
+After the start instruction come may come several different
+blocks of additional information.  Included are the symbol
+table, the undefined-symbol-table, and the random-info-block.
+Any or all of these may be absent in a given file.  
+Each of these are in the format of an Simple-block, including
+the checksum at the end of each block, which must be present
+and correct.
+
+ 4. SYMBOL TABLE
+
+The symbol table is divided arbitrarily into sections.
+Each section looks exactly like a simple block, with zero
+as the address to be loaded.  The first word is
+-<number of data words>,,0;  it is followed by that many
+words of data, followed by a checksum.  After each section
+may come another section;  encountering the duplicate start
+instruction (see 5, below) indicates the nonexistence of
+further sections.
+
+The symbol table itself is obtained by stripping out just
+the data words of the symbol table sections.
+
+See DDT ORDER for information on the contents of the symbol
+table.
+
+ 5. THE UNDEFINED SYMBOL TABLE
+
+
+Each section of DDT undefined symbol table starts with a
+word containing -<# of data words>,,1 (not 0!) after which
+come data words and a checksum.
+
+The two types of symbol table sections may be interspersed
+arbitrarily in the file.
+
+  6. Indirect Symbol Table Pointer
+
+An indirect file pointer looks just like a symbol table
+section except that its data consists of four filenames.
+It starts with a word -4,,2 (2 indicates this is an
+indirect pointer), followed by the device, fn1, fn2 and
+sname (each as a word of sixbit),  followed by the
+checksum.  A file may contain only one such indirect
+pointer, and it must be the last block present before the
+duplicate start instruction which ends the file.
+
+ 7. MISCELLANEOUS INFORMATION BLOCKS
+
+A Miscellaneous Info Block looks like a symbol table block
+except it consists of sub-blocks of various miscellaneous
+info, and begins with a word -<# wds in block>,,3 (the 3
+indicates it is a Misc Info block).  If there are more than
+one of these blocks, the division is not significant, and on
+loading into DDT they may be merged.  The sub-blocks look
+slightly like SBLK's but are entirely contained within one
+or more SBLK's and are *NOT* followed by individual
+checksums.  Only the top-level SBLK's have checksums.
+
+A Misc Info block consists of sub-blocks of the following form:
+-<# of words>,,<type>
+ <data words>
+
+The only currently defined sub-block type is type 1,
+
+Assembly Info:		   Sub-block type 1
+  -<# of words (normally 6)>,,1	 
+  <sixbit UNAME of person assembling>
+  <disk format time of assembly>
+  <source file device>
+  <source file fn1>
+  <source file fn2>
+  <source file sname>
+
+     There may only be one of these blocks in a file.  It
+     is created when MIDAS produces the file.
+
+------
+
+Debugging info:
+  -<# of words>,,2
+  <various debugging info to be defined soon>
+
+  This is intended for taking crash dumps and the like to
+  save various information that a person debugging it might
+  find useful.  It will not be found in most files; a
+  separate debugging dump command will be used to generate
+  it.
+
+ 8. THE DUPLICATE START INSTRUCTION
+
+This word is a second copy of the start instruction.
+It exists to terminate the symbol table, or indicate the
+absence of one.
+
+B. PDUMP FILES.
+
+ 1. INITIAL ZERO
+
+The first word of a PDUMP file is always zero.  This is
+to make it easy to distinguish PDUMP files from SBLK ones.
+
+ 2. PAGE MAP
+
+The next 256 words of the file are the file's "page map".
+The remaining words in the first page of the file are
+unused.
+
+The way a PDUMP file is loaded into a job is that each
+of the job's page slots is treated as specified by the
+corresponding word in the PDUMP file's page map.
+If the page map word is zero, nothing is done to that
+page slot in the job.  Otherwise, the page map word is
+decoded to determine how to obtain the page
+to put there.
+
+  a. Page-map - English Dictionary
+
+       Bit		    Meaning
+
+     400000,,	This is an absolute page.
+     200000,,	The job must not share with the
+		 file;  the job's page should be
+		 set up using %CBCPY.  Note that
+		 %CBCPY will be used in any case
+		 if the page is writeable.
+     100000,,	This page should be shared with
+		 some other page in the job's map.
+		 Should not be present with 400000,,.
+     400000	This page should be writeable.
+     200000	This page should be readable.
+        777	If 400000,, is set, the bottom
+		 bits contain the number of the
+		 page in the system.  If 100000,,
+		 is set, they contain the number of
+		 the other page in the job's map
+		 which is to be shared.
+		 These bits are ignored otherwise.
+
+Bits not mentioned should be ignored when reading,
+and written as zero.
+
+If neither 400000,, nor 100000,, is set, but either
+200000 or 400000 is set, a data page taken from
+the PDUMP file itself is put in the job's page slot.
+If neither 200000,, nor 400000 is set, the job actually
+shares memory with the file;  thus, all jobs into
+which the file is loaded will share that page.
+Otherwise, the file page is copied and the copy is
+put in the job's page slot.
+
+  b. English - Page-map Dictionary
+
+The meaningful word-patterns appear below.
+<access> is either 200000 for read-only, or 600000
+for read-write.  A star indicates a type of map-word
+that requires a corresponding data page in the file.
+
+      No page		  0
+  *   Pure page		  200000
+  *   Impure page	  600000
+  *   Unshared pure page  200000,,200000
+      Absolute page	  400000,,<access> <page #>
+	  Note that only PDP6 pages may be writeable.
+      A sharing of another page in the job
+			  100000,,<access> <page #>
+	  This is to be used when a single data
+	  page is to be loaded into two page slots
+	  (shared).  The lower page slot should
+	  specify the page as either pure, impure,
+	  or unshared impure.  The remaining page
+	  slot(s) should specify sharing with the first.
+
+ 3. AC's
+
+Since the AC's are not part of any page, they would not
+be saved in one of the data pages.  To compensate for
+this, they are saved in locations 1000 - 1017 in the
+first block of the file.
+
+ 4. DATA PAGES
+
+When page map words specify data pages, those data pages
+follow the page-map page.  There must be exactly as many
+data pages as there are map entries that require one, and
+the correspondence of data pages to such map entries is
+made by order in the file or in the map.
+
+ 5. START INSTRUCTION AND SYMBOL TABLE
+
+After the last data page come a start instruction, a symbol
+table, and a duplicate start instruction, just as in an
+SBLK file.
+
+
+;;; Local Modes: :::
+;;; Mode:TEXT :::
+;;; Fill Column:60 :::

doc/sysdoc/ufd.100

@@ -0,0 +1,148 @@
+Disk file directories are each one disk block
+of data (2000 words).  The file directory contains
+all the data necessary to maintain the actual files on the disk.
+The directory is arranged in two main portions.  The name area
+contains identification data for every file said
+to be "in that directory", including the file's names, time of
+creation, and a pointer to the descriptor area.  The descriptor
+area portion of a file directory describes exactly where on the disk
+the files are.
+
+The file SYSTEM; FSDEFS > contains a page beginning
+";UFD INFO", UFD meaning "user file directory".
+This page contains the assignment of most of the important
+symbols which define the directory format parameters.  The following
+description assumes the values of the parameters when this
+document was written, and although most of the parameters are not
+apt to change, there is this possibility.
+
+The first word of the file directory contains a pointer to the beginning
+of the descriptor area, and the second word points to the beginning
+of the name area.  The third word of the directory contains the sixbit
+user name of the directory.
+
+The name area of the directory contains 5 words
+of information for every file.
+
+1 - FN1 (SIXBIT)
+2 - FN2 (SIXBIT)
+3 - STATUS BITS & RANDOM INFO
+4 - CREATION DATE
+5 - DATE LAST REFERENCED
+
+The fourth word contains the compacted date and time of
+creation for the file.  The right half of this word is the
+time of day since midnight in half-seconds.  Bits 3.1-3.5
+are the day, bits 3.6-3.9 are the month, and bits 4.1-4.7
+are the year.  The fifth word's left half holds the date the
+file was last referenced.  This is in the same format as the
+creation date.
+
+	4.9-4.8 - UNUSED
+	4.7-4.1 - YEAR (RELATIVE TO 1900)
+	3.9-3.6 - MONTH (1=JAN)
+	3.5-3.1 - DAY (1-31)
+	2.9-1.1 - (RH) # HALF-SECS SINCE LAST MIDNIGHT (4th wd only)
+
+The third word in the name area for every file contains all
+the information about the file's status, with bits
+indicating things such as whether the file has been deleted,
+whether it is open for writing, etc.
+
+	4.9  -  FILE DUMPED TO TAPE
+	4.8  -  UNUSED
+	4.7-3.7 - # WORDS IN LAST BLOCK OF FILE
+	3.6  -  FILE DELETED FROM UNMOUNTED PACK
+	3.5  -  FILE WILL DISAPPEAR WHEN CLOSED BY ALL WHO HAVE IT OPEN
+	3.4  -  UNUSED
+	3.3  -  OPEN FOR WRITING
+	3.2  -  UNUSED
+	3.1  -  THIS FILE IS LINK
+	2.9-2.5 - PACK # FILE STORED ON
+	2.4-1.1 - BYTE ADDR PTR TO START OF FILE'S DESCRIPTOR BYTES
+
+2.4-1.1 is actually a byte address relative to a point 11.
+words from the beginning of the directory.  The byte size is
+6 characters, so the word address is the pointer divided by
+6, and the byte within that word can easily be determined by
+the remainder of the division.  Once the correct byte
+pointer is determined, successive ILDBs will get the
+descriptor bytes of the file.  Assuming the contents of A
+points to the third word of the name block for a file, here
+is a piece of code which will generate the correct byte
+pointer in N, all set for ILDBing, with N indexing B, which
+holds the correct word address:
+;B=2
+;C=3
+;UFDBYT==6		;SIZE OF BYTES
+;UFDBPW==36./UFDBYT	;NUMBER OF BYTES PER WORD
+;FDIRBF IS FIRST LOCATION IN DIRECTORY, UDDESC IS 11..
+
+	LDB B,[1500,,A]		;GET BYTE ADDRESS
+	IDIVI B,UFDBPW		;CHANGE TO WORD ADDRESS
+	ADDI B,FDIRBF+UDDESC
+	MOVNI N,-UFDBPW(C)
+	IMULI N,UFDBYT		;Only works because UFDBYT divides 36.
+	HRLI N,060200		;ASSUMING B=2 !!!!
+	ROT N,30.
+;END OF ROUTINE
+
+If the file is a link, the descriptor bytes themselves specify
+what directory and file names this file is linked to.  These
+three args are the only pieces of information in the descriptor
+area for links.  Each name is terminated by a semicolon unless
+it is a full six characters long.  Colon quotes the character
+that follows it.
+
+For normal disk files, every descriptor byte tells where the
+next block, or group of blocks, of the file resides on the
+disk.  A byte with a value of 0 ends the description.  A byte
+with the value 31. (UDWPH) is an ignored place-holder.  If
+the byte is from 1 through 12. (UDTKMX), that many blocks
+of the file reside contiguously.  If the byte is from 13.
+through 30., skip that many blocks minus 12., and the next
+block, after the ones skipped, is in the file.  If the 40
+bit of the byte is set, the low 4 bits of that byte together
+with the next 2 bytes tell where the next block of the file
+is to be found.  When the 40 bit is set, the 20 bit is a
+flag which, if on, says that blocks that follow each contain
+a word count in their last word.
+
+Occasionally when a program tries to open a file for
+writing, there is no more room in the file directory for the
+file's specifications, not because there is really no room,
+but because non-existant (deleted) files still have
+descriptors etc. taking up unnecessary room.  When this
+happens, the system rearranges the directory, a
+"housekeeping" chore known as garbage collecting.  Garbage
+collecting a file directory takes about 1-2 minutes of
+realtime waiting, usually.  If the system is provoked to
+garbage collect FOO's file directory, it announces the
+occasion on the system job console with the message "GC OF
+USER DIR FOO".  During the ordeal, the job provoking the
+collection may not be control-Zed amongst other things.  If
+you try to control-Z it, however, the only noticeable
+difference to you will be a long wait before DDT knows to
+recognize your request for interruption.  If ^Z seems not to
+be "doing much", try checking the system job console to see
+if you are being garbage collected.
+
+File directories are read by timesharing programs the way
+any disk files are read.  Merely use the file name .FILE.
+(DIR) for the .OPEN, and the system will supply you with the
+directory instead of a file.  If the mode is ASCII, the data
+you receive after .OPENing .FILE.  (DIR) is the ASCII string
+you normally see, upon doing :LISTF DSK: or DSK in DDT or
+EYDSK: in TECO.  If the mode for the .OPEN is image, the
+data you receive is the actual file directory as advertised,
+and as stored on the disk.  As already mentioned, it is
+exactly 2000 octal words long, and is organized exactly as
+described above.  Any program opening disk file directories
+for the purpose of seeing what files are on the directory
+will be far more efficient opening the directory in image as
+opposed to ASCII mode.  Such programs, when written in MIDAS
+assembly language, should .INSRT SYSTEM; FSDEFS > and use
+the symbolic definitions therein, for greater clarity and
+immunity to system changes.
+
+