sysdoc/binfmt.101

   1 Copyright (c) 1999 Massachusetts Institute of Technology
   2
   3 This program is free software; you can redistribute it and/or modify
   4 it under the terms of the GNU General Public License as published by
   5 the Free Software Foundation; either version 3 of the License, or (at
   6 your option) any later version.
   7
   8 This program is distributed in the hope that it will be useful, but
   9 WITHOUT ANY WARRANTY; without even the implied warranty of
  10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11 General Public License for more details.
  12
  13 You should have received a copy of the GNU General Public License
  14 along with this program; if not, write to the Free Software
  15 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16 ------------------------------
  17
  18 BINARY FILE FORMATS
  19
  20 This file documents the formats of absolute binary program
  21 files on ITS, as understood by the LOAD symbolic system
  22 call.
  23
  24 There are two different file formats:  "SBLK" files, and
  25 "PDUMP" files.  Each has its advantages.  An SBLK file is
  26 easier to write, when that must be done "by hand"; it is
  27 usually smaller than a PDUMP file containing the same
  28 information.  On the other hand, a PDUMP file can record
  29 the accessibility of the pages dumped, including the fact
  30 that some pages may not exist, and when it is loaded such
  31 pages will be left nonexistent;  an SBLK file would lose
  32 that information, and when loaded would fill in all gaps in
  33 the page map, which may be very slow.  On the third hand, a
  34 PDUMP file loads a whole page or it loads nothing in the
  35 page, while an SBLK file may specify contents for some
  36 words in a page but leave the others unmentioned; thus,
  37 when a file is to be merge-loaded an SBLK file may be
  38 advantageous.
  39
  40 \f
  41 A.  SBLK FILES
  42
  43 An SBLK file contains one or more blocks, each of which
  44 specifies the data to be loaded into one or more
  45 consecutive words of core.
  46
  47  1. RIM10 LOADER
  48
  49 The file begins with an essentially arbitrary prologue,
  50 whose end is marked by a word containing a JRST 1
  51 instruction.   The intention of the prologue is to contain
  52 a RIM10-format program which will load the rest of the SBLK
  53 file, assuming that it has been punched on paper tape and
  54 read in using KA-10 "read-in" mode (The one normally used
  55 happens to end with a JRST 1).  However, if that mode of
  56 operation is not desired, the JRST 1 may be the first word
  57 of the SBLK file.  In any case, the prologue's first word
  58 should be nonzero, so that the file will not appear to be a
  59 PDUMP file.
  60
  61  2. SIMPLE BLOCKS
  62
  63 After the JRST 1 come one or more "simple blocks" (whence
  64 comes "SBLK file").  Each simple block starts with an
  65 AOBJN-pointer to the range of core to be loaded;
  66 explicitly, -<number of words>,,<first word's address>.  It
  67 is inadvisable for any block to load more than 1K, or for a
  68 block's range to wrap around from -1 to 0.  After the
  69 range-word come as many words of data as the range-word
  70 specifies.  The simple block is completed by the checksum
  71 word, which is computed as follows:
  72
  73         (DO ((I 0 (1+ I)) (ACCUM 0))
  74             ((> I NUMBER-OF-DATA-WORDS) ACCUM)
  75             (SETQ ACCUM (+ (WORD I) (ROT ACCUM 1))))
  76
  77 where the range-word is treaded as (WORD 0).  All SBLK
  78 files MUST be written with correct checksums, but it is not
  79 essential for all readers of SBLK files to check them
  80 (though it is better to do so).
  81
  82  3. START ADDRESS
  83
  84 A simple block always starts with a negative word.
  85 A positive word seen when the beginning of another simple
  86 block was expected, indicates that there are no more simple
  87 blocks in the file.  The positive word itself is the "start
  88 instruction" of the file, and should be a jump of some sort.
  89 0 indicates that there is no starting address.
  90
  91                  Other Information Blocks
  92
  93 After the start instruction come may come several different
  94 blocks of additional information.  Included are the symbol
  95 table, the undefined-symbol-table, and the random-info-block.
  96 Any or all of these may be absent in a given file.
  97 Each of these are in the format of an Simple-block, including
  98 the checksum at the end of each block, which must be present
  99 and correct.
 100
 101  4. SYMBOL TABLE
 102
 103 The symbol table is divided arbitrarily into sections.
 104 Each section looks exactly like a simple block, with zero
 105 as the address to be loaded.  The first word is
 106 -<number of data words>,,0;  it is followed by that many
 107 words of data, followed by a checksum.  After each section
 108 may come another section;  encountering the duplicate start
 109 instruction (see 5, below) indicates the nonexistence of
 110 further sections.
 111
 112 The symbol table itself is obtained by stripping out just
 113 the data words of the symbol table sections.
 114
 115 See DDT ORDER for information on the contents of the symbol
 116 table.
 117
 118  5. THE UNDEFINED SYMBOL TABLE
 119
 120
 121 Each section of DDT undefined symbol table starts with a
 122 word containing -<# of data words>,,1 (not 0!) after which
 123 come data words and a checksum.
 124
 125 The two types of symbol table sections may be interspersed
 126 arbitrarily in the file.
 127
 128   6. Indirect Symbol Table Pointer
 129
 130 An indirect file pointer looks just like a symbol table
 131 section except that its data consists of four filenames.
 132 It starts with a word -4,,2 (2 indicates this is an
 133 indirect pointer), followed by the device, fn1, fn2 and
 134 sname (each as a word of sixbit),  followed by the
 135 checksum.  A file may contain only one such indirect
 136 pointer, and it must be the last block present before the
 137 duplicate start instruction which ends the file.
 138
 139  7. MISCELLANEOUS INFORMATION BLOCKS
 140
 141 A Miscellaneous Info Block looks like a symbol table block
 142 except it consists of sub-blocks of various miscellaneous
 143 info, and begins with a word -<# wds in block>,,3 (the 3
 144 indicates it is a Misc Info block).  If there are more than
 145 one of these blocks, the division is not significant, and on
 146 loading into DDT they may be merged.  The sub-blocks look
 147 slightly like SBLK's but are entirely contained within one
 148 or more SBLK's and are *NOT* followed by individual
 149 checksums.  Only the top-level SBLK's have checksums.
 150
 151 A Misc Info block consists of sub-blocks of the following form:
 152 -<# of words>,,<type>
 153  <data words>
 154
 155 The only currently defined sub-block type is type 1,
 156
 157 Assembly Info:             Sub-block type 1
 158   -<# of words (normally 6)>,,1
 159   <sixbit UNAME of person assembling>
 160   <disk format time of assembly>
 161   <source file device>
 162   <source file fn1>
 163   <source file fn2>
 164   <source file sname>
 165
 166      There may only be one of these blocks in a file.  It
 167      is created when MIDAS produces the file.
 168
 169 ------
 170
 171 Debugging info:
 172   -<# of words>,,2
 173   <various debugging info to be defined soon>
 174
 175   This is intended for taking crash dumps and the like to
 176   save various information that a person debugging it might
 177   find useful.  It will not be found in most files; a
 178   separate debugging dump command will be used to generate
 179   it.
 180
 181  8. THE DUPLICATE START INSTRUCTION
 182
 183 This word is a second copy of the start instruction.
 184 It exists to terminate the symbol table, or indicate the
 185 absence of one.
 186 \f
 187 B. PDUMP FILES.
 188
 189  1. INITIAL ZERO
 190
 191 The first word of a PDUMP file is always zero.  This is
 192 to make it easy to distinguish PDUMP files from SBLK ones.
 193
 194  2. PAGE MAP
 195
 196 The next 256 words of the file are the file's "page map".
 197 The remaining words in the first page of the file are
 198 unused.
 199
 200 The way a PDUMP file is loaded into a job is that each
 201 of the job's page slots is treated as specified by the
 202 corresponding word in the PDUMP file's page map.
 203 If the page map word is zero, nothing is done to that
 204 page slot in the job.  Otherwise, the page map word is
 205 decoded to determine how to obtain the page
 206 to put there.
 207
 208   a. Page-map - English Dictionary
 209
 210        Bit                  Meaning
 211
 212      400000,,   This is an absolute page.
 213      200000,,   The job must not share with the
 214                  file;  the job's page should be
 215                  set up using %CBCPY.  Note that
 216                  %CBCPY will be used in any case
 217                  if the page is writeable.
 218      100000,,   This page should be shared with
 219                  some other page in the job's map.
 220                  Should not be present with 400000,,.
 221      400000     This page should be writeable.
 222      200000     This page should be readable.
 223         777     If 400000,, is set, the bottom
 224                  bits contain the number of the
 225                  page in the system.  If 100000,,
 226                  is set, they contain the number of
 227                  the other page in the job's map
 228                  which is to be shared.
 229                  These bits are ignored otherwise.
 230
 231 Bits not mentioned should be ignored when reading,
 232 and written as zero.
 233
 234 If neither 400000,, nor 100000,, is set, but either
 235 200000 or 400000 is set, a data page taken from
 236 the PDUMP file itself is put in the job's page slot.
 237 If neither 200000,, nor 400000 is set, the job actually
 238 shares memory with the file;  thus, all jobs into
 239 which the file is loaded will share that page.
 240 Otherwise, the file page is copied and the copy is
 241 put in the job's page slot.
 242
 243   b. English - Page-map Dictionary
 244
 245 The meaningful word-patterns appear below.
 246 <access> is either 200000 for read-only, or 600000
 247 for read-write.  A star indicates a type of map-word
 248 that requires a corresponding data page in the file.
 249
 250       No page             0
 251   *   Pure page           200000
 252   *   Impure page         600000
 253   *   Unshared pure page  200000,,200000
 254       Absolute page       400000,,<access> <page #>
 255           Note that only PDP6 pages may be writeable.
 256       A sharing of another page in the job
 257                           100000,,<access> <page #>
 258           This is to be used when a single data
 259           page is to be loaded into two page slots
 260           (shared).  The lower page slot should
 261           specify the page as either pure, impure,
 262           or unshared impure.  The remaining page
 263           slot(s) should specify sharing with the first.
 264
 265  3. AC's
 266
 267 Since the AC's are not part of any page, they would not
 268 be saved in one of the data pages.  To compensate for
 269 this, they are saved in locations 1000 - 1017 in the
 270 first block of the file.
 271
 272  4. DATA PAGES
 273
 274 When page map words specify data pages, those data pages
 275 follow the page-map page.  There must be exactly as many
 276 data pages as there are map entries that require one, and
 277 the correspondence of data pages to such map entries is
 278 made by order in the file or in the map.
 279
 280  5. START INSTRUCTION AND SYMBOL TABLE
 281
 282 After the last data page come a start instruction, a symbol
 283 table, and a duplicate start instruction, just as in an
 284 SBLK file.
 285
 286 \f
 287 ;;; Local Modes: :::
 288 ;;; Mode:TEXT :::
 289 ;;; Fill Column:60 :::