Copyright (c) 1999 Massachusetts Institute of Technology This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. ------------------------------ 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, -,,. 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 -,,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>,, The only currently defined sub-block type is type 1, Assembly Info: Sub-block type 1 -<# of words (normally 6)>,,1 There may only be one of these blocks in a file. It is created when MIDAS produces the file. ------ Debugging info: -<# of words>,,2 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. 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,, Note that only PDP6 pages may be writeable. A sharing of another page in the job 100000,, 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 :::