Working update reflecting many changes based on full
[dwarf-doc.git] / dwarf5 / latexdoc / introduction.tex
index e0948e7..84132a7 100644 (file)
@@ -4,10 +4,8 @@
 This document defines a format for describing programs to
 facilitate user source level debugging. This description
 can be generated by compilers, assemblers and linkage
-editors. 
-It can be used by debuggers and other tools. 
-The
-debugging information format does not favor the design of any
+editors. It can be used by debuggers and other tools. 
+The debugging information format does not favor the design of any
 compiler or debugger. 
 Instead, the goal is to create a method
 of communicating an accurate picture of the source program
@@ -37,10 +35,10 @@ believed to cover most debugging information needs of
 and \addtoindex{Fortran}; it also covers the basic needs
 of various other languages.
 
-This document describes \addtoindex{DWARF Version 4},
-the fourth generation
-of debugging information based on the DWARF format. DWARF
-Version 4 extends \addtoindex{DWARF Version 3}
+This document describes \DWARFVersionV,
+the fifth generation
+of debugging information based on the DWARF format. 
+\DWARFVersionV{} extends \DWARFVersionIV{}
 in a compatible manner.
 
 The intended audience for this document is the developers
@@ -77,10 +75,9 @@ contained outside of the debugging information entries. The
 encoding of the DWARF information is presented in 
 Section \ref{datarep:datarepresentation}.
 
-This organization closely follows that used in the DWARF
-Version 3 document. Except where needed to incorporate
-new material or to correct errors, the 
-\addtoindex{DWARF Version 3}
+This organization closely follows that used in the 
+\DWARFVersionIV{} document. Except where needed to incorporate
+new material or to correct errors, the \DWARFVersionIV{}
 text is generally reused in this document with little or
 no modification.
 
@@ -163,18 +160,19 @@ This enhances DWARF support for very large programs by saving space
 and improving link times.
 \item Replace the \dotdebugmacinfo{} macro information representation with
 a much more compact \dotdebugmacro{} representation.
-\item Replace the \dotdebugpubnames{} and \dotdebugtypes{} section
+\item Replace the \dotdebugpubnames{} and \dotdebugtypes{} sections
 with a single and more functional name index section, \dotdebugnames{}.
 \item Add a new debugging information entry, related attributes and
 DWARF expression operators, to describe call information, 
 including identification of tail calls and tail recursion.
-This facilitates debugging optimized code.
+This facilitates debugging of optimized code.
 \item Add a new attribute, \DWATnoreturnNAME{}, to identify 
 a subprogram that does not return to its caller.
 \item Add a new attribute, \DWATrankNAME{}, to describe the 
 dimensionality of an array with dynamic rank.
 \item Add a new tag, \DWTAGgenericsubrangeNAME{}, to describe the
 bounds of Fortran assumed-rank arrays.
+\item Add a new tag, \DWTAGcoarraytypeNAME{}, to describe Fortran co-arrays.
 \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.
@@ -186,17 +184,19 @@ DWARF Version 5 is compatible with DWARF Version 4 except as follows:
 \begin{itemize}
 \item The line number table header is substantially revised.
 \item New operand forms for attribute values are defined 
-(\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME, \DWFORMrefsupNAME, 
-\DWFORMstrpNAME, \DWFORMstrpsupNAME, \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 A location list entry (see Section \refersec{chap:locationlists}) with 
-the address range \mbox{(0, \doublequote{-1})} 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.)
+(\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME, 
+\DWFORMrefsupNAME, \DWFORMstrpsupNAME, \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 A location list entry (see Section \refersec{chap:locationlists}) 
+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.)
 \end{itemize}
 
 While not strictly an incompatibility, the macro information 
@@ -206,24 +206,29 @@ representation. While the two representations cannot both be
 used in the same compilation unit, they can co-exist in 
 executable or shared images.
 
+Similar comments apply to replacement of the \dotdebugpubnames{} 
+and \dotdebugpubtypes{} sections with the new \dotdebugnames{} 
+section.
+
 \needlines{4}
 \section{Changes from Version 3 to Version 4}
 \addtoindexx{DWARF Version 4}
-The following is a list of the major changes made to the DWARF Debugging Information
-Format since Version 3 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 3 was 
+published. The list is not meant to be exhaustive.
 \begin{itemize}
 \item Reformulate 
 Section 2.6 (Location Descriptions) 
 to better distinguish DWARF location descriptions, which
-compute the location where a value is found (such as an address in memory or a register
-name) from DWARF expressions, which compute a final value (such as an array bound).
-\item Add support for bundled instructions on machine architectures where instructions do not
-occupy a whole number of bytes.
-\item Add a new attribute form for 
-section offsets, \DWFORMsecoffsetNAME
-\addtoindexx{section offset}
-to replace the use
-of \DWFORMdatafourNAME{} and \DWFORMdataeightNAME{} for section offsets.
+compute the location where a value is found (such as an 
+address in memory or a register name) from DWARF expressions, 
+which compute a final value (such as an array bound).
+\item Add support for bundled instructions on machine architectures 
+where instructions do not occupy a whole number of bytes.
+\item Add a new attribute form for section offsets
+\DWFORMsecoffsetNAME,\addtoindexx{section offset}
+to replace the use of 
+\DWFORMdatafourNAME{} and \DWFORMdataeightNAME{} for section offsets.
 \item Add an attribute, \DWATmainsubprogramNAME, to identify the main subprogram of a
 program.
 \item Define default array lower bound values for each supported language.