In the following, it will be helpful to refer to the examples
in
-Figure \refersec{app:duplicateeliminationexample1csource}
+Figure \ref{app:duplicateeliminationexample1csource}
through
-Figure \refersec{app:duplicateeliminationexample2companiondwarf}
+Figure \ref{app:duplicateeliminationexample2companiondwarf}
of
Section \refersec{app:examples}.
\addtoindexx{section group!name}
For the subsequent
\addtoindex{C++} example, a name like
-
-<producer-prefix>.<file-designator>.<gid-number>
-
+\begin{alltt}
+
<producer-prefix>.<file-designator>.<gid-number>
+\end{alltt}
will suffice, where
-\begin{itemize}
+\begin{description}
-\item \textless producer\dash prefix \textgreater
+\item [\textless producer\dash prefix\textgreater]
is some string specific to the
producer, which has a language\dash designation embedded in the
name when appropriate. (Alternatively, the language name
\textless gid\dash number \textgreater).
-\item \textless file\dash designator \textgreater
+\item [\textless file\dash designator\textgreater]
names the file, such as wa.h in
the example.
-\item \textless gid\dash number \textgreater
+\item [\textless gid\dash number\textgreater]
is a string generated to identify the
specific wa.h header file in such a way that
\item a 'matching' output from another compile generates
the same
-\textless gid\dash number \textgreater,
+\textless gid\dash number\textgreater,
and
\item a non\dash matching output (say because of \#defines)
generates a different
-\textless gid\dash number \textgreater.
+\textless gid\dash number\textgreater.
\end{itemize}
-\end{itemize}
+\end{description}
\textit{It may be useful to think of a
-\textless gid\dash number \textgreater
+\textless gid\dash number\textgreater
as a kind
of ``digital signature'' that allows a fast test for the
equality of two
\end{alltt}
where
-\begin{itemize}
-\item \textless prefix \textgreater\
+\begin{description}
+\item [\textless prefix\textgreater]
distinguishes this as a DWARF debug info name, and should identify the producer
and, when appropriate, the language.
-\item \textless file\dash designator\textgreater\
+\item [\textless file\dash designator\textgreater]
and
-\textless gid\dash number \textgreater
+\texttt{\textless gid\dash number\textgreater}
are as above.
-\item \textless die\dash number \textgreater
+\item [\textless die\dash number\textgreater]
could be a number sequentially assigned
to entities (tokens, perhaps) found
during compilation.
-\end{itemize}
+\end{description}
In general, every point in the
\addtoindexx{section group}
quality\dash of\dash implementation issue.
It is up to the producer to ensure that if
-<die-numbers>
-\textless die\dash numbers \textgreater
+\textless die\dash numbers\textgreater\
in separate compilations would not match properly then a
distinct
-\textless gid\dash number \textgreater
+\textless gid\dash number\textgreater\
is generated.
Note that only
\livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} is not necessary
for a local label.)}
+% This should be a subsubsubsection header but that does work...
\textbf{Use of \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} versus
\livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit}}
When referencing into a removable \addtoindex{section group}
\addtoindex{.debug\_info}
from another \addtoindex{.debug\_info} (from anywhere), the
-\begin{alltt}
-<prefix>.<file-designator>.<gid-number>.<die-number>
-\end{alltt}
+\texttt{<prefix>.<file-designator>.<gid-number>.<die-number>}
name should be used for an external symbol and a relocation
generated based on that name.
: 'T' at-code signature // Recursive type
children // Step 7
: child children
- : '\\0'
+ : '0'
child
: 'S' tag-code string
: \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} string \addtoindexx{string class}
: \livelink{chap:DWFORMblock}{DW\-\_FORM\-\_block} \nolink{block} \addtoindexx{block class}
\livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} \addtoindexx{string class}
- : '\\x08'
+ : 'x08'
\livelink{chap:DWFORMblock}{DW\-\_FORM\-\_block} \addtoindexx{block class}
- : '\\x09'
+ : 'x09'
\livelink{chap:DWFORMflag}{DW\-\_FORM\-\_flag} \addtoindexx{flag class}
- : '\\x0c'
+ : 'x0c'
\livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \addtoindexx{constant class}
- : '\\x0d'
+ : 'x0d'
value
: <SLEB128>
\nolink{block}
For concreteness, suppose that a descriptor looks something
like the C structure in
-Figure \referfol{fig:fortran90exampledescriptorrepresentation}.
+Figure \refersec{fig:fortran90exampledescriptorrepresentation}.
Note, however, that it is
a property of the design that 1) a debugger needs no builtin
knowledge of this structure and 2) there does not need to
void * base; // Address of raw data
int ptr_assoc : 1; // Pointer is associated flag
int ptr_alloc : 1; // Pointer is allocated flag
- int num_dims : 6; // Number of dimensions
+ int num_dims : 6; // Number of dimensions
struct dims_str { // For each dimension...
long low_bound;
long upper_bound;
In practice, of course, a “real” descriptor will have
dimension substructures only for as many dimensions as are
specified in the num\_dims component. Let us use the notation
-desc ,textless n \textgreater\
+\texttt{desc\textless n\textgreater}
to indicate a specialization of the desc struct in
-which n is the bound for the dims component as well as the
+which \texttt{n} is the bound for the dims component as well as the
contents of the num\_dims component.
Because the arrays considered here come in two parts, it is
necessary to distinguish the parts carefully. In particular,
the “address of the variable” or equivalently, the “base
-address of the object” always refers to the descriptor. For
+address of the object” \emph{always} refers to the descriptor. For
arrays that do not come in two parts, an implementation can
provide a descriptor anyway, thereby giving it two parts. (This
may be convenient for general runtime support unrelated to
If an object has a descriptor, then the DWARF type for that
object will have a
-\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. If an object
+\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}
+attribute. If an object
does not have a descriptor, then usually the DWARF type for the
object will not have a
\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}.
(See the following
\addtoindex{Ada} example for a case where the type for an object without
-a descriptor does have a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. In
+a descriptor does have a
+\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. In
that case the object doubles as its own descriptor.)
The \addtoindex{Fortran 90} derived type array\_ptr can now be redescribed
desc<1> arrays;
\end{lstlisting}
-(Recall that desc \textless 1 \textgreater
-indicates the 1\dash dimensional version of desc.)
+(Recall that \texttt{desc\textless 1\textgreater}
+indicates the 1\dash dimensional version of \texttt{desc}.)
Finally, the following notation is useful:
the type is an array type.
-\item Find the 5 element of that array object. To do array
+\item Find the 5$^{th}$ element of that array object. To do array
indexing requires several pieces of information:
-\begin{enumerate}[a]
+\begin{enumerate}[a)]
\item the address of the array data
\item Find the second element of the array object found in step 3. To do array indexing requires
several pieces of information:
-\begin{enumerate}[a]
+\begin{enumerate}[a)]
\item the address of the array storage
\item the lower bounds of the array \\
\begin{figure}[here]
\begin{lstlisting}
TYPE T : PACKED RECORD ! bit size is 2
-F5 : BOOLEAN; ! bit offset is 0
-F6 : BOOLEAN; ! bit offset is 1
-END;
-VAR V : PACKED RECORD
-F1 : BOOLEAN; ! bit offset is 0
-F2 : PACKED RECORD ! bit offset is 1
-F3 : INTEGER; ! bit offset is 0 in F2, 1 in V
-END;
-F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
-F7 : T; ! bit offset is 37
+ F5 : BOOLEAN; ! bit offset is 0
+ F6 : BOOLEAN; ! bit offset is 1
+ END;
+VAR V : PACKED RECORD
+ F1 : BOOLEAN; ! bit offset is 0
+ F2 : PACKED RECORD ! bit offset is 1
+ F3 : INTEGER; ! bit offset is 0 in F2, 1 in V
+ END;
+ F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
+ F7 : T; ! bit offset is 37
END;
\end{lstlisting}
\caption{Packed record example: source fragment}
\begin{alltt}
-version 4
-minimum_instruction_length 1
-opcode_base 10 ! Opcodes 10-12 not needed
-line_base 1
-line_range 15
+version 4
+minimum_instruction_length 1
+opcode_base 10 ! Opcodes 10-12 not needed
+line_base 1
+line_range 15
\end{alltt}
\begin{longtable}{lll}
\caption{Line number program example: one encoding}
\label{tab:linenumberprogramexampleoneencoding} \\
- \hline \\ \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
+ \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
\endfirsthead
\bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
\endhead
\begin{longtable}{lll}
\caption{Line number program example: alternate encoding}
\label{tab:linenumberprogramexamplealternateencoding} \\
- \hline \\ \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
+ \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
\endfirsthead
\bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
\endhead
foo that uses a frame pointer (in addition to the stack
pointer). The first column values are byte addresses.
% The \space is so we get a space after >
-\textless~fs~\textgreater \ denotes the stack frame size in bytes, namely 12.
+\textless fs\textgreater\ denotes the stack frame size in bytes, namely 12.
\begin{figure}[here]
\begin{longtable}{lllllllllll}
\caption{Call frame inforation example: conceptual matrix}
\label{tab:callframeinformationexampleconceptualmatrix} \\
- \hline \\ \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
+ \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
\endfirsthead
\bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
\endhead
\begin{longtable}{lll}
\caption{Call frame information example: common information entry encoding}
\label{tab:callframeinformationexamplecommoninformationentryencoding} \\
- \hline \\ \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
+ \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
\endfirsthead
\bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
\endhead
cie+30&\livelink{chap:DWCFAsamevalue}{DW\-\_CFA\-\_same\-\_value} (6)&R6 preserve \\
cie+32&\livelink{chap:DWCFAsamevalue}{DW\-\_CFA\-\_same\-\_value} (7)&R7 preserve \\
cie+34&\livelink{chap:DWCFAregister}{DW\-\_CFA\-\_register} (8, 1)&R8 is in R1 \\
-cie+37&\livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop}&padding \\
-cie+38&\livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop}& padding \\
+cie+37&\livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop} &padding \\
+cie+38&\livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop} &padding \\
cie+39& \livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop}&padding \\
cie+40 && \\
\end{longtable}
Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
\begin{alltt}
-1. <fs> = frame size
+1. <fs> = frame size
2. <caf> = code alignment factor
3. <daf> = data alignment factor
\end{alltt}
\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{lll}
- \caption{Call frame information example: frame description entry encoding} \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
- \hline \\ \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
+ \caption{Call frame information example: frame description entry encoding}
+ \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
+ \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
\endfirsthead
\bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
\endhead
fde+8&foo&initial\_location \\
fde+12&84&address\_range \\
fde+16&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)&instructions \\
-fde+17&\livelink{chap:DWCFAdefcfaoffset}{DW\-\_CFA\-\_def\-\_cfa\-\_offset}(12)& \textless fs \textgreater \\
-fde+19&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)&4/ \textless caf \textgreater \\
-fde+20&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(8,1)&-4/ \textless daf \textgreater (second parameter) \\
+fde+17&\livelink{chap:DWCFAdefcfaoffset}{DW\-\_CFA\-\_def\-\_cfa\-\_offset}(12)& \textless fs\textgreater \\
+fde+19&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)&4/ \textless caf\textgreater \\
+fde+20&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(8,1)&-4/ \textless daf\textgreater (2nd parameter) \\
fde+22&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)& \\
-fde+23&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(6,2)&-8/ \textless daf> \textgreater (2nd parameter) \\
+fde+23&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(6,2)&-8/ \textless daf\textgreater (2nd parameter) \\
fde+25&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
fde+26&\livelink{chap:DWCFAdefcfaregister}{DW\-\_CFA\-\_def\-\_cfa\-\_register}(6) & \\
fde+28&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
-fde+29&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(4,3)&-12/ \textless daf \textgreater (2nd parameter) \\
-fde+31&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(12)&44/ \textless caf \textgreater \\
+fde+29&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(4,3)&-12/ \textless daf\textgreater (2nd parameter) \\
+fde+31&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(12)&44/ \textless caf\textgreater \\
fde+32&\livelink{chap:DWCFArestore}{DW\-\_CFA\-\_restore}(4)& \\
fde+33&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
fde+34&\livelink{chap:DWCFArestore}{DW\-\_CFA\-\_restore}(6) & \\
The approaches are:
-\begin{itemize}[1.]
+\begin{enumerate}[1.]
\item Inline both OUTER and INNER in all cases
\item Inline OUTER, multiple INNERs \\
\item Inline OUTER, one INNER \\
Compile INNER as a single normal subprogram which is called
from every inlining of OUTER.
-\end{itemize}
+\end{enumerate}
This discussion does not consider why a compiler might choose
one of these approaches; it considers only how to describe
In the examples that follow in this section, the debugging
information entries are given mnemonic labels of the following
form
-
-\begin{lstlisting}
-<io>.<ac>.<n>.<s>
-\end{lstlisting}
-
-where \begin{verbatim}<io>\end{verbatim}
+\begin{verbatim}
+ <io>.<ac>.<n>.<s>
+\end{verbatim}
+where
+\begin{description}
+\item[\textless io\textgreater]
is either INNER or OUTER to indicate to which
subprogram the debugging information entry applies,
-\begin{verbatim}<ac>\end{verbatim}
+\item[\textless ac\textgreater]
is either AI or CI to indicate ``abstract instance'' or
``concrete instance'' respectively,
-\begin{verbatim}<n>\end{verbatim}
+\item[\textless n\textgreater]
is the number of the
alternative being considered, and
-\begin{verbatim}<s>\end{verbatim}
+\item[\textless s\textgreater]
is a sequence number that
-distinguishes the individual entries. There is no implication
+distinguishes the individual entries.
+\end{description}
+There is no implication
that symbolic labels, nor any particular naming convention,
are required in actual use.
\livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 11\$)
\end{alltt}
-In the \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} entry for the instance of consume,
-U is described as
-int.
-The type of formal is
-\begin{alltt}
-wrapper<U>
-\end{alltt}
- in
+In the \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
+entry for the instance of consume, U is described as int.
+The type of formal is \texttt{wrapper\textless U\textgreater} in
the source. DWARF only represents instantiations of templates;
-there is no entry which represents
-\begin{alltt}
-wrapper<U>,
-\end{alltt}
+there is no entry which represents \texttt{wrapper\textless U\textgreater}
which is neither
a template parameter nor a template instantiation. The type
-of formal is described as
-\begin{alltt}
-wrapper<int>,
-\end{alltt}
-the instantiation of
-\begin{alltt}
-wrapper<U>,
-\end{alltt}
+of formal is described as \texttt{wrapper\textless int\textgreater},
+the instantiation of \texttt{wrapper\textless U\textgreater},
in the \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute at
23\$.
There is no
description of the relationship between template type parameter
-T at 12\$ and U at
-22\$ which was used to instantiate
-\begin{alltt}
-wrapper<U>.
-\end{alltt}
+T at 12\$ and U at 22\$ which was used to instantiate
+\texttt{wrapper\textless U\textgreater}.
A consequence of this is that the DWARF information would
not distinguish between the existing example and one where
the formal of consume were declared in the source to be
-\begin{alltt}
-wrapper<int>.
-\end{alltt}
+\texttt{wrapper\textless int\textgreater}.
+
\section{Template Alias Examples}
\label{app:templatealiasexample}
\chapter{GNU Free Documentation License}
\label{app:gnufreedocumentationlicense}
-\section{PREAMBLE}
+\begin{centering}
+Version 1.3, 3 November 2008
+
+Copyright \copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+
+http://fsf.org/
+
+\end{centering}
+\vspace{0.1in}
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+\vspace{0.1in}
+
+\textbf{\Large{PREAMBLE}} \\
The purpose of this License is to make a manual, textbook,
or other functional and useful document free in the sense of
freedom: to assure everyone the effective freedom to copy
thus licensing distribution and modification of the Modified
Version to whoever possesses a copy of it. In addition,
you must do these things in the Modified Version:
-\begin{enumerate}
+\begin{enumerate}[A.]
\item Use in the Title Page (and on the covers, if any)
a title distinct from that of the Document, and from those of
previous versions (which should, if there were any, be listed
copyright and license notices just after the title page:
\begin{myindentpara}{2cm}
-Copyright (C) year your name.
+Copyright (C) YEAR YOUR NAME.
+
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
-Texts. A copy of the license is included in the section entitled ``GNU
+Texts.
+
+A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
\end{myindentpara}
\begin{myindentpara}{2cm}
-with the Invariant Sections being list their titles, with
-the Front-Cover Texts being list, and with the Back-Cover Texts
-being list.
+with the Invariant Sections being list THEIR TITLES, with
+the Front-Cover Texts being LIST, and with the Back-Cover Texts
+being LIST.
\end{myindentpara}
If you have Invariant Sections without Cover Texts, or some
DWARF Git Projects / dwarf-doc.git / commitdiff