Bring up to date with the February 2015 meeting and the
authorRon Brender <ron.brender@gmail.com>
Wed, 4 Mar 2015 20:15:05 +0000 (15:15 -0500)
committerRon Brender <ron.brender@gmail.com>
Wed, 4 Mar 2015 20:15:05 +0000 (15:15 -0500)
review version distributed on March 4, 2015.

Signed-off-by: Ron Brender <ron.brender@gmail.com>
15 files changed:
dwarf5/latexdoc/acceleratednameaccessdiagram.png [new file with mode: 0644]
dwarf5/latexdoc/attributesbytag.tex
dwarf5/latexdoc/changesummary.tex
dwarf5/latexdoc/copyright.tex
dwarf5/latexdoc/datarepresentation.tex
dwarf5/latexdoc/debugsectionrelationships.tex
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/dwarfnamecmds.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

diff --git a/dwarf5/latexdoc/acceleratednameaccessdiagram.png b/dwarf5/latexdoc/acceleratednameaccessdiagram.png
new file mode 100644 (file)
index 0000000..94d6a14
Binary files /dev/null and b/dwarf5/latexdoc/acceleratednameaccessdiagram.png differ
index 33df5c4..a172b03 100644 (file)
@@ -143,6 +143,7 @@ means include all three of the
 &\DWATassociated{} \\
 &\DWATbitsize{} \\
 &\DWATbytesize{} \\
+&\DWATcallingconvention{} \\
 &\DWATdatalocation{} \\
 &\DWATdeclaration{} \\
 &\DWATdescription{} \\
@@ -645,6 +646,7 @@ means include all three of the
 &\DWATassociated{}  \\
 &\DWATbitsize{}  \\
 &\DWATbytesize{}  \\
+&\DWATcallingconvention{} \\
 &\DWATdatalocation{}  \\
 &\DWATdeclaration{}  \\
 &\DWATdescription{}  \\
@@ -666,6 +668,8 @@ means include all three of the
 &\DWATartificial{}  \\
 &\DWATcallingconvention{}  \\
 &\DWATdeclaration{}  \\
+&\DWATdefaulted{} \\
+&\DWATdeleted{} \\
 &\DWATdescription{}  \\
 &\DWATelemental{}  \\
 &\DWATentrypc{}  \\
@@ -834,6 +838,7 @@ means include all three of the
 &\DWATassociated{}   \\
 &\DWATbitsize{}   \\
 &\DWATbytesize{}   \\
+&\DWATcallingconvention{} \\
 &\DWATdatalocation{}   \\
 &\DWATdeclaration{}   \\
 &\DWATdescription{}   \\
index 96b2c66..7f1df95 100644 (file)
@@ -15,7 +15,10 @@ 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
-12/28/2014      & 141121.1 Fortran language codes), 141212.1 (inline/export symbols), \\
+3/3/2015        & 150108.1 (accelerated access) \\
+3/1/2015        & 141215.2 (deleted member functions), 141215.3 (defaulted member functions) \\
+1/24/2015       & 141215.1 (calling convention codes for types), 141215.4 (DW\_FORM\_implicit\_const) \\
+12/28/2014      & 141121.1 (Fortran language codes), 141212.1 (inline/export symbols), \\
                 & Editorial cleanups \& corrections \\
 11/20/2014      & Editorial corrections for 100831.1 and 110722.1 \\
 11/19/2014      & Editorial corrections in Appendix F.2 \\
index 09150a7..4f424cf 100644 (file)
@@ -7,7 +7,7 @@
 \begin{center}
 \dwf, Version 5
 
-Copyright\copyright 2010, 2014 \dwf\ Committee
+Copyright\copyright 2005, 2010, 2015 \dwf\ Committee
 \end{center}
 
 \vspace{4ex}
index 916b095..c3564da 100644 (file)
@@ -105,14 +105,13 @@ not appear in DWARF debugging information.
 \addtoindexx{reserved values!initial length}
 
 An \livetarg{datarep:initiallengthvalues}{initial length} field 
-\addtoindex{initial length field|see{initial length}}
-is one of the length fields that occur at the beginning 
+\addtoindexx{initial length field|see{initial length}}
+is one of the fields that occur at the beginning 
 of those DWARF sections that have a header
 (\dotdebugaranges{}, 
 \dotdebuginfo{}, 
-\dotdebugline{},
-\dotdebugpubnames{}, and 
-\dotdebugpubtypes{}) or the length field
+\dotdebugline{} and
+\dotdebugnames{}) or the length field
 that occurs at the beginning of the CIE and FDE structures
 in the \dotdebugframe{} section.
 
@@ -205,7 +204,7 @@ of the program, and requires relocation.
  The \dotdebugstroffsets{} section contains a list of string offsets,
 each of which is an offset of a string in the \dotdebugstr{} section. Each
 of these offsets requires relocation. Depending on the implementation,
