Bring document up to date with September 2014 meeting.
authorRon Brender <ron.brender@gmail.com>
Thu, 25 Sep 2014 14:15:55 +0000 (10:15 -0400)
committerRon Brender <ron.brender@gmail.com>
Thu, 25 Sep 2014 14:15:55 +0000 (10:15 -0400)
Signed-off-by: Ron Brender <ron.brender@gmail.com>
14 files changed:
dwarf5/latexdoc/attributesbytag.tex
dwarf5/latexdoc/changesummary.tex
dwarf5/latexdoc/datarepresentation.tex
dwarf5/latexdoc/debugsectionrelationships.tex
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/dwarfnamecmds.tex
dwarf5/latexdoc/examples.tex
dwarf5/latexdoc/generaldescription.tex
dwarf5/latexdoc/introduction.tex
dwarf5/latexdoc/otherdebugginginformation.tex
dwarf5/latexdoc/programscope.tex
dwarf5/latexdoc/sectionversionnumbers.tex
dwarf5/latexdoc/splitobjects.tex
dwarf5/latexdoc/typeentries.tex

index 25a112b..1b04deb 100644 (file)
@@ -50,6 +50,7 @@ means include all three of the
 &\livelink{chap:DECL}{DECL} \\
 &\DWATabstractorigin{} \\
 &\DWATaccessibility{} \\
+&\DWATalignment{} \\
 &\DWATallocated{} \\
 &\DWATassociated{} \\
 &\DWATbitsize{} \\
@@ -70,12 +71,14 @@ means include all three of the
 \hline
 \DWTAGatomictype
 &\livelink{chap:DECL}{DECL} \\*
+&\DWATalignment{} \\*
 &\DWATsibling{} \\*
 &\DWATtype{} \\*
 
 \hline
 \DWTAGbasetype
 &\livelink{chap:DECL}{DECL} \\
+&\DWATalignment{} \\
 &\DWATallocated{} \\
 &\DWATassociated{} \\
 &\DWATbinaryscale{} \\
@@ -122,19 +125,20 @@ means include all three of the
 \hline
 \DWTAGcatchblock
 &\livelink{chap:DECL}{DECL} \\*
-&\DWATabstractorigin{} \\
-&\DWATentrypc{} \\
+&\DWATabstractorigin{} \\*
+&\DWATentrypc{} \\*
 &\DWAThighpc{} \\
 &\DWATlowpc{} \\
-&\DWATranges{} \\
-&\DWATsegment{} \\
-&\DWATsibling{} \\
+&\DWATranges{} \\*
+&\DWATsegment{} \\*
+&\DWATsibling{} \\*
 
 \hline
 \DWTAGclasstype
 &\livelink{chap:DECL}{DECL} \\*
 &\DWATabstractorigin{} \\*
 &\DWATaccessibility{} \\*
+&\DWATalignment{} \\
 &\DWATallocated{} \\
 &\DWATassociated{} \\
 &\DWATbitsize{} \\
@@ -153,7 +157,8 @@ means include all three of the
 \DWTAGcoarraytype
 &\livelink{chap:DECL}{DECL} \\*
 &\DWATname{} \\*
-&\DWATdescription{} \\*
+&\DWATdescription{} \\
+&\DWATalignment{} \\*
 &\DWATsibling{} \\*
 &\DWATtype{} \\*
 
@@ -209,6 +214,7 @@ means include all three of the
 \hline
 \DWTAGconsttype
 &\livelink{chap:DECL}{DECL} \\*
+&\DWATalignment{} \\*
 &\DWATsibling{} \\*
 &\DWATtype{} \\*
 
@@ -236,7 +242,8 @@ means include all three of the
 \DWTAGdynamictype
 &\livelink{chap:DECL}{DECL} \\*
 &\DWATabstractorigin \\*
-&\DWATallocated \\*
+&\DWATalignment{} \\*
+&\DWATallocated \\
 &\DWATassociated \\
 &\DWATdatalocation \\
 &\DWATdescription \\
@@ -261,9 +268,10 @@ means include all three of the
 
 \hline
 \DWTAGenumerationtype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaccessibility{} \\*
+&\DWATalignment{} \\
 &\DWATallocated{} \\
 &\DWATassociated{} \\
 &\DWATbitsize{} \\
@@ -284,17 +292,18 @@ means include all three of the
 
 \hline
 \DWTAGenumerator
-&\livelink{chap:DECL}{DECL} \\
-&\DWATconstvalue{} \\
-&\DWATdescription{} \\
-&\DWATname{} \\
-&\DWATsibling{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATconstvalue{} \\*
+&\DWATdescription{} \\*
+&\DWATname{} \\*
+&\DWATsibling{} \\*
 
 \hline
 \DWTAGfiletype
 &\livelink{chap:DECL}{DECL} \\*
 &\DWATabstractorigin{} \\*
-&\DWATallocated{} \\*
+&\DWATalignment{} \\*
+&\DWATallocated{} \\
 &\DWATassociated{} \\
 &\DWATbitsize{} \\
 &\DWATbytesize{} \\
@@ -319,9 +328,9 @@ means include all three of the
 &\DWATlocation{} \\
 &\DWATname{} \\
 &\DWATsegment{} \\
-&\DWATsibling{} \\
-&\DWATtype{} \\
-&\DWATvariableparameter{} \\
+&\DWATsibling{} \\*
+&\DWATtype{} \\*
+&\DWATvariableparameter{} \\*
 
 \hline
 \DWTAGfriend
@@ -403,8 +412,9 @@ means include all three of the
 
 \hline
 \DWTAGinterfacetype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATaccessibility{} \\*
+&\DWATalignment{} \\*
 &\DWATdescription{} \\
 &\DWATname{} \\*
 &\DWATsibling{} \\*
@@ -497,6 +507,7 @@ means include all three of the
 \hline
 \DWTAGpackedtype
 &\livelink{chap:DECL}{DECL} \\*
+&\DWATalignment{} \\*
 &\DWATsibling{} \\*
 &\DWATtype{} \\*
 
@@ -526,14 +537,16 @@ means include all three of the
 \DWTAGpointertype
 &\livelink{chap:DECL}{DECL}  \\*
 &\DWATaddressclass{}  \\*
+&\DWATalignment{} \\*
 &\DWATsibling{} \\*
 &\DWATtype{} \\*
 
 \hline
 \DWTAGptrtomembertype
-&\livelink{chap:DECL}{DECL}  \\
-&\DWATabstractorigin{}  \\
-&\DWATaddressclass{}  \\
+&\livelink{chap:DECL}{DECL}  \\*
+&\DWATabstractorigin{}  \\*
+&\DWATaddressclass{}  \\*
+&\DWATalignment{} \\
 &\DWATallocated{}  \\
 &\DWATassociated{}  \\
 &\DWATcontainingtype{}  \\
@@ -550,12 +563,14 @@ means include all three of the
 \DWTAGreferencetype
 &\livelink{chap:DECL}{DECL} \\*
 &\DWATaddressclass{}  \\*
+&\DWATalignment{} \\*
 &\DWATsibling{} \\*
 &\DWATtype{} \\*
 
 \hline
 \DWTAGrestricttype
 &\livelink{chap:DECL}{DECL} \\*
+&\DWATalignment{} \\*
 &\DWATsibling{} \\*
 &\DWATtype{} \\*
 
@@ -564,14 +579,16 @@ means include all three of the
 \DWTAGrvaluereferencetype
 &\livelink{chap:DECL}{DECL}  \\*
 &\DWATaddressclass{}  \\*
+&\DWATalignment{} \\*
 &\DWATsibling{}  \\*
 &\DWATtype{}  \\*
 
 \hline
 \DWTAGsettype
-&\livelink{chap:DECL}{DECL}  \\
-&\DWATabstractorigin{}  \\
-&\DWATaccessibility{}  \\
+&\livelink{chap:DECL}{DECL}  \\*
+&\DWATabstractorigin{}  \\*
+&\DWATaccessibility{}  \\*
+&\DWATalignment{} \\
 &\DWATallocated{}  \\
 &\DWATassociated{}  \\
 &\DWATbitsize{}  \\
@@ -589,6 +606,7 @@ means include all three of the
 \DWTAGsharedtype
 &\livelink{chap:DECL}{DECL}  \\*
 &\DWATcount{}  \\*
+&\DWATalignment{} \\*
 &\DWATsibling{}  \\*
 &\DWATtype{}  \\*
 
@@ -596,7 +614,8 @@ means include all three of the
 \DWTAGstringtype
 &\livelink{chap:DECL}{DECL}  \\*
 &\DWATabstractorigin{}  \\*
-&\DWATaccessibility{}  \\*
+&\DWATalignment{} \\*
+&\DWATaccessibility{}  \\
 &\DWATallocated{}  \\
 &\DWATassociated{}  \\
 &\DWATbitsize{}  \\
@@ -614,9 +633,10 @@ means include all three of the
 
 \hline
 \DWTAGstructuretype
-&\livelink{chap:DECL}{DECL}  \\
-&\DWATabstractorigin{}  \\
-&\DWATaccessibility{}  \\
+&\livelink{chap:DECL}{DECL}  \\*
+&\DWATabstractorigin{}  \\*
+&\DWATaccessibility{}  \\*
+&\DWATalignment{} \\
 &\DWATallocated{}  \\
 &\DWATassociated{}  \\
 &\DWATbitsize{}  \\
@@ -635,8 +655,9 @@ means include all three of the
 \DWTAGsubprogram
 &\livelink{chap:DECL}{DECL}  \\*
 &\DWATabstractorigin{}  \\*
-&\DWATaccessibility{}  \\
+&\DWATaccessibility{}  \\*
 &\DWATaddressclass{}  \\
+&\DWATalignment{} \\
 &\DWATartificial{}  \\
 &\DWATcallingconvention{}  \\
 &\DWATdeclaration{}  \\
@@ -674,9 +695,10 @@ means include all three of the
 
 \hline
 \DWTAGsubrangetype
-&\livelink{chap:DECL}{DECL}  \\
-&\DWATabstractorigin{}  \\
-&\DWATaccessibility{}  \\
+&\livelink{chap:DECL}{DECL}  \\*
+&\DWATabstractorigin{}  \\*
+&\DWATaccessibility{}  \\*
+&\DWATalignment{} \\
 &\DWATallocated{}  \\
 &\DWATassociated{}  \\
 &\DWATbitsize{}  \\
@@ -697,10 +719,11 @@ means include all three of the
 
 \hline
 \DWTAGsubroutinetype
-&\livelink{chap:DECL}{DECL}  \\
-&\DWATabstractorigin{}  \\
-&\DWATaccessibility{}  \\
+&\livelink{chap:DECL}{DECL}  \\*
+&\DWATabstractorigin{}  \\*
+&\DWATaccessibility{}  \\*
 &\DWATaddressclass{}  \\
+&\DWATalignment{} \\
 &\DWATallocated{}  \\
 &\DWATassociated{}  \\
 &\DWATdatalocation{}  \\
@@ -753,8 +776,9 @@ means include all three of the
 
 \hline
 \DWTAGthrowntype
-&\livelink{chap:DECL}{DECL}   \\
-&\DWATallocated{}   \\
+&\livelink{chap:DECL}{DECL}   \\*
+&\DWATalignment{} \\*
+&\DWATallocated{}   \\*
 &\DWATassociated{}   \\
 &\DWATdatalocation{}   \\
 &\DWATsibling{}   \\
@@ -776,6 +800,7 @@ means include all three of the
 &\livelink{chap:DECL}{DECL}   \\*
 &\DWATabstractorigin{}   \\*
 &\DWATaccessibility{}   \\*
+&\DWATalignment{} \\
 &\DWATallocated{}   \\
 &\DWATassociated{}   \\
 &\DWATdatalocation{}   \\
@@ -796,9 +821,10 @@ means include all three of the
 
 \hline
 \DWTAGuniontype
-&\livelink{chap:DECL}{DECL}   \\
-&\DWATabstractorigin{}   \\
-&\DWATaccessibility{}   \\
+&\livelink{chap:DECL}{DECL}   \\*
+&\DWATabstractorigin{}   \\*
+&\DWATaccessibility{}   \\*
+&\DWATalignment{} \\
 &\DWATallocated{}   \\
 &\DWATassociated{}   \\
 &\DWATbitsize{}   \\
@@ -828,9 +854,10 @@ means include all three of the
 
 \hline
 \DWTAGvariable
-&\livelink{chap:DECL}{DECL}    \\
-&\DWATabstractorigin{}    \\
-&\DWATaccessibility{}    \\
+&\livelink{chap:DECL}{DECL}    \\*
+&\DWATabstractorigin{}    \\*
+&\DWATaccessibility{}    \\*
+&\DWATalignment{}     \\
 &\DWATartificial{}    \\
 &\DWATconstexpr{}    \\
 &\DWATconstvalue{}    \\
index 5a06287..7a6615c 100644 (file)
@@ -15,6 +15,8 @@ This change summary is included only in draft versions of this document.
 \begin{longtable}{ll}
 \textbf{Date}  & \textbf{Issue Incorporated or Other Change}   \\ \hline       \\
 \endhead
+9/25/2014       & 140724.1 (line number table header), pre-release cleanups \\
+9/23/2014       & 140528.1 (alignment attribute), 120604.1 (supplementary macro sections) \\
 8/22/2014       & Miscellaneous editorial corrections, indexing improvements \\
 7/22/2014       & Add items in Section 1.4, Changes from Version 4 to Version 5 \\
 7/21/2014       & Enable section numbers on pdf bookmarks \\
@@ -43,7 +45,7 @@ This change summary is included only in draft versions of this document.
 10/26/2013     & 130313.1 (indirect string table), 130313.2 (indirect address table),  \\
                & 130313.3 (ranges without relocations), 130313.4 (split objects) \\
 10/25/2013     & 130530.1 (MD5 wording), 131017.1 (\DWATentrypcNAME{} descriptions),   \\
-               & 130701.1 (MD5 digest for file names in line table), 100831.1 (implicit pointers)      \\
+               & 130701.1 (MD5 digest for filenames in line number table), 100831.1 (implicit pointers)        \\
 10/24/2013     & 130815.1 (template parameter refactoring)                                     \\
 10/23/2013     & 130722.1 (additional \DWATartificialNAME{} uses in Appendix A), \\
                & 120719.1 (constant \DWATentrypcNAME{} value),                                 \\
index f276437..7254016 100644 (file)
@@ -221,9 +221,10 @@ and includes the following:
 \item
 The line number tables, range tables, frame tables, and
 accelerated access tables, in the usual sections:
-\dotdebugline, \dotdebugranges, \dotdebugframe,
+\dotdebugline, \dotdebuglinestr, \dotdebugranges, \dotdebugframe,
 \dotdebugpubnames, \dotdebugpubtypes{} and \dotdebugaranges,
 respectively.
+\needlines{4}
 \item
 An address table, in the \dotdebugaddr{} section. This table
 contains all addresses and constants that require
@@ -277,7 +278,7 @@ units, in the \dotdebugabbrevdwo{} section.
 \item Location lists, in the \dotdebuglocdwo{} section.
 
 \item
-A skeleton line table (for the type units), in the
+A skeleton line number table (for the type units), in the
 \dotdebuglinedwo{} section (see 
 Section \refersec{chap:skeletoncompilationunitentries}).
 
@@ -516,6 +517,84 @@ words, with L columns and N rows, in row-major order. Each row in
 the array is indexed starting from 1 (row 0 of the table of
 offsets also serves as the key for the table of sizes).
 
+\subsection{DWARF Supplementary Object Files}
+\label{data:dwarfsupplemetaryobjectfiles}
+In order to minimize the size of debugging information, it is possible
+to move duplicate debug information entries, strings and macro entries from
+several executables or shared objects into a separate 
+\addtoindexi{\textit{supplementary object file}}{supplementary object file} by some
+post-linking utility; the moved entries and strings can be then referenced
+from the debugging information of each of those executables or shared objects.
+
+A DWARF supplementary object file is itself an object file, using the same object
+file format, byte order, and size as the corresponding application executables
+or shared libraries. It consists only of a file header, section table, and
+a number of DWARF debug information sections.  Both the supplementary object file
+and all the executables or shared objects that reference entries or strings in that
+file must contain a \dotdebugsup{} section that establishes the relationship.
+
+The \dotdebugsup section contains:
+\begin{enumerate}[1. ]
+\item \texttt{version} (uhalf) \\
+A 2-byte unsigned integer representing the version of the DWARF
+information for the compilation unit (see Appendix G). The
+value in this field is \versiondotdebugsup.
+
+\item \texttt{is\_supplementary} (ubyte) \\
+A 1-byte unsigned integer, which contains the value 1 if it is
+in the \addtoindex{supplementary object file} that other executables or 
+shared objects refer to, or 0 if it is an executable or shared object 
+referring to a supplemental object file file.
+
+\needlines{4}
+\item \texttt{sup\_filename} (null terminated filename string) \\
+If \texttt{is\_supplementary} is 0, this contains either an absolute 
+filename for the supplementary object file, or a filename relative to 
+the object file containing the \dotdebugsup{} section.  
+If \texttt{is\_supplementary} is 1, then \texttt{sup\_filename}
+is not needed and must be an empty string (a single nul byte).
+
+\needlines{4}
+\item \texttt{sup\_checksum\_len} (unsigned LEB128) \\
+Length of the following \texttt{sup\_checksum} field; 
+his value can be 0 if no checksum is provided.
+
+
+\item \texttt{sup\_checksum} (array of ubyte) \\
+Some checksum or cryptographic hash function of the \dotdebuginfo{}, 
+\dotdebugstr{} and \dotdebugmacro{} sections of the 
+\addtoindex{supplementary object file}, or some unique identifier
+which the implementation can choose to verify that the supplementary 
+section object file matches what the debug information in the executables 
+or shared objects expects.
+\end{enumerate}
+
+Debug information entries that refer to an executable's or shared
+object's addresses must \emph{not} be moved to supplementary files (the
+addesses will likely not be the same). Similarly,
+entries referenced from within locationexpressions or using loclistptr
+form attributes must not be moved.
+
+Executable or shared object compilation units can use
+\DWTAGimportedunit{} with \DWFORMrefsup{} form \DWATimport{} attribute
+to import entries from the supplementary object file, other \DWFORMrefsup{}
+attributes to refer to them and \DWFORMstrpsup{} form attributes to
+refer to strings that are used by debug information of multiple
+executables or shared objects.  Within the \addtoindex{supplementary object file}'s
+debugging sections, form \DWFORMrefsup{} or \DWFORMstrpsup{} should
+not be used, and all reference forms referring to some other sections
+refer to the local sections in the supplementary object file.
+
+In macro information, \DWMACROdefineindirectsup{} or
+\DWMACROundefindirectsup{} opcodes can refer to strings in the 
+\dotdebugstr section of the supplementary file, or \DWMACROtransparentincludesup{} 
+can refer to \dotdebugmacro section entries.  Within the 
+\dotdebugmacro{} section of a \addtoindex{supplementary object file}, 
+\DWMACROdefineindirect{} and \DWMACROundefindirect{}
+opcodes refer to the local \dotdebugstr{} section, not the one in
+the executable or shared object."
+
+
 \needlines{6}
 \section{32-Bit and 64-Bit DWARF Formats}
 \label{datarep:32bitand64bitdwarfformats}
