all review comments as of this date.
Signed-off-by: Ron Brender <ron.brender@gmail.com>
&\DWATdatalocation{} \\
&\DWATdeclaration{} \\
&\DWATdescription{} \\
+&\DWATexportsymbols{} \\
&\DWATname{} \\
&\DWATsibling{} \\
&\DWATsignature{} \\
\hline
\DWTAGnamespace
-&\livelink{chap:DECL}{DECL} \\
-&\DWATdescription{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATdescription{} \\*
+&\DWATexportsymbols{} \\*
&\DWATextension{} \\
&\DWATname{} \\*
&\DWATsibling{} \\*
&\DWATbasetypes{} \\*
&\DWATcompdir{} \\
&\DWATdescription{} \\
+&\DWATdwoid{} \\
+&\DWATdwoname{} \\
&\DWATentrypc{} \\
&\DWATidentifiercase{} \\
&\DWAThighpc{} \\
&\DWATdatalocation{} \\
&\DWATdeclaration{} \\
&\DWATdescription{} \\
+&\DWATexportsymbols{} \\
&\DWATname{} \\
&\DWATsibling{} \\
&\DWATsignature{} \\
&\DWATdatalocation{} \\
&\DWATdeclaration{} \\
&\DWATdescription{} \\
+&\DWATexportsymbols{} \\
&\DWATname{} \\
&\DWATsibling{} \\
&\DWATsignature{} \\
\hline
\DWTAGvariantpart
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaccessibility{} \\*
&\DWATdeclaration{} \\
&\DWATdiscr{} \\*
&\DWATsibling{} \\*
\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), \\
+ & Editorial cleanups \& corrections \\
11/20/2014 & Editorial corrections for 100831.1 and 110722.1 \\
11/19/2014 & Editorial corrections in Appendix F.2 \\
11/16/2014 & Add example text for Appendix F.2 \\
\addtoindexx{all source calls summary attribute} \\
\DWATcallalltailcalls~\ddag &0x7c&\CLASSflag
\addtoindexx{all tail calls summary attribute} \\
-\DWATcalldatalocation~\ddag &0x7d &\CLASSexprloc
- \addtoindexx{call data location attribute} \\
-\DWATcalldatavalue~\ddag &0x7e &\CLASSexprloc
- \addtoindexx{call data value attribute} \\
+\DWATcallreturnpc~\ddag &0x7d &\CLASSaddress
+ \addtoindexx{call return pc attribute} \\
+\DWATcallvalue~\ddag &0x7e &\CLASSexprloc
+ \addtoindexx{call value attribute} \\
\DWATcallorigin~\ddag &0x7f &\CLASSexprloc
\addtoindexx{call origin attribute} \\
\DWATcallparameter~\ddag &0x80 &\CLASSreference
\addtoindexx{call parameter attribute} \\
\DWATcallpc~\ddag &0x81 &\CLASSaddress
\addtoindexx{call pc attribute} \\
-\DWATcallreturnpc~\ddag &0x82 &\CLASSaddress
- \addtoindexx{call return pc attribute} \\
-\DWATcalltailcall~\ddag &0x83 &\CLASSflag
+\DWATcalltailcall~\ddag &0x82 &\CLASSflag
\addtoindexx{call tail call attribute} \\
-\DWATcalltarget~\ddag &0x84 &\CLASSexprloc
+\DWATcalltarget~\ddag &0x83 &\CLASSexprloc
\addtoindexx{call target attribute} \\
-\DWATcalltargetclobbered~\ddag &0x85 &\CLASSexprloc
+\DWATcalltargetclobbered~\ddag &0x84 &\CLASSexprloc
\addtoindexx{call target clobbered attribute} \\
-\DWATcallvalue~\ddag &0x86 &\CLASSexprloc
- \addtoindexx{call value attribute} \\
+\DWATcalldatalocation~\ddag &0x85 &\CLASSexprloc
+ \addtoindexx{call data location attribute} \\
+\DWATcalldatavalue~\ddag &0x86 &\CLASSexprloc
+ \addtoindexx{call data value attribute} \\
\DWATnoreturn~\ddag &0x87 &\CLASSflag
\addtoindexx{noreturn attribute} \\
\DWATalignment~\ddag &0x88 &\CLASSconstant
\addtoindexx{alignment attribute} \\
+\DWATexportsymbols~\ddag &0x89 &\CLASSflag
+ \addtoindexx{export symbols attribute} \\
\DWATlouser&0x2000 & --- \addtoindexx{low user attribute encoding} \\
\DWAThiuser&\xiiifff& --- \addtoindexx{high user attribute encoding} \\
unsigned integer, when the big end is all zeroes or sign
extension bits.}
-Unsigned LEB128\addtoindexx{LEB128!unsigned} (ULEB128) numbers are encoded as follows:
+Unsigned LEB128\addtoindexx{LEB128!unsigned} (\addtoindex{ULEB128})
+numbers are encoded as follows:
\addtoindexx{LEB128!unsigned, encoding as}
start at the low order end of an unsigned integer and chop
it into 7\dash bit chunks. Place each chunk into the low order 7
that an additional byte follows.
-The encoding for signed, two\textquoteright s complement LEB128 (SLEB128)
-\addtoindexx{LEB128!signed, encoding as}
+The encoding for signed, two\textquoteright s complement LEB128
+(\addtoindex{SLEB128}) \addtoindexx{LEB128!signed, encoding as}
numbers is similar, except that the criterion for discarding
high order bytes is not whether they are zero, but whether
they consist entirely of sign extension bits. Consider the
\DWLANGSwift{} \ddag &0x001e &0 \addtoindexx{Swift} \\
\DWLANGJulia{} \ddag &0x001f &1 \addtoindexx{Julia} \\
\DWLANGDylan{} \ddag &0x0020 &0 \addtoindexx{Dylan} \\
-\DWLANGCplusplusfourteen{} \ddag &0x0021 &0 \addtoindexx{C++:2014 (ISO)}\\
+\DWLANGCplusplusfourteen{}~\ddag &0x0021 &0 \addtoindexx{C++:2014 (ISO)} \\
+\DWLANGFortranzerothree{}~\ddag &0x0022 &1 \addtoindexx{Fortran:2004 (ISO)} \\
+\DWLANGFortranzeroeight{}~\ddag &0x0023 &1 \addtoindexx{Fortran:2010 (ISO)} \\
\DWLANGlouser{} &0x8000 & \\
\DWLANGhiuser{} &\xffff & \\
% 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}{November 20, 2014}
+\newcommand{\docdate}{December 28, 2014}
%
\usepackage{ifthen}
\newboolean{isdraft}
% use when the index is different from the text and target.
\newcommand{\livelinki}[3]{\hyperlink{#1}{#2}\index{#3}}
% livetarg is the declaration that is the target of livelinks.
-% FIXME: we might want livetarg and livetargi #2 to be \textbf{#2}
\newcommand{\livetarg}[2]{\hypertarget{#1}{#2}\index{#2}}
% When we want the index entry to look different from the name.
\newcommand{\livetargi}[3]{\hypertarget{#1}{#2}\index{#3}}
\include{attributesbytag} \emptypage
\include{debugsectionrelationships} \emptypage
\include{encodingdecoding} \emptypage
-\include{examples} %\emptypage
+\include{examples} \emptypage
\include{compression} \emptypage
\include{splitobjects} %\emptypage
\include{sectionversionnumbers} \emptypage
\newdwfnamecommands{DWATentrypc}{DW\_AT\_entry\_pc}
\newdwfnamecommands{DWATenumclass}{DW\_AT\_enum\_class}
\newdwfnamecommands{DWATexplicit}{DW\_AT\_explicit}
+\newdwfnamecommands{DWATexportsymbols}{DW\_AT\_export\_symbols}
\newdwfnamecommands{DWATextension}{DW\_AT\_extension}
\newdwfnamecommands{DWATexternal}{DW\_AT\_external}
%
\newdwfnamecommands{DWLANGFortranseventyseven}{DW\_LANG\_Fortran77}
\newdwfnamecommands{DWLANGFortranninety}{DW\_LANG\_Fortran90}
\newdwfnamecommands{DWLANGFortranninetyfive}{DW\_LANG\_Fortran95}
+\newdwfnamecommands{DWLANGFortranzerothree}{DW\_LANG\_Fortran03}
+\newdwfnamecommands{DWLANGFortranzeroeight}{DW\_LANG\_Fortran08}
\newdwfnamecommands{DWLANGGo}{DW\_LANG\_Go}
\newdwfnamecommands{DWLANGHaskell}{DW\_LANG\_Haskell}
\newdwfnamecommands{DWLANGhiuser}{DW\_LANG\_hi\_user}
\label{fig:fortrandynamictypeexampledwarfdescription}
\end{figure}
-
\clearpage
+\subsection{C/C++ Anonymous Structure Example}
+\label{app:ccxxanonymousstructureexample}
+\addtoindexx{anonymous structure}
+An example of a \addtoindex{C}/\addtoindex{C++} structure is shown in
+Figure \ref{fig:anonymousstructureexamplesourcefragment}.
+For this source, the DWARF description in
+Figure \ref{fig:anonymousstructureexampledwarfdescription}
+is appropriate. In this example, \texttt{b} is referenced as if it
+were defined in the enclosing structure \texttt{foo}.
+
+\begin{figure}[h]
+\begin{lstlisting}
+struct foo {
+ int a;
+ struct {
+ int b;
+ };
+} x;
+
+void bar(void)
+{
+ struct foo t;
+ t.a = 1;
+ t.b = 2;
+}
+
+\end{lstlisting}
+\caption{Anonymous structure example: source fragment}
+\label{fig:anonymousstructureexamplesourcefragment}
+\end{figure}
+
+\begin{figure}[h]
+\begin{dwflisting}
+\begin{alltt}
+1$: \DWTAGstructuretype
+ \DWATname("foo")
+2$: \DWTAGmember
+ \DWATname("a")
+3$: \DWTAGstructuretype
+ \DWATexportsymbols
+4$: \DWTAGmember
+ \DWATname("b")
+\end{alltt}
+\end{dwflisting}
+\caption{Anonymous structure example: DWARF description}
+\label{fig:anonymousstructureexampledwarfdescription}
+\end{figure}
+
\subsection{Ada Example}
\label{app:adaexample}
Figure \refersec{fig:adaexamplesourcefragment}
\end{figure}
\clearpage
-\section{Namespace Example}
-\label{app:namespaceexample}
+\section{Namespace Examples}
+\label{app:namespaceexamples}
The \addtoindex{C++} example in
-Figure \refersec{fig:namespaceexamplesourcefragment}
+Figure \refersec{fig:namespaceexample1sourcefragment}
is used
\addtoindexx{namespace (C++)!example}
to illustrate the representation of namespaces.
The DWARF representation in
-Figure \refersec{fig:namespaceexampledwarfdescription}
+Figure \refersec{fig:namespaceexample1dwarfdescription}
is appropriate.
\begin{figure}[h]
return myfunc2(3) + j + i + a + 2;
}
\end{lstlisting}
-\caption{Namespace example: source fragment}
-\label{fig:namespaceexamplesourcefragment}
+\caption{Namespace example \#1: source fragment}
+\label{fig:namespaceexample1sourcefragment}
\end{figure}
...
\end{alltt}
\end{dwflisting}
-\caption{Namespace example: DWARF description}
-\label{fig:namespaceexampledwarfdescription}
+\caption{Namespace example \#1: DWARF description}
+\label{fig:namespaceexample1dwarfdescription}
\end{figure}
\begin{figure}
\end{dwflisting}
\begin{center}
\vspace{3mm}
-Figure~\ref{fig:namespaceexampledwarfdescription}: Namespace example: DWARF description \textit{(concluded)}
+Figure~\ref{fig:namespaceexample1dwarfdescription}: Namespace example \#1: DWARF description \textit{(concluded)}
\end{center}
\end{figure}
+\clearpage
+As a further namespace example, consider the inlined namespace shown in
+Figure \refersec{fig:namespaceexample2sourcefragment}. For this source,
+the DWARF description in Figure \ref{fig:namespaceexample2dwarfdescription}
+is appropriate. In this example, \texttt{a} may be referenced either as a member of
+the fully qualified namespace \texttt{A::B}, or as if it were defined
+in the enclosing namespace, \texttt{A}.
+
+\begin{figure}[h]
+\begin{lstlisting}
+namespace A {
+ inline namespace B { // (1) inline namespace
+ int a;
+ }
+}
+
+void foo (void)
+{
+ using A::B::a;
+ a = 1;
+}
+
+void bar (void)
+{
+ using A::a;
+ a = 2;
+}
+\end{lstlisting}
+\caption{Namespace example \#2: source fragment}
+\label{fig:namespaceexample2sourcefragment}
+\end{figure}
+
+\begin{figure}[h]
+\begin{dwflisting}
+\begin{alltt}
+1$: \DWTAGnamespace
+ \DWATname("A")
+2$: \DWTAGnamespace
+ \DWATname("B")
+ \DWATexportsymbols
+3$: \DWTAGvariable
+ \DWATname("a")
+\end{alltt}
+\end{dwflisting}
+\caption{Namespace example \#2: DWARF description}
+\label{fig:namespaceexample2dwarfdescription}
+\end{figure}
+
\clearpage
\section{Member Function Examples}
\label{app:memberfunctionexample}
Figure \refersec{fig:stringtypeexampledwarf} is appropriate.
\begin{figure}[h]
+\addtoindexx{ISO 10646 character set standard}
\begin{lstlisting}
program character_kind
use iso_fortran_env
selected_char_kind ("ascii")
integer, parameter :: ucs4 =
selected_char_kind ('ISO_10646')
-\addtoindexx{ISO 10646 character set standard}
character(kind=ascii, len=26) :: alphabet
character(kind=ucs4, len=30) :: hello_world
character (len=*), parameter :: all_digits="0123456789"
! Afterwards it is not, the call could have clobbered the register,
! and it is not saved in the fn2 function stack frame either, but
-! perhap scan be looked up in the caller
+! perhaps can be looked up in the caller
!
<L2, L3> DW_OP_entry_value 1 DW_OP_reg0 DW_OP_stack_value
<0, 0>
&\livelinki{chap:DWATenumclasstypesafeenumerationdefinition}{Type safe enumeration definition}{type safe enumeration definition}\\
\DWATexplicitTARG
&\livelinki{chap:DWATexplicitexplicitpropertyofmemberfunction}{Explicit property of member function}{explicit property of member function}\\
+\DWATexportsymbolsTARG
+&\livelinki{chap:DWATexportsymbolsofnamespace}{Export (inline) symbols of namespace}
+ {export symbols of a namespace} \\
+&\livelinki{chap:DWATexportsymbolsofstructunionclass}{Export symbols of a structure, union or class}
+ {export symbols of a structure, union or class} \\
\DWATextensionTARG
&\livelinki{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}{Previous namespace extension or original namespace}{previous namespace extension or original namespace}\\
\DWATexternalTARG
\section{Target Addresses}
\label{chap:targetaddresses}
Many places in this document refer to the size of an
-\addtoindexx{size of an address|see{\textit{also} address\_size}}
+\addtoindexx{size of an address|see{\textit{also} \texttt{address\_size}}}
\addtoindexi{address}{size of an address}
\addtoindexx{address size|see{size of an address}}
\addtoindexx{address size|see{\textit{also} \texttt{address\_size}}}
%FIXME: similar undefined as just above
%\descriptionitemnl{\DWOPentryvalue{} 6 \DWOPentryvalue{} 1 \DWOPregfour{} \DWOPplusuconst{} 16 \DWOPderef{} \DWOPstackvalue }
%These two location expressions do the same thing, p
-Push the value of the
-memory location with the size of an address pointed to by the value of
-register 4 upon entering the current subprogram and add 16.
+Add 16 to the value register 4 had upon entering the current subprogram
+to form an address and then push the value of the memory location at that address.
\end{description}
\DWACCESSprotectedTARG{} \\
\end{simplenametable}
+\needlines{5}
\section{Visibility of Declarations}
\label{chap:visibilityofdeclarations}
A count of the number of entries that occur in the
following \addttindex{directory\_entry\_format} field.
-\item \texttt{directory\_entry\_format} (sequence of uleb pairs) \\
+\item \texttt{directory\_entry\_format} (sequence of ULEB128 pairs) \\
\addttindexx{directory\_entry\_format}
A sequence of directory entry format descriptions.
- Each description consists of a pair of uleb values:
+ Each description consists of a pair of ULEB128 values:
\begin{itemize}
\setlength{\itemsep}{0em}
\item A content type code (see below)
\end{itemize}
\needlines{4}
-\item \texttt{directories\_count} (uleb) \\
+\item \texttt{directories\_count} (ULEB128) \\
\addttindexx{directories\_count}
A count of the number of entries that occur in the
following directories field.
If this field is zero, then the \addttindex{file\_names\_count} field
(see below) must also be zero.
-\item \texttt{file\_name\_entry\_format} (sequence of uleb pairs) \\
+\item \texttt{file\_name\_entry\_format} (sequence of ULEB128 pairs) \\
\addttindexx{file\_name\_entry\_format}
A sequence of file entry format descriptions.
-Each description consists of a pair of uleb values:
+Each description consists of a pair of ULEB128 values:
\begin{itemize}
\setlength{\itemsep}{0em}
\item A content type code (see below)
\item A form code using the attribute form codes
\end{itemize}
-\item \texttt{file\_names\_count} (uleb) \\
+\item \texttt{file\_names\_count} (ULEB128) \\
\addttindexx{file\_names\_count}
A count of the number of file name entries that occur
in the following \addttindex{file\_names} field.
\DWLANGFortranseventysevenTARG & ISO FORTRAN:1977 \addtoindexx{FORTRAN:1977 (ISO)} \\
\DWLANGFortranninetyTARG & ISO Fortran:1990 \addtoindexx{Fortran:1990 (ISO)} \\
\DWLANGFortranninetyfiveTARG & ISO Fortran:1995 \addtoindexx{Fortran:1995 (ISO)} \\
+\DWLANGFortranzerothreeTARG & ISO Fortran:2004 \addtoindexx{Fortran:2004 (ISO)} \\
+\DWLANGFortranzeroeightTARG & ISO Fortran:2010 \addtoindexx{Fortran:2010 (ISO)} \\
\DWLANGGoTARG{}~\dag & \addtoindex{Go} \\
\DWLANGHaskellTARG{} \dag & \addtoindex{Haskell} \\
\DWLANGJavaTARG{} & \addtoindex{Java}\\
Section \refersec{datarep:splitdwarfobjects}), the
compilation unit in the \dotdebuginfo{} section is a "skeleton"
compilation unit, which contains only a subset of the
-attributes of the full compilation unit. In general, it
-contains those attributes that are necessary for the consumer
+attributes of a full normal or partial compilation unit. In general,
+it contains those attributes that are necessary for the consumer
to locate the DWARF object where the full compilation unit
can be found, and for the consumer to interpret references to
addresses in the program.
including certain declarations that are also object or
function definitions.}
+A namespace may have a \DWATexportsymbolsNAME{} attribute
+\livetarg{chap:DWATexportsymbolsofnamespace}{}
+\addtoindexx{export symbols attribute}
+\addtoindexx{inline namespace|see{\textit{also} export symbols attribute}}
+which indicates that all member names defined within the
+namespace may be referenced as if they were defined within
+the containing namespace.
+
+\textit{This may be used to describe an \addtoindex{inline namespace} in \addtoindex{C++}}.
+
If a type, variable, or function declared in a namespace is
defined outside of the body of the namespace declaration,
that type, variable, or function definition entry has a
every \addtoindex{C++} compilation unit.
}
-\textit{For a \addtoindex{C++} namespace example,
-see Appendix \refersec{app:namespaceexample}.
+\textit{For \addtoindex{C++} namespace examples,
+see Appendix \refersec{app:namespaceexamples}.
}
-
+\needlines{5}
\subsection{Imported (or Renamed) Declaration Entries}
\label{chap:importedorrenameddeclarationentries}
\textit{Some languages support the concept of importing into or making
\addtoindexx{namespace (C++)!using declaration}
\addtoindexx{using declaration|see {namespace (C++), using declaration}}
that imports an entity in terms of a namespace alias. See
-Appendix \refersec{app:namespaceexample}
+Appendix \refersec{app:namespaceexamples}
for an example.
}
\DWATcallallcalls{} attribute is true then the value of the \DWATcallalltailcalls{}
attribute is also true and the latter attribute need not be present.
+\needlines{5}
\subsection{Subroutine and Entry Point Return Types}
\label{chap:subroutineandentrypointreturntypes}
\subsection{Structure, Union and Class Type Entries}
\label{chap:structureunionandclasstypeentries}
-
-
Structure, union, and class types are represented by debugging
\addtoindexx{structure type entry}
information entries
and appear in the same order as the corresponding declarations
in the source program.
+A structure, union, or class type may have a \DWATexportsymbolsNAME{}
+attribute
+\livetarg{chap:DWATexportsymbolsofstructunionclass}{}
+which indicates that all member names defined within
+the structure, union, or class may be referenced as if they were
+defined within the containing structure, union, or class.
+
+\textit{This may be used to describe anonymous structures, unions
+and classes in \addtoindex{C} or \addtoindex{C++}}.
+
A structure type, union type or class type entry may have
either a \DWATbytesize{} or a
\DWATbitsize{} attribute
the \DWATreference{} and \DWATrvaluereference{} attributes, respectively.
See also Section \refersec{chap:memberfunctionentries}.}
+\needlines{4}
A subroutine type entry may have the \DWATreference{} or
\DWATrvaluereference{} attribute to indicate that it describes the
type of a member function with reference or rvalue-reference
an object of the type is
currently allocated or not.
+\needlines{4}
\hypertarget{chap:DWATassociatedassociationstatusoftypes}{}
The
\DWATassociated{} attribute