-these relocations may be implicit (i.e., the producer may not need to
+these relocations may be implicit (that is, the producer may not need to
 emit any explicit relocation information for these offsets).
 \end{itemize}
 
@@ -222,7 +221,7 @@ and includes the following:
 The line number tables, range tables, frame tables, and
 accelerated access tables, in the usual sections:
 \dotdebugline, \dotdebuglinestr, \dotdebugranges, \dotdebugframe,
-\dotdebugpubnames, \dotdebugpubtypes{} and \dotdebugaranges,
+\dotdebugnames{} and \dotdebugaranges,
 respectively.
 \needlines{4}
 \item
@@ -336,6 +335,7 @@ corresponding application binary. It consists only of a file
 header, section table, a number of DWARF debug information
 sections, and two index sections.
 
+\needlines{5}
 Each DWARF package file contains no more than one of each of the
 following sections, copied from a set of object or DWARF object
 files, and combined, section by section:
@@ -650,31 +650,22 @@ in the headers of DWARF sections (other than initial length
 \addtoindexx{initial length}
 fields) are listed following. In the 32\dash bit DWARF format these
 are 32\dash bit unsigned integer values; in the 64\dash bit DWARF format,
-they 
-\addtoindexx{section length!in .debug\_aranges header}
-are 
-\addtoindexx{section length!in .debug\_pubnames header}
-64\dash bit 
-\addtoindexx{section length!in .debug\_pubtypes header}
-unsigned integer values.
+they are 64\dash bit unsigned integer values.
 
 \begin{center}
 \begin{tabular}{lll}
 Section &Name & Role  \\ \hline
-\dotdebugaranges{} & \addttindex{debug\_info\_offset} & offset in \dotdebuginfo{} \\
-\dotdebugframe{}/CIE & \addttindex{CIE\_id} & CIE distinguished value \\
-\dotdebugframe{}/FDE & \addttindex{CIE\_pointer} & offset in \dotdebugframe{} \\
-\dotdebuginfo{} & \addttindex{debug\_abbrev\_offset} & offset in \dotdebugabbrev{} \\
-\dotdebugline{} & \addttindex{header\_length} & length of header itself \\
-\dotdebugpubnames{} & \addttindex{debug\_info\_offset} & offset in \dotdebuginfo{} \\
-                & \addttindex{debug\_info\_length} & length of \dotdebuginfo{} \\
-                &                   & contribution \\
-\dotdebugpubtypes{} & \addttindex{debug\_info\_offset} & offset in \dotdebuginfo{} \\
-                & \addttindex{debug\_info\_length} & length of \dotdebuginfo{} \\
-                &                   & contribution \\
+\dotdebugaranges{}   & \addttindex{debug\_info\_offset}   & offset in \dotdebuginfo{} \\
+\dotdebugframe{}/CIE & \addttindex{CIE\_id}               & CIE distinguished value \\
+\dotdebugframe{}/FDE & \addttindex{CIE\_pointer}          & offset in \dotdebugframe{} \\
+\dotdebuginfo{}      & \addttindex{debug\_abbrev\_offset} & offset in \dotdebugabbrev{} \\
+\dotdebugline{}      & \addttindex{header\_length}        & length of header itself \\
+\dotdebugnames{}     & entry in array of CUs              & offset in \dotdebuginfo{} \\
+                     & or local TUs                       & \\
 \end{tabular}
 \end{center}
 
+\needlines{4}
 The \texttt{CIE\_id} field in a CIE structure must be 64 bits because
 it overlays the \texttt{CIE\_pointer} in a FDE structure; this implicit
 union must be accessed to distinguish whether a CIE or FDE is
@@ -713,13 +704,13 @@ Form             & Role  \\ \hline
 \end{tabular}
 \end{center}
 
-\item Within the body of the \dotdebugpubnames{} and
-\dotdebugpubtypes{} 
-sections, the representation of the first field
-of each tuple (which represents an offset in the 
+\item Within the body of the \dotdebugnames{} 
+sections, the representation of each entry in the array of
+compilation units (CUs) and the array of local type units
+(TUs), which represents an offset in the 
 \dotdebuginfo{}
-section) depends on the DWARF format as follows: in the
-32\dash bit DWARF format, this field is a 32\dash bit unsigned integer;
+section, depends on the DWARF format as follows: in the
+32\dash bit DWARF format, each entry is a 32\dash bit unsigned integer;
 in the 64\dash bit DWARF format, it is a 64\dash bit unsigned integer.
 
 \needlines{4}
@@ -1173,6 +1164,12 @@ to choose forms for particular attributes
 dynamically,
 without having to add a new entry to the abbreviations table.
 
+The attribute form \DWFORMimplicitconstTARG{} is another special case.
+For attributes with this form, the attribute specification contains 
+a third part, which is a signed LEB128\addtoindexx{LEB128!signed} 
+number. The value of this number is used as the value of the 
+attribute, and no value is stored in the \dotdebuginfo{} section.
+
 The abbreviations for a given compilation unit end with an
 entry consisting of a 0 byte for the abbreviation code.
 
@@ -1289,7 +1286,7 @@ debugging information entries or data bytes.
 
 \item \livelinki{chap:classconstant}{constant}{constant class} \\
 \livetarg{datarep:classconstant}{}
-There are seven forms of constants. There are fixed length
+There are eight forms of constants. There are fixed length
 constant data forms for one-, two-, four-, eight- and sixteen-byte values
 (respectively, 
 \DWFORMdataoneTARG, 
@@ -1298,10 +1295,12 @@ constant data forms for one-, two-, four-, eight- and sixteen-byte values
 \DWFORMdataeightTARG{} and
 \DWFORMdatasixteenTARG). 
 There are also variable length constant
-data forms encoded using LEB128 numbers (see below). Both
-signed (\DWFORMsdataTARG) and unsigned 
-(\DWFORMudataTARG) variable
-length constants are available
+data forms encoded using LEB128 numbers (see below). 
+Both signed (\DWFORMsdataTARG) and unsigned 
+(\DWFORMudataTARG) variable length constants are available.
+There is also an implicit constant (\DWFORMimplicitconst),
+whose value is provided as part of the abbreviation
+declaration.
 
 \needlines{4}
 The data in \DWFORMdataone, 
@@ -1548,11 +1547,11 @@ 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{}  
+(\DWFORMstrpsupTARG).  \DWFORMstrpsupNAME{} 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{}
+\DWFORMstrpNAME{}, \DWFORMstrpNAME{} or \DWFORMstrpsupNAME{}
 value is a 4\dash byte unsigned offset; in the \sixtyfourbitdwarfformat,
 it is an 8\dash byte unsigned offset 
 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
@@ -1923,6 +1922,8 @@ Table \refersec{tab:attributeformencodings}.
         \addtoindexx{alignment attribute} \\
 \DWATexportsymbols~\ddag &0x89 &\CLASSflag
         \addtoindexx{export symbols attribute} \\
+\DWATdeleted~\ddag &0x8a &\CLASSflag \addtoindexx{deleted attribute} \\
+\DWATdefaulted~\ddag &0x8b &\CLASSconstant \addtoindexx{defaulted attribute} \\
 \DWATlouser&0x2000 & --- \addtoindexx{low user attribute encoding}  \\
 \DWAThiuser&\xiiifff& --- \addtoindexx{high user attribute encoding}  \\
 
@@ -1974,8 +1975,9 @@ Table \refersec{tab:attributeformencodings}.
 \DWFORMrefsup{}~\ddag &0x1c &\livelink{chap:classreference}{reference} \\
 \DWFORMstrpsup{}~\ddag &0x1d &\livelink{chap:classstring}{string} \\
 \DWFORMdatasixteen~\ddag &0x1e &\CLASSconstant \\
+\DWFORMlinestrp~\ddag &0x1f &\CLASSstring \\
 \DWFORMrefsigeight &0x20 &\livelink{chap:classreference}{reference} \\
-
+\DWFORMimplicitconst~\ddag &0x21 &\CLASSconstant \\
 \end{longtable}
 \end{centering}
 
@@ -2618,13 +2620,15 @@ Table \refersec{tab:callingconventionencodings}.
 \endhead
   \hline \emph{Continued on next page}
 \endfoot
-  \hline
+  \hline \ddag\ \textit{New in DWARF Version 5}
 \endlastfoot
 
-\DWCCnormal&0x01     \\
+\DWCCnormal &0x01     \\
 \DWCCprogram&0x02     \\
-\DWCCnocall&0x03     \\
-\DWCClouser&0x40     \\
+\DWCCnocall &0x03     \\
+\DWCCpassbyreference~\ddag &0x04 \\
+\DWCCpassbyvalue~\ddag     &0x05 \\
+\DWCClouser &0x40     \\
 \DWCChiuser&\xff     \\
 
 \end{longtable}
@@ -2725,71 +2729,92 @@ Table \refersec{tab:discriminantdescriptorencodings}.
 \end{centering}
 
 \needlines{6}
-\section{Name Lookup Tables}
-\label{datarep:namelookuptables}
-
-Each set of entries in the table of global names contained
-in the \dotdebugpubnames{} and 
-\dotdebugpubtypes{} sections begins
-with a header consisting of:
+\section{Name Index Table}
+\label{datarep:nameindextable}
+Each name index table in the \dotdebugnames{} section 
+begins with a header consisting of:
 \begin{enumerate}[1. ]
-
 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
 \addttindexx{unit\_length}
-A 4\dash byte or 12\dash byte unsigned integer 
-\addtoindexx{initial length}
-representing the length
-of the \dotdebuginfo{}
-contribution for that compilation unit,
-not including the length field itself. In the 
-\thirtytwobitdwarfformat, this is a 4\dash byte unsigned integer (which must be less
-than \xfffffffzero); in the \sixtyfourbitdwarfformat, this consists
-of the 4\dash byte value \wffffffff followed by an 8\dash byte unsigned
-integer that gives the actual length
-(see Section \refersec{datarep:32bitand64bitdwarfformats}).
+A 4-byte or 12-byte initial length field that 
+contains the size in bytes of this contribution to the \dotdebugnames{} 
+section, not including the length field itself
+(see Section \refersec{datarep:initiallengthvalues}).
 
-\item  version (\addtoindex{uhalf}) \\
-A 2\dash byte unsigned integer representing the version of the
-DWARF information for the name lookup table
-\addtoindexx{version number!name lookup table}
-(see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
-The value in this field is 2.
+\item \texttt{version} (\addtoindex{uhalf}) \\
+A 2-byte version number\addtoindexx{version number!name index table} 
+(see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
+This number is specific to the name index table and is
+independent of the DWARF version number.
 
-\needlines{4}
-\item \addttindex{debug\_info\_offset} (section offset) \\
-A 
-\addtoindexx{section offset!in name lookup table set of entries}
-4\dash byte or 8\dash byte 
-offset into the 
-\dotdebuginfo{} or \dotdebuginfodwo{}
-section of the compilation unit header.
-In the \thirtytwobitdwarfformat, this is a 4\dash byte unsigned offset;
-in the \sixtyfourbitdwarfformat, this is an 8\dash byte unsigned offsets
-(see Section \refersec{datarep:32bitand64bitdwarfformats}).
+The value in this field is \versiondotdebugnames.
 
-\item  \addttindex{debug\_info\_length} (\livelink{datarep:sectionoffsetlength}{section length}) \\
-\addtoindexx{section length!in .debug\_pubnames header}
-A 
-\addtoindexx{section length!in .debug\_pubtypes header}
-4\dash byte or 8\dash byte length containing the size in bytes of the
-contents of the \dotdebuginfo{}
-section generated to represent
-this compilation unit. In the \thirtytwobitdwarfformat, this is
-a 4\dash byte unsigned length; in the \sixtyfourbitdwarfformat, this
-is an 8-byte unsigned length 
-(see Section \refersec{datarep:32bitand64bitdwarfformats}).
+\item padding (\addtoindex{uhalf}) \\
+
+\item \texttt{comp\_unit\_count} (4-byte unsigned integer) \\
+The number of CUs in the CU list.
 
+\item \texttt{local\_type\_unit\_count} (4-byte unsigned integer) \\
+The number of TUs in the first TU list.
+
+\item \texttt{foreign\_type\_unit\_count} (4-byte unsigned integer) \\
+The number of TUs in the second TU list.
+
+\item \texttt{bucket\_count} (4-byte unsigned integer) \\
+The number of hash buckets in the hash lookup table. 
+If there is no hash lookup table, this field contains 0.
+
+\item \texttt{name\_count} (4-byte unsigned integer) \\
+The number of unique names in the index.
+
+\item \texttt{abbrev\_table\_size} (4-byte unsigned integer) \\
+The size in bytes of the abbreviations table.
+
+\item \texttt{augmentation\_string\_size} (4-byte unsigned integer) \\
+The size in bytes of the augmentation string. This value should be
+rounded up to a multiple of 4.
+
+\item \texttt{augmentation\_string} (sequence of characters) \\
+A vendor-specific augmentation string, which provides additional 
+information about the contents of this index. If provided, the string
+should begin with a 4-byte vendor ID. The remainder of the
+string is meant to be read by a cooperating consumer, and its
+contents and interpretation are not specified here. The
+string should be padded with null characters to a multiple of
+four bytes in length.
 
 \end{enumerate}
 
-This header is followed by a series of tuples. Each tuple
-consists of a 4\dash byte or 8\dash byte offset followed by a string
-of non\dash null bytes terminated by one null byte. 
-In the 32\dash bit
-DWARF format, this is a 4\dash byte offset; in the 64\dash bit DWARF
-format, it is an 8\dash byte offset. 
-Each set is terminated by an
-offset containing the value 0.
+The index attributes and their encodings are listed in Table \referfol{datarep:indexattributeencodings}.
+
+\begin{centering}
+\setlength{\extrarowheight}{0.1cm}
+\begin{longtable}{l|c|l}
+  \caption{Index attribute encodings} \label{datarep:indexattributeencodings}\\
+  \hline \bfseries Attribute name&\bfseries Value &\bfseries Form/Class \\ \hline
+\endfirsthead
+  \bfseries Attribute name&\bfseries Value &\bfseries Form/Class \\ \hline
+\endhead
+  \hline \emph{Continued on next page}
+\endfoot
+  \hline
+  \ddag \ \textit{New in \DWARFVersionV}
+\endlastfoot
+\DWIDXcompileunit~\ddag & 1        & \CLASSconstant \\
+\DWIDXtypeunit~\ddag    & 2        & \CLASSconstant \\
+\DWIDXdieoffset~\ddag   & 3        & \CLASSreference \\
+\DWIDXparent~\ddag      & 4        & \CLASSconstant \\
+\DWIDXtypehash~\ddag    & 5        & \DWFORMdataeight \\
+\DWIDXlouser~\ddag      & 0x2000   & \\
+\DWIDXhiuser~\ddag      & \xiiifff & \\
+\end{longtable}
+\end{centering}
+
+The abbreviations table ends with an entry consisting of a single 0
+byte for the abbreviation code. The size of the table given by
+\texttt{abbrev\_table\_size} may include optional padding following the
+terminating 0 byte.
+
 
 
 \needlines{10}
@@ -2819,9 +2844,9 @@ the actual length
 A 2\dash byte version identifier representing the version of the
 DWARF information for the address range table
 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
+
 This value in this field \addtoindexx{version number!address range table} is 2. 
  
-
 \item debug\_info\_offset (\livelink{datarep:sectionoffsetlength}{section offset}) \\
 A 
 \addtoindexx{section offset!in .debug\_aranges header}
@@ -2879,6 +2904,8 @@ used by the line number information program are encoded
 as a single byte containing the value 0 
 for \doublequote{false,} and a non-zero value for \doublequote{true.}
 
+\clearpage
+\needlines{10}
 The encodings for the standard opcodes are given in 
 \addtoindexx{line number opcodes!standard opcode encoding}
 Table \refersec{tab:linenumberstandardopcodeencodings}.
@@ -2913,13 +2940,11 @@ Table \refersec{tab:linenumberstandardopcodeencodings}.
 \end{longtable}
 \end{centering}
 
-
 \needspace{6cm}
 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}
@@ -2944,6 +2969,7 @@ Table \refersec{tab:linenumberextendedopcodeencodings}.
 \end{longtable}
 \end{centering}
 
+\clearpage
 \needspace{6cm}
 The encodings for the line number header entry formats are given in 
 \addtoindexx{line number opcodes!file entry format encoding}
@@ -3309,8 +3335,7 @@ in the
 \dotdebuglinestr{},
 \dotdebugloc{}, 
 \dotdebugmacro{},
-\dotdebugpubnames{}, 
-\dotdebugpubtypes{}, 
+\dotdebugnames{}, 
 \dotdebugranges{}, 
 \dotdebugstr{},
 and
index 40c0bc7..e4f83e0 100644 (file)
@@ -30,8 +30,7 @@ or sharable file and a related \addtoindex{supplementary object file}.}
                                      \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 
+                                     \dotdebugnames  
                                      \end{tabular}};
 
 \draw[thick,-to reversed]              (zlinka) -- (zsectara);