@@ -603,13 +682,29 @@ of DWARF format as follows. For the 32\dash bit DWARF format,
 the value is a 32\dash bit unsigned integer; for the 64\dash bit DWARF
 format, the value is a 64\dash bit unsigned integer.
 \begin{center}
-\begin{tabular}{ll}
-Form & Role  \\ \hline
-\DWFORMrefaddr& offset in \dotdebuginfo{} \\
-\DWFORMsecoffset& offset in a section other than \\
-                                                                                       &\dotdebuginfo{} or \dotdebugstr{} \\
-\DWFORMstrp&offset in \dotdebugstr{} \\
-\DWOPcallref&offset in \dotdebuginfo{} \\
+\begin{tabular}{lp{6cm}}
+Form             & Role  \\ \hline
+\DWFORMlinestrp  & offset in \dotdebuglinestr \\
+\DWFORMrefaddr   & offset in \dotdebuginfo{} \\
+\DWFORMrefsup    & offset in \dotdebuginfo{} section of a \mbox{supplementary} object file \\
+                   \addtoindexx{supplementary object file}
+\DWFORMsecoffset & offset in a section other than \\
+                & \dotdebuginfo{} or \dotdebugstr{} \\
+\DWFORMstrp      & offset in \dotdebugstr{} \\
+\DWFORMstrpsup   & offset in \dotdebugstr{} section of a \mbox{supplementary} object file \\
+\DWOPcallref     & offset in \dotdebuginfo{} \\
+\end{tabular}
+\end{center}
+
+\needlines{5}
+\item Within the body of the \dotdebugline{} section, certain forms of content
+description depend on the choice of DWARF format as follows: for the
+32-bit DWARF format, the value is a 32-bit unsigned integer; for the
+64-bit DWARF format, the value is a 64-bit unsigned integer.
+\begin{center}
+\begin{tabular}{lp{6cm}}
+Form             & Role  \\ \hline
+\DWFORMlinestrp  & offset in \dotdebuglinestr
 \end{tabular}
 \end{center}
 
@@ -731,6 +826,7 @@ enumeration are shown in Table \refersec{tab:unitheaderunitkindencodings}.
 \end{longtable}
 \end{centering}
 
+\needlines{5}
 \subsubsection{Compilation Unit Header}
 \label{datarep:compilationunitheader}
 \begin{enumerate}[1. ]
@@ -1183,13 +1279,14 @@ debugging information entries or data bytes.
 
 \item \livelinki{chap:classconstant}{constant}{constant class} \\
 \livetarg{datarep:classconstant}{}
-There are six forms of constants. There are fixed length
-constant data forms for one, two, four and eight byte values
+There are seven forms of constants. There are fixed length
+constant data forms for one-, two-, four-, eight- and sixteen-byte values
 (respectively, 
 \DWFORMdataoneTARG, 
 \DWFORMdatatwoTARG, 
 \DWFORMdatafourTARG,
-and \DWFORMdataeightTARG). 
+\DWFORMdataeightTARG{} and
+\DWFORMdatasixteenTARG). 
 There are also variable length constant
 data forms encoded using LEB128 numbers (see below). Both
 signed (\DWFORMsdataTARG) and unsigned 
@@ -1199,8 +1296,9 @@ length constants are available
 \needlines{4}
 The data in \DWFORMdataone, 
 \DWFORMdatatwo, 
-\DWFORMdatafour{} and
-\DWFORMdataeight{} 
+\DWFORMdatafour{}, 
+\DWFORMdataeight{} and
+\DWFORMdatasixteen{} 
 can be anything. Depending on context, it may
 be a signed integer, an unsigned integer, a floating\dash point
 constant, or anything else. A consumer must use context to
@@ -1332,7 +1430,7 @@ attribute to allow more than one of these classes}
 \begin{itemize}
 \item \livelinki{chap:classreference}{reference}{reference class} \\
 \livetarg{datarep:classreference}{}
-There are three types of reference.
+There are four types of reference.
 
 The 
 \addtoindexx{reference class}
@@ -1368,7 +1466,9 @@ entry in a different shared object.  This type of reference
 (\DWFORMrefaddrTARG) 
 is an offset from the beginning of the
 \dotdebuginfo{} 
-section of the target executable or shared object;
+section of the target executable or shared object, or, for
+references within a \addtoindex{supplementary object file}, 
+an offset from the beginning of the local \dotdebuginfo{} section;
 it is relocatable in a relocatable object file and frequently
 relocated in an executable file or shared object. For
 references from one shared object or static executable file
@@ -1381,8 +1481,7 @@ unsigned value
 
 \textit{A debugging information entry that may be referenced by
 another compilation unit using 
-\DWFORMrefaddr{} must have a
-global symbolic name.}
+\DWFORMrefaddr{} must have a global symbolic name.}
 
 \textit{For a reference from one executable or shared object to
 another, the reference is resolved by the debugger to identify
@@ -1399,19 +1498,28 @@ reference (\DWFORMrefsigeightTARG) is the
 \addtoindexx{type signature}
 64\dash bit type signature 
 (see Section \refersec{datarep:typesignaturecomputation}) 
-that was computed
-for the type.
+that was computed for the type. 
+
+The fourth type of reference is a reference from within the 
+\dotdebuginfo{} section of the executable or shared object to
+a debugging information entry in the \dotdebuginfo{} section of 
+a \addtoindex{supplementary object file}.
+This type of reference (\DWFORMrefsupTARG) is an offset from the 
+beginning of the \dotdebuginfo{} section in the supplementary 
+object file.
 
 \textit{The use of compilation unit relative references will reduce the
 number of link\dash time relocations and so speed up linking. The
-use of the second and third type of reference allows for the
+use of the second, third and fourth type of reference allows for the
 sharing of information, such as types, across compilation
-units.}
+units, while the fourth type further allows for sharing of information 
+across compilation units from different executables or shared objects.}
 
 \textit{A reference to any kind of compilation unit identifies the
 debugging information entry for that unit, not the preceding
 header.}
 
+\needlines{4}
 \item \livelinki{chap:classstring}{string}{string class} \\
 \livetarg{datarep:classstring}{}
 A string is a sequence of contiguous non\dash null bytes followed by
@@ -1419,18 +1527,26 @@ one null byte.
 \addtoindexx{string class}
 A string may be represented: 
 \begin{itemize}
+\setlength{\itemsep}{0em}
 \item immediately in the debugging information entry itself 
 (\DWFORMstringTARG), 
+
 \item as an 
 \addtoindexx{section offset!in class string value}
 offset into a string table contained in
-the \dotdebugstr{} section of the object file 
-(\DWFORMstrpTARG).
+the \dotdebugstr{} section of the object file (\DWFORMstrpTARG), 
+the \dotdebuglinestr{} section of the object file (\DWFORMlinestrpTARG),
+or as an offset into a string table contained in the
+\dotdebugstr{} section of a \addtoindex{supplementary object file} 
+(\DWFORMstrpsupTARG).  \DWFORMstrpNAME{} offsets from the \dotdebuginfo{}  
+section of a \addtoindex{supplementary object file}
+refer to the local \dotdebugstr{} section of that same file.
 In the \thirtytwobitdwarfformat, the representation of a 
 \DWFORMstrpNAME{}
 value is a 4\dash byte unsigned offset; in the \sixtyfourbitdwarfformat,
 it is an 8\dash byte unsigned offset 
 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
