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