@@ -162,7 +161,7 @@ corresponding compilation unit header (not the compilation
 unit entry).
 
 %b
-\item \dotdebugpubnames{} and \dotdebugpubtypes{} to \dotdebuginfo \\
+\item \dotdebugnames{} to \dotdebuginfo \\
 The \texttt{debug\_info\_offset} value in the header is the offset in the
 \dotdebuginfo{} section of the 
 corresponding compilation unit header (not
index abd689c..d69fd43 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}{December 28, 2014}
+\newcommand{\docdate}{March 4, 2015}
 %
 \usepackage{ifthen}
 \newboolean{isdraft}
@@ -22,7 +22,7 @@
 %\renewcommand{\familydefault}{phv}  % font family helvetica
 %
 
-\usepackage{url}              % For color in letters. Links instead?
+\usepackage{url}          % For color in letters. Links instead?
 \usepackage[usenames]{color} % For color in letters. Links instead?
 \usepackage{ellipsis}     % Provides ... as \dots
 %\usepackage{color}
@@ -300,9 +300,9 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \include{generaldescription}            %\emptypage
 \include{programscope}                  %\emptypage
 \include{dataobject}                    %\emptypage
-\include{typeentries}                   %\emptypage
+\include{typeentries}                   \emptypage
 \include{otherdebugginginformation}    \emptypage
-\include{datarepresentation}            \emptypage
+\include{datarepresentation}            %\emptypage
 
 %  The \appendix toggles us into appendix chapters
 \appendix
index 8b64723..c3ba0fb 100644 (file)
@@ -79,7 +79,9 @@
 \newdwfnamecommands{DWATdeclfile}{DW\_AT\_decl\_file}
 \newdwfnamecommands{DWATdeclline}{DW\_AT\_decl\_line}
 \newdwfnamecommands{DWATdeclaration}{DW\_AT\_declaration}
+\newdwfnamecommands{DWATdefaulted}{DW\_AT\_defaulted}
 \newdwfnamecommands{DWATdefaultvalue}{DW\_AT\_default\_value}
+\newdwfnamecommands{DWATdeleted}{DW\_AT\_deleted}
 \newdwfnamecommands{DWATdescription}{DW\_AT\_description}
 \newdwfnamecommands{DWATdigitcount}{DW\_AT\_digit\_count}
 \newdwfnamecommands{DWATdiscr}{DW\_AT\_discr}
 \newdwfnamecommands{DWCClouser}{DW\_CC\_lo\_user}
 \newdwfnamecommands{DWCCnocall}{DW\_CC\_nocall}
 \newdwfnamecommands{DWCCnormal}{DW\_CC\_normal}
+\newdwfnamecommands{DWCCpassbyreference}{DW\_CC\_pass\_by\_reference}
+\newdwfnamecommands{DWCCpassbyvalue}{DW\_CC\_pass\_by\_value}
 \newdwfnamecommands{DWCCprogram}{DW\_CC\_program}
+
 %
 % DW_CFA
 %
 \newdwfnamecommands{DWCHILDRENno}{DW\_CHILDREN\_no}
 \newdwfnamecommands{DWCHILDRENyes}{DW\_CHILDREN\_yes}
 %
+% DW_DEFAULTED
+%
+\newdwfnamecommands{DWDEFAULTEDinclass}{DW\_DEFAULTED\_in\_class}
+\newdwfnamecommands{DWDEFAULTEDno}{DW\_DEFAULTED\_no}
+\newdwfnamecommands{DWDEFAULTEDoutofclass}{DW\_DEFAULTED\_out\_of\_class}
+%
 % DW_DS
 %
 \newdwfnamecommands{DWDSleadingoverpunch}{DW\_DS\_leading\_overpunch}
 \newdwfnamecommands{DWFORMexprloc}{DW\_FORM\_exprloc}
 \newdwfnamecommands{DWFORMflag}{DW\_FORM\_flag}
 \newdwfnamecommands{DWFORMflagpresent}{DW\_FORM\_flag\_present}
+\newdwfnamecommands{DWFORMimplicitconst}{DW\_FORM\_implicit\_const}
 \newdwfnamecommands{DWFORMindirect}{DW\_FORM\_indirect}
 \newdwfnamecommands{DWFORMlinestrp}{DW\_FORM\_line\_strp}
 \newdwfnamecommands{DWFORMrefn}{DW\_FORM\_ref<n>}                      % Generic DW_FORM_ref[1248] name
 \newdwfnamecommands{DWIDdowncase}{DW\_ID\_down\_case}
 \newdwfnamecommands{DWIDupcase}{DW\_ID\_up\_case}
 %
