Incorporate changes as of the May 17 meeting. The corresponding
[dwarf-doc.git] / dwarf5 / latexdoc / introduction.tex
index 8c947b3..dbbc749 100644 (file)
@@ -55,25 +55,23 @@ content of the debugging entries. The second piece is the
 way the debugging information is encoded and represented in
 an object file.
 
-The informational content is described in 
-Sections \ref{chap:generaldescription} 
-through
-\ref{chap:otherdebugginginformation}. 
-Section  \ref{chap:generaldescription}
+The informational content is described in Chapters
+\ref{chap:generaldescription} through
+\ref{chap:otherdebugginginformation}. Chapter 
+\ref{chap:generaldescription}
 describes the overall structure of the information
-and attributes that is common to many or all of the different
-debugging information entries. 
-Sections \ref{chap:programscopeentries}, 
+and attributes that are common to many or all of the different
+debugging information entries. Chapters
+\ref{chap:programscopeentries}, 
 \ref{chap:dataobjectandobjectlistentries} and 
 \ref{chap:typeentries} describe
 the specific debugging information entries and how they
 communicate the necessary information about the source program
-to a debugger. 
-Section \ref{chap:otherdebugginginformation} 
+to a debugger. Chapter \ref{chap:otherdebugginginformation} 
 describes debugging information
 contained outside of the debugging information entries. The
-encoding of the DWARF information is presented in 
-Section \ref{datarep:datarepresentation}.
+encoding of the DWARF information is presented in Chapter
+\ref{datarep:datarepresentation}.
 
 This organization closely follows that used in the 
 \DWARFVersionIV{} document. Except where needed to incorporate
@@ -88,7 +86,6 @@ format definition itself. The several appendices consist only
 of explanatory or supplementary material, and are not part
 of the formal definition.
 
-\bb
 \section{Objectives and Rationale}
 
 DWARF has had a set of objectives since its inception which have 
@@ -99,7 +96,7 @@ understanding of the DWARF Debugging Format.
 Although DWARF Version 1 was developed in the late 1980's as a 
 format to support debugging C programs written for AT\&T hardware 
 running SVR4, \DWARFVersionII{} and later has evolved far beyond 
-this origin. One difference between DWARF and other object formats 
+this origin. One difference between DWARF and other formats 
 is that the latter are often specific to a particular language, 
 architecture, and/or operating system. 
 
@@ -121,7 +118,8 @@ particular language and which doesn't appear to have more
 general application.  For these, DWARF has a description 
 designed to meet the language requirements, although, to the 
 extent possible, an effort is made to generalize the attribute. 
-An example of this is the \DWTAGconditionNAME{} DIE, which is 
+An example of this is the \DWTAGconditionNAME{} 
+debugging information entry, 
 used to describe \addtoindex{COBOL} level 88 conditions, which 
 is described in abstract terms rather than COBOL-specific terms.  
 Conceivably, this TAG might be used with a different language 
@@ -143,13 +141,14 @@ like the i386 can represent the same physical machine location with
 different segment and offset pairs.  Identifying aliases is an 
 implementation issue.)
 
+\needlines{6}
 \subsection{Operating System Independence}
 DWARF is widely associated with SVR4 Unix and similar operating 
 systems like BSD and Linux.  DWARF fits well with the section 
 organization of the ELF object file format. Nonetheless, DWARF 
 attempts to be independent of either the OS or the object file 
 format.  There have been implementations of DWARF debugging 
-data in OMF or COFF object files. 
+data in COFF, Mach-O and other object file formats. 
 
 DWARF assumes that any object file format will be able to 
 distinguish the various DWARF data sections in some fashion, 
@@ -157,9 +156,8 @@ preferably by name.
 
 DWARF makes a few assumptions about functionality provided by 
 the underlying operating system.  DWARF data sections can be 
-read sequentially and independently, for example, to read the 
-\dotdebugabbrev{} section before the \dotdebuginfo{} section.  
-Each DWARF data section is a sequential sequence of 8-bit bytes, 
+read sequentially and independently.
+Each DWARF data section is a sequence of 8-bit bytes, 
 numbered starting with zero.  The presence of offsets from one 
 DWARF data section into other data sections does not imply that 
 the underlying OS must be able to position files randomly; a 
@@ -167,11 +165,7 @@ data section could be read sequentially and indexed using the offset.
 
 \subsection{Compact Data Representation} 
 The DWARF description is designed to be a compact file-oriented 
