Check point of work to date.

[dwarf-doc.git] / dwarf5 / latexdoc / examples.tex

\chapter{Examples (Informative)}
\label{app:examplesinformative}

The following sections provide examples that illustrate
various aspects of the DWARF debugging information format.


\section{General Description Examples}
\label{app:generaldescriptionexamples}


\subsection{Compilation Units and Abbreviations Table Example}
\label{app:compilationunitsandabbreviationstableexample}

Figure \refersec{fig:compilationunitsandabbreviationstable}
depicts the relationship of the abbreviations tables contained
\addtoindexx{abbreviations table!example}
\addtoindexx{\texttt{.debug\_abbrev}!example}
\addtoindexx{\texttt{.debug\_info}!example}
in the \dotdebugabbrev{}
section to the information contained in
the \dotdebuginfo{}
section. Values are given in symbolic form,
where possible.

The figure corresponds to the following two trivial source files:

File myfile.c
\begin{lstlisting}[numbers=none]
typedef char* POINTER;
\end{lstlisting}
File myfile2.c
\begin{lstlisting}[numbers=none]
typedef char* strp;
\end{lstlisting}

% Ensures we get the following float out before we go on.
\clearpage
%%%
%%% Be VERY careful about editing this figure! Both vertical
%%% and horizontal spacing are critical to achieving the
%%% desired effect. But this is very fragile!
%%%
\begin{figure}[ht]
%\centering
%\setlength{\linewidth}{1.1\linewidth}
\begin{minipage}[t]{0.03\linewidth}
\flushright
\scriptsize
% Note: alltt is used to step down the needed number of lines to the labels
\begin{alltt}




















\textit{e1:}




\textit{e2:}
\end{alltt}
\end{minipage}
%
\begin{minipage}[t]{0.38\linewidth}
\centering
Compilation Unit \#1: \dotdebuginfo{}
\begin{framed}
\scriptsize
\begin{alltt}
\textit{length}
4
\textit{a1 (abbreviations table offset)}
4
\vspace{0.01cm}
\hrule
1
"myfile.c"
"Best Compiler Corp, V1.3"
"/home/mydir/src"
\DWLANGCeightynine
0x0
0x55
\DWFORMsecoffset
0x0
\vspace{0.01cm}
\hrule
2
"char"
\DWATEunsignedchar
1
\vspace{0.01cm}
\hrule
3
\textit{e1  (debug info offset)}
\vspace{0.01cm}
\hrule
4
"POINTER"
\textit{e2  (debug info offset)}
\vspace{0.01cm}
\hrule
0
\end{alltt}
%
%
\end{framed}
Compilation Unit \#2: \dotdebuginfo{}
\begin{framed}
\scriptsize
\begin{alltt}
\textit{length}
4
\textit{a1 (abbreviations table offset)}
4
\vspace{0.01cm}
\hrule
...
\vspace{0.01cm}
\hrule
4
"strp"
\textit{e2  (debug info offset)}
\vspace{0.01cm}
\hrule
...
\end{alltt}
%
%
\end{framed}
\end{minipage}
\hfill 
% Place the label for the abbreviation table
\begin{minipage}[t]{0.03\linewidth}
\flushright
\scriptsize
% Note: alltt is used to step down the needed number of lines to the label
\begin{alltt}





\textit{a1:}
\end{alltt}
\end{minipage}
%
\begin{minipage}[t]{0.41\linewidth}
\centering
Abbreviation Table: \dotdebugabbrev{}
\begin{framed}
\scriptsize
\begin{alltt}\vspace{0.06cm}
1
\DWTAGcompileunit
\DWCHILDRENyes
\DWATname       \DWFORMstring
\DWATproducer   \DWFORMstring
\DWATcompdir   \DWFORMstring
\DWATlanguage   \DWFORMdataone
\DWATlowpc     \DWFORMaddr
\DWAThighpc    \DWFORMdataone
\DWATstmtlist  \DWFORMindirect
0
\vspace{0.01cm}
\hrule
2
\DWTAGbasetype
\DWCHILDRENno
\DWATname       \DWFORMstring
\DWATencoding   \DWFORMdataone
\DWATbytesize  \DWFORMdataone
0
\vspace{0.01cm}
\hrule
3
\DWTAGpointertype
\DWCHILDRENno
\DWATtype       \DWFORMreffour
0
\vspace{0.01cm}
\hrule
4
\DWTAGtypedef
\DWCHILDRENno
\DWATname      \DWFORMstring
\DWATtype      \DWFORMrefaddr
0
\vspace{0.01cm}
\hrule
0
\end{alltt}
\end{framed}
\end{minipage}

\vspace{0.2cm}
\caption{Compilation units and abbreviations table} \label{fig:compilationunitsandabbreviationstable}
\end{figure}

% Ensures we get the above float out before we go on.
\clearpage

\subsection{DWARF Stack Operation Examples}
\label{app:dwarfstackoperationexamples}
\textit {The 
\addtoindexx{DWARF expression!examples}
stack operations defined in 
Section \refersec{chap:stackoperations}.
are fairly conventional, but the following
examples illustrate their behavior graphically.}

\begin{longtable}[c]{rrcrr} 
\multicolumn{2}{c}{Before} & Operation & \multicolumn{2}{c}{After} \\
\hline
\endhead
\endfoot
0& 17& \DWOPdup{} &0 &17 \\*
1&   29& &  1 & 17 \\*
2& 1000 & & 2 & 29\\*
& & &         3&1000\\

& & & & \\
0 & 17 & \DWOPdrop{} & 0 & 29 \\*
1 &29  &            & 1 & 1000 \\*
2 &1000& & &          \\

& & & & \\
0 & 17 & \DWOPpick, 2 & 0 & 1000 \\*
1 & 29 & & 1&17 \\*
2 &1000& &2&29 \\*
  &    & &3&1000 \\

& & & & \\
0&17& \DWOPover&0&29 \\*
1&29& &  1&17 \\*
2&1000 & & 2&29\\*
 &     & & 3&1000 \\

& & & & \\
0&17& \DWOPswap{} &0&29 \\*
1&29& &  1&17 \\*
2&1000 & & 2&1000 \\

& & & & \\
0&17&\DWOProt{} & 0 &29 \\*
1&29 & & 1 & 1000 \\*
2& 1000 & &  2 & 17 \\
\end{longtable}

\subsection{DWARF Location Description Examples}
\label{app:dwarflocationdescriptionexamples}

Following are examples of DWARF operations used to form location descriptions:

\newcommand{\descriptionitemnl}[1]
        {\vspace{0.3\baselineskip}\item[#1]\mbox{}\\\vspace{0.5\baselineskip}}
\begin{description}
\descriptionitemnl{\DWOPregthree}
The value is in register 3.

\descriptionitemnl{\DWOPregx{} 54}
The value is in register 54.

\descriptionitemnl{\DWOPaddr{} 0x80d0045c}
The value of a static variable is at machine address 0x80d0045c.

\descriptionitemnl{\DWOPbregeleven{} 44}
Add 44 to the value in register 11 to get the address of an automatic
variable instance.

\needlines{4}
\descriptionitemnl{\DWOPfbreg{} -50}
Given a \DWATframebase{} value of
\doublequote{\DWOPbregthirtyone{} 64,} this example
computes the address of a local variable that is -50 bytes from a
logical frame pointer that is computed by adding 64 to the current
stack pointer (register 31).

\descriptionitemnl{\DWOPbregx{} 54 32 \DWOPderef}
A call-by-reference parameter whose address is in the word 32 bytes
from where register 54 points.

\descriptionitemnl{\DWOPplusuconst{} 4}
A structure member is four bytes from the start of the structure
instance. The base address is assumed to be already on the stack.

\descriptionitemnl{\DWOPregthree{} \DWOPpiece{} 4 \DWOPregten{} \DWOPpiece{} 2}
A variable whose first four bytes reside in register 3 and whose next
two bytes reside in register 10.

\needlines{4}
\descriptionitemnl{\DWOPregzero{} \DWOPpiece{} 4 \DWOPpiece{} 4 \DWOPfbreg{} -12 \DWOPpiece{} 4}
\vspace{-2\parsep}A twelve byte value whose first four bytes reside in register zero,
whose middle four bytes are unavailable (perhaps due to optimization),
and whose last four bytes are in memory, 12 bytes before the frame
base.

\descriptionitemnl{\DWOPbregone{} 0 \DWOPbregtwo{} 0 \DWOPplus{} \DWOPstackvalue{} }
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{-3\parsep}\descriptionitemnl{
\hspace{0.5cm}\DWOPplus{} \DWOPstackvalue{} \DWOPpiece{} 4 }
The object value is found in an anonymous (virtual) location whose
value consists of two parts, given in memory address order: the 4 byte
value 1 followed by the four byte value computed from the sum of the
contents of r3 and r4.

\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} }
The value register 1 contained upon entering the current subprogram is 
pushed on the stack.

\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} \DWOPstackvalue }
The value register 1 contained upon entering the current subprogram is 
pushed on the stack. This value is the
\doublequote{contents} of an otherwise anonymous location.

\descriptionitemnl{\DWOPentryvalue{} 2 \DWOPbregone{} 0 \DWOPstackvalue }
The value register 1 contained upon entering the current subprogram 
(same as the previous example) is pushed on the stack. This value is the
\doublequote{contents} of an otherwise anonymous location.

This and the previous location description are equivalent;
the previous one is shorter, however. 

%FIXME: The following gets an undefined control sequence error for reasons unknown... 
%\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregthirtyone{} \DWOPregone{} \DWOPadd{} \DWOPstackvalue }
%The value register 31 had upon entering the current subprogram
%plus the value register 1 currently has.

% Is the following example really interesting enough (not just complicated) to keep?
\ifthen{\boolean{true}}{
\descriptionitemnl{\DWOPentryvalue{} 3 \DWOPbregfour{} 16 \DWOPderef{} \DWOPstackvalue }
%FIXME: similar undefined as just above
%\descriptionitemnl{\DWOPentryvalue{} 6 \DWOPentryvalue{} 1 \DWOPregfour{} \DWOPplusuconst{} 16 \DWOPderef{} \DWOPstackvalue }
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.
This value is the
\doublequote{contents} of an otherwise anonymous location.
}

\needlines{6}
\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregfive{} \DWOPplusuconst{} 16 }
The address of the memory location is calculated by adding 16 to the value
contained in register 5 upon entering the current subprogram.

\textit{Note that unlike the previous \DWOPentryvalue{} examples, this one does not end
with \DWOPstackvalue.{}}

\end{description}

%\clearpage
\section{Aggregate Examples}
\label{app:aggregateexamples}

The following examples illustrate how to represent some of
the more complicated forms of array and record aggregates
using DWARF.

\subsection{Fortran Simple Array Example}
\label{app:fortranarrayexample}
Consider the \addtoindex{Fortran array}\addtoindexx{Fortran 90} source fragment in 
\addtoindexx{array type entry!examples}
Figure \referfol{fig:fortranarrayexamplesourcefragment}.

\begin{figure}[ht]
\begin{lstlisting}
        TYPE array_ptr
        REAL :: myvar
        REAL, DIMENSION (:), POINTER :: ap
        END TYPE array_ptr
        TYPE(array_ptr), ALLOCATABLE, DIMENSION(:) :: arrayvar
        ALLOCATE(arrayvar(20))
        DO I = 1, 20
            ALLOCATE(arrayvar(i)%ap(i+10))
        END DO
\end{lstlisting}
\caption{Fortran array example: source fragment} 
\label{fig:fortranarrayexamplesourcefragment}
\end{figure}

For allocatable and pointer arrays, it is essentially required
by the\addtoindex{Fortran array} semantics that each array 
consist of two parts, which we here call 1) the 
descriptor\addtoindexx{descriptor!array}\addtoindexx{array!descriptor for}
and 2) the raw
data. (A descriptor has often been called a dope vector in
other contexts, although it is often a structure of some kind
rather than a simple vector.) Because there are two parts,
and because the lifetime of the descriptor is necessarily
longer than and includes that of the raw data, there must be
an address somewhere in the descriptor that points to the
raw data when, in fact, there is some (that is, when 
the \doublequote{variable} is allocated or associated).

For concreteness, suppose that a descriptor looks something
like the C structure in 
Figure \refersec{fig:fortranarrayexampledescriptorrepresentation}.
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
be an explicit representation of this structure in the DWARF
input to the debugger.

\begin{figure}[ht]
\begin{lstlisting}
struct desc {
    long el_len;       // Element length
    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
    struct dims_str {  // For each dimension...  
        long low_bound;
        long upper_bound;
        long stride;
    } dims[63];
};
\end{lstlisting}
\caption{Fortran array example: descriptor representation}
\label{fig:fortranarrayexampledescriptorrepresentation}
\end{figure}


In practice, of course, a \doublequote{real} descriptor will have
dimension substructures only for as many dimensions as are
specified in the \texttt{num\_dims} component. Let us use the notation
\texttt{desc\textless n\textgreater}   
to indicate a specialization of the \texttt{desc} struct in
which \texttt{n} is the bound for the \texttt{dims} component as well as the
contents of the \texttt{num\_dims} component.

Because the arrays considered here come in two parts, it is
necessary to distinguish the parts carefully. In particular,
the \doublequote{address of the variable} or equivalently, the \doublequote{base
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
debugging.) In this case the above vocabulary applies as
stated. Alternatively, an implementation can do without a
descriptor, in which case the \doublequote{address of the variable,}
or equivalently the \doublequote{base address of the object}, refers
to the \doublequote{raw data} (the real data, the only thing around
that can be the object).

If an object has a descriptor, then the DWARF type for that
object will have a 
\DWATdatalocation{} 
attribute. If an object
does not have a descriptor, then usually the DWARF type for the
object will not have a 
\DWATdatalocation{} attribute. 
(See the following
\addtoindex{Ada} example for a case where the type for an object without
a descriptor does have a 
\DWATdatalocation{} attribute. In
that case the object doubles as its own descriptor.)

\needlines{6}
The \addtoindex{Fortran} derived type \texttt{array\_ptr} can now be re-described
in C-like terms that expose some of the representation as in

\begin{lstlisting}[numbers=none]
struct array_ptr {
    float myvar;
    desc<1> ap;
};
\end{lstlisting}

Similarly for variable \texttt{arrayvar}:
\begin{lstlisting}[numbers=none]
desc<1> arrayvar;
\end{lstlisting}

\textit{
Recall that \texttt{desc\textless 1\textgreater} 
indicates the 1\dash dimensional version of \texttt{desc}.
}

