readme.dwarf

早期freebsd实现

	LE			    * -----------------> "foobar.c" <---
	LE								|
	LE								|
	LE  <---------------------- *					|
	LE			    * -----------------> "foobar.h" <|	|
	LE							     |	|
	LE							     |	|
	LE  <---------------------- *				     |	|
	LE			    * ----------------->  "inner.h"  |	|
	LE							     |	|
	LE  <---------------------- *				     |	|
	LE			    * -------------------------------	|
	LE								|
	LE								|
	LE								|
	LE								|
	LE  <---------------------- *					|
	LE			    * -----------------------------------
	LE
	LE
	LE

In effect, each entry in the .debug_srcinfo section points to *both* a
filename (in the .debug_sfnames section) and to the start of a block of
consecutive LEs (in the .line section).

Note that just like in the .line section, there are specialized first and
last entries in the .debug_srcinfo section for each object file.  These
special first and last entries for the .debug_srcinfo section are very
different from the normal .debug_srcinfo section entries.  They provide
additional information which may be helpful to a debugger when it is
interpreting the data in the .debug_srcinfo, .debug_sfnames, and .line
sections.

The first entry in the .debug_srcinfo section for each compilation unit
consists of five 4-byte words of data.  The contents of these five words
should be interpreted (by debuggers) as follows:

	(1)	The starting address (relative to the entire .line section)
		of the .line section for this compilation unit.

	(2)	The starting address (relative to the entire .debug_sfnames
		section) of the .debug_sfnames section for this compilation
		unit.

	(3)	The starting address (in the execution virtual address space)
		of the .text section for this compilation unit.

	(4)	The ending address plus one (in the execution virtual address
		space) of the .text section for this compilation unit.

	(5)	The date/time (in seconds since midnight 1/1/70) at which the
		compilation of this compilation unit occurred.  This value
		should be interpreted as an unsigned quantity because gcc
		might be configured to generate a default value of 0xffffffff
		in this field (in cases where it is desired to have object
		files created at different times from identical source files
		be byte-for-byte identical).  By default, these timestamps
		are *not* generated by dwarfout.c (so that object files
		compiled at different times will be byte-for-byte identical).
		If you wish to enable this "timestamp" feature however, you
		can simply place a #define for the symbol `DWARF_TIMESTAMPS'
		in your target configuration file and then rebuild the GNU
		compiler(s).

