home *** CD-ROM | disk | FTP | other *** search
/ Education Sampler 1992 [NeXTSTEP] / Education_1992_Sampler.iso / NeXT / GnuSource / cc-61.0.1 / cc / README.DWARF < prev    next >
Text File  |  1991-05-13  |  21KB  |  425 lines
  1. Notes on GNU DWARF
  2. ------------------
  3.  
  4. This file accompanies a set of patches (i.e. a patch kit) to the Data General
  5. 1.37.27 version of the GNU C compiler (GCC).  When applied to the DG
  6. 1.37.27 version of GCC, the result should be a version of GCC which
  7. is able to generate DWARF debugging information for systems based on the
  8. Motorola 88000 processor.
  9.  
  10. Note that as of DG version 1.37.27 of GCC, all patches necessary for
  11. generating DWARF debugging information have been completely pre-integrated
  12. into DG versions of GCC.
  13.  
  14. No attempt has been made to insure that the code which implements the
  15. support for DWARF generation is either useful or correct when used with
  16. other versions of GCC or when used for target processors other that 88k's.
  17. In short, if it don't work for non-88k systems, or for GCC releases other
  18. than the one specified here, don't blame me.
  19.  
  20. The DWARF patches have been generously donated by Network Computing Devices
  21. to the Free Software Foundation, and are covered under the GNU General Public
  22. Licence (aka `copyleft').
  23.  
  24. If you have questions or comments about these DWARF patches to GCC, please
  25. send mail to me <rfg@ncd.com>.  I will be happy to investigate any bugs
  26. reported and I may even provide fixes (but of course, I can make no promises).
  27.  
  28. The DWARF debugging information produced by GCC deviates in a few minor
  29. (but perhaps significant) respects from the DWARF debugging information
  30. which may be produced by other C compilers.  (Herein, the DWARF produced
  31. to date by other C compilers shall be referred to as `Traditional DWARF'.)
  32.  
  33. The following paragraphs describe known differences between GNU DWARF and
  34. traditional DWARF.
  35.  
  36. Note that a significant effort has been made to get the GNU compilers to
  37. produce DWARF which, although different in some small respects from
  38. traditional DWARF, is still close enough to traditional DWARF that it
  39. should cause little or no problems for existing tools (i.e. linkers,
  40. debuggers, etc.)  which expect their input files to contain traditional
  41. DWARF code.
  42.  
  43. (Footnote: Within this file, the term `Debugging Information Entry' will
  44. be abbreviated as `DIE'.)
  45.  
  46.  
  47. Known Differences Between GNU DWARF and Traditional DWARF
  48. ---------------------------------------------------------
  49.  
  50. In traditional DWARF, each DIE which represents a function definition
  51. has a sequences of direct `child' DIEs (immediately following it) which
  52. represent not only the function's formal parameters, but also all
  53. of those things (i.e. types, functions, and objects) which are
  54. declared directly within the outermost block of the function (but
  55. not within any more deeply nested blocks).
  56.  
  57. In effect, traditional DWARF fails to even recognize the existence of
  58. the outermost lexical blocks of function definitions.
  59.  
  60. In GNU DWARF, each function definition has a set of direct child DIEs
  61. which represent the function's formal parameters, and the last actual
  62. child DIE for each function definition is a lexical block DIE which
  63. represents the outermost lexical block of the given function.  This
  64. block in turn has a set of it own child DIEs which represent the things
  65. which are declared directly within the block which it represents.
  66.  
  67. The primary advantage of this approach is that it allows the compiler
  68. to communicate (to the debugger) the addresses of the true beginning and
  69. ending of the *body* of the function (excluding any prologue or epilogue
  70. code necessary to properly initialize formal parameter variables or to
  71. allocate or deallocate space for local variables).  This information
  72. can be used by the debugger to prevent invalid informational requests
  73. (e.g. printing the value of a formal or a local) from being honored when
  74. the current execution point is somewhere within either the prologue or
  75. the epilogue of the current function.
  76.  
  77. Another advantage to this approach is that it makes it very easy for the
  78. debugger to find the true beginning of a function body.  This information
  79. may be useful when setting a breakpoint at the `start' of a given function.
  80.  
  81. --------------------------------
  82.  
  83. In traditional DWARF, all DIEs representing labels and variables have
  84. `low_pc' attributes and `location' attributes (respectively).
  85.  
  86. In GNU DWARF, when compiler optimization is enabled (via -O) it is possible
  87. that some labels and local variables will be optimized out of existance.
  88. In such cases, the DIEs produced for these entities will *not* contain
  89. the normal `low_pc' and `location' attributes.  When confronted with
  90. such (perhaps non-standard) DIEs, debuggers should infer that the given
  91. entities have been optimized out of existance and that (for all practical
  92. purposes) they do not actually exist in the executable program.
  93.  
  94. --------------------------------
  95.  
  96. In traditional DWARF, a DIE for a statement label is generated at whatever
  97. point (within the hierarchy of lexical block DIEs) that the given label is
  98. first mentioned (either by being defined, or by being referred to in a goto
  99. statement).
  100.  
  101. In GNU DWARF, all label DIEs for a given function are generated such
  102. that they are direct children of the outermost lexical block DIE for
  103. the function in which they appear.  This placement more accurately
  104. reflects the true `function scope' of labels.  Furthermore, all label
  105. DIEs for a given function precede all other types of DIEs which are
  106. direct children of the outermost lexical block of the containing function.
  107.  
  108. --------------------------------
  109.  
  110. Some compilers producing traditional DWARF may fail to produce type
  111. attributes within DIEs which describe functions.  (This probably represents
  112. a bug in these DWARF implementations.)
  113.  
  114. In GNU DWARF, these `function return type' attributes *are* produced.
  115.  
  116. --------------------------------
  117.  
  118. In traditional DWARF, visibility attributes are generated only for function
  119. definitions which are explicitly declared as `static'.  (Actually, some
  120. C compilers producing `traditional DWARF' may *never* produce any visibility
  121. attributes, even for static function definitions.  This is probably just a
  122. bug in these compilers however.)
  123.  
  124. In GNU DWARF, visibility attributes are produced for all file-scope
  125. declarations (of both functions and data objects) which have `internal
  126. linkage' (as described in the ANSI C standard, section 3.1.2.2).
  127. Entities which have internal linkage are those entities which are
  128. declared at file-scope with the `static' storage class specifier.
  129. Note that all such entities get visibility attributes in which the
  130. visibility is set to `VIS_local'.
  131.  
  132. The generation of visibility attributes (with VIS_local) for all entities
  133. with internal linkage allows for the proper `commonizing' of debugging
  134. information (i.e. DIEs) within linked (i.e. linker output) object files
  135. produced by linking multiple original object files together.  Specifically,
  136. the generation of these visibility attributes is required in order to
  137. prevent the unwarranted commonizing of DIEs representing external linkage
  138. entities with DIEs for similarly named entities (from other compilation
  139. units) which have internal linkage.
  140.  
  141. --------------------------------
  142.  
  143. Traditional DWARF was defined with the (incorrect) belief in mind that an
  144. integral type which is explicitly declared as `signed' and an (otherwise
  145. identical) `plain' integral are somehow different.  In fact, ANSI C and
  146. GCC believe that any such pair of types are *not* different types, but
  147. rather are exactly the same type.  (Note that there is an exception in
  148. case of `char' types; i.e. `char' and `signed char' are in fact different
  149. types.)
  150.  
  151. In GNU DWARF, no attempt is made to reinforce this incorrect notion.
  152. Thus, GNU compilers do not produce any of the three (bogus) fundamental
  153. type codes FT_signed_long, FT_signed_integer, or FT_signed_short.
  154.  
  155. --------------------------------
  156.  
  157. In traditional implementations of DWARF, DIEs which represent types may not
  158. be reused to the maximum extent possible.  Rather, DIEs representing specific
  159. types may appear more than once in the output.
  160.  
  161. The effect of this is that the .debug section may grow larger than is really
  162. necessary.
  163.  
  164. In GNU DWARF, type DIEs are reused to the maximum extent possible.
  165.  
  166. --------------------------------
  167.  
  168. The output from various compilers producing traditional DWARF may vary
  169. with respect to the ordering of DIEs describing things declared with file-
  170. scope.  This is a permissible variation within the definition of DWARF.
  171.  
  172. In GNU DWARF, DIEs representing entities declared at file scope are (in
  173. general) generated in the same order as the declarations of those entities.
  174.  
  175. --------------------------------
  176.  
  177. GNU DWARF Extensions to Handle GNU C Extensions to ANSI C
  178. ---------------------------------------------------------
  179.  
  180. The file dwarfout.c and its associated patches to the GCC sources have been
  181. designed and implemented so as to provide some reasonable DWARF representation
  182. for each and every declarative construct which is accepted by the GNU C
  183. compiler.  Since the GNU C compiler accepts a superset of ANSI C, this means
  184. that there are some cases in which the DWARF information produced by GCC
  185. must take some liberties in violating the rules of `traditional DWARF' in
  186. order to represent declarations which are legal in GNU C but illegal in
  187. ANSI C.  These are described below.
  188.  
  189. --------------------------------
  190.  
  191. GNU C provides a `inline functions' feature (a la C++).  At all sites in the
  192. source code where GCC actually `inlines' a given inline function, proper
  193. DWARF information (including proper .line section entries) will be generated
  194. to allow the debugger to fully understand that code from the inlined function
  195. was incorporated at that site.  In particular, the block (scope) structure
  196. of the inlined function is preserved and is directly reflected in the DWARF
  197. information generated at the call site.  Also, the DWARF representations for
  198. the `location attributes' of all local variables and parameter variables of
  199. the inlined function are adjusted so as to reflect the actual locations of
  200. the corresponding entities after inlining at the call site.
  201.  
  202. Note that wherever a function gets inlined (at a call site) the DWARF
  203. information generated for that call site will properly reflect the fact
  204. that the formal parameter variables of the called function are effectively
  205. changed into local variables (at the call site) as a result of the inlining.
  206.  
  207. --------------------------------
  208.  
  209. GNU C provides a `dynamically sized array' feature in which the declarations of
  210. local (storage class `auto') array variables are allowed to specify non-static
  211. expressions as individual array dimensions.
  212.  
  213. Traditional DWARF does specify a proper way of representing such dynamically
  214. bounded arrays, however it requires that the value of each upper bound of each
  215. dimension be accessible at run-time throughout the scope of the given array
  216. object.
  217.  
  218. Normally, GCC makes sure that these (dynamic) upper bound values are in fact
  219. computed and stored (either in stack slots or in registers) such that they
  220. can be made available to a debugger throughout the scope of any such dynamic
  221. arrays, however when optimization (-O) is used, GCC typically (and correctly)
  222. finds it to be unnecessarily inefficient to compute and to save these dynamic
  223. upper bound values.  Thus, when both -O and -g are used, GCC can produce
  224. TAG_array_type DIEs in which one or more dimensions are represented as
  225. having dynamic upper bounds, but the `location descriptions' for the upper
  226. bound values themselves will be empty (indicating that the given upper
  227. bound is unknown and unknowable).
  228.  
  229. Note that while empty location descriptions for array bounds are in fact
  230. allowed in traditional DWARF,  their only known (legal) use is as an
  231. indication of an incomplete array type, as in:
  232.  
  233.     typedef int array[];
  234.  
  235. Other uses of empty location descriptions for particular array bounds (such
  236. as GCC's use of them to represent upper bounds for dynamic dimensions when
  237. -O is in use) may cause some traditional DWARF debuggers to choke.
  238.  
  239. --------------------------------
  240.  
  241. GNU DWARF Optional Extensions for G++ and GDB
  242. ---------------------------------------------
  243.  
  244. Each GNU DWARF optional extension is controlled by the presence or
  245. absence of a particular preprocessor #define for a given special
  246. symbol within your target-specific tm-*.h file.  These special
  247. symbols are described below.
  248.  
  249. --------------------------------
  250.  
  251. Define GPLUSPLUS if you plan to use dwarfout.c with the GNU g++ compiler.
  252. Note that the implementation of full DWARF support for g++ is (as yet)
  253. unfinished.  If you want to use DWARF debugging information with the g++
  254. compiler you will have to finish the work yourself.  (Note: you may want
  255. to contact John Hassey @ DG <hassey@dg-rtp.dg.com> if you have a serious
  256. interest in this.)
  257.  
  258. --------------------------------
  259.  
  260. Define DWARF_DESCRIBE_USED_EXTERNS if you want the DWARF info for any given
  261. object file to include descriptions of things (i.e. data objects and
  262. functions) which are explicitly declared as `extern' and which are actually
  263. referenced somewhere within the current compilation unit.  This can be useful
  264. if you have a linker which is capable of doing type checking across object
  265. files (based upon DWARF type specifications).  When you define this symbol,
  266. DWARF DIEs will be generated to describe used items declared `extern' and
  267. these DIEs will be placed into the special .externs section (in order to
  268. avoid mixing them with the DIEs used for debugging).
  269.  
  270. The layout of the special .externs section is very similar to that of the
  271. .debug section.  In particular, it begins with an (abbrevaited) source_file
  272. DIE which includes a pointer to the endpoint of the information in the
  273. .externs section for the current compilation unit.  Following the source_file
  274. DIE, there will be a sequence of normal DIE for variables, functions, and
  275. function formal parameter types.  Not that these DIEs may (and often do)
  276. make corss-section references to the type descriptions contained within
  277. the .debug section.  The list of clid DIEs for the source_file DIE is
  278. terminated with a single word with the value 4 (as in the .debug section).
  279.  
  280. --------------------------------
  281.  
  282. Define DWARF_LOCATION_ATTRIBUTES if you want the compiler to generate the
  283. special extended DWARF attributes `AT_file' and `AT_line' for DIEs describing
  284. declared entities whose types may differ in different compilation units.
  285.  
  286. The primary purpose of this option is to allow an intelligent linker (which
  287. has the cross-compilation-unit type checking feature) to identify (in error
  288. messages) the precise locations of conflicting enternal-linkage declarations.
  289. Thus, this option is normally useful only in conjunction with the
  290. DWARF_DESCRIBE_USED_EXTERNS option.
  291.  
  292. WARNING: Use of this option causes DIEs in the .debug section to include
  293. non-standard DWARF attributes.  This may cause trouble for debuggers which
  294. cannot properly cope with non-standard DWARF attributes.
  295.  
  296. --------------------------------
  297.  
  298. Define DWARF_DESCRIBE_FILES if you want extra information generated (in the
  299. special .files and .finfo sections) which can give the debugger enhanced
  300. information regarding the source files which contribute to the executable
  301. code generated for each compilation unit.
  302.  
  303. To understand this GNU DWARF extension, imagine that the sequence of entries
  304. in the .lines section is broken up into several subsections.  Each contiguous
  305. sequence of .line entries which relates to a sequence of lines (or statements)
  306. from one particular file (either a `base' file or an `include' file) could
  307. be called a `line entries chunk' (LEC).
  308.  
  309. For each LEC there is one entry in the .finfo section.
  310.  
  311. Each *normal* entry in the .finfo section contains two parts:
  312.  
  313.     (1) A 4-byte pointer to the start of the first .line entry in the
  314.         given LEC, and
  315.  
  316.     (2) a 4-byte pointer to a string in the .files section.
  317.  
  318. Obviously, each .finfo entry allows you to find the relevant filename, and
  319. it also points you to the first .line entry that was generated as a result
  320. of having compiled a given source line from the given source file.
  321.  
  322. Each subsequent .line entry should also be assumed to have been produced
  323. as a result of compiling yet more lines from the same file.  The end of
  324. any given LEC is easily found by looking at the first 4-byte pointer in
  325. the *next* .finfo entry.  That next .finfo entry points to a new and
  326. different LEC, so the preceeding LEC (implicitly) must have ended with
  327. the last .line section entry which occurs at the 2 1/2 words just before
  328. the address given in the first pointer of the new .finfo entry.
  329.  
  330. The following picture may help to clarify this feature.  Let's assume that
  331. `LE' stands for `.line entry'.  Also, assume that `* 'stands for a pointer.
  332.  
  333.  
  334.     .line section        .finfo section        .files section
  335.     ----------------------------------------------------------------
  336.  
  337.     LE  <---------------------- *
  338.     LE                * -----------------> "foobar.c" <---
  339.     LE                                |
  340.     LE                                |
  341.     LE  <---------------------- *                    |
  342.     LE                * -----------------> "foobar.h" <|    |
  343.     LE                                 |    |
  344.     LE                                 |    |
  345.     LE  <---------------------- *                     |    |
  346.     LE                * ----------------->  "inner.h"  |    |
  347.     LE                                 |    |
  348.     LE  <---------------------- *                     |    |
  349.     LE                * -------------------------------    |
  350.     LE                                |
  351.     LE                                |
  352.     LE                                |
  353.     LE                                |
  354.     LE  <---------------------- *                    |
  355.     LE                * -----------------------------------
  356.     LE
  357.     LE
  358.     LE
  359.  
  360. In effect, each entry in the .finfo section points to *both* a filename
  361. and to (the start of) a block of (consecutive) LEs.
  362.  
  363. Note that just like in the .line section, there are specialized first and
  364. last entries in the .finfo section for each object file.  These special
  365. first and last entries are different from normal ones and they can clearly
  366. indicate (to the debugger) where the set of .finfo entries for that object
  367. file begins and ends.  The debugger will need this information in order
  368. to correctly interpret the .finfo entries.
  369.  
  370. Note also that the first string in the .files section for each object file
  371. will be the full absolute pathname of the directory from which the compiler
  372. was invoked when the given object file was produced.  This tells debuggers
  373. which directory all other (relative) pathnames in the .files section are
  374. relative to.  Proper use of this `compilation directory' string can make
  375. commands like GDB's `directory' command obsolete.
  376.  
  377. --------------------------------
  378.  
  379. Future Directions
  380. -----------------
  381.  
  382. The codes, formats, and other paraphernalia necessary to provide proper
  383. support for symbolic debugging for languages other than C (and in particular,
  384. C++) is not yet well defined for DWARF.  Hopefully, A more complete form
  385. of DWARF which can handle *all* of the symbolic debugging requirements
  386. for C++, FORTRAN, Pascal, Modula, and Ada will evolve in the future.
  387. Efforts are currently underway to develop and promote such extensions to
  388. DWARF under the auspices of the UNIX(r) International Programming Languages
  389. Special Interest Group.  Contact the Chairman, Dan Oldman (oldman@dg-rtp.dg.com)
  390. for further information.
  391.  
  392. As currently defined, DWARF only describes a (binary) language which can
  393. be used to communicate symbolic debugging information from a compiler
  394. through an assembler and a linker, to a debugger.  There is no clear
  395. specification of what processing should be (or must be) done by the
  396. assembler and/or the linker.  Fortunately, the role of the assembler
  397. is easily inferred (by anyone knowledgeable about assemblers) just by
  398. looking  at examples of assembly-level DWARF code.  Sadly though, the
  399. allowable (or required) processing steps performed by a linker are
  400. harder to infer and (perhaps) even harder to agree upon.  There are
  401. several forms of very useful `post-processing' steps which intelligent
  402. linkers *could* (in theory) perform on object files containing DWARF,
  403. but any and all such link-time transformations are currently both disallowed
  404. and unspecified.
  405.  
  406. In particular, possible link-time transformations of DWARF code which could
  407. provide dramatic benefits include (but are not limited to):
  408.  
  409.     Commonization of duplicate DIEs obtained from multiple input
  410.     (object) files.
  411.  
  412.     Reorganization (i.e. re-ordering) of DIEs (in linked output files)
  413.     to provide for decreased I/O (at debug-time) and a corresponding
  414.     increase in debugger speed.
  415.  
  416.     Cross-compilation type checking based upon DWARF type information
  417.     for objects and functions.
  418.  
  419.     Creation of additional `fast lookup tables' (by the linker) which
  420.     could be stored in new and unique output sections designed expressly
  421.     for this purpose.
  422.  
  423.     Other possible `compacting' transformations designed to save disk
  424.     space and to reduce linker & debugger I/O activity.
  425.