![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README.DWARF CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to README.DWARF CVS log | Up to [GCC 2.x] / gcc |
1.1 ! root 1: Notes on the GNU Implementation of Dwarf Debugging Information ! 2: -------------------------------------------------------------- ! 3: Last Updated: Sun Feb 16 21:31:53 1991 by [email protected] ! 4: ----------------------------------------------------- ! 5: ! 6: This file describes special and unique aspects of the GNU implementation ! 7: of the Dwarf debugging information language in the GCC Version 2 compiler. ! 8: ! 9: For general information about the Dwarf debugging information language, ! 10: you should obtain the latest Dwarf draft specification document developed ! 11: by the UNIX(tm) International Programming Languages Special Interest Group. ! 12: A copy of the this document (in PostScript form) may be obtained either ! 13: from me <[email protected]> or from the UI/PLSIG draft specification editor, ! 14: Joel Silverstein <[email protected]>. This file describes only known deviations ! 15: from the current UI/PLSIG Dwarf specification document together with ! 16: those things which are allowed by the current Dwarf specification but ! 17: which are known to cause interoperability problems (e.g. with svr4 SDB). ! 18: ! 19: The generation of Dwarf debugging information in GCC2 has now been tested ! 20: lightly (C language front end only) for m88k, i386, and i860 targets. ! 21: Significant interoperability problems may still exist (e.g. with the ! 22: USL svr4 version of the SDB debugger) due to a lack of accepted ! 23: standards for numbering registers for various target architectures. ! 24: (That is only one of the potential interoperability problems. See below ! 25: for notes on other known interoperability problems applicable to the ! 26: combination of GCC and svr4 SDB.) Note however that it is currently ! 27: believed that the register numbering conventions used by GCC (in Dwarf ! 28: output) are consistant with those used by the svr4 SDB debuggers provided ! 29: with the System V Release 4 reference ports for the m88k, i386, and i860 ! 30: processors. ! 31: ! 32: The Dwarf generation enhancement for GCC has been generously donated ! 33: by Network Computing Devices to the Free Software Foundation. The ! 34: additional code involved is covered under the GNU General Public ! 35: Licence (aka `copyleft') just as the rest of GCC is. ! 36: ! 37: If you have questions or comments about the Dwarf generation feature ! 38: of GCC, please send mail to me <[email protected]>. I will be happy to ! 39: investigate any bugs reported and I may even provide fixes (but of ! 40: course, I can make no promises). ! 41: ! 42: The Dwarf debugging information produced by GCC may deviate in a few minor ! 43: (but perhaps significant) respects from the Dwarf debugging information ! 44: currently produced by other C compilers. A serious attempt has been ! 45: made however to conform to existing practice and generally accepted ! 46: standards in the GNU implementation of Dwarf. ! 47: ! 48: If you are interested in obtaining more information about Dwarf or in ! 49: participating in the continuing evolution of Dwarf within the UI/PLSIG ! 50: group, please contact either myself or the UI/PLSIG chairman, Dan Oldman ! 51: <[email protected]>. The UI/PLSIG welcomes and encourages the partici- ! 52: pation of new members who might be interested in discussing debugging ! 53: issues in general, and Dwarf in particular. There are no dues and you ! 54: DO NOT have to be a UI member in order to join the UI/PLSIG. The UI/PLSIG ! 55: operates an E-mail mailing list and holds regular meeting in various cities. ! 56: If you don't have time to participate actively, but would like to be kept ! 57: abrest of recent developments, you con join the UI/PLSIG mailing list and ! 58: just listen in on our lively discussions. ! 59: ! 60: (Footnote: Within this file, the term `Debugging Information Entry' will ! 61: be abbreviated as `DIE'.) ! 62: ! 63: ! 64: Release Notes (aka known bugs) ! 65: ------------------------------- ! 66: ! 67: At this time, GCC does not know how to handle the GNU C "nested functions" ! 68: extension. (See the GCC manual for more info on this extension to ANSI C.) ! 69: ! 70: -------------------------------- ! 71: ! 72: At this time, GCC does not represent inlined instances of inline functions ! 73: as called for by the current Dwarf draft specification. Support for inlined ! 74: instances of inline functions is still "under construction". ! 75: ! 76: -------------------------------- ! 77: ! 78: At this time, GCC does not generate the kind of really precise information ! 79: about the exact declared types of entities with signed integral types which ! 80: is required by the current Dwarf draft specification. ! 81: ! 82: Specifically, the current Dwarf draft specification seems to require that ! 83: the type of an non-unsigned integral bit-field member of a struct or union ! 84: type be represented as either a "signed" type or as a "plain" type, ! 85: depending upon the the exact set of keywords that were used in the ! 86: type specification for the given bit-field member. It was felt (by the ! 87: UI/PLSIG) that this distinction between "plain" and "signed" integral types ! 88: could have some significance (in the case of bit-fields) because ANSI C ! 89: does not constrain the signedness of a plain bit-field, whereas it does ! 90: constrain the signedness of an explicitly "signed" bit-field. For this ! 91: reason, the current Dwarf specification calls for compilers to produce ! 92: type information (for *all* integral typed entities... not just bit-fields) ! 93: which explicitly indicates the signedness of the relevant type to be ! 94: "signed" or "plain" or "unsigned". ! 95: ! 96: Unfortunately, the GNU Dwarf implementation is currently incapable of making ! 97: such distinctions. ! 98: ! 99: -------------------------------- ! 100: ! 101: Full Dwarf support for the GNU C++ language/front-end (aka g++) is not ! 102: implemented at this time. ! 103: ! 104: -------------------------------- ! 105: ! 106: ! 107: Known Interoperability Problems ! 108: ------------------------------- ! 109: ! 110: Although the GNU implementation of Dwarf conforms (for the most part) with ! 111: the current UI/PLSIG Dwarf draft specification, there are a few known cases ! 112: where GCC's Dwarf output causes confusion in System V Release 4 SDB debuggers ! 113: anyway. There cases are described in this section. ! 114: ! 115: -------------------------------- ! 116: ! 117: The current Dwarf draft specification includes the fundamental type codes ! 118: FT_ext_prec_float, FT_complex, FT_dbl_prec_complex, and FT_ext_prec_complex. ! 119: Since GNU C is only a C compiler (and since C doesn't provide any "complex" ! 120: data types) the only one of these fundamental type codes which GCC ever ! 121: generates is FT_ext_prec_float. This fundamental type code is generated ! 122: by GCC for the `long double' data type. Unfortunately, due to an apparent ! 123: bug, SVR4 SDB can become very confused wherever any attempt is made to ! 124: print a variable, parameter, or field whose type was given in terms of ! 125: FT_ext_prec_float. ! 126: ! 127: (Actually, SVR4 SDB fails to understand *any* of the four fundamental type ! 128: codes mentioned here. This will fact will cause additional problems when ! 129: there is a GNU FORTRAN front-end.) ! 130: ! 131: -------------------------------- ! 132: ! 133: In general, it appears that SVR4 SDB is not able to effectively ignore ! 134: fundamental type codes in the "implementation defined" range. This can ! 135: cause problems when a program being debugged uses the `long long' data ! 136: type (or the signed or unsigned varieties thereof) because these types ! 137: are not defined by ANSI C, and thus, GCC must use its own private fundamental ! 138: type codes (from the implementation-defined range) to represent these types. ! 139: ! 140: -------------------------------- ! 141: ! 142: ! 143: General GNU Dwarf extensions ! 144: ---------------------------- ! 145: ! 146: In the current Dwarf draft specification, no provision is made for providing ! 147: accurate information about executable lines which came into the current ! 148: compilation unit by way of an include file. ! 149: ! 150: Recently, a scheme for providing accurate information about code in include ! 151: files was proposed (by me) to the UI/PLSIG. This scheme was rejected by the ! 152: UI/PLSIG for inclusion into the Dwarf Version 1 specification, but GNU Dwarf ! 153: implements this extension anyway. ! 154: ! 155: To understand this GNU Dwarf extension, imagine that the sequence of entries ! 156: in the .lines section is broken up into several subsections. Each contiguous ! 157: sequence of .line entries which relates to a sequence of lines (or statements) ! 158: from one particular file (either a `base' file or an `include' file) could ! 159: be called a `line entries chunk' (LEC). ! 160: ! 161: For each LEC there is one entry in the .debug_srcinfo section. ! 162: ! 163: Each normal entry in the .debug_srcinfo section consists of two 4-byte ! 164: words of data as follows: ! 165: ! 166: (1) The starting address (relative to the entire .line section) ! 167: of the first .line entry in the relevant LEC. ! 168: ! 169: (2) The starting address (relative to the entire .debug_sfnames ! 170: section) of a NUL terminated string representing the ! 171: relevant filename. (This filename name be either a ! 172: relative or an absolute filename, depending upon how the ! 173: given source file was located during compilation.) ! 174: ! 175: Obviously, each .debug_srcinfo entry allows you to find the relevant filename, ! 176: and it also points you to the first .line entry that was generated as a result ! 177: of having compiled a given source line from the given source file. ! 178: ! 179: Each subsequent .line entry should also be assumed to have been produced ! 180: as a result of compiling yet more lines from the same file. The end of ! 181: any given LEC is easily found by looking at the first 4-byte pointer in ! 182: the *next* .debug_srcinfo entry. That next .debug_srcinfo entry points ! 183: to a new and different LEC, so the preceeding LEC (implicitly) must have ! 184: ended with the last .line section entry which occurs at the 2 1/2 words ! 185: just before the address given in the first pointer of the new .debug_srcinfo ! 186: entry. ! 187: ! 188: The following picture may help to clarify this feature. Let's assume that ! 189: `LE' stands for `.line entry'. Also, assume that `* 'stands for a pointer. ! 190: ! 191: ! 192: .line section .debug_srcinfo section .debug_sfnames section ! 193: ---------------------------------------------------------------- ! 194: ! 195: LE <---------------------- * ! 196: LE * -----------------> "foobar.c" <--- ! 197: LE | ! 198: LE | ! 199: LE <---------------------- * | ! 200: LE * -----------------> "foobar.h" <| | ! 201: LE | | ! 202: LE | | ! 203: LE <---------------------- * | | ! 204: LE * -----------------> "inner.h" | | ! 205: LE | | ! 206: LE <---------------------- * | | ! 207: LE * ------------------------------- | ! 208: LE | ! 209: LE | ! 210: LE | ! 211: LE | ! 212: LE <---------------------- * | ! 213: LE * ----------------------------------- ! 214: LE ! 215: LE ! 216: LE ! 217: ! 218: In effect, each entry in the .debug_srcinfo section points to *both* a ! 219: filename (in the .debug_sfnames section) and to the start of a block of ! 220: consecutive LEs (in the .line section). ! 221: ! 222: Note that just like in the .line section, there are specialized first and ! 223: last entries in the .debug_srcinfo section for each object file. These ! 224: special first and last entries for the .debug_srcinfo section are very ! 225: different from the normal .debug_srcinfo section entries. They provide ! 226: additional information which may be helpful to a debugger when it is ! 227: interpreting the data in the .debug_srcinfo, .debug_sfnames, and .line ! 228: sections. ! 229: ! 230: The first entry in the .debug_srcinfo section for each compilation unit ! 231: consists of five 4-byte words of data. The contents of these five words ! 232: should be interpreted (by debuggers) as follows: ! 233: ! 234: (1) The starting address (relative to the entire .line section) ! 235: of the .line section for this compilation unit. ! 236: ! 237: (2) The starting address (relative to the entire .debug_sfnames ! 238: section) of the .debug_sfnames section for this compilation ! 239: unit. ! 240: ! 241: (3) The starting address (in the execution virtual address space) ! 242: of the .text section for this compilation unit. ! 243: ! 244: (4) The ending address plus one (in the execution virtual address ! 245: space) of the .text section for this compilation unit. ! 246: ! 247: (5) The date/time (in seconds since midnight 1/1/70) at which the ! 248: compilation of this compilation unit occured. This value ! 249: should be interpreted as an unsigned quantity because gcc ! 250: might be configured to generate a default value of 0xffffffff ! 251: in this field (in cases where it is desired to have object ! 252: files created at different times from identical source files ! 253: be byte-for-byte identical). ! 254: ! 255: Note that the first string placed into the .debug_sfnames section for each ! 256: compilation unit is the name of the directory in which compilation occured. ! 257: This string ends with a `/' (to help indicate that it is the pathname of a ! 258: directory). Thus, the second word of each specialized initial .debug_srcinfo ! 259: entry for each compilation unit may be used as a pointer to the (string) ! 260: name of the compilation directory, and that string may in trun be used to ! 261: "absolutize" any relative pathnames which may appear later on in the ! 262: .debug_sfnames section entries for the same compilation unit. ! 263: ! 264: The fifth and last word of each specialized starting entry for a compilation ! 265: unit in the .debug_srcinfo section indicates the date/time of compilation, ! 266: and this may be used (by the debugger) to determine if any of the source ! 267: files which contributed code to this compilation unit are newer than the ! 268: object code for the compilation unit itself. If so, the debugger may wish ! 269: to print an "out-of-date" warning about the compilation unit. ! 270: ! 271: The .debug_srcinfo section associated with each compilation will also have ! 272: a specialized terminating entry. This terminating .debug_srcinfo section ! 273: entry will consist of the following two 4-byte words of data: ! 274: ! 275: (1) The offset, measured from the start of the .line section to ! 276: the beginning of the terminating entry for the .line section. ! 277: ! 278: (2) A word containing the value 0xffffffff. ! 279: ! 280: -------------------------------- ! 281: ! 282: In the current Dwarf draft specification, no provision is made for recording ! 283: any information about macro definitions and un-definitions. ! 284: ! 285: Recently, a scheme for providing accurate information about macro definitions ! 286: an un-definitions was proposed (by me) to the UI/PLSIG. This scheme was ! 287: rejected by the UI/PLSIG for inclusion into the Dwarf Version 1 specification, ! 288: but GNU Dwarf implements this extension anyway (when the -g3 option is used). ! 289: ! 290: GCC records information about macro definitions and undefinitions primarily ! 291: in a section called the .debug_macinfo section. Normal entries in the ! 292: .debug_macinfo section consist of the following three parts: ! 293: ! 294: (1) A special "type" byte. ! 295: ! 296: (2) A 3-byte line-number/filename-offset field. ! 297: ! 298: (3) A NUL terminated string. ! 299: ! 300: The interpretation of the second and third parts is dependent upon the ! 301: value of the leading (type) byte. ! 302: ! 303: The type byte may have one of four values depending upon the type of the ! 304: .debug_macinfo entry which follows. The 1-byte MACINFO type codes presently ! 305: used, and their meanings are as follows: ! 306: ! 307: MACINFO_start A base file or an include file starts here. ! 308: MACINFO_resume The current base or include file ends here. ! 309: MACINFO_define A #define directive occurs here. ! 310: MACINFO_undef A #undef directive occur here. ! 311: ! 312: (Note that the MACINFO_... codes mentioned here are simply symbolic names ! 313: for constants which are defined in the GNU dwarf.h file.) ! 314: ! 315: For MACINFO_define and MACINFO_undef entries, the second (3-byte) field ! 316: contains the number of the source line (relative to the start of the current ! 317: base source file or the current include files) when the #define or #undef ! 318: directive appears. For a MACINFO_define entry, the following string field ! 319: contains the name of the macro which is defined, followed by its definition. ! 320: Note that the definition is always separated from the name of the macro ! 321: by at least one whitespace character. For a MACINFO_undef entry, the ! 322: string which follows the 3-byte line number field contains just the name ! 323: of the macro which is being undef'ed. ! 324: ! 325: For a MACINFO_start entry, the 3-byte field following the type byte contains ! 326: the offset, relative to the start of the .debug_sfnames section for the ! 327: current compilation unit, of a string which names the new source file which ! 328: is beginning its inclusion at this point. Following that 3-byte field, ! 329: each MACINFO_start entry always contains a zero length NUL terminated ! 330: string. ! 331: ! 332: For a MACINFO_resume entry, the 3-byte field following the type byte contains ! 333: the line number WITHIN THE INCLUDING FILE at which the inclusion of the ! 334: current file (whose inclusion ends here) was initiated. Following that ! 335: 3-byte field, each MACINFO_resume entry always contains a zero length NUL ! 336: terminated string. ! 337: ! 338: Each set of .debug_macinfo entries for each compilation unit is terminated ! 339: by a special .debug_macinfo entry consisting of a 4-byte zero value followed ! 340: by a single NUL byte. ! 341: ! 342: -------------------------------- ! 343: ! 344: In the current Dwarf draft specification, no provision is made for providing ! 345: a separate level of (limited) debugging information necessary to support ! 346: tracebacks (only) through fully-debugged code (e.g. code in system libraries). ! 347: ! 348: Recently, a proposal to define such a level was submitted (by me) to the ! 349: UI/PLSIG. This proposal was rejected by the UI/PLSIG for inclusion into ! 350: the Dwarf Version 1 specification because it was felt that the issues ! 351: involved in supporting a "traceback only" subset of dwarf were not yet ! 352: well understood. Nonetheless, the GNU implementation of Dwarf provides ! 353: this extension anyway (when the -g1 option is used). ! 354: ! 355: -------------------------------- ! 356: ! 357: ! 358: GNU Dwarf Representation of GNU C Extensions to ANSI C ! 359: ------------------------------------------------------ ! 360: ! 361: The file dwarfout.c has been designed and implemented so as to provide ! 362: some reasonable Dwarf representation for each and every declarative ! 363: construct which is accepted by the GNU C compiler. Since the GNU C ! 364: compiler accepts a superset of ANSI C, this means that there are some ! 365: cases in which the Dwarf information produced by GCC must take some ! 366: liberties in improvising Dwarf representations for declarations which ! 367: are only valid in (extended) GNU C. ! 368: ! 369: In particular, GNU C provides at least three significant extensions to ! 370: ANSI C when it comes to declarations. These are (1) inline functions, ! 371: and (2) dynamic arrays, and (3) incomplete enum types. (See the GCC ! 372: manual for more information on these GNU extensions to ANSI C.) When ! 373: used, these GNU C extensions are represented (in the generated Dwarf ! 374: output of GCC) in the most natural and intutively obvious ways. ! 375: ! 376: In the case of inline functions, the Dwarf representation is exactly as ! 377: called for (in the current UI/PLSIG Dwarf draft specification) for an ! 378: identical function written in C++; i.e. we "reuse" the representation ! 379: of inline functions defined for C++ to support this GNU C extension. ! 380: ! 381: In the case of dynamic arrays, we use the most obvious representational ! 382: mechanism available; i.e. an array type in which the upper bound of ! 383: some dimension (usually the first and only dimension) is a variable ! 384: rather than a constant. See the UI/PLSIG Dwarf draft specification ! 385: for more details. ! 386: ! 387: In the case of incomplete enum types, such types are represented simply ! 388: as TAG_enumeration_type DIEs which DO NOT contain either AT_byte_size ! 389: attributes or AT_element_list attributes. ! 390: ! 391: -------------------------------- ! 392: ! 393: ! 394: Future Directions ! 395: ----------------- ! 396: ! 397: The codes, formats, and other paraphernalia necessary to provide proper ! 398: support for symbolic debugging for the C++ language have now been defined ! 399: and accepted by the UI/PLSIG. Support for C++ (i.e. the g++ front-end) ! 400: in dwarfout.c has not been fully implemented yet however. ! 401: ! 402: Likewise, the UI/PLSIG has defined what is believed to be a complete and ! 403: sufficient set of codes and rules for adequately representing all of ! 404: FORTRAN 77, and most of Fortran 90 in Dwarf. While some support for ! 405: this has been implemented in dwarfout.c, further implementation and ! 406: testing will have to await the arrival of the GNU Fortran front-end. ! 407: ! 408: Dwarf support for other languages (i.e. Pascal and Modula) currently has ! 409: a number of known problems as far as the current UI/PLSIG Dwarf draft ! 410: specification is concerned. Hopefully, A more complete form of Dwarf ! 411: which can handle *all* of the symbolic debugging requirements for Pascal, ! 412: Modula, and Ada will evolve in the future. Efforts are currently underway ! 413: to develop Dwarf more fully for these and other languages under the auspices ! 414: of the UI/PLSIG. Contact the Chairman, Dan Oldman <[email protected]> ! 415: for further information. ! 416: ! 417: As currently defined, Dwarf only describes a (binary) language which can ! 418: be used to communicate symbolic debugging information from a compiler ! 419: through an assembler and a linker, to a debugger. There is no clear ! 420: specification of what processing should be (or must be) done by the ! 421: assembler and/or the linker. Fortunately, the role of the assembler ! 422: is easily inferred (by anyone knowledgeable about assemblers) just by ! 423: looking at examples of assembly-level Dwarf code. Sadly though, the ! 424: allowable (or required) processing steps performed by a linker are ! 425: harder to infer and (perhaps) even harder to agree upon. There are ! 426: several forms of very useful `post-processing' steps which intelligent ! 427: linkers *could* (in theory) perform on object files containing Dwarf, ! 428: but any and all such link-time transformations are currently both disallowed ! 429: and unspecified. ! 430: ! 431: In particular, possible link-time transformations of Dwarf code which could ! 432: provide significant benefits include (but are not limited to): ! 433: ! 434: Commonization of duplicate DIEs obtained from multiple input ! 435: (object) files. ! 436: ! 437: Cross-compilation type checking based upon Dwarf type information ! 438: for objects and functions. ! 439: ! 440: Other possible `compacting' transformations designed to save disk ! 441: space and to reduce linker & debugger I/O activity.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.