Note that the first string placed into the .debug_sfnames section for each
compilation unit is the name of the directory in which compilation occurred.
This string ends with a `/' (to help indicate that it is the pathname of a
directory).  Thus, the second word of each specialized initial .debug_srcinfo
entry for each compilation unit may be used as a pointer to the (string)
name of the compilation directory, and that string may in turn be used to
"absolutize" any relative pathnames which may appear later on in the
.debug_sfnames section entries for the same compilation unit.

The fifth and last word of each specialized starting entry for a compilation
unit in the .debug_srcinfo section may (depending upon your configuration)
indicate the date/time of compilation, and this may be used (by a debugger)
to determine if any of the source files which contributed code to this
compilation unit are newer than the object code for the compilation unit
itself.  If so, the debugger may wish to print an "out-of-date" warning
about the compilation unit.

The .debug_srcinfo section associated with each compilation will also have
a specialized terminating entry.  This terminating .debug_srcinfo section
entry will consist of the following two 4-byte words of data:

	(1)	The offset, measured from the start of the .line section to
		the beginning of the terminating entry for the .line section.

	(2)	A word containing the value 0xffffffff.

--------------------------------

In the current DWARF version 1 specification, no mechanism is specified by
which information about macro definitions and un-definitions may be provided
to the DWARF consumer.

The DWARF version 2 (draft) specification does specify such a mechanism.
That specification was based on the GNU ("vendor specific extension")
which provided some support for macro definitions and un-definitions,
but the "official" DWARF version 2 (draft) specification mechanism for
handling macros and the GNU implementation have diverged somewhat.  I
plan to update the GNU implementation to conform to the "official"
DWARF version 2 (draft) specification as soon as I get time to do that.

Note that in the GNU implementation, additional information about macro
definitions and un-definitions is *only* provided when the -g3 level of
debug-info production is selected.  (The default level is -g2 and the
plain old -g option is considered to be identical to -g2.)

GCC records information about macro definitions and undefinitions primarily
in a section called the .debug_macinfo section.  Normal entries in the
.debug_macinfo section consist of the following three parts:

	(1)	A special "type" byte.

	(2)	A 3-byte line-number/filename-offset field.

	(3)	A NUL terminated string.

The interpretation of the second and third parts is dependent upon the
value of the leading (type) byte.

The type byte may have one of four values depending upon the type of the
.debug_macinfo entry which follows.  The 1-byte MACINFO type codes presently
used, and their meanings are as follows:

	MACINFO_start		A base file or an include file starts here.
	MACINFO_resume		The current base or include file ends here.
	MACINFO_define          A #define directive occurs here.
	MACINFO_undef           A #undef directive occur here.

(Note that the MACINFO_... codes mentioned here are simply symbolic names
for constants which are defined in the GNU dwarf.h file.)

For MACINFO_define and MACINFO_undef entries, the second (3-byte) field
contains the number of the source line (relative to the start of the current
base source file or the current include files) when the #define or #undef
directive appears.  For a MACINFO_define entry, the following string field
contains the name of the macro which is defined, followed by its definition.
Note that the definition is always separated from the name of the macro
by at least one whitespace character.  For a MACINFO_undef entry, the
string which follows the 3-byte line number field contains just the name
of the macro which is being undef'ed.

For a MACINFO_start entry, the 3-byte field following the type byte contains
the offset, relative to the start of the .debug_sfnames section for the
current compilation unit, of a string which names the new source file which
is beginning its inclusion at this point.  Following that 3-byte field,
each MACINFO_start entry always contains a zero length NUL terminated
string.

For a MACINFO_resume entry, the 3-byte field following the type byte contains
the line number WITHIN THE INCLUDING FILE at which the inclusion of the
current file (whose inclusion ends here) was initiated.  Following that
3-byte field, each MACINFO_resume entry always contains a zero length NUL
terminated string.

Each set of .debug_macinfo entries for each compilation unit is terminated
by a special .debug_macinfo entry consisting of a 4-byte zero value followed
by a single NUL byte.

--------------------------------

In the current DWARF draft specification, no provision is made for providing
a separate level of (limited) debugging information necessary to support
tracebacks (only) through fully-debugged code (e.g. code in system libraries).

A proposal to define such a level was submitted (by me) to the UI/PLSIG.
This proposal was rejected by the UI/PLSIG for inclusion into the DWARF
version 1 specification for two reasons.  First, it was felt (by the PLSIG)
that the issues involved in supporting a "traceback only" subset of DWARF
were not well understood.  Second, and perhaps more importantly, the PLSIG
is already having enough trouble agreeing on what it means to be "conformant"
to the DWARF specification, and it was felt that trying to specify multiple
different *levels* of conformance would only complicate our discussions of
this already divisive issue.  Nonetheless, the GNU implementation of DWARF
provides an abbreviated "traceback only" level of debug-info production for
use with fully-debugged "system library" code.  This level should only be
used for fully debugged system library code, and even then, it should only
be used where there is a very strong need to conserve disk space.  This
abbreviated level of debug-info production can be used by specifying the
-g1 option on the compilation command line.

--------------------------------

As mentioned above, the GNU implementation of DWARF currently uses the DWARF
version 2 (draft) approach for inline functions (and inlined instances
thereof).  This is used in preference to the version 1 approach because
(quite simply) the version 1 approach is highly brain-damaged and probably
unworkable.

--------------------------------


GNU DWARF Representation of GNU C Extensions to ANSI C
------------------------------------------------------

The file dwarfout.c has been designed and implemented so as to provide
some reasonable DWARF representation for each and every declarative
construct which is accepted by the GNU C compiler.  Since the GNU C
compiler accepts a superset of ANSI C, this means that there are some
cases in which the DWARF information produced by GCC must take some
liberties in improvising DWARF representations for declarations which
are only valid in (extended) GNU C.

In particular, GNU C provides at least three significant extensions to
ANSI C when it comes to declarations.  These are (1) inline functions,
and (2) dynamic arrays, and (3) incomplete enum types.  (See the GCC
manual for more information on these GNU extensions to ANSI C.)  When
used, these GNU C extensions are represented (in the generated DWARF
output of GCC) in the most natural and intuitively obvious ways.

In the case of inline functions, the DWARF representation is exactly as
called for in the DWARF version 2 (draft) specification for an identical
function written in C++; i.e. we "reuse" the representation of inline
functions which has been defined for C++ to support this GNU C extension.

In the case of dynamic arrays, we use the most obvious representational
mechanism available; i.e. an array type in which the upper bound of
some dimension (usually the first and only dimension) is a variable
rather than a constant.  (See the DWARF version 1 specification for more
details.)

In the case of incomplete enum types, such types are represented simply
as TAG_enumeration_type DIEs which DO NOT contain either AT_byte_size
attributes or AT_element_list attributes.

--------------------------------


Future Directions
-----------------

The codes, formats, and other paraphernalia necessary to provide proper
support for symbolic debugging for the C++ language are still being worked
on by the UI/PLSIG.  The vast majority of the additions to DWARF which will
be needed to completely support C++ have already been hashed out and agreed
upon, but a few small issues (e.g. anonymous unions, access declarations)
are still being discussed.  Also, we in the PLSIG are still discussing
whether or not we need to do anything special for C++ templates.  (At this
time it is not yet clear whether we even need to do anything special for
these.) 

Unfortunately, as mentioned above, there are quite a few problems in the
g++ front end itself, and these are currently responsible for severly
restricting the progress which can be made on adding DWARF support
specifically for the g++ front-end.  Furthermore, Richard Stallman has
expressed the view that C++ friendships might not be important enough to
describe (in DWARF).  This view directly conflicts with both the DWARF
version 1 and version 2 (draft) specifications, so until this small
misunderstanding is cleared up, DWARF support for g++ is unlikely.

With regard to FORTRAN, the UI/PLSIG has defined what is believed to be a
complete and sufficient set of codes and rules for adequately representing
all of FORTRAN 77, and most of Fortran 90 in DWARF.  While some support for
this has been implemented in dwarfout.c, further implementation and testing
will have to await the arrival of the GNU Fortran front-end (which is
currently in early alpha test as of this writing).

GNU DWARF support for other languages (i.e. Pascal and Modula) is a moot
issue until there are GNU front-ends for these other languages.

GNU DWARF support for DWARF version 2 will probably not be attempted until
such time as the version 2 specification is finalized.  (More work needs
to be done on the version 2 specification to make the new "abbreviations"
feature of version 2 more easily implementable.  Until then, it will be
a royal pain the ass to implement version 2 "abbreviations".)  For the
time being, version 2 features will be added (in a version 1 compatible
manner) when and where these features seem necessary or extremely desirable.

As currently defined, DWARF only describes a (binary) language which can
be used to communicate symbolic debugging information from a compiler
through an assembler and a linker, to a debugger.  There is no clear
specification of what processing should be (or must be) done by the
assembler and/or the linker.  Fortunately, the role of the assembler
is easily inferred (by anyone knowledgeable about assemblers) just by
looking  at examples of assembly-level DWARF code.  Sadly though, the
allowable (or required) processing steps performed by a linker are
harder to infer and (perhaps) even harder to agree upon.  There are
several forms of very useful `post-processing' steps which intelligent
linkers *could* (in theory) perform on object files containing DWARF,
but any and all such link-time transformations are currently both disallowed
and unspecified.

In particular, possible link-time transformations of DWARF code which could
provide significant benefits include (but are not limited to):

	Commonization of duplicate DIEs obtained from multiple input
	(object) files.

	Cross-compilation type checking based upon DWARF type information
	for objects and functions.

	Other possible `compacting' transformations designed to save disk
	space and to reduce linker & debugger I/O activity.