Incorporate Issue 130313.5, Add support for Fortran assumed-rank arrays.
[dwarf-doc.git] / dwarf5 / latexdoc / introduction.tex
index c736270..f1a17f0 100644 (file)
@@ -1,5 +1,6 @@
 \chapter{Introduction}
 \label{chap:introduction}
+\pagenumbering{arabic}
 This document defines a format for describing programs to
 facilitate user source level debugging. This description
 can be generated by compilers, assemblers and linkage
@@ -11,7 +12,8 @@ compiler or debugger.
 Instead, the goal is to create a method
 of communicating an accurate picture of the source program
 to any debugger in a form that is extensible to different
-languages while retaining compatibility.  
+languages while retaining compatibility.
+  
 The design of the
 debugging information format is open-ended, allowing for
 the addition of new debugging information to accommodate new
@@ -46,8 +48,8 @@ of both producers and consumers of debugging information,
 typically compilers, debuggers and other tools that need to
 interpret a binary program in terms of its original source.
 
-\section{Overview}
 
+\section{Overview}
 
 There are two major pieces to the description of the DWARF
 format in this document. The first piece is the informational
@@ -56,24 +58,24 @@ way the debugging information is encoded and represented in
 an object file.
 
 The informational content is described in 
-Sections \refersec{chap:generaldescription} 
+Sections \ref{chap:generaldescription} 
 through
-\refersec{chap:otherdebugginginformation}. 
-Section  \refersec{chap:generaldescription}
+\ref{chap:otherdebugginginformation}. 
+Section  \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 \refersec{chap:programscopeentries}, 
-\refersec{chap:dataobjectandobjectlistentries} and 
-\refersec{chap:typeentries} describe
+Sections \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 \refersec{chap:otherdebugginginformation} 
+Section \ref{chap:otherdebugginginformation} 
 describes debugging information
 contained outside of the debugging information entries. The
 encoding of the DWARF information is presented in 
-Section \refersec{datarep:datarepresentation}.
+Section \ref{datarep:datarepresentation}.
 
 This organization closely follows that used in the DWARF
 Version 3 document. Except where needed to incorporate
@@ -83,7 +85,7 @@ text is generally reused in this document with little or
 no modification.
 
 In the following sections, text in normal font describes
-required aspects of the DWARF format.  Text in italics is
+required aspects of the DWARF format.  Text in \textit{italics} is
 explanatory or supplementary material, and not part of the
 format definition itself. The several appendices consist only
 of explanatory or supplementary material, and are not part
@@ -129,14 +131,35 @@ 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 Version 3 to 4]{Changes from Version 3 to Version 4}
+\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 3 was published. The list is not meant to be exhaustive.
+Format since Version 4 was published. The list is not meant to be exhaustive.
+\begin{itemize}
+\item TBD...
+\item Added a new attribute, \DWATrank{}, to describe the dimensionality of
+an array.
+\item Added a new tag, \DWTAGgenericsubrange{}, to describe the
+bounds of Fortran assumed-rank arrays.
 
+\end{itemize}
 
+DWARF Version 5 is compatible with DWARF Version 4 except as follows:
 \begin{itemize}
+\item A location list entry (see Section \refersec{chap:locationlists}) with 
+the address range (0, \doublequote{-1}) is defined as the new default location 
+list entry.
+\item In a string type (see Section \refersec{chap:stringtypeentries}, a \DWATbytesize{}
+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 \DWATstringlength{}
+attribute was present.)
+\end{itemize}
 
+\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.
+\begin{itemize}
 \item Reformulate 
 Section 2.6 (Location Descriptions) 
 to better distinguish DWARF location descriptions, which
@@ -145,11 +168,11 @@ name) from DWARF expressions, which compute a final value (such as an array boun
 \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, \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}, 
+section offsets, \livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}, 
 \addtoindexx{section offset}
 to replace the use
-of \livelink{chap:DWFORMdata4}{DW\-\_FORM\-\_data4} and \livelink{chap:DWFORMdata8}{DW\-\_FORM\-\_data8} for section offsets.
-\item Add an attribute, \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}, to identify the main subprogram of a
+of \livelink{chap:DWFORMdata4}{DW\_FORM\_data4} and \livelink{chap:DWFORMdata8}{DW\_FORM\_data8} for section offsets.
+\item Add an attribute, \livelink{chap:DWATmainsubprogram}{DW\_AT\_main\_subprogram}, to identify the main subprogram of a
 program.
 \item Define default array lower bound values for each supported language.
 \item Add a new technique using separate type units, type signatures and COMDAT sections to