-representation. In most cases, it is anticipated that DWARF 
-debug data will be read by a consumer (usually a debugger) and 
-onverted into a more efficiently accessed internal representation.  
-For the most part, the DWARF data in a section is not the same as 
-this internal representation. 
+representation. 
 
 There are several encodings which achieve this goal, such as the 
 TAG and attribute abbreviations or the line number encoding.  
@@ -187,10 +181,13 @@ which allow a consumer to find DWARF data in files other than
 the executable, or the type units, which allow similar type 
 definitions from multiple compilations to be combined. 
 
-There is a tension between this objective and the following 
-objective. Every compaction scheme results in more processing 
-which needs to be performed to process the DWARF debug data. 
+In most cases, it is anticipated that DWARF 
+debug data will be read by a consumer (usually a debugger) and 
+converted into a more efficiently accessed internal representation.  
+For the most part, the DWARF data in a section is not the same as 
+this internal representation.
 
+\needlines{4}
 \subsection{Efficient Processing} 
 DWARF is designed to be processed efficiently, so that a 
 producer (a compiler) can generate the debug descriptions 
@@ -208,13 +205,16 @@ the possible implementations.
 DWARF attempts to allow developers the greatest flexibility 
 in designing implementations, without mandating any particular 
 design decisions. Issues which can be described as 
-\doublequote{Quality of Implementation} are avoided.
+quality-of-implementation are avoided.
 
-\subsection{Explicit rather than Implicit Description}
+\subsection{Explicit Rather Than Implicit Description}
 DWARF describes the source to object translation explicitly 
 rather than using common practice or convention as an implicit 
 understanding between producer and consumer.  For example, where 
 other debugging formats assume that a debugger knows how to 
+\bb
+virtually 
+\eb
 unwind the stack, moving from one stack frame to the next using 
 implicit knowledge about the architecture or operating system, 
 DWARF makes this explicit in the Call Frame Information description.
@@ -224,15 +224,15 @@ DWARF has a goal of describing characteristics of a program once,
 rather than repeating the same information multiple times.  The 
 string sections can be compacted to eliminate duplicate strings, 
 for example.  Other compaction schemes or references between 
-ections support this. Whether a particular implementation is 
+sections support this. Whether a particular implementation is 
 effective at eliminating duplicate data, or even attempts to, 
-is a Quality of Implementation issue.  
+is a quality-of-implementation issue.  
 
 \subsection{Leverage Other Standards}
 Where another standard exists which describes how to interpret 
 aspects of a program, DWARF defers to that standard rather than 
 attempting to duplicate the description.  For example, C++ has 
-pecific rules for deciding which function to call depending 
+specific rules for deciding which function to call depending 
 name, scope, argument types, and other factors.  DWARF describes 
 the functions and arguments, but doesn't attempt to describe 
 how one would be selected by a consumer performing any particular 
@@ -245,13 +245,15 @@ without requiring additional functionality specifically to
 support DWARF data.  This may require the implementer to be 
 careful that they do not generate DWARF data which cannot be 
 processed by these programs.  Conversely, an assembler which 
-can generate LEB128 values may allow the compiler to generate 
+can generate LEB128 (Little-Endian Base 128) 
+values may allow the compiler to generate 
 more compact descriptions, and a linker which understands the 
 format of string sections can merge these sections.  Whether 
-or not an implementation includes these functions is a Quality 
-of Implementation issue, not mandated by the DWARF specification.
+or not an implementation includes these functions is a 
+quality-of-implementation issue, not mandated by the DWARF 
+specification.
 
-\subsection{Separate Description from Implementation}
+\subsection{Separate Description From Implementation}
 DWARF intends to describe the translation of a program from 
 source to object, while neither mandating any particular design 
 nor making any other design difficult.  For example, DWARF 
@@ -259,24 +261,43 @@ describes how the arguments and local variables in a function
 are to be described, but doesn't specify how this data is 
 collected or organized by a producer.  Where a particular DWARF 
 feature anticipates that it will be implemented in a certain 
-fashion, non-normative text will suggest but not require this design.
-
-\subsection{Permissive rather than Prescriptive}
-The DWARF Standard specifies the meaning of DWARF descriptions.  
-It does not specify what a particular producer should generate 
-for any source to object conversion, nor what a particular 
-consumer should do with this description.  DWARF is permissive, 
-allowing different producer to generate different descriptions 
-for the same source to object conversion.  As long as the DWARF 
-description follows this specification, the producer is 
-generating valid DWARF.
-For example, DWARF allows producers to identify the end of a 
-function prologue in the Line Information so that a debugger 
-can stop at this location.  A producer which does this is 
-generating valid DWARF, as is another which doesn't.  
+fashion, informative text will suggest but not require this design.
 