%\newpage
Finally, the following notation is useful:
\begin{enumerate}[1. ]
\item  sizeof(type): size in bytes of entities of the given type
\item offset(type, comp): offset in bytes of the comp component
within an entity of the given type
\end{enumerate}

The DWARF description is shown 
\addtoindexx{Fortran 90}
in Figure \refersec{fig:fortranarrayexampledwarfdescription}.

\begin{figure}[ht]
\figurepart{1}{2}
\begin{dwflisting}
\begin{alltt}
! Description for type of 'ap'
!
1\$: \DWTAGarraytype
        ! No name, default (Fortran) ordering, default stride
        \DWATtype(reference to REAL)
        \DWATassociated(expression=    ! Test 'ptr\_assoc' \nolink{flag}
            \DWOPpushobjectaddress
            \DWOPlitn                ! where n == offset(ptr\_assoc)
            \DWOPplus
            \DWOPderef
            \DWOPlitone                  ! mask for 'ptr\_assoc' \nolink{flag}
            \DWOPand)
        \DWATdatalocation(expression= ! Get raw data address
            \DWOPpushobjectaddress
            \DWOPlitn                ! where n == offset(base)
            \DWOPplus
            \DWOPderef)                ! Type of index of array 'ap'
2\$:     \DWTAGsubrangetype
            ! No name, default stride
            \DWATtype(reference to INTEGER)
            \DWATlowerbound(expression=
                \DWOPpushobjectaddress
                \DWOPlitn             ! where n ==
                                         !   offset(desc, dims) +
                                         !   offset(dims\_str, lower\_bound)
                \DWOPplus
                \DWOPderef)
            \DWATupperbound(expression=
                \DWOPpushobjectaddress
                \DWOPlitn            ! where n ==
                                        !   offset(desc, dims) +
                                        !   offset(dims\_str, upper\_bound)
                \DWOPplus
                \DWOPderef)
            !  Note: for the m'th dimension, the second operator becomes
            !  \DWOPlitn where
            !       n == offset(desc, dims)          +
            !                (m-1)*sizeof(dims\_str)  +
            !                 offset(dims\_str, [lower|upper]\_bound)
            !  That is, the expression does not get longer for each successive 
            !  dimension (other than to express the larger offsets involved).
\end{alltt}
\end{dwflisting}
\caption{Fortran array example: DWARF description}
\label{fig:fortranarrayexampledwarfdescription}
\end{figure}

\begin{figure}
\figurepart{2}{2}
\begin{dwflisting}
\begin{alltt}
3\$: \DWTAGstructuretype
        \DWATname("array\_ptr")
        \DWATbytesize(constant sizeof(REAL) + sizeof(desc<1>))
4\$:     \DWTAGmember
            \DWATname("myvar")
            \DWATtype(reference to REAL)
            \DWATdatamemberlocation(constant 0)
5\$:     \DWTAGmember
            \DWATname("ap");
            \DWATtype(reference to 1\$)
            \DWATdatamemberlocation(constant sizeof(REAL))
6\$: \DWTAGarraytype
        ! No name, default (Fortran) ordering, default stride
        \DWATtype(reference to 3\$)
        \DWATallocated(expression=       ! Test 'ptr\_alloc' \nolink{flag}
            \DWOPpushobjectaddress
            \DWOPlitn                  ! where n == offset(ptr\_alloc)
            \DWOPplus
            \DWOPderef
            \DWOPlittwo                    ! Mask for 'ptr\_alloc' \nolink{flag}
            \DWOPand)
        \DWATdatalocation(expression=   ! Get raw data address
            \DWOPpushobjectaddress
            \DWOPlitn                  ! where n == offset(base)
            \DWOPplus
            \DWOPderef)
7\$:     \DWTAGsubrangetype
            ! No name, default stride
            \DWATtype(reference to INTEGER)
            \DWATlowerbound(expression=
                \DWOPpushobjectaddress
                \DWOPlitn              ! where n == ...
                \DWOPplus
                \DWOPderef)
            \DWATupperbound(expression=
                \DWOPpushobjectaddress
                \DWOPlitn              ! where n == ...
                \DWOPplus
                \DWOPderef)
8\$: \DWTAGvariable
        \DWATname("arrayvar")
        \DWATtype(reference to 6\$)
        \DWATlocation(expression=
            ...as appropriate...)       ! Assume static allocation
\end{alltt}
\end{dwflisting}
\begin{center}
\vspace{3mm}
Figure~\ref{fig:fortranarrayexampledwarfdescription}: Fortran array example: DWARF description \textit{(concluded)}
\end{center}
\end{figure}

Suppose 
\addtoindexx{Fortran array example}
the program is stopped immediately following completion
of the do loop. Suppose further that the user enters the
following debug command:
\vspace{2mm}
\begin{lstlisting}[numbers=none]
debug> print arrayvar(5)%ap(2)
\end{lstlisting}

Interpretation of this expression proceeds as follows:
\begin{enumerate}[1. ]

\item Lookup name \texttt{arrayvar}. We find that it is a variable,
whose type is given by the unnamed type at 6\$. Notice that
the type is an array type.


\item Find the 5$^{th}$ element of that array object. To do array
indexing requires several pieces of information:
\begin{enumerate}[a) ]

\item  the address of the array data

\item the lower bounds of the array \\
% Using plain [] here gives trouble.
\lbrack To check that 5 is within bounds would require the upper
bound too, but we will skip that for this example. \rbrack

\item the stride 

\end{enumerate}

For a), check for a 
\DWATdatalocation{} attribute. 
Since there is one, go execute the expression, whose result is
the address needed. The object address used in this case
is the object we are working on, namely the variable named
\texttt{arrayvar}, whose address was found in step 1. (Had there been
no \DWATdatalocation{} attribute, the desired address would
be the same as the address from step 1.)

For b), for each dimension of the array (only one
in this case), go interpret the usual lower bound
attribute. Again this is an expression, which again begins
with \DWOPpushobjectaddress. This object is 
\textbf{still} \texttt{arrayvar},
from step 1, because we have not begun to actually perform
any indexing yet.

For c), the default stride applies. Since there is no
\DWATbytestride{} attribute, use the size of the array element
type, which is the size of type \texttt{array\_ptr} (at 3\$).

\clearpage

Having acquired all the necessary data, perform the indexing
operation in the usual manner--which has nothing to do with
any of the attributes involved up to now. Those just provide
the actual values used in the indexing step.

The result is an object within the memory that was dynamically
allocated for \texttt{arrayvar}.

\item  Find the \texttt{ap} component of the object just identified,
whose type is \texttt{array\_ptr}.

This is a conventional record component lookup and
interpretation. It happens that the \texttt{ap} component in this case
begins at offset 4 from the beginning of the containing object.
Component \texttt{ap} has the unnamed array type defined at 1\$ in the
symbol table.

\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) ]
\item  the address of the array storage

\item  the lower bounds of the array \\
% Using plain [] here gives trouble.
\lbrack To check that 2 is within bounds we would require the upper
bound too, but we will skip that for this example \rbrack

\item  the stride

\end{enumerate}
\end{enumerate}

This is just like step 2), so the details are omitted. Recall
that because the DWARF type 1\$ has a \DWATdatalocation,
the address that results from step 4) is that of a
descriptor, and that address is the address pushed by the
\DWOPpushobjectaddress{} operations in 1\$ and 2\$.

Note: we happen to be accessing a pointer array here instead
of an allocatable array; but because there is a common
underlying representation, the mechanics are the same. There
could be completely different descriptor arrangements and the
mechanics would still be the same---only the stack machines
would be different.

%\needlines{8}
\subsection{Fortran Coarray Examples}
\label{app:Fortrancoarrayexamples}

\subsubsection{Fortran Scalar Coarray Example}
The \addtoindex{Fortran} scalar coarray example
\addtoindexx{coarray!example}\addtoindexx{scalar coarray|see{coarray}}
in Figure \refersec{fig:Fortranscalarcoarraysourcefragment} can be described as 
illustrated in Figure \refersec{fig:FortranscalarcoarrayDWARFdescription}.

\begin{figure}[!ht]
\begin{lstlisting}
        INTEGER x[*]
\end{lstlisting}
\caption{Fortran scalar coarray: source fragment}
\label{fig:Fortranscalarcoarraysourcefragment}
\end{figure}

\begin{figure}[!ht]
\begin{dwflisting}
\begin{alltt}
10\$:  \DWTAGcoarraytype
          \DWATtype(reference to INTEGER)
          \DWTAGsubrangetype                ! Note omitted upper bound
          \DWATlowerbound(constant 1)       ! Can be omitted (default is 1)

11\$:  \DWTAGvariable
          \DWATname("x")
          \DWATtype(reference to coarray type at 10\$)
\end{alltt}
\end{dwflisting}
\caption{Fortran scalar coarray: DWARF description}
\label{fig:FortranscalarcoarrayDWARFdescription}
\end{figure}

\subsubsection{Fortran Array Coarray Example}
The \addtoindex{Fortran} (simple) array coarray example
\addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
in Figure \refersec{fig:Fortranarraycoarraysourcefragment} can be described as 
illustrated in Figure \refersec{fig:FortranarraycoarrayDWARFdescription}.

\begin{figure}[ht]
\begin{lstlisting}
        INTEGER x(10)[*]
\end{lstlisting}
\caption{Fortran array coarray: source fragment}
\label{fig:Fortranarraycoarraysourcefragment}
\end{figure}

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}
10\$:  \DWTAGarraytype
          \DWATordering(\DWORDcolmajor)
          \DWATtype(reference to INTEGER)
11\$:      \DWTAGsubrangetype
            ! \textit{DW\_AT\_lower\_bound(constant 1)}   ! Omitted (default is 1)
              \DWATupperbound(constant 10)

12\$:  \DWTAGcoarraytype
          \DWATtype(reference to array type at 10\$)
13\$:      \DWTAGsubrangetype                ! Note omitted upper \& lower bounds

14$:  \DWTAGvariable
          \DWATname("x")
          \DWATtype(reference to coarray type at 12\$)
\end{alltt}
\end{dwflisting}
\caption{Fortran array coarray: DWARF description}
\label{fig:FortranarraycoarrayDWARFdescription}
\end{figure}

\needlines{6}
\subsubsection{Fortran Multidimensional Coarray Example}
The \addtoindex{Fortran} multidimensional coarray of a multidimensional array example
\addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
in Figure \refersec{fig:Fortranmultidimensionalcoarraysourcefragment} can be described as 
illustrated in Figure \referfol{fig:FortranmultidimensionalcoarrayDWARFdescription}.

\begin{figure}[ht]
\begin{lstlisting}
        INTEGER x(10,11,12)[2,3,*]
\end{lstlisting}
\caption{Fortran multidimensional coarray: source fragment}
\label{fig:Fortranmultidimensionalcoarraysourcefragment}
\end{figure}

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}

10\$:  \DWTAGarraytype                ! Note omitted lower bounds (default to 1)
          \DWATordering(\DWORDcolmajor)
          \DWATtype(reference to INTEGER)
11\$:      \DWTAGsubrangetype
              \DWATupperbound(constant 10)
12\$:      \DWTAGsubrangetype
              \DWATupperbound(constant 11)
13\$:      \DWTAGsubrangetype
              \DWATupperbound(constant 12)

14\$:  \DWTAGcoarraytype              ! Note omitted lower bounds (default to 1)
          \DWATtype(reference to array_type at 10\$)
15\$:      \DWTAGsubrangetype
              \DWATupperbound(constant 2)
16\$:      \DWTAGsubrangetype
              \DWATupperbound(constant 3)
17\$:      \DWTAGsubrangetype         ! Note omitted upper (\& lower) bound

18\$:  \DWTAGvariable
          \DWATname("x")
          \DWATtype(reference to coarray type at 14\$)
        
\end{alltt}
\end{dwflisting}
\caption{Fortran multidimensional coarray: DWARF description}
\label{fig:FortranmultidimensionalcoarrayDWARFdescription}
\end{figure}


\clearpage
\subsection{Fortran 2008 Assumed-rank Array Example}
\label{app:assumedrankexample}
\addtoindexx{array!assumed-rank}
Consider the example in Figure~\ref{fig:assumedrankdecl}, which shows
an assumed-rank array in Fortran~2008 with
supplement~29113:\footnote{Technical Specification ISO/IEC TS
  29113:2012 \emph{Further Interoperability of Fortran with C}}

\begin{figure}[!ht]
\begin{lstlisting}
  SUBROUTINE Foo(x)
    REAL :: x(..)

    ! x has n dimensions
  
  END SUBROUTINE
\end{lstlisting}
\caption{Declaration of a Fortran 2008 assumed-rank array}
\label{fig:assumedrankdecl}
\end{figure}

Let's assume the Fortran compiler used an array descriptor that
(in \addtoindex{C}) looks
like the one shown in Figure~\ref{fig:arraydesc}.

\begin{figure}[!ht]
\begin{lstlisting}
  struct array_descriptor {
    void *base_addr;
    int rank;
    struct dim dims[]; 
  }

  struct dim {
     int lower_bound;
     int upper_bound;
     int stride;
     int flags;
  }
\end{lstlisting}
\caption{One of many possible layouts for an array descriptor}
\label{fig:arraydesc}
\end{figure}

The DWARF type for the array \emph{x} can be described as shown in
Figure~\refersec{fig:assumedrankdwarf}.

\begin{figure}[!ht]
\begin{dwflisting}
\begin{alltt}
10\$:  \DWTAGarraytype
          \DWATtype(reference to real)
          \DWATrank(expression=
              \DWOPpushobjectaddress
              \DWOPlitn                        ! offset of rank in descriptor
              \DWOPplus
              \DWOPderef)
          \DWATdatalocation(expression=
              \DWOPpushobjectaddress
              \DWOPlitn                        ! offset of data in descriptor
              \DWOPplus
              \DWOPderef)
11\$:     \DWTAGgenericsubrange
              \DWATtype(reference to integer)
              \DWATlowerbound(expression=
              !   Looks up the lower bound of dimension i.
              !   Operation                       ! Stack effect
              !   (implicit)                      ! i
                  \DWOPlitn                    ! i sizeof(dim)
                  \DWOPmul                       ! dim[i]
                  \DWOPlitn                    ! dim[i] offsetof(dim)
                  \DWOPplus                      ! dim[i]+offset
                  \DWOPpushobjectaddress       ! dim[i]+offsetof(dim) objptr
                  \DWOPplus                      ! objptr.dim[i]
                  \DWOPlitn                    ! objptr.dim[i] offsetof(lb)
                  \DWOPplus                      ! objptr.dim[i].lowerbound
                  \DWOPderef)                    ! *objptr.dim[i].lowerbound
              \DWATupperbound(expression=
              !   Looks up the upper bound of dimension i.
                  \DWOPlitn                    ! sizeof(dim)
                  \DWOPmul
                  \DWOPlitn                    ! offsetof(dim)
                  \DWOPplus
                  \DWOPpushobjectaddress
                  \DWOPplus
                  \DWOPlitn                    ! offset of upperbound in dim
                  \DWOPplus
                  \DWOPderef)
              \DWATbytestride(expression=
              !   Looks up the byte stride of dimension i.
                  ...
              !   (analogous to \DWATupperboundNAME)
                  )
