home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / pgmutl / val_link.arc / LKSLIDES.ARC / LKSLIDES.SRC < prev    next >
Text File  |  1989-02-18  |  68KB  |  1,335 lines
  1. Linker Overview
  2.                               Linker Overview
  3.  
  4. -  The primary purpose of a linker is to produce an file which can be executed
  5.    by an operating system.
  6.  
  7. -  In DOS, executable files come in three flavors:
  8.  
  9.                              "EXE" files
  10.                              "COM" files
  11.                              "SYS" files
  12.  
  13. -  The input to the linker comes from module(s) called translator modules.
  14.  
  15. -  Individual translator modules can be stored in "OBJ" files.  "OBJ" files
  16.    are produce by language translators such as assemblers and compilers.
  17.  
  18. -  Libraries of translator modules can be stored in "LIB" files which are
  19.    produced by a librarian from either "OBJ" files or other "LIB" files.
  20.  
  21. -  A linker can process translator modules from either "OBJ" or "LIB" files,
  22.    but at least one module must have come from an "OBJ" file.
  23.  
  24. -  All translator modules from "OBJ" files will be included in the executable
  25.    file, but only modules which resolve externals come from "LIB" files.
  26. Comparison of Executable Files (1 of 2)
  27.                         Comparison of Executable Files
  28.  
  29. -  "EXE" files have a header which contains relocation and other information
  30.    which permit "EXE" files to have multiple segments.  This header sets "EXE"
  31.    files apart from the other executable file types.  Programs are written
  32.    starting at address 0 (relative to where the program is loaded in memory).
  33.  
  34. -  "COM" files have no header.  "COM" files are written starting a address 100H
  35.    because the "COM" file is loaded immediately after the program segment prefix
  36.    (PSP) which is 100H bytes long.  At the start of the program, the CS and DS
  37.    segment registers point to the PSP.  "EXE" files which have an empty
  38.    relocation table can be converted to "COM" files by the "EXE2BIN" program.
  39.  
  40. -  "SYS" files are more closely related to "COM" files than "EXE" files.  "SYS"
  41.    files are loaded once at DOS initialization time.  Since there is no PSP,
  42.    the programs are written starting at address 0.  However, like "COM" files,
  43.    "SYS" files must have an empty relocation table.
  44. Comparison of Executable Files (2 of 2)
  45.                          Contents of Executable Files
  46.  
  47.  
  48.  
  49.     "EXE" files                                      "SYS" files
  50. ┌──────────────────┐                                ┌───────────┐
  51. │   "EXE" header   │                                │load module├──┐
  52. ├──────────────────┤                                └───────────┘  │
  53. │ relocation table │                                               │
  54. ├──────────────────┤                    ┌─────┐                    │
  55. │   load module    ├────────────────────┤org 0├────────────────────┘
  56. └──────────────────┘                    └─────┘
  57.  
  58.  
  59.  
  60.                         "COM" files
  61.                        ┌───────────┐                 ┌────────┐
  62.                        │load module├─────────────────┤org 100H│
  63.                        └───────────┘                 └────────┘
  64.  
  65.  
  66. -  Each of the above contents are described in detail in the following slides.
  67.  
  68. "EXE" File Header (1 of 2)
  69.                               "EXE" File Header
  70. ┌──────┬───────────────────────────────────────────────────────────────────────┐
  71. │Offset│                           Description                                 │
  72. ├──────┼───────────────────────────────────────────────────────────────────────┤
  73. │00-01 │ The "EXE" file signature 4D5AH.                                       │
  74. ├──────┼───────────────────────────────────────────────────────────────────────┤
  75. │02-03 │ Length of the "EXE" file modulo 512.                                  │
  76. ├──────┼───────────────────────────────────────────────────────────────────────┤
  77. │04-05 │ Number of 512-byte pages.  If the last page is not full it is still   │
  78. │      │ included in the count.                                                │
  79. ├──────┼───────────────────────────────────────────────────────────────────────┤
  80. │06-07 │ Number of relocation items.                                           │
  81. ├──────┼───────────────────────────────────────────────────────────────────────┤
  82. │08-09 │ Number of 16-byte paragraphs occupied by "EXE" header and relo table. │
  83. ├──────┼───────────────────────────────────────────────────────────────────────┤
  84. │0A-0B │ Number of paragraphs required immediately after load module.  The     │
  85. │      │ linker computes the number of uninitialized bytes at the end of the   │
  86. │      │ load module.  Instead of writing these bytes to the "EXE" file, the   │
  87. │      │ linker sets this value to provide space for this data.                │
  88. ├──────┼───────────────────────────────────────────────────────────────────────┤
  89. │0C-0D │ Maximum number of paragraphs which may be required immediately after  │
  90. │      │ the "EXE" file.  This value comes from the CPARMAXALLOC switch.       │
  91. └──────┴───────────────────────────────────────────────────────────────────────┘
  92. Note:  The "EXE" file header routines are in "EXECFILE.C" (handout page 9)
  93. "EXE" File Header (2 of 2)
  94.                               "EXE" File Header
  95. ┌──────┬───────────────────────────────────────────────────────────────────────┐
  96. │Offset│                           Description                                 │
  97. ├──────┼───────────────────────────────────────────────────────────────────────┤
  98. │0E-11 │ Offset/Segment displacement into the load module of the initial SP/SS.│
  99. │      │ The displacement is converted to an actual address by adding the base │
  100. │      │ address of the load module.  Since there may be several stack segments│
  101. │      │ in the translator modules, the linker uses the highest address of the │
  102. │      │ largest segment with the stack attribute.                             │
  103. ├──────┼───────────────────────────────────────────────────────────────────────┤
  104. │12-13 │ Word checksum computed as minus the sum of all the words in the file. │
  105. │      │ Overflows are ignored.  DOS will not validate the checksum if this    │
  106. │      │ value is set to zero                                                  │
  107. ├──────┼───────────────────────────────────────────────────────────────────────┤
  108. │14-17 │ Offset/Segment displacement into the load module of the initial IP/CS.│
  109. │      │ The displacement is converted to an actual address by adding the base │
  110. │      │ address of the load module.                                           │
  111. ├──────┼───────────────────────────────────────────────────────────────────────┤
  112. │18-19 │ Length of "EXE" file header.  (Used to find beginning of relo table.) │
  113. ├──────┼───────────────────────────────────────────────────────────────────────┤
  114. │1A-1B │ Overlay number.  This is zero for the main program.                   │
  115. ├──────┼───────────────────────────────────────────────────────────────────────┤
  116. │1C-1D │ Always 0001H.                                                         │
  117. └──────┴───────────────────────────────────────────────────────────────────────┘
  118. Relocation Table
  119.                                Relocation Table
  120.  
  121. The number of relocation items is specified at offset 06-07 in the "EXE" file
  122. header.  The offset of the relocation table is located at offset 18-19 in the
  123. "EXE" file header.  Usually this value is 001EH, but can be larger if the "EXE"
  124. file header has been extended.
  125.  
  126. The relocation table can be viewed as an array of Offset/Segment displacements
  127. into the load module.  For each address, the segment portion of the base address
  128. of the load module is added to the word at that displacement.  The only time a
  129. relocation item is needed is when a fixup involves a segment.  As we will see
  130. later, this can only be caused by base and pointer type fixups.
  131.  
  132. As an example of a how a relocation item is generated, consider the following:
  133.  
  134.                            foo      db      'a'
  135.                            bar      dd      foo
  136.  
  137. Note that the contents of "bar" is the address of "foo", but the actual address
  138. of "foo" is not known until the program is loaded in memory.  All that is known
  139. at link time is how far (i.e., the displacement) into the load module "foo" and
  140. "bar" are located.  Only the displacement of "foo" is stored at link time.  But,
  141. the linker makes a relocation entry showing that "bar"+2 must be relocated.
  142. Load Module
  143.                                  Load Module
  144.  
  145. By far, the generation of the load module is the trickest part of producing an
  146. executable file.  The contents of the load module is generated from the contents
  147. of translator modules stored in "OBJ" and "LIB" files.  Much of the structure
  148. of translator modules comes from the assembler directives.  In turn, those
  149. directives are related to the architecture of the 80x86 family of micros.
  150.  
  151. Here are some of the important directives:
  152.  
  153. SEGMENT/ENDS is used to give a logical name along with grouping and combining
  154.      information for the segments.  The linker is responsible for arranging and
  155.      combining these logical segments into the physical segments which comprise
  156.      a load module.
  157.  
  158. EXTRN/PUBLIC is used access data across translator modules.
  159.  
  160. A detailed description of the format of translator modules follows.
  161. Terminology and Abbreviations
  162.                          Terminology and Abbreviations
  163.  
  164. MAS - Memory Address Space:  The memory capable of being addressed by the
  165.     hardware architecture.
  166.  
  167. T-MODULE - Translator Module:  This is a unit of object code produced by a
  168.     language translator.  They may be stored individually in "OBJ" files or
  169.     collections may be stored in "LIB" files.
  170.  
  171. FRAME:  A contiguous 64K chunk of MAS.
  172.  
  173. FRAME NUMBER:  Paragraph number where a FRAME begins.
  174.  
  175. CANONIC FRAME:  For the 8086, each byte of memory is encompassed by up to
  176.     4096 FRAMEs.  The CANONIC FRAME frame is lowest FRAME NUMBER which
  177.     encompasses that byte.
  178.  
  179. LSEG - Logical Segment:  Data and code between SEGMENT - ENDS directives.
  180.  
  181. PSEG - Physical Segment:  A collection of one or more LSEGs placed into a
  182.     load module.
  183. Fixup Overview
  184.                                 Fixup Overview
  185.  
  186. Not all references to MAS can be resolved at translation time.  This can happen
  187. when one T-MODULE must access data located in another T-MODULE.  When this
  188. happens, the language translator places an entry in the T-MODULE so that the
  189. linker can complete the address reference.  Such entries in a T-MODULE are
  190. called "Fixups".
  191.  
  192. In order for the linker to complete the address reference, it needs five pieces
  193. of information:
  194.  
  195.            The LOCATION in memory where the reference occurs.  This is the address
  196.         which must be fixed up.
  197.  
  198.            The type of LOCATION in memory where the reference occurs.
  199.  
  200.            Whether the fixup is relative to the IP or not.  This is refered to
  201.         as the fixup MODE.
  202.  
  203.            The TARGET address which LOCATION is referencing.
  204.  
  205.            The FRAME number in the segment register used to reference the TARGET
  206.         address.
  207. LOCATION Types
  208.                                 LOCATION Types
  209.  
  210. There are five types of LOCATIONs.  They are POINTER, BASE, OFFSET, HIBYTE,
  211. and LOBYTE.  The relative position and length of each LOCATION type from a
  212. LOCATION, X is given below:
  213.  
  214.                  ┌──────────┬──────────┬──────────┬──────────┐
  215.                  │   X+0    │   X+1    │   X+2    │   X+3    │
  216.                  └──────────┴──────────┴──────────┴──────────┘
  217.  
  218.                  ├──LOBYTE──┤
  219.  
  220.                             ├──HIBYTE──┤
  221.  
  222.                  ├───────OFFSET────────┤
  223.  
  224.                                        ├────────BASE─────────┤
  225.  
  226.                  ├──────────────────POINTER──────────────────┤
  227. Fixup Modes
  228.                                  Fixup Modes
  229.  
  230. There are two fixup modes.  Both modes stem from the architecture of the 80x86
  231. microprocessor family.  The TARGET may be addressed directly via the
  232. offset/segment mechanism.  This fixup mode is called "segment-relative".
  233.  
  234. The other manner a TARGET may be addressed is relative to the IP.  For example,
  235. the TARGET of the 80x86 jump instructions (e.g., JE, JC, JA, etc) are all
  236. relative to the IP.  This fixup mode is called "self-relative".  Note that
  237. the self-relative mode is relative to the value of the IP when the instruction
  238. executes.  In all cases, the IP points to the first byte of the instruction
  239. following the one being executed.
  240. TARGET (1 of 3)
  241.                                     TARGET
  242.  
  243. The TARGET is the location in MAS being referenced by LOCATION.  There are
  244. four basic ways of specifying the TARGET.  The four methods of specifying
  245. a TARGET are:
  246.  
  247.                TARGET is specified relative to an LSEG.
  248.                TARGET is specified relative to a group.
  249.                TARGET is specified relative to an external symbol.
  250.                TARGET is specified relative to an absolute FRAME.
  251.  
  252. The four primary methods specify a displacement while the four secondary
  253. methods do not specify a displacement (because the displacement is 0).
  254. TARGET (2 of 3) -- Primary TARGET Methods
  255.                             Primary TARGET Methods
  256. ┌──────┬─────────────────────────┬─────────────────────────────────────────────┐
  257. │Method│       Notation          │               Description                   │
  258. ├──────┼─────────────────────────┼─────────────────────────────────────────────┤
  259. │  T0  │SI(segment),displacement │The TARGET is at the specified displacement  │
  260. │      │                         │in the LSEG segment.                         │
  261. ├──────┼─────────────────────────┼─────────────────────────────────────────────┤
  262. │  T1  │GI(group),displacement   │The TARGET is at the specified displacement  │
  263. │      │                         │in the group.                                │
  264. ├──────┼─────────────────────────┼─────────────────────────────────────────────┤
  265. │  T2  │EI(external),displacement│The TARGET is at the specified displacement  │
  266. │      │                         │past the external.                           │
  267. ├──────┼─────────────────────────┼─────────────────────────────────────────────┤
  268. │  T3  │FR(frame),displacement   │The TARGET is at the specified displacement  │
  269. │      │                         │past the FRAME NUMBER frame.                 │
  270. └──────┴─────────────────────────┴─────────────────────────────────────────────┘
  271.  
  272. Example:
  273.  
  274. SI(foo),4 means the TARGET is 4 bytes into the LSEG foo.  Several T-MODULES
  275. could have an LSEG named foo which may be combined into a PSEG foo.  So, the
  276. final displacement in the PSEG foo may not be 4.  The linker must take this
  277. into consideration.
  278. TARGET (3 of 3) -- Secondary TARGET Methods
  279.                            Secondary TARGET Methods
  280.  
  281.       ┌──────┬────────────┬─────────────────────────────────────────────┐
  282.       │Method│ Notation   │               Description                   │
  283.       ├──────┼────────────┼─────────────────────────────────────────────┤
  284.       │  T4  │SI(segment) │The TARGET is the base of the LSEG segment.  │
  285.       ├──────┼────────────┼─────────────────────────────────────────────┤
  286.       │  T5  │GI(group)   │The TARGET is the base of the group.         │
  287.       ├──────┼────────────┼─────────────────────────────────────────────┤
  288.       │  T6  │EI(external)│The TARGET is the specified external.        │
  289.       ├──────┼────────────┼─────────────────────────────────────────────┤
  290.       │  T7  │FR(frame)   │The TARGET is the specified frame.           │
  291.       └──────┴────────────┴─────────────────────────────────────────────┘
  292. FRAME (1 of 5)
  293.                                       FRAME
  294.  
  295. The FRAME portion of a fixup specifies the FRAME NUMBER that will be used as the
  296. frame of reference for LOCATION's reference to TARGET.  Typically, this frame of
  297. reference is one of the segment registers.  The FRAME NUMBER in the segment
  298. register is specified via the assembler "ASSUME" directive.
  299.  
  300. Even if the fixup is self-relative, the TARGET must still be in the FRAME given
  301. by the FRAME NUMBER in the segment register.  So, a FRAME is required for both
  302. segment-relative fixups and self-relative fixups.
  303.  
  304. There are seven methods of specifying a FRAME:
  305.  
  306.                                  A segment
  307.                                  A group
  308.                                  An external
  309.                                  An absolute FRAME NUMBER
  310.                                  LOCATION's FRAME
  311.                                  TARGET's FRAME
  312.                                  No FRAME specified
  313. FRAME (2 of 5) -- FRAME Methods F0 thru F3
  314.                                   FRAME Methods
  315.  
  316. ┌──────┬───────────────────────────────────────────────────────────────────────┐
  317. │Method│                          Description                                  │
  318. ├──────┼───────────────────────────────────────────────────────────────────────┤
  319. │  F0  │The FRAME for the fixup is the CANONIC FRAME of the PSEG containing the│
  320. │      │LSEG.  (Since the fixup is generated at translation time, an LSEG is   │
  321. │      │specified.)                                                            │
  322. │      │Notation:  EI(segment)                                                 │
  323. ├──────┼───────────────────────────────────────────────────────────────────────┤
  324. │  F1  │The FRAME for the fixup is the CANONIC FRAME of the PSEG located lowest│
  325. │      │in MAS.  A group is specified.                                         │
  326. │      │Notation:  GI(group)                                                   │
  327. ├──────┼───────────────────────────────────────────────────────────────────────┤
  328. │  F2  │The FRAME for the fixup is specified by an external.  Typically, the   │
  329. │      │external is located in a T-MODULE different from the T-MODULE          │
  330. │      │generating the fixup.                                                  │
  331. │      │Notation:  EI(external)                                                │
  332. ├──────┼───────────────────────────────────────────────────────────────────────┤
  333. │  F3  │The absolute FRAME number is specified.                                │
  334. │      │Notation:  FR(FRAME)                                                   │
  335. └──────┴───────────────────────────────────────────────────────────────────────┘
  336. FRAME (3 of 5) -- FRAME Methods F4 thru F6
  337.                                   FRAME Methods
  338.  
  339. ┌──────┬───────────────────────────────────────────────────────────────────────┐
  340. │Method│                          Description                                  │
  341. ├──────┼───────────────────────────────────────────────────────────────────────┤
  342. │  F4  │The FRAME is the CANONIC FRAME of the PSEG containing LOCATION.        │
  343. │      │Notation:  LOCATION                                                    │
  344. ├──────┼───────────────────────────────────────────────────────────────────────┤
  345. │  F5  │The FRAME is determined by the TARGET.  Notation:  TARGET              │
  346. ├──────┼───────────────────────────────────────────────────────────────────────┤
  347. │  F6  │No frame of reference specified.  Notation:  NONE                      │
  348. └──────┴───────────────────────────────────────────────────────────────────────┘
  349. FRAME (4 of 5) -- FRAME Method F2 cases
  350.                               FRAME Method F2 cases
  351.  
  352. When FRAME method F2 is specified (FRAME is specified by an external), there
  353. are three cases depending on how the external is defined:
  354.  
  355. ┌──────┬───────────────────────────────────────────────────────────────────────┐
  356. │Method│                          Description                                  │
  357. ├──────┼───────────────────────────────────────────────────────────────────────┤
  358. │  F2a │If the external is defined relative to an LSEG which is not in a group │
  359. │      │then the FRAME is the CANONIC FRAME of the PSEG containing the LSEG.   │
  360. ├──────┼───────────────────────────────────────────────────────────────────────┤
  361. │  F2b │If the external is defined absolutely and not in a group, then the     │
  362. │      │FRAME is the CANONIC FRAME of the external.                            │
  363. ├──────┼───────────────────────────────────────────────────────────────────────│
  364. │  F2c │If the external is associated with a group, the FRAME is the CANONIC   │
  365. │      │FRAME of the PSEG in the group with the lowest MAS.                    │
  366. └──────┴───────────────────────────────────────────────────────────────────────┘
  367. FRAME (5 of 5) -- FRAME Method F5 cases
  368.                               FRAME Method F5 cases
  369.  
  370. When FRAME method F2 is specified (FRAME is specified by the TARGET), there are
  371. four cases depending on how the TARGET was specified:
  372.  
  373. ┌──────┬───────────────────────────────────────────────────────────────────────┐
  374. │Method│                          Description                                  │
  375. ├──────┼───────────────────────────────────────────────────────────────────────┤
  376. │  F5a │If the TARGET method is T0 or T4, then FRAME is the CANONIC FRAME of   │
  377. │      │PSEG containing TARGET.                                                │
  378. ├──────┼───────────────────────────────────────────────────────────────────────┤
  379. │  F5b │If the TARGET method is T1 or T5, then FRAME is the CANONIC FRAME of   │
  380. │      │PSEG in the same group as TARGET and with the lowest MAS.              │
  381. ├──────┼───────────────────────────────────────────────────────────────────────┤
  382. │  F5c │If the TARGET method is T2 or T6, then the FRAME is determined by the  │
  383. │      │rules given in FRAME method F2.                                        │
  384. ├──────┼───────────────────────────────────────────────────────────────────────┤
  385. │  F5d │If the TARGET method is T3 or T7, then the FRAME is the FRAME NUMBER   │
  386. │      │specified by the TARGET.                                               │
  387. └──────┴───────────────────────────────────────────────────────────────────────┘
  388. Performing a Fixup (1 of 3)
  389.                                Performing a Fixup
  390.  
  391. Regardless of the fixup mode (segment-relative or self-relative), the first
  392. step in performing a fixup is to insure that the TARGET is addressable
  393. given the FRAME of reference.  That is, the TARGET must lie between FRAME
  394. and FRAME+65535 inclusive.
  395.  
  396.                           FRAME ≤ TARGET ≤ FRAME+65535
  397.  
  398. If this is not the case, a warning is given.
  399.  
  400. After verifying that TARGET can be addressed by FRAME, how a fixup is performed
  401. depends of the FIXUP mode.
  402.  
  403. Performing a Fixup (2 of 3) -- Self-Relative Fixups
  404.                               Self-Relative Fixups
  405.  
  406. Self-relative fixups are permitted for LOBYTE and OFFSET type LOCATIONs only.
  407. If the LOCATION type is HIBYTE, BASE, or POINTER, no fixup is performed and an
  408. error message is given.
  409.  
  410. For self-relative fixups, the value of the PC (CS:IP) when the instruction is
  411. executed must be determined.  Then, the DISTANCE to the TARGET from the PC is 
  412. computed.  The formulae for DISTANCE and PC are given below:
  413.  
  414.                      PC = LOCATION + 1 (If LOCATION type is LOBYTE)
  415.                      PC = LOCATION + 2 (If LOCATION type is OFFSET)
  416.                      DISTANCE = TARGET - PC
  417.  
  418. For LOBYTE locations, an error is issued when DISTANCE falls outside of
  419. -128 ≤ DISTANCE ≤ 127.
  420.  
  421. The fixup is performed by adding DISTANCE to LOCATION.  For LOBYTE LOCATIONs,
  422. DISTANCE is added modulo 256.  For OFFSET LOCATIONs, DISTANCE is added
  423. modulo 65536.
  424. Performing a Fixup (3 of 3) -- Segment-Relative Fixups
  425.                              Segment-Relative Fixups
  426.  
  427. For segment-relative fixups, DISTANCE = TARGET - FRAME.  If DISTANCE falls
  428. outside of 0 ≤ DISTANCE ≤ 65535, a warning is issued.  The following table
  429. gives how to perform the fixup depending on LOCATION type:
  430. ┌────────┬─────────────────────────────────────────────────────────────────────┐
  431. │LOCATION│                            Action                                   │
  432. │  type  │                                                                     │
  433. ├────────┼─────────────────────────────────────────────────────────────────────┤
  434. │LOBYTE  │DISTANCE is added (modulo 256) to the low order byte at LOCATION.    │
  435. ├────────┼─────────────────────────────────────────────────────────────────────┤
  436. │HIBYTE  │DISTANCE is added (modulo 256) to the high order byte at LOCATION.   │
  437. ├────────┼─────────────────────────────────────────────────────────────────────┤
  438. │OFFSET  │DISTANCE is added (modulo 65536) to the word at LOCATION.            │
  439. ├────────┼─────────────────────────────────────────────────────────────────────┤
  440. │BASE    │FRAME is added (modulo 65536) to the word at LOCATION.               │
  441. ├────────┼─────────────────────────────────────────────────────────────────────│
  442. │POINTER │DISTANCE is added (modulo 65536) the low order word at LOCATION.     │
  443. │        │A relocation item for the word at LOCATION is created.               │
  444. │        │FRAME is added (modulo 65536) to the high order word of the DWORD at │
  445. │        │LOCATION.  A relocation item for the high order word of the DWORD at │
  446. │        │LOCATION is created.                                                 │
  447. └────────┴─────────────────────────────────────────────────────────────────────┘
  448. T-MODULE Record Format (1 of 38) -- Basics
  449.                           T-MODULE Record Format Basics
  450.  
  451. All T-MODULE records have the following basic format:
  452.  
  453.                        ┌──────┬───────┬────────────────────┬─────┐
  454.                        │Record│ Record│Information Specific│Check│
  455.   Field Names─────────>│ Type │ Length│   to Record Type   │ Sum │
  456.                        ├──────┼───────┼────────────────────┼─────┤
  457.   Field Lengths───────>│  1   │   2   │  Record Length - 1 │  1  │
  458.      (bytes)           └──────┴───────┴────────────────────┴─────┘
  459.  
  460. Record Type --
  461.   This one byte field identifies the type of T-MODULE record.
  462.  
  463. Record Length -- 
  464.   This word contains the number of bytes in all following fields (including
  465.   the checksum).
  466.  
  467. Information Specific to Record Type --
  468.   This field contains the data for the specified Record Type.
  469.  
  470. Check Sum --
  471.   This byte contains the negative of the sum of all the preceding bytes in the
  472.   record.  Therefore, the sum of all the bytes in the record will be 0.
  473. T-MODULE Record Format (2 of 38) -- Bit Fields
  474.                       T-MODULE Record Format -- Bit Fields
  475.  
  476. Bit fields are denoted as follows:
  477.  
  478.                                ┌─────┬─────┬─────┐
  479.                                │ Bit │ Bit │ Bit │
  480.         Field Name────────────>│Field│Field│Field│
  481.                                │  1  │  2  │  n  │
  482.                                ├─────┼─────┼─────┤
  483.         Field Length──────────>│  4  │  1  │  3  │
  484.            (bits)              ├─────┴─────┴─────┤
  485.                                │      byte       │
  486.                                └─────────────────┘
  487. T-MODULE Record Format (3 of 38) -- INDEX Fields
  488.                      T-MODULE Record Format -- INDEX Fields
  489.  
  490. There are three special kinds of fields in a T-MODULE record:
  491.  
  492. "INDEX" fields:
  493.                        ┌─────┐
  494.                        │INDEX│
  495.                        ├─────┤
  496.                        │ 1-2 │
  497.                        └─────┘
  498.  
  499. An INDEX field is one or two bytes long.  If the high order bit of the first
  500. byte of the INDEX is 0, then the INDEX is one byte long and the value is the
  501. remaining 7 bits (0 - 127).  Otherwise, the INDEX is two bytes long and the
  502. value of the INDEX is the low order 7 bits of the first byte * 256 plus
  503. the second byte.
  504. T-MODULE Record Format (4 of 38) -- NAME Fields
  505.                       T-MODULE Record Format -- NAME Fields
  506.  
  507.  
  508. The format of a "NAME" field is:
  509.  
  510.                               ┌──────┬───────────┐
  511.                               │ NAME │   NAME    │
  512.                               │Length│           │
  513.                               ├──────┼───────────┤
  514.                               │  1   │NAME Length│
  515.                               └──────┴───────────┘
  516.  
  517. Note:  NAMEs of 0 bytes are permitted.  The NAME is not NULL terminated.
  518. T-MODULE Record Format (5 of 38) -- VALUE Fields
  519.                      T-MODULE Record Format -- VALUE Fields
  520.  
  521. The format of "VALUE" fields is:
  522.  
  523.                                ┌────┬──────┐
  524.                                │Code│Number│
  525.                                ├────┼──────┤
  526.                                │ 1  │ 0-4  │
  527.                                └────┴──────┘
  528.  
  529. When 0 ≤ Code ≤ 128, the Number field is omitted and the VALUE is Code.
  530.  
  531. When Code = 129, the Number field is 2 bytes long, and the VALUE is Number.
  532.  
  533. When Code = 132, the Number field is 3 bytes long, and the VALUE is Number.
  534.  
  535. When Code = 136, the Number field is 4 bytes long, and the VALUE is Number.
  536. T-MODULE Record Format (6 of 38) -- T-MODULE Header
  537.                     T-MODULE Record Format -- T-MODULE Header
  538.  
  539.                         ┌───┬──────┬─────────────┬─────┐
  540.                         │   │Record│T-MODULE NAME│Check│
  541.                         │80H│Length│             │ Sum │
  542.                         ├───┼──────┼─────────────┼─────┤
  543.                         │ 1 │  2   │    NAME     │  1  │
  544.                         └───┴──────┴─────────────┴─────┘
  545.  
  546. This record type must be the first record in the T-MODULE, and it names the
  547. T-MODULE.  Frequently, the T-MODULE NAME is the name of the source file to
  548. the language translator.
  549. T-MODULE Record Format (7 of 38) -- List of NAMEs (LNAMEs)
  550.                 T-MODULE Record Format -- List of NAMEs (LNAMEs)
  551.                   
  552.                         ┌───┬──────┬────────────┬─────┐
  553.                         │   │Record│            │Check│
  554.                         │96H│Length│Logical NAME│ Sum │
  555.                         ├───┼──────┼────────────┼─────┤
  556.                         │ 1 │  2   │    NAME    │  1  │
  557.                         └───┴──────┼────────────┼─────┘
  558.                                    └──repeated──┘
  559.  
  560. Each Logical NAME is entered into a "List of NAMES" (LNAME) in the order they
  561. are encountered in type 96H records.  The list index starts at 1 (0 means not
  562. specified).  There may be more than one type 96H record in a T-MODULE.  When
  563. this occurs, append the Logical NAMEs to the list.  The Logical NAME field
  564. is repeated.  The number of repetitions is determined by the Record Length.
  565. T-MODULE Record Format (8 of 38) -- LSEG Definition (SEGDEF)
  566.                T-MODULE Record Format -- LSEG Definition (SEGDEF)
  567.  
  568.            ┌───┬──────┬─────────┬───────┬───────┬─────┬───────┬─────┐
  569.            │   │Record│ Segment │Segment│Segment│Class│Overlay│Check│
  570.            │90H│Length│Attribute│Length │ INDEX │INDEX│ INDEX │ Sum │
  571.            ├───┼──────┼─────────┼───────┼───────┼─────┼───────┼─────┤
  572.            │ 1 │  2   │  1-4    │  2    │ INDEX │INDEX│ INDEX │  1  │
  573.            └───┴──────┴─────────┴───────┴───────┴─────┴───────┴─────┘
  574.  
  575. Segment Attribute:  ┌────┬────────────┬──────┐  ACBP:  ┌─┬─┬─┬─┐
  576.                     │ACBP│FRAME NUMBER│Offset│         │A│C│B│P│
  577.                     ├────┼────────────┼──────┤         ├─┼─┼─┼─┤
  578.                     │ 1  │     2      │  1   │         │3│3│1│1│
  579.                     └────┼────────────┴──────┤         ├─┴─┴─┴─┤
  580.                          └────conditional────┘         │  Byte │
  581.                                                        └───────┘
  582.                                                  Note:  ACBP.P must be 0.
  583.  
  584. There is one SEGDEF record for each LSEG in a T-MODULE.  Like the LNAME list,
  585. this forms a list of LSEGs (indexed from 1).
  586. T-MODULE Record Format (9 of 38) -- SEGDEF.ACBP.A
  587.                      T-MODULE Record Format -- SEGDEF.ACBP.A
  588.  
  589. The following table gives the meaning of the A field of the ACBP field:
  590.  
  591. ┌─┬───────────────────────────────────────────────────────────────────────┐
  592. │A│                             Description                               │
  593. ├─┼───────────────────────────────────────────────────────────────────────┤
  594. │0│This is an absolute segment.  The FRAME NUMBER and Offset fields of the│
  595. │ │Segment Attribute field will be present.                               │
  596. ├─┼───────────────────────────────────────────────────────────────────────┤
  597. │1│This is a relocatable, byte-aligned LSEG.                              │
  598. ├─┼───────────────────────────────────────────────────────────────────────┤
  599. │2│This is a relocatable, word-aligned LSEG.                              │
  600. ├─┼───────────────────────────────────────────────────────────────────────┤
  601. │2│This is a relocatable, paragraph-aligned LSEG.                         │
  602. ├─┼───────────────────────────────────────────────────────────────────────┤
  603. │4│This is a relocatable, page-aligned LSEG.                              │
  604. ├─┼───────────────────────────────────────────────────────────────────────┤
  605. │5│This is a relocatable, DWORD-aligned LSEG.                             │
  606. └─┴───────────────────────────────────────────────────────────────────────┘
  607. T-MODULE Record Format (10 of 38) -- SEGDEF.ACBP.C
  608.                      T-MODULE Record Format -- SEGDEF.ACBP.C
  609.  
  610. The following table gives the meaning of the C field of the ACBP field:
  611. ┌─┬─────────────────────────────────────────────────────────────────────────┐
  612. │C│                               Description                               │
  613. ├─┼─────────────────────────────────────────────────────────────────────────┤
  614. │0│The LSEG is private and may not be combined.                             │
  615. ├─┼─────────────────────────────────────────────────────────────────────────┤
  616. │1│Undefined.                                                               │
  617. ├─┼─────────────────────────────────────────────────────────────────────────┤
  618. │2│The LSEG is public and may be combined with other LSEGs of the same name.│
  619. ├─┼─────────────────────────────────────────────────────────────────────────┤
  620. │3│Undefined.                                                               │
  621. ├─┼─────────────────────────────────────────────────────────────────────────┤
  622. │4│The LSEG is public and may be combined with other LSEGs of the same name.│
  623. ├─┼─────────────────────────────────────────────────────────────────────────┤
  624. │5│The LSEG is a stack segment and may be combined with other LSEGs of the  │
  625. │ │same name.                                                               │
  626. ├─┼─────────────────────────────────────────────────────────────────────────┤
  627. │6│The LSEG is a common segment and must be combined with other LSEGs of the│
  628. │ │same name.                                                               │
  629. ├─┼─────────────────────────────────────────────────────────────────────────┤
  630. │7│The LSEG is public and may be combined with other LSEGs of the same name.│
  631. └─┴─────────────────────────────────────────────────────────────────────────┘
  632. T-MODULE Record Format (11 of 38) -- Notes on Combining
  633.                   T-MODULE Record Format -- Notes on Combining
  634.  
  635. LSEGs which can be combined and are not common are combined as follows:
  636.  
  637.                       ┌─────────────────────────────────┐
  638.                       │LSEG data for first T-MODULE     │
  639.                       ├─────────────────────────────────┤
  640.                       │Alignment Gap for second T-MODULE│
  641.                       ├─────────────────────────────────┤
  642.                       │LSEG data for second T-MODULE    │
  643.                       ├─────────────────────────────────┤
  644.                       │            ///                  │
  645.                       ├─────────────────────────────────┤
  646.                       │Alignment Gap for last T-MODULE  │
  647.                       ├─────────────────────────────────┤
  648.                       │LSEG data for last T-MODULE      │
  649.                       └─────────────────────────────────┘
  650.  
  651. The resultant PSEG is the combined length of the above.
  652.  
  653. For common LSEGs, the length of the PSEG is the length of the largest LSEG.
  654. Therefore, the length of the PSEG cannot be determined until all the T-MODULEs
  655. are processed.  For this reason, data cannot be loaded into common segments
  656. until fixup time.
  657. T-MODULE Record Format (12 of 38) -- LSEG Definition (SEGDEF)
  658.                T-MODULE Record Format -- LSEG Definition (SEGDEF)
  659.  
  660.            ┌───┬──────┬─────────┬───────┬───────┬─────┬───────┬─────┐
  661.            │   │Record│ Segment │Segment│Segment│Class│Overlay│Check│
  662.            │90H│Length│Attribute│Length │ INDEX │INDEX│ INDEX │ Sum │
  663.            ├───┼──────┼─────────┼───────┼───────┼─────┼───────┼─────┤
  664.            │ 1 │  2   │  1-4    │  2    │ INDEX │INDEX│ INDEX │  1  │
  665.            └───┴──────┴─────────┴───────┴───────┴─────┴───────┴─────┘
  666.  
  667. Segment Length --
  668.   If ACBP.B is 0, then this is the length of the LSEG.  If ACBP.B is 1, then the
  669.   Segment Length must be 0 and the length of the LSEG is 65536 bytes.
  670.  
  671. Segment INDEX --
  672.   This is an INDEX into the LNAME list.  LNAME[Segment INDEX] is the name of the
  673.   LSEG.
  674.  
  675. Class INDEX --
  676.   This is an INDEX into the LNAME list.  LNAME[Class INDEX] is the name of the
  677.   LSEG.
  678.  
  679. Overlay INDEX --
  680.   This is an INDEX into the LNAME list.  LNAME[Class INDEX] is the name of the
  681.   LSEG.
  682. T-MODULE Record Format (13 of 38) -- Group Definition (GRPDEF)
  683.                T-MODULE Record Format -- Group Definition (GRPDEF)
  684.  
  685.                     ┌───┬──────┬───────────┬───┬─────┬─────┐
  686.                     │   │Record│Group NAME │   │LSEG │Check│
  687.                     │9AH│Length│  INDEX    │FFH│INDEX│ Sum │
  688.                     ├───┼──────┼───────────┼───┼─────┼─────┤
  689.                     │ 1 │  2   │  INDEX    │ 1 │INDEX│  1  │
  690.                     └───┴──────┴───────────┼───┴─────┼─────┘
  691.                                            └─repeated┘
  692.  
  693. Like the LNAME list and SEGDEF list, the GRPDEFs form a list (indexed relative
  694. to 1) of groups.  The is one GRPDEF record for each group in the T-MODULE.
  695.  
  696. Group NAME INDEX --
  697.   LNAME[Group NAME INDEX] is the name of the group.
  698.  
  699. LSEG INDEX --
  700.   This field is repeated once for each LSEG in the group.  The LSEG INDEX is
  701.   the INDEX into the LSEG list which corresponds to the LSEG in the group.
  702. T-MODULE Record Format (14 of 38) -- Public Definition (PUBDEF)
  703.               T-MODULE Record Format -- Public Definition (PUBDEF)
  704.  
  705.            ┌───┬──────┬─────┬───────┬──────┬──────┬──────┬─────┬─────┐
  706.            │   │Record│Group│Segment│FRAME │Public│Public│Type │Check│
  707.            │90H│Length│INDEX│ INDEX │NUMBER│ NAME │Offset│INDEX│ Sum │
  708.            ├───┼──────┼─────┼───────┼──────┼──────┼──────┼─────┼─────┤
  709.            │ 1 │  2   │INDEX│ INDEX │ 0-2  │ NAME │  2   │INDEX│  1  │
  710.            └───┴──────┴─────┴───────┴──────┼──────┴──────┴─────┼─────┘
  711.                                            └─────repeated──────┘
  712.  
  713. Group INDEX --
  714.   If the public(s) are defined is an LSEG which is part of a group, then this is
  715.   the index into the group list.
  716.  
  717. Segment INDEX --
  718.   If the public(s) are defined in an LSEG, this is the index into the LSEG list.
  719.  
  720. FRAME NUMBER --
  721.   This field is only present if the public(s) are absolute (indicated by both
  722.   Group INDEX and Segment INDEX being zero).  When present, this is the FRAME
  723.   NUMBER used to reference the public(s).
  724. T-MODULE Record Format (15 of 38) -- Public Definition (PUBDEF)
  725.               T-MODULE Record Format -- Public Definition (PUBDEF)
  726.  
  727.            ┌───┬──────┬─────┬───────┬──────┬──────┬──────┬─────┬─────┐
  728.            │   │Record│Group│Segment│FRAME │Public│Public│Type │Check│
  729.            │90H│Length│INDEX│ INDEX │NUMBER│ NAME │Offset│INDEX│ Sum │
  730.            ├───┼──────┼─────┼───────┼──────┼──────┼──────┼─────┼─────┤
  731.            │ 1 │  2   │INDEX│ INDEX │ 0-2  │ NAME │  2   │INDEX│  1  │
  732.            └───┴──────┴─────┴───────┴──────┼──────┴──────┴─────┼─────┘
  733.                                            └─────repeated──────┘
  734.  
  735. Public NAME --
  736.   This is the name of the public.
  737.  
  738. Public Offset --
  739.   This is the distance of the start of the public from the group, LSEG or FRAME.
  740.  
  741. Type INDEX --
  742.   This is ignored.
  743. T-MODULE Record Format (16 of 38) -- External Definition (EXTDEF)
  744.               T-MODULE Record Format -- Public Definition (EXTDEF)
  745.  
  746.                         ┌───┬──────┬────────┬─────┬─────┐
  747.                         │   │Record│External│Type │Check│
  748.                         │BCH│Length│  NAME  │INDEX│ Sum │
  749.                         ├───┼──────┼────────┼─────┼─────┤
  750.                         │ 1 │  2   │  NAME  │INDEX│  1  │
  751.                         └───┴──────┼────────┴─────┼─────┘
  752.                                    └───repeated───┘
  753.  
  754. Like the LNAMEs, SEGDEFs, and GRPDEFs, the EXTDEFs form a list (indexed relative
  755. to 1) of the external names used in this T-MODULE.
  756.  
  757. External NAME --
  758.   This is the name of the external public symbol.
  759.  
  760. Type INDEX --
  761.   This is ignored.
  762. T-MODULE Record Format (17 of 38) -- Logical Enumerated Data
  763.            T-MODULE Record Format -- Logical Enumerated Data (LEDATA)
  764.  
  765.                    ┌───┬──────┬───────┬──────┬────────┬─────┐
  766.                    │   │Record│Segment│      │        │Check│
  767.                    │A0H│Length│ INDEX │Offset│  Data  │ Sum │
  768.                    ├───┼──────┼───────┼──────┼────────┼─────┤
  769.                    │ 1 │  2   │ INDEX │  2   │   1    │  1  │
  770.                    └───┴──────┴───────┴──────┼────────┼─────┘
  771.                                              └repeated┘
  772.  
  773. Segment INDEX --
  774.   This data is to be loaded into the LSEG corresponding to SEGDEF list entry
  775.   SEGDEF[Segment INDEX].
  776.  
  777. Offset --
  778.   This data is to be loaded starting at this offset in the LSEG.
  779.  
  780. Data --
  781.   The byte(s) to be loaded.  No more than 1024 can be loaded by an LEDATA
  782.   record.
  783. T-MODULE Record Format (18 of 38) -- Logical Iterated Data
  784.             T-MODULE Record Format -- Logical Iterated Data (LIDATA)
  785.  
  786.                   ┌───┬──────┬───────┬──────┬──────────┬─────┐
  787.                   │   │Record│Segment│      │ Iterated │Check│
  788.                   │A2H│Length│ INDEX │Offset│Data Block│ Sum │
  789.                   ├───┼──────┼───────┼──────┼──────────┼─────┤
  790.                   │ 1 │  2   │ INDEX │  2   │ variable │  1  │
  791.                   └───┴──────┴───────┴──────┼──────────┼─────┘
  792.                                             └─repeated─┘
  793.  
  794. Segment INDEX --
  795.   This data is to be loaded into the LSEG corresponding to SEGDEF list entry
  796.   SEGDEF[Segment INDEX].
  797.  
  798. Offset --
  799.   This data is to be loaded starting at this offset in the LSEG.
  800.  
  801. Iterated Data Block --
  802.   This is (recursively) defined later, but the total size cannot exceed
  803.   1024 bytes.
  804. T-MODULE Record Format (19 of 38) -- Logical Iterated Data
  805.             T-MODULE Record Format -- Logical Iterated Data (LIDATA)
  806.  
  807.  
  808. Iterated Data Block:  ┌──────┬─────┬────────┐
  809.                       │Repeat│Block│        │
  810.                       │Count │Count│ Content│
  811.                       ├──────┼─────┼────────┤
  812.                       │  2   │  2  │variable│
  813.                       └──────┴─────┴────────┘
  814.  
  815. Repeat Count --
  816.   If Block Count is zero then Content is interpreted as a string of bytes of
  817.   length Repeat Count.  If Block Count is zero, then this is the number of times
  818.   the Content field is repeated.
  819.  
  820. Block Count --
  821.   If this is zero, then the Content field is interpreted as a string of bytes
  822.   of length Repeat Count.  If this is non-zero, then the Content field contains
  823.   a string of Block Count Iterated Data Blocks.
  824.  
  825. Content --
  826.   This is either a string of bytes as described above or it is a string of
  827.   Iterated Data Blocks.
  828. T-MODULE Record Format (20 of 38) -- Fixup Record (FIXUPP)
  829.                  T-MODULE Record Format -- Fixup Record (FIXUPP)
  830.  
  831.                            ┌───┬──────┬────────┬─────┐
  832.                            │   │Record│ Thread │Check│
  833.                            │9CH│Length│or Fixup│ Sum │
  834.                            ├───┼──────┼────────┼─────┤
  835.                            │ 1 │  2   │variable│  1  │
  836.                            └───┴──────┼────────┼─────┘
  837.                                       └repeated┘
  838.  
  839. Thread or Fixup --
  840.   This field can be either a Thread (high order bit is 0) or Fixup (high order
  841.   bit is 1).  A Thread is a default TARGET or FRAME method.  There are four
  842.   TARGET threads and four FRAME threads.  Thread fields are used to store the
  843.   default TARGET or FRAME method.  A Fixup type field specifies the five
  844.   pieces of information (discussed earlier) necessary to perform a fixup.
  845. T-MODULE Record Format (21 of 38) -- Thread
  846.                         T-MODULE Record Format -- Thread
  847.  
  848. Thread:  ┌──────┬───────┐  Thread Data:  ┌─┬─┬─┬──────┬─────┐
  849.          │Thread│Thread │                │0│D│0│Method│Thred│
  850.          │ Data │ INDEX │                ├─┼─┼─┼──────┼─────┤
  851.          ├──────┼───────┤                │1│1│1│  3   │  2  │
  852.          │  1   │0-INDEX│                ├─┴─┴─┴──────┴─────┤
  853.          └──────┴───────┘                │       byte       │
  854.                                          └──────────────────┘
  855.  
  856. D --
  857.   If D is zero then a TARGET thread is being specified, otherwise a FRAME thread
  858.   is being specified.
  859.  
  860. Method --
  861.   This is the TARGET or FRAME method.  For TARGET threads, only the four primary
  862.   methods are specified.  All seven FRAME methods can be specified.
  863.  
  864. Thred --
  865.   This is the TARGET or FRAME thread number being specified.
  866.  
  867. Thread INDEX --
  868.   This is not present when F4, F5 or F6 is being specified.  In all other cases,
  869.   this is either a Segment, Group or External index depending on the Method.
  870. T-MODULE Record Format (22 of 38) -- Fixup
  871.                          T-MODULE Record Format -- Fixup
  872.  
  873.                     ┌─────┬───────┬───────┬───────┬──────┐
  874.                     │LOCAT│ Fixup │ FRAME │TARGET │TARGET│
  875.                     │     │Methods│ INDEX │INDEX  │Offset│
  876.                     ├─────┼───────┼───────┼───────┼──────┤
  877.                     │  2  │  1    │0-INDEX│0-INDEX│ 0-2  │
  878.                     └─────┴───────┴───────┴───────┴──────┘
  879.  
  880. LOCAT:  ┌─┬────┬─┬────────┬─────────┐
  881.         │ │    │ │LOCATION│LE/LIDATA│
  882.         │1│Mode│0│  Type  │  Offset │
  883.         ├─┼────┼─┼────────┼─────────┤
  884.         │1│ 1  │1│   3    │    10   │
  885.         ├─┴────┴─┴────────┴─────────┤
  886.         │low byte          high byte│ Note:  Low and high bytes are swapped.
  887.         └───────────────────────────┘
  888.          
  889. Mode --
  890.   If Mode is 0 then this is a self-relative fixup, otherwise it is a segment-
  891.   relative fixup.  Self-relative fixups on LIDATA are not permitted.
  892. T-MODULE Record Format (23 of 38) -- Fixup
  893.                          T-MODULE Record Format -- Fixup
  894.  
  895. LOCAT:  ┌─┬────┬─┬────────┬─────────┐
  896.         │ │    │ │LOCATION│LE/LIDATA│
  897.         │1│Mode│0│  Type  │  Offset │
  898.         ├─┼────┼─┼────────┼─────────┤
  899.         │1│ 1  │1│   3    │    10   │
  900.         ├─┴────┴─┴────────┴─────────┤
  901.         │low byte          high byte│
  902.         └───────────────────────────┘
  903.  
  904. LOCATION Type:  ┌────────┬────────────────┐
  905.                 │LOCATION│Type Description│
  906.                 ├────────┼────────────────┤
  907.                 │      0 │     LOBYTE     │
  908.                 ├────────┼────────────────┤
  909.                 │      1 │     OFFSET     │
  910.                 ├────────┼────────────────┤
  911.                 │      2 │     BASE       │
  912.                 ├────────┼────────────────┤
  913.                 │      3 │     POINTER    │
  914.                 ├────────┼────────────────┤
  915.                 │      4 │     HIBYTE     │
  916.                 └────────┴────────────────┘
  917. T-MODULE Record Format (24 of 38) -- Fixup
  918.                          T-MODULE Record Format -- Fixup
  919.  
  920. LOCAT:  ┌─┬────┬─┬────────┬─────────┐
  921.         │ │    │ │LOCATION│LE/LIDATA│
  922.         │1│Mode│0│  Type  │  Offset │
  923.         ├─┼────┼─┼────────┼─────────┤
  924.         │1│ 1  │1│   3    │    10   │
  925.         ├─┴────┴─┴────────┴─────────┤
  926.         │low byte          high byte│
  927.         └───────────────────────────┘
  928.  
  929. LE/LIDATA Offset --
  930.   This field is used to determine the LOCATION information for the fixup.  This
  931.   offset is actually an offset into the last LEDATA or LIDATA record.  The
  932.   LEDATA or LIDATA contains the base LSEG and offset information.  Note that
  933.   for LIDATA records, each time the data at LE/LIDATA Offset is repeated, the
  934.   fixup must occur.
  935. T-MODULE Record Format (25 of 38) -- Fixup
  936.                          T-MODULE Record Format -- Fixup
  937.  
  938.                     ┌─────┬───────┬───────┬───────┬──────┐
  939.                     │LOCAT│ Fixup │ FRAME │TARGET │TARGET│
  940.                     │     │Methods│ INDEX │INDEX  │Offset│
  941.                     ├─────┼───────┼───────┼───────┼──────┤
  942.                     │  2  │  1    │0-INDEX│0-INDEX│ 0-2  │
  943.                     └─────┴───────┴───────┴───────┴──────┘
  944.  
  945. Fixup Methods:  ┌─┬─────┬─┬─┬──────┐
  946.                 │F│FRAME│T│P│TARGET│  F --
  947.                 ├─┼─────┼─┼─┼──────┤    If F is 1 then FRAME is a thread, else
  948.                 │1│  3  │1│1│  2   │    FRAME is the FRAME method.
  949.                 ├─┴─────┴─┴─┴──────┤
  950.                 │      byte        │  T --
  951.                 └──────────────────┘    If T is 1 then TARGET is a thread, else
  952.                                         TARGET is the TARGET method.
  953. FRAME --
  954.   This is either the FRAME method (F=0) or a FRAME thread (F=1).
  955. TARGET --
  956.   This is either the TARGET method (T=0) or a TARGET thread (T=1).
  957. P --
  958.   If P=0 then the primary TARGET methods are used and the TARGET Offset field
  959.   will be present.
  960. T-MODULE Record Format (26 of 38) -- Fixup
  961.                          T-MODULE Record Format -- Fixup
  962.  
  963.                     ┌─────┬───────┬───────┬───────┬──────┐
  964.                     │LOCAT│ Fixup │ FRAME │TARGET │TARGET│
  965.                     │     │Methods│ INDEX │INDEX  │Offset│
  966.                     ├─────┼───────┼───────┼───────┼──────┤
  967.                     │  2  │  1    │0-INDEX│0-INDEX│ 0-2  │
  968.                     └─────┴───────┴───────┴───────┴──────┘
  969.  
  970. FRAME INDEX --
  971.   Depending on the FRAME method, this is either a Segment, Group, or External
  972.   INDEX.  This will be present only when a FRAME thread is not used (F=0).
  973.  
  974. TARGET INDEX --
  975.   Depending on the TARGET method, this is either a Segment, Group, or External
  976.   INDEX.  This will be present only when a TARGET thread is not used (T=0).
  977.  
  978. TARGET Offset --
  979.   The TARGET is TARGET Offset bytes from the Segment, Group, or External given
  980.   by TARGET INDEX.
  981. T-MODULE Record Format (27 of 38) -- T-MODULE End (MODEND)
  982.                  T-MODULE Record Format -- T-MODULE End (MODEND)
  983.  
  984.                         ┌───┬──────┬────┬────────┬─────┐
  985.                         │   │Record│End │ Start  │Check│
  986.                         │8AH│Length│Type│Address │ Sum │
  987.                         ├───┼──────┼────┼────────┼─────┤
  988.                         │ 1 │  2   │ 1  │variable│  1  │
  989.                         └───┴──────┴────┴────────┴─────┘
  990.  
  991. End Type:  ┌─────────┬─┬─┐  Attribute:  ┌─────────┬──────────────────────────┐
  992.            │Attribute│0│1│              │Attribute│Description               │
  993.            ├─────────┼─┼─┤              ├─────────┼──────────────────────────┤
  994.            │    2    │5│1│              │    0    │Non-main, no Start Address│
  995.            ├─────────┴─┴─┤              ├─────────┼──────────────────────────┤
  996.            │    byte     │              │    1    │Non-main, Start Address   │
  997.            └─────────────┘              ├─────────┼──────────────────────────┤
  998.                                         │    2    │Main, no Start Address    │
  999.                                         ├─────────┼──────────────────────────┤
  1000.                                         │    3    │Main, Start Address       │
  1001.                                         └─────────┴──────────────────────────┘
  1002. T-MODULE Record Format (28 of 38) -- T-MODULE End (MODEND)
  1003.                  T-MODULE Record Format -- T-MODULE End (MODEND)
  1004.  
  1005.  
  1006.     Start Address:  ┌───────┬───────┬───────┬──────┐
  1007.                     │ Fixup │ FRAME │TARGET │TARGET│
  1008.                     │Methods│ INDEX │INDEX  │Offset│
  1009.                     ├───────┼───────┼───────┼──────┤
  1010.                     │  1    │0-INDEX│0-INDEX│ 0-2  │
  1011.                     └───────┴───────┴───────┴──────┘
  1012.  
  1013. The above fields work exactly the same as they do in a FIXUPP record.  The
  1014. start address is computed from the FRAME and TARGET specified above.  The
  1015. initial CS is the FRAME NUMBER of the FRAME, and the initial IP is
  1016. TARGET - FRAME.
  1017. T-MODULE Record Format (29 of 38) -- Comment Record (COMENT)
  1018.                 T-MODULE Record Format -- Comment Record (COMENT)
  1019.  
  1020.                       ┌───┬──────┬───────┬────────┬─────┐
  1021.                       │   │Record│Comment│        │Check│
  1022.                       │88H│Length│ Type  │Comment │ Sum │
  1023.                       ├───┼──────┼───────┼────────┼─────┤
  1024.                       │ 1 │  2   │  2    │variable│  1  │
  1025.                       └───┴──────┴───────┴────────┴─────┘
  1026.  
  1027. Comment Type:  ┌─────┬────┬─┬─────┐
  1028.                │Purge│List│0│Class│
  1029.                ├─────┼────┼─┼─────┤
  1030.                │  1  │ 1  │6│  8  │
  1031.                ├─────┴────┴─┴─────┤
  1032.                │       word       │
  1033.                └──────────────────┘
  1034.  
  1035. Purge --
  1036.   COMENT record should not be deleted by utilities which can delete comments
  1037.   (Purge=1).
  1038.  
  1039. List --
  1040.   COMENT record should not be listed by utilities which can list comments
  1041.   (LIST=1).
  1042. T-MODULE Record Format (30 of 38) -- Comment Record (COMENT)
  1043.                 T-MODULE Record Format -- Comment Record (COMENT)
  1044.  
  1045. ┌─────┬────────────────────────────────────────────────────────────────────┐
  1046. │Class│                            Description                             │
  1047. ├─────┼────────────────────────────────────────────────────────────────────┤
  1048. │ 129 │Do not do a default library search.                                 │
  1049. ├─────┼────────────────────────────────────────────────────────────────────┤
  1050. │ 157 │Memory model information is in the Comment field.                   │
  1051. ├─────┼────────────────────────────────────────────────────────────────────┤
  1052. │ 158 │Use the "DOSSEG" ordering.                                          │
  1053. ├─────┼────────────────────────────────────────────────────────────────────┤
  1054. │ 159 │Library name is in the Comment field.                               │
  1055. ├─────┼────────────────────────────────────────────────────────────────────┤
  1056. │ 161 │Codeview (registered trademark of Microsoft) information is present.│
  1057. ├─────┼────────────────────────────────────────────────────────────────────┤
  1058. │ 162 │Pass 1 of linker can stop processing T-MODULE here.                 │
  1059. └─────┴────────────────────────────────────────────────────────────────────┘
  1060. T-MODULE Record Format (31 of 38) -- Communal Definition
  1061.              T-MODULE Record Format -- Communal Definition (COMDEF)
  1062.  
  1063.             ┌───┬──────┬──────┬─────┬───────────┬──────────┬─────┐
  1064.             │   │      │Symbol│Type │Far or Near│ Communal │Check│
  1065.             │B0H│Length│ NAME │INDEX│ Communal  │   Size   │ Sum │
  1066.             ├───┼──────┼──────┼─────┼───────────┼──────────┼─────┤
  1067.             │ 1 │  2   │ NAME │INDEX│     1     │ variable │  1  │
  1068.             └───┴──────┴──────┴─────┴───────────┴──────────┴─────┘
  1069.  
  1070. Symbol NAME --
  1071.   This is the name of the communal symbol.  It is placed in the list of
  1072.   external symbols just as if it were an EXTDEF record.  If a PUBDEF record
  1073.   with the same Symbol NAME is encountered, it overrides the COMDEF.
  1074.  
  1075. Type INDEX --
  1076.   This is ignored.
  1077.  
  1078. Far or Near Communal --
  1079.   Far communals have a 61H coded here.  Near communals have a 62H coded here.
  1080.  
  1081. The ultimate size of the communal is the largest communal.
  1082. T-MODULE Record Format (32 of 38) -- Communal Definition
  1083.              T-MODULE Record Format -- Communal Definition (COMDEF)
  1084.  
  1085. For near communals, Communal Size is:  ┌─────┐
  1086.                                        │SIZE │
  1087.                                        │VALUE│
  1088.                                        ├─────┤
  1089.                                        │VALUE│
  1090.                                        └─────┘
  1091.  
  1092. For far communals, Communal Size is:   ┌─────┬─────┐
  1093.                                        │COUNT│SIZE │
  1094.     The size of the communal is:       │VALUE│VALUE│
  1095.                                        ├─────┼─────┤
  1096.       COUNT VALUE * SIZE VALUE         │VALUE│VALUE│
  1097.                                        └─────┴─────┘
  1098.  
  1099. Near communals go in DGROUP.  Far communals go in HUGE_BSS and are packed as
  1100. compactly as possible into PSEGs of no more than 64K.
  1101. T-MODULE Record Format (33 of 38) -- Forward Reference Fixups
  1102.            T-MODULE Record Format -- Forward Reference Fixups (FORREF)
  1103.  
  1104.                  ┌───┬──────┬───────┬────┬──────┬────────┬─────┐
  1105.                  │   │      │Segment│    │      │ Fixup  │Check│
  1106.                  │B2H│Length│ INDEX │Size│Offset│ Data   │ Sum │
  1107.                  ├───┼──────┼───────┼────┼──────┼────────┼─────┤
  1108.                  │ 1 │  2   │ INDEX │ 1  │  2   │variable│  1  │
  1109.                  └───┴──────┴───────┴────┼──────┴────────┼─────┘
  1110.                                          └───repeated────┘
  1111.  
  1112. Segment INDEX --
  1113.   The Forward Reference Fixup is to be applied to the LSEG element whose index
  1114.   into the SEGDEF list is Segment INDEX.
  1115. Size --
  1116.   This specifies the size of the Fixup Data fields.  The Fixup Data fields
  1117.   are a byte when Size = 0, a word when Size = 1, or a DWORD when Size = 2.
  1118. Offset --
  1119.   This is the Offset into the LSEG specified by Segment Index where the fixup is
  1120.   applied.
  1121. Fixup Data --
  1122.   This value is added at the specified Offset.
  1123.  
  1124. Note:  The FORREF record may occur before the LE/LIDATA records which load data
  1125.        into the LSEG.  Therefore, FORREFs must be applied at fixup time.
  1126. T-MODULE Record Format (34 of 38) -- Local External Definition
  1127.           T-MODULE Record Format -- Local External Definition (MODEXT)
  1128.  
  1129.                         ┌───┬──────┬────────┬─────┬─────┐
  1130.                         │   │Record│External│Type │Check│
  1131.                         │B4H│Length│  NAME  │INDEX│ Sum │
  1132.                         ├───┼──────┼────────┼─────┼─────┤
  1133.                         │ 1 │  2   │  NAME  │INDEX│  1  │
  1134.                         └───┴──────┼────────┴─────┼─────┘
  1135.                                    └───repeated───┘
  1136.  
  1137.  
  1138. The fields of the MODEXT record function just like the EXTDEF record except that
  1139. the external is local to this T-MODULE only.  The External NAME is included in
  1140. the list of externals.
  1141. T-MODULE Record Format (35 of 38) -- Local Public Definition
  1142.            T-MODULE Record Format -- Local Public Definition (MODPUB)
  1143.  
  1144.            ┌───┬──────┬─────┬───────┬──────┬──────┬──────┬─────┬─────┐
  1145.            │   │Record│Group│Segment│FRAME │Public│Public│Type │Check│
  1146.            │B6H│Length│INDEX│ INDEX │NUMBER│ NAME │Offset│INDEX│ Sum │
  1147.            ├───┼──────┼─────┼───────┼──────┼──────┼──────┼─────┼─────┤
  1148.            │ 1 │  2   │INDEX│ INDEX │ 0-2  │ NAME │  2   │INDEX│  1  │
  1149.            └───┴──────┴─────┴───────┴──────┼──────┴──────┴─────┼─────┘
  1150.                                            └─────repeated──────┘
  1151.  
  1152. The fields of the MODPUB record function just like the PUBDEF record except that
  1153. the public symbol is local to this T-MODULE only.
  1154. T-MODULE Record Format (36 of 38) -- Line Number (LINNUM)
  1155.                  T-MODULE Record Format -- Line Number (LINNUM)
  1156.  
  1157.                         ┌───┬──────┬──────────┬─────┐
  1158.                         │   │Record│          │Check│
  1159.                         │94H│Length│   Data   │ Sum │
  1160.                         ├───┼──────┼──────────┼─────┤
  1161.                         │ 1 │  2   │    1     │  1  │
  1162.                         └───┴──────┼──────────┼─────┘
  1163.                                    └─repeated─┘
  1164.  
  1165. The LINNUM record is ignored by the linker.
  1166. T-MODULE Record Format (37 of 38) -- Type Definition (TYPDEF)
  1167.                T-MODULE Record Format -- Type Definition (TYPDEF)
  1168.  
  1169.                         ┌───┬──────┬──────────┬─────┐
  1170.                         │   │Record│          │Check│
  1171.                         │8EH│Length│   Data   │ Sum │
  1172.                         ├───┼──────┼──────────┼─────┤
  1173.                         │ 1 │  2   │    1     │  1  │
  1174.                         └───┴──────┼──────────┼─────┘
  1175.                                    └─repeated─┘
  1176.  
  1177. The TYPDEF record is ignored by the linker.
  1178. T-MODULE Record Format (38 of 38) -- Record Order
  1179.                      T-MODULE Record Format -- Record Order
  1180.  
  1181. Object modules are parsed via recursive descent as defined below:
  1182.  
  1183.      t_module::      THEADR seg_grp {component} modtail
  1184.  
  1185.      seg_grp::       {LNAMES | SEGDEF | EXTDEF} {TYPDEF | EXTDEF | GRPDEF}
  1186.  
  1187.      component::     data | debug_record
  1188.  
  1189.      data::          content_def | thread_def | COMDEF | TYPDEF | PUBDEF |
  1190.                      EXTDEF | FORREF | MODPUB | MODEXT
  1191.  
  1192.      debug_record::  LINNUM
  1193.  
  1194.      content_def::   data_record {FIXUPP}
  1195.  
  1196.      thread_def::    FIXUPP  (containing only thread fields)
  1197.  
  1198.      data_record::   LIDATA | LEDATA
  1199.  
  1200.      modtail::       MODEND
  1201. Primary Internal Data Structure
  1202.                          Primary Internal Data Structure
  1203.  
  1204. ┌────────────┐             ┌─────────┐              ┌──────────────────┐
  1205. │ Segment #1 ├────────────>│ LSEG #1 ├─────────────>│ LSEG #1 Contents │
  1206. └─────┬──────┘             └────┬────┘              └──────────────────┘
  1207.       │                         │
  1208.       │                         
  1209.       │                    ┌─────────┐              ┌──────────────────┐
  1210.       │                    │ LSEG #2 ├─────────────>│ LSEG #2 Contents │
  1211.       │                    └────┬────┘              └──────────────────┘
  1212.       │                         
  1213.       │                        ///
  1214.       
  1215. ┌────────────┐             ┌─────────┐              ┌──────────────────┐
  1216. │ Segment #2 ├────────────>│ LSEG #1 ├─────────────>│ LSEG #1 Contents │
  1217. └─────┬──────┘             └────┬────┘              └──────────────────┘
  1218.       │                         │
  1219.       │                         
  1220.       │                    ┌─────────┐              ┌──────────────────┐
  1221.                           │ LSEG #2 ├─────────────>│ LSEG #2 Contents │
  1222.      ///                   └────┬────┘              └──────────────────┘
  1223.                                 
  1224.                                ///
  1225. Temp File
  1226.                                   Temp File
  1227.  
  1228. The linker employs a temp file to save information which can only be processed
  1229. after all the T-MODULEs have been processed.  The information which must be
  1230. saved is:
  1231.  
  1232.                               Fixups
  1233.                               LE/LIDATA for common LSEGS
  1234.                               FORREF records
  1235.  
  1236. The temp file is deleted when processing is complete.
  1237. Library File Format (1 of 4)
  1238.                                Library File Format
  1239.  
  1240.   library_file::    header_page {t_modules} trailer_page {directory_pages}
  1241.  
  1242.   header_page ::    ┌───┬──────┬─────────┬─────────┬──────────┬─┐
  1243.                     │   │Record│Directory│Directory│          │ │
  1244.                     │F0H│Length│ Offset  │ Pages   │   Pad    │0│
  1245.                     ├───┼──────┼─────────┼─────────┼──────────┼─┤
  1246.                     │ 1 │  2   │   4     │   2     │    1     │1│
  1247.                     └───┴──────┴─────────┴─────────┼──────────┼─┘
  1248.                                           (prime)  └─repeated─┘
  1249.  
  1250.   t_modules ::      The t_modules are as described above except a pad is added
  1251.                     after the MODEND record to make the t_module occupy a
  1252.                     full page. The page size is the header_page Record Length
  1253.                     + 3.
  1254.  
  1255.   trailer_page ::   ┌───┬──────┬──────────┬─┐
  1256.                     │   │Record│          │ │
  1257.                     │F1H│Length│   Pad    │0│
  1258.                     ├───┼──────┼──────────┼─┤
  1259.                     │ 1 │  2   │    1     │1│
  1260.                     └───┴──────┼──────────┼─┘
  1261.                                └─repeated─┘
  1262. Library File Format (2 of 4) -- Directory
  1263.                         Library File Format -- Directory
  1264.  
  1265.  
  1266.   directory_pages ::  public_pointer_array {public_entry} pad
  1267.  
  1268. Notes:  A directory page is always 512 bytes.  A directory page can contain
  1269.         up to 37 public entries.
  1270.  
  1271. public_pointer_array --
  1272.   This is a 38 byte array which is used to point into the public_entry field.
  1273.   To determine where public i is located in the directory page, take the ith
  1274.   byte of the public_pointer_array (relative 0) and multiple it by 2.  That
  1275.   byte will be the beginning of the public_entry for ith public in the
  1276.   directory.  The 38th entry is used to point to the beginning of the free
  1277.   space in directory page.
  1278.  
  1279. public_entry ::  ┌───────┬────────┐
  1280.                  │ Public│Starting│
  1281.                  │ NAME  │  Page  │
  1282.                  ├───────┼────────┤
  1283.                  │ NAME  │   2    │
  1284.                  └───────┴────────┘
  1285. Library File Format (3 of 4) -- Finding a Public
  1286.                      Library File Format -- Finding a Public
  1287.  
  1288. The library directory employs a two-tiered hashing scheme to store public
  1289. names in its directory.  A detailed description of the algorithm is given later,
  1290. but for now the following general aspects of the algoritm are useful.  To start
  1291. the search, you need to know which directory page to start searching, and if
  1292. you don't find it in that page, which directory page to search next.  Once in
  1293. a directory page, you have to know which entry to use to begin the search and
  1294. which entry to search next if it was not found.
  1295.  
  1296. We will call the four required values STARTING_PAGE, DELTA_PAGE, STARTING_ENTRY,
  1297. and DELTA_ENTRY.  The detail on how to compute these values is give later.
  1298.  
  1299. Start with directory page STARTING_PAGE.  On that page, examine public_entry
  1300. STARTING_ENTRY.  There are three cases.  This could be the public symbol you
  1301. desire, in which case you are done.  The public_pointer_array for this entry
  1302. could be zero, in which case the symbol is not in the library.  Or, this the
  1303. public symbol at STARTING_ENTRY could be some other public symbol.  In this
  1304. case, add DELTA_ENTRY (modulo 37) to the STARTING_ENTRY and examine that
  1305. public entry.  Since there are at most 37 entries in any directory page,
  1306. examine no more than 37 entries in any given page.  If you have tried all
  1307. entries on a page, proceed to the next page by adding DELTA_PAGE (modulo
  1308. Directory_Pages) to STARTING_PAGE and continue the process.  When you move to
  1309. a new page, continue processing the public entries where you left off.
  1310. Library File Format (4 of 4) -- Finding a Public
  1311.                      Library File Format -- Finding a Public
  1312.  
  1313. To compute the STARTING_PAGE, DELTA_PAGE, STARTING_ENTRY, and DELTA_ENTRY, view
  1314. a NAME field as if it were an array of bytes containing the public name:
  1315.  
  1316.                         ┌──────┬────┬────┬────┬─//─┬──────┐
  1317.             NAME───────>│Length│byte│byte│byte│    │ byte │
  1318.                         ├──────┼────┼────┼────┼─//─┼──────┤
  1319.                         │  1   │ 1  │ 1  │ 1  │    │  1   │
  1320.                         ├──────┼────┼────┼────┼─//─┼──────┤
  1321.             index──────>│  0   │ 1  │ 2  │ 3  │    │Length│
  1322.                         └──────┴────┴────┴────┴─//─┴──────┘
  1323.  
  1324. Then, the following code define the values:
  1325. STARTING_PAGE, DELTA_PAGE, STARTING_ENTRY, DELTA_ENTRY  0;
  1326. for i  0 .. Length-1
  1327.  STARTING_PAGESTARTING_PAGE+(NAME[i] or 20H) xor (<<STARTING_PAGE);
  1328.  DELTA_PAGEDELTA_PAGE+(NAME[Length-i+1] or 20H) xor (<<DELTA_PAGE);
  1329.  STARTING_ENTRYSTARTING_ENTRY+(NAME[Length-i+1] or 20H) xor (>>STARTING_ENTRY);
  1330.  DELTA_ENTRYDELTA_ENTRY+(NAME[i] or 20H) xor (>>DELTA_ENTRY);
  1331. end for;
  1332. if DELTA_ENTRY = 0 then DELTA_ENTRY
  1333. if DELTA_PAGE = 0 then DELTA_PAGE
  1334. Note:  << is circular shift left twice and >> is circular shift right twice.
  1335.