-\subsection{Vendor Extensibility}
+\subsection{Permissive Rather Than Prescriptive}
+\bb
+The DWARF Standard specifies the meaning of DWARF descriptions. It does not
+specify in detail what a particular producer should generate for any source to
+object conversion.  One producer may generate a more complete description
+than another, it may describe features in a different order (unless the 
+standard explicitly requires a particular order), or it may use
+different abbreviations or compression methods.  Similarly, DWARF does not
+specify exactly what a particular consumer should do with each part of the
+description, although we believe that the potential uses for each description
+should be evident.
+
+DWARF is permissive, allowing different producers to generate different
+descriptions for the same source to object conversion, and permitting
+different consumers to provide more or less functionality or information
+to the user.  This may result in debugging information being larger or
+smaller, compilers or debuggers which are faster or slower, and more or
+less functional.  These are described as differences in "Quality of
+Implementation".
+
+Each producer conforming to the DWARF standard must follow the format and
+meaning as specified in the standard.  As long as the DWARF description
+generated follows this specification, the producer is generating valid DWARF.
+For example, DWARF allows a producer to identify the end of a function
+prologue in the Line Information so that a debugger can stop at this location.
+A producer which does this is generating valid DWARF, as is another which
+doesn't.  As another example, one producer may generate descriptions
+for variables which are moved from memory to a register in a certain range,
+while another may only describe the variable's location in memory.  Both are
+valid DWARF descriptions, while a consumer using the former would be able
+to provide more accurate values for the variable while executing in that
+range than a consumer using the latter.
 \eb
+
+\subsection{Vendor Extensibility}
 This document does not attempt to cover all interesting
 languages or even to cover all of the possible debugging
 information needs for its primary target languages. 
@@ -292,13 +313,10 @@ debugging information entries and attributes defined here in
 new situations. 
 Future versions of this document will not use
 names or values reserved for vendor specific additions. 
-All
-names and values not reserved for vendor additions, however,
+All names and values not reserved for vendor additions, however,
 are reserved for future versions of this document.
 
-\bb
 Where this specification provides a means for
-\eb
 describing the source language, implementors are expected
 to adhere to that specification. 
 For language features that
@@ -310,27 +328,29 @@ to be compatible with this specification in the absence of
 those extensions.
 
 The DWARF format is organized so that a consumer can skip over
-data which it does not recognize. 
-This may allow a consumer
+data which it does not recognize. This may allow a consumer
 to read and process files generated according to a later
 version of this standard or which contain vendor extensions,
 albeit possibly in a degraded manner.
 
-\section{Changes from Version 4 to Version 5}
+\section{Changes From Version 4 to Version 5}
 \addtoindexx{DWARF Version 5}
-The following is a list of the major changes made to the DWARF Debugging Information
-Format since Version 4 was published. The list is not meant to be exhaustive.
+The following is a list of the major changes made to the 
+DWARF Debugging Information Format since Version 4 was published. 
+The list is not meant to be exhaustive.
 \begin{itemize}
 \item The \dotdebugtypes{}
 %\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (Version 4)}
 section introduced in \DWARFVersionIV{} 
-is eliminated and its contents instead contained in \dotdebuginfo{} sections
-to facilitate other changes.
-\item Add support for collecting common DWARF information (DIEs and macro definitions)
+is eliminated and its contents instead contained in \dotdebuginfo{} sections.
+\item Add support for collecting common DWARF information 
+(debugging information entries and macro definitions)
 across multiple executable and shared files and keeping it in a single
 \addtoindex{supplementary object file}.
-\item A new line number program header design provides the ability to 
-use an MD5 hash to validate source file version in use, allows pooling 
+\needlines{6}
+\item A new line number program header format 
+provides the ability to use an MD5 hash to validate 
+the source file version in use, allows pooling 
 of directory and file name strings and makes provision for vendor-defined
 extensions. It also adds a string section specific to the line number table 
 (\dotdebuglinestr)
@@ -338,35 +358,35 @@ to properly support the common practice of stripping all DWARF sections
 except for line number information.
 \needlines{4}
 \item Add a split object file and package representations to allow most 