+
 \item as an indirect offset into the string table using an 
 index into a table of offsets contained in the 
 \dotdebugstroffsets{} section of the object file (\DWFORMstrxTARG).
@@ -1446,11 +1562,14 @@ If the \DWATuseUTFeight{}
 \addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8} attribute is specified for the
 compilation, partial, skeleton or type unit entry, string values are encoded using the
 UTF\dash 8 (\addtoindex{Unicode} Transformation Format\dash 8) from the Universal
-Character Set standard (ISO/IEC 10646\dash 1:1993). Otherwise,
-the string representation is unspecified.
+Character Set standard (ISO/IEC 10646\dash 1:1993).
+\addtoindexx{ISO 10646 character set standard}
+Otherwise, the string representation is unspecified.
 
 \textit{The \addtoindex{Unicode} Standard Version 3 is fully compatible with
-ISO/IEC 10646\dash 1:1993. It contains all the same characters
+ISO/IEC 10646\dash 1:1993. 
+\addtoindexx{ISO 10646 character set standard}
+It contains all the same characters
 and encoding points as ISO/IEC 10646, as well as additional
 information about the characters and their use.}
 
@@ -1458,6 +1577,7 @@ information about the characters and their use.}
 of strings; for compatibility, this version also does
 not. However, the UTF\dash 8 representation is strongly recommended.}
 
+\needlines{4}
 \item \livelinki{chap:classstroffsetsptr}{stroffsetsptr}{stroffsetsptr class} \\
 \livetarg{datarep:classstroffsetsptr}{}
 This is an offset into the \dotdebugstroffsets{} section 
@@ -1789,6 +1909,8 @@ Table \refersec{tab:attributeformencodings}.
         \addtoindexx{call value attribute} \\
 \DWATnoreturn~\ddag &0x87 &\CLASSflag 
         \addtoindexx{noreturn attribute} \\
+\DWATalignment~\ddag &0x88 &\CLASSconstant 
+        \addtoindexx{alignment attribute} \\
 \DWATlouser&0x2000 & --- \addtoindexx{low user attribute encoding}  \\
 \DWAThiuser&\xiiifff& --- \addtoindexx{high user attribute encoding}  \\
 
@@ -1837,7 +1959,10 @@ Table \refersec{tab:attributeformencodings}.
 \DWFORMflagpresent{} &0x19&\livelink{chap:classflag}{flag} \\
 \DWFORMstrx{} \ddag &0x1a&\livelink{chap:classstring}{string} \\
 \DWFORMaddrx{} \ddag &0x1b&\livelink{chap:classaddress}{address} \\
-\DWFORMrefsigeight &0x20&\livelink{chap:classreference}{reference} \\
+\DWFORMrefsup{}~\ddag &0x1c &\livelink{chap:classreference}{reference} \\
+\DWFORMstrpsup{}~\ddag &0x1d &\livelink{chap:classstring}{string} \\
+\DWFORMdatasixteen~\ddag &0x1e &\CLASSconstant \\
+\DWFORMrefsigeight &0x20 &\livelink{chap:classreference}{reference} \\
 
 \end{longtable}
 \end{centering}
@@ -1926,7 +2051,7 @@ gives algorithms for encoding and decoding these forms.}
 127&127& ---\\
 128& 0 + 0x80 & 1 \\
 129& 1 + 0x80 & 1 \\
-130& 2 + 0x80 & 1 \\
+%130& 2 + 0x80 & 1 \\
 12857& 57 + 0x80 & 100 \\
 \end{longtable}
 \end{centering}
@@ -2777,6 +2902,7 @@ The encodings for the extended opcodes are given in
 \addtoindexx{line number opcodes!extended opcode encoding}
 Table \refersec{tab:linenumberextendedopcodeencodings}.
 
+\needlines{20}
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{l|c}
@@ -2787,14 +2913,14 @@ Table \refersec{tab:linenumberextendedopcodeencodings}.
 \endhead
   \hline \emph{Continued on next page}
 \endfoot
-  \hline \ddag~\textit{New in DWARF Version 5}
+  \hline %\ddag~\textit{New in DWARF Version 5}
 \endlastfoot
 
 \DWLNEendsequence      &0x01 \\
 \DWLNEsetaddress       &0x02 \\
-\DWLNEdefinefile       &0x03 \\
-\DWLNEsetdiscriminator &0x04 \\
-\DWLNEdefinefileMDfive~\ddag &0x05 \\
+\textit{Reserved}      &0x03\footnote{Code 0x03 is reserved to allow backward compatible support of the 
+                                       \texttt{DW\_LNE\_define\_file} operation which was defined prior to \DWARFVersionV.} \\
+\DWLNEsetdiscriminator  &0x04 \\
 \DWLNElouser           &0x80 \\
 \DWLNEhiuser           &\xff \\
 
@@ -2802,26 +2928,29 @@ Table \refersec{tab:linenumberextendedopcodeencodings}.
 \end{centering}
 
 \needspace{6cm}
-The encodings for the file entry format are given in 
+The encodings for the line number header entry formats are given in 
 \addtoindexx{line number opcodes!file entry format encoding}
-Table \refersec{tab:linenumberfileentryformatencodings}.
+Table \refersec{tab:linenumberheaderentryformatencodings}.
 
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{l|c}
-  \caption{Line number file entry format \mbox{encodings}} \label{tab:linenumberfileentryformatencodings}\\
-  \hline \bfseries File entry format name&\bfseries Value \\ \hline
+  \caption{Line number header entry format \mbox{encodings}} \label{tab:linenumberheaderentryformatencodings}\\
+  \hline \bfseries Line number header entry format name&\bfseries Value \\ \hline
 \endfirsthead
-  \bfseries File entry format name&\bfseries Value\\ \hline
+  \bfseries Line number header entry format name&\bfseries Value\\ \hline
 \endhead
   \hline \emph{Continued on next page}
 \endfoot
-  \hline
+  \hline \ddag~\textit{New in DWARF Version 5}
 \endlastfoot
-
-\DWLNFtimestampsize    & 0x01  \\
-\DWLNFMDfive           & 0x02  \\
-
+\DWLNCTpath~\ddag           & 0x1 \\
+\DWLNCTdirectoryindex~\ddag & 0x2 \\
+\DWLNCTtimestamp~\ddag      & 0x3 \\
+\DWLNCTsize~\ddag           & 0x4 \\
+\DWLNCTMDfive~\ddag         & 0x5 \\
+\DWLNCTlouser~\ddag         & 0x2000 \\
+\DWLNCThiuser~\ddag         & \xiiifff \\
 \end{longtable}
 \end{centering}
 
@@ -2835,13 +2964,14 @@ The source line numbers and source file indices encoded in the
 macro information section are represented as 
 unsigned LEB128\addtoindexx{LEB128!unsigned} numbers.
 
+\needlines{4}
 The macro information entry type is encoded as a single unsigned byte. 
 The encodings 
 \addtoindexx{macro information entry types!encoding}
 are given in 
 Table \refersec{tab:macroinfoentrytypeencodings}.
 
-\needlines{8}
+\needlines{10}
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{l|c}
@@ -2862,7 +2992,9 @@ Table \refersec{tab:macroinfoentrytypeencodings}.
 \DWMACROdefineindirect~\ddag      &0x05 \\
 \DWMACROundefindirect~\ddag       &0x06 \\
 \DWMACROtransparentinclude~\ddag  &0x07 \\
-\textit{Reserved}                 &0x08-0x0a \\
+\DWMACROdefineindirectsup~\ddag   &0x08 \\
+\DWMACROundefindirectsup~\ddag    &0x09 \\
+\DWMACROtransparentincludesup~\ddag&0x0a \\
 \DWMACROdefineindirectx~\ddag     &0x0b \\
 \DWMACROundefindirectx~\ddag      &0x0c \\
 \DWMACROlouser~\ddag              &0xe0 \\
@@ -2983,11 +3115,12 @@ DWARF format, this consists of the 4-byte value
 that gives the actual length (see 
 Section \refersec{datarep:32bitand64bitdwarfformats}).
 
-\needlines{4}
+%\needlines{4}
 \item  \texttt{version} (\addtoindex{uhalf}) \\
 A 2-byte version identifier containing the value
 \versiondotdebugstroffsets{} 
 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
+
 \item \texttt{padding} (\addtoindex{uhalf}) \\
 \end{enumerate}
 
@@ -3115,7 +3248,7 @@ A 2-byte version identifier containing the value
 \versiondotdebugloc{} 
 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
 
-\needlines{4}
+\needlines{5}
 \item  \texttt{address\_size} (\addtoindex{ubyte}) \\
 A 1-byte unsigned integer containing the size in
 bytes of an address (or the offset portion of an
@@ -3152,6 +3285,7 @@ in the
 \dotdebugframe{},
 \dotdebuginfo{}, 
 \dotdebugline{}, 
+\dotdebuglinestr{},
 \dotdebugloc{}, 
 \dotdebugmacro{},
 \dotdebugpubnames{}, 
@@ -3292,6 +3426,7 @@ code, and the attribute value.
 \DWATname,
 \DWATaccessibility,
 \DWATaddressclass,
+\DWATalignment,
 \DWATallocated,
 \DWATartificial,
 \DWATassociated,
@@ -3476,6 +3611,7 @@ least significant 64 bits are taken as the type signature.
 the type that uniquely identifies that type (that is, a different
 type is highly unlikely to produce the same string).}
 
+\needlines{6}
 \textit{A debugging information entry should not be placed in a
 separate \addtoindex{type unit}
 if any of the following apply:}
index f6c7ac5..94573ac 100644 (file)
@@ -8,7 +8,9 @@ the diagram and associated notes on the following pages.
 
 \textit{This diagram does not distinguish between the normal
 and split object section pairs (for example, \dotdebuginfo{} 
-versus \dotdebuginfodwo).}
+versus \dotdebuginfodwo). Similarly, it does not show the 
+relationship between the main debugging sections of an executable
+or sharable file and a related \addtoindex{supplementary object file}.}
 
 \clearpage
 \begin{landscape}
@@ -20,37 +22,37 @@ versus \dotdebuginfodwo).}
         link/.style={rectangle,                       draw,
         inner sep=.2cm, minimum width=4.5cm}]
 
-% The left column, first sections, then links, from top to bottom
+% The first (leftmost) column, first sections, then links, from top to bottom
 %
 \node(zsectara) at ( 0, 15.0) [sect] {\dotdebugaranges};
 \node(zlinka)   at ( 0, 13.5) [link] {To compilation unit~~(a)};
 \node(zsectinf) at ( 0,  7.5) [sect] {\begin{tabular}{c} 
-                                                                        \dotdebuginfo 
-                                                                        \end{tabular}};
+                                     \dotdebuginfo 
+                                     \end{tabular}};
 \node(zlinkb)   at ( 0,  1.5) [link] {To compilation unit~~(b)};
 \node(zsectpub) at ( 0,  0.0) [sect] {\begin{tabular}{c} 
-                                                                        \dotdebugpubnames \\ 
-                                                                        \dotdebugpubtypes 
-                                                                        \end{tabular}};
+                                     \dotdebugpubnames \\ 
+                                     \dotdebugpubtypes 
+                                     \end{tabular}};
 
 \draw[thick,-to reversed]              (zlinka) -- (zsectara);
 \draw[thick,angle 90-]                         (zsectinf) -- (zlinka);
 \draw[thick,-angle 90]                         (zlinkb) -- (zsectinf);
 \draw[thick,to reversed-]              (zsectpub) -- (zlinkb);
 
-% The middle column, similarly
+% The seond column, similarly
 %
 \node(zsectfra) at (5, 15.0)  [sect] {\dotdebugframe};
 \node(zlinkc)   at (5, 13.5)  [link] {To abbreviations~~(c)};
 \node(zlinkd)   at (5, 12.1)  [link] {\DWFORMstrp{}~~(d)};
 \node(zlinke)  at (5, 10.4)  [link] {\begin{tabular}{c}
-                                                                         \DWATstroffsetsbase \\
-                                                                         \DWFORMstrx{}~~~~~~~~~(e) \\
-                                                                         \end{tabular}};
+                                     \DWATstroffsetsbase \\
+                                     \DWFORMstrx{}~~~~~~~~~(e) \\
+                                     \end{tabular}};
 \node(zlinkf)   at (5,  8.4)  [link] {\begin{tabular}{c}
-                                                                         \DWOPcallref{}~~~~~(f) \\
-                                                                         \DWFORMrefaddr
-                                                                         \end{tabular}};
+                                     \DWOPcallref{}~~~~~(f) \\
+                                     \DWFORMrefaddr
+                                     \end{tabular}};
 \node(zlinki)   at (5,  6.7)  [link] {\DWATmacros{}~~(g)};
 \node(zlinkj)   at (5,  5.4)  [link] {\DWATstmtlist{}~~(h)};
 \node(zlinkh)   at (5,  3.9)  [link] {\begin{tabular}{c}
@@ -59,25 +61,25 @@ versus \dotdebuginfodwo).}
                                       \end{tabular}};
 \node(zlinkg)   at (5,  2.4)  [link] {\DWATlocation{}, etc.~~(j)};
 \node(zlinkk)  at (5,  0.5)  [link] {\begin{tabular}(c)
-                                                                         \DWATaddrbase    \\
-                                                                         \DWFORMaddrx \\
-                                                                         \DWOPaddrx \\
-                                                                         \DWOPconstx
-                                                                         \end{tabular} (k)};
+                                     \DWATaddrbase    \\
+                                     \DWFORMaddrx \\
+                                     \DWOPaddrx \\
+                                     \DWOPconstx
+                                     \end{tabular} (k)};
 