\end{alltt}
\end{dwflisting}
\caption{Sample DWARF for the array descriptor in Figure~\ref{fig:arraydesc}}
\label{fig:assumedrankdwarf}
\end{figure}

The layout of the array descriptor is not specified by the Fortran
standard unless the array is explicitly marked as \addtoindex{C-interoperable}. To
get the bounds of an assumed-rank array, the expressions in the
\DWTAGgenericsubrange{}
entry need to be evaluated for each of the
\DWATrank{} dimensions as shown by the pseudocode in
Figure~\refersec{fig:assumedrankdwarfparser}.

\begin{figure}[!ht]
\begin{lstlisting}
    typedef struct {
        int lower, upper, stride;
    } dims_t;

    typedef struct {
        int rank;
    struct dims_t *dims;
    } array_t;

    array_t get_dynamic_array_dims(DW_TAG_array a) {
      array_t result;

      // Evaluate the DW_AT_rank expression to get the 
      //    number of dimensions.
      dwarf_stack_t stack;
      dwarf_eval(stack, a.rank_expr);
      result.rank = dwarf_pop(stack); 
      result.dims = new dims_t[rank];

      // Iterate over all dimensions and find their bounds.
      for (int i = 0; i < result.rank; i++) {
        // Evaluate the generic subrange's DW_AT_lower 
        //    expression for dimension i.
        dwarf_push(stack, i);
        assert( stack.size == 1 );
        dwarf_eval(stack, a.generic_subrange.lower_expr);
        result.dims[i].lower = dwarf_pop(stack);
        assert( stack.size == 0 );

        dwarf_push(stack, i);
        dwarf_eval(stack, a.generic_subrange.upper_expr);
        result.dims[i].upper = dwarf_pop(stack);
    
        dwarf_push(stack, i);
        dwarf_eval(stack, a.generic_subrange.byte_stride_expr);
        result.dims[i].stride = dwarf_pop(stack);
      }
      return result;
    }
\end{lstlisting}
\caption{How to interpret the DWARF from Figure~\ref{fig:assumedrankdwarf}}
\label{fig:assumedrankdwarfparser}
\end{figure}


\clearpage
\subsection{Fortran Dynamic Type Example}
\label{app:fortrandynamictypeexample}
Consider the \addtoindex{Fortran 90} example of dynamic properties in 
Figure \refersec{fig:fortrandynamictypeexamplesource}.
This can be represented in DWARF as illustrated in 
Figure \refersec{fig:fortrandynamictypeexampledwarfdescription}.
Note that unnamed dynamic types are used to avoid replicating
the full description of the underlying type \texttt{dt} that is shared by
several variables.

\begin{figure}[ht]
\begin{lstlisting}
        PROGRAM Sample
     
        TYPE :: dt (l)
            INTEGER, LEN :: l
            INTEGER :: arr(l)
        END TYPE

        INTEGER :: n = 4
        CONTAINS

        SUBROUTINE S()
            TYPE (dt(n))               :: t1
            TYPE (dt(n)), pointer      :: t2
            TYPE (dt(n)), allocatable  :: t3, t4
        END SUBROUTINE
     
        END Sample
\end{lstlisting}
\caption{Fortran dynamic type example: source}
\label{fig:fortrandynamictypeexamplesource}
\end{figure}

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}
11$:    \DWTAGstructuretype
            \DWATname("dt")
            \DWTAGmember
                ...
                        ...

13$:    \DWTAGdynamictype             ! plain version
            \DWATdatalocation (dwarf expression to locate raw data)
            \DWATtype (11$)

14$:    \DWTAGdynamictype             ! 'pointer' version
            \DWATdatalocation (dwarf expression to locate raw data)
            \DWATassociated (dwarf expression to test if associated)
            \DWATtype (11$)

15$:    \DWTAGdynamictype             ! 'allocatable' version
            \DWATdatalocation (dwarf expression to locate raw data)
            \DWATallocated (dwarf expression to test is allocated)
            \DWATtype (11$)

16$:    \DWTAGvariable
            \DWATname ("t1")
            \DWATtype (13$)
            \DWATlocation (dwarf expression to locate descriptor)
17$:    \DWTAGvariable
            \DWATname ("t2")
            \DWATtype (14$)
            \DWATlocation (dwarf expression to locate descriptor)
18$:    \DWTAGvariable
            \DWATname ("t3")
            \DWATtype (15$)
            \DWATlocation (dwarf expression to locate descriptor)
19$:    \DWTAGvariable
            \DWATname ("t4")
            \DWATtype (15$)
            \DWATlocation (dwarf expression to locate descriptor)
\end{alltt}
\end{dwflisting}
\caption{Fortran dynamic type example: DWARF description}
\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}[ht]
\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}[ht]
\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}
illustrates two kinds of \addtoindex{Ada} 
parameterized array, one embedded in a record.

\begin{figure}[ht]
\begin{lstlisting}
M : INTEGER := <exp>;
VEC1 : array (1..M) of INTEGER;
subtype TEENY is INTEGER range 1..100;
type ARR is array (INTEGER range <>) of INTEGER;
type REC2(N : TEENY := 100) is record
    VEC2 : ARR(1..N);
end record;

OBJ2B : REC2;
\end{lstlisting}
\caption{Ada example: source fragment}
\label{fig:adaexamplesourcefragment}
\end{figure}

\texttt{VEC1} illustrates an (unnamed) array type where the upper bound
of the first and only dimension is determined at runtime. 
\addtoindex{Ada}
semantics require that the value of an array bound is fixed at
the time the array type is elaborated (where \textit{elaboration} refers
to the runtime executable aspects of type processing). For
the purposes of this example, we assume that there are no
other assignments to \texttt{M} so that it safe for the \texttt{REC1} type
description to refer directly to that variable (rather than
a compiler-generated copy).

\texttt{REC2} illustrates another array type (the unnamed type of
component \texttt{VEC2}) where the upper bound of the first and only
bound is also determined at runtime. In this case, the upper
bound is contained in a discriminant of the containing record
type. (A \textit{discriminant} is a component of a record whose value
cannot be changed independently of the rest of the record
because that value is potentially used in the specification
of other components of the record.)

The DWARF description is shown in 
Figure \refersec{fig:adaexampledwarfdescription}.


Interesting aspects about this example are:
\begin{enumerate}[1. ]
\item The array \texttt{VEC2} is \doublequote{immediately} contained within structure
\texttt{REC2} (there is no intermediate descriptor or indirection),
which is reflected in the absence of a \DWATdatalocation{}
attribute on the array type at 28\$.

\item One of the bounds of \texttt{VEC2} is nonetheless dynamic and part of
the same containing record. It is described as a reference to
a member, and the location of the upper bound is determined
as for any member. That is, the location is determined using
an address calculation relative to the base of the containing
object.  

A consumer must notice that the referenced bound is a
member of the same containing object and implicitly push the
base address of the containing object just as for accessing
a data member generally.

\item The lack of a subtype concept in DWARF means that DWARF types
serve the role of subtypes and must replicate information from
\bbeb 
the parent type. For this reason, DWARF for
the unconstrained array type \texttt{ARR} is not needed for the purposes
of this example and therefore is not shown.
\end{enumerate}

\begin{figure}[p]
\begin{dwflisting}
\begin{alltt}
11\$:  \DWTAGvariable
          \DWATname("M")
          \DWATtype(reference to INTEGER)
12\$:  \DWTAGarraytype
          ! No name, default (\addtoindex{Ada}) order, default stride
          \DWATtype(reference to INTEGER)
13\$:      \DWTAGsubrangetype
              \DWATtype(reference to INTEGER)
              \DWATlowerbound(constant 1)
              \DWATupperbound(reference to variable M at 11\$)
14\$:  \DWTAGvariable
          \DWATname("VEC1")
          \DWATtype(reference to array type at 12\$)
      . . .
21\$:  \DWTAGsubrangetype
          \DWATname("TEENY")
          \DWATtype(reference to INTEGER)
          \DWATlowerbound(constant 1)
          \DWATupperbound(constant 100)
      . . .
26\$:  \DWTAGstructuretype
          \DWATname("REC2")
27\$:      \DWTAGmember
              \DWATname("N")
              \DWATtype(reference to subtype TEENY at 21\$)
              \DWATdatamemberlocation(constant 0)
28\$:      \DWTAGarraytype
              ! No name, default (\addtoindex{Ada}) order, default stride
              ! Default data location
              \DWATtype(reference to INTEGER)
29\$:          \DWTAGsubrangetype
                  \DWATtype(reference to subrange TEENY at 21\$)
                  \DWATlowerbound(constant 1)
                  \DWATupperbound(reference to member N at 27\$)
30\$:      \DWTAGmember
              \DWATname("VEC2")
              \DWATtype(reference to array "subtype" at 28\$)
              \DWATdatamemberlocation(machine=
                  \DWOPlitn                ! where n == offset(REC2, VEC2)
                  \DWOPplus)
      . . .
41\$:  \DWTAGvariable
          \DWATname("OBJ2B")
          \DWATtype(reference to REC2 at 26\$)
          \DWATlocation(...as appropriate...)
\end{alltt}
\end{dwflisting}
\caption{Ada example: DWARF description}
\label{fig:adaexampledwarfdescription}
\end{figure}

\clearpage

\subsection{Pascal Example}
\label{app:pascalexample}
The Pascal \addtoindexx{Pascal example} source in 
Figure \referfol{fig:packedrecordexamplesourcefragment}
is used to illustrate the representation of packed unaligned
\addtoindex{bit fields}.

\begin{figure}[ht]
\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 }
         END;
\end{lstlisting}
\caption{Packed record example: source fragment}
\label{fig:packedrecordexamplesourcefragment}
\end{figure}

The DWARF representation in 
Figure \refersec{fig:packedrecordexampledwarfdescription} 
is appropriate. 
\DWTAGpackedtype{} entries could be added to
better represent the source, but these do not otherwise affect
the example and are omitted for clarity. Note that this same
representation applies to both typical big- and 
little-endian
architectures using the conventions described in 
Section \refersec{chap:datamemberentries}.

\begin{figure}[ht]
\figurepart{1}{2}
\begin{dwflisting}
\begin{alltt}
10\$:  \DWTAGbasetype
          \DWATname("BOOLEAN")
              ...
11\$:  \DWTAGbasetype
          \DWATname("INTEGER")
              ...
20\$:  \DWTAGstructuretype
          \DWATname("T")
          \DWATbitsize(2)
          \DWTAGmember
              \DWATname("F5")
              \DWATtype(reference to 10$)
              \DWATdatabitoffset(0)        ! may be omitted
              \DWATbitsize(1)
\end{alltt}
\end{dwflisting}
\caption{Packed record example: DWARF description}
\label{fig:packedrecordexampledwarfdescription}
\end{figure}

\begin{figure}[ht]
\figurepart{2}{2}
\begin{dwflisting}
\begin{alltt}
          \DWTAGmember
              \DWATname("F6")
              \DWATtype(reference to 10$)
              \DWATdatabitoffset(1)
              \DWATbitsize(1)
21\$:  \DWTAGstructuretype                  ! anonymous type for F2
          \DWTAGmember
              \DWATname("F3")
              \DWATtype(reference to 11\$)
22\$:  \DWTAGarraytype                      ! anonymous type for F4
          \DWATtype(reference to 20\$)
          \DWTAGsubrangetype
              \DWATtype(reference to 11\$)
              \DWATlowerbound(0)
              \DWATupperbound(1)
          \DWATbitstride(2)
          \DWATbitsize(4) \addtoindexx{bit size attribute}
23\$:  \DWTAGstructuretype                  ! anonymous type for V
          \DWATbitsize(39) \addtoindexx{bit size attribute}
          \DWTAGmember
              \DWATname("F1")
              \DWATtype(reference to 10\$)
              \DWATdatabitoffset(0)        ! may be omitted
              \DWATbitsize(1) ! may be omitted
          \DWTAGmember
              \DWATname("F2")
              \DWATtype(reference to 21\$)
              \DWATdatabitoffset(1)
              \DWATbitsize(32) ! may be omitted
          \DWTAGmember
              \DWATname("F4")
              \DWATtype(reference to 22\$)
              \DWATdatabitoffset(33)
              \DWATbitsize(4) ! may be omitted
          \DWTAGmember
              \DWATname("F7")
              \DWATtype(reference to 20\$)    ! type T
              \DWATdatabitoffset(37)
              \DWATbitsize(2) \addtoindexx{bit size attribute}              ! may be omitted
       \DWTAGvariable
          \DWATname("V")
          \DWATtype(reference to 23\$)
          \DWATlocation(...)
          ...
\end{alltt}
\end{dwflisting}
\begin{center}
\vspace{3mm}
Figure~\ref{fig:packedrecordexampledwarfdescription}: Packed record example: DWARF description \textit{(concluded)}
\end{center}
\end{figure}

\clearpage
\subsection{C/C++ Bit-Field Examples}
\label{app:ccppbitfieldexamples}
\textit{Bit fields\addtoindexx{bit fields} in \addtoindex{C} 
and \addtoindex{C++} typically require the use of the
\DWATdatabitoffset{}\addtoindexx{data bit offset}
and \DWATbitsize{}\addtoindexx{data bit size} attributes.}

\needlines{6}
\textit{This Standard uses the following bit numbering and direction
conventions in examples. These conventions are for illustrative
purposes and other conventions may apply on particular
architectures.}
\begin{itemize}
\item \textit{For big-endian architectures, bit offsets are
counted from high-order to low-order bits within a byte (or
larger storage unit); in this case, the bit offset identifies
the high-order bit of the object.}

\item \textit{For little-endian architectures, bit offsets are
counted from low-order to high-order bits within a byte (or
larger storage unit); in this case, the bit offset identifies
the low-order bit of the object.}
\end{itemize}

\textit{In either case, the bit so identified is defined as the 
\addtoindexx{beginning of an object}
beginning of the object.}

\needlines{5}
This section illustrates one possible representation of the 
following \addtoindex{C} structure definition in both big- 
and little-endian \byteorder{s}:

\begin{lstlisting}
struct S {
    int j:5;
    int k:6;
    int m:5;
    int n:8;
};
\end{lstlisting}