+% DW_IDX
+%
+\newdwfnamecommands{DWIDXcompileunit}{DW\_IDX\_cpmpile\_unit}
+\newdwfnamecommands{DWIDXtypeunit}{DW\_IDX\_type\_unit}
+\newdwfnamecommands{DWIDXdieoffset}{DW\_IDX\_die\_offset}
+\newdwfnamecommands{DWIDXparent}{DW\_IDX\_parent}
+\newdwfnamecommands{DWIDXtypehash}{DW\_IDX\_type\_hash}
+\newdwfnamecommands{DWIDXlouser}{DW\_IDX\_lo\_user}
+\newdwfnamecommands{DWIDXhiuser}{DW\_IDX\_hi\_user}
+%
 % DW_INL
 %
 \newdwfnamecommands{DWINLdeclaredinlined}{DW\_INL\_declared\_inlined}
 \newcommand{\dotdebugloc}{\addtoindex{\texttt{.debug\_loc}}}
 \newcommand{\dotdebugmacinfo}{\addtoindex{\texttt{.debug\_macinfo}}}
 \newcommand{\dotdebugmacro}{\addtoindex{\texttt{.debug\_macro}}}
+\newcommand{\dotdebugnames}{\addtoindex{\texttt{.debug\_names}}}
 \newcommand{\dotdebugpubnames}{\addtoindex{\texttt{.debug\_pubnames}}}
 \newcommand{\dotdebugpubtypes}{\addtoindex{\texttt{.debug\_pubtypes}}}
 \newcommand{\dotdebugranges}{\addtoindex{\texttt{.debug\_ranges}}}
 \newcommand{\versiondotdebugline}    {5}
 \newcommand{\versiondotdebugloc}     {5}
 \newcommand{\versiondotdebugmacro}   {5}
+\newcommand{\versiondotdebugnames}   {5}
 \newcommand{\versiondotdebugpubnames}{2}
 \newcommand{\versiondotdebugpubtypes}{2}
 \newcommand{\versiondotdebugranges}  {5}
index 77b94f6..14498fa 100644 (file)
@@ -248,9 +248,12 @@ The attributes are listed in Table \referfol{tab:attributenames}.
            {Line number of inlined subroutine call}
            {line number of inlined subroutine call} \\
 \DWATcallingconventionTARG{} 
-&\livelinki{chap:DWATcallingconventionsubprogramcallingconvention}
-           {Subprogram calling convention}
-           {subprogram calling convention} \\
+&\livelinki{chap:DWATcallingconventionforsubprograms}
+           {Calling convention for subprograms}
+           {Calling convention!for subprograms} \\
+&\livelinki{chap:DWATcallingconventionfortypes}
+           {Calling convention for types}
+           {Calling convention!for types} \\
 \DWATcalloriginTARG{}
 &\livelinki{chap:DWATcalloriginofcallsite}
            {Subprogram called in a call}
@@ -326,8 +329,12 @@ The attributes are listed in Table \referfol{tab:attributenames}.
 &\livelinki{chap:DWATdecllinelinenumberofsourcedeclaration}{Line number of source declaration}{line number of source declaration} \\
 \DWATdeclarationTARG
 &\livelinki{chap:DWATdeclarationincompletenondefiningorseparateentitydeclaration}{Incomplete, non-defining, or separate entity declaration}{incomplete, non-defining, or separate entity declaration} \\
+\DWATdefaultedTARG
+&\livelinki{chap:DWATdefaulted}{Whether a member function has been declared as default}{defaulted attribute} \\
 \DWATdefaultvalueTARG
 &\livelinki{chap:DWATdefaultvaluedefaultvalueofparameter}{Default value of parameter}{default value of parameter} \\
+\DWATdeletedTARG
+&\livelinki{chap:DWATdeleted}{Whether a member has been declared as deleted}{Deletion of member function} \\
 \DWATdescriptionTARG{} 
 &\livelinki{chap:DWATdescriptionartificialnameordescription}{Artificial name or description}{artificial name or description} \\
 \DWATdigitcountTARG
index 2601ddd..e0948e7 100644 (file)
@@ -163,18 +163,23 @@ This enhances DWARF support for very large programs by saving space
 and improving link times.
 \item Replace the \dotdebugmacinfo{} macro information representation with
 a much more compact \dotdebugmacro{} representation.
+\item Replace the \dotdebugpubnames{} and \dotdebugtypes{} section
+with a single and more functional name index section, \dotdebugnames{}.
 \item Add a new debugging information entry, related attributes and
 DWARF expression operators, to describe call information, 
 including identification of tail calls and tail recursion.
 This facilitates debugging optimized code.
-\item Add a new attribute, \DWATnoreturnNAME{}, to identify a subprogram that 
-does not return to its caller.
-\item Add a new attribute, \DWATrankNAME{}, to describe the dimensionality of
-an array with dynamic rank.
+\item Add a new attribute, \DWATnoreturnNAME{}, to identify 
+a subprogram that does not return to its caller.
+\item Add a new attribute, \DWATrankNAME{}, to describe the 
+dimensionality of an array with dynamic rank.
 \item Add a new tag, \DWTAGgenericsubrangeNAME{}, to describe the
 bounds of Fortran assumed-rank arrays.
-\item Add language codes for C 2011, C++ 2003, C++ 2011, Dylan, Go, Haskell, 
+\item Add language codes for C 2011, C++ 2003, C++ 2011, C++ 2014,
+Dylan, Fortran 2003, Fortran 2008, Go, Haskell, 
 Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
+\item Numerous other more minor additions to improve functionality
+and performance.
 \end{itemize}
 
 DWARF Version 5 is compatible with DWARF Version 4 except as follows:
index 17d513e..70644e8 100644 (file)
@@ -67,113 +67,487 @@ entries owned by a particular compilation unit entry in a
 more condensed format.
 
 \subsection{Lookup by Name}
-
-For lookup by name, 
 \addtoindexx{lookup!by name}
-two tables are maintained in separate
 \addtoindexx{accelerated access!by name}
-object file sections named 
-\dotdebugpubnames{} for objects and
-functions, and 
-\dotdebugpubtypes{}
-for types. Each table consists
-of sets of variable length entries. Each set describes the
-names of global objects and functions, or global types,
-respectively, whose definitions are represented by debugging
-information entries owned by a single compilation unit.
-
-\textit{\addtoindex{C++} member functions with a definition in the class declaration
-are definitions in every compilation unit containing the
-class declaration, but if there is no concrete out\dash of\dash line
-instance there is no need to have a 
-\dotdebugpubnames{} entry
-for the member function.}
-
-Each set begins with a header containing four values:
-\begin{enumerate}[1. ]
+For lookup by name, a name index is maintained in a separate
+object file section named \dotdebugnames{}. 
+
+\textit{The \dotdebugnames{} section is new in \DWARFVersionV,
+and supersedes the \dotdebugpubnames{} and \dotdebugpubtypes{}
+sections of earlier DWARF versions. While \dotdebugnames{} and
+either \dotdebugpubnames{} and/or \dotdebugpubtypes{} sections
+cannot both occur in the same compilation unit, both may be
+found in the set of units that make up an executable or shared
+object.}
+
+The index consists
+primarily of two parts: a list of names, and a list of index
+entries. A name, such as a subprogram name, type name, or
+variable name, may have several defining declarations in the
+debugging information. In this case, the entry for that name in
+the list of names will refer to a sequence of index entries in
+the second part of the table, each corresponding to one defining
+declaration in the \dotdebuginfo{} section.
+
+The name index may also contain an optional hash table for faster
+lookup.
+
+\subsubsection{Contents of the Name Index}
+\label{chap:contentsofthenameindex}
+The name index must contain an entry for each DIE that defines a
+named subprogram, label, variable, type, or namespace, subject to
+the following rules:
+\begin{itemize}
+
+\item All non-defining declarations (that is, DIEs with a
+      \DWATdeclaration{} attribute) are excluded.
+
+\item \DWTAGnamespace{} DIEs without a \DWATname{} attribute are
+      included with the name \doublequote{\texttt{(anonymous namespace)}}.
+
+\item All other DIEs without a \DWATname{} attribute are excluded.
+
+\item \DWTAGsubprogram{}, \DWTAGinlinedsubroutine{}, and
+      \DWTAGlabel{} DIEs without an address attribute (\DWATlowpc{},
+      \DWAThighpc{}, \DWATranges{}, or \DWATentrypc{}) are excluded.
+
+\item \DWTAGvariable{} DIEs with a \DWATlocation{} attribute that
+      includes a \DWOPaddr{} or \DWOPformtlsaddress{} operator are
+      included; otherwise, they are excluded.
+
+\item If a subprogram or inlined subroutine is included, and has a
+      \DWATlinkagename{} attribute, there will be an additional
+      index entry for the linkage name.
+      
+\end{itemize}
+
+For the purposes of determining whether a DIE has a particular
+attribute (such as \DWATname{}), if DIE A has a \DWATspecification{}
+or \DWATabstractorigin{} attribute pointing to another DIE B, any
+attributes of DIE B are considered to be part of DIE A.
+
+\textit{The intent of the above rules is to provide the consumer with
+some assurance that looking up an unqualified name in the index
+will yield all relevant DIEs that provide a defining declaration
+at global scope for that name.}
+
+\textit{A producer may choose to implement additional rules for what
+names are placed in the index, and may communicate those rules to
+a cooperating consumer via an augmentation string, described
+below.}
 