-% Links between left and center
+% Links between first and second columns
 %
-\draw[thick,to reversed-]                      (zsectinf) -- (zlinkc.west);
-\draw[thick,to reversed-]                      (zsectinf) -- (zlinkd.west);
-\draw[thick,to reversed-]                      (zsectinf) -- (zlinke.west);
-\draw[<->,thick]                                       (zsectinf) -- (zlinkf.west);
-\draw[thick,to reversed-]                      (zsectinf) -- (zlinkg.west);
-\draw[thick,to reversed-]                      (zsectinf) -- (zlinkh.west);
-\draw[thick,to reversed-]                      (zsectinf) -- (zlinki.west);
-\draw[thick,to reversed-]                      (zsectinf) -- (zlinkj.west);
-\draw[thick,to reversed-]                      (zsectinf) -- (zlinkk.north west);
-
-% The right column
+\draw[thick,to reversed-]      (zsectinf) -- (zlinkc.west);
+\draw[thick,to reversed-]      (zsectinf) -- (zlinkd.west);
+\draw[thick,to reversed-]      (zsectinf) -- (zlinke.west);
+\draw[<->,thick]               (zsectinf) -- (zlinkf.west);
+\draw[thick,to reversed-]      (zsectinf) -- (zlinkg.west);
+\draw[thick,to reversed-]      (zsectinf) -- (zlinkh.west);
+\draw[thick,to reversed-]      (zsectinf) -- (zlinki.west);
+\draw[thick,to reversed-]      (zsectinf) -- (zlinkj.west);
+\draw[thick,to reversed-]      (zsectinf) -- (zlinkk.north west);
+
+% The thrid column
 %
 \node(zsectabb)        at (10, 15.00) [sect] {\dotdebugabbrev};
 \node(zsectstr)        at (10, 13.75) [sect] {\dotdebugstr};
@@ -102,8 +104,8 @@ versus \dotdebuginfodwo).}
                                        \end{tabular} (o)};
 \node(zsectadx) at (10,  -0.25) [sect] {\dotdebugaddr{}};
 
-\draw[thick,to reversed-]              (zsectstx) -- (zlinkl);
-\draw[thick,-angle 90]                 (zlinkl) -- (zsectstr);
+\draw[thick,to reversed-]      (zsectstx) -- (zlinkl);
+\draw[thick,-angle 90]         (zlinkl) -- (zsectstr);
 \draw[thick,to reversed-]       (zsectmac) -- (zlinkm);
 \draw[thick,-angle 90]          (zlinkm) -- (zsectstx);
 \draw[thick,to reversed-]       (zsectmac) -- (zlinkn);
@@ -111,7 +113,7 @@ versus \dotdebuginfodwo).}
 \draw[thick,to reversed-]       (zsectloc) -- (zlinko);
 \draw[thick,-angle 90]          (zlinko) -- (zsectadx);
 
-% Links between center and right
+% Links between second and third colums
 %
 \draw[thick,-angle 90]         (zlinkc.east) -- (zsectabb.west);
 \draw[thick,-angle 90]         (zlinkd.east) -- (zsectstr.west);
@@ -122,20 +124,25 @@ versus \dotdebuginfodwo).}
 \draw[thick,-angle 90]         (zlinkj.east) -- (zsectlin.west);
 \draw[thick,-angle 90]         (zlinkk.east) -- (zsectadx.west);
 
-\node(zlinky)   at (15.5, 10.5) [link] {\begin{tabular}{c}
+% The fourth column
+%
+\node(zlinky)   at (15.6, 10.5) [link] {\begin{tabular}{c}
                                         \DWMACROdefineindirect \\
                                         \DWMACROundefindirect \\
                                         (p)
                                         \end{tabular}};
-\node(zlinkz)   at (15.5,  6.0) [link] {\begin{tabular}{c}
+\node(zlinkz)   at (15.6,  6.0) [link] {\begin{tabular}{c}
                                         \DWMACROtransparentinclude \\
                                         (q)
                                         \end{tabular}};
-
+\node(zlinkx)   at (15.6,  3.8) [link]  {\DWFORMlinestrp~(r)};
+\node(zsectlns) at (15.6,  2.0) [sect]  {\dotdebuglinestr};
+                                        
 \draw[thick,to reversed-]       (zsectmac.east) -- (zlinky);
 \draw[thick,-angle 90]          (zlinky) -- (zsectstr.east);
-\draw[<->,thick]                               (zsectmac.east) -- (zlinkz);
-
+\draw[<->,thick]               (zsectmac.east) -- (zlinkz);
+\draw[thick,to reversed-]       (zsectlin.east) -- (zlinkx);
+\draw[thick, -angle 90]         (zlinkx) -- (zsectlns);
 \end{tikzpicture}
 \vspace{5mm}
 \caption{Debug section relationships}
@@ -281,6 +288,7 @@ into the string offset table in the
 \dotdebugstroffsets{} section.
 
 %q
+\needlines{4}
 \item \dotdebugmacro{} to \dotdebugmacro \\
 The second operand of a 
 \DWMACROtransparentinclude{} macro information
@@ -288,5 +296,11 @@ entry is an offset into another part of the
 \dotdebugmacro{} section to the header for the 
 sequence to be transparently included.
 
+%r
+\item \dotdebugline{} to \dotdebuglinestr \\
+The value of a \DWFORMlinestrp{} form refers to a
+string section specific to the line number table.
+This form can be used in a \dotdebugline{} section
+(as shown) or in a \dotdebuginfo{} section (not shown).
 
 \end{enumerate}
index 2a32066..3028a72 100644 (file)
@@ -3,7 +3,7 @@
 % If draft is in the document class list, pix are just suggested
 % by an outline, the pic does not appear as a picture.
 %
-\newcommand{\docdate}{August 22, 2014}
+\newcommand{\docdate}{September 25, 2014}
 %
 \usepackage{ifthen}
 \newboolean{isdraft}
@@ -185,24 +185,8 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
         \end{table}
         }
 
-% Anti-ligature commands added because \/ and {} don't work for unknown reasons
-% nor does the microtext package DisableLigatures command...???
-%
-\newcommand{\xiiif}                            {0x3\hspace{1pt}f}
-\newcommand{\xiiifff}                  {0x3\hspace{1pt}f\hspace{2pt}f\hspace{2pt}f}
-\newcommand{\xff}                              {0x\hspace{1pt}f\hspace{2pt}f}
-\newcommand{\xffff}                            {0x\hspace{1pt}f\hspace{2pt}f\hspace{2pt}f\hspace{2pt}f}
-%
-% These are intended for use in running text...
-%
-\newcommand{\xffffffff}                {\texttt{0xffffffff}}                   % use with following punctutation
-\newcommand{\wffffffff}                {\texttt{0xffffffff}\ }                 % use as separate "word"
-\newcommand{\xfffffffzero}             {\texttt{0xfffffff0}}                   % use with following punctutation
-\newcommand{\wfffffffzero}             {\texttt{0xfffffff0}\ }
-\newcommand{\xffffffffffffffff}        {\texttt{0xffffffffffffffff}}   % use with following punctutation
-\newcommand{\wffffffffffffffff}        {\texttt{0xffffffffffffffff}\ }
-
 % Define commands for all of the DWARF names (DW\_*, .debug_*, a few others)
+%
 \include{dwarfnamecmds}
 
 %--- Begin the document pages
@@ -288,9 +272,10 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
                \makeevenhead{plain}{}{Change Summary}{}
                \makeoddhead{plain}{}{Change Summary}{}
                \include{changesummary}
+                \emptypage
                }
        }{}
-\cleardoublepage
+%\cleardoublepage
 \flushleft
 \raggedbottom
 \chapterstyle{default}
@@ -310,24 +295,24 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 % Define the levels of sectionality that are numbered.
 \setcounter{secnumdepth}{5}
 
-\include{introduction}
-\include{generaldescription}            \emptypage
+\include{introduction}                  \emptypage
+\include{generaldescription}            %\emptypage
 \include{programscope}                  %\emptypage
 \include{dataobject}                    \emptypage
-\include{typeentries}                   %\emptypage
+\include{typeentries}                   \emptypage
 \include{otherdebugginginformation}    %\emptypage
 \include{datarepresentation}            \emptypage
 
 %  The \appendix toggles us into appendix chapters
 \appendix
 
-\include{attributesbytag}              %\emptypage
-\include{debugsectionrelationships}     %\emptypage
+\include{attributesbytag}              \emptypage
+\include{debugsectionrelationships}     \emptypage
 \include{encodingdecoding}              \emptypage
 \include{examples}                      %\emptypage
-\include{compression}                   %\emptypage
-\include{splitobjects}                 \emptypage
-\include{sectionversionnumbers}
+\include{compression}                   \emptypage
+\include{splitobjects}                 %\emptypage
+\include{sectionversionnumbers}         \emptypage
 \include{gnulicense}
 
 \printindex
index a328647..8438a04 100644 (file)
@@ -32,6 +32,7 @@
 \newdwfnamecommands{DWATaccessibility}{DW\_AT\_accessibility}
 \newdwfnamecommands{DWATaddrbase}{DW\_AT\_addr\_base}
 \newdwfnamecommands{DWATaddressclass}{DW\_AT\_address\_class}
+\newdwfnamecommands{DWATalignment}{DW\_AT\_alignment}
 \newdwfnamecommands{DWATallocated}{DW\_AT\_allocated}
 \newdwfnamecommands{DWATartificial}{DW\_AT\_artificial}
 \newdwfnamecommands{DWATassociated}{DW\_AT\_associated}
 \newdwfnamecommands{DWFORMdatatwo}{DW\_FORM\_data2}
 \newdwfnamecommands{DWFORMdatafour}{DW\_FORM\_data4}
 \newdwfnamecommands{DWFORMdataeight}{DW\_FORM\_data8}
+\newdwfnamecommands{DWFORMdatasixteen}{DW\_FORM\_data16}
 \newdwfnamecommands{DWFORMexprloc}{DW\_FORM\_exprloc}
 \newdwfnamecommands{DWFORMflag}{DW\_FORM\_flag}
 \newdwfnamecommands{DWFORMflagpresent}{DW\_FORM\_flag\_present}
 \newdwfnamecommands{DWFORMindirect}{DW\_FORM\_indirect}
-\newdwfnamecommands{DWFORMrefn}{DW\_FORM\_ref<n>}                                              % Generic DW_FORM_ref[1248] name
+\newdwfnamecommands{DWFORMlinestrp}{DW\_FORM\_line\_strp}
+\newdwfnamecommands{DWFORMrefn}{DW\_FORM\_ref<n>}                      % Generic DW_FORM_ref[1248] name
 \newdwfnamecommands{DWFORMrefone}{DW\_FORM\_ref1}
 \newdwfnamecommands{DWFORMreftwo}{DW\_FORM\_ref2}
 \newdwfnamecommands{DWFORMreffour}{DW\_FORM\_ref4}
 \newdwfnamecommands{DWFORMrefeight}{DW\_FORM\_ref8}
 \newdwfnamecommands{DWFORMrefaddr}{DW\_FORM\_ref\_addr}
 \newdwfnamecommands{DWFORMrefsigeight}{DW\_FORM\_ref\_sig8}
+\newdwfnamecommands{DWFORMrefsup}{DW\_FORM\_ref\_sup}
 \newdwfnamecommands{DWFORMrefudata}{DW\_FORM\_ref\_udata}
 \newdwfnamecommands{DWFORMsdata}{DW\_FORM\_sdata}
 \newdwfnamecommands{DWFORMsecoffset}{DW\_FORM\_sec\_offset}
 \newdwfnamecommands{DWFORMstring}{DW\_FORM\_string}
 \newdwfnamecommands{DWFORMstrp}{DW\_FORM\_strp}
+\newdwfnamecommands{DWFORMstrpsup}{DW\_FORM\_strp\_sup}
 \newdwfnamecommands{DWFORMstrx}{DW\_FORM\_strx}
 \newdwfnamecommands{DWFORMudata}{DW\_FORM\_udata}
 %
 \newdwfnamecommands{DWLLEstartlengthentry}{DW\_LLE\_start\_length\_entry}
 \newdwfnamecommands{DWLLEoffsetpairentry}{DW\_LLE\_offset\_pair\_entry}
 %
+% DW_LNCT
+%
+\newdwfnamecommands{DWLNCTdirectoryindex}{DW\_LNCT\_directory\_index}
+\newdwfnamecommands{DWLNCTMDfive}{DW\_LNCT\_MD5}
+\newdwfnamecommands{DWLNCTpath}{DW\_LNCT\_path}
+\newdwfnamecommands{DWLNCTsize}{DW\_LNCT\_size}
+\newdwfnamecommands{DWLNCTtimestamp}{DW\_LNCT\_timestamp}
+\newdwfnamecommands{DWLNCTlouser}{DW\_LNCT\_lo\_user}
+\newdwfnamecommands{DWLNCThiuser}{DW\_LNCT\_hi\_user}
+%
 % DW_LNE
 %
