Up to date with all available input, including issues approved
authorRon Brender <ron.brender@gmail.com>
Fri, 16 May 2014 18:53:41 +0000 (14:53 -0400)
committerRon Brender <ron.brender@gmail.com>
Fri, 16 May 2014 18:53:41 +0000 (14:53 -0400)
at May 2014 meeting.

Signed-off-by: Ron Brender <ron.brender@gmail.com>
14 files changed:
dwarf5/latexdoc/attributesbytag.tex
dwarf5/latexdoc/changesummary.tex
dwarf5/latexdoc/compression.tex
dwarf5/latexdoc/dataobject.tex
dwarf5/latexdoc/datarepresentation.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/typeentries.tex

index d1a1e8c..25a112b 100644 (file)
@@ -652,6 +652,7 @@ means include all three of the
 &\DWATlowpc{}  \\
 &\DWATmainsubprogram{}  \\
 &\DWATname{}  \\
+&\DWATnoreturn \\
 &\DWATobjectpointer{}  \\
 &\DWATprototyped{}  \\
 &\DWATpure{}  \\
index 2cb8f2b..a6455e6 100644 (file)
@@ -15,8 +15,11 @@ 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
-5/13/2014       & 100909.1 (entry values), 100909.2 (call sites) \\
-4/25/2014       & 140330.1 (C++:2011), 14037.1 (enumeraion size) \\
+5/16/2014       & 140227.1 (references to within type unit), Walker review comments,  \\
+                & 140331.1 (noreturn attribute) \\
+5/13/2014       & 100909.1 (entry values), 100909.2 (call sites), \\
+                & 140327.1 (Clarification of enumeration size) \\
+4/25/2014       & 140330.1 (C++:2011), 14037.1 (enumeration size) \\
 4/19/2014       & Complete revisions to Appendix B (especially for .debug\_macro) \\
 4/17/2014       & 110722.1 (.debug\_macro), Clean up missing target issues \\
 4/15/2014       & 140129.1 (Rust), 140203.1 (hashing of \DWFORMexprlocNAME) \\
@@ -26,33 +29,33 @@ This change summary is included only in draft versions of this document.
 12/18/2013      & 131105.1 (\&- and \&\&-qualification), 131216.1 (non-defining wording), \\
                 & 131112.1 (\_Atomic type), review comments to date \\
 11/22/2013      & 131106.1 (dynamic type), review comments to date \\
-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)      \\
-10/24/2013             & 130815.1 (template parameter refactoring)                                     \\
-10/23/2013             & 130722.1 (additional \DWATartificialNAME{} uses in Appendix A), \\
-                               & 120719.1 (constant \DWATentrypcNAME{} value),                                 \\
-                               & 120727.1 (\DWATuseUTFeightNAME{} affects all sections),       \\
-                               & 130402.1 (\DWATdefaultvalueNAME{} flag on template parameters),       \\
-                               & 130412.1 (non-integral non-type template parameters), 131009.1 (OCaml)        \\
-10/22/2013             & 120628.1 (language codes for C++:2003 and 2011)       \\
-10/11/2013             & Several DW<name>TARG repairs                                                          \\
-10/10/2013             & Convert document to use new DWARF name commands (dwarfnamecmds.tex) \\
-10/2/2013              & Fill out the rest of dwarfnamecmds.tex                                        \\
-9/28/2013              & Introduce newdwfnamecommands and related conventions          \\
-9/27/2013              & Editorial work re assumed-rank arrays, other minor cleanups \\
+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)      \\
+10/24/2013     & 130815.1 (template parameter refactoring)                                     \\
+10/23/2013     & 130722.1 (additional \DWATartificialNAME{} uses in Appendix A), \\
+               & 120719.1 (constant \DWATentrypcNAME{} value),                                 \\
+               & 120727.1 (\DWATuseUTFeightNAME{} affects all sections),       \\
+               & 130402.1 (\DWATdefaultvalueNAME{} flag on template parameters),       \\
+               & 130412.1 (non-integral non-type template parameters), 131009.1 (OCaml)        \\
+10/22/2013     & 120628.1 (language codes for C++:2003 and 2011)       \\
+10/11/2013     & Several DW<name>TARG repairs          \\
+10/10/2013     & Convert document to use new DWARF name commands (dwarfnamecmds.tex) \\
+10/2/2013      & Fill out the rest of dwarfnamecmds.tex                                        \\
+9/28/2013      & Introduce newdwfnamecommands and related conventions          \\
+9/27/2013      & Editorial work re assumed-rank arrays, other minor cleanups \\
 9/23/2013       & 130313.5 (Fortran assumed-rank arrays)\\
 6/22/2013      & 100805.1 (value of reference), 100816.1 (remove .debug\_types), \\ 
-                       & 101014.1, 101111.1, 120218.1 (Go, Modula-3 and Haskell), \\
-                       & 110803.1 (tls), 110926.1 (DW\_OP\_callx), 121212.1 (type unit)        \\
-                       & 121221.1 (location length), 130121.1 (default location) \\
-                       & 121123.1 (length in location list entry),             \\
-                       & 110110.1 \& 130623.1 (size of string length w/o example)      \\
+               & 101014.1, 101111.1, 120218.1 (Go, Modula-3 and Haskell), \\
+               & 110803.1 (tls), 110926.1 (DW\_OP\_callx), 121212.1 (type unit)        \\
+               & 121221.1 (location length), 130121.1 (default location) \\
+               & 121123.1 (length in location list entry),             \\
+               & 110110.1 \& 130623.1 (size of string length w/o example)      \\
 6/20/2013      & 090824.1 (coarray)                                                    \\
 6/18/2013      & 100211.1 (OpenCL), add this Change Summary    \\
 6/1/2013       & Begin V5 (from V4.1), delete V4 vs V3 stuff, delete "new in V4" \\
 (Pre-V5)       & 100923.1 (bungled subheader), 101015.1 (sig8 typo), \\
-                       & 110404.1 (DW\_TAG\_member typos) \\
+               & 110404.1 (DW\_TAG\_member typos) \\
 \end{longtable}
 \end{abstract}
index 2aa882e..a985b5c 100644 (file)
@@ -11,9 +11,9 @@ can
 \addtoindexx{DWARF duplicate elimination}
 use a lot of disk space.
 
-This is especially true for C++, where the depth and complexity
+This is especially true for \addtoindex{C++}, where the depth and complexity
 of headers can mean that many, many (possibly thousands of)
-declarations are repeated in every compilation unit. C++
+declarations are repeated in every compilation unit. \addtoindex{C++}
 templates can also mean that some functions and their DWARF
 descriptions get duplicated.
 
@@ -736,7 +736,7 @@ with an \DWATimport{} attribute that refers to the proper unit
 in the \addtoindex{section group}.
 
 \textit{The \addtoindex{C} rules for consistency of global (file scope) symbols
-across compilations are less strict than for C++; inclusion
+across compilations are less strict than for \addtoindexx{C++}; inclusion
 of the import unit attribute assures that the declarations of
 the proper \addtoindex{section group} are considered before declarations
 from other compilations.}
@@ -1319,6 +1319,63 @@ empty
 \label{fig:typesignaturecomputationgrammar}
 \end{figure}
 
+\clearpage
+\subsection{Declarations Completing Non-Defining Declarations}
+\label{app:declarationscompletingnondefiningdeclarations}
+Consider a compilation unit that contains a definition of the member
+function \texttt{N::A::v()} from 
+Figure \refersec{fig:typesignatureexamplescsource}. 
+A possible representation of the
+debug information for this function in the compilation unit is shown
+in Figure \refersec{fig:completingedeclarationofamemberfunctiondwarf}.
+
+\begin{figure}[h]
+\begin{dwflisting}
+\begin{alltt}
+  \DWTAGnamespace
+      \DWATname{} : "N"
+L1:
+    \DWTAGclasstype
+        \DWATname{} : "A"
+        \DWATdeclaration{} : true
+        \DWATsignature{} : 0xd6d160f5 5589f6e9
+L2:
+      \DWTAGsubprogram
+          \DWATexternal{} : 1
+          \DWATname{} : "v"
+          \DWATdeclfile{} : 1
+          \DWATdeclline{} : 13
+          \DWATtype{} : reference to L3
+          \DWATdeclaration{} : 1
+        \DWTAGformalparameter
+            \DWATtype{} : reference to L4
+            \DWATartificial{} : 1
+...
+L3:
+  \DWTAGbasetype
+      \DWATbytesize{} : 4
+      \DWATencoding{} : \DWATEsigned
+      \DWATname{} : "int"
+...
+L4:
+  \DWTAGpointertype
+      \DWATtype{} : reference to L1
+...
+  \DWTAGsubprogram
+      \DWATspecification{} : reference to L2
+      \DWATdeclfile{} : 2
+      \DWATdeclline{} : 25
+      \DWATlowpc{} : ...
+      \DWAThighpc{} : ...
+    \DWTAGlexicalblock
+    ...
+...
+\end{alltt}
+\end{dwflisting}
+\caption{Completing declaration of a member function: DWARF \mbox{encoding}}
+\label{fig:completingedeclarationofamemberfunctiondwarf}
+\end{figure}
+
 
 \clearpage
 \section{Summary of Compression Techniques}