+\subsubsection{Structure of the Name Index}
+\label{chap:structureofthenametindex}
+Logically, the name index can be viewed as a list of names, with a
+list of index entries for each name. Each index entry corresponds to a
+DIE that matches the criteria given in the previous section. For
+example, if one compilation unit has a function named \texttt{fred} and
+another has a struct named \texttt{fred}, a lookup for \doublequote{fred} will find the
+list containing those two index entries.
+
+The index section contains eight individual parts, as illustrated in 
+Figure \referfol{fig:nameindexlayout}.
+\begin{enumerate}
+\item A header, describing the layout of the section.
+
+\item A list of compile units (CUs) referenced by this index.
+
+\item A list of local type units (TUs) referenced by this index
+    that are present in this object file.
+
+\item A list of foreign type units (TUs) referenced by this index
+    that are not present in this object file (that is, that have
+    been placed in a split DWARF object).
+
+\item An optional hash lookup table.
+
+\item The name table.
+
+\item An abbreviations table, similar to the one used by the
+    \dotdebuginfo{} section.
+
+\item The entry pool, containing a list of index entries for each
+    name in the name list.
+\end{enumerate}
+
+\begin{figure}[t]
+\includegraphics[keepaspectratio=true,scale=0.5]{acceleratednameaccessdiagram}
+\caption{Name Index Layout}
+\label{fig:nameindexlayout}
+\end{figure}
+
+The formats of the header and the hash lookup table are described
+below, in Section \refersec{chap:datarepresentationofthenameindex}.
+
+The list of CUs and the list of local TUs are each an array of
+offsets, each of which is the offset of a compile unit or a type unit
+in the \dotdebuginfo{} section. For a per-CU index, there is a single CU
+entry, and there may be a TU entry for each type unit generated in the
+same translation unit as the single CU. For a per-module index, there
+will be one CU entry for each compile unit in the module, and one TU
+entry for each unique type unit in the module. Each list is indexed
+starting at 0.
+
+The list of foreign TUs is an array of 8-byte (\DWFORMrefsigeight) type
+signatures, representing types referenced by the index whose
+definitions have been placed in a different object file (that is, a split
+DWARF object). This list may be empty. This list is indexed starting
+with the size of the local TU list, so that the two lists of TUs are
+logically combined into one list that can be indexed contiguously.
+
+The name table is logically a table with a row for each unique name in
+the index, and two columns. The first column contains a reference to
+the name, as a string. The second column contains the offset within
+the entry pool of the list of index entries for the name.
+
+The abbreviations table describes the formats of the entries in the
+entry pool. Like the DWARF abbreviations table in the \dotdebugabbrev{}
+section, it defines one or more abbreviation codes. Each abbreviation
+code provides a DWARF tag value followed by a list of pairs that
+defines an attribute and form code used by entries with that
+abbreviation code.
+
+The entry pool contains all the index entries, grouped by name. The
+second column of the name list points to the first index entry for the
+name, and all the index entries for that name are placed one after the
+other.
+
+Each index entry begins with an unsigned LEB128 abbreviation code.
+The  abbreviation list for that code provides the DWARF tag value for
+the entry as well as the set of attributes provided by the entry and
+their forms.
+
+The standard attributes are:
+\begin{itemize}
+\item Compilation Unit (CU), a reference to an entry in the list of
+    CUs. In a per-CU index, index entries without this attribute
+    implicitly refer to the single CU.
+
+\item Type Unit (TU), a reference to an entry in the list of local
+    or foreign TUs.
+
+\item DIE offset within the CU or TU.
+
+\item Parent DIE, a reference to the index entry for the parent.
+    This is represented as the offset of the entry relative to
+    the start of the entry pool.
+
+\item Type hash, an 8-byte hash of the type declaration.
+\end{itemize}
+
+It is possible that an indexed DIE has a parent that is not
+indexed (for example, if its parent does not have a name attribute). In
+such a case, a parent attribute may point to a nameless index
+entry (that is, one that cannot be reached from any entry in the
+name table), or it may point to the nearest ancestor that does
+have an index entry.
+
+A producer may define additional vendor-specific attributes, 
+and a consumer will be able to ignore and skip over any attributes 
+it is not prepared to handle.
+
+\needlines{4}
+When an index entry refers to a foreign type unit, it may have
+attributes for both CU and (foreign) TU. For such entries, the CU
+attribute gives the consumer a reference to the CU that may be used to
+locate a split DWARF object that contains the type unit.
+
+The type hash attribute, not to be confused with the type signature
+for a TU, may be provided for type entries whose declarations are not
+in a type unit, for the convenience of link-time or post-link
+utilities that wish to de-duplicate type declarations across
+compilation units. The type hash should, however, be computed by the
+same method as specified for type signatures.
+
+The last entry for each name is followed by a zero byte that
+terminates the list. There may be gaps between the lists.
+
+\subsubsection{Per-CU versus Per-Module Indexes \textit{(Non-Normative)}}
+\label{chap:percuvspermoduleindexes}
+\textit{In a per-CU index, the CU list may have only a single entry, 
+and index entries may omit the CU attribute. (Cross-module or link-time
+optimization, however, may produce an object file with several compile
+units in one object. A compiler in this case may produce a separate
+index for each CU, or a combined index for all CUs. In the latter
+case, index entries will require the CU attribute.) Most name table
+entries may have only a single index entry for each, but sometimes a
+name may be used in more than one context and will require multiple
+index entries, each pointing to a different debugging information
+entry.}
+
+\textit{When linking object files containing per-CU indexes, the 
+linker may choose to concatenate the indexes as ordinary sections, 
+or it may choose to combine the input indexes into a single 
+per-module index.}
+
+\textit{A per-module index will contain a number of CUs, and each index 
+entry should contain a CU attribute or a TU attribute to identify which 
+CU or TU contains the debugging information entry being indexed. When a
+given name is used in multiple CUs or TUs, it will typically have a
+series of index entries pointing to each CU or TU where it is declared. 
+For example, an index entry for a \addtoindex{C++} namespace will need to
+list each occurrence, since each CU may contribute additional names to
+the namespace, and the consumer will need to find them all. On the
+other hand, some index entries do not need to list more than one
+definition; for example, with the one-definition rule in \addtoindex{C++},
+duplicate entries for a function may be omitted, since the consumer
+only needs to find one declaration. Likewise, a per-module index needs
+to list only a single copy of a type declaration contained in a type
+unit.}
+
+\textit{For the benefit of link-time or post-link utilities that consume
+per-CU indexes and produce a per-module index, the per-CU index
+entries provide the tag encoding for the original debugging
+information entry, and may provide a type hash for certain types that
+may benefit from de-duplication. For example, the standard declaration
+of the typedef \texttt{uint32\_t} is likely to occur in many CUs, but a
+combined per-module index needs to retain only one; a user declaration
+of a typedef \texttt{mytype} may refer to a different type at each
+occurrence, and a combined per-module index should retain each unique
+declaration of that type.}
+
+
+\subsubsection{Data Representation of the Name Index}
+\label{chap:datarepresentationofthenameindex}
+The name index is placed in a section named \dotdebugnames, and
+consists of the eight parts described below.
+
+\subsubsubsection{Section Header}
+The section header contains the following fields:
+\begin{enumerate}[1. ]
 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
 \addttindexx{unit\_length}