Figures \ref{fig:bigendiandatabitoffsets} and
\refersec{fig:littleendiandatabitoffsets}
show the structure layout
and data bit offsets for example big- and little-endian
architectures, respectively. Both diagrams show a structure
that begins at address A and whose size is four bytes. Also,
high order bits are to the left and low order bits are to
the right.

\begin{figure}[ht]
\begin{dwflisting}
\begin{verbatim}

    j:0
    k:5
    m:11
    n:16

    Addresses increase ->
    |       A       |     A + 1     |    A + 2      |    A + 3      | 

    Data bit offsets increase ->
    +---------------+---------------+---------------+---------------+
    |0     4|5         10|11      15|16           23|24           31|
    |   j   |     k      | m        |        n      |       <pad>   |
    |       |            |          |               |               | 
    +---------------------------------------------------------------+ 

\end{verbatim}
\end{dwflisting}
\caption{Big-endian data bit offsets}
\label{fig:bigendiandatabitoffsets}
\end{figure}

\begin{figure}[ht]
\begin{dwflisting}
\begin{verbatim}

    j:0
    k:5
    m:11
    n:16
                                               <- Addresses increase
    |     A + 3     |     A + 2     |    A + 1      |       A       | 

                                        <-  Data bit offsets increase 
    +---------------+---------------+---------------+---------------+
    |31           24|23           16|15     11|10       5|4        0|
    |     <pad>     |        n      |    m    |    k     |     j    |
    |               |               |         |          |          |
    +---------------------------------------------------------------+

\end{verbatim}
\end{dwflisting}
\caption{Little-endian data bit offsets}
\label{fig:littleendiandatabitoffsets}
\end{figure}

\needlines{4}
Note that data member bit offsets in this example are the
same for both big- and little-endian architectures even
though the fields are allocated in different directions
(high-order to low-order versus low-order to high-order);
the bit naming conventions for memory and/or registers of
the target architecture may or may not make this seem natural.

\clearpage
\section{Namespace Examples}
\label{app:namespaceexamples}

The \addtoindex{C++} example in 
Figure \refersec{fig:namespaceexample1sourcefragment}
is used 
\addtoindexx{namespace (C++)!example}
to illustrate the representation of namespaces.
The DWARF representation in 
Figure \refersec{fig:namespaceexample1dwarfdescription}
is appropriate.

\begin{figure}[ht]
\begin{lstlisting}
namespace {
    int i;
}
namespace A {
    namespace B {
        int j;
        int   myfunc (int a);
        float myfunc (float f) { return f - 2.0; }
        int   myfunc2(int a)   { return a + 2; }
    }
}
namespace Y {
    using A::B::j;         // (1) using declaration
    int foo;
}
using A::B::j;             // (2) using declaration
namespace Foo = A::B;      // (3) namespace alias
using Foo::myfunc;         // (4) using declaration
using namespace Foo;       // (5) using directive
namespace A {
    namespace B {
        using namespace Y; // (6) using directive
        int k;
    }
}
int Foo::myfunc(int a)
{
    i = 3;
    j = 4;
    return myfunc2(3) + j + i + a + 2;
}
\end{lstlisting}
\caption{Namespace example \#1: source fragment}
\label{fig:namespaceexample1sourcefragment}
\end{figure}


\begin{figure}[p]
\figurepart{1}{2}
\begin{dwflisting}
\begin{alltt}

1\$:   \DWTAGbasetype
          \DWATname("int")
          ...
2\$:   \DWTAGbasetype
          \DWATname("float")
          ...
6\$:   \DWTAGnamespace
          ! no \DWATname attribute
          \DWATexportsymbols              ! Implied by C++, but can be explicit
          \DWTAGvariable
              \DWATname("i")
              \DWATtype(reference to 1\$)
              \DWATlocation ...
              ...
10\$:  \DWTAGnamespace
          \DWATname("A")
20\$:      \DWTAGnamespace
              \DWATname("B")
30\$:          \DWTAGvariable
                  \DWATname("j")
                  \DWATtype(reference to 1\$)
                  \DWATlocation ...
                  ...
34\$:          \DWTAGsubprogram
                  \DWATname("myfunc")
                  \DWATtype(reference to 1\$)
                  ...
36\$:          \DWTAGsubprogram
                  \DWATname("myfunc")
                  \DWATtype(reference to 2\$)
                  ...
38\$:          \DWTAGsubprogram
                  \DWATname("myfunc2")
                  \DWATlowpc ...
                  \DWAThighpc ...
                  \DWATtype(reference to 1\$)
                  ...
\end{alltt}
\end{dwflisting}
\caption{Namespace example \#1: DWARF description}
\label{fig:namespaceexample1dwarfdescription}
\end{figure}

\begin{figure}
\figurepart{2}{2}
\begin{dwflisting}
\begin{alltt}
40\$:  \DWTAGnamespace
          \DWATname("Y")
          \DWTAGimporteddeclaration            ! (1) using-declaration
              \DWATimport(reference to 30\$)
          \DWTAGvariable
              \DWATname("foo")
              \DWATtype(reference to 1\$)
              \DWATlocation ...
              ...
      \DWTAGimporteddeclaration                ! (2) using declaration
          \DWATimport(reference to 30\$)
      \DWTAGimporteddeclaration                ! (3) namespace alias
          \DWATname("Foo")
          \DWATimport(reference to 20\$)
      \DWTAGimporteddeclaration                ! (4) using declaration
          \DWATimport(reference to 34\$)         !     - part 1
      \DWTAGimporteddeclaration                ! (4) using declaration
          \DWATimport(reference to 36\$)         !     - part 2
      \DWTAGimportedmodule                     ! (5) using directive
          \DWATimport(reference to 20\$)
      \DWTAGnamespace
          \DWATextension(reference to 10\$)
          \DWTAGnamespace
              \DWATextension(reference to 20\$)
              \DWTAGimportedmodule             ! (6) using directive
                  \DWATimport(reference to 40\$)
              \DWTAGvariable
                  \DWATname("k")
                  \DWATtype(reference to 1\$)
                  \DWATlocation ...
                  ...
60\$:  \DWTAGsubprogram
          \DWATspecification(reference to 34\$)
          \DWATlowpc ...
          \DWAThighpc ...
          ...
\end{alltt}
\end{dwflisting}
\begin{center}
\vspace{3mm}
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}[ht]
\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}[ht]
\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}
\addtoindexx{member function example}
Consider the member function example fragment in 
Figure \refersec{fig:memberfunctionexamplesourcefragment}.
The DWARF representation in 
Figure \refersec{fig:memberfunctionexampledwarfdescription}
is appropriate.

\begin{figure}[ht]
\begin{lstlisting}
class A
{
    void func1(int x1);
    void func2() const;
    static void func3(int x3);
};
void A::func1(int x) {}
\end{lstlisting}
\caption{Member function example: source fragment}
\label{fig:memberfunctionexamplesourcefragment}
\end{figure}

\begin{figure}[ht]
\figurepart{1}{2}
\begin{dwflisting}
\begin{alltt}

2\$: \DWTAGbasetype
        \DWATname("int")
        ...
3\$: \DWTAGclasstype
        \DWATname("A")
        ...
4\$:     \DWTAGpointertype
            \DWATtype(reference to 3\$)
            ...
5\$:     \DWTAGconsttype
            \DWATtype(reference to 3\$)
            ...
6\$:     \DWTAGpointertype
            \DWATtype(reference to 5\$)
            ...

7\$:     \DWTAGsubprogram
            \DWATdeclaration
            \DWATname("func1")
            \DWATobjectpointer(reference to 8\$) \addtoindexx{object pointer attribute}
                ! References a formal parameter in this 
                ! member function
            ...

\end{alltt}
\end{dwflisting}
\caption{Member function example: DWARF description}
\label{fig:memberfunctionexampledwarfdescription}
\end{figure}

\begin{figure}[p]
\figurepart{2}{2}
\begin{dwflisting}
\begin{alltt}

8\$:         \DWTAGformalparameter
                \DWATartificial(true)
                \DWATname("this")
                \DWATtype(reference to 4\$)
                    ! Makes type of 'this' as 'A*' =>
                    ! func1 has not been marked const 
                    ! or volatile
                \DWATlocation ...
                ...
9\$:         \DWTAGformalparameter
                \DWATname(x1)
                \DWATtype(reference to 2\$)
                ...
10\$:    \DWTAGsubprogram
            \DWATdeclaration
            \DWATname("func2")
            \DWATobjectpointer(reference to 11\$) \addtoindexx{object pointer attribute}
            ! References a formal parameter in this 
            ! member function
            ...
11\$:        \DWTAGformalparameter
                \DWATartificial(true)
                \DWATname("this")
                \DWATtype(reference to 6\$)
                ! Makes type of 'this' as 'A const*' =>
                !     func2 marked as const
                \DWATlocation ...
                ...
12\$:    \DWTAGsubprogram
            \DWATdeclaration
            \DWATname("func3")
            ...
                ! No object pointer reference formal parameter
                ! implies func3 is static
13\$:        \DWTAGformalparameter
                \DWATname(x3)
                \DWATtype(reference to 2\$)
                ...

\end{alltt}
\end{dwflisting}
\begin{center}
\vspace{3mm}
Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example: DWARF description \textit{(concluded)}
\end{center}
\end{figure}

\clearpage
As a further example illustrating \&- and \&\&-qualification
of member functions, 
consider the member function example fragment in 
Figure \refersec{fig:memberfunctionrefqualexamplesourcefragment}.
The DWARF representation in 
Figure \refersec{fig:memberfunctionrefqualexampledwarfdescription}
is appropriate.

\begin{figure}[ht]
\begin{lstlisting}
class A {
public:
    void f() const &&;
};
   
void g() {
    A a;
    // The type of pointer is "void (A::*)() const &&".
    auto pointer_to_member_function = &A::f;
}
\end{lstlisting}
\caption{Reference- and rvalue-reference-qualification example: source \mbox{fragment}}
\label{fig:memberfunctionrefqualexamplesourcefragment}
\end{figure}

\begin{figure}[ht]
%\figurepart{1}{2}
\begin{dwflisting}
\begin{alltt}

100$:   \DWTAGclasstype
            \DWATname("A")
            \DWTAGsubprogram
                \DWATname("f")
                \DWATrvaluereference(0x01)
                \DWTAGformalparameter
                    \DWATtype({ref to 200$})    ! to const A*
                    \DWATartificial(0x01)

200$:   ! const A*
        \DWTAGpointertype
            \DWATtype({ref to 300$})             ! to const A

300$:   ! const A
        \DWTAGconsttype
            \DWATtype({ref to 100$})             ! to class A

400$:   ! mfptr
        \DWTAGptrtomembertype
            \DWATtype({ref to 400$})             ! to functype
            \DWATcontainingtype({ref to 100$})  ! to class A

500$:   ! functype
        \DWTAGsubroutinetype
            \DWATrvaluereference(0x01)
            \DWTAGformalparameter
                \DWATtype({ref to 200$})         ! to const A*
                \DWATartificial(0x01)

600$:   \DWTAGsubprogram
            \DWATname("g")
            \DWTAGvariable
                \DWATname("a")
                \DWATtype({ref to 100$})         ! to class A
            \DWTAGvariable
                \DWATname("pointer_to_member_function")
                \DWATtype({ref to 300$})
         
\end{alltt}
\end{dwflisting}
% The extra ~ at the end of the following caption is present to get the entry in the
% List of Figures to wrap the page number properly (to align the numbers)...
\caption{Reference- and rvalue-reference-qualification example: DWARF \mbox{description} ~}
\label{fig:memberfunctionrefqualexampledwarfdescription}
\end{figure}


\clearpage
\section{Line Number Examples}
\label{app:linenumberexamples}

\subsection{Line Number Header Example}
\label{app:linenumberheaderexample}

The information found in a \DWARFVersionIV{} line number 
header can be encoded in a \DWARFVersionV{} header
as shown in Figure \refersec{fig:preV5LNCTusingV5}.

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}
  Field           Field Name                      Value(s)
  Number
     1    \textit{Same as in Version 4}            ...
     2    version                         5
     3    \textit{Not present in Version 4}        -
     4    \textit{Not present in Version 4}        -
   5-12   \textit{Same as in Version 4}            ...
    13    \HFNdirectoryentryformatcount{}    1
    14    \HFNdirectoryentryformat{}          \DWLNCTpath, \DWFORMstring
    15    \HFNdirectoriescount{}               <n>
    16    \HFNdirectories{}                     <n>*<null terminated string>
    17    \HFNfilenameentryformatcount{}    4
    18    \HFNfilenameentryformat{}          \DWLNCTpath, \DWFORMstring,
                                          \DWLNCTdirectoryindex, \DWFORMudata,
                                          \DWLNCTtimestamp, \DWFORMudata,
                                          \DWLNCTsize, \DWFORMudata
    19    \HFNfilenamescount{}                <m>
    20    \HFNfilenames{}                      <m>*\{<null terminated string>, <index>, 
                                               <timestamp>, <size>\}
\end{alltt}
\end{dwflisting}
\begin{centering}
\caption{Pre-\DWARFVersionV{} line number program header information \mbox{encoded} using \DWARFVersionV}
\label{fig:preV5LNCTusingV5}
\end{centering}
\end{figure}

\subsection{Line Number Special Opcode Example}
\label{app:linenumberspecialopcodeexample}
Suppose the line number header includes the following 
(header fields not needed are not shown):
\begin{center}
\begin{tabular}{lr}
    \addttindex{opcode\_base} & 13 \\
    \addttindex{line\_base}   & -3 \\
    \addttindex{line\_range}  & 12 \\
    \addttindex{minimum\_instruction\_length} &          1 \\
    \addttindex{maximum\_operations\_per\_instruction} & 1 \\
\end{tabular}
\end{center}
This means that
we can use a special opcode whenever two successive rows in
the matrix have source line numbers differing by any value
within the range \mbox{[-3, 8]} and (because of the limited number
of opcodes available) when the difference between addresses
is within the range [0, 20].
The resulting opcode mapping is shown in
Figure \refersec{fig:examplelinenumberspecialopcodemapping}.

Note in the bottom row of the figure that not all line advances are 
available for the maximum \addtoindex{operation advance}.