index 3cb5500..70c868b 100644 (file)
@@ -45,9 +45,9 @@ is a \livelink{chap:classflag}{flag}, if the name
 of a variable is visible outside of its enclosing compilation
 unit.  
 
-\textit{The definitions of C++ static data members of structures
+\textit{The definitions of \addtoindex{C++} static data members of structures
 or classes are represented by variable entries \nolink{flagged} as
-external. Both file static and local variables in C and C++
+external. Both file static and local variables in \addtoindex{C} and \addtoindex{C++}
 are represented by non-external variable entries.
 }
 
@@ -206,7 +206,7 @@ a lexical \livelink{chap:lexicalblock}{block} in a language
 that allows executable code in a
 \nolink{block} before a variable declaration, or where one declaration
 containing initialization code may change the scope of a
-subsequent declaration.  For example, in the following C code:}
+subsequent declaration.  For example, in the following \addtoindex{C} code:}
 
 \begin{lstlisting}
 float x = 99.99;
@@ -218,7 +218,7 @@ int myfunc()
 }
 \end{lstlisting}
 
-\textit{C scoping rules require that the value of the variable x
+\textit{\addtoindex{C} scoping rules require that the value of the variable x
 assigned to the variable f in the initialization sequence is
 the value of the global variable x, rather than the local x,
 because the scope of the local variable x only starts after
@@ -275,11 +275,11 @@ for different architectures.
 which 
 \hypertarget{chap:DWATconstexprcompiletimeconstantobject}{}
 is a \livelink{chap:classflag}{flag}, if a
-variable entry represents a C++ object declared with the
+variable entry represents a \addtoindex{C++} object declared with the
 \texttt{constexpr} specifier. This attribute indicates that the
 variable can be evaluated as a compile\dash time constant.  
 
-\textit{In C++,
+\textit{In \addtoindex{C++},
 a variable declared with \texttt{constexpr} is implicitly \texttt{const}. Such a
 variable has a \DWATtype{} attribute whose value is a 
 \livelink{chap:classreference}{reference}
index 9306573..93981a7 100644 (file)
@@ -116,6 +116,7 @@ have a header
 that occurs at the beginning of the CIE and FDE structures
 in the \dotdebugframe{} section.
 
+\needlines{4}
 In an \addtoindex{initial length field}, the values \wfffffffzero through
 \wffffffff are reserved by DWARF to indicate some form of
 extension relative to \addtoindex{DWARF Version 2}; such values must not
@@ -229,6 +230,7 @@ addresses in the debugging information for a shared object
 are offsets relative to the start of the lowest region of
 memory loaded from that shared object.
 
+\needlines{4}
 \textit{This requirement makes the debugging information for
 shared objects position independent.  Virtual addresses in a
 shared object may be calculated by adding the offset to the
@@ -552,7 +554,7 @@ The value of this field is \DWUTtype{} for a type unit
 \needlines{4}
 \item \addttindex{debug\_abbrev\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
 A 
-\addtoindexx{section offset!in .debug\_types header}
+\addtoindexx{section offset!in .debug\_info header}
 4\dash byte or 8\dash byte unsigned offset into the 
 \dotdebugabbrev{}
 section. This offset associates the type unit with a
@@ -589,7 +591,7 @@ the primary type contained in this
 \item \texttt{type\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
 \addttindexx{type\_offset}
 A 4\dash byte or 8\dash byte unsigned offset 
-\addtoindexx{section offset!in .debug\_types header}
+\addtoindexx{section offset!in .debug\_info header}
 relative to the beginning
 of the \addtoindex{type unit} header.
 This offset refers to the debugging
@@ -821,36 +823,17 @@ one
 \addtoindexx{loclistptr class}
 class,
 \addtoindexx{lineptr class}
-namely \livelink{chap:classlineptr}{lineptr}, 
-\livelink{chap:classloclistptr}{loclistptr}, 
-\livelink{chap:classmacptr}{macptr} or 
-\livelink{chap:classrangelistptr}{rangelistptr}; the list
-of classes allowed by the applicable attribute in 
+namely 
+\CLASSaddrptr, 
+\CLASSlineptr, 
+\CLASSloclistptr, 
+\CLASSmacptr,  
+\CLASSrangelistptr{} or
+\CLASSstroffsetsptr; 
+the list of classes allowed by the applicable attribute in 
 Table \refersec{tab:attributeencodings}
 determines the class of the form.
 
-\textit{In DWARF V3 the forms \DWFORMdatafour{} and 
-\DWFORMdataeight{} were
-\addtoindexx{lineptr class}
-members 
-\addtoindexx{rangelistptr class}
-of 
-\addtoindexx{macptr class}
-either 
-\addtoindexx{loclistptr class}
-class constant \addtoindexx{constant class}
-or one of the classes 
-\livelink{chap:classlineptr}{lineptr},
-\livelink{chap:classloclistptr}{loclistptr}, 
-\livelink{chap:classmacptr}{macptr} or 
-\livelink{chap:classrangelistptr}{rangelistptr}, depending on context. In
-DWARF V4 
-\DWFORMdatafour{} and 
-\DWFORMdataeight{} are members of class
-constant in all cases. 
-The new 
-\DWFORMsecoffset{} replaces
-their usage for the other classes.}
 
 \needlines{4}
 Each possible form belongs to one or more of the following classes:
@@ -1061,10 +1044,13 @@ format, it is an 8\dash byte unsigned value (see Section
 \refersec{datarep:32bitand64bitdwarfformats}).
 \end{itemize}
 
-\textit{Because classes \livelink{chap:classlineptr}{lineptr}, 
-\livelink{chap:classloclistptr}{loclistptr}, 
-\livelink{chap:classmacptr}{macptr} and 
-\livelink{chap:classrangelistptr}{rangelistptr}
+\textit{Because classes
+\CLASSaddrptr, 
+\CLASSlineptr, 
+\CLASSloclistptr, 
+\CLASSmacptr, 
+\CLASSrangelistptr{} and
+\CLASSstroffsetsptr{}
 share a common representation, it is not possible for an
 attribute to allow more than one of these classes}
 
@@ -1215,17 +1201,14 @@ format, it is an 8\dash byte unsigned value (see Section
 
 \end{itemize}
 
-In no case does an attribute use 
-\addtoindexx{rangelistptr class}
-one 
-\addtoindexx{loclistptr class}
-of 
-\addtoindexx{lineptr class}
-the 
-\addtoindexx{macptr class}
-classes \livelink{chap:classlineptr}{lineptr},
-\livelink{chap:classloclistptr}{loclistptr}, \livelink{chap:classmacptr}{macptr} or 
-\livelink{chap:classrangelistptr}{rangelistptr} to point into either the
+In no case does an attribute use one of the classes 
+\CLASSaddrptr,
+\CLASSlineptr,
+\CLASSloclistptr, 
+\CLASSmacptr, 
+\CLASSrangelistptr{} or 
+\CLASSstroffsetsptr{}
+to point into either the
 \dotdebuginfo{} or \dotdebugstr{} section.
 
 The form encodings are listed in 
@@ -1526,11 +1509,12 @@ Table \refersec{tab:attributeformencodings}.
         \addtoindexx{call tail call attribute!encoding} \\
 \DWATcalltarget~\ddag &0x84 &\CLASSexprloc
         \addtoindexx{call target attribute!encoding} \\
-\DWATcalltargetclobbered!\ddag &0x85 &\CLASSexprloc
+\DWATcalltargetclobbered~\ddag &0x85 &\CLASSexprloc
         \addtoindexx{call target clobbered attribute!encoding} \\
 \DWATcallvalue~\ddag &0x86 &\CLASSexprloc
         \addtoindexx{call value attribute!encoding} \\
-
+\DWATnoreturn~\ddag &0x87 &\CLASSflag 
+        \addtoindexx{noreturn attribute!encoding} \\
 \DWATlouser&0x2000 & --- \addtoindexx{low user attribute encoding}  \\
 \DWAThiuser&\xiiifff& --- \addtoindexx{high user attribute encoding}  \\
 
@@ -1573,7 +1557,8 @@ Table \refersec{tab:attributeformencodings}.
 \DWFORMrefeight&0x14&\livelink{chap:classreference}{reference} \\
 \DWFORMrefudata&0x15&\livelink{chap:classreference}{reference}  \\
 \DWFORMindirect&0x16&(see Section \refersec{datarep:abbreviationstables}) \\
-\DWFORMsecoffset{} &0x17&\livelink{chap:classlineptr}{lineptr}, \livelink{chap:classloclistptr}{loclistptr}, \livelink{chap:classmacptr}{macptr}, \livelink{chap:classrangelistptr}{rangelistptr} \\
+\DWFORMsecoffset{} &0x17& \CLASSaddrptr, \CLASSlineptr, \CLASSloclistptr, \\
+                   &    & \CLASSmacptr, \CLASSrangelistptr, \CLASSstroffsetsptr \\
 \DWFORMexprloc{} &0x18&\livelink{chap:classexprloc}{exprloc} \\
 \DWFORMflagpresent{} &0x19&\livelink{chap:classflag}{flag} \\
 \DWFORMstrx{} \ddag &0x1a&\livelink{chap:classstring}{string} \\
@@ -1843,7 +1828,7 @@ end of list entry.
 \needlines{6}
 \subsubsection{Location List Entries in Non-Split Objects}
 A \addtoindex{location list} entry consists of two address offsets followed
-by a 2\dash byte length, followed by a block of contiguous bytes
+by an unsigned 2\dash byte length, followed by a block of contiguous bytes
 that contains a DWARF location description. The length
 specifies the number of bytes in that block. The two offsets
 are the same size as an address on the target machine.
@@ -1858,11 +1843,11 @@ offsets are the same size as an address on the target machine.
 For a \addtoindex{location list} to be specified, the base address of
 \addtoindexx{base address selection entry!in location list}
 the corresponding compilation unit must be defined 
-(see Section  \refersec{chap:normalandpartialcompilationunitentries}).
+(see Section \refersec{chap:normalandpartialcompilationunitentries}).
 
 \subsubsection{Location List Entries in Split Objects}
 An alternate form for location list entries is used in split objects. 
-Each entry begins with a one-byte code that indicates the kind of entry
+Each entry begins with an unsigned 1-byte code that indicates the kind of entry
 that follows. The encodings for these constants are given in
 Table \refersec{tab:locationlistentryencodingvalues}.
 
@@ -2551,18 +2536,21 @@ Table \refersec{tab:linenumberfileentryformatencodings}.
 
 \section{Macro Information}
 \label{datarep:macroinformation}
+The \addtoindexi{version number}{version number!macro information}
+in the macro information header is \versiondotdebugmacro{}
+(see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
 
 The source line numbers and source file indices encoded in the
 macro information section are represented as 
 unsigned LEB128\addtoindexx{LEB128!unsigned} numbers.
 
-The macro information entry type is encoded as a single byte. 
+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}
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{l|c}
@@ -2673,6 +2661,7 @@ of list entry.
 A \addtoindex{range list} entry consists of two relative addresses. The
 addresses are the same size as addresses on the target machine.
 
+\needlines{4}
 A base address selection entry and an 
 \addtoindexx{end of list entry!in range list}
 end of list entry each
index fd2c3a7..a0e8829 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}{May 13, 2014}
+\newcommand{\docdate}{May 16, 2014}
 %
 \usepackage{ifthen}
 \newboolean{isdraft}
@@ -282,7 +282,7 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \listoftables
 
 \ifthenelse{\boolean{isdraft}}
-       {       %\emptypage
+       {       \emptypage
                {% Environment to keep the following header change local
                \clearpage
                \makeevenhead{plain}{}{Change Summary}{}
@@ -311,12 +311,12 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \setcounter{secnumdepth}{5}
 
 \include{introduction}
-\include{generaldescription}            \emptypage
-\include{programscope}                  %\emptypage
+\include{generaldescription}            %\emptypage
+\include{programscope}                  \emptypage
 \include{dataobject}                    \emptypage
 \include{typeentries}                   %\emptypage
-\include{otherdebugginginformation}    \emptypage
-\include{datarepresentation}            \emptypage
+\include{otherdebugginginformation}    %\emptypage
+\include{datarepresentation}            %\emptypage
 
 %  The \appendix toggles us into appendix chapters
 \appendix
index 952221d..cd16895 100644 (file)
 %
 \newdwfnamecommands{DWATname}{DW\_AT\_name}
 \newdwfnamecommands{DWATnamelistitem}{DW\_AT\_namelist\_item}
+\newdwfnamecommands{DWATnoreturn}{DW\_AT\_noreturn}
 %
 \newdwfnamecommands{DWATobjectpointer}{DW\_AT\_object\_pointer}
 \newdwfnamecommands{DWATordering}{DW\_AT\_ordering}
 \newcommand{\dotdebuginfo}{\addtoindex{\texttt{.debug\_info}}}
 \newcommand{\dotdebugline}{\addtoindex{\texttt{.debug\_line}}}
 \newcommand{\dotdebugloc}{\addtoindex{\texttt{.debug\_loc}}}
-\newcommand{\dotdebugmacinfo}{\addtoindex{\texttt{.debug\_mac\_info}}}
+\newcommand{\dotdebugmacinfo}{\addtoindex{\texttt{.debug\_macinfo}}}
 \newcommand{\dotdebugmacro}{\addtoindex{\texttt{.debug\_macro}}}
 \newcommand{\dotdebugpubnames}{\addtoindex{\texttt{.debug\_pubnames}}}
 \newcommand{\dotdebugpubtypes}{\addtoindex{\texttt{.debug\_pubtypes}}}
 \newcommand{\versiondotdebuginfo}    {5}
 \newcommand{\versiondotdebugline}    {5}
 \newcommand{\versiondotdebugloc}     {5}
-\newcommand{\versiondotdebugmacinfo} {5}
+\newcommand{\versiondotdebugmacro}   {5}
 \newcommand{\versiondotdebugpubnames}{2}
 \newcommand{\versiondotdebugpubtypes}{2}
 \newcommand{\versiondotdebugranges}  {5}
index 7ab8382..c38c7fc 100644 (file)
@@ -2253,9 +2253,9 @@ instances of \texttt{OUTER}. An implementation is likely to require
 vendor\dash specific DWARF attributes and/or debugging information
 entries to describe such cases.
 
-Note that in C++, a member function of a class defined within
+Note that in \addtoindex{C++}, a member function of a class defined within
 a function definition does not require any vendor\dash specific
-extensions because the C++ language disallows access to
+extensions because the \addtoindex{C++} language disallows access to
 entities that would give rise to this problem. (Neither \texttt{extern}
 variables nor \texttt{static} members require any form of static link
 for accessing purposes.)
@@ -2346,7 +2346,7 @@ OUTER.CI.3.3:
 \clearpage
 \section{Constant Expression Example}
 \label{app:constantexpressionexample}
-C++ generalizes the notion of constant expressions to include
+\addtoindex{C++} generalizes the notion of constant expressions to include
 constant expression user-defined literals and functions.
 The constant declarations in Figure \refersec{fig:constantexpressionscsource}
 can be represented as illustrated in 
@@ -2509,7 +2509,7 @@ E e1;
 \section{Template Examples}
 \label{app:templateexample}
 
-The C++ template example in
+The \addtoindex{C++} template example in
 Figure \refersec{fig:ctemplateexample1source}
 can be described in DWARF as illustrated in 
 Figure \refersec{fig:ctemplateexample1dwarf}.
@@ -2561,7 +2561,7 @@ with \texttt{int} in the instance.
 There exist situations where it is
 not possible for the DWARF to imply anything about the nature
 of the original template. 
-Consider the C++ template source in
+Consider the \addtoindex{C++} template source in
 Figure \refersec{fig:ctemplateexample2source}
 and the DWARF that can describe it in
 Figure \refersec{fig:ctemplateexample2dwarf}.
index fdc4a86..6a2eddc 100644 (file)
@@ -143,28 +143,7 @@ There are no limitations on the
 \addtoindexx{attribute ordering}
 ordering of attributes within a debugging information entry.
 
-The attributes are listed in Table \refersec{tab:attributenames}.  
-
-The permissible values
-\addtoindexx{attribute value classes}
-for an attribute belong to one or more classes of attribute
-value forms.  
-Each form class may be represented in one or more ways. 
-For example, some attribute values consist
-of a single piece of constant data. 
-\doublequote{Constant data}
-is the class of attribute value that those attributes may have. 
-There are several representations of constant data,
-however (one, two, ,four, or eight bytes, and variable length
-data). 
-The particular representation for any given instance
-of an attribute is encoded along with the attribute name as
-part of the information that guides the interpretation of a
-debugging information entry.  
-
-Attribute value forms belong
-\addtoindexx{tag names!list of}
-to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
+The attributes are listed in Table \referfol{tab:attributenames}.  
 
 \setlength{\extrarowheight}{0.1cm}
 \addtoindexx{attributes!list of}
@@ -225,7 +204,7 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
            {all tail and normal calls in a subprogram are described by call site entries}
            \index{call site!summary!all tail and normal calls are described} \\
 \DWATcallallsourcecallsTARG{}
-&\livelinki{chap:DWATcallallaourcecallsofa subprogram}
+&\livelinki{chap:DWATcallallsourcecallsofasubprogram}
            {All tail, normal and inlined calls in a subprogram are described by call site and inlined subprogram entries}
            {all tail calls in a subprogram are described by call site and inlined subprogram entries}
            \index{call site!summary!all tail, normal and inlined calls are described} \\
@@ -244,7 +223,7 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
            {address of the value pointed to by an argument passed in a call}
            \index{call site!address of the value pointed to by an argument} \\
 \DWATcalldatavalueTARG{}
-&\livelinki{chap:DWATcalldatavalueofcallsite}
+&\livelinki{chap:DWATcalldatavalueofcallparameter}
            {Value pointed to by an argument passed in a call}
            {value pointed to by an argument passed in a call}
            \index{call site!value pointed to by an argument} \\
@@ -266,7 +245,7 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
            {subprogram called in a call}
            \index{call site!subprogram called} \\
 \DWATcallparameterTARG{}
-&\livelinki{chap:DWATcallparameterofcallsite}
+&\livelinki{chap:DWATcallparameterofcallparameter}
            {Parameter entry in a call}
            {parameter entry in a call}
            \index{call site!parameter entry} \\
@@ -296,7 +275,7 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
            {address of called routine, which may be clobbered, in a call}
            \index{call site!address of called routine, which may be clobbered} \\
 \DWATcallvalueTARG{}
-&\livelinki{chap:DWATcallvalueofcallsite}
+&\livelinki{chap:DWATcallvalueofcallparameter}
            {Argument value passed in a call}
            {argument value passed in a call}
            \index{call site!argument value passed} \\
@@ -411,6 +390,8 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
 &\livelinki{chap:DWATnamepathnameofcompilationsource}{Path name of compilation source}{path name of compilation source} \\
 \DWATnamelistitemTARG
 &\livelinki{chap:DWATnamelistitemnamelistitem}{Namelist item}{namelist item}\\
+\DWATnoreturnTARG
+&\livelinki{chap:DWATnoreturnofsubprogram}{\doublequote{no return} property of a subprogram}{noreturn attribute} \\
 \DWATobjectpointerTARG
 &\livelinki{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}{Object (\texttt{this}, \texttt{self}) pointer of member function}{object (\texttt{this}, \texttt{self}) pointer of member function}\\
 \DWATorderingTARG
@@ -521,6 +502,26 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
 \addtoindexx{class of attribute value!string|see {string class}}
 \addtoindexx{class of attribute value!stroffsetsptr|see {stroffsetsptr class}}
 
+The permissible values
+\addtoindexx{attribute value classes}
+for an attribute belong to one or more classes of attribute
+value forms.  
+Each form class may be represented in one or more ways. 
+For example, some attribute values consist
+of a single piece of constant data. 
+\doublequote{Constant data}
+is the class of attribute value that those attributes may have. 
+There are several representations of constant data,
+however (one, two, ,four, or eight bytes, and variable length
+data). 
+The particular representation for any given instance
+of an attribute is encoded along with the attribute name as
+part of the information that guides the interpretation of a
+debugging information entry.  
+
+Attribute value forms belong
+\addtoindexx{tag names!list of}
+to one of the classes shown in Table \referfol{tab:classesofattributevalue}.
 
 \begin{longtable}{l|p{11cm}}
 \caption{Classes of attribute value}
@@ -768,6 +769,7 @@ taken to be the result (the address of the object, the
 value of the array bound, the length of a dynamic string,
 the desired value itself, and so on).
 
+\needlines{4}
 \subsubsection{Literal Encodings}
 \label{chap:literalencodings}
 The 
@@ -824,6 +826,7 @@ size of a machine address, is stored.
 This index is relative to the value of the 
 \DWATaddrbase{} attribute of the associated compilation unit.
 
+\needlines{3}
 \textit{The \DWOPconstxNAME{} operation is provided for constants that
 require link-time relocation but should not be
 interpreted by the consumer as a relocatable address
@@ -856,7 +859,7 @@ a signed LEB128\addtoindexx{LEB128!signed} offset from
 the specified register.
 
 \itembfnl{\DWOPbregxTARG{} }
-The \DWOPbregxINDX{} operation has two operands: a register
+The \DWOPbregxNAME{} operation has two operands: a register
 which is specified by an unsigned LEB128\addtoindexx{LEB128!unsigned}
 number, followed by a signed LEB128\addtoindexx{LEB128!signed} offset.
 
@@ -915,7 +918,7 @@ The \DWOPderefsizeTARG{} operation behaves like the
 \DWOPderef{}
 operation: it pops the top stack entry and treats it as an
 address. The value retrieved from that address is pushed. In
-the \DWOPderefsizeINDX{} operation, however, the size in bytes
+the \DWOPderefsizeNAME{} operation, however, the size in bytes
 of the data retrieved from the dereferenced address is
 specified by the single operand. This operand is a 1\dash byte
 unsigned integral constant whose value may not be larger
@@ -948,7 +951,7 @@ that support
 address spaces. The top two stack
 elements are popped, and a data item is retrieved through an
 implementation\dash defined address calculation and pushed as the
-new stack top. In the \DWOPxderefsizeINDX{} operation, however,
+new stack top. In the \DWOPxderefsizeNAME{} operation, however,
 the size in bytes of the data retrieved from the 
 \addtoindexi{dereferenced}{address!dereference operator}
 address is specified by the single operand. This operand is a
@@ -1014,6 +1017,7 @@ Instead of    forcing complex thread-local storage calculations into
 the DWARF expressions, the \DWOPformtlsaddress{} allows the consumer 
 to perform the computation based on the run-time environment.}
 
+\needlines{4}
 \itembfnl{\DWOPcallframecfaTARG}
 The \DWOPcallframecfaTARG{} 
 operation pushes the value of the
@@ -1112,7 +1116,7 @@ shifts the former second entry right logically (filling with
 zero bits) by the number of bits specified by the former top
 of the stack, and pushes the result.
 
-\needlines{6}
+\needlines{3}
 \itembfnl{\DWOPshraTARG}
 The \DWOPshraTARG{} operation pops the top two stack entries,
 shifts the former second entry right arithmetically (divide
@@ -1148,9 +1152,9 @@ constant value 0 if the result of the operation is false.
 \end{itemize}
 
 Comparisons are performed as signed operations. The six
-operators are \DWOPleINDX{} (less than or equal to), \DWOPgeINDX{}
-(greater than or equal to), \DWOPeqINDX{} (equal to), \DWOPltINDX{} (less
-than), \DWOPgtINDX{} (greater than) and \DWOPneINDX{} (not equal to).
+operators are \DWOPleNAME{} (less than or equal to), \DWOPgeNAME{}
+(greater than or equal to), \DWOPeqNAME{} (equal to), \DWOPltNAME{} (less
+than), \DWOPgtNAME{} (greater than) and \DWOPneNAME{} (not equal to).
 
 \needlines{6}
 \itembfnl{\DWOPskipTARG}
@@ -1172,12 +1176,12 @@ operation, beginning after the 2\dash byte constant.
 % to an overfull hbox and a visible artifact. 
 % So we use \- to suggest hyphenation in this rare situation.
 \itembfnl{\DWOPcalltwoTARG, \DWOPcallfourTARG, \DWOPcallrefTARG}
-\DWOPcalltwoINDX
-\DWOPcallfourINDX
-and \DWOPcallrefINDX{} perform
+\DWOPcalltwoNAME
+\DWOPcallfourNAME
+and \DWOPcallrefNAME{} perform
 subroutine calls during evaluation of a DWARF expression or
 location description. 
-For \DWOPcalltwoINDX{} and \DWOPcallfour{}, 
+For \DWOPcalltwoNAME{} and \DWOPcallfour{}, 
 the operand is the 2\dash~ or 4\dash byte unsigned offset, respectively,
 of a debugging information entry in the current compilation
 unit. The \DWOPcallref{} operator has a single operand. In the
@@ -1359,6 +1363,8 @@ part of a register or stored in a memory location unrelated
 to other pieces.
 
 \end{enumerate}
+
+\needlines{3}
 \item \textit{Location lists}, which are used to 
 \addtoindexx{location list}
 describe
@@ -1503,7 +1509,7 @@ does not exist in memory but its value is nonetheless known
 and is at the top of the DWARF expression stack. In this form
 of location description, the DWARF expression represents the
 actual value of the object, rather than its location. The
-\DWOPstackvalueINDX{} operation terminates the expression.
+\DWOPstackvalueNAME{} operation terminates the expression.
 
 \itembfnl{\DWOPimplicitpointerTARG}
 The \DWOPimplicitpointerNAME{} operation specifies that the object
@@ -1597,7 +1603,7 @@ the piece within that register is defined by the ABI.
 
 \textit{Many compilers store a single variable in sets of registers,
 or store a variable partially in memory and partially in
-registers. \DWOPpieceINDX{} provides a way of describing how large
+registers. \DWOPpieceNAME{} provides a way of describing how large
 a part of a variable a particular DWARF location description
 refers to. }
 
@@ -1614,22 +1620,22 @@ preceding DWARF location description.
 Interpretation of the
 offset depends on the kind of location description. If the
 location description is empty, the offset doesn\textquoteright t matter and
-the \DWOPbitpieceINDX{} operation describes a piece consisting
+the \DWOPbitpieceNAME{} operation describes a piece consisting
 of the given number of bits whose values are undefined. If
 the location is a register, the offset is from the least
 significant bit end of the register. If the location is a
-memory address, the \DWOPbitpieceINDX{} operation describes a
+memory address, the \DWOPbitpieceNAME{} operation describes a
 sequence of bits relative to the location whose address is
 on the top of the DWARF stack using the bit numbering and
 direction conventions that are appropriate to the current
 language on the target system. If the location is any implicit
-value or stack value, the \DWOPbitpieceINDX{} operation describes
+value or stack value, the \DWOPbitpieceNAME{} operation describes
 a sequence of bits using the least significant bits of that
 value.  
 \end{enumerate}
 
-\textit{\DWOPbitpieceINDX{} is 
-used instead of \DWOPpieceINDX{} when
+\textit{\DWOPbitpieceNAME{} is 
+used instead of \DWOPpieceNAME{} when
 the piece to be assembled into a value or assigned to is not
 byte-sized or is not at the start of a register or addressable
 unit of memory.}
@@ -1687,7 +1693,7 @@ base.
 Add the contents of r1 and r2 to compute a value. This value is the
 \doublequote{contents} of an otherwise anonymous location.
 
-
+\needlines{4}
 \descriptionitemnl{\DWOPlitone{} \DWOPstackvalue{} \DWOPpiece{} 4 \DWOPbregthree{} 0 \DWOPbregfour{} 0}
 \vspace{-2\parsep}\descriptionitemnl{
 \hspace{0.5cm}\DWOPplus{} \DWOPstackvalue{} \DWOPpiece{} 4 \DWOPpiece{} 4}
@@ -1759,8 +1765,8 @@ end of list entry.
 A location list entry has two forms:
 a normal location list entry and a default location list entry.
 
-A 
-\addtoindexx{location list!normal entry}
+\needlines{4}
+\addtoindexx{location list!normal entry}
 normal location list entry consists of:
 \begin{enumerate}[1. ]
 \item A beginning address offset. 
@@ -1784,7 +1790,7 @@ and ending addresses are equal has no effect
 because the size of the range covered by such
 an entry is zero.}
 
-\item A 2-byte length describing the length of the location 
+\item An unsigned 2-byte length describing the length of the location 
 description that follows.
 
 \item A \addtoindex{single location description} 
@@ -1898,7 +1904,7 @@ Section \refersec{datarep:splitdwarfobjects}),
 location lists are contained in the \dotdebuglocdwo{} section.
 
 Each entry in the location list
-begins with a type code, which is a single byte that
+begins with a type code, which is a single unsigned byte that
 identifies the type of entry. There are five types of entries:
 \begin{enumerate}
 \itembfnl{\DWLLEendoflistentryTARG}
@@ -1980,7 +1986,7 @@ base types, user-defined types and type modifiers.
 
 \section{Accessibility of Declarations}
 \label{chap:accessibilityofdeclarations}
-\textit{Some languages, notably C++ and 
+\textit{Some languages, notably \addtoindex{C++} and 
 \addtoindex{Ada}, have the concept of
 the accessibility of an object or of some other program
 entity. The accessibility specifies which classes of other
@@ -2026,7 +2032,7 @@ Table \refersec{tab:visibilitycodes}.
 
 \section{Virtuality of Declarations}
 \label{chap:virtualityofdeclarations}
-\textit{C++ provides for virtual and pure virtual structure or class
+\textit{\addtoindex{C++} provides for virtual and pure virtual structure or class
 member functions and for virtual base classes.}
 
 The 
@@ -2052,7 +2058,7 @@ source of the application. An example is a formal parameter
 %FIXME: not as a quoted name. Changed to tt font--RB
 entry to represent the 
 \texttt{this} parameter\index{this parameter@\texttt{this} parameter}
-hidden \texttt{this} parameter that most C++
+hidden \texttt{this} parameter that most \addtoindex{C++}
 implementations pass as the first argument to non-static member
 functions.}  
 
@@ -2209,6 +2215,20 @@ information entry with a
 attribute does not need to duplicate information
 provided by the debugging information entry referenced by that specification attribute.
 
+When the non-defining declaration is contained within a type that has
+been placed in a separate type unit (see Section \refersec{chap:separatetypeunitentries}), 
+the \DWATspecification{} attribute cannot refer directly to the entry in
+the type unit. Instead, the current compilation unit may contain a
+\doublequote{skeleton} declaration of the type, which contains only the relevant
+declaration and its ancestors as necessary to provide the context
+(including containing types and namespaces). The \DWATspecification{}
+attribute would then be a reference to the declaration entry within
+the skeleton declaration tree. The debugging information entry for the
+top-level type in the skeleton tree may contain a \DWATsignature{}
+attribute whose value is the type signature 
+(see Section \refersec{datarep:typesignaturecomputation}).
+
+
 It is not the case that all attributes of the debugging information entry referenced by a
 \DWATspecification{} attribute 
 apply to the referring debugging information entry.
@@ -2306,7 +2326,7 @@ a program entity for which no name was given in the source.
 names as they appear in the source program, implementations
 of language translators that use some form of mangled name
 \addtoindexx{mangled names}
-(as do many implementations of C++) should use the unmangled
+(as do many implementations of \addtoindex{C++}) should use the unmangled
 form of the name in the 
 DWARF \DWATname{} attribute,
 \addtoindexx{name attribute}
index f467518..dc438ab 100644 (file)
@@ -155,6 +155,7 @@ it described the size of the optional string length data field if the \DWATstrin
 attribute was present.)
 \end{itemize}
 
+\needlines{4}
 \section{Changes from Version 3 to Version 4}
 \addtoindexx{DWARF Version 4}
 The following is a list of the major changes made to the DWARF Debugging Information
@@ -177,12 +178,12 @@ 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
 improve compression and duplicate elimination of DWARF information.
-\item Add support for new C++ language constructs, including rvalue references, generalized
+\item Add support for new \addtoindex{C++} language constructs, including rvalue references, generalized
 constant expressions, Unicode character types and template aliases.
 \item Clarify and generalize support for packed arrays and structures.
 \item Add new line number table support to facilitate profile based compiler optimization.
 \item Add additional support for template parameters in instantiations.
-\item Add support for strongly typed enumerations in languages (such as C++) that have two
+\item Add support for strongly typed enumerations in languages (such as \addtoindex{C++}) that have two
 kinds of enumeration declarations.
 \end{itemize}
 \addtoindex{DWARF Version 4} is compatible with 
index a647755..de0a54c 100644 (file)
@@ -82,7 +82,7 @@ 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{C++ member functions with a definition in the class declaration
+\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 
@@ -137,7 +137,7 @@ no following string).
 
 
 In the case of the name of a function member or static data
-member of a C++ structure, class or union, the name presented
+member of a \addtoindex{C++} structure, class or union, the name presented
 in the 
 \dotdebugpubnames{} 
 section is not the simple name given
@@ -1186,53 +1186,69 @@ any headers and does not support indirect string encodings or transparent includ
 
 The macro information for each
 compilation unit starts with a header followed by a series of 
-\doublequote{macroinfo}
-entries. Each macroinfo entry consists of a \doublequote{type code}
+macro information
+entries. Each entry consists of an opcode
 followed by zero or more operands. The series of entries for a
-given compilation unit ends with an entry containing a type
-code of 0.
-
-The header starts with a 2-byte \texttt{version} field, followed by a
-1-byte \texttt{flags} field. Additional fields may be present, depending
-of the value of the flags \texttt{field}. 
-    
-If the least significant bit (bit 0) (the \texttt{offset\_size} flag) 
-in the \texttt{flags} field is clear, the header is for a 32-bit 
-DWARF format macro section and offsets are 4 bytes long,
+given compilation unit ends with an entry containing an opcode of 0.
+
+\subsection{Macro Information Header}
+The macro information header contains the following fields:
+
+\begin{enumerate}[1. ]
+\item \texttt{version} (uhalf) \\
+A version number (see Section \refersec{datarep:macroinformation}).
+This number is specific to the macro information and is independent
+of the DWARF version number.
+
+\item \texttt{flags} (ubyte) \\
+The bits of the \texttt{flags} field are interpreted as a set
+of flags, some of which may indicate that additional fields follow.
+The following flags, beginning with the least significant bit, are defined:
+\begin{itemize}
+\item \addttindex{offset\_size} flag \\
+If the \texttt{offset\_size} flag is clear, the header is for a 32-bit 
+DWARF format macro section and all offsets are 4 bytes long;
 if it is set, the header is for a 64-bit DWARF format macro section 
-and offsets are 8 bytes long.
+and all offsets are 8 bytes long.
+\item \addttindex{debug\_line\_ section\_ offset} flag -- see below
+\item \addttindex{opcode\_operands\_table} flag -- see below
+\end{itemize}
+All other flags are reserved by DWARF.
 
-If the second least significant bit (bit 1) in the \texttt{flags} is set,
+\item \addttindex{debug\_line\_section\_offset} \\
+If the \texttt{debug\_line\_ section\_offset} flag is set,
 there follows an offset in the \dotdebugline{} section of the
 beginning of the line number information, encoded as 4-byte offset for
 a 32-bit DWARF format macro section and 8-byte offset for a 64-bit DWARF format
 macro section.  
 
-If the third least significant bit (bit 2) in the \texttt{flags} is set, there follows
-an \texttt{opcode\_operands} table describing the operands of the macroinfo entry types.
-The macroinfo entry types defined in this standard may, but need not, be
-described in the table, while other macroinfo entry types used in the section
-are described there.  Vendor extension macroinfo entry types are
+\item \addttindex{opcode\_operands\_table} \\
+If the \texttt{opcode\_operands\_table} flag is set, there follows
+an \texttt{opcode\_operands\_table} describing the operands of the macro information entry opcodes.
+The macro information entries defined in this standard may, but need not, be
+described in the table, while other user-defined entry opcodes used in the section
+are described there.  Vendor extension entry opcodes are
 allocated in the range from \DWMACROlouser{} to \DWMACROhiuser. Other
 unassigned codes are reserved for future DWARF standards.
 
 The table starts with a 1-byte \texttt{count} of the defined opcodes, followed by
-an entry for each of those opcodes.  Each entry starts with a 1-byte
-opcode number, followed by unsigned LEB128 encoded number of operands
-and for each operand there is a single byte describing the form in which
-the operand is encoded.  The allowed values are: 
+an entry for each of those opcodes.  Each entry starts with a 1-byte unsigned
+opcode number, followed by unsigned LEB128\addtoindexx{ULEB128} encoded number of operands
+and for each operand there is a single unsigned byte describing the form in which
+the operand is encoded.  The allowed forms are: 
 \DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
 \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight, 
 \DWFORMsdata, \DWFORMudata, \DWFORMflag, \DWFORMsecoffset,
 \DWFORMstring, \DWFORMstrp{} and \DWFORMstrx.
+\end{enumerate}
 
-\textit{The table allows a consumer to skip over unknown macroinfo entry types.}
+\textit{The opcode operands table allows a consumer to skip over unknown vendor-defined entry types.}
 
-\needlines{6}
-\subsection{Macroinfo Types}
-\label{chap:macroinfotypes}
+\needlines{4}
+\subsection{Macro Information Entries}
+\label{chap:macroinformationentries}
 
-The valid \addtoindex{macroinfo entry types} are as follows:
+The following kinds of macro information entries are defined:
 
 \begin{tabular}{ll}
 \DWMACROdefine{}            &A macro definition\\
@@ -1251,8 +1267,8 @@ The valid \addtoindex{macroinfo entry types} are as follows:
 The define and undefine macro entries have three forms that
 use different representations of their two operands.
 
-\textit{While described in pairs below, the forms of define 
-and undefine entries may be freely intermixed.}
+While described in pairs below, the forms of define 
+and undefine entries may be freely intermixed.
 
 \subsubsubsection{Define and Undefine Using Direct Strings}
 \label{chap:defineandundefinedirectentries}
@@ -1264,7 +1280,7 @@ The second operand consists of a null-terminated character
 string. 
 
 In the case of a \DWMACROdefineNAME{} entry, the value of the
-second string is the name of the macro symbol that is defined
+second operand is the name of the macro symbol that is defined
 at the indicated source line, followed immediately by the 
 \addtoindex{macro formal parameter list}
 including the surrounding parentheses (in
@@ -1306,7 +1322,8 @@ and \DWMACROundef.
 A \DWMACROdefineindirectxTARG{} or \DWMACROundefindirectxTARG{} 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 is represented using an unsigned LEB128 encoded value,
+The second operand is represented using an 
+unsigned LEB128\addtoindexx{ULEB128} encoded value,
 which is interpreted as a zero-based index into an array of offsets in the
 \dotdebugstroffsets{} section.  Apart from the encoding of the operands 
 these entries are equivalent to \DWMACROdefine{}
@@ -1337,15 +1354,17 @@ the entry marks the end of the current source file inclusion.
 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
-\DWMACROtransparentincludeNAME{} macroinfo entry instructs the consumer to 
-replace it with a sequence of macroinfo entries found
+\DWMACROtransparentincludeNAME{} entry instructs the consumer to 
+replace it with a sequence of entries found
 after the section header at the given 
 \dotdebugmacro{} offset, up to, but excluding,
-the terminating entry with type code \texttt{0}.
+the terminating entry with opcode \texttt{0}.
 
 \textit{The \DWMACROtransparentincludeNAME{} entry type makes it possible 
-to share duplicate sequences of macroinfo entries among different compilation units.}
+to share duplicate sequences of macro information entries among different 
+compilation units.}
 
+\needlines{4}
 \subsection{Base Source Entries} 
 \label{chap:basesourceentries}
 
@@ -1357,10 +1376,10 @@ the file entry in the line number information table for the
 primary source file.
 
 
-\subsection{Macroinfo Entries For Command Line Options}
-\label{chap:macinfoentriesforcommandlineoptions}
-%\DWMACROdefineINDX{}\DWMACROdefineindirectINDX{}\DWMACROindirectxINDX
-%\DWMACROundefINDX{}\DWMACROundefindirectINDX{}\DWMACROundefindirectxINDX
+\subsection{Macro Information Entries for Command Line Options}
+\label{chap:macoinformationentriesforcommandlineoptions}
+\DWMACROdefineINDX{}\DWMACROdefineindirectINDX{}\DWMACROdefineindirectxINDX
+\DWMACROundefINDX{}\DWMACROundefindirectINDX{}\DWMACROundefindirectxINDX
 In addition to producing define and undefine entries
 (see Section \refersec{chap:defineandundefineentries})
 for each of the define and undefine directives
@@ -1383,17 +1402,17 @@ and should encode the value 0 in their line number operands.
 \subsection{General rules and restrictions}
 \label{chap:generalrulesandrestrictions}
 
-All macroinfo entries within a \dotdebugmacro{}
+All macro information entries within a \dotdebugmacro{}
 section for a
 given compilation unit appear in the same order in which the
 directives were processed by the compiler.
 
-All macroinfo entries representing command line options appear
+All macro information entries representing command line options appear
 in the same order as the relevant command line options
 were given to the compiler. In the case where the compiler
 itself implicitly supplies one or more macro definitions or
 undefinitions in addition to those which may be specified on
-the command line, macroinfo entries are also produced for these
+the command line, entries are also produced for these
 implicit definitions and undefinitions, and these entries
 also appear in the proper order relative to each other and
 to any definitions or undefinitions given explicitly by the
@@ -1594,6 +1613,7 @@ represented quite compactly by recording just the differences
 starting at the beginning address of each subroutine in
 the program.}
 
+\needlines{4}
 The virtual unwind information is encoded in a self-contained
 section called 
 \dotdebugframe{}.  Entries in a 
@@ -1742,6 +1762,7 @@ If the \addttindex{segment\_size} field of this FDE's CIE is non-zero,
 the initial location is preceded by a segment selector of
 the given length.
 
+\needlines{4}
 \item  \texttt{address\_range} (target address) \\
 The 
 \addttindexx{address\_range}
@@ -1813,7 +1834,7 @@ If the \addttindex{segment\_size} field of this FDE's
 is non\dash zero, the initial location is preceded by a segment
 selector of the given length.
 
-
+\needlines{4}
 \item \textbf{\DWCFAadvancelocTARG} \\
 The \DWCFAadvancelocTARG{} instruction takes a single operand (encoded
 with the opcode) that represents a constant delta. The required
@@ -1938,6 +1959,7 @@ register number to be an offset(N) rule where the value of
 N is 
 \textit{factored offset} * \addttindex{data\_alignment\_factor}.
 
+\needlines{4}
 \item \textbf{\DWCFAoffsetextendedTARG} \\
 The \DWCFAoffsetextendedTARG{} 
 instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned} 
index cd55274..9f0977e 100644 (file)
@@ -1016,9 +1016,9 @@ calling convention codes is given in
 Table \refersec{tab:callingconventioncodes}.
 
 \begin{simplenametable}[1.4in]{Calling convention codes}{tab:callingconventioncodes}
-\DWCCnormalINDX        \\
-\DWCCprogramINDX       \\
-\DWCCnocallINDX        \\
+\DWCCnormal        \\
+\DWCCprogram       \\
+\DWCCnocall        \\
 \end{simplenametable}
 
 If this attribute is not present, or its value is the constant
@@ -1100,6 +1100,12 @@ The attribute indicates whether the subroutine
 or entry point was declared with the \doublequote{recursive} keyword
 or property.
 
+A subprogram entry may have a 
+\DWATnoreturn\livetargi{chap:DWATnoreturnofsubprogram}{ attribute}{noreturn attribute}, 
+which is a \CLASSflag. The attribute 
+indicates whether the subprogram was declared with the \doublequote{noreturn} keyword or property 
+indicating that the subprogram can be called, but will never return to its caller.
+
 \subsubsection{Call Site-Related Attributes}
 A subroutine entry may have \DWATcallalltailcalls, \DWATcallallcalls{} 
 and/or \DWATcallallsourcecalls{} attributes, each of which is a 
@@ -1107,23 +1113,29 @@ and/or \DWATcallallsourcecalls{} attributes, each of which is a
 These flags indicate the completeness of the call site information 
 within the subprogram.
 
-The \DWATcallalltailcalls{} attribute indicates that every tail call 
+The \DWATcallalltailcallsNAME{}
+\livetargi{chap:DWATcallalltailcallsofasubprogram}{attribute}{all tail calls summary attribute} 
+indicates that every tail call 
 that occurs in the code for the subprogram is described by a 
 \DWTAGcallsite{} entry. 
 (There may or may not be other non-tail calls to some of the same 
 target subprograms.)
 
-The \DWATcallallcalls{} attribute indicates that every non-inlined call
+The \DWATcallallcallsNAME{}
+\livetargi{chap:DWATcallallcallsofasubprogram}{attribute}{all calls summary attribute} 
+indicates that every non-inlined call
 (either a tail call or a normal call) that occurs in the code for the subprogram
 is described by a \DWTAGcallsite{} entry.
 
-The \DWATcallallsourcecalls{} attribute indicates that every call that occurs in the
+The \DWATcallallsourcecallsNAME{}
+\livetargi{chap:DWATcallallsourcecallsofasubprogram}{attribute}{all source calls summary attribute} 
+indicates that every call that occurs in the
 code for the subprogram, including every call inlined into it, is described by either a 
 \DWTAGcallsite{} entry or a \DWTAGinlinedsubroutine{} entry; further, any call
 that is optimized out is nonetheless also described using a \DWTAGcallsite{} entry 
 that has neither a \DWATcallpc{} nor \DWATcallreturnpc{} attribute.
 
-\textit{The \DWATcallallsourcecalls{} attribute is intended for debugging 
+\textit{The \DWATcallallsourcecallsNAME{} attribute is intended for debugging 
 information format consumers that analyse call graphs.}
 
 If the value of the \DWATcallallsourcecalls{} attribute is true then the values of the
@@ -2000,7 +2012,8 @@ while \DWTAGinlinedsubroutine{} entries describe inlined calls
 (see Section \refersec{chap:inlinedsubroutines}).
 
 The call site entry has a 
-\DWATcallreturnpcTARG{} \addtoindexi{attribute}{call return pc attribute} 
+\DWATcallreturnpcNAME{}
+\livetargi{chap:DWATcallreturnpcofcallsite}{attribute}{call return pc attribute} 
 which is the return address after the call.  
 The value of this attribute corresponds to the return address computed by 
 call frame information in the called subprogram 
@@ -2011,15 +2024,18 @@ call instruction, but on architectures with delay slots it might
 be an address after the delay slot of the call.}
 
 The call site entry may have a 
-\DWATcallpcTARG{} \addtoindexi{attribute}{call pc attribute} which is the
+\DWATcallpcNAME{}
+\livetargi{chap:DWATcallpcofcallsite}{attribute}{call pc attribute} which is the
 address of the call instruction.
 
 If the call site entry corresponds to a tail call, it has the 
-\DWATcalltailcallTARG{} \addtoindexi{attribute}{call tail call attribute},
+\DWATcalltailcallNAME{}
+\livetargi{chap:DWATcalltailcallofcallsite}{attribute}{call tail call attribute},
 which is a \CLASSflag.
 
 The call site entry may have a 
-\DWATcalloriginTARG{} \addtoindex{attribute}{call origin attribute}
+\DWATcalloriginNAME{}
+\livetargi{chap:DWATcalloriginofcallsite}{attribute}{call origin attribute}
 which is a \CLASSreference.  For direct calls or jumps where the called subprogram is
 known it is a reference to the called subprogram's debugging
 information entry.  For indirect calls it may be a reference to a
@@ -2027,25 +2043,32 @@ information entry.  For indirect calls it may be a reference to a
 the subroutine pointer that is called.
 
 The call site may have a 
-\DWATcalltargetTARG{} \addtoindexi{attribute}{call target attribute} which is
+\DWATcalltargetNAME{}
+\livetargi{dwatcalltargetofcallsite}{attribute}{call target attribute} which is
 a DWARF expression.  For indirect calls or jumps where it is unknown at
 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.
 
 The call site entry may have a 
-\DWATcalltargetclobberedTARG{} \addtoindexi{attribute}{call target clobbered attribute}
+\DWATcalltargetclobberedNAME{}
+\livetargi{chap:DWATcalltargetclobbered}{attribute}{call target clobbered attribute}
 which is a DWARF expression.  For indirect calls or jumps where the
 address is not computable without use of registers or memory locations that
 might be clobbered by the call the \DWATcalltargetclobberedNAME{}
 attribute is used instead of the \DWATcalltarget{} attribute.
 
-The call site entry may have a \DWATtype{} attribute referencing 
-a debugging information entry for the type of the called function.  
-When \DWATcallorigin{} is present, \DWATtype{} is usually omitted.
-
-The call site entry may have \DWATcallfile{}, \DWATcallline{} and
-\DWATcallcolumn{} attributes, each of whose value is an integer constant.
+The call site entry may have a \DWATtypeNAME{}
+\livetargi{chap:DWATtypeofcallsite}{attribute}{type attribute!of call site entry}
+referencing a debugging information entry for the type of the called function.  
+When \DWATcallorigin{} is present, \DWATtypeNAME{} is usually omitted.
+
+The call site entry may have 
+\DWATcallfileNAME{}, \DWATcalllineNAME{} and \DWATcallcolumnNAME{} 
+\livetargi{chap:DWATcallfileofcallsite}{attributes,}{call file attribute!of call site entry}
+\livetargi{chap:DWATcalllineofcallsite}{}{call line attribute!of call site entry}
+\livetargi{chap:DWATcallcolumnofcallsite}{}{call column attribute!of call site entry}
+each of whose value is an integer constant.
 These attributes represent the source file, source line number, and source
 column number, respectively, of the first character of the call statement or
 expression.  The call file, call line, and call column attributes are
@@ -2061,11 +2084,12 @@ The call site entry may own \DWTAGcallsiteparameterTARG{} debugging information
 entries\index{call site parameter entry} representing the parameters passed to the call.
 Each such entry has a \DWATlocation{} attribute which is a location expression.
 This location expression describes where the parameter is passed
-in (usually either some register, or a memory location expressible as the
+(usually either some register, or a memory location expressible as the
 contents of the stack register plus some offset).
 
-Each \DWTAGcallsiteparameterTARG{} entry may have a 
-\DWATcallvalue{} \addtoindexi{attribute}{call value attribute}
+Each \DWTAGcallsiteparameter{} entry may have a 
+\DWATcallvalueNAME{}
+\livetargi{chap:DWATcallvalueofcallparameter}{attribute}{call value attribute}
 which is a DWARF expression.  This expression computes the value
 passed for that parameter.  The expression should not use registers or memory
 locations that might be clobbered by the call, as it might be evaluated after
@@ -2083,9 +2107,11 @@ use the values at all.}
 For parameters passed by reference, where the code passes a pointer to
 a location which contains the parameter, or for reference type parameters
 the \DWTAGcallsiteparameter{} entry may also have 
-\DWATcalldatalocation{} \addtoindexi{attribute}{call data location attribute}
+\DWATcalldatalocationNAME{}
+\livetargi{chap:DWATcalldatalocationofcallparameter}{attribute}{call data location attribute}
 whose value is a location expression and a
-\DWATcalldatavalue{} \addtoindexi{attribute}{call data value attribute}
+\DWATcalldatavalueNAME{}
+\livetargi{chap:DWATcalldatavalueofcallparameter}{attribute}{call data value attribute}
 whose value is a DWARF expression.  The \DWATcalldatalocationNAME{} attribute 
 describes where the referenced value lives during the call.  If it is just 
 \DWOPpushobjectaddress{}, it may be left out.  The 
@@ -2095,7 +2121,8 @@ locations that might be clobbered by the call, as it might be evaluated after
 unwinding from the called function back to the caller.
 
 Each call site parameter entry may also have a 
-\DWATcallparameter{} \addtoindexi{attribute}{call parameter entry}
+\DWATcallparameter{}
+\livetargi{chap:DWATcallparameterofcallparameter}{attribute}{call parameter attribute}
 which contains a reference to a \DWTAGformalparameter{} entry,
 \DWATtype{} attribute referencing the type of the parameter or \DWATname{}
 attribute describing the parameter's name.
index f061ceb..28d7993 100644 (file)
@@ -38,31 +38,32 @@ format would be represented by a change in the
 \endfoot
   \hline
 \endlastfoot
-\dotdebugabbrev{}   & - & - & - & - \\
-\dotdebugaddr{}                & x & x & x & 5 \\
+\dotdebugabbrev{}   & * & * & * & * \\
+\dotdebugaddr{}            & - & - & - & 5 \\
 \dotdebugaranges{}  & 2 & 2 & 2 & 2 \\
 \dotdebugframe{}    & 1 & 3 & 4 & 4 \\
 \dotdebuginfo{}     & 2 & 3 & 4 & 5 \\
 \dotdebugline{}     & 2 & 3 & 4 & 5 \\
-\dotdebugloc{}      & - & - & - & 5 \\
-\dotdebugmacinfo{}  & - & - & - & x \\
-\dotdebugmacro{}    & x & x & x & 5 \\
+\dotdebugloc{}      & * & * & * & 5 \\
+\dotdebugmacinfo{}  & * & * & * & - \\*
+\dotdebugmacro{}    & - & - & - & 5 \\
 \dotdebugpubnames{} & 2 & 2 & 2 & 2 \\
-\dotdebugpubtypes{} & x & 2 & 2 & 2 \\
-\dotdebugranges{}   & x & - & - & 5 \\
-\dotdebugstr{}      & - & - & - & - \\
-\dotdebugstroffsets & x & x & x & 5 \\
-
-\hspace{3cm}\textit{(.dwo sections)}                              \\
-\dotdebugabbrevdwo  & x & x & x & - \\
-\dotdebuginfodwo    & x & x & x & 5 \\
-\dotdebuglinedwo    & x & x & x & 5 \\
-\dotdebuglocdwo     & x & x & x & 5 \\
-\dotdebugmacrodwo   & x & x & x & 5 \\
-\dotdebugstrdwo     & x & x & x & - \\
+\dotdebugpubtypes{} & - & 2 & 2 & 2 \\
+\dotdebugranges{}   & - & * & * & 5 \\
+\dotdebugstr{}      & * & * & * & * \\
+\dotdebugstroffsets & - & - & - & 5 \\
+\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (DWARF Version 4)}
+                    & - & - & 4 & - \\
+
+\hspace{3cm}\textit{(.dwo sections)}\\
+\dotdebugabbrevdwo  & - & - & - & * \\
+\dotdebuginfodwo    & - & - & - & 5 \\
+\dotdebuglinedwo    & - & - & - & 5 \\
+\dotdebuglocdwo     & - & - & - & 5 \\
+\dotdebugmacrodwo   & - & - & - & 5 \\
+\dotdebugstrdwo     & - & - & - & * \\
 \dotdebugstroffsetsdwo 
-                    & x & x & x & 5 \\
-
+                    & - & - & - & 5 \\
 \end{longtable}
 \end{centering}
 
@@ -74,10 +75,10 @@ Notes:
 \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
+\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{x} means that the section was not defined in that
+\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 
index 8204b99..cfd7d47 100644 (file)
@@ -476,7 +476,7 @@ Name&Meaning\\ \hline
 \addtoindexx{packed qualified type entry} \addtoindexx{Ada} \addtoindexx{Pascal} \\
 \DWTAGpointertypeTARG{} & Pointer to an object of
 the type being modified \addtoindexx{pointer qualified type entry} \\
-\DWTAGreferencetypeTARG& C++ (lvalue) reference 
+\DWTAGreferencetypeTARG& \addtoindex{C++} (lvalue) reference 
 to an object of the type 
 \addtoindexx{reference type entry}
 \mbox{being} modified
@@ -486,7 +486,7 @@ restrict
 \addtoindexx{restricted type entry}
 qualified type
 \addtoindexx{restrict qualified type} \\
-\DWTAGrvaluereferencetypeTARG{} & C++
+\DWTAGrvaluereferencetypeTARG{} & \addtoindex{C++}
 \addtoindexx{rvalue reference type entry}
 rvalue 
 \addtoindexx{restricted type entry}
@@ -494,7 +494,7 @@ reference to an object of the type \mbox{being} modified
 \addtoindexx{rvalue reference qualified type entry} \\
 \DWTAGsharedtypeTARG&\addtoindex{UPC} shared qualified type 
 \addtoindexx{shared qualified type entry} \\
-\DWTAGvolatiletypeTARG&C or C++ volatile qualified type 
+\DWTAGvolatiletypeTARG&\addtoindex{C} or \addtoindex{C++} volatile qualified type 
 \addtoindexx{volatile qualified type entry} \\
 \hline
 \end{tabular}
@@ -519,7 +519,7 @@ character. This is encoded in DWARF as:}
 \end{alltt}
 \end{dwflisting}
 
-\needlines{5}
+%\needlines{5}
 \textit{On the other hand}
 \begin{lstlisting}[numbers=none]                        
    volatile unsigned char * const restrict p;
@@ -748,7 +748,7 @@ called \doublequote{members} in \addtoindex{C} and
 \addtoindex{C++}, and \doublequote{fields} in \addtoindex{Pascal}.}
 
 \textit{The components of these collections each exist in their
-own space in computer memory. The components of a C or C++
+own space in computer memory. The components of a \addtoindex{C} or \addtoindex{C++}
 \doublequote{union} all coexist in the same memory.}
 
 \textit{\addtoindex{Pascal} and 
@@ -2359,7 +2359,7 @@ The presence of the
 \hypertarget{chap:DWATrankofdynamicarray}{\DWATrankINDX}
 attribute indicates that an array's rank
 (number of dimensions) is dynamic, and therefore unknown at compile
-time. The value of the \DWATrankINDX{} attribute is either an integer constant
+time. The value of the \DWATrankNAME{} attribute is either an integer constant
 or a location expression whose evaluation yields the dynamic rank.
 
 The bounds of an array with dynamic rank are described using a