-The total length of the all of the entries for that set,
-not including the length field itself 
-(see Section \refersec{datarep:initiallengthvalues}).
-
-\item  version (\addtoindex{uhalf}) \\
-A version number
-\addtoindexx{version number!name lookup table}
-\addtoindexx{version number!type lookup table} 
-(see Section \refersec{datarep:namelookuptables}). 
-This number is specific
-to the name lookup table and is independent of the DWARF
-version number.
-
-\item debug\_info\_offset (section offset) \\
-The 
-\addtoindexx{section offset!in .debug\_pubtypes header}
-offset 
-\addtoindexx{section offset!in .debug\_pubtypes header}
-from the beginning of the 
-\dotdebuginfo{} section of
-the compilation unit header referenced by the set.
-
-\item debug\_info\_length (section length) \\
-\addtoindexx{section length!in .debug\_pubnames header}
-The 
-\addtoindexx{section length!in .debug\_pubtypes header}
-size in bytes of the contents of the 
-\dotdebuginfo{} section
-generated to represent that compilation unit.
+The length of this contribution to the name index section,
+not including the length field itself.
+
+\item \texttt{version} (\addtoindex{uhalf}) \\
+A version number\addtoindexx{version number!name index table} 
+(see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
+This number is specific to the name index table and is
+independent of the DWARF version number.
+
+\item \textit{padding} (\addtoindex{uhalf}) \\
+
+\item \texttt{comp\_unit\_count} (4-byte unsigned integer) \\
+The number of CUs in the CU list.
+
+\item \texttt{local\_type\_unit\_count} (4-byte unsigned integer) \\
+The number of TUs in the first TU list.
+
+\item \texttt{foreign\_type\_unit\_count} (4-byte unsigned integer) \\
+The number of TUs in the second TU list.
+
+\item \texttt{bucket\_count} (4-byte unsigned integer) \\
+The number of hash buckets in the hash lookup table. 
+If there is no hash lookup table, this field contains 0.
+
+\item \texttt{name\_count} (4-byte unsigned integer) \\
+The number of unique names in the index.
+
+\item \texttt{abbrev\_table\_size} (4-byte unsigned integer) \\
+The size in bytes of the abbreviations table.
+
+\item \texttt{augmentation\_string\_size} (4-byte unsigned integer) \\
+The size in bytes of the augmentation string. This value should be
+rounded up to a multiple of 4.
+
+\item \texttt{augmentation\_string} (sequence of characters) \\
+A vendor-specific augmentation string, which provides additional 
+information about the contents of this index. If provided, the string
+should begin with a 4-byte vendor ID. The remainder of the
+string is meant to be read by a cooperating consumer, and its
+contents and interpretation are not specified here. The
+string should be padded with null characters to a multiple of
+four bytes in length.
+
 \end{enumerate}
 
-This header is followed by a variable number of offset/name
-pairs. Each pair consists of the section offset from the
-beginning of the compilation unit corresponding to the current
-set to the debugging information entry for the given object,
-followed by a null\dash terminated character string representing
-the name of the object as given by the \DWATname{} attribute
-of the referenced debugging information entry. Each set of
-names is terminated by an offset field containing zero (and
-no following string).
-
-
-In the case of the name of a function member or static data
-member of a \addtoindex{C++} structure, class or union, the name presented
-in the 
-\dotdebugpubnames{} 
-section is not the simple name given
-by the \DWATname{} attribute of the referenced debugging
-information entry, but rather the fully qualified name of
-the data or function member.
+\subsubsubsection{List of CUs}
 
-\subsection{Lookup by Address}
+The list of CUs immediately follows the header. Each entry in the list
+is a section offset. In the DWARF-32 format, a section offset is 4
+bytes, while in the DWARF-64 format, a section offset is 8 bytes.
+
+The total number of entries in the list is given by \texttt{comp\_unit\_count}.
+There must be at least one CU.
+
+\subsubsubsection{List of Local TUs}
+
+The list of local TUs immediately follows the list of CUs. Each entry
+in the list is a section offset. In the DWARF-32 format, a section
+offset is 4 bytes, while in the DWARF-64 format, a section offset is 8
+bytes.
+
+The total number of entries in the list is given by
+\texttt{local\_type\_unit\_count}. This list may be empty.
+
+\subsubsubsection{List of Foreign TUs}
+
+The list of foreign TUs immediately follows the list of local TUs.
+Each entry in the list is an 8-byte type signature (as described by
+\DWFORMrefsigeight).
+
+The number of entries in the list is given by \texttt{foreign\_type\_unit\_count}.
+This list may be empty.
+
+\subsubsubsection{Hash Lookup Table}
+
+The optional hash lookup table immediately follows the list of type signatures.
+
+The hash lookup table is actually two separate arrays: an array of
+buckets, followed immediately by an array of hashes. The number of
+entries in the buckets array is given by \texttt{bucket\_count}, and the number
+of entries in the hashes array is given by \texttt{name\_count}. Each array
+contains 4-byte unsigned integers.
+
+\needlines{4}
+Symbols are entered into the hash table by first computing a hash
+value from the symbol name. The hash is computed by the \doublequote{DJB}
+hash function (the same hash function used for the \texttt{DT\_GNU\_HASH}
+table in ELF object files). Given a hash value for the symbol,
+the symbol is entered into a bucket whose index is the hash value
+modulo \texttt{bucket\_count}. The buckets array is indexed starting at 0.
+
+Each bucket contains the index of an entry in the hashes array. The
+hashes array is indexed starting at 1, and an empty bucket is
+represented by the value 0.
+
+The hashes array contains a list of the full hash values for each
+symbol. All symbols that fall into the same bucket must be grouped
+together in the hashes array, and the bucket refers to the first
+symbol in the group. When searching for a symbol, the search should
+start at the index given by the bucket, and continue either until a
+matching symbol is found or until a hash value from a different bucket
+is found. If two different symbol names produce the same hash value,
+that hash value will occur twice in the hashes array. Thus, if a
+matching hash value is found, but the name does not match, the search
+should continue visiting subsequent entries in the hashes table.
+
+When a matching hash value is found in the hashes array, the index of
+that entry in the hashes array is used to find the corresponding entry
+in the name table.
+
+\subsubsubsection{Name Table}
+
+The name table immediately follows the hash lookup table. The name
+table is laid out in column-major order (that is, the first column,
+followed by the second column). Each entry in the first column
+contains the string table offset (\DWFORMstrp) of the name in the
+\dotdebugstr{} (or \dotdebugstrdwo) section. Each entry in the second
+column contains the offset (as a section offset) within the entry pool
+of the list of index entries for the name. Rows in the name table are
+indexed starting at 1 (to match the hashes array).
+
+The number of rows in the name table is given by \texttt{name\_count}.
+
+If there is a hash lookup table, the entries in the name table must be
+grouped by bucket: all names that fall into the same hash bucket must
+be grouped together. The row number of an entry in the name table must
+match the row number of its corresponding entry in the hashes array.
+
+If there is no hash lookup table, there is no ordering or grouping
+requirement for the name table.
+
+\subsubsubsection{Abbreviations Table}
+
+The abbreviations table immediately follows the name table. Like the
+abbreviations table for debugging information entries, this table
+consists of a series of abbreviation declarations. Its size is given
+by \texttt{abbrev\_table\_size}.
+
+Each abbreviation declaration defines the tag and other attributes for
+a particular form of index entry. Each declaration starts with an
+unsigned LEB128 number representing the abbreviation code itself. It
+is this code that appears at the beginning of an index entry. The
+abbreviation code must not be 0.
+
+The abbreviation code is followed by another unsigned LEB128 number
+that encodes the tag of the debugging information entry corresponding
+to the index entry.
+
+Following the tag encoding is a series of attribute specifications.
+Each attribute consists of two parts: an unsigned LEB128 number that
+represents the index attribute, and another unsigned LEB128 number
+that represents the attribute's form (as described in 
+Section \refersec{datarep:attributeencodings}). The series of attribute 
+specifications ends with an entry containing 0 for the attribute and 
+0 for the form.
+
+The index attributes and their meanings are listed in Table \referfol{tab:indexattributeencodings}.
+
+\begin{centering}
+\setlength{\extrarowheight}{0.1cm}
+\begin{longtable}{l|l}
+  \caption{Index attribute encodings} \label{tab:indexattributeencodings}\\
+  \hline \bfseries Attribute name &\bfseries Meaning \\ \hline
+\endfirsthead
+  \bfseries Attribute name &\bfseries Meaning \\ \hline
+\endhead
+  \hline \emph{Continued on next page}
+\endfoot
+  \hline
+\endlastfoot
+\DWIDXcompileunitTARG & Index of CU                                  \\
+\DWIDXtypeunitTARG    & Index of TU (\mbox{local} or foreign)        \\
+\DWIDXdieoffsetTARG   & Offset of DIE within CU or TU                \\
+\DWIDXparentTARG      & Index of name \mbox{table} entry for parent  \\
+\DWIDXtypehashTARG    & Hash of type \mbox{declaration}              \\
+\DWIDXlouserTARG      & Start of user-defined range                  \\
+\DWIDXhiuserTARG      & End of user-defined range                    \\
+\end{longtable}
+\end{centering}
 
-For 
-\addtoindexx{lookup!by address}
+The abbreviations table ends with an entry consisting of a single 0
+byte for the abbreviation code. The size of the table given by
+\texttt{abbrev\_table\_size} may include optional padding following the
+terminating 0 byte.
+
+\subsubsubsection{Entry Pool}
+
+The entry pool immediately follows the abbreviations table. The second
+column of each row of the name table points to an offset in the entry
+pool, where a series of index entries for that name is located.
+
+Each index entry in the series begins with an abbreviation code, and is
+followed by the attributes described by the abbreviation declaration
+for that code. The last index entry in the series is followed by a
+terminating entry whose abbreviation code is 0.
+
+Gaps are not allowed between entries in a series (that is, the entries
+for a single name must all be contiguous), but there may be gaps
+between series (if, for example, a producer/consumer combination finds
+it useful to maintain alignment).
+
+The size of the entry pool is limited by the size of the contribution
+to the index section, as defined by the \texttt{unit\_length} header field.
+
+\subsection{Lookup by Address}
+\label{chap:lookupbyaddress}
+For \addtoindexx{lookup!by address}
 lookup by address, a table is maintained in a separate
 \addtoindexx{accelerated access!by address}
 object file section called 
 \dotdebugaranges{}. The table consists
 of sets of variable length entries, each set describing the