-\newdwfnamecommands{DWLNEdefinefile}{DW\_LNE\_define\_file}
-\newdwfnamecommands{DWLNEdefinefileMDfive}{DW\_LNE\_define\_file\_MD5}
+%\newdwfnamecommands{DWLNEdefinefile}{DW\_LNE\_define\_file}
+%\newdwfnamecommands{DWLNEdefinefileMDfive}{DW\_LNE\_define\_file\_MD5}
 \newdwfnamecommands{DWLNEendsequence}{DW\_LNE\_end\_sequence}
 \newdwfnamecommands{DWLNEhiuser}{DW\_LNE\_hi\_user}
 \newdwfnamecommands{DWLNElouser}{DW\_LNE\_lo\_user}
 \newdwfnamecommands{DWMACROdefineindirect}{DW\_MACRO\_define\_indirect}
 \newdwfnamecommands{DWMACROundefindirect}{DW\_MACRO\_undef\_indirect}
 \newdwfnamecommands{DWMACROtransparentinclude}{DW\_MACRO\_transparent\_include}
+\newdwfnamecommands{DWMACROdefineindirectsup}{DW\_MACRO\_define\_indirect\_sup}
+\newdwfnamecommands{DWMACROundefindirectsup}{DW\_MACRO\_undef\_indirect\_sup}
+\newdwfnamecommands{DWMACROtransparentincludesup}{DW\_MACRO\_transparent\_include\_sup}
 \newdwfnamecommands{DWMACROdefineindirectx}{DW\_MACRO\_define\_indirectx}
 \newdwfnamecommands{DWMACROundefindirectx}{DW\_MACRO\_undef\_indirectx}
 \newdwfnamecommands{DWMACROlouser}{DW\_MACRO\_lo\_user}
 \newdwfnamecommands{DWOPand}{DW\_OP\_and}
 \newdwfnamecommands{DWOPbitpiece}{DW\_OP\_bit\_piece}
 \newdwfnamecommands{DWOPbra}{DW\_OP\_bra}
-\newdwfnamecommands{DWOPbregn}{DW\_OP\_breg<n>}                                                                        % Generic DW_OP_breg[0..31] name
+\newdwfnamecommands{DWOPbregn}{DW\_OP\_breg<n>}                                                % Generic DW_OP_breg[0..31] name
 \newdwfnamecommands{DWOPbregzero}{DW\_OP\_breg0}
 \newdwfnamecommands{DWOPbregone}{DW\_OP\_breg1}
        \newcommand{\DWOPbregtwo}{\hyperlink{chap:DWOPbregn}{DW\_OP\_breg2}}            % Link, don't index...
 \newcommand{\dotdebugframe}{\addtoindex{\texttt{.debug\_frame}}}
 \newcommand{\dotdebuginfo}{\addtoindex{\texttt{.debug\_info}}}
 \newcommand{\dotdebugline}{\addtoindex{\texttt{.debug\_line}}}
+\newcommand{\dotdebuglinestr}{\addtoindex{\texttt{.debug\_line\_str}}}
 \newcommand{\dotdebugloc}{\addtoindex{\texttt{.debug\_loc}}}
 \newcommand{\dotdebugmacinfo}{\addtoindex{\texttt{.debug\_macinfo}}}
 \newcommand{\dotdebugmacro}{\addtoindex{\texttt{.debug\_macro}}}
 \newcommand{\dotdebugranges}{\addtoindex{\texttt{.debug\_ranges}}}
 \newcommand{\dotdebugstr}{\addtoindex{\texttt{.debug\_str}}}
 \newcommand{\dotdebugstroffsets}{\addtoindex{\texttt{.debug\_str\_offsets}}}
+\newcommand{\dotdebugsup}{\addtoindex{\texttt{.debug\_sup}}}
 %
 \newcommand{\dotdebugabbrevdwo}{\addtoindex{\texttt{.debug\_abbrev.dwo}}}
 \newcommand{\dotdebugaddrdwo}{\addtoindex{\texttt{.debug\_addr.dwo}}}
 \newcommand{\versiondotdebugpubtypes}{2}
 \newcommand{\versiondotdebugranges}  {5}
 \newcommand{\versiondotdebugstr}     {5}
+\newcommand{\versiondotdebugsup}     {5}
 \newcommand{\versiondotdebugstroffsets}{5}
 %
 % DWARF Standard Versions
 %
 \newcommand{\MDfive}{\livelink{def:MDfive}{MD5}}
 \newcommand{\COMDAT}{\addtoindex{COMDAT}}
-\newcommand{\autoreturntype}{\texttt{auto} return type\index{auto return type@\texttt{auto} return type}}
\ No newline at end of file
+\newcommand{\autoreturntype}{\texttt{auto} return type\index{auto return type@\texttt{auto} return type}}
+%
+% Anti-ligature commands added because \/ and {} don't work for unknown reasons
+% nor does the microtext package DisableLigatures command...???
+%
+\newcommand{\xiiif}                    {0x3\hspace{1pt}f}
+\newcommand{\xiiifff}                  {0x3\hspace{1pt}f\hspace{2pt}f\hspace{2pt}f}
+\newcommand{\xff}                      {0x\hspace{1pt}f\hspace{2pt}f}
+\newcommand{\xffff}                    {0x\hspace{1pt}f\hspace{2pt}f\hspace{2pt}f\hspace{2pt}f}
+%
+% These are intended for use in running text...
+%
+\newcommand{\xffffffff}                {\texttt{0xffffffff}}           % use with following punctutation
+\newcommand{\wffffffff}                {\texttt{0xffffffff}\ }         % use as separate "word"
+\newcommand{\xfffffffzero}             {\texttt{0xfffffff0}}           % use with following punctutation
+\newcommand{\wfffffffzero}             {\texttt{0xfffffff0}\ }
+\newcommand{\xffffffffffffffff}        {\texttt{0xffffffffffffffff}}           % use with following punctutation
+\newcommand{\wffffffffffffffff}        {\texttt{0xffffffffffffffff}\ }
+
index 73776e4..5b0a3b6 100644 (file)
@@ -2981,9 +2981,11 @@ Figure \refersec{fig:stringtypeexampledwarf} is appropriate.
         program character_kind
             use iso_fortran_env
             implicit none
-            integer, parameter :: ascii = selected_char_kind ("ascii")
-            integer, parameter :: ucs4  = selected_char_kind ('ISO_10646')
-              
+            integer, parameter :: ascii = 
+                selected_char_kind ("ascii")
+            integer, parameter :: ucs4  = 
+                selected_char_kind ('ISO_10646')
+\addtoindexx{ISO 10646 character set standard}             
             character(kind=ascii, len=26) :: alphabet
             character(kind=ucs4,  len=30) :: hello_world
             character (len=*), parameter :: all_digits="0123456789"
index e6428b6..b738cdf 100644 (file)
@@ -132,7 +132,16 @@ DWARF object file that resides alongside the normal object
 file. See Section \refersec{datarep:splitdwarfobjects} and
 Appendix \refersec{app:splitdwarfobjectsinformative} for details.
 
-
+As a further option, debugging information entries and other debugging
+information that are the same in multiple executables or shared objects 
+may found in a separate \addtoindex{supplementary object file} that 
+contains supplementary debug sections.
+The executable or shared object which contains references to
+those debugging information entries contain a \dotdebugsup{} section
+with information that identifies the supplementary object file; the 
+supplementary object file contains a variant of this same section
+that is used to unambiguously associate it with the referencing object.
 \section{Attribute Types}
 \label{chap:attributetypes}
 Each attribute value is characterized by an attribute name. 
@@ -170,6 +179,9 @@ The attributes are listed in Table \referfol{tab:attributenames}.
 &\livelinki{chap:DWATaddressclasssubroutineorsubroutinetype}{Subroutine or subroutine type}{subroutine or subroutine type} \\
 \DWATaddrbaseTARG
 &\livelinki{chap:DWATaddrbaseforaddresstable}{Base offset for address table}{address table} \\
+\DWATalignmentTARG
+&\livelinki{chap:DWATalignmentnondefault}{Non-default alignment of type, subprogram or variable}{non-default alignment}
+\addtoindexx{alignment!non-default} \\
 \DWATallocatedTARG
 &\livelinki{chap:DWATallocatedallocationstatusoftypes}{Allocation status of types}{allocation status of types}  \\
 \DWATartificialTARG
@@ -432,7 +444,7 @@ The attributes are listed in Table \referfol{tab:attributenames}.
 \DWATspecificationTARG
 &\livelinki{chap:DWATspecificationincompletenondefiningorseparatedeclaration}{Incomplete, non-defining, or separate declaration corresponding to a declaration}{incomplete, non-defining, or separate declaration corresponding to a declaration} \\
 \DWATstartscopeTARG
-&\livelinki{chap:DWATstartscopeobjectdeclaration}{Object declaration}{object declaration}\\
+&\livelinki{chap:DWATstartscopeobjectdeclaration}{Object declaration}{object declaration}\\*
 &\livelinki{chap:DWATstartscopetypedeclaration}{Type declaration}{type declaration}\\
 \DWATstaticlinkTARG
 &\livelinki{chap:DWATstaticlinklocationofuplevelframe}{Location of uplevel frame}{location of uplevel frame} \\
@@ -521,6 +533,7 @@ of an attribute is encoded along with the attribute name as
 part of the information that guides the interpretation of a
 debugging information entry.  
 
+\needlines{4}
 Attribute value forms belong
 \addtoindexx{tag names!list of}
 to one of the classes shown in Table \referfol{tab:classesofattributevalue}.
@@ -922,7 +935,7 @@ type of the value contained in the specified register.
 
 \end{enumerate}
 
-
+\needlines{6}
 \subsubsection{Stack Operations}
 \label{chap:stackoperations}
 The following 
@@ -1070,6 +1083,7 @@ operand is an unsigned LEB128 integer that represents the offset of a
 debugging information entry in the current compilation unit, which must be a
 \DWTAGbasetype{} entry that provides the type of the data pushed.
 
+\needlines{6}
 \itembfnl{\DWOPpushobjectaddressTARG}
 The \DWOPpushobjectaddressNAME{}
 operation pushes the address
@@ -1190,6 +1204,7 @@ stack from the former second entry, and pushes the result.
 The \DWOPmodTARG{} operation pops the top two stack values and pushes the result of the
 calculation: former second stack entry modulo the former top of the stack.
 
+\needlines{4}
 \itembfnl{\DWOPmulTARG}
 The \DWOPmulTARG{} operation pops the top two stack entries, multiplies them together, and
 pushes the result.
@@ -2141,7 +2156,7 @@ for descriptions of the entries describing
 base types, user-defined types and type modifiers.
 
 
