![[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
1.1.1.2 ! root 28: output) are consistent with those used by the svr4 SDB debuggers provided
1.1 root 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
1.1.1.2 ! root 35: License (aka `copyleft') just as the rest of GCC is.
1.1 root 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
1.1.1.2 ! root 51: <[email protected]>. The UI/PLSIG welcomes and encourages the
! 52: participation of new members who might be interested in discussing debugging
1.1 root 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
1.1.1.2 ! root 183: to a new and different LEC, so the preceding LEC (implicitly) must have
1.1 root 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
1.1.1.2 ! root 248: compilation of this compilation unit occurred. This value
1.1 root 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
1.1.1.2 ! root 256: compilation unit is the name of the directory in which compilation occurred.
1.1 root 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
1.1.1.2 ! root 374: output of GCC) in the most natural and intuitively obvious ways.
1.1 root 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.