-portion of the program\textquoteright s address space that is covered by
+portion of the program\textquoteright{}s address space that is covered by
 a single compilation unit.
 
 Each set begins with a header containing five values:
 \begin{enumerate}[1. ]
 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
 \addttindexx{unit\_length}
-The total length of all of the
-entries for that set, not including the length field itself
-(see Section \refersec{datarep:initiallengthvalues}).
+The length of this contribution to the address lookup section,
+not including the length field itself.
 
-\item version (\addtoindex{uhalf}) \\
+\item \texttt{version} (\addtoindex{uhalf}) \\
 A version number\addtoindexx{version number!address lookup table} 
 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
 This number is specific to the address lookup table and is
 independent of the DWARF version number.
 
-\item debug\_info\_offset (section offset) \\
+\item \texttt{debug\_info\_offset} (section offset) \\
 The offset from the
-\addtoindexx{section offset!in .debug\_pubnames header}
+\addtoindexx{section offset!in .debug\_aranges header}
 beginning of the \dotdebuginfo{} section of the
 compilation unit header referenced by the set.
 
@@ -194,7 +568,6 @@ a flat address space, this value is 0.
 
 \end{enumerate}
 
-
 This header is followed by a variable number of address range
 descriptors. Each descriptor is a triple consisting of a
 segment selector, the beginning address within that segment
@@ -215,8 +588,6 @@ of a compilation unit is not contiguous, then there may be
 multiple address range descriptors for that compilation unit.}
 
 
-
-
 \section{Line Number Information}
 \label{chap:linenumberinformation}
 \textit{A source\dash level debugger will need to know how to
@@ -291,7 +662,6 @@ separate matrix for each contiguous subrange.}
 The following terms are used in the description of the line
 number information format:
 
-
 \begin{longtable} {lp{9cm}}
 state machine &
 The hypothetical machine used by a consumer of the line number
@@ -314,20 +684,20 @@ subprogram invocation is defined to be an exit from a
 necessarily correspond to a specific source code
 construct.} \\
 
-
 sequence &
 A series of contiguous target machine instructions. One compilation unit
 may emit multiple sequences (that is, not all instructions within a
 compilation unit are assumed to be contiguous). \\
 \end{longtable}
 
-\needlines{5}
+\needlines{8}
 \subsection{State Machine Registers}
 \label{chap:statemachineregisters}
-The line number information state machine has the following 
-registers:
+The line number information state machine has a number of  
+registers as shown in Table \referfol{tab:statemachineregisters}.
+
 \begin{longtable}{l|p{9cm}}
-  \caption{State machine registers } \\
+  \caption{State machine registers } \label{tab:statemachineregisters} \\
   \hline \bfseries Register name&\bfseries Meaning\\ \hline
 \endfirsthead
   \bfseries Register name&\bfseries Meaning\\ \hline
@@ -833,9 +1203,10 @@ or \DWFORMdataeight.
 of the file contents. It is paired with form \DWFORMdatasixteen.
 \end{enumerate}
 
+\needlines{6}
 \textit{Using this representation, the information found in a 
 \DWARFVersionIV{} line number header could be encoded as shown in 
-Figure \referfol{fig:preV5LNCTusingV5}.}
+Figure \refersec{fig:preV5LNCTusingV5}.}
 
 \begin{figure}[here]
 \begin{dwflisting}
@@ -857,14 +1228,14 @@ Figure \referfol{fig:preV5LNCTusingV5}.}
                                           \DWLNCTtimestamp, \DWFORMudata,
                                           \DWLNCTsize, \DWFORMudata
     19    \HFNfilenamescount{}                <m>
-    20    \HFNfilenames{}                      <m>*{<null terminated string>,
-                                          <index>, <timestamp>, <size>}
+    20    \HFNfilenames{}                      <m>*\{<null terminated string>, <index>, 
+                                               <timestamp>, <size>\}
 \end{alltt}
 \end{dwflisting}
 \begin{centering}
-\caption{Pre-\DWARFVersionV{} Line Number Program Header Information \mbox{Encoded} Using \DWARFVersionV}
-\end{centering}
+\caption{Pre-\DWARFVersionV{} line number program header information \mbox{encoded} using \DWARFVersionV}
 \label{fig:preV5LNCTusingV5}
+\end{centering}
 \end{figure}
 
 \subsubsection{Vendor-defined Content Descriptions}
@@ -881,6 +1252,7 @@ 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.
 
+\needlines{6}
 \subsection{The Line Number Program}
 \label{linenumberprogram}
 As stated before, the goal of a line number program is to build
@@ -1063,6 +1435,7 @@ Figure \refersec{fig:examplelinenumberspecialopcodemapping}.}
 255 - \addttindex{line\_base} + 1 be an integral multiple of
 \addttindex{line\_range}. }
 
+\needlines{6}
 \subsubsection{Standard Opcodes}
 \label{chap:standardopcodes}
 
@@ -1592,9 +1965,9 @@ on the call stack. An activation consists of:}
 \begin{itemize}
 \item \textit{A code location that is within the
 subroutine. This location is either the place where the program
-stopped when the debugger got control (e.g. a breakpoint), or
+stopped when the debugger got control (for example, a breakpoint), or
 is a place where a subroutine made a call or was interrupted
-by an asynchronous event (e.g. a signal).}
+by an asynchronous event (for example, a signal).}
 
 \item \textit{An area of memory that is allocated on a stack called a
 \doublequote{call frame.} The call frame is identified by an address
@@ -1842,6 +2215,7 @@ needs to be freed on exit from the routine.}
 any \dotdebuginfo{} section, the augmentation string always uses
 UTF\dash 8 encoding.}
 
+\needlines{4}
 \item  \texttt{address\_size} (\addtoindex{ubyte}) \\
 The size of a target address
 \addttindexx{address\_size}
@@ -1979,6 +2353,7 @@ these instructions because its use would be circular.
 include \DWCFAdefcfaexpression, \DWCFAexpression{}
 and \DWCFAvalexpression.}
 
+\needlines{8}
 \subsubsection{Row Creation Instructions}
 \label{chap:rowcreationinstructions}
 \begin{enumerate}[1. ]
@@ -2096,6 +2471,7 @@ expression operators that can be used.}
 
 \end{enumerate}
 
+\needlines{8}
 \subsubsection{Register Rule Instructions}
 \label{chap:registerruleinstructions}
 \begin{enumerate}[1. ]
@@ -2278,6 +2654,7 @@ instruction is encountered, then compute a new location value
 (L2). If L1 $\geq$ L2 then process the instruction and go back
 to step 2.}
 
+\needlines{6}
 \item \textit{ The end of the instruction stream can be thought
 of as a \DWCFAsetloc{} (\addttindex{initial\_location} + \addttindex{address\_range})
 instruction. Note that the FDE is ill-formed if L2 is less
@@ -2322,7 +2699,7 @@ same context as the calling address, the unwind might fail.}
 the return address immediately follows the call instruction,
 a simple solution is to subtract the length of an instruction
 from the return address to obtain the calling instruction. For
-architectures with variable-length instructions (e.g.  x86),
+architectures with variable-length instructions (for example, x86),
 this is not possible. However, subtracting 1 from the return
 address, although not guaranteed to provide the exact calling
 address, generally will produce an address within the same
index 370357c..9dabf1b 100644 (file)
@@ -1027,18 +1027,19 @@ and will therefore not be safe to call from within a debugger.
 }
 
 A subroutine entry may 
-\hypertarget{chap:DWATcallingconventionsubprogramcallingconvention}{}
+\hypertarget{chap:DWATcallingconventionforsubprograms}{}
 contain a 
 \DWATcallingconventionNAME{}
+\addtoindexx{calling convention attribute}
 attribute, whose value is an 
 \livelink{chap:classconstant}{integer constant}. The set of
-calling convention codes is given in 
-Table \refersec{tab:callingconventioncodes}.
+\addtoindexi{calling convention codes for subroutines}{calling convention codes!for subroutines}
+is given in Table \refersec{tab:callingconventioncodesforsubroutines}.
 
-\begin{simplenametable}[1.4in]{Calling convention codes}{tab:callingconventioncodes}
-\DWCCnormal        \\
-\DWCCprogram       \\
-\DWCCnocall        \\
+\begin{simplenametable}[1.4in]{Calling convention codes for subroutines}{tab:callingconventioncodesforsubroutines}
+\DWCCnormalTARG        \\
+\DWCCprogramTARG       \\
+\DWCCnocallTARG        \\
 \end{simplenametable}
 
 If this attribute is not present, or its value is the constant
@@ -1049,6 +1050,10 @@ is the constant \DWCCnocallTARG, the subroutine does not obey
 standard calling conventions, and it may not be safe for the
 debugger to call this subroutine.
 