-
+\needlines{6}
 \section{Accessibility of Declarations}
 \label{chap:accessibilityofdeclarations}
 \textit{Some languages, notably \addtoindex{C++} and 
@@ -2188,6 +2203,7 @@ Table \refersec{tab:visibilitycodes}.
 \DWVISqualifiedTARG{}  \\
 \end{simplenametable}
 
+\needlines{8}
 \section{Virtuality of Declarations}
 \label{chap:virtualityofdeclarations}
 \textit{\addtoindex{C++} provides for virtual and pure virtual structure or class
@@ -2962,7 +2978,6 @@ The entry may also have a
 that the value corresponds to the default argument for the 
 template parameter.
 
-
 A
 \addtoindexx{formal type parameter|see{template type parameter entry}}
 template type parameter entry has a
@@ -2970,7 +2985,6 @@ template type parameter entry has a
 \DWATtype{} attribute
 describing the actual type by which the formal is replaced.
 
-
 A template value parameter entry has a \DWATtype{} attribute 
 describing the type of the parameterized value.
 The entry also has an attribute giving the 
@@ -2984,3 +2998,30 @@ on the target architecture.
 Or, the attribute can be a \DWATlocation{} attribute, whose value is a 
 single location description for the run-time constant address.
 
+\section{Alignment}
+\label{chap:alignment}
+\livetarg{chap:DWATalignmentnondefault}{}
+A debugging information entry may have a 
+\DWATalignment{} attribute\addtoindexx{alignment attribute}
+that describes the (non-default) alignment requirements of the entry.
+\DWATalignment{} has a positive, non-zero, integer constant value
+describing the strictest specified (non-default) alignment of the entity. 
+This constant describes the actual alignment used by the compiler.
+(If there are multiple alignments specified by the user, or if the 
+user specified an alignment the compiler could not satisfy, then 
+only the strictest alignment is added using this attribute.)
+
+\textit{Debugging information entries to which \DWATalignment{} may 
+apply include (but are not limited to):
+\DWTAGarraytype, \DWTAGatomictype, \DWTAGbasetype, 
+\DWTAGclasstype, 
+\DWTAGcoarraytype, \DWTAGconsttype, \DWTAGdynamictype,
+\DWTAGenumerationtype, \DWTAGfiletype, \DWTAGinterfacetype,
+\DWTAGpackedtype, \DWTAGpointertype, \DWTAGptrtomembertype,
+\DWTAGreferencetype, \DWTAGrestricttype, \DWTAGrvaluereferencetype,
+\DWTAGsettype, \DWTAGsharedtype, \DWTAGstringtype, \DWTAGstructuretype,
+\DWTAGsubprogram, \DWTAGsubrangetype, \DWTAGsubroutinetype,
+\DWTAGthrowntype, \DWTAGtypedef, \DWTAGuniontype, and \DWTAGvariable.}
+
+
+
index df20014..f67212f 100644 (file)
@@ -137,6 +137,12 @@ The following is a list of the major changes made to the DWARF Debugging Informa
 Format since Version 4 was published. The list is not meant to be exhaustive.
 \begin{itemize}
 \item OTHERS TBD...
+\item Add support for collecting common DWARF information (DIEs and macro definitions)
+across multiple executable and shared files and keeping it in a single
+supplementary object file.
+\item Add a string section specific to the line number table (\dotdebuglinestr)
+to more properly support the common practice of stripping all DWARF sections
+except for line number information.
 \item Add a split object file and package representations to allow most 
 DWARF information to be compacted and/or kept separate from an executable 
 or shared image. This includes new sections 
@@ -150,11 +156,11 @@ a much more compact \dotdebugmacro{} representation.
 \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.
-\item Add a new attribute, \DWATnoreturn{}, to identify a subprogram that 
+\item Add a new attribute, \DWATnoreturnNAME{}, to identify a subprogram that 
 does not return to its caller.
-\item Add a new attribute, \DWATrank{}, to describe the dimensionality of
+\item Add a new attribute, \DWATrankNAME{}, to describe the dimensionality of
 an array with dynamic rank.
-\item Add a new tag, \DWTAGgenericsubrange{}, to describe the
+\item Add a new tag, \DWTAGgenericsubrangeNAME{}, to describe the
 bounds of Fortran assumed-rank arrays.
 \item Add language codes for C 2011, C++ 2003, C++ 2011, Dylan, Go, Haskell, 
 Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
@@ -162,17 +168,21 @@ Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
 
 DWARF Version 5 is compatible with DWARF Version 4 except as follows:
 \begin{itemize}
-\item A new field is included in the line number table header to allow use of an MD5
-hash to validate source file version in use.
-\item New operand forms for attribute values are defined (\DWFORMstrx, \DWFORMaddrx).
+\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 
+of directory and file name strings and make provision for vendor-defined
+extensions.
+\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, they 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 \DWATbytesize{}
+\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 \DWATstringlength{}
+it described the size of the optional string length data field if the \DWATstringlengthNAME{}
 attribute was present.)
 \end{itemize}
 
@@ -197,11 +207,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, \DWFORMsecoffset, 
+section offsets, \DWFORMsecoffsetNAME
 \addtoindexx{section offset}
 to replace the use
-of \DWFORMdatafour{} and \DWFORMdataeight{} for section offsets.
-\item Add an attribute, \DWATmainsubprogram, to identify the main subprogram of a
+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.
 \item Add a new technique using separate type units, type signatures and \COMDAT{} sections to
@@ -222,7 +232,7 @@ section offsets, flag compression, type signature references, and so on) cannot
 \addtoindex{DWARF Version 3}
 consumers because the consumer will not know how to skip over the
 unexpected form of data.
-\item DWARF frame and line table sections include a additional fields that affect the location
+\item DWARF frame and line bumber table sections include a additional fields that affect the location
 and interpretation of other data in the section.
 \end{itemize}
 
@@ -272,7 +282,7 @@ is defined to increase the possible size of DWARF descriptions
 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
 \item
 References that use the attribute form 
-\DWFORMrefaddr{}
+\DWFORMrefaddrNAME{}
 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} 
index 88cc6e0..7e2a554 100644 (file)
@@ -234,12 +234,12 @@ or statement to statement.}
 
 Line number information generated for a compilation unit is
 represented in the 
-\dotdebugline{} section of an object file and
+\dotdebugline{} section of an object file, and optionally
+also in the \dotdebuglinestr{} section, and
 is referenced by a corresponding compilation unit debugging
 information entry 
 (see Section \refersec{chap:normalandpartialcompilationunitentries}) 
-in the \dotdebuginfo{}
-section.
+in the \dotdebuginfo{} section.
 
 \textit{Some computer architectures employ more than one instruction
 set (for example, the ARM 
@@ -422,7 +422,7 @@ program, the state of the registers is:
 \texttt{line} & 1 \\
 \texttt{column} & 0 \\
 \addttindex{is\_stmt} & determined by \addttindex{default\_is\_stmt} 
-                                                                       in the line number program header \\
+                       in the line number program header \\
 \addttindex{basic\_block}    & \doublequote{false} \addtoindexx{basic block} \\
 \addttindex{end\_sequence}   & \doublequote{false} \\
 \addttindex{prologue\_end}   & \doublequote{false} \\
@@ -466,7 +466,7 @@ extended opcode). \\
 
 
 \subsection{The Line Number Program Header}
-
+\label{chap:linenumberprogramheader}
 The optimal encoding of line number information depends to a
 certain degree upon the architecture of the target machine. The
 line number program header provides information used by
@@ -491,6 +491,26 @@ This number is specific to
 the line number information and is independent of the DWARF
 version number. 
 
+\item \texttt{address\_size} (ubyte)\\
+A 1-byte unsigned integer containing the size in bytes of an
+address (or offset portion of an address for segmented addressing)
+on the target system.
+   
+\textit{The \texttt{address\_size} field is new in DWARF Version 5. 
+It is needed to legitimize the common practice of stripping all but 
+the line number sections (\dotdebugline{} and \dotdebuglinestr{}) 
+from an executable.}
+
+\item \texttt{segment\_size} (ubyte) \\
+A 1-byte unsigned integer containing the size in bytes of a segment
+selector on the target system.
+   
+\textit{The \texttt{segment\_size} field is new in DWARF Version 5. 
+It is needed in combination with the \texttt{address\_size} field (preceding) 
+to accurately characterize the address representation on the target 
+system.}
+
+\needlines{4}
 \item \texttt{header\_length}  \\
 The number of bytes following the \addttindex{header\_length} field to the
 beginning of the first byte of the line number program itself.
@@ -559,6 +579,7 @@ This parameter affects the meaning of the special opcodes. See below.
 \addttindexx{line\_range}
 This parameter affects the meaning of the special opcodes. See below.
 
+\needlines{4}
 \item \texttt{opcode\_base} (\addtoindex{ubyte}) \\
 The 
 \addttindexx{opcode\_base}
@@ -600,111 +621,253 @@ do not know about these new opcodes to be able to skip them.}
 \textit{Codes for vendor specific extensions, if any, are described
 just like standard opcodes.}
 
-\item \texttt{file\_entry\_format} (\addtoindex{ubyte}) \\
-A format code indicating the format of certain data in the 
-entries of the file names field (see below). The format codes 
-and their meanings are as follows:
+%%% Save the current enum counter so we can restart later
+%%% End this enumeration so the following text is outdented to
+%%% the left margin (because it applies to the many following
+%%% items
+\newcounter{saveenumi}
+\setcounter{saveenumi}{\value{enumi}}
+\end{enumerate}
+
+\textit{The remaining fields provide information about the
+source files used in the compilation. These fields
+have been revised in \DWARFVersionV{} to support these
+goals:}
 \begin{itemize}
-\item \DWLNFtimestampsizeTARG \\
-Entries contain a modification timestamp and file size.
-\item \DWLNFMDfiveTARG \\
-Entries contain an \MDfive{} digest of the file contents.
+\item
+    \textit{To allow new alternative means for a consumer to
+    check that a file it can access is the same version
+    as that used in the compilation.}
+\item
+    \textit{To allow a producer to collect file name strings
+    in a new section (\dotdebuglinestr{}) that can be used
+    to merge duplicate file name strings.}
+\item
+    \textit{To add the ability for producers to provide 
+    vendor-defined information that can be skipped by a consumer
+    that is unprepared to process it.}
 \end{itemize}
 
-\needlines{3}
-\item \texttt{include\_directories} (sequence of path names) \\
-Entries 
-\addttindexx{include\_directories}
-in this sequence describe each path that was searched
-for included source files in this compilation. (The paths
-include those directories specified explicitly by the user for
-the compiler to search and those the compiler searches without
-explicit direction.) Each path entry is either a full path name
-or is relative to the current directory of the compilation.
-
-The last entry is followed by a single null byte.
-
-The line number program assigns numbers to each of the file
-entries in order, beginning with 1. The current directory of
-the compilation is understood to be the zeroth entry and is
-not explicitly represented.
-
-\item  \texttt{file\_names} (sequence of file entries) \\
-Entries 
-\addtoindexx{file names}
-in 
-\addttindexx{file\_names}
-this sequence describe source files that contribute
-to the line number information for this compilation unit or is
-used in other contexts, such as in a 
-\livelinki{chap:declarationcoordinates}{declaration coordinate}{declaration coordinates} or
-a macro file inclusion. Each entry consists of the following
-values:
-
-
-\begin{itemize}
-\item A null\dash terminated string containing the full or relative
-path name of a source file. If the entry contains a file
-name or relative path name, the file is located relative
-to either the compilation directory (as specified by the
-\DWATcompdir{} 
-attribute given in the compilation unit) or one
-of the directories listed in the 
-\addttindex{include\_directories} section.
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned} 
-number representing the directory
-index of a directory in the 
-\addttindex{include\_directories} section.
-
-\item If \texttt{file\_entry\_format} (see above) is \DWLNFtimestampsize:
+\begin{enumerate}[1. ]
+%%% Resume enumeration count where it left off above
+\setcounter{enumi}{\value{saveenumi}}
+\item \texttt{directory\_entry\_format\_count} (ubyte) \\
+    A count of the number of entries that occur in the
+    following \texttt{directory\_entry\_format} field.
+   
+\item \texttt{directory\_entry\_format} (sequence of uleb pairs) \\
+    A sequence of directory entry format descriptions.
+    Each description consists of a pair of uleb values:
 \begin{itemize}
-    \item An unsigned LEB128\addtoindexx{LEB128!unsigned}
-    number representing the
-    (implementation-\linebreak[0]defined) time of last modification for
-    the file, or 0 if not available.
-
-    \item An unsigned LEB128\addtoindexx{LEB128!unsigned} 
-    number representing the length in
-    bytes of the file, or 0 if not available.  
+\setlength{\itemsep}{0em}
+\item A content type code (see below)
+\item A form code using the attribute form codes
 \end{itemize}
-If \texttt{file\_entry\_format} is \DWLNFMDfive:
+
+\needlines{4} 
+\item \texttt{directories\_count} (uleb) \\
+A count of the number of entries that occur in the
+following directories field.
+
+\needlines{4}    
+\item \texttt{directories} (sequence of directory names) \\
+A sequence of directory names and optional related
+information. Each entry is encoded as described
+by the \texttt{directory\_entry\_format} field.
+   
+Entries in this sequence describe each path that was
+searched for included source files in this compilation,
+including the compilation directory of the compilation.
+(The paths include those directories specified by the
+user for the compiler to search and those the compiler
+searches without explicit direction.)
+   
+The first entry is the current directory of the compilation.
+Each additional path entry is either a full path name or
+is relative to the current directory of the compilation.
+   
+The line number program assigns a number (index) to each
+of the directory entries in order, beginning with 0.
+   
+\textit{Prior to \DWARFVersionV, the current directory was not
+represented in the directories field and a directory index
+of 0 implicitly referred to that directory as found in the
+\DWATcompdir{} attribute of the compilation unit DIE. In
+\DWARFVersionV, the current directory is explicitly present
+in the directories field. This is needed to legitimize the
+common practice of stripping all but the line number sections
+(\dotdebugline{} and \dotdebuglinestr) from an executable.}
+
+\textit{Note that if a \dotdebuglinestr{} section is present, 
+both the compilation unit DIE and the line number header can
+share a single copy of the current directory name string.}
+
+\item \texttt{file\_name\_entry\_format\_count} (ubyte) \\
+A count of the number of file entry format entries that
+occur in the following \texttt{file\_name\_entry\_format} field. 
+If this field is zero, then the \texttt{file\_names\_count} field 
+(see below) must also be zero.
+
+\item \texttt{file\_name\_entry\_format} (sequence of uleb pairs) \\
+A sequence of file entry format descriptions.
+Each description consists of a pair of uleb values:
 \begin{itemize}
-\item A 16-byte \MDfive{} digest of the file contents.
+\setlength{\itemsep}{0em}
+\item A content type code (see below)
+\item A form code using the attribute form codes
 \end{itemize}
 
-\end{itemize}
+\item \texttt{file\_names\_count} (uleb) \\
+A count of the number of file name entries that occur
+in the following \texttt{file\_names} field.
 
