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