@@ -161,8 +184,10 @@ constant expressions, Unicode character types and template aliases.
 \item Add additional support for template parameters in instantiations.
 \item Add support for strongly typed enumerations in languages (such as C++) that have two
 kinds of enumeration declarations.
+\end{itemize}
 \addtoindex{DWARF Version 4} is compatible with 
 \addtoindex{DWARF Version 3} except as follows:
+\begin{itemize}
 \item DWARF attributes that use any of the new forms of attribute value representation (for
 section offsets, flag compression, type signature references, and so on) cannot be read by
 \addtoindex{DWARF Version 3}
@@ -172,80 +197,68 @@ unexpected form of data.
 and interpretation of other data in the section.
 \end{itemize}
 
-
-Contents needed.
 \section{Changes from Version 2 to Version 3}
+\addtoindexx{DWARF Version 3}
 The following is a list of the major differences between
 Version 2 and Version 3 of the DWARF Debugging Information
 Format. The list is not meant to be exhaustive.
-
 \begin{itemize}
 \item
 Make provision for DWARF information files that are larger
 than 4 GBytes.
-
 \item
 Allow attributes to refer to debugging information entries
 in other shared libraries.
-
 \item
 Add support for \addtoindex{Fortran 90} modules as well as allocatable
 array and pointer types.
-
 \item
 Add additional base types for \addtoindex{C} (as revised for 1999).
-
 \item
 Add support for \addtoindex{Java} and \addtoindex{COBOL}.
-
 \item
 Add namespace support for \addtoindex{C++}.
-
 \item
 Add an optional section for global type names (similar to
 the global section for objects and functions).
-
 \item
-Adopt UTF-8 as the preferred representation of program name strings.
+Adopt \addtoindex{UTF-8} as the preferred representation of program name strings.
 \item
 Add improved support for optimized code (discontiguous
 scopes, end of prologue determination, multiple section
 code generation).  
-
 \item Improve the ability to eliminate
 duplicate DWARF information during linking.  
-
 \end{itemize}
 
 \addtoindex{DWARF Version 3}
 is compatible with 
 \addtoindex{DWARF Version 2} except as follows:
-
 \begin{itemize}
 \item
 Certain very large values of the initial length fields that
 begin DWARF sections as well as certain structures are reserved
 to act as escape codes for future extension; one such extension
 is defined to increase the possible size of DWARF descriptions
-(see Section 7.4).
-
+(see Section \refersec{datarep:32bitand64bitdwarfformats}).
 \item
-References that use the attribute form \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr}
+References that use the attribute form 
+\livelink{chap:DWFORMrefaddr}{DW\_FORM\_ref\_addr}
 are specified to be four bytes in the DWARF 32-bit format and
 eight bytes in the DWARF 64-bit format, while 
 \addtoindex{DWARF Version 2} 
 specifies that such references have the same size as an
-address on the target system (see Sections 7.4 and 7.5.4).
-
+address on the target system (see Sections 
+\refersec{datarep:32bitand64bitdwarfformats} and 
+\refersec{datarep:attributeencodings}).
 \item
 The return\_address\_register field in a Common Information
 Entry record for call frame information is changed to unsigned
-LEB representation (see Section 6.4.1).
-
+LEB representation (see Section 
+\refersec{chap:structureofcallframeinformation}).
 \end{itemize}
 
-
-\section[Changes Version1 to 2]{Changes from Version 1 to Version 2}
+\section{Changes from Version 1 to Version 2}
 \addtoindex{DWARF Version 2} 
 describes the second generation of debugging
 information based on the DWARF format. While 
@@ -271,15 +284,13 @@ Version 2 DWARF information is not binary compatible with
 Version 1 information. To make it easier for consumers to
 support both Version 1 and Version 2 DWARF information, the
 Version 2 information has been moved to a different object
-file section, \addtoindex{.debug\_info}.  
+file section, \dotdebuginfo{}.  
 
 \textit{
-A summary of the major changes
-made in 
+A summary of the major changes made in 
 \addtoindex{DWARF Version 2}
-compared to the DWARF Version 1 may
-be found in the 
+compared to the DWARF Version 1 may be found in the 
 \addtoindex{DWARF Version 2}
-document
+document.
 }