-DWARF information to be compacted and/or kept separate from an executable 
+DWARF information to be kept separate from an executable 
 or shared image. This includes new sections 
 \dotdebugaddr, \dotdebugstroffsets, \dotdebugabbrevdwo, \dotdebuginfodwo, 
 \dotdebuglinedwo, \dotdebuglocdwo, \dotdebugmacrodwo, \dotdebugstrdwo,
 \dotdebugstroffsetsdwo, \dotdebugcuindex{} and \dotdebugtuindex{} 
 together with new forms of attribute value for referencing these sections.
-This enhances DWARF support for very large programs by saving space 
-and improving link times.
+This enhances DWARF support by reducing executable program size and
+by improving link times.
 \item Replace the \dotdebugmacinfo{} macro information representation with
-a much more compact \dotdebugmacro{} representation.
+with a \dotdebugmacro{} representation that can potentially be much more compact.
+
 \item Replace the \dotdebugpubnames{} and \dotdebugpubtypes{} sections
 with a single and more functional name index section, \dotdebugnames{}.
-\item Add a new debugging information entry (\DWTAGcallsiteNAME) and related 
+\item Add a new debugging information entry (\DWTAGcallsiteNAME), related 
 attributes and DWARF expression operators to describe call site information, 
 including identification of tail calls and tail recursion.
-This facilitates debugging of optimized code.
 \item Add improved support for \addtoindex{FORTRAN} assumed rank arrays 
 (\DWTAGgenericsubrangeNAME), dynamic rank arrays (\DWATrankNAME)
 and co-arrays (\DWTAGcoarraytypeNAME{}).
-\item Add a new option to allow debuggers and other DWARF consumers to
-support a DWARF expression stack containing typed values.
-\item Add improved support for the \addtoindex{C++} \texttt{auto}
-return type, deleted member functions (\DWATdeletedNAME), as well as defaulted 
-constructors and destructors (\DWATdefaultedNAME).
-\item Add a new attribute, \DWATnoreturnNAME{}, to identify 
+\item Add new operations that allow support for 
+a DWARF expression stack containing typed values.
+\item Add improved support for the \addtoindex{C++}:
+\texttt{auto} return type, deleted member functions (\DWATdeletedNAME), 
+as well as defaulted constructors and destructors (\DWATdefaultedNAME).
+\item Add a new attribute (\DWATnoreturnNAME{}), to identify 
 a subprogram that does not return to its caller.
 \item Add language codes for C 2011, C++ 2003, C++ 2011, C++ 2014,
 Dylan, Fortran 2003, Fortran 2008, Go, Haskell, 
-Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
+Julia, Modula 3, Ocaml, OpenCL, Rust and Swift.
 \item Numerous other more minor additions to improve functionality
 and performance.
 \end{itemize}
@@ -377,22 +397,22 @@ DWARF Version 5 is compatible with DWARF Version 4 except as follows:
 a new \HFNunittype{} field.
 \needlines{4}
 \item New operand forms for attribute values are defined 
-(\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME, 
+(\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMimplicitconstNAME, 
+\DWFORMlinestrpNAME, 
 \DWFORMrefsupNAME, \DWFORMstrpsupNAME{} and \DWFORMstrxNAME).
-(Because a pre-DWARF Version 5 consumer will not be able to interpret 
-these even to ignore and skip over them, such new forms must be 
-considered incompatible.)
-\item The line number table header (in the \dotdebugline{} section) 
-is substantially revised.
+
+\textit{Because a pre-DWARF Version 5 consumer will not be able to interpret 
+these even to ignore and skip over them, new forms must be 
+considered incompatible additions.}
+\item The line number table header is substantially revised.
 \needlines{4}
-\item A location list entry (see Section \refersec{chap:locationlists}) 
+\item A location list entry 
 with the address range \mbox{(0, \textit{maximum-address})} is defined 
 as the new default location list entry.
-\item In a string type (see Section \refersec{chap:stringtypeentries}), 
-a \DWATbytesizeNAME{} attribute is defined to always describe the size 
-of the string type. (Previously
-it described the size of the optional string length data field if the 
-\DWATstringlengthNAME{} attribute was present.)
+\item In a string type, the \DWATbytesizeNAME{} attribute is re-defined 
+to always describe the size of the string type. 
+(Previously it described the size of the optional string length data 
+field if the \DWATstringlengthNAME{} attribute was also present.)
 \end{itemize}
 
 While not strictly an incompatibility, the macro information