\begin{figure}[ht]
\begin{alltt}
                        Line Advance
   Operation  
     Advance    -3  -2  -1   0   1   2   3   4   5   6   7   8
   ---------   -----------------------------------------------
           0    13  14  15  16  17  18  19  20  21  22  23  24
           1    25  26  27  28  29  30  31  32  33  34  35  36
           2    37  38  39  40  41  42  43  44  45  46  47  48
           3    49  50  51  52  53  54  55  56  57  58  59  60
           4    61  62  63  64  65  66  67  68  69  70  71  72
           5    73  74  75  76  77  78  79  80  81  82  83  84
           6    85  86  87  88  89  90  91  92  93  94  95  96
           7    97  98  99 100 101 102 103 104 105 106 107 108
           8   109 110 111 112 113 114 115 116 117 118 119 120
           9   121 122 123 124 125 126 127 128 129 130 131 132
          10   133 134 135 136 137 138 139 140 141 142 143 144
          11   145 146 147 148 149 150 151 152 153 154 155 156
          12   157 158 159 160 161 162 163 164 165 166 167 168
          13   169 170 171 172 173 174 175 176 177 178 179 180
          14   181 182 183 184 185 186 187 188 189 190 191 192
          15   193 194 195 196 197 198 199 200 201 202 203 204
          16   205 206 207 208 209 210 211 212 213 214 215 216
          17   217 218 219 220 221 222 223 224 225 226 227 228 
          18   229 230 231 232 233 234 235 236 237 238 239 240 
          19   241 242 243 244 245 246 247 248 249 250 251 252
          20   253 254 255
          
\end{alltt}
\caption{Example line number special opcode mapping}
\label{fig:examplelinenumberspecialopcodemapping}
\end{figure}

There is no requirement that the expression 
255 - \addttindex{line\_base} + 1 be an integral multiple of
\addttindex{line\_range}.


\clearpage
\subsection{Line Number Program Example}
\label{app:linenumberprogramexample}

Consider the simple source file and the resulting machine
code for the Intel 8086 processor in 
Figure \refersec{fig:linenumberprogramexamplemachinecode}.

\begin{figure}[ht]
\begin{lstlisting}
1: int
2: main()
    0x239: push pb
    0x23a: mov bp,sp
3: {
4: printf("Omit needless words\n");
    0x23c: mov ax,0xaa
    0x23f: push ax
    0x240: call _printf
    0x243: pop cx
5: exit(0);
    0x244: xor ax,ax
    0x246: push ax
    0x247: call _exit
    0x24a: pop cx
6: }
    0x24b: pop bp
    0x24c: ret
7: 0x24d:
\end{lstlisting}
\caption{Line number program example: machine code}
\label{fig:linenumberprogramexamplemachinecode}
\end{figure}

Suppose the line number program header includes the 
same values and resulting encoding illustrated in the 
previous Section \refersec{app:linenumberspecialopcodeexample}.

Table \refersec{tab:linenumberprogramexampleoneencoding}
shows one encoding of the line number program, which occupies
12 bytes.

\newpage
\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{l|l|l}
  \caption{Line number program example: one \mbox{encoding}}
  \label{tab:linenumberprogramexampleoneencoding} \\
  \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
\endfirsthead
  \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
\endhead
  \hline \emph{Continued on next page}
\endfoot
  \hline
\endlastfoot
\DWLNSadvancepc&LEB128(0x239)&0x2, 0xb9, 0x04 \\
SPECIAL\dag~(2, 0)& & 0x12~~(18$_{10}$)  \\
SPECIAL\dag~(2, 3)& & 0x36~~(54$_{10}$) \\
SPECIAL\dag~(1, 8)& & 0x71~~(113$_{10}$) \\
SPECIAL\dag~(1, 7)& & 0x65~~(101$_{10}$) \\
\DWLNSadvancepc&LEB128(2)&0x2, 0x2 \\
\DWLNEendsequence{} &&0x0, 0x1, 0x1 \\
\end{longtable}
\end{centering}
\dag~The opcode notation SPECIAL(\textit{m},\textit{n}) indicates 
the special opcode generated for a line advance of \textit{m} 
and an operation advance of \textit{n})

Table \refersec{tab:linenumberprogramexamplealternateencoding}
shows an alternate 
encoding of the same program using 
standard opcodes to advance
the program counter; 
this encoding occupies 22 bytes.

\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{l|l|l}
  \caption{Line number program example: alternate encoding} 
  \label{tab:linenumberprogramexamplealternateencoding} \\
  \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
\endfirsthead
  \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
\endhead
  \hline \emph{Continued on next page}
\endfoot
  \hline
\endlastfoot
\DWLNSfixedadvancepc&0x239&0x9, 0x39, 0x2        \\
SPECIAL\ddag~(2, 0) && 0x12~~(18$_{10}$)        \\
\DWLNSfixedadvancepc&0x3&0x9, 0x3, 0x0        \\
SPECIAL\ddag~(2, 0) && 0x12~~(18$_{10}$)        \\
\DWLNSfixedadvancepc&0x8&0x9, 0x8, 0x0        \\
SPECIAL\ddag~(1, 0) && 0x11~~(17$_{10}$)        \\
\DWLNSfixedadvancepc&0x7&0x9, 0x7, 0x0        \\
SPECIAL\ddag~(1, 0) && 0x11~~(17$_{10}$)        \\
\DWLNSfixedadvancepc&0x2&0x9, 0x2, 0x0        \\
\DWLNEendsequence&&0x0, 0x1, 0x1        \\
\end{longtable}
\end{centering}
\ddag~SPECIAL is defined the same as in the preceding Table
\ref{tab:linenumberprogramexampleoneencoding}.
\needlines{6}
\section{Call Frame Information Example}
\label{app:callframeinformationexample}

The following example uses a hypothetical RISC machine in
the style of the Motorola 88000.
\begin{itemize}
\item Memory is byte addressed.

\item Instructions are all 4 bytes each and word aligned.

\item Instruction operands are typically of the form:
\begin{alltt}
    <destination.reg>, <source.reg>, <constant>
\end{alltt}

\item The address for the load and store instructions is computed
by adding the contents of the
source register with the constant.

\item There are eight 4-byte registers:
\newline
\begin{tabular}{p{5mm}l}
   & R0 always 0 \\
   & R1 holds return address on call \\
   & R2-R3 temp registers (not preserved on call) \\
   & R4-R6 preserved on call \\
   & R7 stack pointer \\
\end{tabular}

\item  The stack grows in the negative direction.

\item The architectural ABI committee specifies that the
stack pointer (R7) is the same as the CFA

\end{itemize}

Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
shows two code fragments from a subroutine called
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.


\begin{figure}[ht]
\begin{lstlisting}
       ;; start prologue
foo    sub   R7, R7, <fs>        ; Allocate frame
foo+4  store R1, R7, (<fs>-4)    ; Save the return address
foo+8  store R6, R7, (<fs>-8)    ; Save R6
foo+12 add   R6, R7, 0           ; R6 is now the Frame ptr
foo+16 store R4, R6, (<fs>-12)   ; Save a preserved reg
       ;; This subroutine does not change R5
       ...
       ;; Start epilogue (R7 is returned to entry value)
foo+64 load  R4, R6, (<fs>-12)   ; Restore R4
foo+68 load  R6, R7, (<fs>-8)    ; Restore R6
foo+72 load  R1, R7, (<fs>-4)    ; Restore return address
foo+76 add   R7, R7, <fs>        ; Deallocate frame
foo+80 jump  R1                  ; Return
foo+84
\end{lstlisting}
\caption{Call frame information example: machine code fragments}
\label{fig:callframeinformationexamplemachinecodefragments}
\end{figure}


An abstract table 
(see Section \refersec{chap:structureofcallframeinformation}) 
for the foo subroutine is shown in 
Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
Corresponding fragments from the
\dotdebugframe{} section are shown in 
Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.

The following notations apply in 
Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
\newline
\begin{tabular}{p{5mm}l}
&1.  R8 is the return address \\
&2.  s = same\_value rule \\
&3.  u = undefined rule \\
&4.  rN = register(N) rule \\
&5.  cN = offset(N) rule \\
&6.  a = architectural rule \\
\end{tabular}