+\textit{Note that \DWCCnormal{} is also used as a calling convention 
+code for certain types 
+(see Table \refersec{tab:callingconventioncodesfortypes}).}
+
 If the semantics of the language of the compilation unit
 containing the subroutine entry distinguishes between ordinary
 subroutines and subroutines that can serve as the \doublequote{main
index b8dbc38..ddbdcec 100644 (file)
@@ -61,8 +61,9 @@ format would be represented by a change in the
 \dotdebugloc{}      & * & * & * & 5 \\
 \dotdebugmacinfo{}  & * & * & * & - \\*
 \dotdebugmacro{}    & - & - & - & 5 \\
-\dotdebugpubnames{} & 2 & 2 & 2 & 2 \\
-\dotdebugpubtypes{} & - & 2 & 2 & 2 \\
+\dotdebugnames{}    & - & - & - & 5 \\
+\dotdebugpubnames{} & 2 & 2 & 2 & - \\
+\dotdebugpubtypes{} & - & 2 & 2 & - \\
 \dotdebugranges{}   & - & * & * & 5 \\
 \dotdebugstr{}      & * & * & * & * \\
 \dotdebugstroffsets & - & - & - & 5 \\
index fc489c5..9bba652 100644 (file)
@@ -132,13 +132,7 @@ design.
 \dotdebugranges{} - Contains the range lists, unaffected by this
 design.
 \item
-\dotdebugpubnames{} - Contains the public names for use in
-building an index section. This section has the same
-format and use as always. The section header refers to a
-compilation unit offset, which is the offset of the
-skeleton compilation unit in the \dotdebuginfo{} section.
-\item
-\dotdebugpubtypes{} - Contains the public types for use in
+\dotdebugnames{} - Contains the names for use in
 building an index section. This section has the same
 format and use as always. The section header refers to a
 compilation unit offset, which is the offset of the
@@ -270,9 +264,10 @@ start/length, and offset pair), the two operand values are
 followed by a location description as in a normal location list
 entry in the \dotdebugloc{} section.
 
+\needlines{8}
 This design depends on having an index of debugging information
 available to the consumer. For name lookups, the consumer can use
-the \dotdebugpubnames{} and \dotdebugpubtypes{} sections (or an index
+the \dotdebugnames{} sections (or an index
 built at link time based on the information in those sections),
 which will lead to a skeleton compilation unit. The
 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
@@ -408,8 +403,7 @@ information:
   \dotdebugline
   \dotdebugstr
   \dotdebugaddr
-  \dotdebugpubnames
-  \dotdebugpubtypes
+  \dotdebugnames
   \dotdebugaranges
 \end{alltt}
 
@@ -510,17 +504,14 @@ Slot & Location referenced \\
 \end{center}
 
 \needlines{4}
-\textit{\textbf{[***The following paragraph will need updating when the accelerated access
-proposal is finalized.***]}}
-
-The \dotdebugpubnames{} and \dotdebugpubtypes{}
-sections contain the public names defined by the debugging
+The \dotdebugnames{}
+section contains the public names defined by the debugging
 information in the split DWARF object, and reference the skeleton
 compilation unit. When linked together into a final executable,
 they can be used by a DWARF consumer to lookup a name to find one
 or more skeleton compilation units that provide information about
 that name. From the skeleton compilation unit, the consumer can
-find the split DWARF object that it can read to get the full
+find the split DWARF object that it can then read to get the full
 DWARF information.
 
 The \dotdebugaranges{} section contains the PC ranges defined in this
index e1074b2..ec615ff 100644 (file)
@@ -783,6 +783,11 @@ in the following discussion statements about
 \addtoindex{C++} classes may
 be understood to apply to \addtoindex{C++} structures as well.}
 
+\textit{\addtoindex{C++} has the notion of a "trivial" class, 
+whose objects can be bitwise copied. Trivial classes may have 
+different rules for passing objects of that type as parameters 
+or return values.}
+
 \subsection{Structure, Union and Class Type Entries}
 \label{chap:structureunionandclasstypeentries}
 Structure, union, and class types are represented by debugging
@@ -911,6 +916,34 @@ different compilation units to
 facilitate DWARF space compression 
 (see Appendix \refersec{app:usingcompilationunits}).}
 
+\needlines{4}
+A structure type, union type or class type entry may have a
+\DWATcallingconvention{} attribute,
+\addtoindexx{calling convention attribute} 
+whose value indicates whether a value of the type should be passed by reference 
+or passed by value. The set of calling convention codes for use with types 
+\addtoindexx{calling convention codes!for types}
+\hypertarget{chap:DWATcallingconventionfortypes}{}
+is given in Table \referfol{tab:callingconventioncodesfortypes}.
+
+\begin{simplenametable}[2.2in]{Calling convention codes for types}{tab:callingconventioncodesfortypes}
+\DWCCnormalTARG             \\
+\DWCCpassbyvalueTARG        \\
+\DWCCpassbyreferenceTARG    \\
+\end{simplenametable}
+
+If this attribute is not present, or its value is
+\DWCCnormalNAME, the convention to be used for an object of the
+given type is assumed to be unspecified.
+
+\textit{Note that \DWCCnormalNAME{} is also used as a calling convention 
+code for certain subprograms 
+(see Table \refersec{tab:callingconventioncodesforsubroutines}).}
+
+\textit{If unspecified, a consumer may be able to deduce the calling
+convention based on knowledge of the type and the ABI.}
+
+
 \subsection{Interface Type Entries}
 \label{chap:interfacetypeentries}
 
@@ -1368,6 +1401,7 @@ may contain the same attributes and follows the same rules
 as non\dash member global subroutine entries 
 (see Section \refersec{chap:subroutineandentrypointentries}).
 
+\needlines{4}
 \textit{In particular, if the member function entry is an
 instantiation of a member function template, it follows the 
 same rules as function template instantiations (see Section 
@@ -1476,9 +1510,58 @@ by the declaration entry referenced by the specification
 attribute. In particular, such entries do not need to contain
 a name attribute giving the name of the function member whose 
 definition they represent.  
-Similarly, such entries do not need to contain a return type attribute, 
-unless the return type on the declaration was unspecified (for example, the 
-declaration used the \addtoindex{C++} \autoreturntype{} specifier).
+Similarly, such entries do not need to contain a return type 
+attribute, unless the return type on the declaration was 
+unspecified (for example, the declaration used the 
+\addtoindex{C++} \autoreturntype{} specifier).
+
+\textit{In \addtoindex{C++}, a member function may be declared 
+as deleted. This prevents the compiler from generating a default
+implementation of a special member function such as a
+constructor or destructor, and can affect overload resolution
+when used on other member functions.}
+
+If the member function entry has been declared as deleted,
+\hypertarget{chap:DWATdeleted}{}
+then that entry has a \DWATdeletedTARG{} attribute.\addtoindexx{deleted attribute}
+
+\textit{In \addtoindex{C++}, a special member function may be 
+declared as defaulted, which explicitly declares a default
+compiler-generated implementation of the function. The
+declaration may have different effects on the calling
+convention used for objects of its class, depending on
+whether the default declaration is made inside or outside the
+class.}
+
+If the member function has been declared as defaulted, 
+then the entry has a \DWATdefaultedTARG{} 
+attribute\addtoindexx{defaulted attribute}
+whose integer constant value indicates whether, and if so,
+how, that member is defaulted. The possible values and
+their meanings are shown in 
+Table \referfol{tab:defaultedattributevaluenames}.
+
+\begin{centering}
+  \setlength{\extrarowheight}{0.1cm}
+\begin{longtable}{l|l}
+  \caption{Defaulted attribute names} \label{tab:defaultedattributevaluenames} \\
+  \hline \bfseries Defaulted attribute name & \bfseries Meaning \\ \hline
+\endfirsthead
+  \bfseries Defaulted attribute name & \bfseries Meaning \\ \hline
+\endhead
+  \hline \emph{Continued on next page}
+\endfoot
+\endlastfoot
+\DWDEFAULTEDnoTARG        & Not declared default \\
+\DWDEFAULTEDinclassTARG   & Defaulted within the class \\
+\DWDEFAULTEDoutofclassTARG& Defaulted outside of the class \\
+\hline
+\end{longtable}
+\end{centering}
+
+\textit{An artificial member function (that is, a compiler-generated
+copy that does not appear in the source) does not have a
+\DWATdefaultedNAME{} attribute.}
 
 \needlines{5}
 \subsection{Class Template Instantiations}
@@ -1862,7 +1945,7 @@ A subroutine type entry may have the \DWATreference{} or
 type of a member function with reference or rvalue-reference 
 semantics, respectively.
 
-
+\needlines{6}
 \section{String Type Entries}
 \label{chap:stringtypeentries}
 
@@ -1939,6 +2022,7 @@ size attribute is present, the size of the data to be retrieved
 is the same as the 
 \addtoindex{size of an address} on the target machine.
 
+\needlines{8}
 \addtoindexx{DWARF Version 5}  % Avoid italics
 \textit{Prior to DWARF Version 5, the meaning of a 
 \DWATbytesize{} attribute depends on the presence of the