-The last entry is followed by a single null byte.
+\needlines{4}
+\item \texttt{file\_names} (sequence of file name entries) \\
+A sequence of file names and optional related
+information. Each entry is encoded as described
+by the \texttt{file\_name\_entry\_format} field (in the
+order described).
+  
+Entries in this sequence describe source files that
+contribute to the line number information for this
+compilation or is used in other contexts, such as in
+a declaration coordinate or a macro file inclusion.
+The first entry in the sequence is the primary source file 
+whose file name exactly matches that given in the 
+\DWATname{} attribute in the compilation unit DIE.
+   
+The line number program assigns numbers to each of
+the file name entries in order, beginning with 0, and uses
+those numbers instead of file names in the line number
+program that follows.
+
+\textit{Prior to \DWARFVersionV, the current compilation 
+file name was not represented in the \texttt{file\_names}
+field. In \DWARFVersionV, the current compilation file name 
+is explicitly present and has index 0. This is needed to legitimize 
+the common practice of stripping all but the line number sections
+(\dotdebugline{} and \dotdebuglinestr) from an executable.}
 
-The directory index represents an entry in the
-\addttindex{include\_directories} section. 
-The index is 0 if the file was
-found in the current directory of the compilation, 1 if it
-was found in the first directory in the 
-\addttindex{include\_directories}
-section, and so on. The directory index is ignored for file
-names that represent full path names.
+\end{enumerate}
 
-The primary source file is described by an entry whose path
-name exactly matches that given in the \DWATname{} attribute
-in the compilation unit, and whose directory is understood
-to be given by the implicit entry with index 0.
+\subsubsubsection{Standard Content Descriptions}
+DWARF-defined content type codes are used to indicate
+the type of information that is represented in one
+component of an include directory or file name description.
+The following type codes are defined.
+\begin{enumerate}[1. ]
 
-The line number program assigns numbers to each of the file
-entries in order, beginning with 1, and uses those numbers
-instead of file names in the file register.
+\item  \DWLNCTpathTARG \\
+The component is a null-terminated path name string.
+If the associated form code is \DWFORMstring{}, then the
+string occurs immediately in the containing \texttt{directories}
+or \texttt{file\_names} field. If the form code is \DWFORMlinestrp{},
+then the string is included in the \dotdebuglinestr{} section
+and its offset occurs immediately in the containing
+\texttt{directories} or \texttt{file\_names} field.
+
+\textit{Note that this use of \DWFORMlinestrp{} is similar to
+\DWFORMstrp{} but refers to the \dotdebuglinestr{} section,
+not \dotdebugstr.}
+   
+In a \dotdebuglinedwo{} section, the form \DWFORMstrx{} may
+also be used. This refers into the \dotdebugstroffsetsdwo{}
+section (and indirectly also the \dotdebugstrdwo{} section)
+because no \texttt{.debug\_line\_str\_offsets.dwo} or 
+\texttt{.debug\_line\_str.dwo} sections exist or are defined for 
+use in split objects. (The form \DWFORMstring{} may also be used, 
+but this precludes the benefits of string sharing.)
+   
+In the 32-bit DWARF format, the representation of a
+\DWFORMlinestrp{} value is a 4-byte unsigned offset; in the
+64-bit DWARF format, it is an 8-byte unsigned offset (see
+Section \refersec{datarep:32bitand64bitdwarfformats}).
+   
+\item \DWLNCTdirectoryindexTARG \\
+The unsigned directory index represents an entry in the
+directories field of the header. The index is 0 if
+the file was found in the current directory of the compilation
+(hence, the first directory in the directories field),
+1 if it was found in the second directory in the directories
+field, and so on.
+
+This content code is always paired with one of \DWFORMdataone, 
+\DWFORMdatatwo{} or \DWFORMudata.
+
+\textit{The optimal form for a producer to use (which results in the
+minimum size for the set of \texttt{include\_index} fields) depends not only
+on the number of directories in the directories
+field, but potentially on the order in which those directories are
+listed and the number of times each is used in the \texttt{file\_names} field.
+However, \DWFORMudata{} is expected to be near optimal in most common
+cases.}
+   
+\item \DWLNCTtimestampTARG \\
+\DWLNCTtimestampNAME{} indicates that the value is the implementation-defined 
+time of last modification of the file, or 0 if not available. 
+It is always paired with one of the forms
+\DWFORMudata, \DWFORMdatafour, \DWFORMdataeight{} or \DWFORMblock.
+   
+\item  \DWLNCTsizeTARG \\
+\DWLNCTsizeNAME{} indicates that the value is the unsigned size of the
+file in bytes, or 0 if not available. It is paired with one of the
+forms \DWFORMudata, \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour{}
+or \DWFORMdataeight.
+\item \DWLNCTMDfiveTARG \\
+\DWLNCTMDfiveNAME{} indicates that the value is a 16-byte \MDfive digest
+of the file contents. It is paired with form \DWFORMdatasixteen.
+\end{enumerate}
 
-\textit{A compiler may generate a single null byte for the file
-names field and define file names using the extended opcode
-\DWLNEdefinefile{} (when \texttt{file\_entry\_format} is \DWLNFtimestampsize) or
-\DWLNEdefinefileMDfive{} (when \texttt{file\_entry\_format} is \DWLNFMDfive).}
+\textit{Using this representation, the information found in a DWARF
+Version 4 line number header could be encoded as shown in 
+Figure \refersec{fig:preV5LNCTusingV5}.}
 
+\begin{figure}[here]
+\begin{dwflisting}
+\begin{alltt}
+  Field           Field Name                      Value(s)
+  Number
+     1    \textit{Same as in Version 4}            ...
+     2    version                         5
+     3    \textit{Not present in Version 4}        -
+     4    \textit{Not present in Version 4}        -
+   5-12   \textit{Same as in Version 4}            ...
+    13    directory_entry_format_count    1
+    14    directory_entry_format          \DWLNCTpath, \DWFORMstring
+    15    directories_count               <n>
+    16    directories                     <n>*<null terminated string>
+    17    file_name_entry_format_count    4
+    18    file_name_entry_format          \DWLNCTpath, \DWFORMstring,
+                                          \DWLNCTdirectoryindex, \DWFORMudata,
+                                          \DWLNCTtimestamp, \DWFORMudata,
+                                          \DWLNCTsize, \DWFORMudata
+    19    file_names_count                <m>
+    20    file_names                      <m>*{<null terminated string>,
+                                          <index>, <timestamp>, <size>}
+\end{alltt}
+\end{dwflisting}
+\caption{Pre-\DWARFVersionV{} Line Number Program Header Information \mbox{Encoded} Using \DWARFVersionV}
+\label{fig:preV5LNCTusingV5}
+\end{figure}
 
-\end{enumerate}
+\subsubsubsection{Vendor-defined Content Descriptions}
+Vendor-defined content descriptions may be defined using content
+type codes in the range \DWLNCTlouserTARG{} to \DWLNCThiuserTARG{}. Each
+such code may be combined with one or more forms from the set:
+\DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
+\DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight,
+\DWFORMdatasixteen,
+\DWFORMflag, \DWFORMlinestrp, \DWFORMsdata, \DWFORMsecoffset,
+\DWFORMstring, \DWFORMstrp, \DWFORMstrx{}  and \DWFORMudata.
 
-\subsection{The Line Number Program}
+If a consumer encounters a vendor-defined content type that
+it does not understand, it should skip the content data as though
+it was not present.
 
+\subsection{The Line Number Program}
+\label{linenumberprogram}
 As stated before, the goal of a line number program is to build
 a matrix representing one compilation unit, which may have
 produced multiple sequences of target machine instructions.
@@ -1073,49 +1236,6 @@ sets the \addttindex{op\_index} register to 0.
 affect the \texttt{address} register add a delta to it. This instruction
 stores a relocatable value into it instead.}
 
-\needlines{4}
-\item \textbf{\DWLNEdefinefileTARG} \\
-The \DWLNEdefinefileTARG{} opcode takes four operands:
-\begin{enumerate}[1. ]
-
-\item A null\dash terminated string containing the full or relative
-path name of a source file. If the entry contains a file
-name or a relative path name, the file is located relative
-to either the compilation directory (as specified by the
-\DWATcompdir{} attribute given in the compilation unit)
-or one of the directories in the 
-\addttindex{include\_directories} section.
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned} 
-number representing the directory index
-of the directory in which the file was found.  
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned} 
-number representing the time of last modification
-of the file, or 0 if not available.  
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned}
-number representing the length in bytes of the file, or 0 if
-not available.
-\end{enumerate}
-
-The directory index represents an entry in the
-\addttindex{include\_directories} section of the line number program
-header. The index is 0 if the file was found in the current
-directory of the compilation, 1 if it was found in the first
-directory in the \addttindex{include\_directories} section,
-and so on. The
-directory index is ignored for file names that represent full
-path names.
-
-The primary source file is described by an entry whose path
-name exactly matches that given in the \DWATname{} attribute
-in the compilation unit, and whose directory index is 0. The
-files are numbered, starting at 1, in the order in which they
-appear; the names in the header come before names defined by
-the \DWLNEdefinefile{} instruction. These numbers are used
-in the file register of the state machine.
-
 \item \textbf{\DWLNEsetdiscriminatorTARG} \\
 The \DWLNEsetdiscriminatorTARG{}
 opcode takes a single
@@ -1123,29 +1243,12 @@ parameter, an unsigned LEB128\addtoindexx{LEB128!unsigned}
 integer. It sets the
 \addttindex{discriminator} register to the new value.
 
-\needlines{4}
-\item \textbf{\DWLNEdefinefileMDfiveTARG} \\
-The \DWLNEdefinefileMDfiveTARG{} opcode takes three operands:
-\begin{enumerate}[1. ]
-
-\item A null\dash terminated string containing the full or relative
-path name of a source file. If the entry contains a file
-name or a relative path name, the file is located relative
-to either the compilation directory (as specified by the
-\DWATcompdir{} attribute given in the compilation unit)
-or one of the directories in the 
-\addttindex{include\_directories} section.
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned} 
-number representing the directory index
-of the directory in which the file was found.  
-
-\item A 16-byte \MDfive{} digest of the file contents.
-\end{enumerate}
-The first two operands are interpreted in the same way as the 
-first two operands of \DWLNEdefinefile.
 \end{enumerate}
 
+\textit{The \texttt{DW\_LNE\_define\_file} operation defined
+in earlier versions of DWARF is deprecated in \DWARFVersionV.}
+\addtoindexx{\texttt{DW\_LNE\_define\_file}!deprecated}
+
 \textit{Appendix \refersec{app:linenumberprogramexample} 
 gives some sample line number programs.}
 
@@ -1238,7 +1341,7 @@ and for each operand there is a single unsigned byte describing the form in whic
 the operand is encoded.  The allowed forms are: 
 \DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
 \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight, 
-\DWFORMsdata, \DWFORMudata, \DWFORMflag, \DWFORMsecoffset,
+\DWFORMdatasixteen, \DWFORMsdata, \DWFORMudata, \DWFORMflag, \DWFORMsecoffset,
 \DWFORMstring, \DWFORMstrp{} and \DWFORMstrx.
 \end{enumerate}
 
@@ -1248,19 +1351,33 @@ the operand is encoded.  The allowed forms are:
 \subsection{Macro Information Entries}
 \label{chap:macroinformationentries}
 
-The following kinds of macro information entries are defined:
-
-\begin{tabular}{ll}
+The kinds of macro information entries are shown in Table \refersec{tab:macroinformationentrykinds}.
+\begin{table}[here]
+\centering
+\caption{Macro information entry kinds}
+\label{tab:macroinformationentrykinds}
+\begin{tabular}{l|p{7cm}}
+\hline
+Name&Meaning\\ \hline
 \DWMACROdefine{}            &A macro definition\\
 \DWMACROundef               &A macro undefinition\\
 \DWMACROstartfile           &The start of a new source file inclusion\\
-\DWMACROendfile             &The end of the current source file inclusion\\
+\DWMACROendfile             &The end of the current source file \mbox{inclusion}\\
 \DWMACROdefineindirect      &A macro definition (indirect name string)\\
 \DWMACROundefindirect       &A macro undefinition (indirect name string)\\
-\DWMACROtransparentinclude  &A sequence of macro information entries to include\\
+\DWMACROtransparentinclude  &A sequence of macro information \mbox{entries} to include\\
+\DWMACROdefineindirectsup   &A macro definition whose indirect name string is in the 
+                             \addtoindex{supplementary object file}\\
+\DWMACROundefindirectsup    &A macro undefinition whose indirect name string is in the 
+                             supplementary object file)\\
+\DWMACROtransparentincludesup
+                            &A sequence of macro information \mbox{entries} to include 
+                             from the \addtoindex{supplementary object file}\\
 \DWMACROdefineindirectx     &A macro definition (indexed name string)\\
 \DWMACROundefindirectx      &A macro undefinition (indexed name string)\\
+\hline
 \end{tabular}
+\end{table}
 
 \subsubsection{Define and Undefine Entries}
 \label{chap:defineandundefineentries}
@@ -1329,6 +1446,18 @@ which is interpreted as a zero-based index into an array of offsets in the
 these entries are equivalent to \DWMACROdefine{}
 and \DWMACROundef.
 
+\subsubsubsection{Define and Undefine Using Indirect Strings in a Supplementary Object File}
+A \DWMACROdefineindirectsupTARG{} or \DWMACROundefindirectsupTARG{} entry has
+two operands.  The first operand encodes the line number of the source line
+on which the relevant defining or undefining macro directives appeared.
+The second operand consists of an offset into a string table contained in
+the \dotdebugstr{} section of the \addtoindex{supplementary object file}.  
+The size of the operand is given in the section header \texttt{offset\_size} field.  
+Apart from the encoding of the second operand these entries are equivalent to
+\DWMACROdefineindirect{} and \DWMACROundefindirect{}, respectively.
+
+
+
 \subsubsection{Start File Entries}
 \label{chap:startfileentries}
 A \DWMACROstartfileTARG{} entry has two operands. The
