binfmt.101

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 :::