
   Miscellaneous OMF notes
   =======================

 This is an attempt to put together some of the more difficult to come by
information concerning the standard (if that is the appropriate word) Object
Module Format, or OMF. It is assumed that the reader is acquainted with the
OMF structure and basic records.

 The best "official" source of information is a file called omf.pdf,
available from several places on the Internet. Its title is:

   Tool Interface Standards (TIS)
  Relocatable Object Module Format
        (OMF) Specification
           Version 1.1

 It contains a lot of detail on the Microsoft-generated OMF files but it
doesn't help a whole lot when dealing with object files generated by
tools by IBM, Borland or even Watcom of that matter.

 Since our tools should work with the widest possible variety of OMF files,
we need to understand some of the vendor specific information, especially as
it pertains to commonly used OMF records.


  LINNUM records (94h or 95h)
  ===========================

 LINNUM/LINNUM386 records are common and our tools try to parse them. Sadly,
their contents is not standardized. In particular, it depends on the COMENT
record 0A1h. The 0A1h COMENT record contains debug info style information,
omf.pdf describes three possibilities:

 - CV - Microsoft CodeView style; somewhat documented in omf.pdf
 - DX - AIX style - no information, very exotic
 - HL - IBM HLL style; generated by IBM's CSet, CSet++ and VisualAge C++
        compilers.

 The last type is important when dealing with IBM's OMF files, rather common
on 32-bit OS/2. It does not seem to be publicly documented anywhere but
it is possible to glean its structure from file dumps coupled with the output
of IBM's LINK386. The IBM HLL style is almost certainly exclusively 32-bit
(because for 16-bit development IBM always used Microsoft's tools).

 IBM uses (at least) two types of LINNUM386 records: one type lists source
files, the other lists actual lines and how they correspond to offsets in the
compiled code.

 The first type lists the source files. The structure is not entirely clear
but at the end it contains strings that hold file names.


 DWORD    - number of bytes that follow
 DWORD    - number of file names that follow
 <string> - file name(s)

 The other LINNUM386 record looks like this: there is a header followed by
variable number of line number subrecords. The header is 14 bytes long:

 WORD   - segment (will be non-zero)
 DWORD  - unknown
 DWORD  - number of line number subrecords following
 DWORD  - unknown

 Each line number subrecord is 8 bytes long:

 WORD   - source line number
 WORD   - source file index (corresponds to preceding LINNUM386 record)
 DWORD  - offset within the segment

 Coupled with the information in the preceding LINNUM386 record, this uniquely
identifies lines in particular source files.

 Some of our code parses the LINNUM records. If it vital that we only parse
this data when we know what format it is in! Otherwise we're sure to get
errors or crashes.