@@ -1351,6 +1480,11 @@ A \DWMACROendfileTARG{} entry has no operands. The presence of
 the entry marks the end of the current source file inclusion.
 
 \subsubsection{Transparent Inclusion of a Sequence of Entries}
+\textit{The transparent inclusion entry types makes it possible 
+to share duplicate sequences of macro information entries among different 
+compilation units or object files.}
+
+\subsubsubsection{Transparent Inclusion within the Current Compilation}
 A \DWMACROtransparentincludeTARG{} entry has one operand, an offset into
 another part of the \dotdebugmacro{} section.  The size of the operand
 is given in the header \texttt{offset\_size} field.  The
@@ -1360,9 +1494,23 @@ after the section header at the given
 \dotdebugmacro{} offset, up to, but excluding,
 the terminating entry with opcode \texttt{0}.
 
-\textit{The \DWMACROtransparentincludeNAME{} entry type makes it possible 
-to share duplicate sequences of macro information entries among different 
-compilation units.}
+\subsubsubsection{Transparent Inclusion Across Executable and Shared Object Files}
+A \DWMACROtransparentincludesupTARG{} entry has one operand, an 
+offset from the start of the \dotdebugmacro{} section in the 
+\addtoindex{supplementary object file}.  
+The size of the operand is given in the section header offset size. 
+Apart from the different location in which to find the sequence of 
+macro  information  entries this entry type is equivalent to 
+\DWMACROtransparentinclude. This entry type is aimed at sharing duplicate 
+sequences of macro information entries between \dotdebugmacro{}
+sections from different executables or shared objects.  
+
+\needlines{4}
+From within the \dotdebugmacro{} section of the \addtoindex{supplementary object file}, 
+\DWMACROdefineindirect{} and \DWMACROundefindirect{} entry types refer to the 
+local \dotdebugstr{} section and \DWMACROtransparentinclude{} refers to the 
+local \dotdebugmacro{} section.
+
 
 \needlines{4}
 \subsection{Base Source Entries} 
index 288b25d..57444c4 100644 (file)
@@ -321,7 +321,7 @@ correctly.
 \addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8} 
 which is a \livelink{chap:classflag}{flag} whose
 presence indicates that all strings (such as the names of
-declared entities in the source program, or file names in the line table) 
+declared entities in the source program, or filenames in the line number table) 
 are represented using the UTF\dash 8 representation. 
 
 \item A \DWATmainsubprogram{} attribute, which is a \livelink{chap:classflag}{flag}
@@ -1421,6 +1421,7 @@ types and values. The exceptions are:
 \item Template parameters are described and referenced as specified in
 Section \refersec{chap:templateparameters}.
 
+\needlines{4}
 \item If the compiler has generated a special compilation unit
 to hold the template instantiation and that compilation unit
 has a different name from the compilation unit containing
@@ -1481,7 +1482,7 @@ instance (see below) is represented by a debugging information
 entry with the tag \DWTAGsubprogram. Such an entry has a
 \DWATinline{} attribute whose value is \DWINLinlined.}
 
-
+\needlines{4}
 \subsubsection{Abstract Instances}
 \label{chap:abstractinstances}
 Any debugging information entry that is owned (either
@@ -1997,6 +1998,7 @@ address is not preserved (and thus not available using the unwind information).
 A \textit{tail recursion call} is a call
 to the current subroutine which is compiled as a loop into the middle of the
 current subroutine.
+\needlines{4}
 \item
 An \textit{inline (or inlined) call} is a call to an inlined subprogram,
 where at least one instruction has the location of the inlined subprogram
@@ -2052,6 +2054,7 @@ information entry.  For indirect calls it may be a reference to a
 \DWTAGvariable{}, \DWTAGformalparameter{} or \DWTAGmember{} entry representing
 the subroutine pointer that is called.
 
+\needlines{4}
 The call site may have a 
 \DWATcalltargetNAME{}
 \livetargi{chap:DWATcalltargetofcallsite}{attribute}{call target attribute} which is
@@ -2060,6 +2063,7 @@ compile time which subprogram will be called the expression computes the
 address of the subprogram that will be called.  The DWARF expression should
 not use register or memory locations that might be clobbered by the call.
 
+\needlines{4}
 The call site entry may have a 
 \DWATcalltargetclobberedNAME{}
 \livetargi{chap:DWATcalltargetclobberedofcallsite}{attribute}{call target clobbered attribute}
index 9ca9705..b8dbc38 100644 (file)
@@ -17,7 +17,15 @@ as two byte unsigned integers.
 
 Table \refersec{tab:sectionversionnumbers}
 shows what version
-numbers are in use for each section.
+numbers are in use for each section. In that table:
+\begin{itemize}
+\setlength{\itemsep}{0em}
+\item  \doublequote{V2} means \addtoindex{DWARF Version 2}, published July 27, 1993.
+\item  \doublequote{V3} means \addtoindex{DWARF Version 3}, published December 20, 2005.
+\item  \doublequote{V4} means \addtoindex{DWARF Version 4}, published June 10, 2010.
+\item  \doublequote{V5} means \addtoindex{DWARF Version 5}\footnote{Higher numbers are reserved for future use.}, published 
+                       \ifthenelse{\boolean{isdraft}}{\textit{<to be determined>}}{\docdate}.
+\end{itemize}
 
 There are sections with no version number encoded in them;
 they are only accessed via the 
@@ -26,11 +34,15 @@ sections and so an incompatible change in those sections'
 format would be represented by a change in the 
 \dotdebuginfo{} section version number.
 
+\needlines{10}
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{lcccc}
   \caption{Section version numbers} \label{tab:sectionversionnumbers} \\
-  \hline \bfseries Section Name &\bfseries V2 &\bfseries V3 &\bfseries V4 &\bfseries V5 \\ \hline
+  \hline 
+  \bfseries Section Name &\bfseries V2 &\bfseries V3 &\bfseries V4 
+                         &\bfseries V5 \\ 
+  \hline
 \endfirsthead
    \bfseries Section Name &\bfseries V2 &\bfseries V3 &\bfseries V4 &\bfseries V5 \\ \hline
 \endhead
@@ -45,6 +57,7 @@ format would be represented by a change in the
                     & 1 & 3 & 4 & 4 \\
 \dotdebuginfo{}     & 2 & 3 & 4 & 5 \\
 \dotdebugline{}     & 2 & 3 & 4 & 5 \\
+\dotdebuglinestr{}  & - & - & - & 5 \\
 \dotdebugloc{}      & * & * & * & 5 \\
 \dotdebugmacinfo{}  & * & * & * & - \\*
 \dotdebugmacro{}    & - & - & - & 5 \\
@@ -53,6 +66,7 @@ format would be represented by a change in the
 \dotdebugranges{}   & - & * & * & 5 \\
 \dotdebugstr{}      & * & * & * & * \\
 \dotdebugstroffsets & - & - & - & 5 \\
+\dotdebugsup        & - & - & - & 5 \\
 \addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (Version 4)}
                     & - & - & 4 & - \\
 
@@ -69,27 +83,18 @@ format would be represented by a change in the
 \hspace{3.5cm}\textit{(.dwp sections)}\\
 \dotdebugcuindex{}  & - & - & - & 5 \\
 \dotdebugtuindex{}  & - & - & - & 5 \\
-
 \end{longtable}
 \end{centering}
 
+\needlines{8}
 Notes:
-
 \begin{itemize}
-\item  \doublequote{V2} means \addtoindex{DWARF Version 2}, published July 27, 1993.
-\item  \doublequote{V3} means \addtoindex{DWARF Version 3}, published December 20, 2005.
-\item  \doublequote{V4} means \addtoindex{DWARF Version 4}, published June 10, 2010.
-\item  \doublequote{V5} means \addtoindex{DWARF Version 5}, published 
-                       \ifthenelse{\boolean{isdraft}}{\textit{<to be determined>}}{\docdate}.
 \item  \doublequote{*} means that a version number is not applicable
 (the section does not include a header or the section's header does not include a version).
-
 \item  \doublequote{-} means that the section was not defined in that
 version of the DWARF standard.
-
 \item  The version numbers for corresponding .debug\_<kind> and .debug\_<kind>.dwo 
 sections are the same.
-
 \end{itemize}
-Higher numbers are reserved for future use.
+
 
index 674c753..f354441 100644 (file)
@@ -67,13 +67,24 @@ for the strings in the \dotdebugstrdwo{}{} section.
 \dotdebugmacrodwo{} - Contains macro definition information,
 normally found in the \dotdebugmacro{} section.
 \item
-\dotdebuglinedwo{} - Contains skeleton line tables for the type
-units in the \dotdebuginfodwo{} section. These line tables
-contain only the directory and files lists needed to
+\dotdebuglinedwo{} - Contains skeleton line number tables for the type
+units in the \dotdebuginfodwo{} section. These tables
+contain only the directory and filename lists needed to
 interpret \DWATdeclfile{} attributes in the debugging
 information entries. Actual line number tables remain in the
 \dotdebugline{} section, and remain in the relocatable object
 (.o) files.
+
+In a .dwo file there is no benefit to having a separate string
+section for directories and file names because the primary
+string table will never be stripped. Accordingly, no
+\texttt{.debug\_line\_str.dwo} is defined. Content descriptions corresponding
+to \DWFORMlinestrp{} in an executable file (for example, in the
+skeleton compilation unit) instead use \DWFORMstrx. This allows
+directory and file name strings to be merged with general
+strings and across compilations in package files (which are not
+subject to potential stripping).
+
 \end{itemize}
 
 In order for the consumer to locate and process the debug
index 50b1537..08d0555 100644 (file)
@@ -148,9 +148,10 @@ floating\dash point number \\
 \DWATEsignedfixedTARG{} & signed fixed\dash point scaled integer \\
 \DWATEunsignedfixedTARG& unsigned fixed\dash point scaled integer \\
 \DWATEdecimalfloatTARG{} & decimal floating\dash point number \\ 
-\DWATEUTFTARG{} & \addtoindex{Unicode} character \\
-\DWATEASCIITARG{} & \addtoindex{ASCII} character \\
-\DWATEUCSTARG{} & \addtoindex{ISO 10646} character \\
+\DWATEUTFTARG{} & \addtoindexi{Unicode character}{Unicode character base type} \\
+\DWATEASCIITARG{} & \addtoindexi{ASCII character}{ASCII character base type}\\
+\DWATEUCSTARG{} & \addtoindexi{ISO 10646 character}{ISO 10646 character base type}
+                  \addtoindexx{ISO 10646 character set standard}  \\
 \hline
 \end{tabular}
 \end{table}
@@ -161,15 +162,19 @@ exponent, such as that specified in IEEE 754R.}
 
 \textit{The \DWATEUTF{} encoding is intended for \addtoindex{Unicode}
 string encodings (see the Universal Character Set standard,
-ISO/IEC 10646\dash 1:1993). For example, the 
+ISO/IEC 10646\dash 1:1993).
+ \addtoindexx{ISO 10646 character set standard}
+For example, the 
 \addtoindex{C++} type char16\_t is
 represented by a base type entry with a name attribute whose
 value is \doublequote{char16\_t}, an encoding attribute whose value
 is \DWATEUTF{} and a byte size attribute whose value is 2.}
 
 \textit{The \DWATEASCII{} and \DWATEUCS{} encodings are intended for
-the {Fortran 2003} string kinds \texttt{ASCII} (ISO/IEC 646:1991) and
-\texttt{ISO\_10646} (UCS-4 in ISO//IEC 10646:2000).}
+the {Fortran 2003} string kinds 
+\texttt{ASCII}\index{ASCII@\texttt{ASCII} (Fortran string kind)} (ISO/IEC 646:1991) and
+\texttt{ISO\_10646}\index{ISO\_10646@\texttt{ISO\_10646} (Fortran string kind)} (UCS-4 in ISO/IEC 10646:2000).}
+\addtoindexx{ISO 10646 character set standard}
 
 The 
 \DWATEpackeddecimal{} 
@@ -1876,8 +1881,12 @@ it appears in the source program.
 \addtoindex{Fortran 2003} language standard allows string 
 types that are composed of different types of (same sized) characters. 
 While there is no standard list of character kinds, the kinds
-\addttindex{ASCII} (see \DWATEASCII), \addttindex{ISO\_10646}
-(see \DWATEUCS) and \texttt{DEFAULT} are defined.}
+\texttt{ASCII}\index{ASCII@\texttt{ASCII} (Fortran string kind)} (see \DWATEASCII), 
+\texttt{ISO\_10646}\index{ISO\_10646@\texttt{ISO\_10646} (Fortran string kind)}
+\addtoindexx{ISO 10646 character set standard}
+(see \DWATEUCS) and 
+\texttt{DEFAULT}\index{DEFAULT@\texttt{DEFAULT} (Fortran string kind)}
+are defined.}
 
 A string type entry may have a \DWATtype{} 
 \livetargi{char:DWAATtypeofstringtype}{attribute}{type attribute!of string type entry}