Debugging Format Interoperability

From Open Watcom

Jump to: navigation, search

What is Currently Supported

Traditionally, Watcom tools have supported three debugging information formats: Watcom, DWARF, and CodeView. These formats have been supported since the 10.x product line.

The Watcom format was the only format supported in early versions of Watcom tools. It supports both 16-bit and 32-bit development and it supports C, C++ and Fortran. It has some capacity limitations, is considered obsolete, tied to x86 architecture, and its use is not recommended. Up to and including version 10.6, Watcom was the default debug debugging information format emitted by the compilers.
Open Watcom tools can both generate and read CV4 flavour of the Microsoft CodeView debugging information format. This format was used by early releases of Visual C++ and is publicly documented. It supports both 16-bit and 32-bit debugging and is not tied to the x86 architecture. Currently the Open Watcom linker emits NB05 style debug data in executable images, which are turned into NB09 format by cvpack. The DIP (Debugging Information Processor) file used by debugger, profiler, and Dr. Watcom only reads NB09 data. This format is intended primarily for interoperability with other tools, many of which can read or write CodeView debugging information. It has some capacity limitations (16-bit symbol/type handles).
This format is the default since version 11.0. DWARF is by far the most flexible and extensible (and complex) of these formats. It is not tied to any operating system or hardware architecture. DWARF is also an official standard and not a proprietary format like CodeView or Watcom. Note that Open Watcom tools always package DWARF data in an ELF container; that is, in ELF executables the DWARF data lives in regular sections, while other formats (DOS EXE, LX, PE, etc.) will contain a minimal ELF image appended at the end. As of Open Watcom 1.4, it should be possible to debug GNU executables with Open Watcom tools and vice versa. DWARF appears to be the format of choice outside the Microsoft world.

The above three debugging information formats are full fledged formats that can contain comprehensive symbol and type information. Currently there are two other, less capable formats supported:

This format is generated by IBM/Microsoft MAPSYM tool and .SYM files in this format are shipped by IBM for OS/2 system components. This format was also commonly used for 16-bit DOS development. MAPSYM format has severe capacity limitations (some 16-bit offsets)and only contains public symbol information. Open Watcom does not provide tools to generate this format. Support for MAPSYM symbol files was added in OW 1.4.
This is strictly speaking not a debugging information format at all. The EXPORTS DIP will look at NE, LX, LE, PE, ELF, and NLM modules and report information about symbols exported by name to the debugger. It is useful when calling into DLLs or shared libraries that provide no debugging information.

What Would be Good to Have

Windows .DBG files
These are symbol files delivered by Microsoft for Windows NT system components. Some contain CodeView information, but it is packaged in a special format. It is conceivable that the current CodeView DIP could be extended to handle some of these files. Older Microsoft .DBG files may also include COFF symbols, which we currently don't support. Source code and some documentation for reading (undocumented) .DBG and .PDB files can be found in the book "Undocumented Windows 2000 Secrets". Update: The book is now available from the author in PDF format here. The CodeView, .dbg and .pdb file structures are described at the end of chapter 1. Two more articles on the .pdb format by the same author is available here. The source code from the companion CD to the book is also available on the book site, and contains C source code to read and process .dbg and .pdb files.
IBM HLL debugging information
The HLL format is used by IBM's OS/2 (and presumably Windows) compilers. It is very similar to old (pre-CV4) CodeView format and uses the NB04 signature. The format is documented in good detail.
Pre-CV4 CodeView
This format was emitted notably by Microsoft C 6.0 and probably many other Microsoft tools. Executables using this format have a NB02 signature. It supports both 16-bit and 32-bit debugging, although 32-bit tools using this format are extremely rare since it was only used for early (when OS/2 was still under joint development with IBM and Microsoft) OS/2 2.0 development. IBM OS/2 debuggers understand this format, and it is very similar to IBM HLL; in fact IBM's NB04 style debug data may contain both IBM HLL and pre-CV4 CodeView data (this would happen in mixed 16/32-bit executables). This format appears to be undocumented, although source code for IBM's SD386 debugger that can work with this format is available.
Borland Turbo Debug Symbols(TDS)
This is the debugging format used by Borland C/C++ and Delphi tools. It is similar to CodeView in structure, although some details are different (likely to support Pascal/Delphi debugging). Executables using this format have a FB09 or FB0A signature. At least the FB09 format is publicly documented.
Personal tools