\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{l|llllllllll}
  \caption{Call frame information 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
\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
  \hline \emph{Continued on next page}
\endfoot
  \hline
\endlastfoot
foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
...&&&&&&&&&& \\
foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4  \\
foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4  \\
foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
\end{longtable}
\end{centering}

\clearpage      % ?????

\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{l|ll}
  \caption{Call frame information example: common information entry encoding} 
  \label{tab:callframeinformationexamplecommoninformationentryencoding} 
  \\
  \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
\endfirsthead
  \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
\endhead
  \hline \emph{Continued on next page}
\endfoot
  \hline
\endlastfoot
cie&36&length    \\
cie+4&\xffffffff&CIE\_id    \\
cie+8&4&version    \\
cie+9&0&augmentation     \\
cie+10&4&address size    \\
cie+11&0&segment size    \\
cie+12&4&code\_alignment\_factor, \textless caf \textgreater    \\
cie+13&-4&data\_alignment\_factor, \textless daf \textgreater    \\
cie+14&8&R8 is the return addr.    \\
cie+15&\DWCFAdefcfa{} (7, 0)&CFA = [R7]+0    \\
cie+18&\DWCFAsamevalue{} (0)&R0 not modified (=0)    \\
cie+20&\DWCFAundefined{} (1)&R1 scratch    \\
cie+22&\DWCFAundefined{} (2)&R2 scratch    \\
cie+24&\DWCFAundefined{} (3)&R3 scratch    \\
cie+26&\DWCFAsamevalue{} (4)&R4 preserve    \\
cie+28&\DWCFAsamevalue{} (5)&R5 preserve    \\
cie+30&\DWCFAsamevalue{} (6)&R6 preserve    \\
cie+32&\DWCFAsamevalue{} (7)&R7 preserve    \\
cie+34&\DWCFAregister{} (8, 1)&R8 is in R1    \\
cie+37&\DWCFAnop{} &padding    \\
cie+38&\DWCFAnop{} &padding \\
cie+39& \DWCFAnop&padding  \\
cie+40 &&  \\
\end{longtable}
\end{centering}


The following notations apply in 
Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
\newline
\begin{tabular}{p{5mm}l}
&\texttt{<fs>  =} frame size \\
&\texttt{<caf> =} code alignment factor \\
&\texttt{<daf> =} data alignment factor \\
\end{tabular}


\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{l|ll}
  \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
  \hline \emph{Continued on next page}
\endfoot
  \hline
\endlastfoot
fde&40&length \\
fde+4&cie&CIE\_ptr \\
fde+8&foo&initial\_location \\
fde+12&84&address\_range \\
fde+16&\DWCFAadvanceloc(1)&instructions \\
fde+17&\DWCFAdefcfaoffset(12)& \textless fs\textgreater \\
fde+19&\DWCFAadvanceloc(1)&4/\textless caf\textgreater \\
fde+20&\DWCFAoffset(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
fde+22&\DWCFAadvanceloc(1)& \\
fde+23&\DWCFAoffset(6,2)&-8/\textless daf\textgreater (2nd parameter)  \\
fde+25&\DWCFAadvanceloc(1) & \\
fde+26&\DWCFAdefcfaregister(6) & \\
fde+28&\DWCFAadvanceloc(1) & \\
fde+29&\DWCFAoffset(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
fde+31&\DWCFAadvanceloc(12)&44/\textless caf\textgreater \\
fde+32&\DWCFArestore(4)& \\
fde+33&\DWCFAadvanceloc(1) & \\
fde+34&\DWCFArestore(6) & \\
fde+35&\DWCFAdefcfaregister(7)  & \\
fde+37&\DWCFAadvanceloc(1) & \\
fde+38&\DWCFArestore(8) &\\
fde+39&\DWCFAadvanceloc(1) &\\
fde+40&\DWCFAdefcfaoffset(0)  &\\
fde+42&\DWCFAnop&padding \\
fde+43&\DWCFAnop&padding \\
fde+44 && \\
\end{longtable}
\end{centering}

\needlines{6}
\section{Inlining Examples}
\label{app:inliningexamples}
The pseudo\dash source in 
Figure \referfol{fig:inliningexamplespseudosourcefragment}
is used to illustrate the
\addtoindexx{inlined subprogram call!examples}
use of DWARF to describe inlined subroutine calls. This
example involves a nested subprogram \texttt{INNER} that makes uplevel
references to the formal parameter and local variable of the
containing subprogram \texttt{OUTER}.

\begin{figure}[ht]
\begin{lstlisting}
inline procedure OUTER (OUTER_FORMAL : integer) =
    begin
    OUTER_LOCAL : integer;
    procedure INNER (INNER_FORMAL : integer) =
        begin
        INNER_LOCAL : integer;
        print(INNER_FORMAL + OUTER_LOCAL);
        end;
    INNER(OUTER_LOCAL);
    ...
    INNER(31);
    end;
! Call OUTER
!
OUTER(7);
\end{lstlisting}
\caption{Inlining examples: pseudo-source fragmment} 
\label{fig:inliningexamplespseudosourcefragment}
\end{figure}


There are several approaches that a compiler might take to
inlining for this sort of example. This presentation considers
three such approaches, all of which involve inline expansion
of subprogram \texttt{OUTER}. (If \texttt{OUTER} is not inlined, the inlining
reduces to a simpler single level subset of the two level
approaches considered here.)

The approaches are:
\begin{enumerate}[1. ]
\item  Inline both \texttt{OUTER} and \texttt{INNER} in all cases

\item Inline \texttt{OUTER}, multiple \texttt{INNER}s \\
Treat \texttt{INNER} as a non-inlinable part of \texttt{OUTER}, compile and
call a distinct normal version of \texttt{INNER} defined within each
inlining of \texttt{OUTER}.

\item Inline \texttt{OUTER}, one \texttt{INNER} \\
Compile \texttt{INNER} as a single normal subprogram which is called
from every inlining of \texttt{OUTER}.
\end{enumerate}

This discussion does not consider why a compiler might choose
one of these approaches; it considers only how to describe
the result.

In the examples that follow in this section, the debugging
information entries are given mnemonic labels of the following
form
\begin{verbatim}
    <io>.<ac>.<n>.<s>
\end{verbatim}
where
\begin{description}
\item[\textless io\textgreater]
is either \texttt{INNER} or \texttt{OUTER} to indicate to which
subprogram the debugging information entry applies, 
\item[\textless ac\textgreater]
is either AI or CI to indicate \doublequote{abstract instance} or
\doublequote{concrete instance} respectively, 
\item[\textless n\textgreater]
is the number of the
alternative being considered, and 
\item[\textless s\textgreater]
is a sequence number that
distinguishes the individual entries. 
\end{description}
There is no implication
that symbolic labels, nor any particular naming convention,
are required in actual use.

For conciseness, declaration coordinates and call coordinates are omitted.

\subsection{Alternative \#1: inline both OUTER and INNER}
\label{app:inlinebothouterandinner}

A suitable abstract instance for an alternative where both
\texttt{OUTER} and \texttt{INNER} are always inlined is shown in 
Figure \refersec{fig:inliningexample1abstractinstance}.

Notice in 
Figure \ref{fig:inliningexample1abstractinstance} 
that the debugging information entry for
\texttt{INNER} (labelled \texttt{INNER.AI.1.1\$}) is nested in (is a child of)
that for \texttt{OUTER} (labelled \texttt{OUTER.AI.1.1\$}). Nonetheless, the
abstract instance tree for \texttt{INNER} is considered to be separate
and distinct from that for \texttt{OUTER}.

The call of \texttt{OUTER} shown in 
Figure \refersec{fig:inliningexamplespseudosourcefragment}
might be described as
shown in 
Figure \refersec{fig:inliningexample1concreteinstance}.


\begin{figure}[p]
\begin{dwflisting}
\begin{alltt}
    ! Abstract instance for OUTER
    ! \addtoindexx{abstract instance!example}
OUTER.AI.1.1\$:
    \DWTAGsubprogram
        \DWATname("OUTER")
        \DWATinline(\DWINLdeclaredinlined)
        ! No low/high PCs
OUTER.AI.1.2\$:
        \DWTAGformalparameter
            \DWATname("OUTER\_FORMAL")
            \DWATtype(reference to integer)
            ! No location
OUTER.AI.1.3\$:
        \DWTAGvariable
            \DWATname("OUTER\_LOCAL")
            \DWATtype(reference to integer)
            ! No location
        !
        ! Abstract instance for INNER
        !
INNER.AI.1.1\$:
        \DWTAGsubprogram
            \DWATname("INNER")
            \DWATinline(\DWINLdeclaredinlined)
            ! No low/high PCs
INNER.AI.1.2\$:
            \DWTAGformalparameter
                \DWATname("INNER\_FORMAL")
                \DWATtype(reference to integer)
                ! No location
INNER.AI.1.3\$:
            \DWTAGvariable
                \DWATname("INNER\_LOCAL")
                \DWATtype(reference to integer)
                ! No location
            ...
            0
        ! No \DWTAGinlinedsubroutine (concrete instance)
        ! for INNER corresponding to calls of INNER
        ...
        0
\end{alltt}
\end{dwflisting}
\caption{Inlining example \#1: abstract instance}
\label{fig:inliningexample1abstractinstance}
\end{figure}

\begin{figure}[p]
\begin{dwflisting}
\begin{alltt}
! Concrete instance for call "OUTER(7)"
! \addtoindexx{concrete instance!example}
OUTER.CI.1.1\$:
    \DWTAGinlinedsubroutine
        ! No name
        \DWATabstractorigin(reference to OUTER.AI.1.1\$)
        \DWATlowpc(...)
        \DWAThighpc(...)
OUTER.CI.1.2\$:
        \DWTAGformalparameter
            ! No name
            \DWATabstractorigin(reference to OUTER.AI.1.2\$)
            \DWATconstvalue(7)
OUTER.CI.1.3\$:
        \DWTAGvariable
            ! No name
            \DWATabstractorigin(reference to OUTER.AI.1.3\$)
            \DWATlocation(...)
        !
        ! No \DWTAGsubprogram (abstract instance) for INNER
        !
        ! Concrete instance for call INNER(OUTER\_LOCAL)
        !
INNER.CI.1.1\$:
        \DWTAGinlinedsubroutine
            ! No name
            \DWATabstractorigin(reference to INNER.AI.1.1\$)
            \DWATlowpc(...)
            \DWAThighpc(...)
            \DWATstaticlink(...)
INNER.CI.1.2\$:
            \DWTAGformalparameter
                ! No name
                \DWATabstractorigin(reference to INNER.AI.1.2\$)
                \DWATlocation(...)
INNER.CI.1.3\$:
            \DWTAGvariable
                ! No name
                \DWATabstractorigin(reference to INNER.AI.1.3\$)
                \DWATlocation(...)
            ...
            0
        ! Another concrete instance of INNER within OUTER
        ! for the call "INNER(31)"
        ...
        0
\end{alltt}
\end{dwflisting}
\caption{Inlining example \#1: concrete instance}
\label{fig:inliningexample1concreteinstance}
\end{figure}

\subsection{Alternative \#2: Inline OUTER, multiple INNERs}
\label{app:inlineoutermultiipleinners}


In the second alternative we assume that subprogram \texttt{INNER}
is not inlinable for some reason, but subprogram \texttt{OUTER} is
inlinable. 
\addtoindexx{concrete instance!example}
Each concrete inlined instance of \texttt{OUTER} has its
own normal instance of \texttt{INNER}. 
The abstract instance for \texttt{OUTER},
\addtoindexx{abstract instance!example}
which includes \texttt{INNER}, is shown in 
Figure \refersec{fig:inliningexample2abstractinstance}.

Note that the debugging information in 
Figure \ref{fig:inliningexample2abstractinstance}
differs from that in 
Figure \refersec{fig:inliningexample1abstractinstance}
in that \texttt{INNER} lacks a 
\DWATinline{} attribute
and therefore is not a distinct abstract instance. \texttt{INNER}
is merely an out\dash of\dash line routine that is part of \texttt{OUTER}\textquoteright s
abstract instance. This is reflected in the Figure by
\addtoindexx{abstract instance!example}
the fact that the labels for \texttt{INNER} use the substring \texttt{OUTER}
instead of \texttt{INNER}.

A resulting 
\addtoindexx{concrete instance!example}
concrete inlined instance of \texttt{OUTER} is shown in
Figure \refersec{fig:inliningexample2concreteinstance}.

Notice in 
Figure \ref{fig:inliningexample2concreteinstance}
that \texttt{OUTER} is expanded as a concrete
\addtoindexx{concrete instance!example}
inlined instance, and that \texttt{INNER} is nested within it as a
concrete out\dash of\dash line subprogram. Because \texttt{INNER} is cloned
for each inline expansion of \texttt{OUTER}, only the invariant
attributes of \texttt{INNER} 
(for example, \DWATname) are specified
in the abstract instance of \texttt{OUTER}, and the low\dash level,
\addtoindexx{abstract instance!example}
instance\dash specific attributes of \texttt{INNER} (for example,
\DWATlowpc) are specified in 
each concrete instance of \texttt{OUTER}.
\addtoindexx{concrete instance!example}

The several calls of \texttt{INNER} within \texttt{OUTER} are compiled as normal
calls to the instance of \texttt{INNER} that is specific to the same
instance of \texttt{OUTER} that contains the calls.

\begin{figure}[t]
\begin{dwflisting}
\begin{alltt}
    ! Abstract instance for OUTER
    ! \addtoindex{abstract instance}
OUTER.AI.2.1\$:
    \DWTAGsubprogram
        \DWATname("OUTER")
        \DWATinline(\DWINLdeclaredinlined)
        ! No low/high PCs
OUTER.AI.2.2\$:
        \DWTAGformalparameter
            \DWATname("OUTER\_FORMAL")
            \DWATtype(reference to integer)
            ! No location
OUTER.AI.2.3\$:
        \DWTAGvariable
            \DWATname("OUTER\_LOCAL")
            \DWATtype(reference to integer)
            ! No location
        !
        ! Nested out-of-line INNER subprogram
        !
OUTER.AI.2.4\$:
        \DWTAGsubprogram
            \DWATname("INNER")
            ! No \DWATinline
            ! No low/high PCs, frame\_base, etc.
OUTER.AI.2.5\$:
            \DWTAGformalparameter
                \DWATname("INNER\_FORMAL")
                \DWATtype(reference to integer)
                ! No location
OUTER.AI.2.6\$:
            \DWTAGvariable
                \DWATname("INNER\_LOCAL")
                \DWATtype(reference to integer)
                ! No location
            ...
            0
        ...
        0
\end{alltt}
\end{dwflisting}
\caption{Inlining example \#2: abstract instance}
\label{fig:inliningexample2abstractinstance}
\end{figure}

\begin{figure}[t]
\begin{dwflisting}
\begin{alltt}

    ! Concrete instance for call "OUTER(7)"
    !
OUTER.CI.2.1\$:
    \DWTAGinlinedsubroutine
        ! No name
        \DWATabstractorigin(reference to OUTER.AI.2.1\$)
        \DWATlowpc(...)
        \DWAThighpc(...)
OUTER.CI.2.2\$:
        \DWTAGformalparameter
            ! No name
            \DWATabstractorigin(reference to OUTER.AI.2.2\$)
            \DWATlocation(...)
OUTER.CI.2.3\$:
        \DWTAGvariable
            ! No name
            \DWATabstractorigin(reference to OUTER.AI.2.3\$)
            \DWATlocation(...)
        !
        ! Nested out-of-line INNER subprogram
        !
OUTER.CI.2.4\$:
        \DWTAGsubprogram
            ! No name
            \DWATabstractorigin(reference to OUTER.AI.2.4\$)
            \DWATlowpc(...)
            \DWAThighpc(...)
            \DWATframebase(...)
            \DWATstaticlink(...)
OUTER.CI.2.5\$:
            \DWTAGformalparameter
                ! No name
                \DWATabstractorigin(reference to OUTER.AI.2.5\$)
                \DWATlocation(...)
OUTER.CI.2.6\$:
            \DWTAGvariable
                ! No name
                \DWATabstractorigin(reference to OUTER.AT.2.6\$)
                \DWATlocation(...)
            ...
            0
        ...
        0
\end{alltt}
\end{dwflisting}
\caption{Inlining example \#2: concrete instance}
\label{fig:inliningexample2concreteinstance}
\end{figure}

\subsection{Alternative \#3: inline OUTER, one normal INNER}
\label{app:inlineouteronenormalinner}

In the third approach, one normal subprogram for \texttt{INNER} is
compiled which is called from all concrete inlined instances of
\addtoindexx{concrete instance!example}
\addtoindexx{abstract instance!example}
\texttt{OUTER}. The abstract instance for \texttt{OUTER} is shown in 
Figure \refersec{fig:inliningexample3abstractinstance}.

The most distinctive aspect of that Figure is that subprogram
\texttt{INNER} exists only within the abstract instance of \texttt{OUTER},
and not in \texttt{OUTER}\textquoteright s concrete instance. In the abstract
\addtoindexx{concrete instance!example}
\addtoindexx{abstract instance!example}
instance of \texttt{OUTER}, the description of \texttt{INNER} has the full
complement of attributes that would be expected for a
normal subprogram. 
While attributes such as 
\DWATlowpc,
\DWAThighpc, 
\DWATlocation,
and so on, typically are omitted
\addtoindexx{high PC attribute}
from 
\addtoindexx{low PC attribute}
an 
\addtoindexx{location attribute}
abstract instance because they are not invariant across
instances of the containing abstract instance, in this case
those same attributes are included precisely because they are
invariant -- there is only one subprogram \texttt{INNER} to be described
and every description is the same.

A concrete inlined instance of \texttt{OUTER} is illustrated in
Figure \refersec{fig:inliningexample3concreteinstance}.

Notice in 
Figure \ref{fig:inliningexample3concreteinstance}
that there is no DWARF representation for
\texttt{INNER} at all; the representation of \texttt{INNER} does not vary across
instances of \texttt{OUTER} and the abstract instance of \texttt{OUTER} includes
the complete description of \texttt{INNER}, so that the description of
\texttt{INNER} may be (and for reasons of space efficiency, should be)
omitted from each 
\addtoindexx{concrete instance!example}
concrete instance of \texttt{OUTER}.

There is one aspect of this approach that is problematical from
the DWARF perspective. The single compiled instance of \texttt{INNER}
is assumed to access up\dash level variables of \texttt{OUTER}; however,
those variables may well occur at varying positions within
the frames that contain the 
\addtoindexx{concrete instance!example}
concrete inlined instances. A
compiler might implement this in several ways, including the
use of additional compiler-generated parameters that provide
reference parameters for the up\dash level variables, or a 
compiler-generated static link like parameter that points to the group
of up\dash level entities, among other possibilities. In either of
these cases, the DWARF description for the location attribute
of each uplevel variable needs to be different if accessed
from within \texttt{INNER} compared to when accessed from within the
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 \addtoindex{C++}, a member function of a class defined within
a function definition does not require any vendor\dash specific
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.)

\begin{figure}[t]
\begin{dwflisting}
\begin{alltt}
    ! Abstract instance for OUTER
    ! \addtoindexx{abstract instance!example}
OUTER.AI.3.1\$:
    \DWTAGsubprogram
        \DWATname("OUTER")
        \DWATinline(\DWINLdeclaredinlined)
        ! No low/high PCs
OUTER.AI.3.2\$:
        \DWTAGformalparameter
            \DWATname("OUTER\_FORMAL")
            \DWATtype(reference to integer)
            ! No location
OUTER.AI.3.3\$:
        \DWTAGvariable
            \DWATname("OUTER\_LOCAL")
            \DWATtype(reference to integer)
            ! No location
        !
        ! Normal INNER
        !
OUTER.AI.3.4\$:
        \DWTAGsubprogram
            \DWATname("INNER")
            \DWATlowpc(...)
            \DWAThighpc(...)
            \DWATframebase(...)
            \DWATstaticlink(...)
OUTER.AI.3.5\$:
            \DWTAGformalparameter
                \DWATname("INNER\_FORMAL")
                \DWATtype(reference to integer)
                \DWATlocation(...)
OUTER.AI.3.6\$:
            \DWTAGvariable
                \DWATname("INNER\_LOCAL")
                \DWATtype(reference to integer)
                \DWATlocation(...)
            ...
            0
        ...
        0
\end{alltt}
\end{dwflisting}
\caption{Inlining example \#3: abstract instance}
\label{fig:inliningexample3abstractinstance}
\end{figure}

\clearpage
\begin{figure}[t]
\begin{dwflisting}
\begin{alltt}
    ! Concrete instance for call "OUTER(7)"
    ! \addtoindexx{concrete instance!example}
OUTER.CI.3.1\$:
    \DWTAGinlinedsubroutine
        ! No name
        \DWATabstractorigin(reference to OUTER.AI.3.1\$)
        \DWATlowpc(...)
        \DWAThighpc(...)
        \DWATframebase(...)
OUTER.CI.3.2\$:
        \DWTAGformalparameter
            ! No name
            \DWATabstractorigin(reference to OUTER.AI.3.2\$)
            ! No type
            \DWATlocation(...)
OUTER.CI.3.3\$:
        \DWTAGvariable
            ! No name
            \DWATabstractorigin(reference to OUTER.AI.3.3\$)
            ! No type
            \DWATlocation(...)
        ! No \DWTAGsubprogram for "INNER"
        ...
        0
\end{alltt}
\end{dwflisting}
\caption{Inlining example \#3: concrete instance}
\label{fig:inliningexample3concreteinstance}
\end{figure}

\vspace*{0.4\baselineskip}
\section{Constant Expression Example}
\label{app:constantexpressionexample}
\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 
Figure \refersec{fig:constantexpressionsdwarfdescription}.

\begin{figure}[ht]
\begin{lstlisting}[numbers=none]
constexpr double mass = 9.8;
constexpr int square (int x) { return x * x; }
float arr[square(9)]; // square() called and inlined
\end{lstlisting}
\caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
\end{figure}

\begin{figure}[!ht]
\begin{dwflisting}
\begin{alltt}
        ! For variable mass
        !
1\$:     \DWTAGconsttype
            \DWATtype(reference to "double")
2\$:     \DWTAGvariable
            \DWATname("mass")
            \DWATtype(reference to 1\$)
            \DWATconstexpr(true)
            \DWATconstvalue(9.8)
        ! Abstract instance for square
        !
10\$:    \DWTAGsubprogram
            \DWATname("square")
            \DWATtype(reference to "int")
            \DWATinline(\DWINLinlined)
11\$:        \DWTAGformalparameter
                \DWATname("x")
                \DWATtype(reference to "int")
        ! Concrete instance for square(9)
        ! \addtoindexx{concrete instance!example}
20\$:    \DWTAGinlinedsubroutine
            \DWATabstractorigin(reference to 10\$)
            \DWATconstexpr(present)
            \DWATconstvalue(81)
            \DWTAGformalparameter
                \DWATabstractorigin(reference to 11\$)
                \DWATconstvalue(9)
        ! Anonymous array type for arr
        !
30\$:    \DWTAGarraytype
            \DWATtype(reference to "float")
            \DWATbytesize(324) ! 81*4
            \DWTAGsubrangetype
                \DWATtype(reference to "int")
                \DWATupperbound(reference to 20\$)
        ! Variable arr
        !
40\$:    \DWTAGvariable
            \DWATname("arr")
            \DWATtype(reference to 30\$)
\end{alltt}
\end{dwflisting}
\caption{Constant expressions: DWARF description}
\label{fig:constantexpressionsdwarfdescription}
\end{figure}

\clearpage
\section{Unicode Character Example}
\label{app:unicodecharacterexample}
\addtoindexx{Unicode|see {\textit{also} UTF-8}}
The \addtoindex{Unicode} character encodings in
Figure \refersec{fig:unicodecharacterexamplesource}
can be described in DWARF as illustrated in 
Figure \refersec{fig:unicodecharacterexampledwarfdescription}.

\begin{figure}[!ht]
\begin{lstlisting}[numbers=none]
// C++ source
//
char16_t chr_a = u'h';
char32_t chr_b = U'h';
\end{lstlisting}
\caption{Unicode character example: source}
\label{fig:unicodecharacterexamplesource}
\end{figure}

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}

! DWARF description
!
1\$: \DWTAGbasetype
        \DWATname("char16\_t")
        \DWATencoding(\DWATEUTF)
        \DWATbytesize(2)
2\$: \DWTAGbasetype
        \DWATname("char32\_t")
        \DWATencoding(\DWATEUTF)
        \DWATbytesize(4)
3\$: \DWTAGvariable
        \DWATname("chr\_a")
        \DWATtype(reference to 1\$)
4\$: \DWTAGvariable
        \DWATname("chr\_b")
        \DWATtype(reference to 2\$)
\end{alltt}
\end{dwflisting}
\caption{Unicode character example: DWARF description}
\label{fig:unicodecharacterexampledwarfdescription}
\end{figure}

\clearpage
\section{Type-Safe Enumeration Example}
\label{app:typesafeenumerationexample}

The \addtoindex{C++} type\dash safe enumerations in
\addtoindexx{type-safe enumeration}
Figure \refersec{fig:ctypesafeenumerationexamplesource}
can be described in DWARF as illustrated in 
Figure \refersec{fig:ctypesafeenumerationexampledwarf}.

\begin{figure}[ht]
\begin{lstlisting}[numbers=none]
// C++ source
//
enum class E { E1, E2=100 };
E e1;
\end{lstlisting}
\caption{Type-safe enumeration example: source}
\label{fig:ctypesafeenumerationexamplesource}
\end{figure}

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}
! DWARF description
!
11\$:  \DWTAGenumerationtype
          \DWATname("E")
          \DWATtype(reference to "int")
          \DWATenumclass(present)
12\$:      \DWTAGenumerator
              \DWATname("E1")
              \DWATconstvalue(0)
13\$:      \DWTAGenumerator
              \DWATname("E2")
              \DWATconstvalue(100)
14\$:  \DWTAGvariable
          \DWATname("e1")
          \DWATtype(reference to 11\$)
\end{alltt}
\end{dwflisting}
\caption{Type-safe enumeration example: DWARF description}
\label{fig:ctypesafeenumerationexampledwarf}
\end{figure}


\clearpage
\section{Template Examples}
\label{app:templateexample}

The \addtoindex{C++} template example in
Figure \refersec{fig:ctemplateexample1source}
can be described in DWARF as illustrated in 
Figure \refersec{fig:ctemplateexample1dwarf}.

\begin{figure}[ht]
\begin{lstlisting}
// C++ source
//
template<class T>
struct wrapper {
    T comp;
};
wrapper<int> obj;
\end{lstlisting}
\caption{C++ template example \#1: source}
\label{fig:ctemplateexample1source}
\end{figure}

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}
! DWARF description
!
11\$:  \DWTAGstructuretype
          \DWATname("wrapper")
12\$:      \DWTAGtemplatetypeparameter
              \DWATname("T")
              \DWATtype(reference to "int")
13\$:      \DWTAGmember
              \DWATname("comp")
              \DWATtype(reference to 12\$)
14\$:  \DWTAGvariable
          \DWATname("obj")
          \DWATtype(reference to 11\$)
\end{alltt}
\end{dwflisting}
\caption{C++ template example \#1: DWARF description}
\label{fig:ctemplateexample1dwarf}
\end{figure}

The actual type of the component \texttt{comp} is \texttt{int}, but in the DWARF
the type references the
\DWTAGtemplatetypeparameter{}
for \texttt{T}, which in turn references \texttt{int}. This implies that in the
original template comp was of type \texttt{T} and that was replaced
with \texttt{int} in the instance. 

\needlines{10}
There exist situations where it is
not possible for the DWARF to imply anything about the nature
of the original template. 
Consider the \addtoindex{C++} template source in
Figure \refersec{fig:ctemplateexample2source}
and the DWARF that can describe it in
Figure \refersec{fig:ctemplateexample2dwarf}.

\begin{figure}[!ht]
\begin{lstlisting}
// C++ source
//
    template<class T>
    struct wrapper {
        T comp;
    };
    template<class U>
    void consume(wrapper<U> formal)
    {
        ...
    }
    wrapper<int> obj;
    consume(obj);
\end{lstlisting}
\caption{C++ template example \#2: source}
\label{fig:ctemplateexample2source}
\end{figure}

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}
! DWARF description
!
11\$:  \DWTAGstructuretype
          \DWATname("wrapper")
12\$:      \DWTAGtemplatetypeparameter
              \DWATname("T")
              \DWATtype(reference to "int")
13\$:      \DWTAGmember
              \DWATname("comp")
              \DWATtype(reference to 12\$)
14\$:  \DWTAGvariable
          \DWATname("obj")
          \DWATtype(reference to 11\$)
21\$:  \DWTAGsubprogram
          \DWATname("consume")
22\$:      \DWTAGtemplatetypeparameter
              \DWATname("U")
              \DWATtype(reference to "int")
23\$:      \DWTAGformalparameter
              \DWATname("formal")
              \DWATtype(reference to 11\$)
\end{alltt}
\end{dwflisting}
\caption{C++ template example \#2: DWARF description}
\label{fig:ctemplateexample2dwarf}
\end{figure}

In the \DWTAGsubprogram{} 
entry for the instance of consume, \texttt{U} is described as \texttt{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 \texttt{wrapper\textless U\textgreater} 
which is neither
a template parameter nor a template instantiation. The type
of formal is described as \texttt{wrapper\textless int\textgreater},
the instantiation of \texttt{wrapper\textless U\textgreater},
in the \DWATtype{} attribute at 
23\$. 
There is no
description of the relationship between template type parameter
\texttt{T} at 12\$ and \texttt{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 parameter of \texttt{consume} were declared in the source to be
\texttt{wrapper\textless int\textgreater}.


\section{Template Alias Examples}
\label{app:templatealiasexample}

The \addtoindex{C++} template alias shown in
Figure \refersec{fig:ctemplatealiasexample1source}
can be described in DWARF as illustrated 
\addtoindexx{template alias example} in 
Figure \refersec{fig:ctemplatealiasexample1dwarf}.

\begin{figure}[ht]
\begin{lstlisting}
// C++ source, template alias example 1
//
template<typename T, typename U>
struct Alpha {
    T tango;
    U uniform;
};
template<typename V> using Beta = Alpha<V,V>;
Beta<long> b;
\end{lstlisting}
\caption{C++ template alias example \#1: source}
\label{fig:ctemplatealiasexample1source}
\end{figure}

\clearpage
\begin{figure}[ht]
\addtoindexx{template alias example 1}
\begin{dwflisting}
\begin{alltt}
! DWARF representation for variable 'b'
!
20\$:  \DWTAGstructuretype
          \DWATname("Alpha")
21\$:      \DWTAGtemplatetypeparameter
              \DWATname("T")
              \DWATtype(reference to "long")
22\$:      \DWTAGtemplatetypeparameter
              \DWATname("U")
              \DWATtype(reference to "long")
23\$:      \DWTAGmember
              \DWATname("tango")
              \DWATtype(reference to 21\$)
24\$:      \DWTAGmember
              \DWATname("uniform")
              \DWATtype(reference to 22\$)
25\$:  \DWTAGtemplatealias
          \DWATname("Beta")
          \DWATtype(reference to 20\$)
26\$:      \DWTAGtemplatetypeparameter
              \DWATname("V")
              \DWATtype(reference to "long")
27\$:  \DWTAGvariable
          \DWATname("b")
          \DWATtype(reference to 25\$)
\end{alltt}
\end{dwflisting}
\caption{C++ template alias example \#1: DWARF description}
\label{fig:ctemplatealiasexample1dwarf}
\end{figure}

\vspace*{0.7\baselineskip}
Similarly, the \addtoindex{C++} template alias shown in
Figure \refersec{fig:ctemplatealiasexample2source}
can be described in DWARF as illustrated 
\addtoindexx{template alias example} in 
Figure \refersec{fig:ctemplatealiasexample2dwarf}.

\begin{figure}[ht]
\begin{lstlisting}
// C++ source, template alias example 2
//
template<class TX> struct X { };
template<class TY> struct Y { };
template<class T> using Z = Y<T>;
X<Y<int>> y;
X<Z<int>> z;
\end{lstlisting}
\caption{C++ template alias example \#2: source}
\label{fig:ctemplatealiasexample2source}
\end{figure}

\begin{figure}[ht]
\addtoindexx{template alias example 2}
\begin{dwflisting}
\begin{alltt}
! DWARF representation for X<Y<int>>
!
30\$:  \DWTAGstructuretype
          \DWATname("Y")
31\$:      \DWTAGtemplatetypeparameter
              \DWATname("TY")
              \DWATtype(reference to "int")
32\$:  \DWTAGstructuretype
          \DWATname("X")
33\$:      \DWTAGtemplatetypeparameter
              \DWATname("TX")
              \DWATtype(reference to 30\$)
!
! DWARF representation for X<Z<int>>
!
40\$:  \DWTAGtemplatealias
          \DWATname("Z")
          \DWATtype(reference to 30\$)
41\$:      \DWTAGtemplatetypeparameter
              \DWATname("T")
              \DWATtype(reference to "int")
42\$:  \DWTAGstructuretype
          \DWATname("X")
43\$:      \DWTAGtemplatetypeparameter
              \DWATname("TX")
              \DWATtype(reference to 40\$)
!
! Note that 32\$ and 42\$ are actually the same type
!
50\$:  \DWTAGvariable
          \DWATname("y")
          \DWATtype(reference to \$32)
51\$:  \DWTAGvariable
          \DWATname("z")
          \DWATtype(reference to \$42)
\end{alltt}
\end{dwflisting}
\caption{C++ template alias example \#2: DWARF description}
\label{fig:ctemplatealiasexample2dwarf}
\end{figure}

\clearpage
\section{Implicit Pointer Examples}
\label{app:implicitpointerexamples}
If the compiler determines that the value of an object is
constant (either throughout the program, or within a specific
range), it may choose to materialize that constant only when
used, rather than store it in memory or in a register. The
\DWOPimplicitvalue{} operation can be used to describe such a
value. Sometimes, the value may not be constant, but still can be
easily rematerialized when needed. A DWARF expression terminating
in \DWOPstackvalue{} can be used for this case. The compiler may
also eliminate a pointer value where the target of the pointer
resides in memory, and the \DWOPstackvalue{} operator may be used
to rematerialize that pointer value. In other cases, the compiler
will eliminate a pointer to an object that itself needs to be
materialized. Since the location of such an object cannot be
represented as a memory address, a DWARF expression cannot give
either the location or the actual value or a pointer variable
that would refer to that object. The \DWOPimplicitpointer{}
operation can be used to describe the pointer, and the debugging
information entry to which its first operand refers describes the
value of the dereferenced object. A DWARF consumer will not be
able to show the location or the value of the pointer variable,
but it will be able to show the value of the dereferenced
pointer.

Consider the \addtoindex{C} source shown in 
Figure \refersec{fig:cimplicitpointerexample1source}.
Assume that the function \texttt{foo} is not inlined,
that the argument x is passed in register 5, and that the
function \texttt{foo} is optimized by the compiler into just 
an increment of the volatile variable \texttt{v}. Given these
assumptions a possible DWARF description is shown in
Figure \refersec{fig:cimplicitpointerexample1dwarf}.

\begin{figure}[ht]
\begin{lstlisting}
struct S { short a; char b, c; };
volatile int v;
void foo (int x)
{
    struct S s = { x, x + 2, x + 3 };
    char *p = &s.b;
    s.a++;
    v++;
}
int main ()
{
    foo (v+1);
    return 0;
}
\end{lstlisting}
\caption{C implicit pointer example \#1: source}
\label{fig:cimplicitpointerexample1source}
\end{figure}

\begin{figure}[ht]
\addtoindexx{implicit pointer example}
\begin{dwflisting}
\begin{alltt}
1\$:   \DWTAGstructuretype
          \DWATname("S")
          \DWATbytesize(4)
10\$:      \DWTAGmember
              \DWATname("a")
              \DWATtype(reference to "short int")
              \DWATdatamemberlocation(constant 0)
11\$:      \DWTAGmember
              \DWATname("b")
              \DWATtype(reference to "char")
              \DWATdatamemberlocation(constant 2)
12\$:      \DWTAGmember
              \DWATname("c")
              \DWATtype(reference to "char")
              \DWATdatamemberlocation(constant 3)
2\$:   \DWTAGsubprogram
          \DWATname("foo")
20\$:      \DWTAGformalparameter
              \DWATname("x")
              \DWATtype(reference to "int")
              \DWATlocation(\DWOPregfive)
21\$:      \DWTAGvariable
              \DWATname("s")
              \DWATtype(reference to S at 1\$)
              \DWATlocation(expression=
                  \DWOPbregfive(1) \DWOPstackvalue \DWOPpiece(2)
                  \DWOPbregfive(2) \DWOPstackvalue \DWOPpiece(1)
                  \DWOPbregfive(3) \DWOPstackvalue \DWOPpiece(1))
22\$:      \DWTAGvariable
              \DWATname("p")
              \DWATtype(reference to "char *")
              \DWATlocation(expression=
                  \DWOPimplicitpointer(reference to 21\$, 2))
\end{alltt}
\end{dwflisting}
\caption{C implicit pointer example \#1: DWARF description}
\label{fig:cimplicitpointerexample1dwarf}
\end{figure}

In Figure \refersec{fig:cimplicitpointerexample1dwarf},
even though variables \texttt{s} and \texttt{p} are both optimized 
away completely, this DWARF description still allows a debugger to 
print the value of the variable \texttt{s}, namely \texttt{(2, 3, 4)}. 
Similarly, because the variable \texttt{s} does not live in
memory, there is nothing to print for the value of \texttt{p}, but the 
debugger should still be able to show that \texttt{p[0]} is 3, 
\texttt{p[1]} is 4, \texttt{p[-1]} is 0 and \texttt{p[-2]} is 2.

\needlines{6}
As a further example, consider the C source 
shown in Figure \refersec{fig:cimplicitpointerexample2source}. Make
the following assumptions about how the code is compiled:
\begin{itemize}
\item The function \texttt{foo} is inlined
into function \texttt{main}
\item The body of the main function is optimized to just
three blocks of instructions which each increment the volatile
variable \texttt{v}, followed by a block of instructions to return 0 from
the function
\item Label \texttt{label0} is at the start of the main
function, \texttt{label1} follows the first \texttt{v++} block, 
\texttt{label2} follows the second \texttt{v++} block and 
\texttt{label3} is at the end of the main function
\item Variable \texttt{b} is optimized away completely, as it isn't used
\item The string literal \texttt{"opq"} is optimized away as well
\end{itemize}
Given these assumptions a possible DWARF description is shown in
Figure \refersec{fig:cimplicitpointerexample2dwarf}.

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}

static const char *b = "opq";
volatile int v;
static inline void foo (int *p)
\{
    (*p)++;
    v++;
    p++;
    (*p)++;
    v++;
\}

int main ()
\{
label0:
    int a[2] = { 1, 2 };
    v++;
label1:
    foo (a);
label2:
    return a[0] + a[1] - 5;
label3:
\}

\end{alltt}
\end{dwflisting}
\caption{C implicit pointer example \#2: source}
\label{fig:cimplicitpointerexample2source}
\end{figure}

\begin{figure}[ht]
\addtoindexx{implicit pointer example}
\begin{dwflisting}
\begin{alltt}
1\$:   \DWTAGvariable
          \DWATname("b")
          \DWATtype(reference to "const char *")
          \DWATlocation(expression=
              \DWOPimplicitpointer(reference to 2$, 0))
2\$:   \DWTAGdwarfprocedure
          \DWATlocation(expression=
              \DWOPimplicitvalue(4, \{'o', 'p', 'q', '\textbackslash{}0'\}))
3\$:   \DWTAGsubprogram
          \DWATname("foo")
          \DWATinline(\DWINLdeclaredinlined)
30\$:      \DWTAGformalparameter
              \DWATname("p")
              \DWATtype(reference to "int *")
4\$:   \DWTAGsubprogram
          \DWATname("main")
40\$:           \DWTAGvariable
              \DWATname("a")
              \DWATtype(reference to "int[2]")
              \DWATlocation(location list 98$)
41\$:      \DWTAGinlinedsubroutine
              \DWATabstractorigin(reference to 3$)
42\$:          \DWTAGformalparameter
                  \DWATabstractorigin(reference to 30$)
                  \DWATlocation(location list 99$)

! .debug_loclists section
98\$:  \DWLLEstartend[<label0 in main> .. <label1 in main>)
          \DWOPlitone \DWOPstackvalue \DWOPpiece(4)
          \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
      \DWLLEstartend[<label1 in main> .. <label2 in main>)
          \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
          \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
      \DWLLEstartend[<label2 in main> .. <label3 in main>)
          \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
          \DWOPlitthree \DWOPstackvalue \DWOPpiece(4)
      \DWLLEendoflist
99\$:  \DWLLEstartend[<label1 in main> .. <label2 in main>)
          \DWOPimplicitpointer(reference to 40\$, 0)
      \DWLLEstartend[<label2 in main> .. <label3 in main>)
          \DWOPimplicitpointer(reference to 40\$, 4)
      \DWLLEendoflist
\end{alltt}
\end{dwflisting}
\caption{C implicit pointer example \#2: DWARF description}
\label{fig:cimplicitpointerexample2dwarf}
\end{figure}

\clearpage
\section{String Type Examples}
\label{app:stringtypeexamples}
Consider the \addtoindex{Fortran 2003} string type example source in
Figure \referfol{fig:stringtypeexamplesource}. The DWARF representation in
Figure \refersec{fig:stringtypeexampledwarf} is appropriate.

\begin{figure}[ht]
\addtoindexx{ISO 10646 character set standard}
\begin{lstlisting}
        program character_kind
            use iso_fortran_env
            implicit none
            integer, parameter :: ascii = 
                selected_char_kind ("ascii")
            integer, parameter :: ucs4  = 
                selected_char_kind ('ISO_10646')
            character(kind=ascii, len=26) :: alphabet
            character(kind=ucs4,  len=30) :: hello_world
            character (len=*), parameter :: all_digits="0123456789"
              
            alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
            hello_world = ucs4_'Hello World and Ni Hao -- ' &
                          // char (int (z'4F60'), ucs4)     &
                          // char (int (z'597D'), ucs4)
              
            write (*,*) alphabet
            write (*,*) all_digits
              
            open (output_unit, encoding='UTF-8')
            write (*,*) trim (hello_world)
        end program character_kind
\end{lstlisting}
\caption{String type example: source}
\label{fig:stringtypeexamplesource}
\end{figure}

\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}

1\$: \DWTAGbasetype
        \DWATencoding (\DWATEASCII)

2\$: \DWTAGbasetype
        \DWATencoding (\DWATEUCS)
        \DWATbytesize (4)

3\$: \DWTAGstringtype
        \DWATbytesize (10)

4\$: \DWTAGconsttype
        \DWATtype (reference to 3\$)
      
5\$: \DWTAGstringtype
        \DWATtype (1\$)
        \DWATstringlength ( ... )
        \DWATstringlengthbytesize ( ... )
        \DWATdatalocation ( ... )
      
6\$: \DWTAGstringtype
        \DWATtype (2\$)
        \DWATstringlength ( ... )
        \DWATstringlengthbytesize ( ... )
        \DWATdatalocation ( ... )

7\$: \DWTAGvariable
        \DWATname (alphabet)
        \DWATtype (5\$)
        \DWATlocation ( ... )

8\$: \DWTAGconstant
        \DWATname (all\_digits)
        \DWATtype (4\$)
        \DWATconstvalue ( ... )

9\$: \DWTAGvariable
        \DWATname (hello\_world)
        \DWATtype (6\$)
        \DWATlocation ( ... )
        
\end{alltt}
\end{dwflisting}
\caption{String type example: DWARF representation}
\label{fig:stringtypeexampledwarf}
\end{figure}

\clearpage
\section{Call Site Examples}
\label{app:callsiteexamples}
The following examples use a hypothetical machine which: 
\begin{itemize}
\item
Passes the first argument in register 0, the second in register 1, and the third in register 2.
\item
Keeps the stack pointer is register 3.
\item
Has one call preserved register 4.
\item
Returns a function value in register 0.
\end{itemize}

\subsection{Call Site Example \#1 (C)}
Consider the \addtoindex{C} source in Figure \referfol{fig:callsiteexample1source}.

\begin{figure}[ht]
\begin{lstlisting}

extern void fn1 (long int, long int, long int);

long int
fn2 (long int a, long int b, long int c) 
{
    long int q = 2 * a;
    fn1 (5, 6, 7); 
    return 0;
}
 
long int
fn3 (long int x, long int (*fn4) (long int *))
{
    long int v, w, w2, z;
    w = (*fn4) (&w2);
    v = (*fn4) (&w2);
    z = fn2 (1, v + 1, w);
    {
        int v1 = v + 4;
        z += fn2 (w, v * 2, x);
    }
    return z;
}
\end{lstlisting}
\caption{Call Site Example \#1: Source}
\label{fig:callsiteexample1source}
\end{figure}

Possible generated code for this source is shown using a suggestive 
pseudo-\linebreak[0]assembly notation in Figure \refersec{fig:callsiteexample1code}.

\begin{figure}[ht]
\begin{lstlisting}
fn2:
L1:
    %reg2 = 7   ! Load the 3rd argument to fn1
    %reg1 = 6   ! Load the 2nd argument to fn1
    %reg0 = 5   ! Load the 1st argument to fn1
L2:
    call fn1
    %reg0 = 0   ! Load the return value from the function
    return
L3:
fn3:
    ! Decrease stack pointer to reserve local stack frame
    %reg3 = %reg3 - 32
    [%reg3] = %reg4       ! Save the call preserved register to
                          !   stack
    [%reg3 + 8] = %reg0   ! Preserve the x argument value
    [%reg3 + 16] = %reg1  ! Preserve the fn4 argument value
    %reg0 = %reg3 + 24    ! Load address of w2 as argument
    call %reg1            ! Call fn4 (indirect call)
L6:
    %reg2 = [%reg3 + 16]  ! Load the fn4 argument value
    [%reg3 + 16] = %reg0  ! Save the result of the first call (w)
    %reg0 = %reg3 + 24    ! Load address of w2 as argument
    call %reg2            ! Call fn4 (indirect call)
L7:
    %reg4 = %reg0         ! Save the result of the second call (v) 
                          !   into register.
    %reg2 = [%reg3 + 16]  ! Load 3rd argument to fn2 (w)
    %reg1 = %reg4 + 1     ! Compute 2nd argument to fn2 (v + 1)
    %reg0 = 1             ! Load 1st argument to fn2
    call fn2
L4:
    %reg2 = [%reg3 + 8]   ! Load the 3rd argument to fn2 (x)
    [%reg3 + 8] = %reg0   ! Save the result of the 3rd call (z)
    %reg0 = [%reg3 + 16]  ! Load the 1st argument to fn2 (w)
    %reg1 = %reg4 + %reg4 ! Compute the 2nd argument to fn2 (v * 2)
    call fn2
L5:
    %reg2 = [%reg3 + 8]   ! Load the value of z from the stack
    %reg0 = %reg0 + %reg2 ! Add result from the 4th call to it
L8:
    %reg4 = [%reg3]       ! Restore original value of call preserved 
                          !   register
    %reg3 = %reg3 + 32    ! Leave stack frame
    return
\end{lstlisting}
\caption{Call Site Example \#1: Code}
\label{fig:callsiteexample1code}
\end{figure}

\clearpage
The location list for variable \texttt{a} in function \texttt{fn2}
might look like the following 
(where the notation \doublequote{\textit{Range} [\texttt{m .. n)}} 
specifies the range of addresses from \texttt{m} through but not 
including \texttt{n} over which the following
location description applies):

%\begin{figure}[ht]
\begin{dwflisting}
\begin{alltt}

    ! Before the assignment to register 0, the argument a is live in register 0
    !
    \textit{Range} [L1 .. L2) 
        \DWOPregzero

    ! Afterwards, it is not. The value can perhaps be looked up in the caller
    !
    \textit{Range} [L2 .. L3) 
        \DWOPentryvalue 1 \DWOPregzero \DWOPstackvalue
    \textit{End-of-list}

\end{alltt}
\end{dwflisting}
%\end{figure}

\vspace*{0.7\baselineskip}
Similarly, the variable \texttt{q} in \texttt{fn2} then might have this location list:

\begin{dwflisting}
\begin{alltt}

    ! Before the assignment to register 0, the value of q can be computed as 
    ! two times the contents of register 0
    !
    \textit{Range} [L1 .. L2)
        \DWOPlittwo \DWOPbregzero 0 \DWOPmul \DWOPstackvalue

    ! Afterwards. it is not. It can be computed from the original value of 
    ! the first parameter, multiplied by two
    !
    \textit{Range} [L2 .. L3)
        \DWOPlittwo \DWOPentryvalue 1 \DWOPregzero \DWOPmul \DWOPstackvalue
    \textit{End-of-list}

\end{alltt}
\end{dwflisting}

\vspace*{0.7\baselineskip}
Variables \texttt{b} and \texttt{c} each have a location list similar to 
that for variable \texttt{a},
except for a different label between the two ranges and they
use \DWOPregone{} and \DWOPregtwo{}, respectively, instead of \DWOPregzero.


The call sites for all the calls in function \texttt{fn3} are children of the
\DWTAGsubprogram{} entry for \texttt{fn3} (or of its \DWTAGlexicalblock{} entry
if there is any for the whole function). 
This is shown in Figure \refersec{fig:callsiteexample1dwarf}.

\begin{figure}[ht]
\figurepart{1}{2}
\begin{dwflisting}
\begin{alltt}
    \DWTAGcallsite
        \DWATcallreturnpc(L6) ! First indirect call to (*fn4) in fn3.
        ! The address of the call is preserved across the call in memory at
        ! stack pointer + 16 bytes.
        \DWATcalltarget(\DWOPbregthree{} 16 \DWOPderef)
        \DWTAGcallsiteparameter
            \DWATlocation(\DWOPregzero)
            ! Value of the first parameter is equal to stack pointer + 24 bytes.
            \DWATcallvalue(\DWOPbregthree{} 24)